mirror of https://github.com/hwanny1128/HGZero.git synced 2025-12-06 09:06:24 +00:00

djeon e1d411e989 외부 시퀀스 설계 가이드 및 설계서 추가

- 외부 시퀀스 설계 가이드 다운로드 (claude/sequence-outer-design.md)
- 외부 시퀀스 설계 디렉토리 생성 (design/backend/sequence/)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-10-22 13:23:50 +09:00

13 KiB

Raw Blame History

외부 시퀀스 설계서 (Outer Sequence Design)

개요

본 문서는 회의록 작성 및 공유 개선 서비스의 외부 시퀀스 다이어그램을 설명합니다. 외부 시퀀스는 마이크로서비스 간의 통신 흐름을 나타내며, 주요 사용자 플로우별로 서비스 간 상호작용을 정의합니다.

문서 정보

작성일: 2025-10-22
작성자: 홍길동 (Architect)
버전: 2.0
설계 원칙: 공통설계원칙 및 외부시퀀스설계가이드 준용

병렬 처리 전략 적용

Group A (순차): 회의 생애주기 플로우 (플로우 10-13)
Group B (독립): Todo 관리 플로우 (플로우 14)
Group C (독립): 회의록 조회/수정 플로우 (플로우 15)
3개 서브 에이전트가 병렬로 작업하여 전체 작업 시간 약 60% 단축

외부 시퀀스 목록

1. 사용자 인증 및 대시보드 조회

파일: 01-사용자인증및대시보드조회.puml
관련 유저스토리: AFR-USER-010, AFR-USER-020
참여 서비스:
- Web App
- API Gateway
- User Service
- Meeting Service
- Todo Service
- Redis (Cache)
- PostgreSQL (User DB, Meeting DB, Todo DB)

주요 흐름:

사용자 인증:
- 사용자가 사번과 비밀번호로 로그인
- User Service가 LDAP 연동하여 인증
- JWT 토큰 생성 및 사용자 프로필 Redis 캐싱 (TTL: 30분)
- 인증 성공 시 토큰 반환
대시보드 데이터 조회:
- 예정된 회의 조회 (Meeting Service)
  - Redis 캐시 확인 → Cache Miss → DB 조회 → 캐싱 (TTL: 10분)
- 진행 중 Todo 조회 (Todo Service)
  - Redis 캐시 확인 → Cache Hit → 캐시에서 직접 반환
- 최근 회의록 조회 (Meeting Service)
  - Redis 캐시 확인 → Cache Miss → DB 조회 → 캐싱 (TTL: 10분)
- Todo 통계 조회 (Todo Service)
  - Redis 캐시 확인 → Cache Hit → 캐시에서 직접 반환

적용 패턴:

Cache-Aside Pattern: 캐시 우선 조회로 DB 부하 감소
JWT 인증: API Gateway에서 일괄 토큰 검증
LDAP 연동: 기업 사용자 인증

성능 목표:

API 응답 시간 (P95): < 500ms
Cache Hit Rate: > 70%

2. 회의 예약 및 초대

파일: 02-회의예약및초대.puml
관련 유저스토리: UFR-MEET-010
참여 서비스:
- Web App
- API Gateway
- Meeting Service
- User Service
- Notification Service
- RabbitMQ (Message Broker)
- Redis (Cache)
- PostgreSQL (Meeting DB, User DB, Notification DB)

주요 흐름:

회의 예약:
- 사용자가 회의 정보 입력 (제목, 날짜/시간, 장소, 참석자)
- 입력 유효성 검증 (필수 필드, 날짜 형식, 이메일 형식)
- Meeting Service가 회의 생성 및 DB 저장
- 회의 정보 Redis 캐싱 (TTL: 10분)
이벤트 발행:
- Meeting Service가 MeetingCreated 이벤트를 RabbitMQ에 발행
  - Exchange: meeting.events
  - Routing Key: meeting.created
- Notification Service가 이벤트 구독
초대 알림 발송:
- Notification Service가 MeetingCreated 이벤트 수신
- User Service에서 참석자 정보 조회 (캐시 우선)
- 알림 메시지 생성 및 DB 저장
- 각 참석자에게 이메일 초대 발송
- 알림 상태 업데이트 (PENDING → SENT)
- 리마인더 일정 생성 (회의 시작 30분 전)
결과 확인:
- 사용자가 대시보드에서 새로 예약한 회의 확인
- 캐시 무효화 후 DB 재조회 및 재캐싱

적용 패턴:

Publisher-Subscriber Pattern: 이벤트 기반 느슨한 결합
Queue-Based Load Leveling: 대량 알림 발송 시 부하 분산
Cache-Aside Pattern: 사용자 정보 캐싱으로 성능 향상
Asynchronous Processing: 알림 발송은 비동기로 처리

