# Phase 10 코드 리뷰·QA — 2026-07-29

## 1. 리뷰 정보

| 항목 | 내용 |
|---|---|
| 리뷰 대상 | Phase 10 / OpenAPI 2.3.0 후속 vertical slices와 최종 Gate |
| 기준 commit 또는 working tree | `dd30e36323543e8f60e9983326503653e8001f12`; 리뷰 시작 시 tracked diff 36개, 전체 변경 169개 |
| 리뷰 일자 | 2026-07-29 |
| 리뷰어 | Codex |
| 기준 문서 | `prd.md`, `api-contract.openapi.json`, `plan-task.md` |
| 리뷰 상태 | 수정 완료 |

## 2. 리뷰 목적과 범위

### 목적

- `P10-T1~T7` 완료 체크와 실제 OpenAPI 2.3.0 구현·test·문서 상태가 일치하는지 확인한다.
- 기존 문서에 명시된 server fixture 차단은 새 결함과 구분한다.

### 포함 범위

- 코드·테스트: P10 변경 도메인, 공통 오류 fallback, 가격/file 회귀
- 문서: PRD 현재 계약 설명, Phase 10 Task/Gate/추적표
- 계약: OpenAPI version/path/operation/status와 주요 schema
- 수동 검증: 문서 metadata와 JSON 실제 집계 대조

### 제외 범위

- 개발 API 계정/fixture 자체 수정과 애플리케이션 결함 수정

## 3. 판정 기준

심각도는 `Blocker/High/Medium/Low`, 상태는 `확정/오탐/보류/수정 완료`를 사용했다.

## 4. 검토한 근거

### 문서와 코드

- 요구사항: `EXT-009~011`, `COMMUNITY-012`, PRD `11`, `13`, `14`
- 계약: OpenAPI `3.1.0`, document version `2.3.0`, 25 paths, 37 operations, status `implemented`
- 코드: `upload-audio-content.ts:66`, `upload-audio-content.ts:72`, `upload-audio-content.ts:82`
- 실패 테스트: `App.protected-errors.test.tsx`, `auth-api.test.ts`, `audio-upload.test.ts`
- 문서: `prd.md:9`, `prd.md:597`, `prd.md:598`, `prd.md:801`

### 실행 환경

```text
OS: macOS 26.0
Node: v24.12.0
npm: 11.7.0
Browser: Playwright Chromium/WebKit/mobile viewport projects
API mode: unit stub/MSW, VITE_API_MODE=mock
```

### 실행한 검증

| 명령 또는 검증 | 결과 | 핵심 증거 |
|---|---|---|
| OpenAPI `jq` 집계 | 성공 | version 2.3.0, 25 paths, 37 HTTP operations, status unique=`implemented` |
| `npm run test:run` | 실패 | 66 files / 290 tests, 6 failed·284 passed |
| focused domain unit | 성공 | shared 27, Character 23, Audio+Series 46, Community+FanTalk+Comments 52 tests passed |
| 7개 spec mock E2E | 실패 | 147 passed, 17 skipped, WebKit timeout 4건 |
| WebKit 실패 4건 단일 worker 재실행 | 성공 | 4 passed / 28.4초; 동일 시나리오 단독 재현 실패 |
| `npm run typecheck`, `npm run lint`, `git diff --check` | 성공 | 모두 exit 0 |
| `npm run build` | 성공 | 249 modules transformed, production build exit 0 |

## 5. 발견 사항 요약

| ID | 심각도 | 상태 | 제목 | 소유 Task | 후속 goal |
|---|---|---|---|---|---|
| `REV-P10-001` | Medium | 수정 완료 | 공통 오류 문구 migration이 불완전해 전체 unit Gate가 실패한다 | `P10-T7` | `P10-R1` |
| `REV-P10-002` | Low | 수정 완료 | PRD의 OpenAPI 집계와 Community metadata 설명이 2.0.0 상태다 | `P10-T1~T7` | `P10-R2` |

## 6. 발견 사항 상세

### REV-P10-001 — `EXT-011` migration과 전체 unit 회귀가 끝나지 않았다

- **심각도:** Medium
- **상태:** 수정 완료
- **관련 요구사항:** `EXT-011`
- **관련 계약:** 미정의 오류 기본 문구 `알 수 없는 오류가 발생했습니다.`
- **소유 Task:** 신규 `P10-R1`

**관찰 내용**

전체 unit에서 보호 route 2건과 login response 4건이 과거 `API 응답 형식이 올바르지 않습니다.`/feature fallback을 기대해 실패한다. 반대로 XHR upload의 2xx malformed JSON/envelope 구현과 test는 여전히 과거 문구를 사용한다.

**재현 또는 검증 절차**

1. `npm run test:run`을 실행한다.
2. `App.protected-errors.test.tsx` 2건, `auth-api.test.ts` 4건이 실제 공통 문구와 기대 문구 불일치로 실패한다.
3. `audio-upload.test.ts`의 malformed 2xx test는 과거 문구를 기대하며 통과한다.
4. 요구 결과는 fetch/XHR의 network·JSON·envelope·빈 message가 모두 공통 문구이고 전체 unit이 통과하는 것이다.

