hgzero/claudedocs/설계서_업데이트_요약.md

# 설계서 업데이트 요약

**작업일**: 2025-01-29
**작업자**: Backend Developer (동욱)
**작업 범위**: 프로토타입, 유저스토리, 개발 소스 기반 설계서 전면 업데이트

---

## 1. 작업 개요

### 목적
- 실제 구현된 기능과 설계서 간 불일치 해소
- RAG Service 독립 서비스 분리 반영
- 구현되지 않은 기능의 설계서 삭제
- MVP 범위 축소에 따른 설계 정리

### 주요 변경 사항
1. **RAG Service 문서화**: 독립 서비스로 분리된 RAG 시스템 전체 문서화
2. **불필요한 설계서 삭제**: 구현되지 않은 기능의 시퀀스 다이어그램 10개 삭제
3. **API 설계서 정리**: 삭제된 기능 제거, RAG 연동 반영
4. **마이크로서비스 구성 업데이트**: 5개 → 6개 서비스

---

## 2. 삭제된 파일 (10개)

### AI Service 시퀀스 (2개)
1. `design/backend/sequence/inner/ai-결정사항제안.puml`
   - **삭제 사유**: Discussion/Decision Suggestion 기능 미구현
   - **영향**: API 설계서에서 `/suggestions/discussion`, `/suggestions/decision` 엔드포인트 제거

2. `design/backend/sequence/inner/ai-논의사항제안.puml`
   - **삭제 사유**: Discussion Suggestion 기능 미구현
   - **영향**: 동일

### Meeting Service 시퀀스 (5개)
3. `design/backend/sequence/inner/meeting-실시간수정동기화.puml`
   - **삭제 사유**: 실시간 협업 기능 제거 (Last Write Wins로 단순화)
   - **영향**: 충돌 해결 로직 불필요

4. `design/backend/sequence/inner/meeting-충돌해결.puml`
   - **삭제 사유**: Last Write Wins 정책으로 충돌 처리 불필요
   - **영향**: 실시간 동기화 설계 제거

5. `design/backend/sequence/inner/meeting-Todo완료처리.puml`
   - **삭제 사유**: Todo 관리 기능 MVP에서 제외
   - **영향**: Todo 상태 업데이트 API 제거

6. `design/backend/sequence/inner/meeting-Todo할당.puml`
   - **삭제 사유**: Todo 할당 기능 MVP에서 제외
   - **영향**: Todo 할당 API 제거

7. `design/backend/sequence/inner/notification-리마인더발송.puml`
   - **삭제 사유**: 리마인더 기능 MVP에서 제외
   - **영향**: 리마인더 API 제거

### Notification Service 시퀀스 (3개 → 1개 통합)
8. `design/backend/sequence/inner/notification-Todo알림발송.puml`
   - **삭제 사유**: Todo 기능 제거로 알림 불필요
   - **영향**: Todo 알림 API 제거

9. `design/backend/sequence/inner/notification-초대알림발송.puml`
   - **삭제 사유**: 일반 알림 시퀀스로 통합
   - **영향**: 중복 설계 제거

10. `design/backend/sequence/inner/notification-{duplicate}.puml` (추가 중복 파일)
    - **삭제 사유**: 동일 기능의 중복 시퀀스
    - **영향**: 설계 일관성 향상

---

## 3. 추가된 파일 (2개)

### RAG Service 문서화
1. **`design/backend/api/spec/rag-service-api.yaml`** (NEW)
   - **내용**: RAG Service OpenAPI 3.0.3 명세서
   - **API 개수**: 9개
     - Terms APIs: 3개 (검색, 조회, 설명)
     - Documents APIs: 2개 (검색, 통계)
     - Minutes APIs: 4개 (검색, 조회, 연관, 통계)
   - **주요 기술**:
     - Python 3.11+, FastAPI
     - PostgreSQL + pgvector
     - Azure AI Search
     - Claude 3.5 Sonnet
     - Redis 캐싱

2. **`claudedocs/설계서_업데이트_요약.md`** (이 문서)
   - **내용**: 전체 설계서 업데이트 요약
   - **목적**: 변경 사항 추적 및 문서화

---

## 4. 수정된 파일 (4개)

### 4.1 유저스토리 (design/userstory.md)
- **버전**: v2.5.0 → v2.5.1
- **변경 내용**:
  - 마이크로서비스 개수: 5개 → 6개
  - RAG Service 섹션 추가 (2.5)
  - 유저스토리 3개 추가:
    - UFR-RAG-010: 전문용어 감지
    - UFR-RAG-020: 맥락 기반 용어 설명
    - UFR-RAG-030: 관련 회의록/자료 검색

