shared-dg05-coffeeQuokka/hgzero
1
0
Fork 0
mirror of https://github.com/hwanny1128/HGZero.git synced 2025-12-06 10:16:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: 회의 진행 실시간 기능 API 누락 분석 추가

Browse Source 
- 프로토타입 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 <noreply@anthropic.com>
This commit is contained in:
yabo0812 2025-10-28 11:24:12 +09:00
parent c030498948
commit 8ab563fe86
2 changed files with 272 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
claudedocs/API-누락-요약표.md Normal file
View File

@ -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 추천 채택 → 입력창에 시간 포함하여 추가 확인
- [ ] 용어 검색 → 키워드로 조직/회의 용어 찾기 확인
- [ ] 녹음 일시정지 → 타이머 정지 확인
- [ ] 녹음 재개 → 타이머 재개 확인
---
**문서 종료**

189
claudedocs/API리뷰-프로토타입vs구현.md
View File

@ -8,21 +8,39 @@
## 📋 요약 ## 📋 요약
### 전체 현황 ### 전체 현황 (v2.0 - 회의 진행 실시간 기능 추가 분석)
- **분석된 화면**: 9개 프로토타입 화면 - **분석된 화면**: 9개 프로토타입 화면
- **프로토타입 요구 API**: 27개 - **프로토타입 요구 API**: **34개** (v1: 27개 → v2: +7개)
- **구현된 API**: 23개 엔드포인트 - **구현된 API**: 27개 엔드포인트
- **완전 누락 API**: 4개 - **완전 누락 API**: **11개** (v1: 4개 → v2: +7개)
- **개선 필요 API**: 2개 - **개선 필요 API**: 2개
- **불필요한 API**: 0개 - **불필요한 API**: 0개
### 주요 발견사항 ### 주요 발견사항 (v2.0 업데이트)
1. ✅ **강점**: 핵심 비즈니스 로직 API는 모두 구현됨 1. ✅ **강점**: 핵심 비즈니스 로직 API는 모두 구현됨
2. 🔴 **치명적 누락**: `GET /api/meetings` (목록 조회) - 대시보드 "최근 회의" 표시 불가 2. 🔴 **치명적 누락 (기존)**:
3. 🔴 **치명적 누락**: `PUT/PATCH /api/meetings/{meetingId}` (회의 수정) - **예정된 회의 수정 불가** - `GET /api/meetings` (목록 조회) - 대시보드 "최근 회의" 표시 불가
4. 🔴 **치명적 누락**: `GET /api/dashboard/statistics` - 대시보드 통계 카드 표시 불가 - `PUT/PATCH /api/meetings/{meetingId}` (회의 수정) - 예정된 회의 수정 불가
5. 🟡 **기능 누락**: AI 요약 재생성 API 미구현 - `GET /api/dashboard/statistics` - 대시보드 통계 카드 표시 불가
6. 🟡 **개선 필요**: 회의록 검색/필터링 파라미터 추가 필요 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 | 구현 상태 | 구현 위치 | 비고 | | 화면 기능 | 요구 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 세션 생성 | | 회의 시작 | `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) | 실시간 협업 지원 | | 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) | 이메일 발송 포함 | | 참석자 초대 | `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" }
```
--- ---