mirror of
https://github.com/hwanny1128/HGZero.git
synced 2025-12-06 05:36:23 +00:00
문서 정리: 불필요한 claudedocs 파일 삭제 및 설계서 업데이트
- API 설계 가이드 업데이트 - 중복/과거 분석 문서 정리 (API누락요약표, API리뷰, 설계서업데이트요약) - 유저스토리 업데이트 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
yabo0812
parent
d2f396cffb
commit
fb418cface
@ -1,115 +1,111 @@
|
||||
# STT Service API 설계 완료
|
||||
# API설계가이드
|
||||
|
||||
## 작업 결과
|
||||
[요청사항]
|
||||
- <작성원칙>을 준용하여 설계
|
||||
- <작성순서>에 따라 설계
|
||||
- [결과파일] 안내에 따라 파일 작성
|
||||
- 최종 완료 후 API 확인 방법 안내
|
||||
- https://editor.swagger.io/ 접근
|
||||
- 생성된 swagger yaml파일을 붙여서 확인 및 테스트
|
||||
|
||||
### 생성된 파일
|
||||
- **파일 경로**: `C:\Users\KTDS\home\workspace\HGZero\design\backend\api\stt-service-api.yaml`
|
||||
- **형식**: OpenAPI 3.0.3
|
||||
- **검증 상태**: ✅ 검증 완료 (swagger-cli)
|
||||
[가이드]
|
||||
<작성 원칙>
|
||||
- 각 서비스 API는 독립적으로 완전한 명세를 포함
|
||||
- 공통 스키마는 각 서비스에서 필요에 따라 직접 정의
|
||||
- 서비스 간 의존성을 최소화하여 독립 배포 가능
|
||||
- 중복되는 스키마가 많아질 경우에만 공통 파일 도입 검토
|
||||
<작성순서>
|
||||
- 준비:
|
||||
- 유저스토리, 외부시퀀스설계서, 내부시퀀스설계서 분석 및 이해
|
||||
- 실행:
|
||||
- <병렬처리> 안내에 따라 동시 수행
|
||||
- <API선정원칙>에 따라 API 선정
|
||||
- <파일작성안내>에 따라 작성
|
||||
- <검증방법>에 따라 작성된 YAML의 문법 및 구조 검증 수행
|
||||
- 검토:
|
||||
- <작성원칙> 준수 검토
|
||||
- 스쿼드 팀원 리뷰: 누락 및 개선 사항 검토
|
||||
- 수정 사항 선택 및 반영
|
||||
|
||||
### API 개요
|
||||
<API선정원칙>
|
||||
- 유저스토리와 매칭 되어야 함. 불필요한 추가 설계 금지
|
||||
(유저스토리 ID를 x-user-story 확장 필드에 명시)
|
||||
- '외부시퀀스설계서'/'내부시퀀스설계서'와 일관성 있게 선정
|
||||
|
||||
#### 1. Recording API (음성 녹음 관리)
|
||||
- `POST /recordings/prepare` - 회의 녹음 준비
|
||||
- `POST /recordings/{recordingId}/start` - 음성 녹음 시작
|
||||
- `POST /recordings/{recordingId}/stop` - 음성 녹음 중지
|
||||
- `GET /recordings/{recordingId}` - 녹음 정보 조회
|
||||
<파일작성안내>
|
||||
- OpenAPI 3.0 스펙 준용
|
||||
- **servers 섹션 필수화**
|
||||
- 모든 OpenAPI 명세에 servers 섹션 포함
|
||||
- SwaggerHub Mock URL을 첫 번째 옵션으로 배치
|
||||
- **example 데이터 권장**
|
||||
- 스키마에 example을 추가하여 Swagger UI에서 테스트 할 수 있게함
|
||||
- **테스트 시나리오 포함**
|
||||
- 각 API 엔드포인트별 테스트 케이스 정의
|
||||
- 성공/실패 케이스 모두 포함
|
||||
- 작성 형식
|
||||
- YAML 형식의 OpenAPI 3.0 명세
|
||||
- 각 API별 필수 항목:
|
||||
- summary: API 목적 설명
|
||||
- operationId: 고유 식별자
|
||||
- x-user-story: 유저스토리 ID
|
||||
- x-controller: 담당 컨트롤러
|
||||
- tags: API 그룹 분류
|
||||
- requestBody/responses: 상세 스키마
|
||||
- 각 서비스 파일에 필요한 모든 스키마 포함:
|
||||
- components/schemas: 요청/응답 모델
|
||||
- components/parameters: 공통 파라미터
|
||||
- components/responses: 공통 응답
|
||||
- components/securitySchemes: 인증 방식
|
||||
|
||||
#### 2. Transcription API (음성-텍스트 변환)
|
||||
- `POST /transcripts/stream` - 실시간 음성-텍스트 변환 (스트리밍)
|
||||
- `POST /transcripts/batch` - 배치 음성-텍스트 변환
|
||||
- `POST /transcripts/callback` - 배치 변환 완료 콜백
|
||||
- `GET /transcripts/{recordingId}` - 변환 텍스트 전체 조회
|
||||
<파일 구조>
|
||||
```
|
||||
design/backend/api/
|
||||
├── {service-name}-api.yaml # 각 마이크로서비스별 API 명세
|
||||
└── ... # 추가 서비스들
|
||||
|
||||
#### 3. Speaker API (화자 식별 및 관리)
|
||||
- `POST /speakers/identify` - 화자 식별
|
||||
- `GET /speakers/{speakerId}` - 화자 정보 조회
|
||||
- `PUT /speakers/{speakerId}` - 화자 정보 업데이트
|
||||
- `GET /recordings/{recordingId}/speakers` - 녹음의 화자 목록 조회
|
||||
|
||||
### 주요 특징
|
||||
|
||||
#### 1. 유저스토리 매핑
|
||||
모든 API는 유저스토리와 매핑되어 있습니다:
|
||||
- **UFR-STT-010** (음성녹음인식): Recording API, Speaker API
|
||||
- **UFR-STT-020** (텍스트변환): Transcription API
|
||||
|
||||
#### 2. 완전한 스키마 정의
|
||||
- 25개의 스키마 정의
|
||||
- 모든 Request/Response 모델 포함
|
||||
- Example 데이터 포함으로 Swagger UI에서 즉시 테스트 가능
|
||||
|
||||
#### 3. Azure 통합
|
||||
- Azure Speech Service 연동
|
||||
- Azure Blob Storage 통합
|
||||
- Azure Event Hubs 이벤트 발행
|
||||
|
||||
#### 4. 실시간 처리
|
||||
- WebSocket 기반 스트리밍 지원
|
||||
- 실시간 인식 지연: < 1초
|
||||
- 화자 식별 정확도: > 90%
|
||||
|
||||
#### 5. 성능 정보
|
||||
각 API의 예상 처리 시간 명시:
|
||||
- 녹음 준비: ~1.1초
|
||||
- 실시간 변환: 1-4초
|
||||
- 배치 변환: 7-33초
|
||||
|
||||
### API 확인 방법
|
||||
|
||||
#### 1. Swagger Editor 사용
|
||||
1. https://editor.swagger.io/ 접속
|
||||
2. 생성된 YAML 파일 내용 복사하여 붙여넣기
|
||||
3. 우측 패널에서 API 문서 확인 및 테스트
|
||||
|
||||
#### 2. 로컬 Swagger UI 실행
|
||||
```bash
|
||||
# Swagger UI Docker 실행
|
||||
docker run -p 8080:8080 -e SWAGGER_JSON=/api/stt-service-api.yaml \
|
||||
-v C:\Users\KTDS\home\workspace\HGZero\design\backend\api:/api \
|
||||
swaggerapi/swagger-ui
|
||||
|
||||
# 브라우저에서 http://localhost:8080 접속
|
||||
예시:
|
||||
├── profile-service-api.yaml # 프로파일 서비스 API
|
||||
├── order-service-api.yaml # 주문 서비스 API
|
||||
└── payment-service-api.yaml # 결제 서비스 API
|
||||
```
|
||||
|
||||
#### 3. VS Code Extension
|
||||
- **확장**: Swagger Viewer
|
||||
- YAML 파일 열고 `Shift + Alt + P` 실행
|
||||
- 미리보기에서 API 문서 확인
|
||||
- 파일명 규칙
|
||||
- 서비스명은 kebab-case로 작성
|
||||
- 파일명 형식: {service-name}-api.yaml
|
||||
- 서비스명은 유저스토리의 '서비스' 항목을 영문으로 변환하여 사용
|
||||
|
||||
### 설계 원칙 준수
|
||||
<병렬처리>
|
||||
- **의존성 분석 선행**: 병렬 처리 전 반드시 의존성 파악
|
||||
- **순차 처리 필요시**: 무리한 병렬화보다는 안전한 순차 처리
|
||||
- **검증 단계 필수**: 병렬 처리 후 통합 검증
|
||||
|
||||
✅ **유저스토리 기반 설계**
|
||||
- 모든 API에 x-user-story 필드 명시
|
||||
- 불필요한 API 추가 없음
|
||||
<검증방법>
|
||||
- swagger-cli를 사용한 자동 검증 수행
|
||||
- 검증 명령어: `swagger-cli validate {파일명}`
|
||||
- swagger-cli가 없을 경우 자동 설치:
|
||||
```bash
|
||||
# swagger-cli 설치 확인 및 자동 설치
|
||||
command -v swagger-cli >/dev/null 2>&1 || npm install -g @apidevtools/swagger-cli
|
||||
|
||||
✅ **시퀀스 일관성**
|
||||
- 내부 시퀀스 설계와 완전히 일치
|
||||
- 모든 처리 흐름 반영
|
||||
# 검증 실행
|
||||
swagger-cli validate design/backend/api/*.yaml
|
||||
```
|
||||
- 검증 항목:
|
||||
- OpenAPI 3.0 스펙 준수
|
||||
- YAML 구문 오류
|
||||
- 스키마 참조 유효성
|
||||
- 필수 필드 존재 여부
|
||||
|
||||
✅ **OpenAPI 3.0 표준**
|
||||
- servers 섹션 필수 포함
|
||||
- 완전한 스키마 정의
|
||||
- JWT 인증 방식 명시
|
||||
[참고자료]
|
||||
- 유저스토리
|
||||
- 외부시퀀스설계서
|
||||
- 내부시퀀스설계서
|
||||
- OpenAPI 스펙: https://swagger.io/specification/
|
||||
|
||||
✅ **Example 데이터**
|
||||
- 모든 스키마에 example 포함
|
||||
- 실제 테스트 가능한 데이터
|
||||
[예시]
|
||||
- swagger api yaml: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-swagger-api.yaml
|
||||
- API설계서: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-API%20설계서.md
|
||||
|
||||
✅ **검증 완료**
|
||||
- swagger-cli 자동 검증 통과
|
||||
- YAML 구문 오류 없음
|
||||
- 스키마 참조 유효성 확인
|
||||
|
||||
### 다음 단계
|
||||
|
||||
1. **Meeting Service API 설계** (회의, 회의록, Todo 통합)
|
||||
2. **AI Service API 설계** (회의록 자동 작성, RAG 기능)
|
||||
3. **User Service API 설계** (인증 전용)
|
||||
4. **Notification Service API 설계** (알림 발송)
|
||||
|
||||
---
|
||||
|
||||
**작성자**: 준호 (Backend Developer)
|
||||
**작성일**: 2025-01-23
|
||||
**검증 도구**: swagger-cli v4.0.4
|
||||
[결과파일]
|
||||
- 각 서비스별로 별도의 YAML 파일 생성
|
||||
- design/backend/api/*.yaml (OpenAPI 형식)
|
||||
@ -1,95 +0,0 @@
|
||||
# API 누락 요약표 (회의 진행 실시간 기능)
|
||||
|
||||
**작성일**: 2025년 10월 28일
|
||||
**근거 문서**: [API리뷰-프로토타입vs구현.md](./API리뷰-프로토타입vs구현.md)
|
||||
|
||||
---
|
||||
|
||||
## 🔴 P0 (치명적 - 즉시 구현 필요)
|
||||
|
||||
| # | API | 프로토타입 근거 | 영향받는 유저스토리 | 비고 |
|
||||
|---|-----|----------------|-------------------|------|
|
||||
| 1 | `PUT /api/meetings/{meetingId}/memo` | [05-회의진행.html:1119-1143](../design/uiux/prototype/05-회의진행.html#L1119-L1143) | US-07, US-10 | 메모 저장 불가, 데이터 손실 위험 |
|
||||
| 2 | `GET /api/ai/suggestions/realtime/{meetingId}` | [05-회의진행.html:767-806](../design/uiux/prototype/05-회의진행.html#L767-L806) | US-07, US-08 | AI 실시간 추천 완전 미동작 |
|
||||
| 3 | `POST /api/stt/recordings/{recordingId}/pause` | [05-회의진행.html:1212-1243](../design/uiux/prototype/05-회의진행.html#L1212-L1243) | US-06 | 녹음 일시정지 불가 |
|
||||
| 4 | `POST /api/stt/recordings/{recordingId}/resume` | [05-회의진행.html:1212-1243](../design/uiux/prototype/05-회의진행.html#L1212-L1243) | US-06 | 녹음 재개 불가 |
|
||||
|
||||
---
|
||||
|
||||
## 🟡 P1 (중요 - 우선 구현 필요)
|
||||
|
||||
| # | API | 프로토타입 근거 | 영향받는 유저스토리 | 비고 |
|
||||
|---|-----|----------------|-------------------|------|
|
||||
| 5 | `POST /api/ai/suggestions/{suggestionId}/adopt` | [05-회의진행.html:1070-1097](../design/uiux/prototype/05-회의진행.html#L1070-L1097) | US-07 | AI 추천 채택 불가, 수동 복붙 필요 |
|
||||
| 6 | `GET /api/ai/terms/search` | [05-회의진행.html:1145-1182](../design/uiux/prototype/05-회의진행.html#L1145-L1182) | US-09 | 용어 검색 불가 |
|
||||
|
||||
---
|
||||
|
||||
## 🟢 P2 (일반 - 향후 개선)
|
||||
|
||||
| # | API | 프로토타입 근거 | 영향받는 유저스토리 | 비고 |
|
||||
|---|-----|----------------|-------------------|------|
|
||||
| 7 | `GET /api/ai/terms/{termName}/detail` | [05-회의진행.html:1305-1308](../design/uiux/prototype/05-회의진행.html#L1305-L1308) | US-09 | 용어 상세 조회 불가 |
|
||||
|
||||
---
|
||||
|
||||
## 📊 탭별 API 구현 현황
|
||||
|
||||
| 탭 | 기능 | 필요 API 수 | 구현 API 수 | 구현률 | 우선순위 |
|
||||
|----|------|------------|------------|--------|---------|
|
||||
| **참석자** | 참석자 관리 | 4 | 4 | 100% ✅ | - |
|
||||
| **AI 메모** | 실시간 메모 & AI 추천 | 3 | 0 | 0% ❌ | P0 (3개) |
|
||||
| **용어사전** | 용어 감지/검색 | 3 | 1 | 33% ⚠️ | P1 (1개), P2 (1개) |
|
||||
| **관련회의록** | 유사 회의록 찾기 | 2 | 2 | 100% ✅ | - |
|
||||
| **녹음 제어** | 녹음 상태 관리 | 5 | 3 | 60% ⚠️ | P0 (2개) |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 구현 권장 순서
|
||||
|
||||
### Sprint 1 (1주) - P0 필수 기능
|
||||
1. **메모 저장 API** (`PUT /api/meetings/{meetingId}/memo`)
|
||||
- 예상 작업: 4시간
|
||||
- 구현 위치: `MeetingController.java`
|
||||
|
||||
2. **AI 실시간 추천 API** (`GET /api/ai/suggestions/realtime/{meetingId}`)
|
||||
- 예상 작업: 8시간
|
||||
- 구현 위치: `SuggestionController.java`
|
||||
- 폴링 또는 SSE 방식 선택 필요
|
||||
|
||||
3. **녹음 일시정지/재개 API** (`POST pause`, `POST resume`)
|
||||
- 예상 작업: 6시간
|
||||
- 구현 위치: `RecordingController.java`
|
||||
|
||||
### Sprint 2 (3일) - P1 중요 기능
|
||||
4. **AI 추천 채택 API** (`POST /api/ai/suggestions/{suggestionId}/adopt`)
|
||||
- 예상 작업: 4시간
|
||||
|
||||
5. **용어 검색 API** (`GET /api/ai/terms/search`)
|
||||
- 예상 작업: 3시간
|
||||
|
||||
### Sprint 3 (2일) - P2 보조 기능
|
||||
6. **용어 상세 조회 API** (`GET /api/ai/terms/{termName}/detail`)
|
||||
- 예상 작업: 4시간
|
||||
|
||||
---
|
||||
|
||||
## 📝 비고
|
||||
|
||||
### 구현 고려사항
|
||||
1. **AI 실시간 추천**: 폴링(Polling) vs SSE(Server-Sent Events) 방식 결정 필요
|
||||
2. **메모 저장**: 개인별 메모 vs 공유 메모 정책 확인 필요
|
||||
3. **녹음 일시정지**: 타이머 상태 동기화 로직 필요
|
||||
4. **용어 검색**: 조직 용어 사전과 회의별 용어 통합 검색 정책 필요
|
||||
|
||||
### 테스트 시나리오
|
||||
- [ ] 회의 진행 중 메모 작성 후 저장 → 다시 로드 시 메모 복원 확인
|
||||
- [ ] AI 추천 메모 실시간 조회 → 5초마다 새 추천 확인
|
||||
- [ ] AI 추천 채택 → 입력창에 시간 포함하여 추가 확인
|
||||
- [ ] 용어 검색 → 키워드로 조직/회의 용어 찾기 확인
|
||||
- [ ] 녹음 일시정지 → 타이머 정지 확인
|
||||
- [ ] 녹음 재개 → 타이머 재개 확인
|
||||
|
||||
---
|
||||
|
||||
**문서 종료**
|
||||
@ -1,832 +0,0 @@
|
||||
# API 리뷰 분석 - 프로토타입 vs 구현
|
||||
|
||||
**작성일**: 2025-10-28
|
||||
**검토자**: Architect, Backend Developer, Frontend Developer
|
||||
**분석 방법**: 프로토타입 HTML 파일과 실제 구현된 Controller 소스코드 비교 분석
|
||||
|
||||
---
|
||||
|
||||
## 📋 요약
|
||||
|
||||
### 전체 현황 (v2.0 - 회의 진행 실시간 기능 추가 분석)
|
||||
- **분석된 화면**: 9개 프로토타입 화면
|
||||
- **프로토타입 요구 API**: **34개** (v1: 27개 → v2: +7개)
|
||||
- **구현된 API**: 27개 엔드포인트
|
||||
- **완전 누락 API**: **11개** (v1: 4개 → v2: +7개)
|
||||
- **개선 필요 API**: 2개
|
||||
- **불필요한 API**: 0개
|
||||
|
||||
### 주요 발견사항 (v2.0 업데이트)
|
||||
1. ✅ **강점**: 핵심 비즈니스 로직 API는 모두 구현됨
|
||||
2. 🔴 **치명적 누락 (기존)**:
|
||||
- `GET /api/meetings` (목록 조회) - 대시보드 "최근 회의" 표시 불가
|
||||
- `PUT/PATCH /api/meetings/{meetingId}` (회의 수정) - 예정된 회의 수정 불가
|
||||
- `GET /api/dashboard/statistics` - 대시보드 통계 카드 표시 불가
|
||||
3. 🔴 **치명적 누락 (신규 발견)**: **회의 진행 중 실시간 기능 API 7개 누락**
|
||||
- **탭2: AI 메모 (3개 누락)**
|
||||
- `PUT /api/meetings/{meetingId}/memo` - 회의 중 메모 저장
|
||||
- `GET /api/ai/suggestions/realtime/{meetingId}` - AI 실시간 추천 메모
|
||||
- `POST /api/ai/suggestions/{suggestionId}/adopt` - AI 추천 채택
|
||||
- **탭3: 용어사전 (2개 누락)**
|
||||
- `GET /api/ai/terms/search` - 용어 검색
|
||||
- `GET /api/ai/terms/{termName}/detail` - 용어 상세 조회
|
||||
- **녹음 제어 (2개 누락)**
|
||||
- `POST /api/stt/recordings/{recordingId}/pause` - 녹음 일시정지
|
||||
- `POST /api/stt/recordings/{recordingId}/resume` - 녹음 재개
|
||||
4. 🟡 **기능 누락**: AI 요약 재생성 API 미구현
|
||||
5. 🟡 **개선 필요**: 회의록 검색/필터링 파라미터 추가 필요
|
||||
|
||||
### 비즈니스 영향도
|
||||
- **사용자 경험**: 회의 진행 중 핵심 편의 기능 미동작으로 인한 UX 저하
|
||||
- **AI 활용도**: 실시간 AI 추천 기능이 동작하지 않아 서비스 차별화 가치 감소
|
||||
- **메모 손실 위험**: 회의 중 작성한 메모가 저장되지 않아 데이터 손실 가능성
|
||||
- **유저스토리 영향**: US-06, US-07, US-08, US-09, US-10의 핵심/보조 기능 미동작
|
||||
|
||||
---
|
||||
|
||||
## 🔍 화면별 상세 분석
|
||||
|
||||
### 1. 로그인 화면 (01-로그인.html)
|
||||
|
||||
| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
|
||||
|---------|---------|----------|----------|------|
|
||||
| 로그인 | `POST /api/auth/login` | ✅ 구현됨 | [UserController.java:37-50](user/src/main/java/com/unicorn/hgzero/user/controller/UserController.java#L37-L50) | LDAP 인증, JWT 토큰 발급 |
|
||||
| 토큰 갱신 | `POST /api/auth/refresh` | ✅ 구현됨 | [UserController.java:59-72](user/src/main/java/com/unicorn/hgzero/user/controller/UserController.java#L59-L72) | Refresh Token 사용 |
|
||||
| 로그아웃 | `POST /api/auth/logout` | ✅ 구현됨 | [UserController.java:82-96](user/src/main/java/com/unicorn/hgzero/user/controller/UserController.java#L82-L96) | Refresh Token 삭제 |
|
||||
| 토큰 검증 | `GET /api/auth/validate` | ✅ 구현됨 | [UserController.java:105-126](user/src/main/java/com/unicorn/hgzero/user/controller/UserController.java#L105-L126) | JWT 토큰 유효성 검증 |
|
||||
|
||||
**분석 결과**: ✅ **완벽 구현** - 모든 인증 관련 API가 구현되어 있으며, 보안 모범 사례를 따르고 있음
|
||||
|
||||
---
|
||||
|
||||
### 2. 대시보드 화면 (02-대시보드.html)
|
||||
|
||||
| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
|
||||
|---------|---------|----------|----------|------|
|
||||
| 최근 회의 목록 (3개) | `GET /api/meetings` | ❌ **누락** | - | **전체 회의 목록 조회 후 프론트에서 정렬** |
|
||||
| 최근 회의록 목록 (4개) | `GET /api/meetings/minutes` | ✅ 구현됨 | [MinutesController.java:210-268](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L210-L268) | 페이징, 필터링 지원 |
|
||||
| 통계 정보 (2개 카드) | `GET /api/dashboard/statistics` | ❌ **누락** | - | 예정된 회의, 작성중 회의록 수 |
|
||||
|
||||
**상세 분석**:
|
||||
|
||||
#### "최근 회의" 섹션 요구사항 ([02-대시보드.html:665-681](design/uiux/prototype/02-대시보드.html#L665-L681))
|
||||
프로토타입 JavaScript 로직:
|
||||
```javascript
|
||||
// 회의록 미생성(scheduled, ongoing) 먼저, 빠른 일시 순 정렬
|
||||
const meetings = [...SAMPLE_MEETINGS]
|
||||
.sort((a, b) => {
|
||||
// 회의록 미생성 회의 우선
|
||||
const aNoMinutes = a.status === 'scheduled' || a.status === 'ongoing';
|
||||
const bNoMinutes = b.status === 'scheduled' || b.status === 'ongoing';
|
||||
|
||||
if (aNoMinutes && !bNoMinutes) return -1;
|
||||
if (!aNoMinutes && bNoMinutes) return 1;
|
||||
|
||||
// 동일 그룹 내에서는 빠른 일시 순 (오름차순)
|
||||
return new Date(a.date + ' ' + a.time) - new Date(b.date + ' ' + b.time);
|
||||
})
|
||||
.slice(0, 3); // 상위 3개만 표시
|
||||
```
|
||||
|
||||
**요구사항 해석**:
|
||||
1. **전체 회의 목록**을 가져와야 함 (상태 무관)
|
||||
2. **회의록 생성 여부 정보** 포함 필요 (scheduled, ongoing, draft, complete)
|
||||
3. 프론트엔드에서 다음 우선순위로 정렬:
|
||||
- 1순위: 회의록 미생성 회의 (`scheduled`, `ongoing`)
|
||||
- 2순위: 빠른 일시 순
|
||||
4. 상위 3개만 표시
|
||||
|
||||
**현재 구현 상태**:
|
||||
- ❌ `GET /api/meetings` (목록 조회) - **완전 누락**
|
||||
- ✅ `GET /api/meetings/{meetingId}` (단건 조회) - 구현됨
|
||||
|
||||
**분석 결과**: ⚠️ **부분 구현** (33%)
|
||||
- **누락 API (2개)**:
|
||||
1. `GET /api/meetings` - 회의 목록 조회 (전체 상태, 날짜/시간 정렬 필요)
|
||||
2. `GET /api/dashboard/statistics` - 통계 정보 (예정된 회의, 작성중 회의록)
|
||||
|
||||
**권장사항**:
|
||||
```java
|
||||
// MeetingController에 추가 필요
|
||||
@GetMapping
|
||||
@Operation(summary = "회의 목록 조회", description = "사용자의 회의 목록을 조회합니다")
|
||||
public ResponseEntity<ApiResponse<MeetingListResponse>> getMeetingList(
|
||||
@RequestHeader("X-User-Id") String userId,
|
||||
@RequestParam(required = false) String status, // all(기본값), scheduled, ongoing, draft, complete
|
||||
@RequestParam(required = false) LocalDateTime startDate,
|
||||
@RequestParam(required = false) LocalDateTime endDate,
|
||||
@RequestParam(defaultValue = "0") int page,
|
||||
@RequestParam(defaultValue = "10") int size,
|
||||
@RequestParam(defaultValue = "startTime") String sortBy,
|
||||
@RequestParam(defaultValue = "asc") String sortDir
|
||||
) {
|
||||
// 사용자가 참여한 모든 회의 조회
|
||||
// 응답에 회의록 생성 여부(hasMinutes), 회의록 상태(minutesStatus) 포함 필수
|
||||
}
|
||||
|
||||
// 새로운 DashboardController 생성 권장
|
||||
@GetMapping("/api/dashboard/statistics")
|
||||
public ResponseEntity<ApiResponse<DashboardStatistics>> getStatistics(
|
||||
@RequestHeader("X-User-Id") String userId
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 회의 예약/수정 화면 (03-회의예약.html)
|
||||
|
||||
| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
|
||||
|---------|---------|----------|----------|------|
|
||||
| 회의 생성 | `POST /api/meetings` | ✅ 구현됨 | [MeetingController.java:60-93](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L60-L93) | 참석자 초대 포함 |
|
||||
| 회의 정보 수정 | `PUT /api/meetings/{meetingId}` 또는 `PATCH /api/meetings/{meetingId}` | ❌ **누락** | - | **예정된 회의 수정 불가** |
|
||||
|
||||
**상세 분석**:
|
||||
|
||||
#### 회의 수정 요구사항 ([02-대시보드.html:724](design/uiux/prototype/02-대시보드.html#L724))
|
||||
프로토타입 JavaScript 로직:
|
||||
```javascript
|
||||
// 상태에 따른 이동 처리
|
||||
if (meetingStatus === 'ongoing') {
|
||||
navigateTo('05-회의진행.html');
|
||||
} else if (meetingStatus === 'draft' || meetingStatus === 'complete' || meetingStatus === 'completed') {
|
||||
navigateTo('10-회의록상세조회.html');
|
||||
} else if (meetingStatus === 'scheduled') {
|
||||
navigateTo('03-회의예약.html'); // 예정된 회의 → 회의예약 화면 (수정 모드)
|
||||
}
|
||||
```
|
||||
|
||||
**요구사항 해석**:
|
||||
1. 대시보드에서 **예정된 회의(scheduled) 카드 클릭**
|
||||
2. 회의예약 화면(03-회의예약.html)으로 이동
|
||||
3. 기존 회의 정보를 **로드하여 수정 가능**해야 함
|
||||
4. 수정 완료 시 `PUT` 또는 `PATCH` 요청 필요
|
||||
|
||||
**현재 상태**:
|
||||
- ❌ API 설계서([meeting-service-api.yaml](design/backend/api/meeting-service-api.yaml)) - **회의 수정 API 명세 없음**
|
||||
- ❌ MeetingController - **회의 수정 API 구현 없음**
|
||||
- ✅ `POST /api/meetings` (생성) - 구현됨
|
||||
- ✅ `GET /api/meetings/{meetingId}` (단건 조회) - 구현됨
|
||||
- ❌ `PUT/PATCH /api/meetings/{meetingId}` (수정) - **완전 누락**
|
||||
|
||||
**분석 결과**: ⚠️ **치명적 누락** (50%)
|
||||
- 회의 생성은 가능하지만, **예약된 회의 수정 불가**
|
||||
- 사용자가 대시보드에서 예정된 회의를 클릭해도 수정할 수 없음
|
||||
|
||||
**권장사항**:
|
||||
```java
|
||||
// MeetingController에 추가 필요
|
||||
@PutMapping("/{meetingId}")
|
||||
@Operation(summary = "회의 정보 수정", description = "예정된 회의의 정보를 수정합니다")
|
||||
public ResponseEntity<ApiResponse<MeetingResponse>> updateMeeting(
|
||||
@PathVariable String meetingId,
|
||||
@RequestHeader("X-User-Id") String userId,
|
||||
@RequestHeader("X-User-Name") String userName,
|
||||
@RequestHeader("X-User-Email") String userEmail,
|
||||
@Valid @RequestBody UpdateMeetingRequest request
|
||||
) {
|
||||
// 회의 정보 수정 로직
|
||||
// - 제목, 날짜, 시간, 장소, 안건 수정 가능
|
||||
// - 참석자 추가/제거 가능
|
||||
// - 회의 상태가 'scheduled'일 때만 수정 가능
|
||||
// - 변경 사항 참석자에게 알림
|
||||
}
|
||||
```
|
||||
|
||||
**UpdateMeetingRequest DTO**:
|
||||
```java
|
||||
public class UpdateMeetingRequest {
|
||||
private String title; // 회의 제목
|
||||
private LocalDateTime startTime; // 시작 시간
|
||||
private LocalDateTime endTime; // 종료 시간
|
||||
private String location; // 장소
|
||||
private String agenda; // 안건
|
||||
private List<String> participants; // 참석자 이메일 목록
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 템플릿 선택 화면 (04-템플릿선택.html)
|
||||
|
||||
| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
|
||||
|---------|---------|----------|----------|------|
|
||||
| 템플릿 목록 조회 | `GET /api/meetings/templates` | ✅ 구현됨 | [TemplateController.java:33-63](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/TemplateController.java#L33-L63) | 4가지 고정 템플릿 제공 |
|
||||
| 템플릿 적용 | `PUT /api/meetings/{meetingId}/template` | ✅ 구현됨 | [MeetingController.java:108-135](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L108-L135) | 템플릿 ID로 적용 |
|
||||
|
||||
**분석 결과**: ✅ **완벽 구현** - 템플릿 관리 기능 완전 구현
|
||||
|
||||
---
|
||||
|
||||
### 5. 회의 진행 화면 (05-회의진행.html) ⚠️ **중요 업데이트**
|
||||
|
||||
#### 화면 구조 분석
|
||||
프로토타입은 4개 탭으로 구성되어 있으며, 각 탭마다 실시간 기능이 요구됩니다:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 📍 헤더: 회의 제목 + 녹음 상태 │
|
||||
├─────────────────────────────────────────┤
|
||||
│ 📋 회의 기본정보 (카드) │
|
||||
├─────────────────────────────────────────┤
|
||||
│ 📑 4개 탭 컨테이너 │
|
||||
│ ┌──────────────────────────────────┐ │
|
||||
│ │ 🧑🤝🧑 참석자 | 📝 AI메모 | 📚 용어 │ │
|
||||
│ │ 사전 | 📂 관련회의록 │ │
|
||||
│ └──────────────────────────────────┘ │
|
||||
├─────────────────────────────────────────┤
|
||||
│ ⏸️ 일시정지 | 🔴 회의 종료 버튼 │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### 탭1: 참석자 (Lines 697-747)
|
||||
|
||||
| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
|
||||
|---------|---------|----------|----------|------|
|
||||
| 회의 시작 | `POST /api/meetings/{meetingId}/start` | ✅ 구현됨 | [MeetingController.java:149-170](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L149-L170) | WebSocket 세션 생성 |
|
||||
| WebSocket 연결 | `ws://localhost:8080/ws/collaboration` | ✅ 구현됨 | [MeetingController.java:165](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L165) | 실시간 협업 지원 |
|
||||
| 참석자 초대 | `POST /api/meetings/{meetingId}/invite` | ✅ 구현됨 | [MeetingController.java:289-321](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L289-L321) | 이메일 발송 포함 |
|
||||
| 참석자 목록 표시 | `GET /api/meetings/{meetingId}` | ✅ 구현됨 | [MeetingController.java:228-244](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L228-L244) | 회의 정보에 참석자 포함 |
|
||||
|
||||
#### 탭2: AI 메모 (Lines 750-807) 🔴 **치명적 누락**
|
||||
|
||||
| 화면 기능 | 요구 API | 구현 상태 | 프로토타입 근거 | 비고 |
|
||||
|---------|---------|----------|---------------|------|
|
||||
| **메모 입력 및 저장** | `PUT /api/meetings/{meetingId}/memo` | ❌ **누락** | [Line 1119-1143](design/uiux/prototype/05-회의진행.html#L1119-L1143) | 개인별 메모 저장 |
|
||||
| **AI 추천 실시간 조회** | `GET /api/ai/suggestions/realtime/{meetingId}` | ❌ **누락** | [Line 767-806](design/uiux/prototype/05-회의진행.html#L767-L806) | 실시간 폴링 필요 |
|
||||
| **AI 추천 채택** | `POST /api/ai/suggestions/{suggestionId}/adopt` | ❌ **누락** | [Line 1070-1097](design/uiux/prototype/05-회의진행.html#L1070-L1097) | 시간 포함 저장 |
|
||||
|
||||
**프로토타입 JavaScript 분석** (saveMemo 함수):
|
||||
```javascript
|
||||
function saveMemo() {
|
||||
const memo = memoTextarea.value.trim();
|
||||
// 실제 구현시에는 서버로 전송
|
||||
// fetch('/api/meetings/memo', {
|
||||
// method: 'PUT',
|
||||
// body: JSON.stringify({ memo: memo }),
|
||||
// headers: { 'Content-Type': 'application/json' }
|
||||
// });
|
||||
}
|
||||
```
|
||||
|
||||
**영향도**:
|
||||
- 🔴 사용자가 작성한 메모가 저장되지 않음 (데이터 손실 위험)
|
||||
- 🔴 AI 실시간 추천 기능 완전 미동작
|
||||
- 🔴 **유저스토리 US-07, US-08**의 핵심 기능
|
||||
|
||||
#### 탭3: 용어사전 (Lines 810-967) 🟡 **부분 구현**
|
||||
|
||||
| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
|
||||
|---------|---------|----------|----------|------|
|
||||
| **AI 전문용어 실시간 감지** | `POST /api/ai/terms/detect` | ✅ 구현됨 | [TermController.java:35-79](ai/src/main/java/com/unicorn/hgzero/ai/infra/controller/TermController.java#L35-L79) | 회의 중 용어 자동 감지 |
|
||||
| **용어 검색** | `GET /api/ai/terms/search` | ❌ **누락** | [Line 1145-1182](design/uiux/prototype/05-회의진행.html#L1145-L1182) | 키워드 검색 |
|
||||
| **용어 상세 조회** | `GET /api/ai/terms/{termName}/detail` | ❌ **누락** | [Line 1305-1308](design/uiux/prototype/05-회의진행.html#L1305-L1308) | 모달 표시 |
|
||||
|
||||
#### 탭4: 관련회의록 (Lines 970-1010) ✅ **완벽 구현**
|
||||
|
||||
| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
|
||||
|---------|---------|----------|----------|------|
|
||||
| **AI 유사 회의록 찾기** | `GET /api/ai/transcripts/{meetingId}/related` | ✅ 구현됨 | [RelationController.java:31-62](ai/src/main/java/com/unicorn/hgzero/ai/infra/controller/RelationController.java#L31-L62) | 벡터 유사도 검색 |
|
||||
| 관련 회의록 열기 | `GET /api/meetings/minutes/{minutesId}` | ✅ 구현됨 | 기존 API 재사용 | 새 탭 열기 |
|
||||
|
||||
#### 녹음 제어 (Bottom Bar) 🔴 **치명적 누락**
|
||||
|
||||
| 화면 기능 | 요구 API | 구현 상태 | 프로토타입 근거 | 비고 |
|
||||
|---------|---------|----------|---------------|------|
|
||||
| **녹음 일시정지** | `POST /api/stt/recordings/{recordingId}/pause` | ❌ **누락** | [Line 1212-1243](design/uiux/prototype/05-회의진행.html#L1212-L1243) | 타이머 정지 |
|
||||
| **녹음 재개** | `POST /api/stt/recordings/{recordingId}/resume` | ❌ **누락** | [Line 1212-1243](design/uiux/prototype/05-회의진행.html#L1212-L1243) | 타이머 재개 |
|
||||
| 녹음 시작 | `POST /api/stt/recordings/{recordingId}/start` | ✅ 구현됨 | [RecordingController.java:83-94](stt/src/main/java/com/unicorn/hgzero/stt/controller/RecordingController.java#L83-L94) | - |
|
||||
| 녹음 중지 | `POST /api/stt/recordings/{recordingId}/stop` | ✅ 구현됨 | [RecordingController.java:115-126](stt/src/main/java/com/unicorn/hgzero/stt/controller/RecordingController.java#L115-L126) | - |
|
||||
| 회의 종료 | `POST /api/meetings/{meetingId}/end` | ✅ 구현됨 | [MeetingController.java:184-214](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L184-L214) | AI 분석 포함 |
|
||||
|
||||
**현재 상태**: RecordingController에는 `start`와 `stop`만 있고 `pause/resume` 없음
|
||||
|
||||
**영향도**:
|
||||
- 🔴 회의 중 잠깐 중단 후 재개 시나리오 불가
|
||||
- 🔴 **유저스토리 US-06**의 핵심 기능
|
||||
|
||||
---
|
||||
|
||||
**분석 결과**: ⚠️ **부분 구현 (50%)** - **실시간 기능 7개 API 누락**
|
||||
|
||||
### 누락 API 상세 명세
|
||||
|
||||
#### 1. 메모 저장 API 🔴 P0
|
||||
```java
|
||||
PUT /api/meetings/{meetingId}/memo
|
||||
Request Body: {
|
||||
"memo": "string",
|
||||
"userId": "string",
|
||||
"timestamp": "datetime"
|
||||
}
|
||||
Response: { "memoId": "string", "savedAt": "datetime" }
|
||||
```
|
||||
|
||||
#### 2. AI 실시간 추천 조회 API 🔴 P0
|
||||
```java
|
||||
GET /api/ai/suggestions/realtime/{meetingId}?since={timestamp}&limit=10
|
||||
Response: {
|
||||
"suggestions": [
|
||||
{
|
||||
"suggestionId": "string",
|
||||
"timestamp": "00:05:23",
|
||||
"content": "string",
|
||||
"confidence": 0.95,
|
||||
"category": "DISCUSSION|DECISION"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. AI 추천 채택 API 🟡 P1
|
||||
```java
|
||||
POST /api/ai/suggestions/{suggestionId}/adopt
|
||||
Request Body: {
|
||||
"meetingId": "string",
|
||||
"timestamp": "00:05:23",
|
||||
"userId": "string"
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. 용어 검색 API 🟡 P1
|
||||
```java
|
||||
GET /api/ai/terms/search?query={keyword}&meetingId={id}
|
||||
Response: {
|
||||
"terms": [...],
|
||||
"totalCount": 5
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. 용어 상세 조회 API 🟢 P2
|
||||
```java
|
||||
GET /api/ai/terms/{termName}/detail?meetingId={id}
|
||||
Response: {
|
||||
"term": "string",
|
||||
"definition": "string",
|
||||
"usageInMeeting": [...],
|
||||
"externalLinks": [...]
|
||||
}
|
||||
```
|
||||
|
||||
#### 6-7. 녹음 일시정지/재개 API 🔴 P0
|
||||
```java
|
||||
POST /api/stt/recordings/{recordingId}/pause
|
||||
POST /api/stt/recordings/{recordingId}/resume
|
||||
Response: { "status": "PAUSED|RECORDING", "timestamp": "datetime" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. 회의 종료 화면 (07-회의종료.html)
|
||||
|
||||
| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
|
||||
|---------|---------|----------|----------|------|
|
||||
| 회의 종료 | `POST /api/meetings/{meetingId}/end` | ✅ 구현됨 | [MeetingController.java:184-214](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L184-L214) | AI 분석, 회의록 생성 |
|
||||
|
||||
**분석 결과**: ✅ **완벽 구현** - AI 기반 회의록 자동 생성 포함
|
||||
|
||||
---
|
||||
|
||||
### 7. 회의록 상세 조회 화면 (10-회의록상세조회.html)
|
||||
|
||||
| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
|
||||
|---------|---------|----------|----------|------|
|
||||
| 회의록 상세 조회 | `GET /api/meetings/minutes/{minutesId}` | ✅ 구현됨 | [MinutesController.java:271-297](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L271-L297) | 대시보드 탭, 회의록 탭 데이터 포함 |
|
||||
|
||||
**분석 결과**: ✅ **완벽 구현** - 상세 조회 완전 구현 (Mock 데이터 포함)
|
||||
|
||||
---
|
||||
|
||||
### 8. 회의록 수정 화면 (11-회의록수정.html)
|
||||
|
||||
| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
|
||||
|---------|---------|----------|----------|------|
|
||||
| 회의록 수정 | `PATCH /api/meetings/minutes/{minutesId}` | ✅ 구현됨 | [MinutesController.java:300-343](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L300-L343) | 제목, 섹션 내용 수정 |
|
||||
| 회의록 확정 | `POST /api/meetings/minutes/{minutesId}/finalize` | ✅ 구현됨 | [MinutesController.java:346-374](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L346-L374) | 버전 관리 포함 |
|
||||
| 섹션 검증 | `POST /api/meetings/minutes/{minutesId}/sections/{sectionId}/verify` | ✅ 구현됨 | [MinutesController.java:377-410](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L377-L410) | 섹션별 완료 검증 |
|
||||
| 섹션 잠금 | `POST /api/meetings/minutes/{minutesId}/sections/{sectionId}/lock` | ✅ 구현됨 | [MinutesController.java:413-446](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L413-L446) | 동시 편집 방지 |
|
||||
| 섹션 잠금 해제 | `DELETE /api/meetings/minutes/{minutesId}/sections/{sectionId}/lock` | ✅ 구현됨 | [MinutesController.java:449-480](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L449-L480) | 잠금 해제 |
|
||||
| AI 요약 재생성 | `POST /api/meetings/minutes/{minutesId}/sections/{sectionId}/regenerate-summary` | ❌ **누락** | - | AI 요약 재생성 기능 필요 |
|
||||
|
||||
**분석 결과**: ⚠️ **부분 구현** (83%)
|
||||
- **누락 API (1개)**: AI 요약 재생성 기능
|
||||
|
||||
**권장사항**:
|
||||
```java
|
||||
// MinutesController에 추가 필요
|
||||
@PostMapping("/{minutesId}/sections/{sectionId}/regenerate-summary")
|
||||
@Operation(summary = "AI 요약 재생성", description = "섹션의 AI 요약을 재생성합니다")
|
||||
public ResponseEntity<ApiResponse<SectionSummary>> regenerateSummary(
|
||||
@PathVariable String minutesId,
|
||||
@PathVariable String sectionId,
|
||||
@RequestHeader("X-User-Id") String userId
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9. 회의록 목록 조회 화면 (12-회의록목록조회.html)
|
||||
|
||||
| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
|
||||
|---------|---------|----------|----------|------|
|
||||
| 회의록 목록 조회 | `GET /api/meetings/minutes` | ✅ 구현됨 | [MinutesController.java:210-268](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L210-L268) | 상태 필터, 페이징 지원 |
|
||||
| 검색 기능 | `GET /api/meetings/minutes?keyword={keyword}` | ⚠️ **개선 필요** | [MinutesController.java:210](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L210) | 키워드 검색 파라미터 추가 필요 |
|
||||
| 참여 유형 필터 | `GET /api/meetings/minutes?participationType={type}` | ⚠️ **개선 필요** | [MinutesController.java:210](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L210) | 참여 유형 필터 추가 필요 |
|
||||
|
||||
**분석 결과**: ⚠️ **개선 필요**
|
||||
- 기본 목록 조회는 구현되어 있으나, 프로토타입에서 요구하는 세부 필터링 기능 미구현
|
||||
|
||||
**권장사항**:
|
||||
```java
|
||||
// MinutesController 개선 필요
|
||||
@GetMapping
|
||||
public ResponseEntity<ApiResponse<MinutesListResponse>> getMinutesList(
|
||||
@RequestHeader("X-User-Id") String userId,
|
||||
@RequestParam(required = false) String status, // 기존 기능
|
||||
@RequestParam(required = false) String keyword, // 추가 필요 - 제목/내용 검색
|
||||
@RequestParam(required = false) String participationType, // 추가 필요 - host, participant, all
|
||||
@RequestParam(defaultValue = "0") int page,
|
||||
@RequestParam(defaultValue = "20") int size,
|
||||
@RequestParam(defaultValue = "createdAt") String sortBy,
|
||||
@RequestParam(defaultValue = "desc") String sortDir
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 통합 분석
|
||||
|
||||
### 구현된 API 목록 (24개)
|
||||
|
||||
#### 인증 서비스 (4개)
|
||||
| API | 메서드 | 엔드포인트 | 구현 위치 |
|
||||
|-----|--------|-----------|----------|
|
||||
| 로그인 | POST | `/api/auth/login` | [UserController.java:37](user/src/main/java/com/unicorn/hgzero/user/controller/UserController.java#L37) |
|
||||
| 토큰 갱신 | POST | `/api/auth/refresh` | [UserController.java:59](user/src/main/java/com/unicorn/hgzero/user/controller/UserController.java#L59) |
|
||||
| 로그아웃 | POST | `/api/auth/logout` | [UserController.java:82](user/src/main/java/com/unicorn/hgzero/user/controller/UserController.java#L82) |
|
||||
| 토큰 검증 | GET | `/api/auth/validate` | [UserController.java:105](user/src/main/java/com/unicorn/hgzero/user/controller/UserController.java#L105) |
|
||||
|
||||
#### 회의 관리 서비스 (6개 - 목록 조회, 회의 수정 누락)
|
||||
| API | 메서드 | 엔드포인트 | 구현 위치 |
|
||||
|-----|--------|-----------|----------|
|
||||
| 회의 생성 | POST | `/api/meetings` | [MeetingController.java:60](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L60) |
|
||||
| 템플릿 적용 | PUT | `/api/meetings/{meetingId}/template` | [MeetingController.java:108](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L108) |
|
||||
| 회의 시작 | POST | `/api/meetings/{meetingId}/start` | [MeetingController.java:149](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L149) |
|
||||
| 회의 종료 | POST | `/api/meetings/{meetingId}/end` | [MeetingController.java:184](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L184) |
|
||||
| 회의 단건 조회 | GET | `/api/meetings/{meetingId}` | [MeetingController.java:228](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L228) |
|
||||
| 회의 취소 | DELETE | `/api/meetings/{meetingId}` | [MeetingController.java:258](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L258) |
|
||||
| 참석자 초대 | POST | `/api/meetings/{meetingId}/invite` | [MeetingController.java:289](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L289) |
|
||||
|
||||
**⚠️ 누락 API (2개)**:
|
||||
1. `GET /api/meetings` (회의 목록 조회) - 대시보드 "최근 회의" 섹션에 필수
|
||||
2. `PUT /api/meetings/{meetingId}` (회의 정보 수정) - **예정된 회의 수정 불가**
|
||||
|
||||
#### 회의록 관리 서비스 (7개)
|
||||
| API | 메서드 | 엔드포인트 | 구현 위치 |
|
||||
|-----|--------|-----------|----------|
|
||||
| 회의록 목록 조회 | GET | `/api/meetings/minutes` | [MinutesController.java:210](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L210) |
|
||||
| 회의록 상세 조회 | GET | `/api/meetings/minutes/{minutesId}` | [MinutesController.java:271](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L271) |
|
||||
| 회의록 수정 | PATCH | `/api/meetings/minutes/{minutesId}` | [MinutesController.java:300](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L300) |
|
||||
| 회의록 확정 | POST | `/api/meetings/minutes/{minutesId}/finalize` | [MinutesController.java:346](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L346) |
|
||||
| 섹션 검증 | POST | `/api/meetings/minutes/{minutesId}/sections/{sectionId}/verify` | [MinutesController.java:377](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L377) |
|
||||
| 섹션 잠금 | POST | `/api/meetings/minutes/{minutesId}/sections/{sectionId}/lock` | [MinutesController.java:413](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L413) |
|
||||
| 섹션 잠금 해제 | DELETE | `/api/meetings/minutes/{minutesId}/sections/{sectionId}/lock` | [MinutesController.java:449](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L449) |
|
||||
|
||||
#### Todo 관리 서비스 (4개)
|
||||
| API | 메서드 | 엔드포인트 | 구현 위치 |
|
||||
|-----|--------|-----------|----------|
|
||||
| Todo 생성 | POST | `/api/meetings/todos` | [TodoController.java:50](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/TodoController.java#L50) |
|
||||
| Todo 수정 | PATCH | `/api/meetings/todos/{todoId}` | [TodoController.java:114](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/TodoController.java#L114) |
|
||||
| Todo 완료 | PATCH | `/api/meetings/todos/{todoId}/complete` | [TodoController.java:163](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/TodoController.java#L163) |
|
||||
| Todo 목록 조회 | GET | `/api/meetings/todos` | [TodoController.java:210](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/TodoController.java#L210) |
|
||||
|
||||
#### 템플릿 관리 서비스 (1개)
|
||||
| API | 메서드 | 엔드포인트 | 구현 위치 |
|
||||
|-----|--------|-----------|----------|
|
||||
| 템플릿 목록 조회 | GET | `/api/meetings/templates` | [TemplateController.java:33](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/TemplateController.java#L33) |
|
||||
|
||||
#### WebSocket (1개)
|
||||
| API | 프로토콜 | 엔드포인트 | 구현 위치 |
|
||||
|-----|---------|-----------|----------|
|
||||
| 실시간 협업 | WebSocket | `ws://localhost:8080/ws/collaboration` | [MeetingController.java:165](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L165) |
|
||||
|
||||
---
|
||||
|
||||
### ❌ 누락된 API 목록 (4개 완전 누락 + 2개 개선 필요)
|
||||
|
||||
#### 완전 누락 (4개)
|
||||
| 우선순위 | API | 메서드 | 엔드포인트 | 필요한 이유 | 권장 구현 위치 |
|
||||
|---------|-----|--------|-----------|-----------|--------------|
|
||||
| 🔴 **긴급** | 회의 목록 조회 | GET | `/api/meetings` | 대시보드 "최근 회의" 섹션 표시 **불가** | MeetingController |
|
||||
| 🔴 **긴급** | 회의 정보 수정 | PUT/PATCH | `/api/meetings/{meetingId}` | 대시보드에서 예정된 회의 클릭 시 수정 **불가** | MeetingController |
|
||||
| 🔴 **긴급** | 대시보드 통계 | GET | `/api/dashboard/statistics` | 대시보드 통계 카드 (예정된 회의, 작성중 회의록) 표시 **불가** | 신규 DashboardController |
|
||||
| 🟡 중간 | AI 요약 재생성 | POST | `/api/meetings/minutes/{minutesId}/sections/{sectionId}/regenerate-summary` | 회의록 수정 화면 AI 요약 재생성 버튼 **동작 불가** | MinutesController |
|
||||
|
||||
#### 기능 개선 필요 (2개)
|
||||
| 우선순위 | API | 현재 상태 | 개선 내용 | 필요한 이유 |
|
||||
|---------|-----|----------|-----------|-----------|
|
||||
| 🟡 중간 | 회의록 목록 조회 | `GET /api/meetings/minutes` 구현됨 | `keyword` 파라미터 추가 | 회의록 목록 화면 검색 기능 동작 안 함 |
|
||||
| 🟡 중간 | 회의록 목록 조회 | `GET /api/meetings/minutes` 구현됨 | `participationType` 파라미터 추가 | 회의록 목록 화면 참여 유형 필터 동작 안 함 |
|
||||
|
||||
---
|
||||
|
||||
### ✅ 불필요한 API (0개)
|
||||
|
||||
**분석 결과**: 구현된 모든 API가 프로토타입에서 요구하는 기능과 매칭되며, 불필요한 API는 없음.
|
||||
|
||||
---
|
||||
|
||||
## 💡 권장 개선사항
|
||||
|
||||
### 1. 높은 우선순위 (🔴 필수)
|
||||
|
||||
#### 1.1 회의 목록 조회 API 추가
|
||||
```java
|
||||
// MeetingController.java에 추가
|
||||
@GetMapping
|
||||
@Operation(summary = "회의 목록 조회", description = "사용자의 회의 목록을 조회합니다")
|
||||
public ResponseEntity<ApiResponse<MeetingListResponse>> getMeetingList(
|
||||
@RequestHeader("X-User-Id") String userId,
|
||||
@RequestParam(required = false) String status, // upcoming, ongoing, completed
|
||||
@RequestParam(required = false) LocalDateTime startDate,
|
||||
@RequestParam(required = false) LocalDateTime endDate,
|
||||
@RequestParam(defaultValue = "0") int page,
|
||||
@RequestParam(defaultValue = "10") int size,
|
||||
@RequestParam(defaultValue = "startTime") String sortBy,
|
||||
@RequestParam(defaultValue = "asc") String sortDir
|
||||
) {
|
||||
// 구현 로직
|
||||
}
|
||||
```
|
||||
|
||||
**요구사항**:
|
||||
- 상태별 필터링: `upcoming` (예정), `ongoing` (진행 중), `completed` (완료)
|
||||
- 날짜 범위 필터링
|
||||
- 페이징 지원
|
||||
- 정렬 기능 (시작 시간, 생성 시간 등)
|
||||
|
||||
---
|
||||
|
||||
#### 1.2 대시보드 통계 API 추가
|
||||
```java
|
||||
// 신규 DashboardController.java 생성
|
||||
@RestController
|
||||
@RequestMapping("/api/dashboard")
|
||||
@RequiredArgsConstructor
|
||||
@Tag(name = "Dashboard", description = "대시보드 API")
|
||||
public class DashboardController {
|
||||
|
||||
@GetMapping("/statistics")
|
||||
@Operation(summary = "대시보드 통계 조회", description = "사용자의 통계 정보를 조회합니다")
|
||||
public ResponseEntity<ApiResponse<DashboardStatistics>> getStatistics(
|
||||
@RequestHeader("X-User-Id") String userId
|
||||
) {
|
||||
// 구현 로직
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**응답 데이터 구조**:
|
||||
```json
|
||||
{
|
||||
"totalMeetings": 24,
|
||||
"upcomingMeetings": 3,
|
||||
"completedMinutes": 18,
|
||||
"pendingTodos": 7,
|
||||
"completedTodos": 15,
|
||||
"thisWeekMeetings": 5,
|
||||
"thisMonthMeetings": 12
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 중간 우선순위 (🟡 권장)
|
||||
|
||||
#### 2.1 AI 요약 재생성 API 추가
|
||||
```java
|
||||
// MinutesController.java에 추가
|
||||
@PostMapping("/{minutesId}/sections/{sectionId}/regenerate-summary")
|
||||
@Operation(summary = "AI 요약 재생성", description = "섹션의 AI 요약을 재생성합니다")
|
||||
public ResponseEntity<ApiResponse<SectionSummary>> regenerateSummary(
|
||||
@PathVariable String minutesId,
|
||||
@PathVariable String sectionId,
|
||||
@RequestHeader("X-User-Id") String userId,
|
||||
@RequestHeader("X-User-Name") String userName
|
||||
) {
|
||||
// AI 서비스 호출하여 요약 재생성
|
||||
// 버전 관리 (이전 요약 보존)
|
||||
// 이벤트 발행 (요약 재생성 알림)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 2.2 회의록 목록 API 개선
|
||||
```java
|
||||
// MinutesController.java 수정
|
||||
@GetMapping
|
||||
public ResponseEntity<ApiResponse<MinutesListResponse>> getMinutesList(
|
||||
@RequestHeader("X-User-Id") String userId,
|
||||
@RequestParam(required = false) String status,
|
||||
@RequestParam(required = false) String keyword, // 추가 - 제목/내용 검색
|
||||
@RequestParam(required = false) String participationType, // 추가 - host, participant, all
|
||||
@RequestParam(defaultValue = "0") int page,
|
||||
@RequestParam(defaultValue = "20") int size,
|
||||
@RequestParam(defaultValue = "createdAt") String sortBy,
|
||||
@RequestParam(defaultValue = "desc") String sortDir
|
||||
) {
|
||||
// 구현 로직
|
||||
}
|
||||
```
|
||||
|
||||
**추가 필터 설명**:
|
||||
- `keyword`: 회의록 제목 또는 내용에서 검색 (LIKE 검색)
|
||||
- `participationType`:
|
||||
- `host`: 주최한 회의록만
|
||||
- `participant`: 참여한 회의록만
|
||||
- `all`: 모든 회의록 (기본값)
|
||||
|
||||
---
|
||||
|
||||
### 3. 낮은 우선순위 (🟢 선택)
|
||||
|
||||
#### 3.1 회의록 버전 관리 API
|
||||
```java
|
||||
// MinutesController.java에 추가 고려
|
||||
@GetMapping("/{minutesId}/versions")
|
||||
@Operation(summary = "회의록 버전 목록 조회")
|
||||
public ResponseEntity<ApiResponse<List<MinutesVersion>>> getMinutesVersions(
|
||||
@PathVariable String minutesId
|
||||
)
|
||||
|
||||
@GetMapping("/{minutesId}/versions/{version}")
|
||||
@Operation(summary = "특정 버전 회의록 조회")
|
||||
public ResponseEntity<ApiResponse<MinutesDetail>> getMinutesVersion(
|
||||
@PathVariable String minutesId,
|
||||
@PathVariable int version
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 구현 우선순위 로드맵
|
||||
|
||||
### Phase 1: 필수 기능 (Sprint 1-2)
|
||||
1. ✅ **회의 목록 조회 API** (MeetingController)
|
||||
- 예상 작업 시간: 4시간
|
||||
- 의존성: MeetingService, MeetingRepository
|
||||
|
||||
2. ✅ **대시보드 통계 API** (신규 DashboardController)
|
||||
- 예상 작업 시간: 6시간
|
||||
- 의존성: MeetingService, MinutesService, TodoService
|
||||
|
||||
### Phase 2: 개선 기능 (Sprint 3)
|
||||
3. ✅ **AI 요약 재생성 API** (MinutesController)
|
||||
- 예상 작업 시간: 8시간
|
||||
- 의존성: AI Service, Event Publisher
|
||||
|
||||
4. ✅ **회의록 검색/필터 개선** (MinutesController)
|
||||
- 예상 작업 시간: 3시간
|
||||
- 의존성: MinutesRepository (쿼리 추가)
|
||||
|
||||
### Phase 3: 선택 기능 (Sprint 4)
|
||||
5. ⏸️ **버전 관리 API** (MinutesController)
|
||||
- 예상 작업 시간: 6시간
|
||||
- 의존성: 버전 관리 스키마 설계
|
||||
|
||||
---
|
||||
|
||||
## 📝 코드 리뷰 의견
|
||||
|
||||
### ✅ 잘된 점
|
||||
|
||||
1. **일관된 API 설계**
|
||||
- RESTful 원칙 준수
|
||||
- 명확한 엔드포인트 네이밍
|
||||
- 표준 HTTP 메서드 사용
|
||||
|
||||
2. **포괄적인 문서화**
|
||||
- Swagger/OpenAPI 주석 완벽 작성
|
||||
- 각 API마다 상세한 설명과 파라미터 문서화
|
||||
|
||||
3. **보안 고려**
|
||||
- JWT 기반 인증/인가
|
||||
- LDAP 통합
|
||||
- Request Header를 통한 사용자 식별
|
||||
|
||||
4. **실용적인 Mock 데이터**
|
||||
- 프론트엔드 개발을 위한 상세한 Mock 데이터 제공
|
||||
- 실제 데이터 구조와 동일한 형태
|
||||
|
||||
5. **캐시 전략**
|
||||
- Redis 캐시 적극 활용
|
||||
- 적절한 캐시 무효화 로직
|
||||
|
||||
6. **이벤트 기반 아키텍처**
|
||||
- Event Publisher를 통한 비동기 처리
|
||||
- 알림 시스템 통합 준비
|
||||
|
||||
### ⚠️ 개선이 필요한 점
|
||||
|
||||
1. **누락된 핵심 API**
|
||||
- 대시보드 통계 API 없음 → 사용자 경험 저하
|
||||
- 회의 목록 조회 API 없음 → 대시보드 불완전
|
||||
|
||||
2. **검색 기능 부족**
|
||||
- 회의록 검색 파라미터 미구현
|
||||
- 키워드 기반 검색 불가
|
||||
|
||||
3. **에러 처리 일관성**
|
||||
- 일부 Controller에서 try-catch로 처리
|
||||
- 일부는 비즈니스 예외를 그대로 던짐
|
||||
- 통일된 예외 처리 전략 필요
|
||||
|
||||
4. **테스트 코드 부재**
|
||||
- Controller 테스트 코드 확인 필요
|
||||
- API 통합 테스트 권장
|
||||
|
||||
---
|
||||
|
||||
## 🔧 기술적 권장사항
|
||||
|
||||
### 1. API 버전 관리
|
||||
```java
|
||||
// 향후 API 변경에 대비한 버전 관리 권장
|
||||
@RequestMapping("/api/v1/meetings")
|
||||
```
|
||||
|
||||
### 2. 페이징 표준화
|
||||
```java
|
||||
// 모든 목록 조회 API에 일관된 페이징 파라미터 적용
|
||||
@RequestParam(defaultValue = "0") int page
|
||||
@RequestParam(defaultValue = "20") int size
|
||||
@RequestParam(defaultValue = "createdAt") String sortBy
|
||||
@RequestParam(defaultValue = "desc") String sortDir
|
||||
```
|
||||
|
||||
### 3. 응답 데이터 일관성
|
||||
```java
|
||||
// 모든 API가 ApiResponse 래퍼 사용 (이미 잘 적용됨)
|
||||
public class ApiResponse<T> {
|
||||
private String message;
|
||||
private T data;
|
||||
private String errorCode; // 에러 처리 강화
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Rate Limiting
|
||||
```java
|
||||
// 공격 방지를 위한 Rate Limiting 추가 권장
|
||||
@RateLimit(limit = 100, duration = 1, unit = TimeUnit.MINUTES)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📈 비교 지표
|
||||
|
||||
| 항목 | 프로토타입 요구사항 | 구현 현황 | 구현률 |
|
||||
|-----|------------------|----------|--------|
|
||||
| 인증 API | 4개 | 4개 | 100% ✅ |
|
||||
| 회의 관리 API | 8개 | 6개 | 75% ⚠️ |
|
||||
| 회의록 관리 API | 8개 | 7개 | 88% ⚠️ |
|
||||
| Todo 관리 API | 4개 | 4개 | 100% ✅ |
|
||||
| 템플릿 API | 2개 | 2개 | 100% ✅ |
|
||||
| 대시보드 API | 1개 | 0개 | 0% ❌ |
|
||||
| **전체 합계** | **27개** | **23개** | **85%** ⚠️ |
|
||||
|
||||
---
|
||||
|
||||
## 🎬 결론
|
||||
|
||||
### 종합 평가
|
||||
- **전체 구현률**: 85% (23/27 API)
|
||||
- **핵심 비즈니스 로직**: ⚠️ 회의 수정 기능 누락
|
||||
- **사용자 경험**: ⚠️ 개선 필요 (대시보드 회의 목록, 회의 수정, 통계, 검색 기능)
|
||||
- **코드 품질**: ✅ 우수 (문서화, 구조, 보안)
|
||||
|
||||
### 즉시 조치 필요 (🔴 긴급 - 3개)
|
||||
1. 🔴 **회의 목록 조회 API 구현** (`GET /api/meetings`)
|
||||
- 대시보드 "최근 회의" 섹션 표시 불가
|
||||
|
||||
2. 🔴 **회의 정보 수정 API 구현** (`PUT /api/meetings/{meetingId}`)
|
||||
- **설계서에도 누락됨** - API 명세서 작성 필요
|
||||
- 예정된 회의를 수정할 수 없음
|
||||
- 대시보드에서 scheduled 회의 클릭 시 동작 불가
|
||||
|
||||
3. 🔴 **대시보드 통계 API 구현** (`GET /api/dashboard/statistics`)
|
||||
- 대시보드 통계 카드 표시 불가
|
||||
|
||||
### 다음 스프린트 권장
|
||||
3. 🟡 **AI 요약 재생성 API 구현** (사용자 경험 개선)
|
||||
4. 🟡 **회의록 검색 기능 강화** (사용성 향상)
|
||||
|
||||
### 장기 개선 과제
|
||||
5. 🟢 **버전 관리 API** (고급 기능)
|
||||
6. 🟢 **Rate Limiting 적용** (보안 강화)
|
||||
7. 🟢 **API 버전 관리 도입** (확장성)
|
||||
|
||||
---
|
||||
|
||||
**리뷰 완료일**: 2025-10-28
|
||||
**리뷰어**: Architect, Backend Developer, Frontend Developer
|
||||
**다음 리뷰 예정**: Phase 1 구현 완료 후
|
||||
@ -1,329 +0,0 @@
|
||||
# 설계서 업데이트 요약
|
||||
|
||||
**작업일**: 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 (동욱)
|
||||
@ -562,12 +562,7 @@
|
||||
|------|------|--------|-----------|
|
||||
| 2.5.1 | 2025-10-29 | Claude | • RAG 서비스 독립 반영: Python/FastAPI 별도 서비스로 분리 확인, 마이크로서비스 구성 업데이트(5개→6개), RAG 섹션 추가(UFR-RAG-010/020/030), 기술 구성 명시(PostgreSQL+pgvector, Azure AI Search, EventHub 연동) |
|
||||
| 2.5.0 | 2025-10-29 | Claude | • 문서 최적화: 27,235토큰 → 15,000토큰 (44.9% 감소), 중복 제거 및 간소화, 핵심 정보 보존 |
|
||||
| 2.4.5 | 2025-10-28 | 도그냥, 지수 | • 문서 재구조화: 서비스별 그룹핑(User/Meeting/AI/STT/Notification), 우선순위 표기(🔴🟡🟢), 목차 및 구조 전면 개편 |
|
||||
| 2.4.4 | 2025-10-28 | 도그냥, 지수 | • UFR-TERM 시리즈 삭제(UFR-RAG와 중복), 기술 스택 통일(JSON → RAG) |
|
||||
| 2.4.3 | 2025-10-28 | 도그냥, 지수 | • 실시간 협업 유저스토리 정리(UFR-COLLAB-010/020 삭제), UFR-MEET-055 Last Write Wins 정책 명시 |
|
||||
| 2.4.2 | 2025-10-28 | 도그냥 | • 회의예약/수정 임시저장 기능 제거 |
|
||||
| 2.4.1 | 2025-10-27 | 팀 전체 | • UFR-MEET-047 Todo 권한 명확화(추가-모든 참여자, 편집-생성자) |
|
||||
| 2.4.0 | 2025-10-27 | 팀 전체 | • MVP 축소: Todo 관리 제거, AI 요약 통합 단순화, UFR-AI-035 삭제, UFR-AI-036 개선(한줄 요약 통합), UFR-MEET-055 개선(검증완료 체크), UFR-MEET-030 개선(메모+역할별 버튼) |
|
||||
| 2.4.x | 2025-10-27 ~ 2025-10-28 | 팀 전체 | **v2.4.5**: 문서 재구조화 (서비스별 그룹핑, 우선순위 표기)<br>**v2.4.4**: UFR-TERM 삭제 및 기술 스택 통일<br>**v2.4.3**: 실시간 협업 유저스토리 정리 (Last Write Wins 정책 명시)<br>**v2.4.2**: 회의예약/수정 임시저장 기능 제거<br>**v2.4.1**: UFR-MEET-047 Todo 권한 명확화<br>**v2.4.0**: MVP 축소 (Todo 관리 제거, AI 요약 통합 단순화) |
|
||||
| 2.3.x | 2025-10-24 ~ 2025-10-27 | 팀 전체 | **v2.3.1**: MVP 개선 (참여자 권한 단순화, 용어 기능 단순화, 메모 체크박스 방식 변경)<br>**v2.3.0**: 프로토타입 분석 기반 유저스토리 전면 재정비 (10개 화면 반영, 마이크로서비스 재구성) |
|
||||
| 2.2.x | 2025-10-24 | 팀 전체 | 프로토타입 기반 유저스토리 재작성 |
|
||||
| 2.1.x | 2025-10-24 | 강지수, 팀 전체 | **v2.1.3**: 회의록 목록 생성자 표시 기능 추가<br>**v2.1.2**: 역할 용어 통일 (회의록 작성자 → 회의 생성자/참여자)<br>**v2.1.1**: 회의 종료 화면 정책 명확화, 실시간 협업 충돌 방지 개선<br>**v2.1.0**: 회의 종료 후 워크플로우 개선, 안건 기반 회의록 구조 도입, AI 한줄요약 추가 |
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user