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

# 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 구현 완료 후