**영향**

`P10-T7`과 P10 Gate의 “미정의 오류 문구 불일치 0건” 완료 증거가 성립하지 않는다.

**권장 조치**

XHR success parse fallback을 `UNKNOWN_API_ERROR_MESSAGE`로 통일하고 보호 route/login/audio upload의 오래된 assertion을 요구사항 기준으로 갱신한다. focused 뒤 전체 unit과 error-mapping E2E를 실행한다.

**판정 기록**

- 2026-07-29 — 전체 unit 실패와 XHR 구현/test를 함께 대조해 확정.
- 2026-07-30 — XHR success parse fallback과 보호 route/login stale assertion을 `UNKNOWN_API_ERROR_MESSAGE` 기준으로 정렬했다. 전체 unit의 잔여 4건은 개별 통과·병렬 실패로 MSW handler 경합임을 확인해 Vitest file parallelism을 끄고 기본 `npm run test:run`으로 71 files / 335 tests 통과를 확인했다.

### REV-P10-002 — PRD의 현재 API 계약 설명이 실제 JSON과 다르다

- **심각도:** Low
- **상태:** 수정 완료
- **관련 요구사항:** 문서 단일 진실 원천, `COMMUNITY-012`
- **관련 계약:** OpenAPI metadata
- **소유 Task:** 신규 `P10-R2`

**관찰 내용**

PRD는 현재 계약을 version 2.0.0, 15 paths, 23 operations로 쓰고 최종 수정일도 2026-07-28이다. 실제 JSON은 2.3.0, 25 paths, 37 operations다. 성능 절에는 Community 종료 metadata가 아직 없다고 쓰지만 현재 계약·구현은 `totalCount/page/size/hasNext/items`를 사용한다.

**영향**

후속 작업자가 오래된 계약 범위로 구현·리뷰하거나 Community pagination을 미제공으로 오판할 수 있다.

**권장 조치**

현재 집계와 metadata 제공 상태, 최종 수정일만 정정하고 2.0.0 과거 결정·검증 기록은 당시 이력으로 보존한다.

**판정 기록**

- 2026-07-29 — `jq` 실제 집계와 PRD 현재형 문장을 대조해 확정.
- 2026-07-30 — PRD 현재 계약 문장을 OpenAPI 2.3.0, 25 paths, 37 operations와 Community pagination metadata 제공 상태로 정정했다. 2026-07-28 Decision Log의 과거 2.0.0 이력은 보존했다.

## 7. 확정 항목의 plan·goal 전환

- `REV-P10-001` → `P10-R1`
- `REV-P10-002` → `P10-R2`

## 8. 리뷰 종료 판정

| 판정 항목 | 결과 | 근거 |
|---|---|---|
| 리뷰 범위 전체 확인 | 충족 | OpenAPI·P10 code/test/docs 대조 |
| 후보 항목 판정 완료 | 충족 | 2건 수정 완료 |
| 확정 항목 plan 반영 | 충족 | `P10-R1`, `P10-R2` |
| 보류 항목 담당·재개 조건 | 충족 | server fixture는 기존 P10 Gate 상태 유지 |
| 검증 명령과 결과 기록 | 충족 | §4 |

**최종 결론:** 수정 검증 완료. 자동 Gate 정리는 완료됐고 실제 개발 API 수동 QA는 별도 대기한다.

**남은 항목:** 실제 개발 API credential·고정 fixture 확보 후 Series/FanTalk/파일 정책 수동 QA.

## 9. 수정 후 검증 기록

애플리케이션 수정은 아직 하지 않았다. 병렬 통합 실행에서 timeout 난
WebKit 4건을 `--project=webkit --workers=1 --last-failed`와 단일 worker로
재실행해 4 passed / 28.4초를 확인했다. 따라서 timeout 4건은 별도 기능
결함으로 확정하지 않았지만, 전체 mock E2E Gate의 최초 실행은 exit 0이
아니므로 `P10-GATE` 완료 근거로 사용하지 않는다. `npm run build`는 249
modules transformed와 exit 0으로 통과했다.

### P10-R1~P10-R3 및 Gate 정책 정정 — 2026-07-30

- `P10-R1`: fetch/XHR 미정의 오류 fallback을 `UNKNOWN_API_ERROR_MESSAGE`로 정렬하고 stale unit assertion을 갱신했다. 전체 unit은 이후 72 files / 354 tests passed까지 통과했다.
- `P10-R2`: PRD 현재 계약 설명을 OpenAPI 2.3.0, 25 paths, 37 operations와 Community pagination metadata 제공 상태로 정정했다.
- `P10-R3`: plan 상단, 구현 완료 정의, 현재 Phase 10 리뷰를 자동 Gate 완료와 실제 개발 API 수동 QA 대기 기준으로 정렬했다.
- Gate 정책: `P10-GATE` 자동 범위는 focused unit/mock E2E/server allowlist/typecheck/lint/build/diff 기준으로 정리하고, Series/FanTalk 실제 개발 API 검증은 credential·fixture 준비 후 수동 QA로 분리한다.