mirror of
https://github.com/hwanny1128/HGZero.git
synced 2026-01-21 20:46:23 +00:00
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>
329 lines
13 KiB
Markdown
329 lines
13 KiB
Markdown
# 외부 시퀀스 설계서 (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](./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)
|
|
|
|
**주요 흐름**:
|
|
1. **사용자 인증**:
|
|
- 사용자가 사번과 비밀번호로 로그인
|
|
- User Service가 LDAP 연동하여 인증
|
|
- JWT 토큰 생성 및 사용자 프로필 Redis 캐싱 (TTL: 30분)
|
|
- 인증 성공 시 토큰 반환
|
|
|
|
2. **대시보드 데이터 조회**:
|
|
- 예정된 회의 조회 (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](./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)
|
|
|
|
**주요 흐름**:
|
|
1. **회의 예약**:
|
|
- 사용자가 회의 정보 입력 (제목, 날짜/시간, 장소, 참석자)
|
|
- 입력 유효성 검증 (필수 필드, 날짜 형식, 이메일 형식)
|
|
- Meeting Service가 회의 생성 및 DB 저장
|
|
- 회의 정보 Redis 캐싱 (TTL: 10분)
|
|
|
|
2. **이벤트 발행**:
|
|
- Meeting Service가 `MeetingCreated` 이벤트를 RabbitMQ에 발행
|
|
- Exchange: `meeting.events`
|
|
- Routing Key: `meeting.created`
|
|
- Notification Service가 이벤트 구독
|
|
|
|
3. **초대 알림 발송**:
|
|
- Notification Service가 `MeetingCreated` 이벤트 수신
|
|
- User Service에서 참석자 정보 조회 (캐시 우선)
|
|
- 알림 메시지 생성 및 DB 저장
|
|
- 각 참석자에게 이메일 초대 발송
|
|
- 알림 상태 업데이트 (PENDING → SENT)
|
|
- 리마인더 일정 생성 (회의 시작 30분 전)
|
|
|
|
4. **결과 확인**:
|
|
- 사용자가 대시보드에서 새로 예약한 회의 확인
|
|
- 캐시 무효화 후 DB 재조회 및 재캐싱
|
|
|
|
**적용 패턴**:
|
|
- **Publisher-Subscriber Pattern**: 이벤트 기반 느슨한 결합
|
|
- **Queue-Based Load Leveling**: 대량 알림 발송 시 부하 분산
|
|
- **Cache-Aside Pattern**: 사용자 정보 캐싱으로 성능 향상
|
|
- **Asynchronous Processing**: 알림 발송은 비동기로 처리
|
|
|
|
**이벤트 스키마**:
|
|
```json
|
|
{
|
|
"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 완료 시 |
|
|
|
|
**캐시 처리 플로우**:
|
|
1. 조회 요청 → Redis 캐시 확인
|
|
2. Cache Hit → 캐시 데이터 반환
|
|
3. Cache Miss → DB 조회 → Redis 저장 (TTL 설정) → 데이터 반환
|
|
4. 데이터 수정 시 → 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<br/>AI Service | 참석자 알림 발송<br/>회의 분석 준비 |
|
|
| **MeetingEnded** | Meeting Service | STT Service<br/>AI Service<br/>Todo Service<br/>Notification Service | 회의록 생성<br/>AI 분석 시작<br/>Todo 추출<br/>종료 알림 |
|
|
| **TodoCreated** | Todo Service | Notification Service | 담당자 알림 발송 |
|
|
|
|
---
|
|
|
|
## 다이어그램 렌더링 방법
|
|
|
|
### PlantUML 렌더링
|
|
|
|
#### 1. Visual Studio Code 플러그인 사용
|
|
1. PlantUML 확장 설치: `jebbs.plantuml`
|
|
2. `.puml` 파일 열기
|
|
3. `Alt + D` (미리보기) 또는 우클릭 → `Preview Current Diagram`
|
|
|
|
#### 2. 온라인 렌더링
|
|
- [PlantUML Online Editor](https://www.plantuml.com/plantuml/uml/)
|
|
- 파일 내용 복사 → 붙여넣기 → 렌더링
|
|
|
|
#### 3. 로컬 PlantUML 서버
|
|
```bash
|
|
# 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. 데이터 설계
|
|
각 서비스별 데이터베이스 스키마 설계를 진행합니다.
|
|
|
|
---
|
|
|
|
## 참고 자료
|
|
|
|
- [논리 아키텍처 설계서](../../logical/logical-architecture.md)
|
|
- [유저스토리](../../../userstory.md)
|
|
- [아키텍처 패턴 적용 방안](../../../pattern/architecture-pattern.md)
|
|
- [클라우드 디자인 패턴 요약](../../../../claude/cloud-design-patterns.md)
|
|
|
|
---
|
|
|
|
---
|
|
|
|
## 신규 플로우 (v2.0)
|
|
|
|
### 10. 회의 예약 및 초대
|
|
- **파일**: [회의예약및초대.puml](./회의예약및초대.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](./회의시작및회의록작성.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](./회의종료및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](./회의록확정및공유.puml)
|
|
- **관련 유저스토리**: UFR-MEET-060
|
|
- **참여 서비스**: Frontend, API Gateway, Meeting Service, Notification Service, Redis, RabbitMQ, Meeting DB
|
|
- **주요 특징**:
|
|
- 필수 항목 자동 검사 (제목, 참석자, 논의 내용, 결정 사항)
|
|
- 고유 공유 링크 생성 (UUID 기반)
|
|
- 공유 보안 설정 (비밀번호, 유효기간)
|
|
- TranscriptShared 이벤트 발행
|
|
- 다음 회의 일정 자동 캘린더 등록 (선택)
|
|
|
|
### 14. Todo 완료 및 회의록 반영
|
|
- **파일**: [Todo완료및회의록반영.puml](./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](./회의록조회및수정.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), 병렬 처리 전략 적용 |
|