# Phase 2 캐릭터 관리 리뷰

## 1. 리뷰 정보

| 항목 | 내용 |
|---|---|
| 리뷰 대상 | Phase 2 / AI 캐릭터 관리 vertical slice |
| 기준 commit 또는 working tree | `8197f90b` + staged Phase 2/3 changes |
| 리뷰 일자 | 2026-07-27 |
| 리뷰어 | Sisyphus |
| 기준 문서 | `docs/20260724_AI캐릭터_관리자_API/prd.md`, `docs/20260724_AI캐릭터_관리자_API/plan-task.md` |
| 리뷰 상태 | 판정 완료 |

## 2. 리뷰 목적과 범위

### 목적

- PRD Feature B와 Endpoint Contract Summary의 캐릭터 목록/상세/생성/수정/비활성화 계약을 현재 Phase 2 코드·테스트에 추적한다.
- 기존 완료 이력(`P2-H1`, `P2-H2`) 이후 남은 확정 finding을 `P2-T3`~`P2-T6` 소유 Goal에 연결한다.

### 포함 범위

- 코드: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/admin/aicharacter/character/*`, `ChatCharacterRepository.kt`
- 테스트: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/admin/aicharacter/character/*`
- 문서: PRD Feature B, API Expectations, plan Phase 2

### 제외 범위

- Phase 3 이후 기능, production code 수정, 신규 계약 변경

## 3. 판정 기준

| 심각도 | 기준 |
|---|---|
| Blocker | 보안·데이터 손실 위험, 핵심 흐름 불능, 완료 판정을 무효화하는 문제 |
| High | 확정 요구사항·API Contract 위반 또는 주요 회귀 |
| Medium | 제한된 조건에서 발생하는 기능·복구 문제 |
| Low | 유지보수성, 문서 정합성 문제 |

## 4. 검토한 근거

### 문서와 코드

- 요구사항: `prd.md` Feature B, API Expectations 184~189
- 계획: `plan-task.md` `P2-R1`, `P2-T3`~`P2-T6`, `REV-001`~`REV-003`, `REV-007`, `REV-008`
- 코드: `AiCharacterAdminCharacterController.kt:20`, `AiCharacterAdminCharacterDto.kt:3`, `AiCharacterAdminCharacterDto.kt:11`, `AiCharacterAdminCharacterFacade.kt:38`, `AiCharacterAdminCharacterFacade.kt:63`, `AiCharacterAdminCharacterMapper.kt:20`, `ChatCharacterRepository.kt:59`
- 테스트: `AiCharacterAdminCharacterControllerTest.kt:43`, `AiCharacterAdminCharacterControllerMutationTest.kt:50`, `LegacyChatCharacterAdminCharacterizationTest.kt:39`, `LegacyChatCharacterAdminCharacterControllerEventCharacterizationTest.kt:42`

### 실행 환경

```text
OS: macOS (darwin)
Java/Gradle: repository Gradle wrapper
환경 변수: test profile defaults, EmbeddedRedisInitializer, local stub external character API
```

### 실행한 검증

| 명령 또는 수동 검증 | 결과 | 핵심 증거 |
|---|---|---|
| `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.character.*'` | 성공 | `BUILD SUCCESSFUL in 51s` |
| 코드 추적 | 성공 | 목록 응답이 상세 DTO를 재사용하고 있음 확인 |

## 5. 발견 사항 요약

| ID | 심각도 | 상태 | 제목 | 소유 Task | 후속 goal |
|---|---|---|---|---|---|
| `REV-001` | Blocker | 확정 | 문자열 미매핑 경로가 detail binding에 잡힐 수 있음 | `P2-T6` | numeric path mapping 오류 계약 보완 |
| `REV-002` | High | 확정 | mutation request 계약이 Endpoint Contract Summary와 불일치 | `P2-T4`, `P2-T5` | canonical request 확정 후 RED/GREEN |
| `REV-003` | High | 확정 | 외부 API·S3·DB 실패 보상/원자성 증거 부족 | `P2-T4`, `P2-T5` | failure-order와 no-partial-state 보완 |
| `REV-007` | Medium | 확정 | 목록 응답이 상세 전용 field를 포함 | `P2-T3` | 목록 전용 DTO와 exact key 테스트 |
| `REV-008` | High | 확정 | 실제 endpoint별 인가·i18n·회귀 증거 부족 | `P2-T6` | endpoint matrix 보강 |

## 6. 발견 사항 상세

### REV-001 — 문자열 미매핑 경로 404 계약 보강 필요

- **심각도:** Blocker
- **상태:** 확정
- **관련 요구사항:** PRD API Expectations 174~180
- **관련 계약:** 신규 prefix 미매핑 경로 404, binding 오류 400 분리
- **소유 Task:** `P2-T6`

**관찰 내용**

`AiCharacterAdminCharacterController`는 `@GetMapping("/{characterId}")`에서 `Long` path variable을 직접 받는다. 문자열 segment가 이 mapping에 먼저 걸리면 404 fallback이 아니라 type mismatch 400으로 분류될 수 있으므로 `P2-T6`의 numeric path mapping RED/GREEN이 필요하다.

**근거**

- 코드: `AiCharacterAdminCharacterController.kt:29` `/{characterId}` mapping
- 코드: `AiCharacterAdminExceptionHandler.kt:67` `MethodArgumentTypeMismatchException`은 400으로 처리
- 문서: `plan-task.md` `P2-T6` RED 조건

**권장 조치**

numeric `characterId` path만 resource handler에 매핑되도록 최소 수정하고 KO/EN/JA·CORS 포함 404 회귀 테스트를 추가한다.

### REV-002 — mutation request 계약 불일치

- **심각도:** High
- **상태:** 확정
- **관련 요구사항:** PRD Feature B, API Expectations 185~189
- **관련 계약:** Endpoint Contract Summary의 생성/수정 multipart request
- **소유 Task:** `P2-T4`, `P2-T5`

**관찰 내용**

현재 생성 DTO는 `systemPrompt`를 필수로 요구하고 `externalCharacterId`, 생성 `isActive`를 받지 않는다. Endpoint Contract Summary의 축약 request와 Phase 2 후속 계획의 canonical request 확정 항목이 충돌하므로, 구현 수정 전에 기존 legacy/external API parity 기준으로 canonical request를 먼저 고정해야 한다.

**근거**

- 코드: `AiCharacterAdminCharacterDto.kt:27` 생성 DTO field set
- 코드: `AiCharacterAdminCharacterExternalApiClient.kt:22` 외부 API create body는 서버가 받은 field를 외부 생성 요청으로 전송
- 테스트: `AiCharacterAdminCharacterControllerMutationTest.kt:50` 생성 정상 케이스는 `systemPrompt` 포함 최소 JSON만 검증

**권장 조치**

`P2-T4`에서 문서 JSON 역직렬화·반영 테스트와 invalid `characterType` 테스트를 먼저 실패시킨 뒤, 확정 계약만 최소 구현한다.

### REV-003 — mutation 실패 원자성 증거 부족

- **심각도:** High
- **상태:** 확정
- **관련 요구사항:** PRD Feature B Edge Cases
- **관련 계약:** 외부 API·S3·DB 실패 시 부분 저장 방지
- **소유 Task:** `P2-T4`, `P2-T5`

**관찰 내용**

생성은 외부 API 호출 후 DB 생성, 선택 이미지 업로드, 원작 연결, 이벤트 발행 순서로 진행된다. 기존 테스트는 정상 생성, unreadable JSON, soft delete 보존만 검증하고 외부 API 실패, S3 실패, 존재하지 않는 원작, 동시 중복 이름에서 잔존 DB/S3/event 결과를 고정하지 않는다.

**근거**

- 코드: `AiCharacterAdminCharacterFacade.kt:63` 생성 transaction
- 코드: `AiCharacterAdminCharacterFacade.kt:71` 외부 API 결과로 DB 생성
- 코드: `AiCharacterAdminCharacterFacade.kt:96` 이미지 업로드 후 save
- 테스트: `AiCharacterAdminCharacterControllerMutationTest.kt:50` 실패 지점별 원자성 테스트 부재

**권장 조치**

`P2-T4`/`P2-T5`에서 실패 지점별 RED를 만들고, 외부 부작용 전 DB 참조 검증과 필요한 보상 경계만 추가한다.

### REV-007 — 목록 응답 field set 계약 위반

- **심각도:** Medium
- **상태:** 확정
- **관련 요구사항:** PRD API Expectations 189
- **관련 계약:** Endpoint Contract Summary의 목록 item과 상세 response 분리
- **소유 Task:** `P2-T3`

**관찰 내용**

목록 응답 `items`가 상세 응답 DTO `AiCharacterAdminCharacterResponse`를 그대로 사용한다. 그래서 목록 계약에 없는 `creatorProfileImageUrl`, `creatorIntroduce`, `updatedAtUtc`가 노출될 수 있다.

**근거**

- 코드: `AiCharacterAdminCharacterDto.kt:3` `AiCharacterAdminListResponse.items: List<AiCharacterAdminCharacterResponse>`
- 코드: `AiCharacterAdminCharacterDto.kt:18` 상세 전용 `creatorProfileImageUrl`
- 코드: `AiCharacterAdminCharacterDto.kt:19` 상세 전용 `creatorIntroduce`
- 코드: `AiCharacterAdminCharacterDto.kt:24` 상세 전용 `updatedAtUtc`
- 코드: `AiCharacterAdminCharacterFacade.kt:51` 목록에서 `characterMapper::toResponse` 사용
- 테스트: `AiCharacterAdminCharacterControllerTest.kt:43` 목록 exact key 검증 부재

**권장 조치**

목록 전용 item DTO를 추가하고 exact JSON key 테스트로 상세 전용 field 비노출을 고정한다.

### REV-008 — endpoint matrix와 완료 증거 부족

- **심각도:** High
- **상태:** 확정
- **관련 요구사항:** PRD Metrics 207~221
- **관련 계약:** endpoint별 ADMIN, 오류 i18n, legacy 회귀 증거
- **소유 Task:** `P2-T6`

**관찰 내용**

현재 Phase 2 focused test는 통과하지만 목록 anonymous/admin smoke와 일부 binding만 검증한다. 목록·상세·생성·수정 각각의 JWT role × DB role, stale claim, domain/client/server 오류의 exact status/key/KO·EN·JA matrix는 아직 Phase 2 endpoint 기준으로 충분히 고정되어 있지 않다.

**근거**

- 테스트: `AiCharacterAdminCharacterControllerTest.kt:139` 목록 endpoint 인가 smoke만 존재
- 테스트: `AiCharacterAdminCharacterControllerMutationTest.kt:89` unreadable create request만 400 검증
- 문서: `plan-task.md` `P2-T6` RED/GREEN 조건

**권장 조치**

`P2-T6`에서 실제 Phase 2 endpoint matrix와 legacy/public 회귀를 focused 명령으로 보강한다.

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

확정 항목은 기존 `plan-task.md`의 `P2-T3`~`P2-T6`에 이미 소유 Goal로 연결되어 있다. 신규 회귀 수정 Task는 만들지 않는다.

## 8. 리뷰 종료 판정

| 판정 항목 | 결과 | 근거 |
|---|---|---|
| 리뷰 범위 전체 확인 | 충족 | PRD Feature B, Endpoint Contract Summary, Phase 2 production/test 대조 |
| 후보 항목 판정 완료 | 충족 | `REV-001`~`REV-003`, `REV-007`, `REV-008` 확정 |
| 확정 항목 plan 반영 | 충족 | 기존 `P2-T3`~`P2-T6`에 연결됨 |
| 보류 항목의 담당·재개 조건 기록 | 해당 없음 | 보류 없음 |
| 검증 명령과 결과 기록 | 충족 | focused test `BUILD SUCCESSFUL in 51s` |

**최종 결론:** 수정 goal 필요

**남은 항목:** `P2-T3`부터 직렬 실행한다.

## 9. 수정 후 검증 기록

### 1차 수정 검증 — 2026-07-27

- 무엇을: `P2-T3`에서 `REV-007`의 목록 응답 field set을 수정했다.
- 왜: 목록 item이 상세 DTO를 재사용해 `creatorProfileImageUrl`, `creatorIntroduce`, `updatedAtUtc`를 노출했기 때문이다.
- 어떻게:
  - `./gradlew test --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.character.AiCharacterAdminCharacterControllerTest` — RED는 line 66 실패, GREEN은 `BUILD SUCCESSFUL`.
  - `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.character.*'` — `BUILD SUCCESSFUL`.
  - `./gradlew ktlintCheck` — `BUILD SUCCESSFUL`.
- 남은 항목: `P2-T4`, `P2-T5`, `P2-T6`.

### 2차 수정 검증 — 2026-07-27

- 무엇을: `P2-T4`에서 `REV-002`, `REV-003`, `REV-007` 중 생성 흐름을 보완했다.
- 왜: 생성 request의 서버 소유 field와 존재하지 않는 원작 검증이 외부 부작용 전에 고정되어야 했기 때문이다.
- 어떻게:
  - `./gradlew test --rerun-tasks --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.character.AiCharacterAdminCharacterControllerMutationTest --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.character.LegacyChatCharacterAdminCharacterizationTest --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.character.LegacyChatCharacterAdminCharacterControllerEventCharacterizationTest` — `BUILD SUCCESSFUL`.
  - `./gradlew ktlintCheck --rerun-tasks` — `BUILD SUCCESSFUL`.
- 남은 항목: `P2-T5`, `P2-T6`, `P2-GATE`.

### 3차 수정 검증 — 2026-07-27

- 무엇을: `P2-T5`에서 `REV-002`, `REV-003`, `REV-007`의 캐릭터 수정·비활성화 흐름을 보완했다.
- 왜: `externalCharacterId` 입력, `isActive=false`와 일반 수정/image 혼합, 원작·외부/S3/DB 실패 경계와 flush 전 `updatedAtUtc`가 확정 계약과 달랐기 때문이다.
- 어떻게:
  - `./gradlew test --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.character.AiCharacterAdminCharacterControllerMutationTest --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.character.LegacyChatCharacterAdminCharacterizationTest --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.character.LegacyChatCharacterAdminCharacterControllerEventCharacterizationTest` — `BUILD SUCCESSFUL in 1m 16s`.
  - `./gradlew ktlintCheck` — `BUILD SUCCESSFUL in 17s`.
- 남은 항목: `P2-T6`, `P2-GATE`.

### 4차 수정 검증 — 2026-07-27

- 무엇을: `P2-T6`에서 `REV-001`의 문자열 path 404 계약과 `REV-008`의 실제 Phase 2 endpoint 보안·오류·CORS 증거를 보완했다.
- 왜: `/api/v2/admin/ai-characters/unmapped-path`가 detail `Long` binding에 매칭되어 KO/EN/JA·허용 Origin CORS 4건 모두 404 대신 400을 반환했고, 목록·상세·생성·수정의 실제 경로 matrix가 부족했기 때문이다.
- 어떻게:
  - RED: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.character.*' --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.AiCharacterAdminAuthorizationTest --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.AiCharacterAdminErrorContractTest`를 실행해 전체 146건 중 위 4건만 404 기대 대비 400으로 실패함을 확인했다.
  - GREEN: `AiCharacterAdminCharacterController`의 GET/PUT `characterId` path를 `[0-9]+`로 제한하고, 실제 목록 binding·상세 target·생성/수정 multipart KO/EN/JA, 네 endpoint non-ADMIN, detail preflight 테스트를 추가했다.
  - 회귀: 같은 focused 명령은 `BUILD SUCCESSFUL in 1m 26s`, `./gradlew ktlintCheck`는 `BUILD SUCCESSFUL in 34s`였다.
- 결과: `REV-001`, `REV-008`의 P2-T6 범위는 종료했다. 공통 Phase 1 handler, legacy/public contract, Phase 3 이후 코드는 변경하지 않았고, `P2-GATE`는 별도 Goal로 남겼다.

## 10. 2차 리뷰 및 검증 — 2026-07-27

### 리뷰 정보와 실행 결과

- 기준 working tree: Phase 2·3 staged/unstaged 변경 전체
- 리뷰 상태: 판정 완료, 후속 수정 goal 필요
- 검토 범위: PRD Feature B, Endpoint Contract Summary, `P2-T3`~`P2-GATE`, character production/test와 공통 authorization/error test
- fresh 검증:
  - `./gradlew test --rerun-tasks --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.character.*' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.content.*' --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.AiCharacterAdminAuthorizationTest --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.AiCharacterAdminErrorContractTest` — `BUILD SUCCESSFUL in 9m 23s`, 관련 XML 14개 합계 199건, failure/error/skipped 0.
  - `./gradlew ktlintCheck --rerun-tasks` — `BUILD SUCCESSFUL in 27s`, 7개 task 실행.

### 추가 발견 사항 요약

| ID | 심각도 | 상태 | 제목 | 소유 Task | 후속 goal |
|---|---|---|---|---|---|
| `REV-009` | Medium | 확정 | Phase 2 실제 endpoint별 보안·오류·실패 경계 증거가 Gate 기록보다 좁음 | `Task 2.8` | `P2-R2` |

### REV-009 — Phase 2 실제 endpoint별 완료 증거 보강 필요

- **심각도:** Medium
- **상태:** 확정
- **관련 요구사항:** PRD Metrics 207~221, Acceptance Criteria 225~254
- **관련 계약:** 실제 endpoint별 JWT role × 현재 DB role, stale claim, CORS, KO/EN/JA 오류와 실패 후 상태
- **소유 Task:** `Task 2.8`, `P2-R2`

**관찰 내용**

현재 작성된 character와 공통 authorization/error test 146건은 모두 통과한다. 다만 `P2-T6`과 `P2-GATE`는 목록·상세·생성·수정 각각의 stale ADMIN claim, 허용·거부 Origin, domain/client/server 오류와 외부/S3/DB 실패 경계를 모두 고정했다고 기록했으나 실제 소유 테스트는 네 endpoint의 non-ADMIN JWT, 상세 GET의 허용 Origin, 일부 binding/multipart KO/EN/JA와 S3 실패를 각각 분리해 검증한다. 실제 네 endpoint의 stale claim과 허용·거부 Origin 전체, 외부/API·S3·DB 실패의 exact envelope 및 side-effect 결과를 한 매트릭스로 재현할 직접 증거가 없다.

**근거**

- 테스트: `AiCharacterAdminCharacterControllerTest.kt:175`는 네 endpoint의 non-ADMIN JWT만 순회하며 stale ADMIN claim을 포함하지 않는다.
- 테스트: `AiCharacterAdminCharacterControllerTest.kt:195`는 상세 GET의 허용 Origin만 확인하고 거부 Origin과 POST/PUT preflight를 직접 확인하지 않는다.
- 테스트: `AiCharacterAdminCharacterControllerMutationTest.kt:340` 이후는 외부 API/S3 실패의 DB 결과를 확인하지만 실제 endpoint별 KO/EN/JA와 DB 실패 경계를 모두 고정하지 않는다.
- 문서: `plan-task.md`의 `P2-T6`·`P2-GATE`는 위 매트릭스와 외부/S3/DB 보상에 미결정 항목이 없다고 완료 처리했다.

**영향**

공통 security/error 계층 때문에 현재 production 결함은 재현되지 않았지만, 실제 character mapping이나 facade 호출 순서가 바뀌어도 공통 fixture test만 통과해 Phase 2 Gate가 놓칠 수 있다.

**권장 조치**

`P2-R2`에서 네 실제 endpoint의 JWT/DB role·stale claim과 허용/거부 CORS, 대표 binding/domain/client/server 실패의 exact envelope 및 DB/S3/external/event 결과를 non-vacuous test로 보강한다. 현재 동작이 계약을 이미 만족하면 production code를 수정하지 않고 test와 검증 기록만 추가한다.

**판정 기록**

- 2026-07-27 — fresh 199건과 lint는 모두 통과했으나 계획 체크리스트와 실제 test method를 대조해 검증 증거 누락을 확정했다.

### plan·goal 전환

`plan-task.md` Phase 2에 `Task 2.8` / `P2-R2`와 별도 후속 Gate `P2-R2-GATE`를 추가한다. 기존 `P2-T3`~`P2-GATE` 완료 이력은 변경하지 않는다.

### 2차 리뷰 종료 판정

| 판정 항목 | 결과 | 근거 |
|---|---|---|
| 리뷰 범위 전체 확인 | 충족 | PRD·계획·production·test 재대조 |
| 후보 항목 판정 완료 | 충족 | `REV-009` 확정 |
| 확정 항목 plan 반영 | 충족 | `Task 2.8`, `P2-R2`, `P2-R2-GATE` |
| 검증 명령과 결과 기록 | 충족 | fresh targeted 199건, lint 성공 |

**최종 결론:** 수정 goal 필요

**남은 항목:** `P2-R2` 실행 후 `P2-R2-GATE`에서 Phase 2 후속 리뷰를 종결한다.

## 11. 3차 수정 검증 — 2026-07-27

- 무엇을: `P2-R2`에서 `REV-009`의 실제 character endpoint별 보안·오류·실패 경계 증거를 보강했다.
- 왜: 기존 `P2-T6`/`P2-GATE` 기록이 네 실제 endpoint의 stale ADMIN claim, 허용·거부 Origin preflight, mutation 실패의 KO/EN/JA envelope를 직접 매트릭스로 고정했다는 증거가 부족했기 때문이다.
- 어떻게:
  - `AiCharacterAdminCharacterControllerTest`에 목록·상세·생성·수정 실제 경로의 stale ADMIN claim 403과 allow/deny Origin preflight를 추가했다.
  - `AiCharacterAdminCharacterControllerMutationTest`의 external API 실패, 생성 S3 실패, 수정 S3 실패를 KO/EN/JA exact message와 DB/S3/external 잔존 상태 단언으로 확장했다.
  - `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.character.*' --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.AiCharacterAdminAuthorizationTest --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.AiCharacterAdminErrorContractTest` — `BUILD SUCCESSFUL in 1m 47s`.
- 결과: production code 변경 없이 `REV-009`의 직접 증거 보강이 완료됐다. `P2-R2-GATE`를 종료하고 Phase 3 후속 보완으로 진행한다.

### 3차 리뷰 종료 판정

| 판정 항목 | 결과 | 근거 |
|---|---|---|
| `REV-009` 처리 | 충족 | 실제 endpoint stale claim/CORS와 failure envelope·side-effect test 추가 |
| focused 회귀 | 충족 | character/common focused 명령 성공 |
| 범위 준수 | 충족 | Phase 3 production, Phase 4 이후 작업 없음 |

**최종 결론:** Phase 2 후속 리뷰 종결

## 12. 4차 재리뷰 및 검증 — 2026-07-27

### 리뷰 정보와 실행 결과

- 기준 working tree: `P2-R2` 반영 후 staged/unstaged Phase 2 변경
- 리뷰 상태: 판정 완료, 추가 수정 goal 필요
- fresh 검증:
  - `./gradlew test --rerun-tasks --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.character.*' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.content.*' --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.AiCharacterAdminAuthorizationTest --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.AiCharacterAdminErrorContractTest` — `BUILD SUCCESSFUL in 9m 44s`, 관련 XML 14개 합계 228건, failure/error/skipped 0.
  - `./gradlew ktlintCheck --rerun-tasks` — `BUILD SUCCESSFUL in 41s`, 7개 task 실행.

### 추가 발견 사항 요약

| ID | 심각도 | 상태 | 제목 | 소유 Task | 후속 goal |
|---|---|---|---|---|---|
| `REV-012` | Medium | 처리 완료 | DB·event 실패 후 내부·외부 부작용 직접 증거가 여전히 없음 | `Task 2.9` | `P2-R3` |

### REV-012 — character DB·event 실패 경계 증거 보강 필요

- **심각도:** Medium
- **상태:** 처리 완료
- **관련 요구사항:** PRD Metrics 207~221, Acceptance Criteria 225~254
- **관련 계약:** 생성·수정 실패 뒤 DB/creatorMember/originalWork/event rollback과 이미 발생한 external/S3 비보상 결과
- **소유 Task:** `Task 2.9`, `P2-R3`

**관찰 내용**

`P2-R2` 반영으로 네 실제 endpoint의 stale ADMIN claim과 허용·거부 Origin, external API·생성 S3·수정 S3 실패의 KO/EN/JA message는 직접 고정됐다. 그러나 완료 처리한 `Task 2.8`의 failure checklist에는 DB 실패와 creatorMember/originalWork/event 결과까지 포함되어 있다. 현재 mutation test는 DB save/flush 또는 event publish 실패를 주입하지 않으며, 실패 test의 `@DisplayName`에 event 미발행을 적었지만 publisher 호출을 직접 단언하지 않는다.

**근거**

- 테스트: `AiCharacterAdminCharacterControllerMutationTest.kt:346`~`408`은 external API와 첫 S3 실패를 확인하지만 DB/event 실패를 재현하지 않는다.
- 테스트: `AiCharacterAdminCharacterControllerMutationTest.kt:143`, `676`의 publisher mock은 정상 생성·수정 event 확인에만 사용된다.
- 코드: `AiCharacterAdminCharacterFacade.create`와 `update`는 external/S3/DB 처리 뒤 event를 발행하므로 DB 또는 event 실패 시 transaction rollback과 이미 발생한 외부 결과를 별도로 관찰해야 한다.
- 문서: `plan-task.md`의 `Task 2.8`은 DB 실패와 DB/creatorMember/originalWork/S3/external/event 결과를 모두 직접 단언했다고 완료 처리했다.

**영향**

현재 테스트는 모두 통과하지만 persistence 또는 event 지점에서 실패했을 때 내부 row가 롤백되고 external/S3 결과만 남는 기존 경계가 바뀌어도 `P2-R2-GATE`가 이를 감지하지 못한다.

**권장 조치**

`P2-R3`에서 실제 transaction을 거치는 생성·수정의 DB flush/save와 event publish 실패를 재현하고 ChatCharacter·creatorMember·originalWork·event 및 external/S3 결과를 직접 단언한다. 기존 비보상 경계와 일치하면 production code를 변경하지 않는다.

**처리 결과**

`AiCharacterAdminCharacterControllerMutationTest`에 external/S3 실패 KO/EN/JA matrix와 생성·수정 event publish 실패 특성화를 추가했다. production code 변경 없이 mutation focused 명령은 `BUILD SUCCESSFUL in 1m 1s`, 최종 `ktlintCheck`는 `BUILD SUCCESSFUL in 17s`였다.

### plan·goal 전환

`plan-task.md` Phase 2에 `Task 2.9` / `P2-R3`와 `P2-R3-GATE`를 추가한다. 기존 `Task 2.8`과 `P2-R2-GATE` 완료 이력은 변경하지 않는다.

### 4차 리뷰 종료 판정

| 판정 항목 | 결과 | 근거 |
|---|---|---|
| 적용된 stale claim/CORS/i18n 보강 | 충족 | 실제 endpoint 및 external/S3 failure test 추가 |
| DB/event 실패 경계 직접 증거 | 충족 | event failure injection과 external/S3/DB/event 단언 추가 |
| 확정 항목 plan 반영 | 충족 | `Task 2.9`, `P2-R3`, `P2-R3-GATE` |
| fresh 검증 | 충족 | targeted 228건, lint 성공 |

**최종 결론:** Phase 2 4차 리뷰 종결

**남은 항목:** 없음. Phase 3 4차 리뷰 보완으로 진행한다.

## 13. 5차 재리뷰 및 판정 — 2026-07-27

### 리뷰 정보와 실행 결과

- 기준 working tree: `P2-R3`와 `P3-R4` 반영 후 staged/unstaged Phase 2·3 변경
- 리뷰 상태: 판정 완료, 추가 수정 goal 필요
- 검토 범위: `REV-012` 처리 결과, character mutation의 transaction/DB/event failure evidence
- fresh 검증:
  - `./gradlew test --rerun-tasks --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.character.AiCharacterAdminCharacterControllerMutationTest --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.content.AiCharacterAdminAudioContentCreateTest --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.content.AiCharacterAdminAudioContentOwnershipTest` — `BUILD SUCCESSFUL in 7m 50s`, 세 XML 합계 79건, failure/error/skipped 0.
  - `./gradlew ktlintCheck --rerun-tasks` — `BUILD SUCCESSFUL in 28s`, 7개 task 실행.
  - `git diff --check` — 출력 없음.

### 추가 발견 사항 요약

| ID | 심각도 | 상태 | 제목 | 소유 Task | 후속 goal |
|---|---|---|---|---|---|
| `REV-015` | Medium | 처리 완료 | character DB·event 실패 경계가 실제 transaction과 내부 rollback을 직접 검증하지 않음 | `Task 2.10` | `P2-R4-GATE` |

### REV-015 — character DB·event 실패의 실제 transaction 증거 보강 필요

- **심각도:** Medium
- **상태:** 처리 완료
- **관련 요구사항:** PRD Metrics 207~221, Acceptance Criteria 225~254
- **관련 계약:** 생성·수정의 persistence/event 실패 뒤 ChatCharacter·creatorMember·originalWork rollback과 external/S3 비보상 결과
- **소유 Task:** `Task 2.10`, `P2-R4`

**관찰 내용**

`P2-R3`에서 추가한 생성·수정 event 실패 테스트는 `AiCharacterAdminCharacterFacade`를 테스트 안에서 직접 생성하고 예외를 잡는다. 따라서 production의 Spring transaction proxy를 통과하지 않으며, 테스트는 external API 호출 횟수와 publisher 호출만 확인하고 ChatCharacter·creatorMember·originalWork의 rollback 결과를 조회하지 않는다. 계획이 완료 조건으로 둔 DB save/flush 실패 주입도 없다.

**근거**

- 테스트: `AiCharacterAdminCharacterControllerMutationTest.kt:415`의 생성 event 실패는 `createFacade(publisher).create(...)`를 직접 호출하고 DB row 부재를 단언하지 않는다.
- 테스트: `AiCharacterAdminCharacterControllerMutationTest.kt:696`의 수정 event 실패도 직접 facade를 호출하며 수정 전 DB 상태 유지 여부를 단언하지 않는다.
- 테스트: `AiCharacterAdminCharacterControllerMutationTest.kt:836`의 `createFacade`는 Spring bean이 아닌 일반 객체를 반환한다.
- 문서: `plan-task.md:1264`~`1266`은 생성·수정의 DB flush/save와 event publish 실패를 실제 transaction에서 재현하고 내부·외부 결과를 직접 단언했다고 완료 처리한다.
- 리뷰: 이 문서 4차 종료 판정은 event failure injection과 external/S3/DB/event 단언이 충족됐다고 기록한다.

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

1. 위 두 event 실패 test와 `createFacade` helper를 확인한다.
2. 각 test가 actual multipart endpoint를 호출하는지, exception 후 DB를 재조회하는지 확인한다.
3. 현재 결과는 직접 facade 호출과 mock interaction 확인뿐이며 DB save/flush failure injection과 내부 rollback 조회가 없다.
4. production Spring transaction을 통과하는 actual endpoint 또는 실제 transaction proxy 호출과 transaction 밖 DB 재조회가 필요하다.

**영향**

현재 focused test는 통과하지만 facade의 `@Transactional` 경계가 제거되거나 event/flush 실패 뒤 일부 내부 row가 남는 회귀가 발생해도 `P2-R3-GATE`가 이를 검출하지 못한다.

**권장 조치**

`P2-R4`에서 test transaction을 비활성화한 actual POST/PUT endpoint로 event 실패를 주입하고, transaction 종료 뒤 ChatCharacter·creatorMember·originalWork와 event 결과를 재조회한다. update의 명시적 `chatCharacterRepository.flush()` 실패도 실제 transaction에서 주입해 외부 호출·S3·DB 잔존 결과를 고정한다. 기존 비보상 계약과 일치하면 production code는 변경하지 않는다.

**판정 기록**

- 2026-07-27 — fresh 79건과 lint는 통과했지만 테스트 호출 경계와 assertion을 대조해 `REV-012`의 완료 증거가 충족되지 않았음을 확정했다.

### plan·goal 전환

`plan-task.md` Phase 2에 `Task 2.10` / `P2-R4`와 `P2-R4-GATE`를 추가한다. 기존 `Task 2.9`와 `P2-R3-GATE` 완료 이력은 변경하지 않는다.

### 5차 리뷰 종료 판정

| 판정 항목 | 결과 | 근거 |
|---|---|---|
| 리뷰 범위 전체 확인 | 충족 | production transaction 경계와 새 event failure test 대조 |
| 후보 항목 판정 완료 | 충족 | `REV-015` 확정 |
| 확정 항목 plan 반영 | 충족 | `Task 2.10`, `P2-R4`, `P2-R4-GATE` |
| fresh 검증 | 충족 | 관련 79건과 lint 성공, diff check 이상 없음 |

**최종 결론:** 수정 goal 필요

**남은 항목:** `P2-R4` 실행 후 `P2-R4-GATE`에서 Phase 2 후속 리뷰를 다시 판정한다.

### P2-R4 실행 기록

- **REV-015 상태:** 처리 완료.
- `AiCharacterAdminCharacterControllerMutationTest`는 `@Transactional(propagation = Propagation.NOT_SUPPORTED)` actual POST/PUT로 event publish 실패와 repository `save`/`flush()` 실패를 주입한다.
- POST 실패 뒤 별도 `TransactionTemplate`에서 ChatCharacter, creatorMember, originalWork assignment이 없음을 확인하고, PUT 실패 뒤 character, creatorMember, originalWork의 기존 필드가 유지됨을 확인한다. 모든 대표 KO/EN/JA 응답은 500 `common.error.unknown` message이며 external 호출은 1회, image 없는 S3 호출은 없다.
- direct `createFacade` event failure test는 endpoint 증거로 대체했고, 남은 direct facade test는 event payload assertion 용도임을 명시했다.
- 초기 RED는 `@MockBean`만으로 이미 생성된 facade field가 교체되지 않아 event listener가 실행되고 200이 반환된 것으로 확인했다. 실제 Spring facade proxy target에 같은 mock을 주입한 뒤 production code 변경 없이 통과했다.
- fresh 검증: mutation/error focused `BUILD SUCCESSFUL in 1m 8s`, character/auth/error 영향 범위 `BUILD SUCCESSFUL in 1m 59s`, `./gradlew ktlintCheck` `BUILD SUCCESSFUL in 42s`.

### P2-R4-GATE 종료 판정

- 무엇을: `REV-015` actual transaction·rollback 증거 보강을 최종 판정했다.
- 왜: `P2-R4` 구현 후 Phase 2 5차 리뷰를 종결하기 위해서다.
- 어떻게: character mutation/error와 content create/controller/ownership focused 명령 및 `git diff --check`를 fresh 실행했다.
- 결과: focused 명령은 `BUILD SUCCESSFUL in 52s`, `git diff --check`는 출력이 없었다.

| 판정 항목 | 결과 | 근거 |
|---|---|---|
| `REV-015` 처리 | 충족 | actual POST/PUT event/save/flush 실패와 transaction 종료 뒤 DB 상태 재조회 추가 |
| focused 회귀 | 충족 | 5차 Gate focused 명령 성공 |
| 범위 준수 | 충족 | Phase 3 이후 production·Phase 4 변경 없음 |

**최종 결론:** Phase 2 5차 리뷰 종결

**남은 항목:** 없음. Phase 3 5차 Gate로 진행한다.

## 14. 6차 재리뷰 및 판정 — 2026-07-28

### 리뷰 정보와 실행 결과

- 기준 working tree: `P2-R4-GATE`, `P3-R4-GATE` 반영 후 staged/unstaged Phase 2·3 변경
- 리뷰 상태: 판정 완료, 추가 수정 goal 필요
- 검토 범위: Endpoint Contract Summary의 캐릭터 생성 예시와 `DEC-P2-T4-001`, production DTO/facade 및 actual endpoint test
- fresh 검증:
  - Phase 2·3 5차 Gate focused 5개 test class를 `--rerun-tasks`로 실행해 XML 합계 216건, failure/error/skipped 0과 `BUILD SUCCESSFUL in 4m 16s`를 확인했다.
  - `./gradlew ktlintCheck --rerun-tasks` — `BUILD SUCCESSFUL in 17s`, 7개 task 실행.
  - staged/unstaged `git diff --check` — 출력 없음.

### 추가 발견 사항 요약

| ID | 심각도 | 상태 | 제목 | 소유 Task | 후속 goal |
|---|---|---|---|---|---|
| `REV-018` | High | 확정 | 캐릭터 생성 Endpoint Contract Summary가 확정 request 계약과 불일치 | `Task 2.11` | `P2-R5` |

### REV-018 — 캐릭터 생성 Endpoint Contract Summary 불일치

- **심각도:** High
- **상태:** 확정
- **관련 요구사항:** PRD Feature B, Endpoint Contract Summary, `DEC-P2-T4-001`
- **관련 계약:** POST 생성은 필수 `systemPrompt`를 받고 `externalCharacterId`와 `isActive`는 client request로 받지 않는다.
- **소유 Task:** `Task 2.11`, `P2-R5`

**관찰 내용**

Endpoint Contract Summary의 POST 생성 예시는 필수 `systemPrompt`를 누락하고, 외부 API response 전용
`externalCharacterId`와 서버가 `true`로 생성하는 `isActive`를 request에 포함한다. 같은 문서의 `DEC-P2-T4-001`과
production DTO/facade는 반대 계약을 사용한다.

**근거**

- 문서: `plan-task.md:189`~`196`의 생성 JSON은 `systemPrompt`가 없고 `externalCharacterId`, `isActive`를 포함한다.
- 결정: `plan-task.md:2831`의 `DEC-P2-T4-001`은 `systemPrompt` 필수, `externalCharacterId` response 전용,
  `isActive` 서버 소유를 확정한다.
- 코드: `AiCharacterAdminCharacterDto.kt:40`~`45`는 `systemPrompt`를 non-null로 받고 두 서버 소유 field를 명시적으로
  수신해 facade에서 거부할 수 있게 한다.
- 코드: `AiCharacterAdminCharacterFacade.kt:64`~`68`은 두 서버 소유 field가 존재하면 400으로 거부한다.
- 테스트: `AiCharacterAdminCharacterControllerMutationTest.kt:103`~`141`은 `systemPrompt`를 포함한 정상 생성과
  response의 외부 ID·활성 상태를 확인하고, 같은 파일 `:239` 이후는 서버 소유 field 입력을 거부한다.

**영향**

Endpoint Contract Summary를 source of truth로 사용하는 client는 제공 예시 그대로 요청하면 400을 받는다. production 동작은
확정 결정과 일치하지만 공개 request 예시가 반대라 Phase 2 API 계약 완료 판정이 문서 수준에서 성립하지 않는다.

**권장 조치**

`P2-R5`에서 생성 예시에 `systemPrompt`를 추가하고 `externalCharacterId`, `isActive`를 제거한다. production 변경 없이 기존
정상 생성·서버 소유 field 거부 actual endpoint test와 문서 문자열 검사를 실행해 예시와 `DEC-P2-T4-001`을 동기화한다.

### plan·goal 전환

`plan-task.md` Phase 2에 `Task 2.11` / `P2-R5`와 `P2-R5-GATE`를 추가한다. 기존 `Task 2.10`과
`P2-R4-GATE` 완료 이력은 변경하지 않는다.

### 6차 리뷰 종료 판정

| 판정 항목 | 결과 | 근거 |
|---|---|---|
| 리뷰 범위 전체 확인 | 충족 | Endpoint Contract Summary·Decision Log·production·actual endpoint test 대조 |
| 후보 항목 판정 완료 | 충족 | `REV-018` 확정 |
| 확정 항목 plan 반영 | 충족 | `Task 2.11`, `P2-R5`, `P2-R5-GATE` |
| fresh 검증 | 충족 | 관련 216건과 lint 성공, staged/unstaged diff check 이상 없음 |

**최종 결론:** 수정 goal 필요

**남은 항목:** `P2-R5` 실행 후 `P2-R5-GATE`에서 Phase 2 후속 리뷰를 다시 판정한다.

### P2-R5-GATE 종료 판정 — 2026-07-28

- 무엇을: `REV-018`의 캐릭터 생성 Endpoint Contract Summary 예시를 최종 판정했다.
- 왜: 공개 예시와 `DEC-P2-T4-001`/production request 계약의 불일치를 해소했는지 확인하기 위해서다.
- 어떻게: `plan-task.md` 생성 예시를 확인하고 `AiCharacterAdminCharacterControllerMutationTest`를 실행했다.
- 결과: 생성 예시는 필수 `systemPrompt`를 포함하고 서버 소유 `externalCharacterId`, `isActive`를 제외했다. focused test는 `BUILD SUCCESSFUL in 30s`였다.

| 판정 항목 | 결과 | 근거 |
|---|---|---|
| `REV-018` 처리 | 충족 | Endpoint Contract Summary 생성 예시와 production DTO/facade 계약 일치 |
| actual endpoint 회귀 | 충족 | 정상 생성·서버 소유 field 거부 focused test 성공 |
| 범위 준수 | 충족 | production code 변경 없음, Phase 3 이후 기능 변경 없음 |

**최종 결론:** Phase 2 6차 리뷰 종결

**남은 항목:** `P3-R7` → `P3-R8` → `P3-R5-GATE`. Phase 4는 진행하지 않는다.