### 4.2 API 설계서 (design/backend/api/API설계서.md)
- **버전**: v2.0 → v2.1
- **주요 변경**:

#### 마이크로서비스 구성 업데이트
```markdown
5. **AI Service** - AI 기반 회의록 자동화, Todo 추출, RAG 서비스 연동
6. **RAG Service** - 용어집/관련자료/회의록 검색 (Python/FastAPI 독립 서비스)
```

#### AI Service 섹션 업데이트
- **삭제된 API**:
  - `POST /suggestions/discussion` - 논의사항 제안
  - `POST /suggestions/decision` - 결정사항 제안
  - `PUT /minutes/{minutesId}/improve` - 회의록 개선

- **추가된 API 설명**:
  - `POST /sections/{sectionId}/summary` - 안건별 AI 요약 생성
  - `POST /sections/{sectionId}/regenerate` - 한줄 요약 재생성
  - `GET /meetings/{meetingId}/suggestions/stream` - 실시간 주요 내용 제안 (SSE)

- **RAG 연동 명시**:
  ```markdown
  **Related Transcripts APIs (1개) - RAG 연동**
  | GET | /transcripts/{meetingId}/related | 관련 회의록 검색 (RAG 서비스 연동) |

  **Term APIs (2개) - RAG 연동**
  | POST | /terms/detect | 전문용어 감지 (RAG 서비스 연동) |
  | GET | /terms/{termId}/explain | 맥락 기반 용어 설명 (RAG 서비스 연동) |
  ```

- **주요 특징 업데이트**:
  ```markdown
  - LLM 기반 회의록 자동 작성 (Claude 3.5 Sonnet)
  - RAG Service 연동
    - 전문용어 자동 감지 및 맥락 기반 설명
    - 관련 회의록 검색 (벡터 유사도 70% 이상)
    - 조직 내 문서 및 이력 기반 용어 설명 생성
  - 안건별 요약 생성 (한줄 요약 + 상세 요약)
  - 실시간 주요 내용 제안 (SSE 스트리밍)
  ```

- **차별화 포인트 업데이트**:
  ```markdown
  1. **맥락 기반 용어 설명**: 단순 사전 정의가 아닌, RAG를 통해 조직 내 실제 사용 맥락과 과거 논의 이력 제공
  2. **하이브리드 검색 기반 연관성**: 키워드 매칭과 벡터 유사도를 결합하여 관련 회의록 정확도 향상
  3. **실시간 AI 제안**: SSE 기반 스트리밍으로 회의 중 주요 내용 실시간 제안
  ```

#### RAG Service 섹션 추가 (완전 신규)
- **개요**:
  - 파일: `rag-service-api.yaml`
  - 베이스 URL: `/api/rag`
  - 기술 스택: Python 3.11+, FastAPI, PostgreSQL+pgvector, Azure AI Search, Redis

- **API 목록**: 9개
  - Terms APIs: 3개
  - Documents APIs: 2개
  - Minutes APIs: 4개

- **주요 특징**:
  - 하이브리드 검색 (키워드 + 벡터)
  - Azure OpenAI text-embedding-3-large (3,072 차원)
  - Claude 3.5 Sonnet (맥락 기반 설명)
  - Redis 캐싱 (TTL: 30분~1시간)
  - EventHub 연동 (회의록 확정 이벤트 수신)

- **성능 요구사항**:
  - 용어 검색: < 500ms (캐시 HIT: < 50ms)
  - 용어 설명 생성: < 3초
  - 회의록 검색: < 1초 (캐시 HIT: < 100ms)

#### 통계 업데이트
```markdown
| 서비스 | API 개수 | 주요 기능 |
|--------|---------|----------|
| User Service | 4 | 사용자 인증 |
| Meeting Service | 17 | 회의, 회의록, Todo 관리 |
| STT Service | 12 | 음성 녹음, 변환, 화자 식별 |
| AI Service | 8 | AI 회의록, Todo 추출, RAG 연동 |
| RAG Service | 9 | 용어집/문서/회의록 검색 |
| Notification Service | 6 | 알림 발송, 설정 관리 |
| **합계** | **56** | |
```

- **유저스토리 커버리지**: 25개 → 28개

#### 문서 이력 추가
```markdown
| 2.1 | 2025-01-29 | 동욱 (Backend Developer) | RAG Service 추가, 불필요한 API 정리 (6개 마이크로서비스) |
```

