Files

Klaus 54bbfc75cf docs(ai-character): 관리자 API 검증 기록을 보강한다

2026-07-28 01:32:40 +09:00

36 KiB

Raw Blame History

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

실행 환경

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 단언이 충족됐다고 기록한다.

재현 또는 검증 절차

위 두 event 실패 test와 createFacade helper를 확인한다.
각 test가 actual multipart endpoint를 호출하는지, exception 후 DB를 재조회하는지 확인한다.
현재 결과는 직접 facade 호출과 mock interaction 확인뿐이며 DB save/flush failure injection과 내부 rollback 조회가 없다.
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는 진행하지 않는다.

36 KiB Raw Blame History Unescape Escape

Phase 2 캐릭터 관리 리뷰

1. 리뷰 정보

2. 리뷰 목적과 범위

목적

포함 범위

제외 범위

3. 판정 기준

4. 검토한 근거

문서와 코드

실행 환경

실행한 검증

5. 발견 사항 요약

6. 발견 사항 상세

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

REV-002 — mutation request 계약 불일치

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

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

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

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

8. 리뷰 종료 판정

9. 수정 후 검증 기록

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

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

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

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

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

리뷰 정보와 실행 결과

추가 발견 사항 요약

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

plan·goal 전환

2차 리뷰 종료 판정

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

3차 리뷰 종료 판정

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

리뷰 정보와 실행 결과

추가 발견 사항 요약

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

plan·goal 전환

4차 리뷰 종료 판정

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

리뷰 정보와 실행 결과

추가 발견 사항 요약

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

plan·goal 전환

5차 리뷰 종료 판정

P2-R4 실행 기록

P2-R4-GATE 종료 판정

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

리뷰 정보와 실행 결과

추가 발견 사항 요약

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

plan·goal 전환

6차 리뷰 종료 판정

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

36 KiB

Raw Blame History