이벤트 스키마:

{
  "eventType": "MeetingCreated",
  "payload": {
    "meetingId": "uuid",
    "title": "프로젝트 킥오프 회의",
    "dateTime": "2025-02-01T14:00:00",
    "location": "회의실 A",
    "creatorId": "userId",
    "participants": ["user1@company.com", "user2@company.com"]
  }
}

성능 목표:

회의 생성 응답 시간: < 300ms
알림 발송 지연 시간: < 5초

설계 원칙

1. 통신 패턴

동기 통신 (REST API)

적용 대상: 즉시 응답이 필요한 단순 조회
특징:
- API Gateway를 통한 일관된 인증/인가
- 캐시 우선 전략으로 직접 의존성 최소화

비동기 통신 (Message Queue)

적용 대상: 이벤트 기반 통신, 느슨한 결합
특징:
- RabbitMQ Topic Exchange를 통한 Pub/Sub 패턴
- 이벤트 발행자와 구독자 간 느슨한 결합
- 대량 작업 시 Queue-Based Load Leveling

2. 캐싱 전략 (Cache-Aside)

데이터 유형	TTL	캐시 키 패턴	무효화 시점
사용자 프로필	30분	`user:profile:{userId}`	프로필 수정 시
사용자 권한	1시간	`user:auth:{userId}`	권한 변경 시
회의 정보	10분	`meeting:info:{meetingId}`	회의 수정 시
회의 참여자	10분	`meeting:participants:{meetingId}`	참여자 변경 시
Todo 목록	5분	`todo:user:{userId}`	Todo 상태 변경 시
Todo 통계	5분	`todo:stats:{userId}`	Todo 완료 시

캐시 처리 플로우:

조회 요청 → Redis 캐시 확인
Cache Hit → 캐시 데이터 반환
Cache Miss → DB 조회 → Redis 저장 (TTL 설정) → 데이터 반환
데이터 수정 시 → DB 업데이트 → Redis 캐시 무효화

3. 이벤트 기반 아키텍처

RabbitMQ Exchange/Queue 구성

Topic Exchange: meeting.events, transcript.events, todo.events
Queue 네이밍: {service}.{event-category}.queue
Routing Key 패턴: {event}.{action} (예: meeting.created, todo.completed)

주요 이벤트

이벤트	발행자	구독자	목적
MeetingCreated	Meeting Service	Notification Service AI Service	참석자 알림 발송 회의 분석 준비
MeetingEnded	Meeting Service	STT Service AI Service Todo Service Notification Service	회의록 생성 AI 분석 시작 Todo 추출 종료 알림
TodoCreated	Todo Service	Notification Service	담당자 알림 발송

다이어그램 렌더링 방법

PlantUML 렌더링

1. Visual Studio Code 플러그인 사용

PlantUML 확장 설치: jebbs.plantuml
.puml 파일 열기
Alt + D (미리보기) 또는 우클릭 → Preview Current Diagram

2. 온라인 렌더링

PlantUML Online Editor
파일 내용 복사 → 붙여넣기 → 렌더링

3. 로컬 PlantUML 서버

# Docker로 PlantUML 서버 실행
docker run -d --name plantuml -p 38080:8080 plantuml/plantuml-server:latest

# 브라우저에서 접근
http://localhost:38080

다음 단계

1. 내부 시퀀스 설계

각 서비스 내부의 상세 처리 흐름을 설계합니다:

User Service 내부 시퀀스 (인증 처리, 프로필 관리)
Meeting Service 내부 시퀀스 (회의 생성, 회의록 관리)
Notification Service 내부 시퀀스 (알림 발송, 리마인더 관리)

2. API 명세 작성

각 서비스별 REST API 명세를 OpenAPI 3.0 형식으로 작성합니다.

3. 클래스 설계

엔티티, DTO, 서비스 클래스 설계를 진행합니다.

4. 데이터 설계

각 서비스별 데이터베이스 스키마 설계를 진행합니다.

참고 자료

신규 플로우 (v2.0)

10. 회의 예약 및 초대

파일: 회의예약및초대.puml
관련 유저스토리: UFR-MEET-010
참여 서비스: Frontend, API Gateway, Meeting Service, User Service, Redis, RabbitMQ, Notification Service, Meeting DB
주요 특징:
- Cache-Aside 패턴으로 참석자 정보 조회 (Redis 캐시 우선)
- 회의 정보 저장 및 캐싱 (TTL: 10분)
- MeetingCreated 이벤트 비동기 발행
- Notification Service가 참석자 전원에게 초대 이메일 발송

