From 8ab563fe8696bff5f3ccd311f840a80b6e45661a Mon Sep 17 00:00:00 2001 From: yabo0812 Date: Tue, 28 Oct 2025 11:24:12 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=ED=9A=8C=EC=9D=98=20=EC=A7=84=ED=96=89?= =?UTF-8?q?=20=EC=8B=A4=EC=8B=9C=EA=B0=84=20=EA=B8=B0=EB=8A=A5=20API=20?= =?UTF-8?q?=EB=88=84=EB=9D=BD=20=EB=B6=84=EC=84=9D=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 프로토타입 05-회의진행.html 4개 탭 상세 분석 - AI 메모, 용어사전, 녹음 제어 기능 누락 API 7개 식별 - 우선순위별 구현 권장 순서 제시 (P0/P1/P2) - 유저스토리 영향도 매핑 (US-06, US-07, US-08, US-09, US-10) 주요 누락 API: - PUT /api/meetings/{meetingId}/memo (메모 저장) - GET /api/ai/suggestions/realtime/{meetingId} (AI 실시간 추천) - POST /api/ai/suggestions/{suggestionId}/adopt (AI 추천 채택) - GET /api/ai/terms/search (용어 검색) - GET /api/ai/terms/{termName}/detail (용어 상세) - POST /api/stt/recordings/{recordingId}/pause (녹음 일시정지) - POST /api/stt/recordings/{recordingId}/resume (녹음 재개) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- claudedocs/API-누락-요약표.md | 95 +++++++++++++ claudedocs/API리뷰-프로토타입vs구현.md | 189 +++++++++++++++++++++++-- 2 files changed, 272 insertions(+), 12 deletions(-) create mode 100644 claudedocs/API-누락-요약표.md diff --git a/claudedocs/API-누락-요약표.md b/claudedocs/API-누락-요약표.md new file mode 100644 index 0000000..211b470 --- /dev/null +++ b/claudedocs/API-누락-요약표.md @@ -0,0 +1,95 @@ +# 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 추천 채택 → 입력창에 시간 포함하여 추가 확인 +- [ ] 용어 검색 → 키워드로 조직/회의 용어 찾기 확인 +- [ ] 녹음 일시정지 → 타이머 정지 확인 +- [ ] 녹음 재개 → 타이머 재개 확인 + +--- + +**문서 종료** diff --git a/claudedocs/API리뷰-프로토타입vs구현.md b/claudedocs/API리뷰-프로토타입vs구현.md index 2e0dfd4..7aa081d 100644 --- a/claudedocs/API리뷰-프로토타입vs구현.md +++ b/claudedocs/API리뷰-프로토타입vs구현.md @@ -8,21 +8,39 @@ ## 📋 요약 -### 전체 현황 +### 전체 현황 (v2.0 - 회의 진행 실시간 기능 추가 분석) - **분석된 화면**: 9개 프로토타입 화면 -- **프로토타입 요구 API**: 27개 -- **구현된 API**: 23개 엔드포인트 -- **완전 누락 API**: 4개 +- **프로토타입 요구 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` (목록 조회) - 대시보드 "최근 회의" 표시 불가 -3. 🔴 **치명적 누락**: `PUT/PATCH /api/meetings/{meetingId}` (회의 수정) - **예정된 회의 수정 불가** -4. 🔴 **치명적 누락**: `GET /api/dashboard/statistics` - 대시보드 통계 카드 표시 불가 -5. 🟡 **기능 누락**: AI 요약 재생성 API 미구현 -6. 🟡 **개선 필요**: 회의록 검색/필터링 파라미터 추가 필요 +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의 핵심/보조 기능 미동작 --- @@ -199,15 +217,162 @@ public class UpdateMeetingRequest { --- -### 5. 회의 진행 화면 (05-회의진행.html) +### 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" } +``` ---