### 4.3 AI Service 내부 시퀀스 - 전문용어감지 (design/backend/sequence/inner/ai-전문용어감지.puml)
- **변경 내용**: RAG Service API 호출 방식 명시
  ```plantuml
  note over Service
    **구현 방식**: AI Service → RAG Service API 호출
    POST /api/rag/terms/search
    - 하이브리드 검색 (키워드 + 벡터)
    - PostgreSQL + pgvector
    - Redis 캐싱
  end note
  ```

### 4.4 AI Service 내부 시퀀스 - 맥락기반용어설명 (design/backend/sequence/inner/ai-맥락기반용어설명.puml)
- **변경 내용**: RAG Service API 호출 방식 명시
  ```plantuml
  note over Service
    **구현 방식**: AI Service → RAG Service API 호출
    GET /api/rag/terms/{termId}
    - PostgreSQL + pgvector에서 조회
    - Redis 캐싱 적용
  end note
  ```

---

## 5. 영향 분석

### 5.1 설계서 감소율
- **삭제 전**: 37개 시퀀스 파일
- **삭제 후**: 27개 시퀀스 파일
- **감소율**: 27.0% (10개 파일 삭제)

### 5.2 API 개수 변화
- **기존**: 47개 API (5개 서비스)
- **현재**: 56개 API (6개 서비스)
- **증가**: +9개 (RAG Service)

### 5.3 서비스 아키텍처 변화
```
기존 (5개 서비스):
User → Meeting ← STT
         ↓
        AI ← Notification

현재 (6개 서비스):
User → Meeting ← STT
         ↓
        AI ← Notification
         ↓
       RAG (독립 서비스)
```

---

## 6. 다음 단계 작업

### 6.1 완료된 작업
- ✅ 불필요한 시퀀스 파일 삭제 (10개)
- ✅ RAG Service API 명세 작성
- ✅ API 설계서 업데이트 (RAG 추가, 불필요 API 제거)
- ✅ AI Service 특징 및 차별화 포인트 업데이트
- ✅ 통계 및 문서 이력 업데이트

### 6.2 남은 작업 (우선순위 순)
1. **외부 시퀀스 검증** (6개 파일)
   - 프로토타입 화면과 일치 여부 확인
   - 유저스토리와 매핑 검증

2. **RAG 연동 시퀀스 완성** (3개 파일)
   - `ai-관련회의록연결.puml`: RAG Service 호출 흐름 추가
   - EventHub를 통한 비동기 처리 흐름 추가

3. **클래스 설계 작성** (미작성 상태)
   - AI Service: High 우선순위
   - Meeting Service: High 우선순위
   - RAG Service: Medium 우선순위

---

## 7. 설계 원칙 준수

### 7.1 마이크로서비스 독립성
- ✅ RAG Service를 완전 독립 서비스로 분리
- ✅ AI Service는 RAG API를 REST로 호출 (직접 DB 접근 없음)
- ✅ 각 서비스별 독립적인 OpenAPI 명세

### 7.2 비동기 처리
- ✅ EventHub를 통한 회의록 확정 이벤트 전달 (Meeting → RAG)
- ✅ RAG Consumer가 벡터 DB에 저장
- ✅ 실시간 응답이 필요한 API는 동기 호출 (용어 검색, 설명)

### 7.3 캐싱 전략
- ✅ Redis를 통한 검색 결과 캐싱 (TTL: 30분~1시간)
- ✅ 용어 검색 성능 목표: < 500ms (캐시 HIT: < 50ms)

---

## 8. 검증 항목

### 8.1 문서 일관성 체크리스트
- ✅ 유저스토리 개수 일치 (28개)
- ✅ API 개수 일치 (56개)
- ✅ 마이크로서비스 개수 일치 (6개)
- ✅ OpenAPI 파일 경로 일치 (`design/backend/api/spec/*.yaml`)
- ✅ 문서 버전 및 날짜 업데이트

### 8.2 설계서 검증
- ✅ PlantUML 문법 검사 필요
- ✅ OpenAPI YAML 검증 필요
- ⏳ 외부 시퀀스 프로토타입 일치 확인 (향후)

---

## 9. 참고 자료

### 삭제된 설계서 목록
전체 목록은 `claudedocs/설계서_삭제_목록.md` 참조

### RAG Service 소스 코드
- `rag/src/api/main.py`: FastAPI 엔드포인트 9개
- `rag/src/services/`: 비즈니스 로직
- `rag/src/models/`: 데이터 모델

### 관련 유저스토리
- UFR-RAG-010: 전문용어 감지
- UFR-RAG-020: 맥락 기반 용어 설명
- UFR-RAG-030: 관련 회의록/자료 검색

---

**작성 완료**: 2025-01-29
**작성자**: Backend Developer (동욱)