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
• 주요 변경:

마이크로서비스 구성 업데이트

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 연동 명시:

  **Related Transcripts APIs (1개) - RAG 연동**
  | GET | /transcripts/{meetingId}/related | 관련 회의록 검색 (RAG 서비스 연동) |
  
  **Term APIs (2개) - RAG 연동**
  | POST | /terms/detect | 전문용어 감지 (RAG 서비스 연동) |
  | GET | /terms/{termId}/explain | 맥락 기반 용어 설명 (RAG 서비스 연동) |
  

• 주요 특징 업데이트:

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

• 차별화 포인트 업데이트:

  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)

통계 업데이트

| 서비스 | 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개

문서 이력 추가

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

4.3 AI Service 내부 시퀀스 - 전문용어감지 (design/backend/sequence/inner/ai-전문용어감지.puml)

• 변경 내용: RAG Service API 호출 방식 명시

  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 호출 방식 명시

  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 (동욱)