docs(subtitle): 자막 연동 검증과 배포 조건을 기록한다

2026-11-11 08:35:29 +09:00
parent 9c1c544e45
commit 4c1d876d5e
7 changed files with 623 additions and 0 deletions
@@ -0,0 +1,47 @@
+# 자막 Phase 1 Backend Gate 리뷰
+
+## 1. 리뷰 정보
+
+- 일자: 2026-11-10
+- 대상: `test` working tree의 신규 `v2.subtitle` 및 기존 업로드/상세/보안 연결
+- 기준: [PRD](../prd.md), [계획](../plan-task.md), [구현 보고](../implementation-report.md)
+- 리뷰어: 독립 Oracle (`ses_e3a1e039bffeXbBb7Nx0V7Hvk8`)
+- 상태: 회귀 수정 검증 완료, 로컬 backend APPROVE
+- 검토 제외: AWS/운영 DB/실음성/2시간 성능, 기존 전체 회귀 실행
+
+## 2. 근거와 판정
+
+부모 직접 실행의 실제 localhost HTTP 신규 테스트 13개가 0 failure/error/skip으로 통과했다.
+reviewer는 코드·신규 테스트·실행 로그·DDL을 읽었고 테스트를 재실행하지 않았다.
+저장/권한/언어별 결과/업로드/스키마는 부합 판정이나 HTTP 오류 경계 한 건으로 REQUEST_CHANGES다.
+
+| ID | 심각도 | 상태 | 내용 | 수정 Goal |
+|---|---|---|---|---|
+| REV-P1-001 | High | 수정 완료 / ADDRESSED | 자막 빈 body/저장 실패가 공통 advice에서 HTTP200으로 변환 | P1-R1 |
+
+## 3. REV-P1-001
+
+- `SubtitleExceptionHandler.kt`는 ResponseStatusException만 처리한다.
+- 기존 `common/SodaExceptionHandler.kt:73`과 `:94`는 DB 예외/일반 예외에 HTTP 상태 없이 ApiResponse.error를 반환한다.
+- 필수 body가 비면 strict parser 이전에 HttpMessageNotReadableException이 발생한다.
+- receipt 실패의 기존 새 테스트는 서비스 직접 호출 rollback만 검증하므로 HTTP200 문제를 포착하지 못했다.
+- 영향: 결과가 저장되지 않았어도 Lambda가 HTTP 성공으로 해석할 수 있다.
+
+최소 수정은 자막 controller에 한정된 advice에서 body 읽기 오류를 422, 예상하지 못한 서버 오류를
+민감정보 없는 500으로 반환하는 것이다. 기존 404/409/422 및 공유 API 동작을 보존한다.
+
+## 4. 수정 검증 조건
+
+1. 빈 callback/started 요청이 200이 되는 RED를 실제 HTTP로 확인한다.
+2. receipt 실패 callback이 200이 되는 RED와 전체 DB rollback을 확인한다.
+3. 수정 후 422/500 및 무부분반영을 검증하고 이번 작성 테스트만 재실행한다.
+4. 같은 reviewer가 수정 delta와 새 증거를 재검토한다.
+
+## 5. 판정 기록
+
+- 1차: REQUEST_CHANGES 1건. 부모가 공통 handler 코드를 직접 확인하고 `P1-R1`에 반영했다.
+- 2026-11-11 수정 검증: 전용 advice만 수정하고 신규 HTTP 두 사례의 RED/GREEN을 확인했다. 이후 신규 자막15개·bootJar·변경 lint가 통과했고, 부모 직접 두 HTTP 사례 재실행도 2/0/0/0으로 통과했다. 기존 공통 handler와 직접 서비스 rollback 테스트는 보존했다. reviewer session continuation 유실로 기존 판정과 delta만 전달한 단일 재검토를 진행 중이다.
+- 운영 배포는 코드 리뷰와 별개이며 [배포 게이트](../deployment-gates.md)의 차단 상태를 유지한다.
+- 최종 제한 delta 리뷰 (`ses_e39e64c42ffeCOGUZjgeM4P1jf`): **REV-P1-001 ADDRESSED / 로컬 backend APPROVE**.
+  전용 advice의 422/500, 기존 404/409/422 유지, 실제 HTTP 및 rollback RED/GREEN 증거를 확인했다.
+  수정 delta에서 신규 버그/blocker는 발견하지 못했다. 추가 코드 수정 불필요 판정이며 전체 리뷰 반복이나 기존 테스트 실행은 하지 않았다.