11. 회의 시작 및 회의록 작성

파일: 회의시작및회의록작성.puml
관련 유저스토리: UFR-MEET-030, UFR-STT-010/020, UFR-AI-010, UFR-RAG-010/020, UFR-COLLAB-010
참여 서비스: Frontend, API Gateway, Meeting Service, STT Service, AI Service, RAG Service, Collaboration Service, Redis, RabbitMQ, Azure Speech, LLM Server, 각 서비스 DB
주요 특징:
- 실시간 음성 인식 (Azure Speech, 5초 간격)
- AI 기반 회의록 자동 작성 (LLM)
- WebSocket 실시간 동기화 (델타만 전송)
- RAG 기반 전문용어 감지 및 맥락 설명 제공
- 가장 복잡한 플로우 (동기+비동기+실시간 혼합)

12. 회의 종료 및 Todo 추출

파일: 회의종료및Todo추출.puml
관련 유저스토리: UFR-MEET-040/050, UFR-AI-020, UFR-TODO-010
참여 서비스: Frontend, API Gateway, Meeting Service, AI Service, Todo Service, Notification Service, Redis, RabbitMQ, LLM Server, 각 서비스 DB
주요 특징:
- 회의 통계 자동 생성 (duration, 참석자 수, 발언 수)
- AI Todo 자동 추출 (액션 아이템 식별, 담당자 자동 지정)
- 이벤트 체인: MeetingEnded → TodoExtracted → TodoCreated
- Todo 목록 캐싱 (TTL: 5분)
- 담당자에게 자동 알림 발송

13. 회의록 확정 및 공유

파일: 회의록확정및공유.puml
관련 유저스토리: UFR-MEET-060
참여 서비스: Frontend, API Gateway, Meeting Service, Notification Service, Redis, RabbitMQ, Meeting DB
주요 특징:
- 필수 항목 자동 검사 (제목, 참석자, 논의 내용, 결정 사항)
- 고유 공유 링크 생성 (UUID 기반)
- 공유 보안 설정 (비밀번호, 유효기간)
- TranscriptShared 이벤트 발행
- 다음 회의 일정 자동 캘린더 등록 (선택)

14. Todo 완료 및 회의록 반영

파일: Todo완료및회의록반영.puml
관련 유저스토리: UFR-TODO-030
참여 서비스: Frontend, API Gateway, Todo Service, Meeting Service, Notification Service, Redis, RabbitMQ, 각 서비스 DB
주요 특징 (차별화 포인트):
- Todo 완료가 회의록에 실시간 반영되는 양방향 연동
- 완료 시간 및 완료자 정보 자동 기록
- TodoCompleted 이벤트 → Meeting Service가 회의록 자동 업데이트
- 모든 Todo 완료 시 전체 완료 알림 자동 발송
- Cache-Aside 패턴으로 회의록 조회 최적화

15. 회의록 조회 및 수정

파일: 회의록조회및수정.puml
관련 유저스토리: UFR-MEET-046/047/055, UFR-COLLAB-010
참여 서비스: Frontend, API Gateway, Meeting Service, Collaboration Service, Redis, Meeting DB
주요 특징:
- Cache-Aside 패턴으로 목록/상세 조회 (TTL: 10분)
- 권한 검증 (본인 작성 회의록만 수정 가능)
- 수정 이력 자동 기록 (수정자, 수정 시간, 변경 내용)
- WebSocket 실시간 동기화 (델타만 전송)
- 버전 관리 (새 버전 생성, 이전 버전 보관)
- 확정완료 → 작성중 자동 상태 변경

설계 원칙 적용

PlantUML 문법 검사

✅ 모든 파일 검증 통과 (Docker 기반 PlantUML 검사 완료)

!theme mono 적용
동기: 실선 (→), 비동기: 점선 (->>) 명확 구분
..> 사용 금지 (sequence diagram 원칙 준수)

논리 아키텍처 일치성

✅ 참여자: 논리 아키텍처의 서비스, DB, 메시지 큐 구조 일치
✅ 통신 방식: 동기(REST), 비동기(RabbitMQ), 실시간(WebSocket) 일치
✅ 캐시 전략: Cache-Aside 패턴, TTL 설정 일치

유저스토리 커버리지

✅ 신규 6개 플로우가 11개 유저스토리 완전 커버
✅ 기존 9개 플로우와 통합하여 전체 시스템 커버

문서 이력

버전	작성일	작성자	변경 내용
1.0	2025-01-22	길동 (Architect)	초안 작성 (Flow 1-9)
2.0	2025-10-22	길동 (Architect)	신규 6개 플로우 추가 (Flow 10-15), 병렬 처리 전략 적용

13 KiB Raw Blame History