# 외부 시퀀스 설계서 (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), 병렬 처리 전략 적용 |