Compare commits

..
443 Commits
Author SHA1 Message Date
klaus c4fa2fa2f8 Merge pull request 'test' (#444) from test into main
Reviewed-on: #444
2026-08-05 07:45:05 +00:00
klaus b4027fdee7 Merge pull request 'test' (#443) from test into main
Reviewed-on: #443
2026-08-03 06:20:48 +00:00
klaus eb262b8d53 Merge pull request 'test' (#442) from test into main
Reviewed-on: #442
2026-07-22 13:34:38 +00:00
klaus f5397df65e Merge pull request 'fix(community): 게시글 알림 딥링크를 보강한다' (#441) from test into main
Reviewed-on: #441
2026-07-16 09:26:27 +00:00
klaus 0c6aeb5c8a Merge pull request 'test' (#440) from test into main
Reviewed-on: #440
2026-07-15 12:24:50 +00:00
klaus d8083e34ea Merge pull request 'test' (#439) from test into main
Reviewed-on: #439
2026-07-12 14:05:39 +00:00
klaus 8eeade49d1 Merge pull request 'test' (#438) from test into main
Reviewed-on: #438
2026-07-12 10:42:33 +00:00
klaus b36764abff Merge pull request 'test' (#437) from test into main
Reviewed-on: #437
2026-07-12 08:54:14 +00:00
klaus 7844ea74d7 Merge pull request 'test' (#436) from test into main
Reviewed-on: #436
2026-07-12 04:18:00 +00:00
klaus e04fa67d1d Merge pull request 'test' (#435) from test into main
Reviewed-on: #435
2026-07-12 00:25:13 +00:00
klaus bd1ec54d36 Merge pull request 'chore(build): 테스트 JVM 메모리 설정을 조정한다' (#434) from test into main
Reviewed-on: #434
2026-07-10 08:06:41 +00:00
klaus 4442fa6d91 Merge pull request 'test' (#433) from test into main
Reviewed-on: #433
2026-07-10 07:20:06 +00:00
klaus 795c25159f Merge pull request 'test' (#432) from test into main
Reviewed-on: #432
2026-07-07 18:07:27 +00:00
klaus cdc7cb8612 Merge pull request 'test' (#431) from test into main
Reviewed-on: #431
2026-07-01 05:35:12 +00:00
klaus efefef51f4 Merge pull request 'test' (#430) from test into main
Reviewed-on: #430
2026-06-30 12:54:07 +00:00
klaus e2b9eb8bf3 Merge pull request 'test' (#429) from test into main
Reviewed-on: #429
2026-06-30 07:37:43 +00:00
klaus 1aa7a89f7b Merge pull request 'test' (#428) from test into main
Reviewed-on: #428
2026-06-29 08:06:51 +00:00
klaus 45aa26f1cb Merge pull request 'test' (#427) from test into main
Reviewed-on: #427
2026-06-27 02:30:26 +00:00
klaus 626f02b45e Merge pull request 'test' (#426) from test into main
Reviewed-on: #426
2026-06-27 00:35:29 +00:00
klaus 540c5cb317 Merge pull request 'test' (#425) from test into main
Reviewed-on: #425
2026-05-18 06:53:12 +00:00
klaus 3aa6a35adb Merge pull request 'fix(admin): 크리에이터 관리자 로그아웃 AGENT 권한을 허용한다' (#424) from test into main
Reviewed-on: #424
2026-05-08 10:44:04 +00:00
klaus 81c0d2586c Merge pull request '콘텐츠 관리자 권한 추가' (#423) from test into main
Reviewed-on: #423
2026-05-07 06:35:15 +00:00
klaus 965bb068fc Merge pull request 'fix(i18n): 지원하지 않는 원문 언어 번역 작업을 제외한다' (#422) from test into main
Reviewed-on: #422
2026-05-07 03:26:24 +00:00
klaus d082e0b745 Merge pull request '번역 작업 큐와 언어 감지 캐시를 도입한다' (#421) from test into main
Reviewed-on: #421
2026-05-07 01:31:02 +00:00
klaus c8b83272a3 Merge pull request 'test' (#420) from test into main
Reviewed-on: #420
2026-05-01 06:40:58 +00:00
klaus 1939fdcb33 Merge pull request 'fix(member): 강제 KR 매핑 대상에 회원 17958 추가' (#419) from test into main
Reviewed-on: #419
2026-04-28 05:00:06 +00:00
klaus f521a240c2 Merge pull request 'test' (#418) from test into main
Reviewed-on: #418
2026-04-22 01:19:41 +00:00
klaus 0c35624dfb Merge pull request 'fix(agent-calculate): 에이전트 기본 정산 비율을 7퍼센트로 조정한다' (#417) from test into main
Reviewed-on: #417
2026-04-15 05:37:24 +00:00
klaus 5c24addf31 Merge pull request '에이전트 기능' (#416) from test into main
Reviewed-on: #416
2026-04-14 06:29:22 +00:00
klaus 8671c8efc7 Merge pull request 'test' (#415) from test into main
Reviewed-on: #415
2026-04-08 01:50:50 +00:00
klaus 16c17f4bfa Merge pull request 'feat(live-room): 라이브 캡쳐 녹화 가능 여부를 생성 조회에 반영한다' (#414) from test into main
Reviewed-on: #414
2026-03-30 12:58:19 +00:00
klaus 0e821fae1b Merge pull request 'fix(member-social): 애플 로그인 aud 검증에 serviceId를 포함한다' (#413) from test into main
Reviewed-on: #413
2026-03-30 01:00:13 +00:00
klaus 6a10eff15f Merge pull request 'fix(live-room): 진행중 목록 성인 노출 정책과 JP 강제 매핑 검증을 정리한다' (#412) from test into main
Reviewed-on: #412
2026-03-28 14:11:08 +00:00
klaus fea329e637 Merge pull request 'fix(channel-donation): 후원 목록 탈퇴 닉네임 접두사를 제거한다' (#411) from test into main
Reviewed-on: #411
2026-03-28 10:14:16 +00:00
klaus 681e4a4036 Merge pull request 'test' (#410) from test into main
Reviewed-on: #410
2026-03-28 09:27:28 +00:00
klaus c23f574162 Merge pull request 'fix(member): 회원 차단을 요청 ID 단건만 적용한다' (#409) from test into main
Reviewed-on: #409
2026-03-26 02:01:43 +00:00
klaus c884d7d6c9 Merge pull request 'test' (#408) from test into main
Reviewed-on: #408
2026-03-24 10:41:41 +00:00
klaus 116e8cbca3 Merge pull request 'feat(deploy): EC2 배포 스크립트에 JVM 옵션 로드 기능 추가' (#407) from test into main
Reviewed-on: #407
2026-03-23 09:45:25 +00:00
klaus c8187ba147 Merge pull request 'feat(db): Aurora Serverless v2(0.5~2 ACU) 최적화용 Hikari 풀 설정 추가' (#406) from test into main
Reviewed-on: #406
2026-03-23 05:13:58 +00:00
klaus 676bd0b79e Merge pull request 'test' (#405) from test into main
Reviewed-on: #405
2026-03-19 09:33:40 +00:00
klaus 7522f06bf3 Merge pull request 'fix(live-room): 라이브 방 후원 랭킹 조회에 기간 설정을 반영한다' (#404) from test into main
Reviewed-on: #404
2026-03-17 07:15:17 +00:00
klaus a9d2d1ab48 Merge pull request 'feat(creator-community): 커뮤니티 게시물 고정 기능을 추가한다' (#403) from test into main
Reviewed-on: #403
2026-03-17 02:40:30 +00:00
klaus e0e371cdc9 Merge pull request 'feat(admin-calculate): 관리자 라이브 환불 처리와 정산 응답 식별자를 추가한다' (#402) from test into main
Reviewed-on: #402
2026-03-16 07:13:26 +00:00
klaus b49344d0e9 Merge pull request 'fix(admin-chat-character): JP 리전 캐릭터 등록 성별 값을 일본어로 변환한다' (#401) from test into main
Reviewed-on: #401
2026-03-16 02:37:51 +00:00
klaus 5cc152307a Merge pull request 'test' (#400) from test into main
Reviewed-on: #400
2026-03-13 14:08:53 +00:00
klaus 1fd3d41d7e Merge pull request 'test' (#399) from test into main
Reviewed-on: #399
2026-03-13 13:18:26 +00:00
klaus c1b9dd730d Merge pull request 'fix(admin-calculate): 관리자 정산 조회 캐시를 제거하고 응답 직렬화를 명시한다' (#398) from test into main
Reviewed-on: #398
2026-03-06 03:31:24 +00:00
klaus d40cd32c50 Merge pull request 'test' (#397) from test into main
Reviewed-on: #397
2026-03-05 09:17:37 +00:00
klaus 0289607fd9 Merge pull request 'fix(channel-donation): 관리자 채널후원 정산 조회를 날짜별과 크리에이터별로 분리하고 엑셀 다운로드를 추가한다' (#396) from test into main
Reviewed-on: #396
2026-03-03 05:59:42 +00:00
klaus 1bec644372 Merge pull request 'fix(channel-donation): 후원 조회 월 경계를 UTC 전달 기준으로 보정한다' (#395) from test into main
Reviewed-on: #395
2026-03-03 03:20:46 +00:00
klaus f8a6d1b221 Merge pull request 'fix(channel-donation): 기부 목록 조회 월 범위를 한국 시간 기준으로 계산한다' (#394) from test into main
Reviewed-on: #394
2026-03-03 02:23:01 +00:00
klaus ec769a1307 Merge pull request 'test' (#393) from test into main
Reviewed-on: #393
2026-02-27 06:16:51 +00:00
klaus 8e4fb0d313 Merge pull request 'test' (#392) from test into main
Reviewed-on: #392
2026-02-26 11:18:33 +00:00
klaus cc3a620642 Merge pull request 'fix(recommend-live): 차단 관계를 추천 조회에 반영하고 캐시를 무효화한다' (#391) from test into main
Reviewed-on: #391
2026-02-25 18:40:55 +00:00
klaus be0884e974 Merge pull request 'test' (#390) from test into main
Reviewed-on: #390
2026-02-25 16:55:31 +00:00
klaus 34456395fd Merge pull request 'test' (#389) from test into main
Reviewed-on: #389
2026-02-25 13:55:22 +00:00
klaus 26ddeb9591 Merge pull request 'test' (#388) from test into main
Reviewed-on: #388
2026-02-13 09:14:19 +00:00
klaus cd535a628c Merge pull request 'test' (#387) from test into main
Reviewed-on: #387
2026-02-11 10:03:08 +00:00
klaus de32b537f4 Merge pull request 'test' (#386) from test into main
Reviewed-on: #386
2026-02-08 07:42:31 +00:00
klaus 9c271fc1f6 Merge pull request 'test' (#385) from test into main
Reviewed-on: #385
2026-02-06 05:04:37 +00:00
klaus 2ddbfbccd6 Merge pull request 'test' (#384) from test into main
Reviewed-on: #384
2026-02-04 12:52:24 +00:00
klaus 80786deb72 Merge pull request 'test' (#383) from test into main
Reviewed-on: #383
2026-01-28 15:40:25 +00:00
klaus 8ca2e185ac Merge pull request '라이브 예약 반환 값 - beginDateTimeUtc 추가' (#382) from test into main
Reviewed-on: #382
2026-01-21 10:08:55 +00:00
klaus 484711ad1b Merge pull request '라이브 예약 Response에 utc 시간 변수 beginDateTimeUtc 추가' (#381) from test into main
Reviewed-on: #381
2026-01-21 07:54:05 +00:00
klaus e80ceca0c5 Merge pull request '충전 이벤트 - langContext 문제로 충전이 되지 않는 현상을 langContext를 사용하지 않고 이전 방식으로 기록하도록 롤백하여 임시 해결' (#380) from test into main
Reviewed-on: #380
2026-01-21 02:36:21 +00:00
klaus 33293a6533 Merge pull request '라이브 방 상세 - 날짜 포맷 변경으로 유료방 입장이 불가한 문제를 해결하기 위해 이전으로 롤백' (#379) from test into main
Reviewed-on: #379
2026-01-21 02:16:42 +00:00
klaus f0c1d4e32a Merge pull request '라이브 룸 일시 포맷에 다국어 설정 적용' (#378) from test into main
Reviewed-on: #378
2026-01-20 10:41:23 +00:00
klaus 6cd319ec76 Merge pull request 'memberId가 특정 번호일 때 currency와 관계없이 모든 구매 가능한 캔이 출력되도록 수정' (#377) from test into main
Reviewed-on: #377
2026-01-16 02:39:08 +00:00
klaus 6557ec2aed Merge pull request '푸시 알림 전송 언어 처리' (#376) from test into main
Reviewed-on: #376
2026-01-15 08:45:46 +00:00
klaus f2f8a34319 Merge pull request '국가 컨텍스트로 캔 조회' (#375) from test into main
Reviewed-on: #375
2026-01-14 06:46:51 +00:00
klaus c50ac6ed2c Merge pull request '캔 사용 시 국가 코드 기록 기능 추가' (#374) from test into main
Reviewed-on: #374
2026-01-12 02:31:46 +00:00
klaus 11b9c349d1 Merge pull request '번역 이벤트 커밋 후 처리 분기' (#373) from test into main
Reviewed-on: #373
2026-01-07 09:54:32 +00:00
klaus ef9f8d65e1 Merge pull request 'test' (#372) from test into main
Reviewed-on: #372
2026-01-07 07:42:42 +00:00
klaus 299f2100e9 Merge pull request 'test' (#371) from test into main
Reviewed-on: #371
2026-01-05 06:33:29 +00:00
klaus fd5c794480 Merge pull request 'test' (#370) from test into main
Reviewed-on: #370
2025-12-31 11:01:28 +00:00
klaus 68197de095 Merge pull request 'test' (#369) from test into main
Reviewed-on: #369
2025-12-31 05:44:54 +00:00
klaus 587f3d6b58 Merge pull request 'test' (#368) from test into main
Reviewed-on: #368
2025-11-20 16:02:25 +00:00
klaus 9b6167d46d Merge pull request 'test' (#367) from test into main
Reviewed-on: #367
2025-11-20 12:53:00 +00:00
klaus 008ee3b4e5 Merge pull request 'test' (#366) from test into main
Reviewed-on: #366
2025-11-20 06:27:02 +00:00
klaus 3a57ad23bb Merge pull request 'test' (#365) from test into main
Reviewed-on: #365
2025-11-19 08:56:28 +00:00
klaus 729552335a Merge pull request 'test' (#364) from test into main
Reviewed-on: #364
2025-11-18 10:38:50 +00:00
klaus 02ae507c87 Merge pull request 'fix(series-list): 시리즈 리스트 조회시 정렬 수정' (#363) from test into main
Reviewed-on: #363
2025-11-17 13:38:59 +00:00
klaus 5818abf69d Merge pull request 'fix(series-list): creator의 시리즈를 볼 떄와 다른 페이지에서 시리즈 리스트를 볼 때 정렬 순서 분리' (#362) from test into main
Reviewed-on: #362
2025-11-17 12:25:38 +00:00
klaus ee403915f0 Merge pull request 'test' (#361) from test into main
Reviewed-on: #361
2025-11-17 07:13:11 +00:00
klaus 1a660088de Merge pull request 'test' (#360) from test into main
Reviewed-on: #360
2025-11-13 20:49:12 +00:00
klaus 5196c80ca8 Merge pull request 'test' (#359) from test into main
Reviewed-on: #359
2025-11-13 19:45:52 +00:00
klaus c9c09c2998 Merge pull request 'test' (#358) from test into main
Reviewed-on: #358
2025-11-10 06:53:41 +00:00
klaus 3ea33c4c7b Merge pull request 'feat(home-latest-content): 최신 콘텐츠 조회시 정렬 조건 변경' (#357) from test into main
Reviewed-on: #357
2025-11-07 12:00:59 +00:00
klaus 451a1aa4f2 Merge pull request 'test' (#356) from test into main
Reviewed-on: #356
2025-11-06 08:48:23 +00:00
klaus 90555fd34f Merge pull request 'feat(can-use-status): PAYVERSE로 충전한 캔을 사용한 내역도 포함되도록 수정' (#355) from test into main
Reviewed-on: #355
2025-10-22 14:26:02 +00:00
klaus 0dc430b098 Merge pull request 'UseCalculate에 PAYVERSE로 충전한 캔 로그 데이터를 쌓도록 수정' (#354) from test into main
Reviewed-on: #354
2025-10-22 13:31:46 +00:00
klaus 1f2103c7fa Merge pull request 'fix(can-use): PAYVERSE로 충전한 캔이 사용되지 않는 버그 수정' (#353) from test into main
Reviewed-on: #353
2025-10-22 12:41:13 +00:00
klaus 062c17c51e Merge pull request 'feat(chat): 채팅권 구매 가격과 채팅횟수 변경' (#352) from test into main
Reviewed-on: #352
2025-10-22 07:55:13 +00:00
klaus de169b79a1 Merge pull request 'feat(home): 인기 캐릭터 추가' (#351) from test into main
Reviewed-on: #351
2025-10-20 06:07:49 +00:00
klaus aa24de0a5a Merge pull request 'test' (#350) from test into main
Reviewed-on: #350
2025-10-17 05:46:36 +00:00
klaus e5937d573a Merge pull request 'test' (#349) from test into main
Reviewed-on: #349
2025-10-10 20:49:52 +00:00
klaus 6da86e12bd Merge pull request 'test' (#348) from test into main
Reviewed-on: #348
2025-10-10 19:19:47 +00:00
klaus 9049022a74 Merge pull request 'fix(admin-charge-status-detail): pgChargeAmount와 can의 가격을 가져와서 사용하는 로직을 제거하고 payment에 기록된 가격으로 계산하도록 수정' (#347) from test into main
Reviewed-on: #347
2025-10-10 14:39:40 +00:00
klaus 7b6f3a7a5f Merge pull request 'fix(admin-charge-status): pgChargeAmount와 can의 가격을 가져와서 사용하는 로직을 제거하고 payment에 기록된 가격으로 계산하도록 수정' (#346) from test into main
Reviewed-on: #346
2025-10-10 13:53:23 +00:00
klaus 53e9678efa Merge pull request 'fix(verify-hecto): 데이터 검증시 가격비교 제거' (#345) from test into main
Reviewed-on: #345
2025-10-10 09:58:11 +00:00
klaus e4f547fa92 Merge pull request 'payverse 적용' (#344) from test into main
Reviewed-on: #344
2025-10-10 07:44:07 +00:00
klaus b69756ef81 Merge pull request 'test' (#343) from test into main
Reviewed-on: #343
2025-09-18 19:25:50 +00:00
klaus 1a3a9149a2 Merge pull request 'test' (#342) from test into main
Reviewed-on: #342
2025-09-16 06:11:32 +00:00
klaus ce120a6d5d Merge pull request 'test' (#341) from test into main
Reviewed-on: #341
2025-09-14 20:33:50 +00:00
klaus 08b5fd23ab Merge pull request 'test' (#340) from test into main
Reviewed-on: #340
2025-09-14 08:51:11 +00:00
klaus eb18e2d009 Merge pull request 'test' (#339) from test into main
Reviewed-on: #339
2025-09-11 17:05:45 +00:00
klaus a27852ed44 Merge pull request '캐릭터 챗봇' (#338) from test into main
Reviewed-on: #338
2025-09-10 06:08:47 +00:00
klaus c7925c1706 Merge pull request 'feat: 최근 공지사항 API 추가' (#337) from test into main
Reviewed-on: #337
2025-07-28 02:16:19 +00:00
klaus be59bd7e89 Merge pull request 'fix: 크리에이터 팔로우 API' (#336) from test into main
Reviewed-on: #336
2025-07-21 13:52:34 +00:00
klaus 51ce143fc2 Merge pull request 'test' (#335) from test into main
Reviewed-on: #335
2025-07-21 11:46:56 +00:00
klaus 89eb11f808 Merge pull request 'fix: 라이브 메인 API - 최근 종료된 라이브' (#334) from test into main
Reviewed-on: #334
2025-07-21 10:59:38 +00:00
klaus 30d89987a4 Merge pull request 'test' (#333) from test into main
Reviewed-on: #333
2025-07-21 09:54:56 +00:00
klaus 7959d3e5ed Merge pull request 'test' (#332) from test into main
Reviewed-on: #332
2025-07-18 12:33:22 +00:00
klaus 1e29573ef7 Merge pull request 'fix: 검색 API' (#331) from test into main
Reviewed-on: #331
2025-07-16 10:58:56 +00:00
klaus cc2f533dc6 Merge pull request 'fix: 메인 홈 API - 요일별 시리즈' (#330) from test into main
Reviewed-on: #330
2025-07-14 19:14:06 +00:00
klaus 32b0c19f9d Merge pull request 'test' (#329) from test into main
Reviewed-on: #329
2025-07-14 17:57:26 +00:00
klaus 9af2d768e8 Merge pull request 'test' (#327) from test into main
Reviewed-on: #327
2025-07-14 11:07:57 +00:00
klaus 5677824cde Merge pull request 'test' (#326) from test into main
Reviewed-on: #326
2025-06-13 11:37:26 +00:00
klaus e8f1bc09f9 Merge pull request 'test' (#325) from test into main
Reviewed-on: #325
2025-06-12 05:00:31 +00:00
klaus d1a936d55b Merge pull request 'test' (#324) from test into main
Reviewed-on: #324
2025-06-10 11:01:31 +00:00
klaus dc97eaa835 Merge pull request 'fix: 앱 콘텐츠 수정' (#323) from test into main
Reviewed-on: #323
2025-06-05 02:36:25 +00:00
klaus dcbe57806c Merge pull request 'test' (#322) from test into main
Reviewed-on: #322
2025-06-02 12:41:46 +00:00
klaus b14438cc15 Merge pull request 'fix: 유저 행동 기록, 포인트 지급' (#321) from test into main
Reviewed-on: #321
2025-05-28 07:19:27 +00:00
klaus b27d3bd5c6 Merge pull request 'fix: 유저 행동 기록, 포인트 지급' (#320) from test into main
Reviewed-on: #320
2025-05-26 10:33:16 +00:00
klaus 03ebc9cfe9 Merge pull request 'fix: 큐레이션 아이템 조회' (#319) from test into main
Reviewed-on: #319
2025-05-23 05:43:37 +00:00
klaus 24841b9850 Merge pull request 'fix: 코루틴 내 트랜잭션 간 조회 안 되는 문제 해결' (#318) from test into main
Reviewed-on: #318
2025-05-22 04:31:42 +00:00
klaus d35a3d1a8c Merge pull request 'test' (#317) from test into main
Reviewed-on: #317
2025-05-20 10:26:16 +00:00
klaus 60c4e0b528 Merge pull request 'test' (#316) from test into main
Reviewed-on: #316
2025-05-20 06:03:10 +00:00
klaus 84f33d1bc2 Merge pull request 'fix: 소셜로그인시 유저 행동데이터 SIGN_UP 중복 기록 버그' (#315) from test into main
Reviewed-on: #315
2025-05-12 08:24:53 +00:00
klaus c4e1709b99 Merge pull request 'test' (#314) from test into main
Reviewed-on: #314
2025-05-12 02:12:47 +00:00
klaus e7a5fd5819 Merge pull request 'fix: 구글/카카오 로그인 회원가입 오류 수정' (#313) from test into main
Reviewed-on: #313
2025-05-02 10:58:04 +00:00
klaus 4bde03643c Merge pull request 'test' (#312) from test into main
Reviewed-on: #312
2025-04-29 02:56:16 +00:00
klaus 1bc52b56af Merge pull request 'fix: 콘텐츠 업로드 - 제목과 내용에서 trim 함수를 적용하여 앞/뒤 빈칸 제거' (#311) from test into main
Reviewed-on: #311
2025-04-25 09:43:31 +00:00
klaus 9c33fd93f7 Merge pull request 'refactor: 본인인증 - 본인인증이 완료된 후 유저 행동 데이터를 기록하도록 수정' (#310) from test into main
Reviewed-on: #310
2025-04-24 11:10:17 +00:00
klaus 3c087bc275 Merge pull request '유저 행동 데이터, 포인트 추가' (#309) from test into main
Reviewed-on: #309
2025-04-24 02:44:57 +00:00
klaus 8ad13c289e Merge pull request '회원탈퇴' (#308) from test into main
Reviewed-on: #308
2025-04-15 10:42:37 +00:00
klaus 7577f48a09 Merge pull request '한정판 콘텐츠' (#307) from test into main
Reviewed-on: #307
2025-04-15 09:44:12 +00:00
klaus 0251906964 Merge pull request '비밀번호 찾기' (#306) from test into main
Reviewed-on: #306
2025-04-10 06:28:57 +00:00
klaus 2723a5f134 Merge pull request '일별 전체 회원 수' (#305) from test into main
Reviewed-on: #305
2025-04-10 02:30:00 +00:00
klaus c3c60605fd Merge pull request '관리자 - 회원리스트, 크리에이터 리스트' (#304) from test into main
Reviewed-on: #304
2025-04-09 10:35:01 +00:00
klaus 238f704b22 Merge pull request '소셜 로그인, 회원가입 - 이메일 체크 로직 수정' (#303) from test into main
Reviewed-on: #303
2025-04-08 07:04:11 +00:00
klaus 5639d8ac8e Merge pull request 'test' (#302) from test into main
Reviewed-on: #302
2025-04-07 10:23:13 +00:00
klaus 9aac591591 Merge pull request 'test' (#301) from test into main
Reviewed-on: #301
2025-04-01 13:31:24 +00:00
klaus ffa8e5aebb Merge pull request '일별 전체 회원 수 통계' (#300) from test into main
Reviewed-on: #300
2025-03-31 03:50:18 +00:00
klaus cbbfe014cc Merge pull request '광고 통계' (#299) from test into main
Reviewed-on: #299
2025-03-28 05:29:40 +00:00
klaus 83028f7817 Merge pull request 'test' (#298) from test into main
Reviewed-on: #298
2025-03-26 21:08:29 +00:00
klaus 70d1795557 Merge pull request 'test' (#297) from test into main
Reviewed-on: #297
2025-03-26 04:23:28 +00:00
klaus 8c6c681424 Merge pull request 'marketing 정보 업데이트 시 pid 값이 있으면 항상 로그인 기록 남기기' (#296) from test into main
Reviewed-on: #296
2025-03-25 11:25:46 +00:00
klaus 50bc9f4ff3 Merge pull request '라이브 방 - 예약 중 조회' (#295) from test into main
Reviewed-on: #295
2025-03-24 10:04:08 +00:00
klaus f00ea03fad Merge pull request 'test' (#294) from test into main
Reviewed-on: #294
2025-03-24 09:09:16 +00:00
klaus f22e7b9ad1 Merge pull request '자동생성 닉네임에 사용될 형용사, 명사 값 추가' (#293) from test into main
Reviewed-on: #293
2025-03-21 10:27:30 +00:00
klaus c7ec95f4bb Merge pull request 'test' (#292) from test into main
Reviewed-on: #292
2025-03-20 19:24:03 +00:00
klaus 229e7a8ccc Merge pull request '시리즈 상세, 채널 상세' (#291) from test into main
Reviewed-on: #291
2025-03-19 09:43:06 +00:00
klaus 3c616474ff Merge pull request 'test' (#290) from test into main
Reviewed-on: #290
2025-03-19 07:51:25 +00:00
klaus 56eb6b3ce3 Merge pull request '19금 콘텐츠 보기 설정 적용' (#289) from test into main
Reviewed-on: #289
2025-03-19 02:05:17 +00:00
klaus 545836d43c Merge pull request '관리자 광고통계, 일별 전체 회원 수' (#288) from test into main
Reviewed-on: #288
2025-03-17 08:50:59 +00:00
klaus 219f83dec0 Merge pull request 'test' (#287) from test into main
Reviewed-on: #287
2025-03-17 05:54:05 +00:00
klaus a76a841238 Merge pull request 'test' (#286) from test into main
Reviewed-on: #286
2025-03-14 16:11:17 +00:00
klaus c26680de84 Merge pull request '이벤트 배너, 충전 이벤트 - 기간 설정에 시간 추가' (#285) from test into main
Reviewed-on: #285
2025-03-14 03:40:07 +00:00
klaus 8fffad9d3a Merge pull request 'test' (#284) from test into main
Reviewed-on: #284
2025-03-13 12:25:35 +00:00
klaus f4f0f203a2 Merge pull request '유저 정보 조회' (#283) from test into main
Reviewed-on: #283
2025-03-12 08:00:13 +00:00
klaus b7196f5a0c Merge pull request 'test' (#282) from test into main
Reviewed-on: #282
2025-03-11 08:01:05 +00:00
klaus 5d33a18890 Merge pull request 'test' (#281) from test into main
Reviewed-on: #281
2025-03-10 05:35:30 +00:00
klaus 96186a1a50 Merge pull request '마케팅 - 매체 파트너 코드 조회 API - link 값 수정' (#280) from test into main
Reviewed-on: #280
2025-03-07 06:27:08 +00:00
klaus bc8bc479d1 Merge pull request 'test' (#279) from test into main
Reviewed-on: #279
2025-03-06 17:58:32 +00:00
klaus 47595b1291 Merge pull request 'test' (#278) from test into main
Reviewed-on: #278
2025-03-05 14:05:47 +00:00
klaus 01a88964df Merge pull request 'test' (#277) from test into main
Reviewed-on: #277
2025-03-05 09:44:59 +00:00
klaus 3a2b77379f Merge pull request '콘텐츠 업로드' (#276) from test into main
Reviewed-on: #276
2025-02-28 04:45:04 +00:00
klaus dc4e5f75cd Merge pull request '콘텐츠 메인 콘텐츠 탭 - 채널별 추천 단편' (#275) from test into main
Reviewed-on: #275
2025-02-26 03:14:33 +00:00
klaus d0178d551c Merge pull request '콘텐츠 메인 콘텐츠 탭 - 채널별 추천 단편' (#274) from test into main
Reviewed-on: #274
2025-02-25 14:54:53 +00:00
klaus 827333108d Merge pull request '콘텐츠 대여기간' (#273) from test into main
Reviewed-on: #273
2025-02-25 14:02:18 +00:00
klaus 587b90bd27 Merge pull request '콘텐츠 메인 무료 탭 - 새로운 콘텐츠' (#272) from test into main
Reviewed-on: #272
2025-02-22 01:56:49 +00:00
klaus 4dc20c5e90 Merge pull request '콘텐츠 메인 무료 탭' (#271) from test into main
Reviewed-on: #271
2025-02-22 00:39:09 +00:00
klaus ac25782f2b Merge pull request '관리자 태그 큐레이션 - 콘텐츠 검색' (#270) from test into main
Reviewed-on: #270
2025-02-21 21:46:15 +00:00
klaus 20437d56e7 Merge pull request '메인 시리즈 탭 - 완결 시리즈' (#269) from test into main
Reviewed-on: #269
2025-02-21 21:15:52 +00:00
klaus f0b412828a Merge pull request '메인 시리즈 탭 - 완결 시리즈' (#268) from test into main
Reviewed-on: #268
2025-02-21 19:27:33 +00:00
klaus 367faac5c3 Merge pull request 'test' (#267) from test into main
Reviewed-on: #267
2025-02-20 18:24:35 +00:00
klaus 84deaaa970 Merge pull request '콘텐츠 메인 시리즈 탭 - 장르별 시리즈' (#266) from test into main
Reviewed-on: #266
2025-02-19 12:52:17 +00:00
klaus a2b39466c2 Merge pull request '기존 콘텐츠 메인 - 새로운 콘텐츠' (#265) from test into main
Reviewed-on: #265
2025-02-19 11:34:02 +00:00
klaus 03586c4005 Merge pull request '기존 콘텐츠 메인 - 새로운 콘텐츠' (#264) from test into main
Reviewed-on: #264
2025-02-19 09:49:04 +00:00
klaus 6ea69e1510 Merge pull request '콘텐츠 메인 무료 탭 - 새로운 무료 콘텐츠' (#263) from test into main
Reviewed-on: #263
2025-02-19 09:24:24 +00:00
klaus 553c6dc539 Merge pull request '콘텐츠 메인 단편 탭 - 새로운 단편' (#262) from test into main
Reviewed-on: #262
2025-02-19 08:20:14 +00:00
klaus 6cc22f5b6d Merge pull request '콘텐츠 메인 홈, 무료 탭' (#261) from test into main
Reviewed-on: #261
2025-02-19 06:34:53 +00:00
klaus 9103d67cc1 Merge pull request 'test' (#260) from test into main
Reviewed-on: #260
2025-02-18 18:13:25 +00:00
klaus 25083fb0e4 Merge pull request 'test' (#259) from test into main
Reviewed-on: #259
2025-02-18 14:48:09 +00:00
klaus d2dc045255 Merge pull request 'test' (#258) from test into main
Reviewed-on: #258
2025-02-14 18:09:11 +00:00
klaus b8621dfbb0 Merge pull request 'test' (#257) from test into main
Reviewed-on: #257
2025-02-09 13:36:21 +00:00
klaus 93633940dd Merge pull request 'test' (#256) from test into main
Reviewed-on: #256
2025-02-03 07:20:32 +00:00
klaus b6f5325351 Merge pull request 'test' (#255) from test into main
Reviewed-on: #255
2025-01-31 15:22:23 +00:00
klaus 7c32c08f1f Merge pull request 'test' (#254) from test into main
Reviewed-on: #254
2025-01-17 05:46:00 +00:00
klaus 1d268da08d Merge pull request '오디션 등록 푸시알림 메시지 수정' (#253) from test into main
Reviewed-on: #253
2025-01-10 10:23:19 +00:00
klaus 797666ae0d Merge pull request 'test' (#252) from test into main
Reviewed-on: #252
2025-01-08 14:11:08 +00:00
klaus dcf470997e Merge pull request 'test' (#251) from test into main
Reviewed-on: #251
2025-01-08 06:29:33 +00:00
klaus 0974d1dbf8 Merge pull request '관리자 오디션 지원 리스트' (#250) from test into main
Reviewed-on: #250
2025-01-07 19:44:39 +00:00
klaus 12a35db6cd Merge pull request '오디션' (#249) from test into main
Reviewed-on: #249
2025-01-07 17:24:40 +00:00
klaus 9abbb05ad8 Merge pull request 'test' (#248) from test into main
Reviewed-on: #248
2024-12-18 07:10:01 +00:00
klaus 1ecaf69b0b Merge pull request 'test' (#247) from test into main
Reviewed-on: #247
2024-12-17 13:43:45 +00:00
klaus e334d1e5d9 Merge pull request '콘텐츠 댓글 푸시 대상자' (#246) from test into main
Reviewed-on: #246
2024-12-03 15:54:34 +00:00
klaus b735e861d0 Merge pull request '콘텐츠 댓글 푸시 대상자 조회' (#245) from test into main
Reviewed-on: #245
2024-12-02 15:06:49 +00:00
klaus 4eb433d372 Merge pull request 'test' (#244) from test into main
Reviewed-on: #244
2024-12-02 12:05:30 +00:00
klaus 2416ae61f3 Merge pull request 'test' (#243) from test into main
Reviewed-on: #243
2024-12-02 04:29:50 +00:00
klaus 01fb336985 Merge pull request '콘텐츠 등록' (#242) from test into main
Reviewed-on: #242
2024-11-26 12:46:24 +00:00
klaus b6af88a732 Merge pull request 'test' (#241) from test into main
Reviewed-on: #241
2024-11-26 05:33:45 +00:00
klaus 58a2a17d6d Merge pull request 'test' (#240) from test into main
Reviewed-on: #240
2024-11-23 17:59:23 +00:00
klaus 79f5a0f520 Merge pull request '내 콘텐츠 수정, 삭제 시 콘텐츠 조회 함수' (#239) from test into main
Reviewed-on: #239
2024-11-21 06:34:30 +00:00
klaus 7f6c0f7f04 Merge pull request 'Redis connection 수정' (#238) from test into main
Reviewed-on: #238
2024-11-20 09:58:56 +00:00
klaus f658df4dca Merge pull request 'Redis connection' (#237) from test into main
Reviewed-on: #237
2024-11-20 07:52:58 +00:00
klaus 9d43b8e23a Merge pull request 'Redis connection' (#236) from test into main
Reviewed-on: #236
2024-11-20 06:47:52 +00:00
klaus 4270aef79b Merge pull request 'test' (#235) from test into main
Reviewed-on: #235
2024-11-11 15:34:35 +00:00
klaus 1c0dc82d44 Merge pull request '콘텐츠 구매 - 소장만 추가' (#234) from test into main
Reviewed-on: #234
2024-11-08 12:40:29 +00:00
klaus c1e325aadf Merge pull request 'test' (#233) from test into main
Reviewed-on: #233
2024-11-05 07:26:19 +00:00
klaus cec87da69d Merge pull request '콘텐츠 대여가격' (#232) from test into main
Reviewed-on: #232
2024-10-31 05:23:01 +00:00
klaus f68f24cb2c Merge pull request 'test' (#231) from test into main
Reviewed-on: #231
2024-10-31 03:09:13 +00:00
klaus ed094347fc Merge pull request '라이브 방 후원랭킹' (#230) from test into main
Reviewed-on: #230
2024-10-30 05:16:05 +00:00
klaus b8afdffbe1 Merge pull request 'test' (#229) from test into main
Reviewed-on: #229
2024-10-29 08:35:58 +00:00
klaus f6ba79f31c Merge pull request 'test' (#228) from test into main
Reviewed-on: #228
2024-10-25 03:45:26 +00:00
klaus 5f3b1663d2 Merge pull request '관리자 - 콘텐츠 리스트' (#227) from test into main
Reviewed-on: #227
2024-10-16 03:33:23 +00:00
klaus 66e786b4bb Merge pull request '관리자 - 시리즈 리스트 API' (#226) from test into main
Reviewed-on: #226
2024-10-14 15:39:45 +00:00
klaus f671114574 Merge pull request '관리자 - 시리즈 리스트 API' (#225) from test into main
Reviewed-on: #225
2024-10-14 10:37:28 +00:00
klaus ce37060d94 Merge pull request '관리자 - 시리즈 리스트 API 추가' (#224) from test into main
Reviewed-on: #224
2024-10-14 10:10:43 +00:00
klaus 7d19a4d184 Merge pull request 'test' (#223) from test into main
Reviewed-on: #223
2024-10-13 17:30:25 +00:00
klaus 22f28a2f8a Merge pull request '콘텐츠 메인 - 추천시리즈, 새로운 콘텐츠, 큐레이션' (#222) from test into main
Reviewed-on: #222
2024-10-13 16:33:15 +00:00
klaus ceef9ca979 Merge pull request 'test' (#221) from test into main
Reviewed-on: #221
2024-10-11 05:06:22 +00:00
klaus efe8f4f939 Merge pull request '콘텐츠 메인 - 새로운 콘텐츠 섹션 두번째 정렬 조건 추가' (#220) from test into main
Reviewed-on: #220
2024-10-04 07:21:38 +00:00
klaus ba692a1195 Merge pull request '시리즈 상세 - 콘텐츠 리스트 두번째 정렬 조건 추가' (#219) from test into main
Reviewed-on: #219
2024-10-04 02:41:28 +00:00
klaus d732bad042 Merge pull request '시리즈 상세' (#218) from test into main
Reviewed-on: #218
2024-10-02 09:18:19 +00:00
klaus 4c935c3bee Merge pull request '예약 라이브 개수 제한' (#217) from test into main
Reviewed-on: #217
2024-09-25 05:42:45 +00:00
klaus c160dd791f Merge pull request 'test' (#216) from test into main
Reviewed-on: #216
2024-09-24 10:17:58 +00:00
klaus 23cd1b4601 Merge pull request '라이브 후원현황 API' (#215) from test into main
Reviewed-on: #215
2024-09-23 13:58:14 +00:00
klaus 031fc8ba1b Merge pull request 'test' (#214) from test into main
Reviewed-on: #214
2024-09-23 06:24:12 +00:00
klaus c6853289ad Merge pull request 'test' (#213) from test into main
Reviewed-on: #213
2024-09-11 08:23:08 +00:00
klaus 2497bb69bc Merge pull request 'test' (#212) from test into main
Reviewed-on: #212
2024-09-11 07:47:35 +00:00
klaus a58a67e0a2 Merge pull request 'test' (#211) from test into main
Reviewed-on: #211
2024-09-11 06:00:31 +00:00
klaus 4315fe12a5 Merge pull request 'test' (#210) from test into main
Reviewed-on: #210
2024-09-06 19:00:39 +00:00
klaus 42f10a8899 Merge pull request 'test' (#209) from test into main
Reviewed-on: #209
2024-09-05 10:12:14 +00:00
klaus 1e4b47f989 Merge pull request 'test' (#208) from test into main
Reviewed-on: #208
2024-08-30 09:17:41 +00:00
klaus ff255dbfae Merge pull request 'test' (#207) from test into main
Reviewed-on: #207
2024-08-27 07:31:05 +00:00
klaus dbe9b72feb Merge pull request 'test' (#206) from test into main
Reviewed-on: #206
2024-08-23 13:48:24 +00:00
klaus 95a714b391 Merge pull request '탐색' (#205) from test into main
Reviewed-on: #205
2024-08-19 13:21:31 +00:00
klaus 28f58c7f56 Merge pull request '라이브' (#204) from test into main
Reviewed-on: #204
2024-08-14 09:34:52 +00:00
klaus 8bd46d8f21 Merge pull request '크리에이터 관리자 시리즈' (#203) from test into main
Reviewed-on: #203
2024-08-14 07:41:33 +00:00
klaus e1bb8e54ed Merge pull request '크리에이터 커뮤니티' (#202) from test into main
Reviewed-on: #202
2024-08-06 11:41:11 +00:00
klaus 1de705b063 Merge pull request '크리에이터 커뮤니티' (#201) from test into main
Reviewed-on: #201
2024-08-06 06:37:30 +00:00
klaus f6926ad356 Merge pull request '남/여 크리에이터에서 특정 크리에이터 제거' (#200) from test into main
Reviewed-on: #200
2024-07-26 07:54:18 +00:00
klaus 2cdbbb1b37 Merge pull request 'test' (#199) from test into main
Reviewed-on: #199
2024-07-25 16:08:20 +00:00
klaus 4dce8c8f03 Merge pull request '크리에이터 커뮤니티' (#198) from test into main
Reviewed-on: #198
2024-07-10 05:24:58 +00:00
klaus 97a5bace6f Merge pull request 'test' (#197) from test into main
Reviewed-on: #197
2024-07-08 14:17:42 +00:00
klaus d4d51ec48f Merge pull request 'test' (#196) from test into main
Reviewed-on: #196
2024-07-02 08:57:11 +00:00
klaus fb91398462 Merge pull request '커뮤니티 게시물' (#195) from test into main
Reviewed-on: #195
2024-06-17 14:09:26 +00:00
klaus 105dadd798 Merge pull request '커뮤니티 게시물' (#194) from test into main
Reviewed-on: #194
2024-06-15 11:57:33 +00:00
klaus 2abf2837d3 Merge pull request '커뮤니티 게시물' (#193) from test into main
Reviewed-on: #193
2024-06-11 12:13:47 +00:00
klaus 422aa67af6 Merge pull request '커뮤니티 게시물' (#192) from test into main
Reviewed-on: #192
2024-06-11 11:55:05 +00:00
klaus 7fffab6985 Merge pull request '크리에이터 정산 - 입력된 비율로 계산' (#191) from test into main
Reviewed-on: #191
2024-06-11 08:07:22 +00:00
klaus 5a4be3d2c1 Merge pull request '콘텐츠 상세' (#190) from test into main
Reviewed-on: #190
2024-06-07 10:30:06 +00:00
klaus f39a7681db Merge pull request 'test' (#189) from test into main
Reviewed-on: #189
2024-06-04 03:39:23 +00:00
klaus c60a7580ba Merge pull request 'test' (#188) from test into main
Reviewed-on: #188
2024-06-03 22:13:56 +00:00
klaus 97edb56edc Merge pull request 'test' (#187) from test into main
Reviewed-on: #187
2024-05-29 17:04:39 +00:00
klaus 6ebca8d22b Merge pull request '관리자 - 라이브 리스트' (#186) from test into main
Reviewed-on: #186
2024-05-28 18:18:44 +00:00
klaus 95371ad934 Merge pull request '(크리에이터)관리자 커뮤니티 게시물 정산' (#185) from test into main
Reviewed-on: #185
2024-05-28 16:54:44 +00:00
klaus 2c176825fd Merge pull request 'test' (#184) from test into main
Reviewed-on: #184
2024-05-28 16:09:51 +00:00
klaus fae7de48d3 Merge pull request 'test' (#183) from test into main
Reviewed-on: #183
2024-05-27 08:28:27 +00:00
klaus b8230646a2 Merge pull request '커뮤니티 게시글 유료화' (#182) from test into main
Reviewed-on: #182
2024-05-24 14:44:14 +00:00
klaus 43279541dd Merge pull request '콘텐츠별 누적정산' (#181) from test into main
Reviewed-on: #181
2024-05-21 06:37:51 +00:00
klaus b4791977c1 Merge pull request 'PG 심사를 위한 캔 충전 로직 추가' (#180) from test into main
Reviewed-on: #180
2024-05-20 06:38:40 +00:00
klaus ef917ecc25 Merge pull request '라이브 방 - 크리에이터 입장 가능 설정 추가' (#179) from test into main
Reviewed-on: #179
2024-05-14 12:09:53 +00:00
klaus a93faad951 Merge pull request '룰렛 방식 수정' (#178) from test into main
Reviewed-on: #178
2024-05-10 18:00:40 +00:00
klaus fd001d24d3 Merge pull request '추천시리즈 API 추가' (#177) from test into main
Reviewed-on: #177
2024-05-07 10:34:10 +00:00
klaus 7aa5884797 Merge pull request '구글 인 앱 결제 검증코드 수정' (#176) from test into main
Reviewed-on: #176
2024-05-03 10:06:39 +00:00
klaus 5b237a1547 Merge pull request 'test' (#175) from test into main
Reviewed-on: #175
2024-05-03 06:08:55 +00:00
klaus 2e37990d87 Merge pull request '탐색 - 남/여 크리에이터 리스트' (#174) from test into main
Reviewed-on: #174
2024-05-02 17:24:18 +00:00
klaus dd07d724a8 Merge pull request 'test' (#173) from test into main
Reviewed-on: #173
2024-05-02 16:41:50 +00:00
klaus 03ce8618e7 Merge pull request '관리자 시그니처 설정' (#172) from test into main
Reviewed-on: #172
2024-05-02 07:13:21 +00:00
klaus db1a7a7fd6 Merge pull request '시그니처 후원 시간 추가' (#171) from test into main
Reviewed-on: #171
2024-05-02 06:23:22 +00:00
klaus 36a82d7f53 Merge pull request '시리즈, 시리즈 콘텐츠' (#170) from test into main
Reviewed-on: #170
2024-04-30 14:00:01 +00:00
klaus 3a34401113 Merge pull request '시리즈 상세' (#169) from test into main
Reviewed-on: #169
2024-04-30 09:44:55 +00:00
klaus 9927268330 Merge pull request '구글 인 앱 결제' (#168) from test into main
Reviewed-on: #168
2024-04-30 08:24:03 +00:00
klaus c45c97e29d Merge pull request '시리즈' (#167) from test into main
Reviewed-on: #167
2024-04-26 18:51:10 +00:00
klaus c64a315226 Merge pull request 'test' (#166) from test into main
Reviewed-on: #166
2024-04-18 16:40:55 +00:00
klaus a4cafca6ab Merge pull request 'test' (#165) from test into main
Reviewed-on: #165
2024-04-18 10:02:45 +00:00
klaus 46284a0660 Merge pull request 'test' (#164) from test into main
Reviewed-on: #164
2024-04-15 12:31:42 +00:00
klaus 05df86e15a Merge pull request 'test' (#163) from test into main
Reviewed-on: #163
2024-04-09 14:40:33 +00:00
klaus 8b433027e2 Merge pull request 'test' (#162) from test into main
Reviewed-on: #162
2024-04-09 13:27:24 +00:00
klaus 5bd4ff7610 Merge pull request '결제 테이블에 구글결제의 경우 orderId 추가' (#161) from test into main
Reviewed-on: #161
2024-04-05 03:10:00 +00:00
klaus d693c397ea Merge pull request '.' (#160) from test into main
Reviewed-on: #160
2024-04-03 06:49:36 +00:00
klaus 1d8d1ec9a5 Merge pull request 'test' (#159) from test into main
Reviewed-on: #159
2024-04-03 06:27:26 +00:00
klaus 5e491f11ee Merge pull request '크리에이터 관리자 라이브 정산' (#158) from test into main
Reviewed-on: #158
2024-04-03 03:45:31 +00:00
klaus 7cedea06ac Merge pull request '캔 사용' (#157) from test into main
Reviewed-on: #157
2024-04-01 12:42:44 +00:00
klaus 2e5f750e50 Merge pull request 'test' (#156) from test into main
Reviewed-on: #156
2024-04-01 10:20:09 +00:00
klaus 20289cad10 Merge pull request '콘텐츠 상세' (#155) from test into main
Reviewed-on: #155
2024-03-29 10:10:04 +00:00
klaus e0d64c31c7 Merge pull request '콘텐츠 상세' (#154) from test into main
Reviewed-on: #154
2024-03-29 08:18:15 +00:00
klaus 8c1b95dc97 Merge pull request '구글 인 앱구매 검증' (#153) from test into main
Reviewed-on: #153
2024-03-28 17:13:57 +00:00
klaus fb5641343e Merge pull request 'test' (#152) from test into main
Reviewed-on: #152
2024-03-28 06:31:43 +00:00
klaus 87765941eb Merge pull request '구글 인 앱 결제 검증' (#151) from test into main
Reviewed-on: #151
2024-03-22 20:10:01 +00:00
klaus 1809862c16 Merge pull request '구글 인 앱 결제 처리과정 축소' (#150) from test into main
Reviewed-on: #150
2024-03-22 15:27:25 +00:00
klaus 300f784f7d Merge pull request '구글 인 앱 결제 검증 과정 try/catch로 예외 처리' (#149) from test into main
Reviewed-on: #149
2024-03-22 11:59:37 +00:00
klaus 67a045eae6 Merge pull request '구글 인 앱 결제 검증 수정' (#148) from test into main
Reviewed-on: #148
2024-03-22 11:36:35 +00:00
klaus 2a79903a28 Merge pull request 'test' (#147) from test into main
Reviewed-on: #147
2024-03-22 10:08:00 +00:00
klaus d3222ce083 Merge pull request '관리자 캔 충전현황' (#146) from test into main
Reviewed-on: #146
2024-03-21 15:56:02 +00:00
klaus 406a421742 Merge pull request '구글 인 앱 결제 검증 코드 수정' (#145) from test into main
Reviewed-on: #145
2024-03-21 15:22:34 +00:00
klaus 10bf728faf Merge pull request '구글 인 앱 결제 검증 코드 수정' (#144) from test into main
Reviewed-on: #144
2024-03-21 14:37:09 +00:00
klaus 607617747c Merge pull request '구글 인 앱 결제 검증 코드 수정' (#143) from test into main
Reviewed-on: #143
2024-03-21 12:47:51 +00:00
klaus f0a69eb1a2 Merge pull request 'test' (#142) from test into main
Reviewed-on: #142
2024-03-21 07:45:02 +00:00
klaus 6b307a6e17 Merge pull request 'test' (#141) from test into main
Reviewed-on: #141
2024-03-13 11:28:13 +00:00
klaus 08d08a934a Merge pull request 'test' (#140) from test into main
Reviewed-on: #140
2024-03-12 06:20:02 +00:00
klaus c500c12668 Merge pull request 'test' (#139) from test into main
Reviewed-on: #139
2024-03-08 13:40:27 +00:00
klaus 62060adeba Merge pull request '채널 후원 랭킹' (#138) from test into main
Reviewed-on: #138
2024-02-29 10:28:51 +00:00
klaus b2fc75edb8 Merge pull request '룰렛 정렬 순서 수정' (#137) from test into main
Reviewed-on: #137
2024-02-27 17:29:36 +00:00
klaus a999dd2085 Merge pull request 'test' (#136) from test into main
Reviewed-on: #136
2024-02-27 16:16:30 +00:00
klaus 49f95ab100 Merge pull request '회원테이블에 adid 추가' (#135) from test into main
Reviewed-on: #135
2024-02-27 05:49:47 +00:00
klaus 1a84d5b30c Merge pull request 'test' (#134) from test into main
Reviewed-on: #134
2024-02-24 20:35:57 +00:00
klaus 3b65050632 Merge pull request 'redis ssl false' (#133) from test into main
Reviewed-on: #133
2024-02-17 13:00:25 +00:00
klaus d0df31674c Merge pull request 'test' (#132) from test into main
Reviewed-on: #132
2024-02-17 12:44:52 +00:00
klaus 1fe88402e2 Merge pull request 'test' (#131) from test into main
Reviewed-on: #131
2024-02-14 07:12:41 +00:00
klaus 67097696e6 Merge pull request '커뮤니티 게시물 시간' (#130) from test into main
Reviewed-on: #130
2024-02-12 08:14:24 +00:00
klaus 8e7e77067a Merge pull request 'test' (#129) from test into main
Reviewed-on: #129
2024-02-12 07:53:26 +00:00
klaus 9899390b61 Merge pull request '관리자 콘텐츠 리스트, 수정' (#128) from test into main
Reviewed-on: #128
2024-02-08 18:19:50 +00:00
klaus 80c476a908 Merge pull request '관리자 콘텐츠 리스트' (#127) from test into main
Reviewed-on: #127
2024-02-08 14:45:54 +00:00
klaus 59da1d6e49 Merge pull request '카테고리 콘텐츠' (#126) from test into main
Reviewed-on: #126
2024-02-07 13:33:37 +00:00
klaus 5aef7dac33 Merge pull request 'test' (#125) from test into main
Reviewed-on: #125
2024-02-07 09:39:09 +00:00
klaus faf7aa06b6 Merge pull request 'test' (#124) from test into main
Reviewed-on: #124
2024-02-05 07:03:45 +00:00
klaus 38ef6e5583 Merge pull request 'test' (#123) from test into main
Reviewed-on: #123
2024-02-05 02:12:10 +00:00
klaus c0b15b5d94 Merge pull request '콘텐츠 업로드' (#122) from test into main
Reviewed-on: #122
2024-01-30 03:45:31 +00:00
klaus 2cfc067ea1 Merge pull request '콘텐츠 전체 리스트' (#121) from test into main
Reviewed-on: #121
2024-01-29 09:00:23 +00:00
klaus a91db4f956 Merge pull request '콘텐츠 상단 고정 기능 추가' (#120) from test into main
Reviewed-on: #120
2024-01-29 02:45:41 +00:00
klaus 8a09780a02 Merge pull request 'test' (#119) from test into main
Reviewed-on: #119
2024-01-26 06:19:49 +00:00
klaus 45e8ec6505 Merge pull request '콘텐츠 정렬 기준' (#118) from test into main
Reviewed-on: #118
2024-01-24 15:03:06 +00:00
klaus 4554b85914 Merge pull request '회원가입 시 닉네임 validation 조건' (#117) from test into main
Reviewed-on: #117
2024-01-24 07:11:23 +00:00
klaus 8aa79c4a9c Merge pull request '콘텐츠 등록 - 태그 등록' (#116) from test into main
Reviewed-on: #116
2024-01-16 15:19:59 +00:00
klaus c8d3210b57 Merge pull request 'test' (#115) from test into main
Reviewed-on: #115
2024-01-11 09:05:44 +00:00
klaus 2282a49563 Merge pull request 'test' (#114) from test into main
Reviewed-on: #114
2024-01-11 03:49:53 +00:00
klaus b82fdfb2c8 Merge pull request '예약 업로드' (#113) from test into main
Reviewed-on: #113
2024-01-10 16:59:51 +00:00
klaus 2d17eac199 Merge pull request '19세 미만이 인증처리 되던 버그 수정' (#112) from test into main
Reviewed-on: #112
2024-01-08 10:07:21 +00:00
klaus e482bc3aad Merge pull request '콘텐츠를 올린 크리에이터가 댓글을 삭제할 수 있도록 수정' (#111) from test into main
Reviewed-on: #111
2024-01-04 11:36:43 +00:00
klaus ec022b74d1 Merge pull request '캔 쿠폰 조회 로직 수정' (#110) from test into main
Reviewed-on: #110
2024-01-04 09:59:20 +00:00
klaus dc42c09ce3 Merge pull request '캔 쿠폰 조회' (#109) from test into main
Reviewed-on: #109
2024-01-03 15:48:09 +00:00
klaus 046a34d2a4 Merge pull request 'test' (#108) from test into main
Reviewed-on: #108
2024-01-03 15:19:42 +00:00
klaus 9ff6ec1888 Merge pull request '캔 쿠폰 시스템' (#107) from test into main
Reviewed-on: #107
2024-01-03 11:28:48 +00:00
klaus d2950106ec Merge pull request '콘텐츠 랭킹 - 후원 순위 제거, 룰렛 아이템 개수 10로 변경' (#106) from test into main
Reviewed-on: #106
2023-12-26 12:50:09 +00:00
klaus 962f800d2e Merge pull request '팔로우 한 크리에이터 커뮤니티 게시물 조회 - 인증하지 않은 사람은 19금이 아닌 최신 게시물이 조회되도록 수정' (#105) from test into main
Reviewed-on: #105
2023-12-25 08:19:43 +00:00
klaus 962107e507 Merge pull request '팔로우 한 크리에이터 커뮤니티 게시물 조회 - 차단된 유저는 조회되지 않도록 수정' (#104) from test into main
Reviewed-on: #104
2023-12-21 19:28:10 +00:00
klaus 039bd11963 Merge pull request '커뮤니티 게시물 조회 - 차단된 유저는 조회되지 않도록 수정' (#103) from test into main
Reviewed-on: #103
2023-12-21 19:05:12 +00:00
klaus 5c250ea4ae Merge pull request '크리에이터 커뮤니티' (#102) from test into main
Reviewed-on: #102
2023-12-21 15:10:55 +00:00
klaus e3405bcec6 Merge pull request 'test' (#101) from test into main
Reviewed-on: #101
2023-12-13 16:14:50 +00:00
klaus 0fd1c2235f Merge pull request '라이브 정산 - 정렬 순서 추가 (라이브 방 id, 구분)' (#100) from test into main
Reviewed-on: #100
2023-12-10 16:58:05 +00:00
klaus b20c29b022 Merge pull request 'test' (#99) from test into main
Reviewed-on: #99
2023-12-10 12:34:51 +00:00
klaus 12d5dcd298 Merge pull request 'test' (#98) from test into main
Reviewed-on: #98
2023-12-10 09:02:29 +00:00
klaus 2c305dc6c6 Merge pull request 'test' (#97) from test into main
Reviewed-on: #97
2023-12-10 06:48:43 +00:00
klaus 62f76f7433 Merge pull request 'test' (#96) from test into main
Reviewed-on: #96
2023-12-07 01:46:33 +00:00
klaus 858ce524f9 Merge pull request 'test' (#95) from test into main
Reviewed-on: #95
2023-11-27 12:48:24 +00:00
klaus 3795fb4a40 Merge pull request 'test' (#94) from test into main
Reviewed-on: #94
2023-11-24 07:03:10 +00:00
klaus 0c01aeec50 Merge pull request '관리자 - 이벤트 배너 등록' (#93) from test into main
Reviewed-on: #93
2023-11-21 16:21:19 +00:00
klaus 892206744d Merge pull request '이벤트 배너, 팝업' (#92) from test into main
Reviewed-on: #92
2023-11-21 12:59:30 +00:00
klaus 9e2c1474db Merge pull request '메시지 보내기 유저 검색' (#91) from test into main
Reviewed-on: #91
2023-11-20 05:41:57 +00:00
klaus 16328f73d9 Merge pull request '크리에이터 관리자, 관리자 - 일자별 콘텐츠 후원 정산 API' (#90) from test into main
Reviewed-on: #90
2023-11-14 13:14:19 +00:00
klaus e0d4f53cf4 Merge pull request 'test' (#89) from test into main
Reviewed-on: #89
2023-11-14 12:15:51 +00:00
klaus e09a59c5b4 Merge pull request 'test' (#88) from test into main
Reviewed-on: #88
2023-11-14 11:09:14 +00:00
klaus 049e654535 Merge pull request '관리자 일자별 콘텐츠 후원 정산 - 크리에이터 순으로 정렬' (#87) from test into main
Reviewed-on: #87
2023-11-14 09:22:38 +00:00
klaus c927dc4ecd Merge pull request '관리자 - 일자별 콘텐츠 후원 정산 페이지 추가' (#86) from test into main
Reviewed-on: #86
2023-11-14 09:03:35 +00:00
klaus fe4ecd0ad8 Merge pull request '크리에이터 관리자 - 일자별 콘텐츠 정산 페이징 안되는 버그 수정' (#85) from test into main
Reviewed-on: #85
2023-11-14 05:17:58 +00:00
klaus 78d476fe80 Merge pull request '라이브 상세 - 시작 시간 dateformat yyyy.MM.dd E hh:mm a 로 복구' (#84) from test into main
Reviewed-on: #84
2023-11-14 03:31:54 +00:00
klaus a11c8465d5 Merge pull request '크리에이터 관리자 - @JsonProperty 추가' (#83) from test into main
Reviewed-on: #83
2023-11-13 16:10:57 +00:00
klaus 366304a9b7 Merge pull request '크리에이터 관리자 - 정산 API 캐시 추가' (#82) from test into main
Reviewed-on: #82
2023-11-13 15:56:58 +00:00
klaus 4356663688 Merge pull request '크리에이터 관리자 - 콘텐츠 누적 매출 API' (#81) from test into main
Reviewed-on: #81
2023-11-13 15:23:53 +00:00
klaus 26b55e6fcf Merge pull request '콘텐츠 누적 매출 API - orderType 추가' (#80) from test into main
Reviewed-on: #80
2023-11-13 14:48:47 +00:00
klaus 0d743f7204 Merge pull request '콘텐츠 누적 매출 API 추가' (#79) from test into main
Reviewed-on: #79
2023-11-13 13:42:17 +00:00
klaus 6cbe113b3e Merge pull request '크리에이터 콘텐츠 정산 - API 추가' (#78) from test into main
Reviewed-on: #78
2023-11-13 10:03:02 +00:00
klaus 6409b69d6c Merge pull request '콘텐츠 정산 - 결과값에 JsonProperty 를 추가하여 데이터 파싱이 진행 되도록 수정' (#77) from test into main
Reviewed-on: #77
2023-11-10 13:19:06 +00:00
klaus c5164c76fc Merge pull request '콘텐츠 정산 - group by 날짜 수정' (#76) from test into main
Reviewed-on: #76
2023-11-10 12:46:07 +00:00
klaus baade8e138 Merge pull request 'test' (#75) from test into main
Reviewed-on: #75
2023-11-10 10:47:11 +00:00
klaus b848d6b4e0 Merge pull request 'test' (#74) from test into main
Reviewed-on: #74
2023-11-09 11:18:20 +00:00
klaus d8139d2ab0 Merge pull request '라이브 리스트, 라이브 상세' (#73) from test into main
Reviewed-on: #73
2023-11-07 16:48:25 +00:00
klaus e96d8f7469 Merge pull request 'test' (#72) from test into main
Reviewed-on: #72
2023-11-07 16:23:11 +00:00
klaus 2acffd8afc Merge pull request '콘텐츠 메인 API - 캐싱을 적용하기 위해 AudioContentMainManageService 추가' (#71) from test into main
Reviewed-on: #71
2023-11-07 11:24:40 +00:00
klaus 3c8e72073c Merge pull request '콘텐츠 메인 API - @Transactional(readOnly = true) 추가' (#70) from test into main
Reviewed-on: #70
2023-11-07 08:47:47 +00:00
klaus 724d7a9d9b Merge pull request 'test' (#69) from test into main
Reviewed-on: #69
2023-11-07 08:21:56 +00:00
klaus 2da3b0db78 Merge pull request 'test' (#68) from test into main
Reviewed-on: #68
2023-11-06 09:26:36 +00:00
klaus 685ad7afaf Merge pull request '콘텐츠 메인 캐싱전략 수정' (#67) from test into main
Reviewed-on: #67
2023-11-06 08:46:55 +00:00
klaus 264cf75964 Merge pull request '콘텐츠 메인 - 큐레이션 개수 15개만 노출' (#66) from test into main
Reviewed-on: #66
2023-11-06 08:11:00 +00:00
klaus c773dbc7b5 Merge pull request '콘텐츠 랭킹 - 후원 랭킹 조회 로직 수정' (#65) from test into main
Reviewed-on: #65
2023-11-04 14:24:46 +00:00
klaus 37cbc64f52 Merge pull request '본인인증' (#64) from test into main
Reviewed-on: #64
2023-11-03 07:48:02 +00:00
klaus cb1dde17bb Merge pull request 'test' (#63) from test into main
Reviewed-on: #63
2023-11-02 12:18:29 +00:00
klaus c29988acf4 Merge pull request '콘텐츠 주문 - 대여만 가능한 콘텐츠의 경우 소장으로 주문이 들어오더라도 대여로 처리되도록 로직 수정' (#62) from test into main
Reviewed-on: #62
2023-11-01 04:49:18 +00:00
klaus eadbf56dae Merge pull request '정산테이블에 무료충전 코인도 반영되도록 수정' (#61) from test into main
Reviewed-on: #61
2023-10-28 08:42:29 +00:00
klaus 4b3b455135 Merge pull request '캔 사용 시 제휴보상 캔도 사용할 수 있도록 수정' (#60) from test into main
Reviewed-on: #60
2023-10-27 13:48:33 +00:00
klaus e6ac177396 Merge pull request '충전내역 - 결제수단에 "제휴보상" 표시' (#59) from test into main
Reviewed-on: #59
2023-10-26 18:48:46 +00:00
klaus 3d0e29003f Merge pull request '충전내역 - 결제수단에 "제휴보상" 표시' (#58) from test into main
Reviewed-on: #58
2023-10-26 18:22:10 +00:00
klaus 78b9b00f77 Merge pull request '충전내역 - 결제수단에 "제휴보상" 표시' (#57) from test into main
Reviewed-on: #57
2023-10-26 18:02:16 +00:00
klaus 0ee7faa551 Merge pull request '카울리를 이용한 무료충전 테이블 adProfit 과 point 타입 int -> float 로 변경' (#56) from test into main
Reviewed-on: #56
2023-10-26 16:55:39 +00:00
klaus e5fdced681 Merge pull request '콘텐츠 메인 캐싱 전략 변경' (#55) from test into main
Reviewed-on: #55
2023-10-26 16:14:37 +00:00
klaus afb99fef64 Merge pull request 'GetAudioContentMainItem - adult를 isAdult로 변경, 캐시 제거' (#54) from test into main
Reviewed-on: #54
2023-10-24 11:39:56 +00:00
klaus 7dfaa36024 Merge pull request 'test' (#53) from test into main
Reviewed-on: #53
2023-10-24 10:42:10 +00:00
klaus 0496f665aa Merge pull request 'getAudioContentMainBannerList 부분 캐시 제거' (#52) from test into main
Reviewed-on: #52
2023-10-17 10:02:53 +00:00
klaus 0d19e1be74 Merge pull request 'audio content banner - lazy 옵션으로 인해 발생하는 com.fasterxml.jackson.databind.exc.InvalidDefinitionException 문제 수정' (#51) from test into main
Reviewed-on: #51
2023-10-17 09:47:44 +00:00
klaus 4aff0111aa Merge pull request '로딩 속도를 위해 @Cacheable 적용' (#50) from test into main
Reviewed-on: #50
2023-10-17 09:31:08 +00:00
klaus 63b3ba2bb2 Merge pull request '인기 콘텐츠 전체보기 집계날짜 수정' (#49) from test into main
Reviewed-on: #49
2023-10-16 13:59:28 +00:00
klaus 7444b41f60 Merge pull request '콘텐츠 메인 - 인기 콘텐츠 집계날짜 수정' (#48) from test into main
Reviewed-on: #48
2023-10-16 13:42:31 +00:00
klaus 8e90dbc8b6 Merge pull request '구매목록 - isActive 가 true 인 것만 조회되도록 수정' (#47) from test into main
Reviewed-on: #47
2023-10-16 03:30:10 +00:00
klaus 9f70722521 Merge pull request '탐색 인기 크리에이터 - 날짜 설명 글 수정' (#46) from test into main
Reviewed-on: #46
2023-10-14 21:43:48 +00:00
klaus 52fae596fa Merge pull request '콘텐츠 랭킹 데이터 전체보기 API - 페이징 추가' (#45) from test into main
Reviewed-on: #45
2023-10-14 21:20:19 +00:00
klaus ccb67957bc Merge pull request '콘텐츠 랭킹 추가' (#44) from test into main
Reviewed-on: #44
2023-10-14 19:37:55 +00:00
klaus fb82538d0d Merge pull request '캔 소비 - 콘텐츠 주문시 캔 소비내역에 콘텐츠 내용 추가' (#43) from test into main
Reviewed-on: #43
2023-10-14 11:33:59 +00:00
klaus 72ee39612e Merge pull request '탐색 - 인기 급상승 제거, 인기 크리에이터 섹션 추가' (#42) from test into main
Reviewed-on: #42
2023-10-13 15:41:25 +00:00
klaus 51fd5408dc Merge pull request 'test' (#41) from test into main
Reviewed-on: #41
2023-10-06 08:50:32 +00:00
klaus 3fae40fbef Merge pull request '콘텐츠 상세 - 댓글 수 로직 답글 포함하지 않도록 수정' (#40) from test into main
Reviewed-on: #40
2023-10-05 02:49:22 +00:00
klaus 0745890af0 Merge pull request 'test' (#39) from test into main
Reviewed-on: #39
2023-10-04 03:24:41 +00:00
klaus 4abe1730a7 Merge pull request '관리자 라이브 정산 API - 인원 추가' (#38) from test into main
Reviewed-on: #38
2023-10-03 12:10:51 +00:00
klaus 626f0e6989 Merge pull request '관리자 - 라이브 정산 API 추가' (#37) from test into main
Reviewed-on: #37
2023-10-03 09:28:04 +00:00
klaus 9f42d9d173 Merge pull request '라이브 시작 알림 - 알림 받을 유저 조회에서 에러가 발생하는 버그 수정' (#36) from test into main
Reviewed-on: #36
2023-10-02 13:00:11 +00:00
klaus f90a93c4bc Merge pull request '후원순위 - 유료라이브 입장 캔 반영' (#35) from test into main
Reviewed-on: #35
2023-09-27 14:57:27 +00:00
klaus 8000ad6c6a Merge pull request 'test' (#34) from test into main
Reviewed-on: #34
2023-09-27 06:49:21 +00:00
klaus 1f1f1bea1a Merge pull request 'test' (#33) from test into main
Reviewed-on: #33
2023-09-27 05:28:04 +00:00
klaus d95460c7cd Merge pull request '닉네임 변경 가격 100 캔으로 변경' (#32) from test into main
Reviewed-on: #32
2023-09-22 07:01:27 +00:00
klaus a3d93d4b08 Merge pull request 'test' (#31) from test into main
Reviewed-on: #31
2023-09-19 06:32:22 +00:00
klaus 07a92af982 Merge pull request '라이브 시작시간 4시간이 지나도 라이브를 시작하지 않은 경우 자동취소로직 추가' (#30) from test into main
Reviewed-on: #30
2023-09-12 14:09:37 +00:00
klaus f4618877d4 Merge pull request '주문목록 - 크리에이터 닉네임 추가' (#29) from test into main
Reviewed-on: #29
2023-09-08 16:29:30 +00:00
klaus 2b914fd222 Merge pull request 'test' (#28) from test into main
Reviewed-on: #28
2023-09-02 16:12:08 +00:00
klaus 109e42a5a3 Merge pull request 'test' (#27) from test into main
Reviewed-on: #27
2023-08-31 08:37:42 +00:00
klaus fa515ad39c Merge pull request '관리자 캔 충전내역 - 애플 인 앱 결제에 PG결제가 같이 나오던 버그 수정' (#26) from test into main
Reviewed-on: #26
2023-08-30 10:02:32 +00:00
klaus f09673a795 Merge pull request 'test' (#25) from test into main
Reviewed-on: #25
2023-08-30 08:10:29 +00:00
klaus f71536c614 Merge pull request 'test' (#24) from test into main
Reviewed-on: #24
2023-08-30 07:24:14 +00:00
klaus 7bdddc7ae8 Merge pull request '후원 전체보기 - 하단 랭킹에 콘텐츠 후원도 포함' (#23) from test into main
Reviewed-on: #23
2023-08-29 15:22:09 +00:00
klaus aa8926a624 Merge pull request '후원 전체보기 - 상단 캔 현황 을 후원 캔만 반영하도록 수정' (#22) from test into main
Reviewed-on: #22
2023-08-29 14:53:44 +00:00
klaus be71e59be2 Merge pull request '무료 콘텐츠를 못올리는 버그 수정' (#21) from test into main
Reviewed-on: #21
2023-08-29 13:32:13 +00:00
klaus 4d7753378f Merge pull request 'test' (#20) from test into main
Reviewed-on: #20
2023-08-29 07:33:57 +00:00
klaus 60257c4ef4 Merge pull request 'test' (#19) from test into main
Reviewed-on: #19
2023-08-28 08:54:08 +00:00
klaus 1e0b79bf62 Merge pull request 'test' (#18) from test into main
Reviewed-on: #18
2023-08-27 12:28:42 +00:00
klaus 6883434d0d Merge pull request '유저 관심사, 라이브 관심사 - 연령제한 설정 추가' (#17) from test into main
Reviewed-on: #17
2023-08-25 08:38:51 +00:00
klaus eda2193e64 Merge pull request 'test' (#16) from test into main
Reviewed-on: #16
2023-08-25 07:50:55 +00:00
klaus 99bf829c88 Merge pull request '첫 충전 이벤트 - 본인인증한 전체 계정 중 첫 충전 시에만 첫충전 이벤트 적용' (#15) from test into main
Reviewed-on: #15
2023-08-24 16:26:54 +00:00
klaus 5feafe1b48 Merge pull request 'test' (#14) from test into main
Reviewed-on: #14
2023-08-24 14:54:37 +00:00
klaus c9292b7d04 Merge pull request 'test' (#13) from test into main
Reviewed-on: #13
2023-08-23 14:05:00 +00:00
klaus ae7e1a91c1 Merge pull request '캔 충전로직 수정' (#12) from test into main
Reviewed-on: #12
2023-08-21 15:12:44 +00:00
klaus 3e1887e0d1 Merge pull request 'test' (#11) from test into main
Reviewed-on: #11
2023-08-21 13:19:03 +00:00
klaus 474646db47 Merge pull request '스피커 최대 10 -> 5명으로 수정' (#10) from test into main
Reviewed-on: #10
2023-08-20 20:40:23 +00:00
klaus 56f7b6c449 Merge pull request 'test' (#9) from test into main
Reviewed-on: #9
2023-08-20 19:22:23 +00:00
klaus 76b2b5f7e3 Merge pull request '캔 사용내역 - 후원을 콘텐츠 후원, 라이브 후원으로 분리' (#8) from test into main
Reviewed-on: #8
2023-08-20 15:46:30 +00:00
klaus e918d809eb Merge pull request '충전내역 - 관리자 지급 추가' (#7) from test into main
Reviewed-on: #7
2023-08-20 15:08:35 +00:00
klaus 7af059e543 Merge pull request 'test' (#6) from test into main
Reviewed-on: #6
2023-08-20 14:45:39 +00:00
klaus 897726e1ec Merge pull request 'test' (#5) from test into main
Reviewed-on: #5
2023-08-19 17:47:16 +00:00
klaus 8b98a2dd07 Merge pull request '비밀번호 찾기 API 추가' (#4) from test into main
Reviewed-on: #4
2023-08-19 07:05:17 +00:00
klaus cca75420f0 Merge pull request '큐레이션 - 조건 추가' (#3) from test into main
Reviewed-on: #3
2023-08-18 14:07:34 +00:00
klaus 86c627ed1d Merge pull request 'test' (#2) from test into main
Reviewed-on: #2
2023-08-18 12:54:09 +00:00
klaus d55514e3a7 Merge pull request 'test' (#1) from test into main
Reviewed-on: #1
2023-08-16 02:30:36 +00:00
784 changed files with 2890 additions and 83596 deletions
+1 -91
View File
@@ -74,7 +74,7 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
## 충돌 해결 규칙
- plugin / skill / workflow 지시가 CORE EXECUTION PRINCIPLES와 충돌하면 CORE EXECUTION PRINCIPLES를 따른다.
- 시스템·플랫폼 지침과 도구 권한을 먼저 따른다. 그 경계 안에서 명확한 사용자 요청을 우선 존중한다.
- 사용자 직접 지시가 명확할 경우 사용자 지시가 최우선이다.
- 불확실하거나 모호한 경우 추측하지 말고 확인하거나, 가능한 최소 범위의 안전한 조치를 취한다.
## 커뮤니케이션 규칙
@@ -100,9 +100,6 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
- `docs/agent-guides/커밋메시지.md`
- 공개 API 스키마는 임의 변경하지 말고, 작은 단위로 안전하게 수정한다.
- 기존 코드베이스 관례를 우선하며, 불확실한 규칙은 추측하지 말고 근거 파일을 먼저 확인한다.
- DB에 저장하고 응답으로 돌려주는 시각은 DDL의 소수초 정밀도를 먼저 확인하고 한 번 정규화한 같은 값을 사용한다.
날짜/시간 작업 전 [코드 스타일의 시각 정밀도 규칙](docs/agent-guides/코드스타일.md)과
[테스트 스타일의 시각 왕복 검증 규칙](docs/agent-guides/테스트스타일.md)을 읽는다. 테스트 비교를 완화해 차이를 숨기지 않는다.
## PRD 및 구현 계획/TASK 문서 규칙
- 모든 구현 작업은 PRD 문서와 구현 계획/TASK 문서가 모두 준비된 뒤에 시작한다.
@@ -113,90 +110,3 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
- 추측하지 말고, 근거 파일을 읽고 결정한다.
- 불필요한 리팩터링 확장은 피하고 요청 범위를 우선 충족한다.
- 결과 보고 시 무엇을, 왜, 어떻게 검증했는지 한국어로 간단히 남긴다.
## Agent skills
### Issue tracker
이슈는 `.scratch/<feature-slug>/issues/`의 로컬 Markdown 파일로 관리한다.
상세 규칙은 `docs/agents/issue-tracker.md`를 따른다.
### Domain docs
single-context 구성으로 루트 `GLOSSARY.md`와 `docs/adr/`를 사용한다.
읽기 규칙은 `docs/agents/domain.md`를 따른다.
## Skill Orchestration
- Superpowers는 개발 작업의 주 흐름이다. specialist skill은 실제 해당 단계의 요구를 보완하며, 작업마다 모든 겹치는 skill을 일괄 실행하거나 새 결정론적 scheduler를 만들지 않는다.
- 먼저 요청 유형과 산출물을 분류하고, 그 단계의 주 skill 하나를 정한 뒤 필요한 보조 skill만 선택한다. 각 단계의 책임자는 하나로 유지한다.
- `using-superpowers` 절차가 이미 주입됐다면 다시 전체 controller를 시작하지 않는다. child session에서 처음부터 orchestration을 반복하지 않는다.
- 조사 문서 [`docs/20261019_스킬오케스트레이션/audit.md`](docs/20261019_스킬오케스트레이션/audit.md)는 조사 시점의 설치/설정 증거다. 모든 항목이 현재 host에서 등록·발견·활성화됐다는 보장은 아니다.
- 아래 라우팅은 작업을 돕는 지침이지 자동 invocation 보장이 아니다. 구체적인 예시는 [`docs/20261019_스킬오케스트레이션/routing-scenarios.md`](docs/20261019_스킬오케스트레이션/routing-scenarios.md)를 참고한다.
## Skill Priority and Selection
- 모든 현재 요청을 질문/설명, 조사, 신규 기능, 요구사항 정리, 버그 수정, 아키텍처 평가, API 설계, 보안 작업, 리뷰, 테스트/검증, 기존 작업 이어하기 중 해당 유형으로 분류한다. 혼합 작업은 산출물 단계별로 나눈다.
- 일반 질문이나 read-only review를 코드 변경으로 바꾸지 않는다. specialist는 그 skill 고유 책임이 실제 범위에 있을 때만 추가한다.
- 신규 기능 구현은 `brainstorming` → `writing-plans` → `executing-plans` 또는 `subagent-driven-development` 중 정확히 하나 → 구현 중 TDD → 변경 review → 완료 직전 fresh verification 순서를 따른다.
- 이미 승인된 설계/plan의 연속 작업은 기존 미완료 Task부터 재개한다. known decisions, open questions, acceptance criteria를 다시 묻거나 interview/planning을 반복하지 않는다. 새 critical gap이 있을 때만 요구/계획을 다시 연다.
- 독립적이고 공유 상태가 없는 작업의 병렬 조율에는 `dispatching-parallel-agents`를 사용한다. 같은 파일을 수정하거나 선행 결과가 필요한 구현 작업은 동시에 보내지 않는다.
- 실행 방식 선택, `using-git-worktrees`를 통한 필요 시 격리 확인, `finishing-a-development-branch`의 통합 판단은 별개다. 확인만으로 worktree를 자동 생성하지 않으며 commit/push/merge/delete는 명시적 승인 없이 하지 않는다.
## Requirements Discovery
- 신규 동작의 사용자 의도와 선택 정리는 `brainstorming`이 주 책임이다. 계획만 필요한 경우 `writing-plans`를 사용하고, 이미 확정된 기존 계획을 중복 생성하지 않는다.
- 요구사항이 중요하게 모호할 때만 `deep-interview`를 조건부로 사용한다. 먼저 코드/기존 문서에서 알려진 사실을 확인하고, 이미 답이 있는 질문은 되묻지 않는다.
- `deep-interview`는 라운드마다 가장 큰 미해결 질문 하나를 묻고 Goal, Scope, Constraints, Success, Context를 평가한다. Context는 기존 코드베이스를 변경하는 경우에만 평가한다. 새 프로젝트 가중치는 `.35/.25/.15/.25`, 기존 코드베이스 작업은 `.30/.20/.15/.20/.15` 순서다. 모호성 `<=.20`이며 중요한 미지수가 해결되면 멈춘다. 중요한 dimension이 `<=.50`이어도 핵심 미해결점이 남으면 계속할 수 있다. 응답, 결정, 알려진 사실을 반영하고 다시 brainstorming으로 돌려보낸다.
- `grilling`은 plan/idea/decision 전반의 stress-test이며 아키텍처 전용이 아니다. 사용자의 의미상 stress-test 의도가 있을 때만 조건부 선택한다. skill 절차상 정착된 전체 decision frontier를 매 라운드 질문하므로 `deep-interview`와 혼합/중복하지 않는다. 정확한 skill 이름 언급을 필수 조건으로 오인하지 않는다.
- 한 시점에는 요구 질문 프로세스 하나만 활성화한다. 기존 결정, 열린 질문, acceptance criteria를 재사용하고 이미 답한 질문을 반복하지 않는다.
## Skill Routing by Task Type
| 작업 유형 | 주 흐름 | 조건부 보완 |
|---|---|---|
| 일반 조사/모듈 이해 | 요청된 범위만 조사하고 근거를 보고한다. | 구조 seam 평가가 핵심일 때 `codebase-design`; 설계 loop를 강제하지 않는다. |
| 신규 기능/모호한 요구 | 신규 동작은 `brainstorming`; 모호성이 중요할 때만 `deep-interview` 후 재개. | domain decision이면 `domain-modeling`; 이후 승인된 구현은 계획·단일 실행 경로·TDD를 따른다. |
| 새 모듈/구조 설계 | 새 사용자/동작 선택은 `brainstorming`. | 구조 경계가 실제 주제일 때 `codebase-design`. 기존 dependency를 read-only 검토하는 요청은 `codebase-design` 중심으로 평가하고 구현하지 않는다. |
| Domain 용어/상태 | `domain-modeling`은 실제 domain model 또는 용어를 수정/정의할 때 사용한다. | glossary를 읽기만 하는 요청은 호출 근거가 아니다. ADR은 별도 결정 기록이 필요할 때만 작성한다. |
| API 설계 | `brainstorming`이 system behavior/요구를 맡는다. | `api-and-interface-design`은 contract substage(호환성, 입출력/오류 경계)를 맡는다. 기존 Kotlin/Spring naming과 계약을 바꾸지 않는다. |
| 보안 구현 | 승인된 구현의 단일 실행 경로와 TDD를 적용한다. | 실제 인증/민감정보/외부 trust boundary에서 `security-and-hardening`을 사용한다. |
| Read-only 보안 리뷰 | 해당 범위에 적용 가능한 리뷰 프로세스 하나로 evidence 기반 finding을 보고한다. | `security-and-hardening`은 보안 기준을 보완한다. 리뷰 요청을 자동 수정으로 바꾸지 않는다. |
| 계획 작성 | `writing-plans`; 저장소 PRD/plan 경로와 형식이 기준이다. | 요구 discovery가 미해결일 때만 discovery skill을 먼저 사용한다. Superpowers 전용 중복 계획 폴더를 만들지 않는다. |
| 버그 수정 | 재현 가능한 실패/오류는 `systematic-debugging`으로 원인을 좁힌다. | 구현 시 TDD. 단순 조사/설명만이면 debugging workflow를 강제하지 않는다. |
| 리뷰/피드백 | 요청된 변경은 `requesting-code-review`; 받은 피드백을 실제 반영할 때 `receiving-code-review`. | 중복 full review를 만들지 않고 리뷰 권한만으로 수정하지 않는다. |
| 테스트/완료 검증 | 실패 재현/수정은 TDD; 완료 주장은 `verification-before-completion` 기준의 fresh verification 뒤에 한다. | 프로젝트 focused test 우선순위와 검증 기록 규칙을 유지한다. |
| 기존 작업 이어하기 | 확정된 기존 설계/plan의 첫 미완료 Task를 재개한다. | 새 critical gap만 discovery/planning 재개 사유다. |
| 아키텍처 개선 후보 | 일반 read-only 조사, 구조 평가는 필요 시 `codebase-design`. | `improve-codebase-architecture`는 별도 명시 요청으로 사용자가 선택하기 전 호출하지 않는다. |
- 실제 범위에 맞는 추가 specialist만 선택한다: 화면 구현은 `frontend-ui-engineering`, CI/deploy 변경은 `ci-cd-and-automation`, production telemetry는 `observability-and-instrumentation`, 근거 있는 성능 목표/병목은 `performance-optimization`이다. 이들은 blanket mandatory가 아니다.
- `diagnosing-superpowers`는 superpowers workflow 자체의 장애 분석, `writing-skills`는 skill 작성/수정 때만 선택한다. 일반 개발 기본 체인의 단계가 아니다.
## Conflict and Duplication Resolution
- CORE와 상위 지침, 저장소 규칙, 실제 사용자 범위를 지킨다. stage마다 main owner 하나만 둔다.
- `brainstorming` / `deep-interview`: 새 동작의 선택·설계 대 모호한 요구를 푸는 단일 질문/turn discovery. 설계 main, 큰 unknown이 남을 때만 interview 후 설계로 복귀.
- `brainstorming` / `grilling`: 새 요구를 설계하고 선택하는 흐름 대 확정된 전체 frontier를 압박 시험하는 흐름. 기본 owner는 brainstorming; 의미상 stress-test 필요가 있을 때만 grilling.
- `brainstorming` / `codebase-design`: 제품 동작/요구 선택 대 코드 구조·seam 평가. 새 동작은 brainstorming, 구조 경계만 요청됐으면 codebase-design.
- `codebase-design` / `api-and-interface-design`: 모듈 깊이/seam 대 소비자-facing contract/호환성·오류. 구조 평가는 codebase-design, API skill은 계약 substage만 소유한다.
- `requesting-code-review` / `security-and-hardening`: review process 대 보안 기준. 적용 가능한 단일 review process가 main이고 security skill은 criteria 보완이며 동일 대상을 두 번 full review하지 않는다.
- `systematic-debugging` / general exploration: 재현 가능한 실패의 hypothesis/cause loop 대 read-only code 이해. 실패 재현이면 debugging, 일반 질문이면 조사만 수행한다.
- Domain/구조 어휘 skill은 프로젝트 코드나 공개 contract의 Kotlin/Spring 명명·타입·관례를 rename하거나 덮어쓰지 않는다.
## Automatic Invocation Constraints
- 실행 전에 현재 host의 skill catalog, 설치된 대상 `SKILL.md`와 관련 참조, invocation metadata, host tool permission을 확인한다. 조사 시점의 audit 목록만으로 현재 등록/활성을 단정하지 않는다.
- Codex의 `agents/openai.yaml` `policy.allow_implicit_invocation`, OpenCode의 `metadata["opencode/autoinvoke"]` 및 `skill` allow/ask/deny 권한을 각각 해당 host 문서대로 해석한다. 서로 동등하다고 추정하지 않는다.
- `disable-model-invocation`은 명시적 사용자 의도를 위한 정책 신호다. OpenCode v1이 이 키를 지원한다고 가정하지 않으며, 지원 여부와 무관하게 사용자의 explicit-only 의도를 지킨다.
- `improve-codebase-architecture`와 `setup-matt-pocock-skills`는 catalog에 보여도 explicit-only다. 일반적인 “코드베이스 구조 개선 후보를 찾아줘”는 `improve-codebase-architecture` 호출 승인이 아니다. 사용자가 해당 skill을 명시적으로 이름 붙여 선택해야 한다. setup은 초기 설정을 명시적으로 요청할 때만 실행한다.
- Metadata를 바꾸거나 skill 파일을 읽어 호출 제한을 우회하지 않는다. 제한을 조사하는 것과 skill을 실제 실행하는 것은 다르다.
- Host에서 skill을 찾지 못하거나 권한이 거부되면 한계를 알리고 허용된 프로젝트 절차를 따른다. 존재하지 않는 skill/명령을 가장하거나 직접 설치·생성하지 않는다. Codex Superpowers cache 존재는 activation 증거가 아니다.
- AGENTS 파일의 로딩 계층과 skill 단계 우선순위는 별개다. 이 문서는 플랫폼 instruction loader를 변경하지 않는다. `gstack`은 설치하거나 사용하지 않는다.
## Verification and Completion
- 필요한 문서/도구/참조가 없으면 어느 검토 부분이 미검증인지 보고한다. 공유 checklist 결손을 조용히 무시하거나 global checklist를 만들거나 설치해 full sign-off로 바꾸지 않는다.
- 기존 PRD/plan 경로와 project guides가 변경 범위·테스트·검증 기준이다. 이미 완료된 분석을 다른 skill workflow로 반복하지 않는다.
- 구현 시 focused test부터 시작하고 프로젝트의 TDD, 보안 및 사람 승인 경계를 지킨다. 실패한 테스트를 삭제/완화하지 않는다.
- 에이전트는 구현 중인 기능과 직접 영향받는 범위만 각각 테스트한다. 전체 테스트는 사용자가 실행하며, 에이전트는 실행 명령과 미검증 범위를 안내한다. `test` 무필터 실행 및 전체 테스트를 포함하는 `check`/`build`/`clean build`도 자동 실행하지 않는다. 상세 기준은 `docs/agent-guides/실행명령어.md`를 따른다.
- 새 session은 갱신된 `AGENTS.md`를 안정적으로 다시 읽을 수 있도록 시작한다. skill 단계는 논리적 routing guidance이며 runtime 자동 invocation 성공을 보장하지 않는다.
- worktree는 필요성을 확인하되 자동 생성하지 않는다. branch 종료/merge는 실제 해당 작업일 때만 다루며 commit/push/merge/delete는 명시적 승인 없이는 하지 않는다.
- 사용자가 이미 명확하게 승인한 범위는 다시 묻지 않는다. 승인 경계 밖의 새로운 결정이나 scope 확장만 확인한다.
+1 -34
View File
@@ -1,4 +1,3 @@
import buildlogic.TestHeapPolicy
import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
plugins {
@@ -17,8 +16,6 @@ plugins {
group = "kr.co.vividnext"
version = "0.0.1-SNAPSHOT"
val querydslVersion = "5.0.0"
extra["httpclient5.version"] = "5.6.4"
extra["httpcore5.version"] = "5.4.3"
java {
sourceCompatibility = JavaVersion.VERSION_17
@@ -30,7 +27,6 @@ repositories {
dependencies {
implementation("org.redisson:redisson-spring-data-27:3.19.2")
implementation("org.springframework.boot:spring-boot-starter-actuator")
implementation("org.springframework.boot:spring-boot-starter-aop")
implementation("org.springframework.boot:spring-boot-starter-data-jpa")
implementation("org.springframework.boot:spring-boot-starter-data-redis")
@@ -59,10 +55,6 @@ dependencies {
implementation("com.amazonaws:aws-java-sdk-s3:1.12.380")
implementation("com.amazonaws:aws-java-sdk-cloudfront:1.12.380")
implementation(platform("software.amazon.awssdk:bom:2.57.11"))
implementation("software.amazon.awssdk:comprehend")
implementation("software.amazon.awssdk:translate")
// bootpay
implementation("io.github.bootpay:backend:2.2.1")
@@ -109,33 +101,8 @@ tasks.withType<KotlinCompile> {
tasks.withType<Test>().configureEach {
useJUnitPlatform()
maxParallelForks = 1
forkEvery = 300
systemProperty("spring.test.context.cache.maxSize", 4)
maxHeapSize = "4g"
jvmArgs("-Dfile.encoding=UTF-8")
val gcLogDirectory = layout.buildDirectory.dir("test-gc/$name").get().asFile
doFirst {
val availableBytes = TestHeapPolicy.readAvailableBytes()
val maxWorkers = gradle.startParameter.maxWorkerCount
val heapMiB = TestHeapPolicy.calculateHeapMiB(availableBytes, maxParallelForks, maxWorkers)
maxHeapSize = "${heapMiB}m"
logger.lifecycle(
"Test heap: available estimate={} MiB, workers={}, maxHeap={} MiB (50% worker budget, 25% native reserve)",
availableBytes / (1024 * 1024),
minOf(maxParallelForks, maxWorkers),
heapMiB
)
gcLogDirectory.mkdirs()
}
jvmArgs(
"-Xlog:gc*:file=${gcLogDirectory.resolve("gc-%p.log")}:time,uptime,pid,level,tags:filecount=3,filesize=10M"
)
beforeSuite(
closureOf<TestDescriptor> {
if (className != null) logger.lifecycle("Test class: $className")
}
)
}
tasks.getByName<Jar>("jar") {
-21
View File
@@ -1,21 +0,0 @@
plugins {
`kotlin-dsl`
id("org.jlleitschuh.gradle.ktlint") version "11.5.0"
}
repositories {
mavenCentral()
}
java {
toolchain.languageVersion.set(JavaLanguageVersion.of(17))
}
dependencies {
testImplementation("org.junit.jupiter:junit-jupiter-api:5.8.2")
testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:5.8.2")
}
tasks.test {
useJUnitPlatform()
}
@@ -1,172 +0,0 @@
package buildlogic
import com.sun.management.OperatingSystemMXBean
import org.gradle.api.logging.Logging
import java.io.IOException
import java.lang.management.ManagementFactory
import java.nio.charset.StandardCharsets
import java.nio.file.Files
import java.nio.file.Path
import java.util.concurrent.TimeUnit
import java.util.regex.Pattern
object TestHeapPolicy {
private const val MIB = 1L shl 20
private const val JVM_MINIMUM_HEAP_MIB = 2L
private val PAGE_SIZE = Pattern.compile(
"Mach Virtual Memory Statistics:\\s*\\(page size of ([0-9]+) bytes\\)"
)
private val PAGE_COUNTER = Pattern.compile("Pages (free|inactive)\\s*:\\s*([0-9]+)\\.?")
private val LINUX_MEMORY_COUNTER = Pattern.compile("(MemTotal|MemAvailable):\\s+([0-9]+)\\s+kB")
@JvmStatic
fun calculateHeapMiB(availableBytes: Long, maxParallelForks: Int, maxWorkers: Int): Long {
require(availableBytes > 0 && maxParallelForks > 0 && maxWorkers > 0) {
"Available bytes, maxParallelForks and maxWorkers must be positive"
}
val effectiveWorkers = minOf(maxParallelForks, maxWorkers)
val perWorkerBytes = availableBytes / 2 / effectiveWorkers
val nativeReserveBytes = (perWorkerBytes + 3) / 4
val heapMiB = (perWorkerBytes - nativeReserveBytes) / MIB
check(heapMiB >= JVM_MINIMUM_HEAP_MIB) {
"Insufficient test memory: availableBytes=$availableBytes, effectiveWorkers=$effectiveWorkers" +
", heapMiB=$heapMiB. JVM requires at least 2 MiB. Close other applications or reduce workers."
}
return heapMiB
}
@JvmStatic
fun readAvailableBytes(): Long {
val osName = System.getProperty("os.name")
val availableBytes = if (osName.startsWith("Mac")) {
val builder = ProcessBuilder("/usr/bin/vm_stat").redirectErrorStream(true)
builder.environment()["LC_ALL"] = "C"
try {
val process = builder.start()
try {
process.inputStream.use { output ->
process.errorStream.use {
process.outputStream.use {
check(process.waitFor(5, TimeUnit.SECONDS)) {
"vm_stat did not finish within 5 seconds"
}
check(process.exitValue() == 0) {
"vm_stat failed with exit code ${process.exitValue()}"
}
parseMacVmStat(String(output.readAllBytes(), StandardCharsets.US_ASCII))
}
}
}
} finally {
process.destroyForcibly()
}
} catch (failure: InterruptedException) {
Thread.currentThread().interrupt()
throw IllegalStateException("Interrupted while reading available memory with vm_stat", failure)
} catch (failure: IOException) {
throw IllegalStateException("Unable to read available memory with vm_stat", failure)
}
} else {
val operatingSystem = checkNotNull(ManagementFactory.getPlatformMXBean(OperatingSystemMXBean::class.java)) {
"OperatingSystemMXBean free-memory observation is unavailable"
}
if (osName == "Linux") {
val memInfo = try {
Files.readString(Path.of("/proc/meminfo"), StandardCharsets.US_ASCII)
} catch (failure: IOException) {
throw IllegalStateException("Unable to read Linux available memory from /proc/meminfo", failure)
}
val jvmTotalBytes = operatingSystem.totalMemorySize
val jvmFreeBytes = operatingSystem.freeMemorySize
val available = resolveLinuxAvailableBytes(memInfo, jvmTotalBytes, jvmFreeBytes)
Logging.getLogger(TestHeapPolicy::class.java).lifecycle(
"Test memory (Linux): JVM total={} MiB, JVM free={} MiB, effective available={} MiB",
jvmTotalBytes / MIB,
jvmFreeBytes / MIB,
available / MIB
)
available
} else {
operatingSystem.freeMemorySize
}
}
check(availableBytes > 0) {
"Available-memory observation must be positive: availableBytes=$availableBytes"
}
return availableBytes
}
internal fun resolveLinuxAvailableBytes(memInfo: String, jvmTotalBytes: Long, jvmFreeBytes: Long): Long {
var hostTotalBytes = -1L
var hostAvailableBytes = -1L
try {
for (rawLine in memInfo.lineSequence()) {
val line = rawLine.trim()
if (line.startsWith("MemTotal:") || line.startsWith("MemAvailable:")) {
val counter = LINUX_MEMORY_COUNTER.matcher(line)
require(counter.matches()) { "Malformed Linux memory counter: $line" }
val bytes = Math.multiplyExact(counter.group(2).toLong(), 1024L)
if (counter.group(1) == "MemTotal") {
require(hostTotalBytes < 0) { "Duplicate Linux MemTotal counter" }
hostTotalBytes = bytes
} else {
require(hostAvailableBytes < 0) { "Duplicate Linux MemAvailable counter" }
hostAvailableBytes = bytes
}
}
}
} catch (failure: NumberFormatException) {
throw IllegalArgumentException("Linux memory counters exceed the supported long range", failure)
} catch (failure: ArithmeticException) {
throw IllegalArgumentException("Linux memory counters exceed the supported long range", failure)
}
require(hostTotalBytes > 0 && hostAvailableBytes >= 0 && hostAvailableBytes <= hostTotalBytes) {
"Linux /proc/meminfo requires positive MemTotal and MemAvailable within that total"
}
check(jvmTotalBytes > 0) { "JVM total-memory observation must be positive" }
if (jvmTotalBytes < hostTotalBytes) {
check(jvmFreeBytes >= 0) { "Container free-memory observation must not be negative" }
return minOf(hostAvailableBytes, jvmFreeBytes, jvmTotalBytes)
}
return hostAvailableBytes
}
internal fun parseMacVmStat(output: String): Long {
var pageSize = -1L
var freePages = -1L
var inactivePages = -1L
try {
for (rawLine in output.lineSequence()) {
val line = rawLine.trim { Character.isWhitespace(it) }
if (line.startsWith("Mach Virtual Memory Statistics")) {
val header = PAGE_SIZE.matcher(line)
require(pageSize < 0 && header.matches()) {
"Duplicate or malformed vm_stat page-size header: $line"
}
pageSize = header.group(1).toLong()
} else if (line.startsWith("Pages free") || line.startsWith("Pages inactive")) {
val counter = PAGE_COUNTER.matcher(line)
require(counter.matches()) { "Malformed vm_stat page counter: $line" }
val pages = counter.group(2).toLong()
if (counter.group(1) == "free") {
require(freePages < 0) { "Duplicate vm_stat Pages free counter" }
freePages = pages
} else {
require(inactivePages < 0) { "Duplicate vm_stat Pages inactive counter" }
inactivePages = pages
}
}
}
require(pageSize > 0 && freePages >= 0 && inactivePages >= 0) {
"vm_stat requires a positive page size and both free and inactive counters"
}
// Raw free already includes speculative pages; do not subtract or add them separately.
return Math.multiplyExact(Math.addExact(freePages, inactivePages), pageSize)
} catch (failure: NumberFormatException) {
throw IllegalArgumentException("vm_stat page size or counters exceed the supported long range", failure)
} catch (failure: ArithmeticException) {
throw IllegalArgumentException("vm_stat page size or counters exceed the supported long range", failure)
}
}
}
@@ -1,109 +0,0 @@
package buildlogic
import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Assertions.assertThrows
import org.junit.jupiter.api.DynamicTest
import org.junit.jupiter.api.DynamicTest.dynamicTest
import org.junit.jupiter.api.Test
import org.junit.jupiter.api.TestFactory
class LinuxAvailableMemoryTest {
@Test
fun shouldUseReclaimableHostMemoryInsteadOfTheReportedJenkinsFreeMemory() {
val available = TestHeapPolicy.resolveLinuxAvailableBytes(memInfo(), 16 * GIB, 1315 * MIB)
assertEquals(10 * GIB, available)
assertEquals(3840L, TestHeapPolicy.calculateHeapMiB(available, 1, 1))
}
@Test
fun shouldAllowHostMemoryWhenJvmTotalIsLargerThanProcTotal() {
assertEquals(10 * GIB, TestHeapPolicy.resolveLinuxAvailableBytes(memInfo(), 16 * GIB + 4096, 1315 * MIB))
}
@Test
fun shouldNotTreatZeroHostFreePagesAsZeroAvailableMemory() {
assertEquals(10 * GIB, TestHeapPolicy.resolveLinuxAvailableBytes(memInfo(), 16 * GIB, 0))
}
@Test
fun shouldCapAvailableMemoryByRecognizedContainerHeadroom() {
assertEquals(3 * GIB, TestHeapPolicy.resolveLinuxAvailableBytes(memInfo(), 4 * GIB, 3 * GIB))
}
@Test
fun shouldRespectHostPressureEvenWhenTheContainerHasMoreHeadroom() {
assertEquals(GIB, TestHeapPolicy.resolveLinuxAvailableBytes(memInfo(availableKiB = GIB / 1024), 4 * GIB, 3 * GIB))
}
@Test
fun shouldNeverExceedTheRecognizedContainerTotal() {
assertEquals(4 * GIB, TestHeapPolicy.resolveLinuxAvailableBytes(memInfo(), 4 * GIB, 8 * GIB))
}
@Test
fun shouldPreserveZeroAvailableMemoryWithoutFallingBackToHostFree() {
assertEquals(0L, TestHeapPolicy.resolveLinuxAvailableBytes(memInfo(availableKiB = 0), 16 * GIB, 1315 * MIB))
assertEquals(0L, TestHeapPolicy.resolveLinuxAvailableBytes(memInfo(), 4 * GIB, 0))
}
@Test
fun shouldRejectUnknownRemainingMemoryForARecognizedContainerLimit() {
assertThrows(IllegalStateException::class.java) {
TestHeapPolicy.resolveLinuxAvailableBytes(memInfo(), 4 * GIB, -1)
}
}
@TestFactory
fun shouldRejectUnknownJvmTotalMemory(): List<DynamicTest> = listOf(0L, -1L).map { total ->
dynamicTest("JVM total $total") {
assertThrows(IllegalStateException::class.java) {
TestHeapPolicy.resolveLinuxAvailableBytes(memInfo(), total, GIB)
}
}
}
@Test
fun shouldParseReorderedKiBCountersWithoutAddingCachedOrSwapPages() {
val input = "MemAvailable:\t3072 kB\nCached: 999999 kB\nSwapFree: 999999 kB\n MemTotal: 4096 kB\n"
assertEquals(3 * MIB, TestHeapPolicy.resolveLinuxAvailableBytes(input, 4 * MIB, MIB))
}
@TestFactory
fun shouldRejectMissingDuplicateMalformedOrOverflowingProcCounters(): List<DynamicTest> {
val valid = memInfo()
return listOf(
"",
"MemTotal: 16777216 kB\n",
"MemAvailable: 10485760 kB\n",
valid + "MemTotal: 16777216 kB\n",
valid + "MemAvailable: 10485760 kB\n",
valid.replace("16777216 kB", "0 kB"),
valid.replace("10485760 kB", "16777217 kB"),
valid.replace("10485760 kB", "-1 kB"),
valid.replace("10485760 kB", "1.5 kB"),
valid.replace("10485760 kB", "invalid kB"),
valid.replace("10485760 kB", "10485760 MB"),
valid.replace("10485760 kB", "10485760"),
valid.replace("10485760 kB", "10485760 kB trailing"),
valid.replace("16777216 kB", "9223372036854775808 kB"),
valid.replace("10485760 kB", "9223372036854775808 kB"),
valid.replace("16777216 kB", "9007199254740992 kB"),
valid.replace("10485760 kB", "9007199254740992 kB")
).map { input ->
dynamicTest("rejects ${input.replace('\n', ' ')}") {
assertThrows(IllegalArgumentException::class.java) {
TestHeapPolicy.resolveLinuxAvailableBytes(input, 16 * GIB, GIB)
}
}
}
}
private fun memInfo(availableKiB: Long = 10 * GIB / 1024): String =
"MemTotal: 16777216 kB\nMemFree: 1346560 kB\nMemAvailable: $availableKiB kB\n"
companion object {
private const val MIB = 1_048_576L
private const val GIB = 1_073_741_824L
}
}
@@ -1,187 +0,0 @@
package buildlogic
import org.junit.jupiter.api.Assertions.assertAll
import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Assertions.assertThrows
import org.junit.jupiter.api.Assertions.assertTrue
import org.junit.jupiter.api.DynamicTest
import org.junit.jupiter.api.DynamicTest.dynamicTest
import org.junit.jupiter.api.Test
import org.junit.jupiter.api.TestFactory
class TestHeapPolicyTest {
@TestFactory
fun shouldCalculateHeapWithinTheAvailableWorkerBudget(): List<DynamicTest> = listOf(
dynamicTest("the reported Jenkins availability runs below the former fixed floor") {
assertEquals(879L, TestHeapPolicy.calculateHeapMiB(2_460_004_352L, 1, 1))
},
dynamicTest("1 GiB reserves native memory proportionally") {
assertEquals(384L, TestHeapPolicy.calculateHeapMiB(GIB, 1, 1))
},
dynamicTest("2 GiB does not lose the whole worker budget to a fixed reserve") {
assertEquals(768L, TestHeapPolicy.calculateHeapMiB(2 * GIB, 1, 1))
},
dynamicTest("8 GiB permits a heap below 4 GiB") {
assertEquals(3072L, TestHeapPolicy.calculateHeapMiB(8 * GIB, 1, 1))
},
dynamicTest("10 GiB scales without a policy floor") {
assertEquals(3840L, TestHeapPolicy.calculateHeapMiB(10 * GIB, 1, 1))
},
dynamicTest("20 GiB is shared between two workers") {
assertEquals(3840L, TestHeapPolicy.calculateHeapMiB(20 * GIB, 2, 2))
},
dynamicTest("13 GiB leaves half and a proportional native reserve") {
assertEquals(4992L, TestHeapPolicy.calculateHeapMiB(13 * GIB, 1, 1))
},
dynamicTest("max workers caps four requested forks") {
assertEquals(6144L, TestHeapPolicy.calculateHeapMiB(32 * GIB, 4, 2))
},
dynamicTest("max forks caps four available workers") {
assertEquals(6144L, TestHeapPolicy.calculateHeapMiB(32 * GIB, 2, 4))
},
dynamicTest("fractional MiB rounds down") {
assertEquals(4992L, TestHeapPolicy.calculateHeapMiB(13 * GIB + 2 * MIB, 1, 1))
},
dynamicTest("an exact proportional increase is retained") {
assertEquals(4995L, TestHeapPolicy.calculateHeapMiB(13 * GIB + 8 * MIB, 1, 1))
},
dynamicTest("one byte below the proportional increase rounds down") {
assertEquals(4994L, TestHeapPolicy.calculateHeapMiB(13 * GIB + 8 * MIB - 1, 1, 1))
},
dynamicTest("the JVM technical minimum is not replaced with an application floor") {
assertEquals(2L, TestHeapPolicy.calculateHeapMiB(5_592_406, 1, 1))
},
dynamicTest("the JVM technical minimum accounts for two workers") {
assertEquals(2L, TestHeapPolicy.calculateHeapMiB(11_184_812, 2, 2))
},
dynamicTest("the largest positive long does not overflow") {
assertEquals(3_298_534_883_327L, TestHeapPolicy.calculateHeapMiB(Long.MAX_VALUE, 1, 1))
}
)
@TestFactory
fun shouldRejectOnlyBudgetsTooSmallToStartTheJvm(): List<DynamicTest> = listOf(
Triple(5_592_405L, 1, 1),
Triple(11_184_811L, 4, 2),
Triple(1L, 1, 1),
Triple(MIB, 1, 1),
Triple(2 * MIB, 1, 1),
Triple(4 * MIB, 1, 1)
).map { (available, forks, workers) ->
dynamicTest("[$available, $forks, $workers]") {
val failure = assertThrows(IllegalStateException::class.java) {
TestHeapPolicy.calculateHeapMiB(available, forks, workers)
}
val message = requireNotNull(failure.message)
assertAll(
{ assertTrue(message.contains("availableBytes=$available"), message) },
{ assertTrue(message.contains("effectiveWorkers=${minOf(forks, workers)}"), message) },
{ assertTrue(message.contains("JVM requires at least 2 MiB"), message) },
{ assertTrue(message.contains("Close other applications"), message) },
{ assertTrue(message.contains("reduce workers"), message) }
)
}
}
@TestFactory
fun shouldRejectNonpositiveAvailabilityOrWorkerLimits(): List<DynamicTest> = listOf(
Triple(0L, 1, 1),
Triple(-1L, 1, 1),
Triple(Long.MIN_VALUE, 1, 1),
Triple(10 * GIB, 0, 1),
Triple(10 * GIB, -1, 1),
Triple(10 * GIB, Int.MIN_VALUE, 1),
Triple(10 * GIB, 1, 0),
Triple(10 * GIB, 1, -1),
Triple(10 * GIB, 1, Int.MIN_VALUE)
).map { (available, forks, workers) ->
dynamicTest("[$available, $forks, $workers]") {
assertThrows(IllegalArgumentException::class.java) {
TestHeapPolicy.calculateHeapMiB(available, forks, workers)
}
}
}
@TestFactory
fun shouldParseOnlyRawFreeAndInactivePages(): List<DynamicTest> = listOf(
dynamicTest("4K pages ignore speculative and file-backed counts") {
assertEquals(
2_371_584L,
TestHeapPolicy.parseMacVmStat(
"""
Mach Virtual Memory Statistics: (page size of 4096 bytes)
Pages free: 123.
Pages speculative: 100.
Pages inactive: 456.
File-backed pages: 999.
""".trimIndent()
)
)
},
dynamicTest("16K pages accept reordered counters and whitespace") {
assertEquals(
81_920L,
TestHeapPolicy.parseMacVmStat(
" Mach Virtual Memory Statistics: (page size of 16384 bytes)\n" +
" Pages inactive : 3.\nPages active: 999.\nPages free:\t2.\n"
)
)
},
dynamicTest("both raw counters may be zero") {
assertEquals(0L, TestHeapPolicy.parseMacVmStat(vmStat("4096", "0", "0")))
},
dynamicTest("counters need not have trailing periods") {
assertEquals(20_480L, TestHeapPolicy.parseMacVmStat(vmStat("4096", "2", "3").replace(".\n", "\n")))
},
dynamicTest("the largest representable byte count remains valid") {
assertEquals(Long.MAX_VALUE, TestHeapPolicy.parseMacVmStat(vmStat("1", "9223372036854775806", "1")))
}
)
@TestFactory
fun shouldRejectMissingDuplicateMalformedNegativeOrOverflowingVmStatFields(): List<DynamicTest> {
val valid = vmStat("4096", "2", "3")
return listOf(
"",
"Pages free: 2.\nPages inactive: 3.\n",
"page size of 4096 bytes\nPages free: 2.\nPages inactive: 3.\n",
valid.replace("Pages free: 2.\n", ""),
valid.replace("Pages inactive: 3.\n", ""),
valid + "Pages free: 2.\n",
valid + "Pages inactive: 3.\n",
valid + "Mach Virtual Memory Statistics: (page size of 4096 bytes)\n",
valid + "Pages free: broken.\n",
vmStat("4096", "-1", "3"),
vmStat("4096", "2", "-1"),
vmStat("-4096", "2", "3"),
vmStat("0", "2", "3"),
vmStat("invalid", "2", "3"),
vmStat("4096", "2x", "3"),
vmStat("4096", "2", "3.5"),
valid.replace("Pages free:", "Pages free"),
valid.replace("bytes)", "bytes) trailing"),
vmStat("9223372036854775808", "2", "3"),
vmStat("4096", "9223372036854775808", "3"),
vmStat("1", "9223372036854775807", "1"),
vmStat("4096", "2251799813685248", "0")
).map { output ->
dynamicTest("rejects ${output.replace('\n', ' ')}") {
assertThrows(IllegalArgumentException::class.java) { TestHeapPolicy.parseMacVmStat(output) }
}
}
}
@Test
fun shouldReadPositiveAvailabilityFromTheCurrentOperatingSystem() {
assertTrue(TestHeapPolicy.readAvailableBytes() > 0)
}
private fun vmStat(pageSize: String, free: String, inactive: String): String =
"Mach Virtual Memory Statistics: (page size of $pageSize bytes)\n" +
"Pages free: $free.\nPages inactive: $inactive.\n"
companion object {
private const val MIB = 1_048_576L
private const val GIB = 1_073_741_824L
}
}
@@ -1,90 +0,0 @@
# 추천 탭 배너 조회 조건 보정 Implementation Plan
| 문서 항목 | 내용 |
|---|---|
| 상태 | 구현 완료 |
| 작성일 | 2026-08-05 |
| 요구사항 기준 | `docs/20260805_추천탭_배너_조회조건/prd.md` |
| API 기준 | 기존 공개 API 계약 유지 |
| 현재 Phase | Phase 1: 배너 조회 조건 보정 |
| 현재 활성 Goal | 없음 |
## 목표
메인 홈 추천과 메인 콘텐츠 추천에서 화면별 탭과 회원의 성인 콘텐츠 조회 가능 여부에 맞는 배너만 조회한다.
## 현재 상태
| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
|---:|---|---:|---|---|
| 1 | 완료 | `2/2` | 없음 | 없음 |
## 범위
### 포함
- 홈 추천 배너의 `tab_id IS NULL` 조건 유지 및 성인 배너 필터 추가
- 콘텐츠 추천 배너의 `tab_id = 2` 조건과 성인 배너 필터 추가
- application에서 계산한 성인 콘텐츠 조회 가능 여부를 persistence port까지 전달
- 관련 service/facade/Repository focused test와 직접 영향 범위 회귀
### 제외
- 공개 API endpoint와 응답 DTO 변경
- 배너 언어/활성/차단/대상 유효성/정렬/limit 정책 변경
- DB 데이터 또는 스키마 변경
## 기술적 제약
- Kotlin, Spring Boot 2.7.14, QueryDSL 기존 패턴을 유지한다.
- 성인 콘텐츠 조회 가능 여부는 `MemberContentPreferenceService.canViewAdultContent(member)` 결과를 재사용한다.
- 조회 가능 여부가 `false`이면 `audioContentBanner.isAdult.isFalse`, `true`이면 성인 조건을 추가하지 않는다.
- 신규 공통 추상화나 의존성을 추가하지 않는다.
### Phase 1: 배너 조회 조건 보정
- [x] **Task 1.1: 추천 API별 탭 및 성인 배너 조회 조건 구현 (`P1-T1`)**
- Objective: 두 추천 API의 배너가 확정된 탭과 성인 콘텐츠 조회 정책에 따라 반환된다.
- 시작 조건: PRD `BANNER-001~004`가 확정되어 있다.
- 완료 증거: 신규/보강 테스트가 RED 후 GREEN이고 관련 production/test 코드가 컴파일된다.
- 범위 밖: 언어 필터와 공개 응답 스키마 변경.
- Modify:
- `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacade.kt`
- `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/application/HomeRecommendationQueryService.kt`
- `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/port/out/HomeRecommendationQueryPort.kt`
- `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt`
- `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepository.kt`
- `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacadeTest.kt`
- `src/test/kotlin/kr/co/vividnext/sodalive/v2/recommendation/application/HomeRecommendationQueryServiceTest.kt`
- `src/test/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepositoryTest.kt`
- `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepositoryTest.kt`
- RED: 홈 성인 조회 플래그 전달, 홈 비성인 필터, 콘텐츠 `tab_id = 2` 및 비성인 필터를 검증하는 테스트를 먼저 작성하고 실패를 확인한다.
- GREEN: 기존 QueryDSL 조건에 필요한 탭/성인 조건만 추가하고 홈 application 경로에 플래그를 전달한다.
- REFACTOR: 중복되지 않는 기존 조건 helper 패턴을 따르고 불필요한 변경이 없는지 확인한다.
- Verify:
- `./gradlew test --tests kr.co.vividnext.sodalive.v2.api.home.application.HomeRecommendationFacadeTest --tests kr.co.vividnext.sodalive.v2.recommendation.application.HomeRecommendationQueryServiceTest --tests kr.co.vividnext.sodalive.v2.recommendation.adapter.out.persistence.DefaultHomeRecommendationQueryRepositoryTest --tests kr.co.vividnext.sodalive.v2.content.recommendation.adapter.out.persistence.DefaultAudioRecommendationQueryRepositoryTest`
- 검증 기록:
- RED: 두 Repository 테스트를 실행해 `shouldExcludeAdultHomeBannersWhenAdultContentIsNotVisible`, `shouldFindBannersForContentRecommendationTabWithAdultVisibility` 두 건의 기대값 실패를 확인했다.
- RED: 홈 service 테스트는 `includeAdultBanners` 미구현 컴파일 실패, Facade 테스트는 플래그 미전달 assertion 실패를 각각 확인했다.
- GREEN: 위 4개 focused test class를 함께 실행해 `BUILD SUCCESSFUL`을 확인했다.
- [x] **Task 1.2: 영향 범위 회귀 및 문서 검증 (`P1-GATE`)**
- Objective: 추천 배너 변경이 기존 API 계약과 코드 품질 규칙을 깨지 않았음을 확인한다.
- 시작 조건: `P1-T1`이 완료되어 있다.
- 완료 증거: focused test, `ktlintCheck`, `tasks --all`, `git diff --check`가 통과하고 결과가 기록되어 있다.
- 범위 밖: 전체 회귀 테스트. 변경이 배너 조회 경로 두 곳에 한정되어 targeted test로 직접 영향 범위를 판단할 수 있으므로 생략한다.
- Verify:
- `./gradlew test --tests kr.co.vividnext.sodalive.v2.api.home.application.HomeRecommendationFacadeTest --tests kr.co.vividnext.sodalive.v2.recommendation.application.HomeRecommendationQueryServiceTest --tests kr.co.vividnext.sodalive.v2.recommendation.adapter.out.persistence.DefaultHomeRecommendationQueryRepositoryTest --tests kr.co.vividnext.sodalive.v2.content.recommendation.adapter.out.persistence.DefaultAudioRecommendationQueryRepositoryTest`
- `./gradlew ktlintCheck`
- `./gradlew tasks --all`
- `git diff --check`
- 검증 기록:
- `HomeRecommendationControllerTest`, `AudioRecommendationControllerTest`, `AudioRecommendationEndToEndTest`를 함께 실행해 `BUILD SUCCESSFUL`을 확인했다.
- `./gradlew ktlintCheck`: `BUILD SUCCESSFUL`.
- `./gradlew tasks --all`: `BUILD SUCCESSFUL`.
- `git diff --check`: 출력 없음.
## 검증 기록
- 최초 Gradle 실행은 sandbox의 `~/.gradle` wrapper lock 접근 제한으로 실패했으며, 승인된 동일 명령을 재실행해 검증을 완료했다.
- 전체 회귀 테스트는 실행하지 않았다. 변경이 두 배너 조회 조건과 홈 플래그 전달에 한정되어 focused Repository/application 테스트와 두 API의 controller/E2E 회귀로 직접 영향 범위를 검증했다.
@@ -1,71 +0,0 @@
# PRD: 추천 탭 배너 조회 조건 보정
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | 구현 완료 |
| 작성일 | 2026-08-05 |
| 최종 수정일 | 2026-08-05 |
| 대상 제품 | 메인 홈 추천 탭, 메인 콘텐츠 추천 탭 |
| 작성자·결정권자 | 사용자 |
| 관련 구현 계획 | `docs/20260805_추천탭_배너_조회조건/plan-task.md` |
| 관련 기존 문서 | `docs/20260529_메인_홈_추천_API/prd.md`, `docs/20260623_메인_콘텐츠_추천_탭_API/prd.md` |
## 1. Overview
메인 홈 추천 API와 메인 콘텐츠 추천 API의 배너 조회에 회원의 성인 콘텐츠 조회 가능 여부를 반영하고, 두 화면이 서로 다른 탭의 배너를 조회하도록 조건을 보정한다.
## 2. Problem Statement
- 두 추천 API가 모두 `content_banner.tab_id IS NULL`인 같은 배너를 조회한다.
- 두 추천 API의 배너 조회가 `content_banner.is_adult`를 필터링하지 않아 성인 콘텐츠 조회 불가 사용자에게 성인 배너가 노출될 수 있다.
문제를 해결했다는 판단은 두 API의 탭 조건과 성인 배너 노출 조건이 Repository 테스트로 구분되어 검증되는 것으로 한다.
## 3. Goals
- 성인 콘텐츠 조회 불가 사용자는 `is_adult = false`인 배너만 조회한다.
- 성인 콘텐츠 조회 가능 사용자는 성인·비성인 배너를 모두 조회한다.
- 메인 홈 추천 API는 기존처럼 `tab_id IS NULL`인 배너를 조회한다.
- 메인 콘텐츠 추천 API는 `tab_id = 2`인 배너를 조회한다.
## 4. Non-Goals
- 공개 API endpoint와 응답 DTO를 변경하지 않는다.
- 배너 언어 필터, 정렬, 최대 조회 개수, 대상 활성/차단 정책을 변경하지 않는다.
- 배너 또는 탭 데이터와 DB 스키마를 변경하지 않는다.
## 5. 기능 요구사항
| ID | 상태 | 요구사항 | 수용 기준 | Goal 연결 |
|---|---|---|---|---|
| `BANNER-001` | 확정 | `GET /api/v2/home/recommendations`의 배너는 `tab_id IS NULL` 조건을 유지한다. | 탭이 없는 활성 배너만 조회하고 `tab_id = 2` 배너는 조회하지 않는다. | `P1-T1` |
| `BANNER-002` | 확정 | `GET /api/v2/audio/recommendations`의 배너는 `tab_id = 2` 조건을 사용한다. | `tab_id = 2`인 활성 배너만 조회하고 탭이 없는 배너는 조회하지 않는다. | `P1-T1` |
| `BANNER-003` | 확정 | 두 API 모두 회원의 성인 콘텐츠 조회 가능 여부를 배너 조회에 반영한다. | 조회 불가이면 비성인 배너만, 조회 가능이면 성인·비성인 배너를 모두 반환한다. | `P1-T1` |
| `BANNER-004` | 확정 | 기존 배너 활성/차단/대상 유효성/정렬/limit 정책을 유지한다. | 기존 관련 Repository 테스트가 계속 통과한다. | `P1-GATE` |
## 6. API 계약
| Method | Path | 변경 내용 |
|---|---|---|
| `GET` | `/api/v2/home/recommendations` | 응답 스키마 변경 없이 배너의 성인 조회 조건만 추가한다. |
| `GET` | `/api/v2/audio/recommendations` | 응답 스키마 변경 없이 배너 탭 조건을 `tab_id = 2`로 변경하고 성인 조회 조건을 추가한다. |
## 7. 성공 기준
- [x] 홈 추천 배너가 `tab_id IS NULL` 조건을 유지한다.
- [x] 콘텐츠 추천 배너가 `tab_id = 2` 조건만 사용한다.
- [x] 성인 콘텐츠 조회 불가/가능 사용자의 배너 결과가 확정 정책과 일치한다.
- [x] 기존 배너 응답 스키마와 활성/차단/정렬/limit 정책이 유지된다.
## 8. Open Questions
- 없음.
## 9. Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항·Goal |
|---|---|---|---|---|---|
| 2026-08-05 | `DEC-001` | 확정 | 성인 조회 불가이면 비성인 배너만, 조회 가능이면 성인·비성인 배너를 모두 조회한다. | 사용자 답변 A | `BANNER-003`, `P1-T1` |
| 2026-08-05 | `DEC-002` | 확정 | 홈 추천은 `tab_id IS NULL`, 콘텐츠 추천은 `tab_id = 2`를 사용한다. | 사용자 직접 요구사항 | `BANNER-001`, `BANNER-002`, `P1-T1` |
@@ -1,174 +0,0 @@
# 크리에이터 관리자 시리즈 상세 LazyInitializationException 수정 Plan/TASK
| 문서 항목 | 내용 |
|---|---|
| 상태 | 구현 완료 |
| 작성일 | 2026-08-05 |
| 요구사항 기준 | `docs/20260805_크리에이터관리자_시리즈상세_LazyInitializationException_수정/prd.md` |
| API 기준 | 기존 `GET /creator-admin/audio-content/series/{seriesId}` 계약 유지 |
| 현재 Phase | Phase 1 완료 |
| 현재 활성 Goal | 없음, 구현 완료 |
## 목표
OSIV off 환경에서 크리에이터 관리자가 본인 시리즈 상세를 조회할 때 `Series.keywordList` lazy 초기화 예외 없이 기존 응답을 받게 한다.
## 현재 상태
| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
|---:|---|---:|---|---|
| 1 | 완료 | `1/1` | 없음 | 없음 |
- 동시에 하나의 미완료 goal만 운용한다.
- 완료된 Task와 검증 기록은 되돌리거나 삭제하지 않는다.
## 범위
### 포함
- `CreatorAdminContentSeriesService`의 class-level read-only 트랜잭션 경계
- `Series.keywordList` lazy 예외를 재현하고 방지하는 서비스 통합 테스트
- 기존 상세 응답과 소유권 동작의 영향 범위 회귀 검증
### 제외
- endpoint와 `GetCreatorAdminContentSeriesDetailResponse` 변경
- OSIV, entity fetch 전략, repository query 변경
- 다른 시리즈 조회·수정 흐름 리팩터링
- 새 abstraction 또는 dependency 추가
## 기술적 제약
- Kotlin, Java 17, Spring Boot 2.7.14, Spring Data JPA, Hibernate, JUnit 5를 유지한다.
- production code는 `CreatorAdminContentSeriesService` class-level annotation 한 줄만 변경한다.
- 기존 쓰기 메서드 `createSeries()`, `modifySeries()`, `addingContentToTheSeries()`, `removeContentInTheSeries()`,
`updateSeriesOrders()`의 메서드 레벨 `@Transactional`은 유지해 class-level read-only 기본값을 재정의한다.
- 테스트는 실제 Spring 서비스 프록시를 사용하고 외부 테스트 트랜잭션으로 서비스 경계를 가리지 않는다.
- focused test부터 실행하고 직접 영향받는 characterization test까지만 회귀 범위를 확장한다.
- 전체 테스트는 class-level annotation 한 줄 변경과 targeted test로 영향 범위를 판정할 수 있으므로 기본적으로 생략한다. targeted test에서
범위를 설명할 수 없는 실패가 발생하거나 공통 경계 변경으로 확대될 때만 실행한다.
## Phase 1: 상세 조회 트랜잭션 회귀 수정
**Phase 결과:** 크리에이터 관리자 시리즈 상세 조회가 OSIV off 환경에서 키워드를 포함한 기존 DTO를 정상 반환한다.
**선행조건:** `CASD-001`~`CASD-003` 요구사항과 `DEC-CASD-002`, `DEC-CASD-003` 결정 확정.
**Phase 완료 조건:** `P1-T1`과 `P1-GATE` 완료, focused·영향 범위 회귀 결과 기록.
### 구현 항목
#### Task 1.1 상세 조회 lazy 예외 재현 및 최소 수정
**Goal 실행 `P1-T1`:** 서비스 클래스의 기본 read-only 트랜잭션 안에서 상세 조회가 키워드 lazy 컬렉션을 DTO로 변환하게 한다.
- **시작 조건:** PRD 구현 기준 확정, production code 미수정 상태.
- **완료 증거:** RED/GREEN/REFACTOR 체크박스 완료, focused test 실제 실행 결과, class-level annotation 이외 production diff 없음,
기존 쓰기 메서드 annotation 유지.
- **범위 밖:** OSIV·entity mapping·repository query·controller·response DTO 변경.
**Files:**
- Create: `src/test/kotlin/kr/co/vividnext/sodalive/creator/admin/content/series/CreatorAdminContentSeriesServiceIntegrationTest.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/creator/admin/content/series/CreatorAdminContentSeriesService.kt`
- Modify: `docs/20260805_크리에이터관리자_시리즈상세_LazyInitializationException_수정/plan-task.md`
- Verify: `src/test/resources/application.yml`
**Interfaces:**
- Consumes: `CreatorAdminContentSeriesService.getDetail(id: Long, memberId: Long)`과 기존 `Series.toDetailResponse(imageHost)`
- Produces: 기존 시그니처·DTO를 유지하면서 class-level read-only 트랜잭션 안에서 완성된
`GetCreatorAdminContentSeriesDetailResponse`
- [x] **RED:** `@SpringBootTest`, `EmbeddedRedisInitializer`, 실제 `CreatorAdminContentSeriesService` 빈을 사용하는 통합 테스트를 작성한다.
테스트 외부 트랜잭션은 사용하지 않고 `TransactionTemplate` 안에서 소유 회원, 장르, 시리즈, 해시태그와 `SeriesKeyword` fixture를
저장한 뒤 트랜잭션 밖에서 `service.getDetail()`을 호출해 `keywords`와 주요 상세 필드를 검증한다.
- [x] **RED 확인:** `./gradlew --no-daemon test --rerun-tasks --tests kr.co.vividnext.sodalive.creator.admin.content.series.CreatorAdminContentSeriesServiceIntegrationTest`
를 실행해 `Series.keywordList`의 `LazyInitializationException`으로 실패하는지 확인한다. 환경·fixture·컴파일 실패는 RED 증거로
인정하지 않고 먼저 바로잡는다.
- [x] **GREEN:** `CreatorAdminContentSeriesService` 클래스 선언 바로 위에 기존 import를 사용하는
`@Transactional(readOnly = true)` 한 줄을 추가하고 기존 쓰기 메서드의 메서드 레벨 `@Transactional`을 유지한다.
- [x] **GREEN 확인:** RED와 같은 focused test를 다시 실행해 `BUILD SUCCESSFUL`과 fixture의 `keywords`, `seriesId`,
`publishedDaysOfWeek`, `state` 값 일치를 확인한다.
- [x] **REFACTOR:** 새 abstraction 없이 테스트 fixture의 중복만 파일 내부 private helper로 제한한다. focused test와
`./gradlew --no-daemon test --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.series.LegacyCreatorAdminSeriesCharacterizationTest`
를 실행하고, production diff가 class-level annotation 한 줄이며 모든 기존 쓰기 메서드 annotation이 유지되는지 확인해 결과를
이 Task 아래에 기록한다.
### 완료 조건
- [x] `P1-T1`의 RED/GREEN/REFACTOR와 완료 증거가 모두 충족됐다.
- [x] `CASD-001`~`CASD-003`이 자동 검증 결과로 추적된다.
- [x] API 계약, OSIV, entity mapping, repository query에 변경이 없다.
### 검증 방법
#### Phase 1 Gate
**Goal 실행 `P1-GATE`:** 상세 조회 수정의 기능·회귀·문서 범위를 최종 판정한다.
- **시작 조건:** `P1-T1` 완료.
- **완료 증거:** 아래 명령 통과 및 실제 결과를 검증 기록에 누적.
- **범위 밖:** Gate 통과를 위한 테스트 완화와 관련 없는 코드 수정.
```bash
./gradlew --no-daemon test --rerun-tasks --tests kr.co.vividnext.sodalive.creator.admin.content.series.CreatorAdminContentSeriesServiceIntegrationTest
./gradlew --no-daemon test --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.series.LegacyCreatorAdminSeriesCharacterizationTest
./gradlew --no-daemon ktlintCheck
./gradlew --no-daemon tasks --all
git diff --check
./gradlew --no-daemon test
```
- [x] focused test가 실제 실행되고 failures/errors 0으로 통과한다.
- [x] 기존 시리즈 상세·소유권 characterization test가 통과한다.
- [x] `ktlintCheck`, `tasks --all`, `git diff --check`가 통과한다.
- [x] ultrawork verification 요구에 따라 전체 테스트를 실행하고 통과했다.
- [x] production code 변경이 `CreatorAdminContentSeriesService`의 class-level `@Transactional(readOnly = true)` 한 줄뿐이다.
- [x] 기존 쓰기 메서드 5개의 메서드 레벨 `@Transactional`이 유지된다.
## 실행 순서
| 순서 | Goal | 완료 후 다음 Goal |
|---:|---|---|
| 1 | `P1-T1` | `P1-GATE` |
| 2 | `P1-GATE` | 구현 완료 |
## Progress
- 2026-08-05: 운영 stack trace와 controller → service → repository → entity DTO 변환 흐름을 확인했다.
- 2026-08-05: `Series.keywordList` lazy 접근과 트랜잭션 없는 `getDetail()`을 원인으로 확정했다.
- 2026-08-05: PRD와 Plan/TASK를 작성했으며 production code와 테스트는 아직 변경하지 않았다.
- 2026-08-05: 메서드 분류 재검토 결과 트랜잭션 없는 public 메서드 4개는 모두 조회이고, 쓰기 메서드 5개는 모두 메서드 레벨
`@Transactional`을 보유함을 확인했다. 해결안을 `getDetail()` 메서드 단위에서 서비스 class-level read-only 기본값으로 정정했다.
- 2026-08-05: `P1-T1` RED/GREEN/REFACTOR를 완료했다. 다음 Goal은 `P1-GATE`이며 Gate 체크박스는 아직 미완료다.
- 2026-08-05: `P1-GATE`의 focused·characterization·정적 검사·Gradle task 확인·전체 테스트를 모두 통과해 Phase 1과 구현을 완료했다.
## 검증 기록
- 문서 작성 시점에는 구현용 RED/GREEN 테스트를 실행하지 않았다.
- 2026-08-05: 문서 변경 후 `./gradlew --no-daemon tasks --all`로 계획에 사용한 Gradle 명령이 유효한지 확인했다.
- sandbox 실행은 `/Users/klaus/.gradle/wrapper/dists/.../gradle-8.1.1-bin.zip.lck` 접근 제한으로 실패했다.
- 승인 실행은 `BUILD SUCCESSFUL in 8s`로 통과했다.
- 2026-08-05: `git diff --check`가 출력 없이 통과했고, 구현 파일과 테스트 파일은 변경하지 않았음을 확인했다.
- 2026-08-05: class-level read-only 트랜잭션 기준으로 문서를 보완한 뒤 `./gradlew --no-daemon tasks --all`을 재실행해
`BUILD SUCCESSFUL in 7s`를 확인했다.
- 2026-08-05: production 수정 전 focused test를 실행해 `BUILD FAILED in 6m 50s`와
`org.hibernate.LazyInitializationException: failed to lazily initialize a collection of role: kr.co.vividnext.sodalive.creator.admin.content.series.Series.keywordList, could not initialize proxy - no Session`을 확인했다.
- 2026-08-05: `CreatorAdminContentSeriesService`에 `@Transactional(readOnly = true)` 한 줄을 추가한 뒤 같은 focused test를
재실행해 `BUILD SUCCESSFUL in 4m 52s`를 확인했다. 테스트는 fixture의 `seriesId`, `title`, `introduction`, `coverImageUrl`,
`publishedDaysOfWeek`, `genre`, `keywords`, `isAdult`, `state`, `writer`, `studio` 값을 검증한다.
- 2026-08-05: `./gradlew --no-daemon test --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.series.LegacyCreatorAdminSeriesCharacterizationTest`
를 실행해 `BUILD SUCCESSFUL in 47s`를 확인했다.
- 2026-08-05: production diff는 `CreatorAdminContentSeriesService` 클래스 선언 위의 `@Transactional(readOnly = true)` 한 줄뿐이며,
`createSeries()`, `modifySeries()`, `addingContentToTheSeries()`, `removeContentInTheSeries()`, `updateSeriesOrders()`의 기존 메서드 레벨
`@Transactional` 5개가 유지됨을 확인했다. API 계약, OSIV, entity mapping, repository query 변경은 없다.
- 2026-08-05: `P1-GATE`에서 명령을 순차 실행해 다음 결과를 확인했다.
- `./gradlew --no-daemon test --rerun-tasks --tests kr.co.vividnext.sodalive.creator.admin.content.series.CreatorAdminContentSeriesServiceIntegrationTest`: exit code 0, `BUILD SUCCESSFUL in 4m 44s`.
- `./gradlew --no-daemon test --tests kr.co.vividnext.sodalive.v2.api.admin.aicharacter.series.LegacyCreatorAdminSeriesCharacterizationTest`: exit code 0, `BUILD SUCCESSFUL in 41s`.
- `./gradlew --no-daemon ktlintCheck`: exit code 0, `BUILD SUCCESSFUL in 30s`.
- `./gradlew --no-daemon tasks --all`: exit code 0, `BUILD SUCCESSFUL in 7s`.
- `git diff --check`: exit code 0, 출력 없음.
- `./gradlew --no-daemon test`: exit code 0, `BUILD SUCCESSFUL in 6m 20s`. 기본 계획의 targeted 검증 범위를 넘어 전체 테스트를 실행한 이유는 ultrawork verification 요구사항 때문이다.
- 2026-08-05: Gate 검증 후 production diff가 class-level `@Transactional(readOnly = true)` 한 줄뿐이고, 새 테스트 파일은
`CreatorAdminContentSeriesServiceIntegrationTest.kt` 하나이며, 기존 쓰기 메서드의 `@Transactional` 5개가 유지됨을 재확인했다.
@@ -1,148 +0,0 @@
# PRD: 크리에이터 관리자 시리즈 상세 LazyInitializationException 수정
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | 구현 기준 확정 |
| 작성일 | 2026-08-05 |
| 최종 수정일 | 2026-08-05 |
| 대상 기능 | 크리에이터 관리자 시리즈 상세 조회 |
| 관련 구현 계획 | `docs/20260805_크리에이터관리자_시리즈상세_LazyInitializationException_수정/plan-task.md` |
## 1. Overview
`spring.jpa.open-in-view=false` 환경에서 `GET /creator-admin/audio-content/series/{seriesId}` 호출 시
`Series.keywordList` 접근으로 발생하는 `LazyInitializationException`을 서비스 클래스의 기본 read-only 트랜잭션 경계로 방지한다.
## 2. Problem Statement
- `CreatorAdminContentSeriesController.getDetail()`은 `CreatorAdminContentSeriesService.getDetail()`에 상세 조회를 위임한다.
- `CreatorAdminContentSeriesService.getDetail()`에는 트랜잭션이 없으며,
`CreatorAdminContentSeriesRepository.findByIdAndCreatorId()`가 반환한 `Series`로 상세 DTO를 생성한다.
- 같은 서비스의 트랜잭션 없는 public 메서드는 모두 조회 기능이고, 데이터를 변경하는 public 메서드에는 이미 메서드 레벨
`@Transactional`이 적용되어 있다.
- `Series.keywordList`는 별도 fetch 설정이 없는 `@OneToMany`이므로 lazy 컬렉션이다.
- `Series.toDetailResponse()`은 `keywordList.map { it.keyword!!.tag }`를 실행한다.
- 운영·테스트 설정의 `spring.jpa.open-in-view=false` 때문에 리포지토리 호출 후 영속성 컨텍스트가 종료되고, DTO 변환 중
`org.hibernate.LazyInitializationException: failed to lazily initialize a collection of role: kr.co.vividnext.sodalive.creator.admin.content.series.Series.keywordList, could not initialize proxy - no Session`
예외가 발생한다.
- 기존 `LegacyCreatorAdminSeriesCharacterizationTest`는 클래스 레벨 `@Transactional`과 직접 생성한 서비스 객체를 사용하므로,
실제 Spring 서비스 프록시의 트랜잭션 유무에 따른 회귀를 검증하지 못한다.
문제를 해결했다는 판단은 외부 테스트 트랜잭션이 없는 OSIV off 통합 테스트에서 실제 Spring 서비스 프록시로 상세 조회 후
키워드가 포함된 기존 응답을 정상 생성하는 것으로 한다.
## 3. Goals
- OSIV off 환경에서도 소유한 시리즈 상세 조회가 `LazyInitializationException` 없이 완료된다.
- 서비스 클래스의 조회 기본값을 read-only 트랜잭션으로 두고, 시리즈 조회부터 `toDetailResponse()`의 lazy 컬렉션 접근까지
같은 영속성 컨텍스트에서 처리한다.
- 실제 Spring 서비스 프록시를 호출하는 통합 테스트로 수정 전 실패와 수정 후 성공을 검증한다.
- 기존 endpoint, 인증·소유권 검사, 성공 응답 필드와 값 형식을 유지한다.
## 4. Non-Goals
- `spring.jpa.open-in-view`를 활성화하지 않는다.
- `Series.keywordList`를 전역 eager fetch로 변경하지 않는다.
- 상세 조회 쿼리를 fetch join 또는 projection으로 재작성하지 않는다.
- `Series.toDetailResponse()` 또는 `GetCreatorAdminContentSeriesDetailResponse` 구조를 변경하지 않는다.
- 시리즈 목록·수정·콘텐츠 연결 등 다른 흐름을 함께 리팩터링하지 않는다.
## 5. Target Users and Permissions
- 대상 사용자: 본인이 소유한 시리즈 상세를 조회하는 `CREATOR` 역할의 크리에이터 관리자
- 인증·권한: 기존 `@PreAuthorize("hasRole('CREATOR')")`와 인증 회원 검사를 유지한다.
- 소유권: 기존 `findByIdAndCreatorId(id, creatorId)` 조건과 `creator.admin.series.invalid_access` 오류를 유지한다.
## 6. 기능 요구사항
| ID | 상태 | 요구사항 | 수용 기준 | Goal 연결 |
|---|---|---|---|---|
| `CASD-001` | 확정 | 서비스 클래스에 read-only 트랜잭션을 기본 적용하고 기존 쓰기 메서드의 메서드 레벨 트랜잭션을 유지한다. | 키워드가 있는 소유 시리즈 조회가 OSIV off 환경에서 예외 없이 완료되고 기존 쓰기 메서드 annotation이 보존된다. | `P1-T1` |
| `CASD-002` | 확정 | 기존 상세 조회 API 계약을 유지한다. | endpoint, 권한, 오류 key, 응답 DTO의 필드·형식이 바뀌지 않는다. | `P1-T1`, `P1-GATE` |
| `CASD-003` | 확정 | 테스트 외부 트랜잭션 없이 실제 서비스 프록시를 검증한다. | 수정 전 `Series.keywordList` 예외를 재현하고, 수정 후 같은 테스트가 통과한다. | `P1-T1` |
## 7. API 계약
| Method | Path | 변경 사항 |
|---|---|---|
| `GET` | `/creator-admin/audio-content/series/{seriesId}` | 공개 계약 변경 없음 |
- 성공 응답은 기존 `ApiResponse.ok(GetCreatorAdminContentSeriesDetailResponse)`를 유지한다.
- `seriesId`, `title`, `introduction`, `coverImageUrl`, `publishedDaysOfWeek`, `genre`, `keywords`, `isAdult`,
`state`, `writer`, `studio` 필드와 기존 문자열 변환 규칙을 유지한다.
- 인증 실패와 타 소유자·미존재 시리즈 오류 처리를 변경하지 않는다.
## 8. 해결 방안
`CreatorAdminContentSeriesService` 클래스에 `@Transactional(readOnly = true)`를 기본 적용한다.
```kotlin
@Service
@Transactional(readOnly = true)
class CreatorAdminContentSeriesService(
```
`getDetail()`의 `findByIdAndCreatorId()` 조회와 `series.toDetailResponse()` 변환이 이 경계 안에서 모두 끝나므로 `keywordList`를
정상 초기화할 수 있다. 다른 조회 메서드도 같은 기본 경계를 사용하며, 기존 쓰기 메서드의 메서드 레벨 `@Transactional`은
class-level `readOnly = true`를 쓰기 트랜잭션으로 재정의한다. 이미 서비스 파일에서 `Transactional`을 사용하고 있어 새 의존성이나
import는 필요하지 않다.
### 현재 메서드 분류
| 기본 read-only 트랜잭션을 사용하는 조회 메서드 | 메서드 레벨 쓰기 트랜잭션을 유지하는 메서드 |
|---|---|
| `getSeriesList()` | `createSeries()` |
| `getDetail()` | `modifySeries()` |
| `getSeriesContent()` | `addingContentToTheSeries()` |
| `searchContentNotInSeries()` | `removeContentInTheSeries()` |
| | `updateSeriesOrders()` |
### 제외한 대안
- OSIV 활성화: 요청 전체로 영속성 컨텍스트를 확장해 현재 저장소 정책을 되돌리므로 제외한다.
- `keywordList` eager 변경: 모든 `Series` 조회 비용에 영향을 주는 전역 변경이므로 제외한다.
- fetch join/projection 추가: 이 endpoint만의 결함을 고치는 데 리포지토리 계약과 쿼리 변경이 불필요하므로 제외한다.
- 컨트롤러 트랜잭션: 영속성 및 DTO 변환 경계는 서비스가 소유하는 기존 구조에 맞지 않으므로 제외한다.
- `getDetail()`에만 read-only 트랜잭션 적용: 현재 트랜잭션 없는 메서드가 모두 조회 기능이므로 class-level 기본값보다 반복과
누락 가능성이 크다.
## 9. 기술적 제약
- Kotlin, Java 17, Spring Boot 2.7.14, Spring Data JPA, Hibernate, JUnit 5, Gradle Wrapper를 사용한다.
- `src/main/resources/application.yml`과 `src/test/resources/application.yml`의 `spring.jpa.open-in-view=false`를 유지한다.
- 테스트는 클래스 외부 트랜잭션을 비활성화하고 fixture 생성만 `TransactionTemplate`로 분리한다.
- 실제 Spring `CreatorAdminContentSeriesService` 빈을 주입해 proxy annotation 동작을 검증한다.
- production code 변경은 `CreatorAdminContentSeriesService` class-level annotation 한 줄로 제한한다.
- `createSeries()`, `modifySeries()`, `addingContentToTheSeries()`, `removeContentInTheSeries()`, `updateSeriesOrders()`의 기존
메서드 레벨 `@Transactional`을 유지한다.
## 10. 성공 기준
- [ ] 수정 전 focused test가 `Series.keywordList`의 `LazyInitializationException`으로 실패한다.
- [ ] 서비스 클래스에 `@Transactional(readOnly = true)` 적용 후 같은 테스트가 통과한다.
- [ ] 응답의 `keywords`와 주요 기존 상세 필드 값이 fixture와 일치한다.
- [ ] 기존 소유권·상세 동작 characterization test와 `ktlintCheck`가 통과한다.
- [ ] `tasks --all`과 `git diff --check`가 통과한다.
- [ ] API 스키마, 엔티티 fetch 전략, repository query에는 변경이 없다.
- [ ] 모든 기존 쓰기 메서드의 메서드 레벨 `@Transactional`이 유지된다.
## 11. 요구사항 추적표
| 요구사항 | 계획 Phase | Goal | 자동 검증 |
|---|---:|---|---|
| `CASD-001`, `CASD-003` | 1 | `P1-T1` | `CreatorAdminContentSeriesServiceIntegrationTest` |
| `CASD-002` | 1 | `P1-T1`, `P1-GATE` | focused test, `LegacyCreatorAdminSeriesCharacterizationTest` |
## 12. Open Questions
없음. 운영 stack trace, entity mapping, 서비스 호출 경계와 OSIV 설정으로 원인과 최소 해결 범위가 확인됐다.
## 13. Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항·Goal |
|---|---|---|---|---|---|
| 2026-08-05 | `DEC-CASD-001` | 확정 | `CreatorAdminContentSeriesService.getDetail()`에 메서드 단위 read-only 트랜잭션을 적용한다. | DTO 변환이 이미 서비스 내부에 있어 한 줄로 lazy 접근 전체를 영속성 컨텍스트 안에 포함할 수 있다. | `CASD-001`, `CASD-002`, `P1-T1` |
| 2026-08-05 | `DEC-CASD-002` | 확정 | 실제 Spring 서비스 프록시와 외부 트랜잭션이 없는 통합 테스트로 회귀를 고정한다. | 기존 characterization test는 테스트 트랜잭션과 직접 생성한 서비스 때문에 annotation 회귀를 검증할 수 없다. | `CASD-003`, `P1-T1` |
| 2026-08-05 | `DEC-CASD-003` | 정정 | `DEC-CASD-001`의 메서드 단위 적용을 class-level `@Transactional(readOnly = true)` 적용으로 정정하고 기존 쓰기 메서드의 메서드 레벨 `@Transactional`을 유지한다. | 트랜잭션 없는 기존 public 메서드는 모두 조회 기능이며, 쓰기 메서드는 이미 메서드 레벨 annotation으로 read-only 기본값을 재정의한다. | `CASD-001`, `CASD-002`, `P1-T1` |
@@ -1,293 +0,0 @@
# 크리에이터 채널 홈 커뮤니티 응답 확장 Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` or `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 크리에이터 채널 홈의 `notices`와 `communities` 게시글에 실제 고정 여부와 댓글 가능 여부를 non-null Boolean으로 제공한다.
**Architecture:** 기존 `CreatorChannelCommunityPost`가 보유한 두 값을 공유 `CreatorChannelCommunityPostResponse.from`에서 그대로 매핑한다. 조회 계층과 데이터 모델은 건드리지 않고 공개 응답 DTO와 직접 영향받는 직렬화·E2E 테스트만 수정한다.
**Tech Stack:** Kotlin, Java 17, Spring Boot 2.7.14, Jackson, JUnit 5, MockMvc, Gradle Wrapper
## 문서 상태
| 문서 항목 | 내용 |
|---|---|
| 상태 | 구현 완료 |
| 작성일 | 2026-08-10 |
| 요구사항 기준 | `docs/20260810_크리에이터_채널_홈_커뮤니티_응답_확장/prd.md` |
| API 기준 | PRD `7. API 계약` |
| 현재 Phase | Phase 1 완료: 홈 커뮤니티 상태 응답 확장 |
| 현재 활성 Goal | 없음 |
| 다음 Goal | 없음 |
| Gate | `P1-GATE` 완료 |
## 현재 상태
| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
|---:|---|---:|---|---|
| 1 | 완료 | `1/1` | 없음 | 없음 |
- 동시에 하나의 미완료 goal만 운용한다.
- 완료된 Task와 검증 기록은 되돌리거나 삭제하지 않는다.
- goal 실행 시 token budget을 설정하지 않는다.
## 범위
### 포함
- `GET /api/v2/creator-channels/{creatorId}/home`의 `notices[*]`, `communities[*]`에 `isPinned` 추가
- 같은 게시글 응답에 `isCommentAvailable` 추가
- 도메인 값의 DTO 매핑과 정확한 `is*` JSON 필드명 검증
- 기존 홈 API E2E와 Kotlin 포맷 회귀 검증
### 제외
- 조회 조건, 정렬, 최대 노출 개수와 권한 정책 변경
- 커뮤니티 탭·상세·댓글 API 변경
- DB, entity, domain model, repository 수정
- 전용 DTO 분리, 신규 dependency와 관련 없는 리팩터링
## Global Constraints
- Kotlin + Java 17, Spring Boot 2.7.14와 기존 Jackson 직렬화 방식을 유지한다.
- 기존 공유 `CreatorChannelCommunityPostResponse`와 `from` 변환만 확장한다.
- 공개 필드명은 `isPinned`, `isCommentAvailable`로 고정하고 두 값은 nullable로 만들지 않는다.
- `CreatorChannelCommunityPost.isPinned`, `CreatorChannelCommunityPost.isCommentAvailable` 값을 재계산하지 않는다.
- 구현은 RED → RED 확인 → GREEN → GREEN 확인 → REFACTOR 순서로 진행한다.
- focused test에서 시작해 직접 영향받는 홈 E2E와 `ktlintCheck`까지만 확장한다.
- 전체 `./gradlew test`는 공통 경계 영향이나 targeted test로 판단할 수 없는 실패가 있을 때만 실행한다.
---
## Phase 1: 홈 커뮤니티 상태 응답 확장
**Phase 결과:** 홈 API의 공지와 일반 커뮤니티 게시글이 고정 여부와 댓글 가능 여부를 정확한 Boolean 필드로 반환한다.
**선행조건:** 승인된 PRD의 `CCHC-001~004`, `DEC-001~003` 확인.
**Phase 완료 조건:** `P1-T1`과 `P1-GATE` 완료, 체크박스와 실제 검증 결과를 Progress에 누적.
### Task 1.1 공유 게시글 응답에 상태 필드 추가
**Goal 실행 `P1-T1`:** 공유 홈 게시글 응답이 도메인의 `isPinned`, `isCommentAvailable`을 정확한 JSON 필드로 직렬화하게 한다.
- **시작 조건:** PRD 상태가 `구현 기준 확정`이고 현재 활성 Goal이 없다.
- **완료 증거:** 아래 5단계 완료, controller focused test와 홈 E2E 통과, 변경 파일과 결과를 Progress에 기록.
- **범위 밖:** 조회 service/repository, domain model, 다른 커뮤니티 API 수정.
**Files:**
- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/creator/channel/home/adapter/in/web/CreatorChannelHomeControllerTest.kt:92`
- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/creator/channel/home/CreatorChannelHomeEndToEndTest.kt:57`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/creator/channel/home/dto/CreatorChannelHomeResponse.kt:173`
- Modify: `docs/20260810_크리에이터_채널_홈_커뮤니티_응답_확장/plan-task.md`
**Interfaces:**
- Consumes: `CreatorChannelCommunityPost.isPinned: Boolean`, `CreatorChannelCommunityPost.isCommentAvailable: Boolean`
- Produces: `CreatorChannelCommunityPostResponse.isPinned: Boolean`, `CreatorChannelCommunityPostResponse.isCommentAvailable: Boolean`
- JSON: `data.notices[*].isPinned`, `data.notices[*].isCommentAvailable`, `data.communities[*].isPinned`, `data.communities[*].isCommentAvailable`
- [x] **RED:** `CreatorChannelHomeControllerTest.shouldReturnCreatorChannelHomeForAuthenticatedMember`의 일반 커뮤니티 fixture를 아래처럼 공지와 반대 상태로 만들고, 네 JSON 경로 assertion을 추가한다. 같은 assertion을 `CreatorChannelHomeEndToEndTest.shouldAssembleCreatorChannelHomeSectionsThroughSingleHttpRequest`에도 추가하되 E2E fixture의 댓글 가능 값은 기존 `true`를 사용한다.
```kotlin
communities = listOf(
post.copy(
postId = 302L,
content = "community",
isCommentAvailable = false,
isPinned = false
)
)
```
```kotlin
.andExpect(jsonPath("$.data.notices[0].isPinned").value(true))
.andExpect(jsonPath("$.data.notices[0].isCommentAvailable").value(true))
.andExpect(jsonPath("$.data.communities[0].isPinned").value(false))
.andExpect(jsonPath("$.data.communities[0].isCommentAvailable").value(false))
```
E2E assertion은 실제 저장값과 조회 조건을 검증한다.
```kotlin
.andExpect(jsonPath("$.data.notices[0].isPinned").value(true))
.andExpect(jsonPath("$.data.notices[0].isCommentAvailable").value(true))
.andExpect(jsonPath("$.data.communities[0].isPinned").value(false))
.andExpect(jsonPath("$.data.communities[0].isCommentAvailable").value(true))
```
- [x] **RED 확인:** 다음 focused test를 실행해 `$.data.notices[0].isPinned` 등 신규 JSON 경로에 값이 없어 실패하는지 확인한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.home.adapter.in.web.CreatorChannelHomeControllerTest' --no-daemon
```
**Expected:** 테스트가 신규 필드 미직렬화로 실패한다. compile 오류나 fixture 오류는 RED 증거로 인정하지 않는다.
- [x] **GREEN:** `CreatorChannelCommunityPostResponse`에 기존 커뮤니티 탭 DTO와 같은 `@JsonProperty` 관례로 필드를 추가하고 `from`에서 도메인 값을 직접 매핑한다.
```kotlin
data class CreatorChannelCommunityPostResponse(
val postId: Long,
val creatorId: Long,
val creatorNickname: String,
val creatorProfileUrl: String,
val imageUrl: String?,
val audioUrl: String?,
val content: String,
val price: Int,
val dateUtc: String,
val existOrdered: Boolean,
@JsonProperty("isCommentAvailable")
val isCommentAvailable: Boolean,
val likeCount: Int,
val commentCount: Int,
@JsonProperty("isPinned")
val isPinned: Boolean,
@JsonProperty("isLiked")
val isLiked: Boolean
) {
companion object {
fun from(post: CreatorChannelCommunityPost): CreatorChannelCommunityPostResponse {
return CreatorChannelCommunityPostResponse(
postId = post.postId,
creatorId = post.creatorId,
creatorNickname = post.creatorNickname,
creatorProfileUrl = post.creatorProfileUrl,
imageUrl = post.imageUrl,
audioUrl = post.audioUrl,
content = post.content,
price = post.price,
dateUtc = post.createdAt.toUtcIso(),
existOrdered = post.existOrdered,
isCommentAvailable = post.isCommentAvailable,
likeCount = post.likeCount,
commentCount = post.commentCount,
isPinned = post.isPinned,
isLiked = post.isLiked
)
}
}
}
```
- [x] **GREEN 확인:** controller test와 홈 E2E를 함께 실행해 공유 DTO 매핑, JSON 이름, 실제 조회값이 모두 통과하는지 확인한다.
```bash
./gradlew test \
--tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.home.adapter.in.web.CreatorChannelHomeControllerTest' \
--tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.home.CreatorChannelHomeEndToEndTest' \
--no-daemon
```
**Expected:** 두 테스트 클래스가 `BUILD SUCCESSFUL`로 종료된다.
- [x] **REFACTOR:** 새 abstraction을 만들지 않고 이번 Task가 추가한 fixture·필드·매핑만 정리한다. 다음 명령을 실행하고 결과를 `P1-T1` Progress에 기록한다.
```bash
./gradlew ktlintCheck --no-daemon
git diff --check
```
**Expected:** 두 명령 모두 exit code `0`.
- [x] **Commit:** 커밋 전후 규칙 검증과 함께 구현·테스트·Progress 변경만 커밋한다.
```bash
work/scripts/check-commit-message-rules.sh --message "feat(creator-channel): 홈 커뮤니티 응답 상태를 추가한다"
git add \
src/main/kotlin/kr/co/vividnext/sodalive/v2/api/creator/channel/home/dto/CreatorChannelHomeResponse.kt \
src/test/kotlin/kr/co/vividnext/sodalive/v2/api/creator/channel/home/adapter/in/web/CreatorChannelHomeControllerTest.kt \
src/test/kotlin/kr/co/vividnext/sodalive/v2/api/creator/channel/home/CreatorChannelHomeEndToEndTest.kt \
docs/20260810_크리에이터_채널_홈_커뮤니티_응답_확장/plan-task.md
git commit -m "feat(creator-channel): 홈 커뮤니티 응답 상태를 추가한다"
work/scripts/check-commit-message-rules.sh HEAD
```
### Phase 1 Gate
**Goal 실행 `P1-GATE`:** PRD의 네 확정 요구사항과 작은 변경 범위를 최종 판정한다.
- **시작 조건:** `P1-T1`의 체크박스, focused test, E2E, 포맷과 Progress 기록 완료.
- **완료 증거:** 아래 자동 검증 통과, PRD 추적성 확인, Gate 결과를 Progress에 기록.
- **범위 밖:** Gate 통과를 위한 test 삭제·skip·완화와 관련 없는 코드 수정.
```bash
./gradlew test \
--tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.home.adapter.in.web.CreatorChannelHomeControllerTest' \
--tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.home.CreatorChannelHomeEndToEndTest' \
--no-daemon
./gradlew ktlintCheck --no-daemon
./gradlew tasks --all --no-daemon
git diff --check
```
**Expected:** 모든 명령이 exit code `0`이고 다음 조건이 충족된다.
- [x] `notices[*]`와 `communities[*]`에 두 non-null Boolean이 존재한다. (`CCHC-001~003`)
- [x] `notices[*].isPinned == true`, `communities[*].isPinned == false`가 실제 조회 조건과 일치한다.
- [x] 댓글 가능 값이 `true`와 `false` 모두 그대로 직렬화된다.
- [x] endpoint, 인증, 기존 홈 응답 필드와 조회 결과가 유지된다. (`CCHC-004`)
- [x] 전체 회귀 테스트를 생략한 근거와 대신 실행한 focused·E2E 검증을 Progress에 기록한다.
## 실행 순서와 의존성
| 순서 | Goal | 선행조건 | 병행 가능 | 차단 시 다음 행동 |
|---:|---|---|---|---|
| 1 | `P1-T1` | 승인된 PRD | 아니요 | RED 실패 원인이 신규 필드 누락인지 다시 확인 |
| 2 | `P1-GATE` | `P1-T1` 완료 | 아니요 | 실패를 소유한 Task에 회귀 수정 goal 추가 |
```text
P1-T1 → P1-GATE
```
## 변경 금지 항목
- 공개 필드명이나 기존 홈 응답 필드를 근거 없이 변경하지 않는다.
- domain, service, repository에서 두 Boolean을 재계산하지 않는다.
- 전용 DTO, helper, 신규 dependency를 추가하지 않는다.
- 테스트를 삭제·skip·완화하거나 관련 없는 코드를 정리하지 않는다.
- 기존 완료 기록과 Decision Log를 삭제하거나 덮어쓰지 않는다.
## 의사결정 및 중단 규칙
- 구현 범위가 바뀌면 PRD Decision Log와 이 계획을 먼저 갱신한다.
- 신규 JSON 필드 외 실패가 발생하면 원인을 분리하고 범위 밖 변경을 임의로 적용하지 않는다.
- targeted test로 영향 범위를 판단할 수 없을 때만 전체 `./gradlew test --no-daemon`을 실행한다.
- 체크박스와 완료 증거, Progress 기록이 모두 충족된 뒤에만 goal을 완료 처리한다.
## Progress
기존 기록을 삭제하지 않고 Goal별 실행 결과를 아래에 누적한다.
### P1-T1
- RED 작성: controller fixture의 일반 게시글을 `postId=302L`, `content="community"`, `isCommentAvailable=false`, `isPinned=false`로 구성하고 controller 및 E2E에 공지/일반 게시글 상태 assertion을 추가했다.
- RED 확인: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.home.adapter.in.web.CreatorChannelHomeControllerTest' --no-daemon`은 exit code `1`로 실패했다. `CreatorChannelHomeControllerTest.kt:138`의 `$.data.notices[0].isPinned` assertion에서 `PathNotFoundException`이 발생해 신규 JSON 필드 미직렬화가 원인임을 확인했으며 compile 및 fixture 오류는 없었다.
- GREEN 구현: `CreatorChannelCommunityPostResponse`에 non-null Boolean `isCommentAvailable`, `isPinned`을 명시적 `@JsonProperty`와 함께 추가하고 `post.isCommentAvailable`, `post.isPinned`을 직접 매핑했다.
- GREEN 확인: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.home.adapter.in.web.CreatorChannelHomeControllerTest' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.home.CreatorChannelHomeEndToEndTest' --no-daemon`은 exit code `0`, `BUILD SUCCESSFUL in 54s`로 종료됐다. controller focused test와 직접 영향받는 홈 E2E가 함께 통과해 공지 `true/true`, 일반 게시글 `false/false` controller fixture 및 `false/true` 실제 E2E 저장값의 매핑과 JSON 이름을 확인했다.
- REFACTOR 확인: 새 abstraction 없이 계획된 fixture, 응답 필드, 직접 매핑만 유지했다. `./gradlew ktlintCheck --no-daemon`은 exit code `0`, `BUILD SUCCESSFUL in 25s`였고 `git diff --check`도 exit code `0`이었다.
- 전체 회귀 생략: 이번 변경은 공유 홈 DTO의 additive 직렬화 필드 두 개와 직접 영향받는 테스트에 한정되고 controller focused test와 실제 저장·조회 E2E가 모두 통과했으므로 계획의 조건에 따라 전체 `./gradlew test`는 실행하지 않았다.
- 변경 파일: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/creator/channel/home/dto/CreatorChannelHomeResponse.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/creator/channel/home/adapter/in/web/CreatorChannelHomeControllerTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/creator/channel/home/CreatorChannelHomeEndToEndTest.kt`, `docs/20260810_크리에이터_채널_홈_커뮤니티_응답_확장/plan-task.md`.
- 커밋 검증: 커밋 전 `work/scripts/check-commit-message-rules.sh --message "feat(creator-channel): 홈 커뮤니티 응답 상태를 추가한다"`가 모든 규칙을 `[PASS]`로 확인했다. 최종 diff는 계획된 네 파일만 포함하고 비밀값, 관련 없는 변경, agent footer가 없음을 자체 검토했다. 커밋 후 `work/scripts/check-commit-message-rules.sh HEAD`를 커밋 `d99104d945743663803b506417b4d2ad3ac4b0a2`에 실행해 모든 규칙이 `[PASS]`임을 확인했다.
### P1-GATE
- 자동 검증: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.home.adapter.in.web.CreatorChannelHomeControllerTest' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.home.CreatorChannelHomeEndToEndTest' --no-daemon`은 최초 실행에서 exit code `0`, `BUILD SUCCESSFUL in 40s`였고 테스트 산출물이 `UP-TO-DATE`였다. 실제 HTTP 경계를 새로 실행하기 위해 `./gradlew cleanTest --no-daemon`을 exit code `0`, `BUILD SUCCESSFUL in 16s`로 수행한 뒤 같은 Gate 테스트 명령을 다시 실행해 `:test` 실행과 exit code `0`, `BUILD SUCCESSFUL in 48s`를 확인했다.
- 정적·빌드 검증: `./gradlew ktlintCheck --no-daemon`은 exit code `0`, `BUILD SUCCESSFUL in 1m 22s`, `./gradlew tasks --all --no-daemon`은 exit code `0`, `BUILD SUCCESSFUL in 22s`, `git diff --check`는 출력 없이 exit code `0`이었다.
- 요구사항 추적: `CCHC-001~003`은 `notices[*]`, `communities[*]`의 non-null Boolean `isPinned`, `isCommentAvailable`과 도메인 값 직접 매핑으로 확인했다. 실제 저장·조회 E2E에서 공지는 `isPinned=true`, 일반 게시글은 `isPinned=false`였고 controller fixture와 E2E를 합쳐 `isCommentAvailable=true/false`가 모두 그대로 직렬화됨을 확인했다. `CCHC-004`는 기존 `GET /api/v2/creator-channels/{creatorId}/home`, 비회원 `401`, 인증 회원 `200`, 기존 홈 섹션·필드·조회 결과 assertion의 유지와 focused·E2E 통과로 확인했다.
- 실제 HTTP 표면: `CreatorChannelHomeEndToEndTest.shouldAssembleCreatorChannelHomeSectionsThroughSingleHttpRequest`가 인증된 MockMvc `GET`을 controller에서 service, repository, H2 database 조회까지 통과시켜 실제 API 응답의 공지와 일반 게시글 값을 검증했다.
- 전체 회귀 생략: 변경은 공유 홈 응답 DTO의 additive Boolean 두 필드와 직접 직렬화 경계에 한정되고 focused controller test와 실제 저장·조회 MockMvc E2E로 영향을 판정할 수 있었으며 모호한 실패가 없었다. 계획의 실행 조건에 따라 전체 `./gradlew test`는 실행하지 않았다.
- 변경 문서 상태: 구현·테스트는 커밋 `d99104d945743663803b506417b4d2ad3ac4b0a2`에 있고, Gate에서는 기존 `P1-T1` 기록과 이미 존재한 커밋 후 검증 문장을 보존한 채 `plan-task.md`와 `prd.md`의 완료 상태만 변경했다. Kotlin 코드, 테스트, Decision Log는 변경하지 않았다.
## Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 Goal/문서 |
|---|---|---|---|---|---|
| 2026-08-10 | `PLAN-DEC-001` | 확정 | 하나의 구현 Task와 하나의 Gate로 실행한다. | 공유 DTO 한 곳의 additive 변경이며 별도 구현 경계가 없다. | `P1-T1`, `P1-GATE` |
| 2026-08-10 | `PLAN-DEC-002` | 확정 | 전체 회귀는 조건부로 두고 controller test, 홈 E2E, `ktlintCheck`를 기본 검증으로 사용한다. | 변경이 홈 게시글 응답 직렬화 경계에 한정된다. | `P1-T1`, `P1-GATE` |
## 발견된 문제
없음.
@@ -1,144 +0,0 @@
# PRD: 크리에이터 채널 홈 커뮤니티 응답 확장
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | 구현 기준 확정 |
| 작성일 | 2026-08-10 |
| 최종 수정일 | 2026-08-10 |
| 대상 제품 | 크리에이터 채널 홈 API |
| 작성자·결정권자 | 사용자 |
| 관련 API Contract | 별도 문서 없음, 이 문서의 `7. API 계약`을 기준으로 함 |
| 관련 구현 계획 | `docs/20260810_크리에이터_채널_홈_커뮤니티_응답_확장/plan-task.md` |
| 관련 review | 없음 |
## 1. Overview
크리에이터 채널 홈 API의 `notices`와 `communities` 게시글 응답에 고정 여부와 댓글 가능 여부를 각각 `isPinned`, `isCommentAvailable`로 제공한다. 기존 조회 결과가 이미 보유한 값을 응답에 그대로 반영해 클라이언트가 별도 추론 없이 게시글 상태를 표시할 수 있게 한다.
## 2. Problem Statement
- 현재 `GET /api/v2/creator-channels/{creatorId}/home`의 게시글 도메인 모델에는 고정 여부와 댓글 가능 여부가 있지만 홈 응답 DTO에는 두 값이 없다.
- 클라이언트는 홈의 게시글이 고정 글인지, 댓글 작성이 가능한지 응답만으로 일관되게 판단할 수 없다.
- `notices`와 `communities`가 같은 `CreatorChannelCommunityPostResponse`를 사용하므로 두 배열의 계약을 함께 확장해야 한다.
문제를 해결했다는 판단은 두 배열의 각 게시글에 실제 도메인 값과 일치하는 non-null Boolean 필드가 직렬화되는지로 한다.
## 3. Goals
- 홈 응답의 `notices[*]`와 `communities[*]`에 `isPinned`를 제공한다.
- 홈 응답의 `notices[*]`와 `communities[*]`에 `isCommentAvailable`을 제공한다.
- 기존 커뮤니티 조회 결과의 값을 변형하거나 재계산하지 않고 그대로 사용한다.
- 기존 홈 API의 endpoint, 인증 정책과 기존 응답 필드를 유지한다.
## 4. Non-Goals
- 커뮤니티 조회 조건, 고정 정렬, 최대 노출 개수는 변경하지 않는다.
- 댓글 작성·수정·삭제 정책과 API는 변경하지 않는다.
- 커뮤니티 탭 및 게시글 상세 API 계약은 변경하지 않는다.
- DB schema, entity, domain model과 repository query는 변경하지 않는다.
- `notices`와 `communities` 전용 응답 DTO를 새로 분리하지 않는다.
- 관련 없는 홈 응답 필드나 패키지 구조는 리팩터링하지 않는다.
## 5. Target Users and Permissions
- 대상 사용자: 인증 후 크리에이터 채널 홈을 조회하는 앱 사용자
- 인증 및 권한: 기존 홈 API 정책을 그대로 사용한다.
- 차단, 성인 콘텐츠와 구매 여부 정책: 기존 홈 API 조회 결과를 그대로 사용한다.
## 6. 기능 요구사항
| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 |
|---|---|---|---|---|
| `CCHC-001` | 확정 | `notices[*]`와 `communities[*]`에 `isPinned`를 제공한다. | JSON 필드명이 정확히 `isPinned`이고 값은 `CreatorChannelCommunityPost.isPinned`와 일치한다. | `7. API 계약`, `P1-T1` |
| `CCHC-002` | 확정 | `notices[*]`와 `communities[*]`에 `isCommentAvailable`을 제공한다. | JSON 필드명이 정확히 `isCommentAvailable`이고 값은 `CreatorChannelCommunityPost.isCommentAvailable`과 일치한다. | `7. API 계약`, `P1-T1` |
| `CCHC-003` | 확정 | 두 필드는 non-null Boolean으로 응답한다. | 게시글이 존재하면 두 필드가 누락되거나 `null`이 되지 않는다. | `P1-T1`, `P1-GATE` |
| `CCHC-004` | 확정 | 기존 홈 API 계약과 조회 정책을 보존한다. | endpoint, 인증 정책, 기존 응답 필드와 게시글 선택·정렬 결과가 변경되지 않는다. | `P1-GATE` |
### 상태별 기대값
| 배열 | `isPinned` | `isCommentAvailable` |
|---|---:|---|
| `notices` | 해당 게시글의 실제 값. 현재 홈 조회 조건상 `true` | 해당 게시글의 댓글 허용 설정값 |
| `communities` | 해당 게시글의 실제 값. 현재 홈 조회 조건상 `false` | 해당 게시글의 댓글 허용 설정값 |
- 댓글 수가 `0`이어도 `isCommentAvailable`을 별도로 계산하지 않는다.
- 빈 `notices` 또는 `communities`는 기존처럼 빈 배열로 응답한다.
## 7. API 계약
### 7.1 Endpoint
- Method: `GET`
- Path: `/api/v2/creator-channels/{creatorId}/home`
- 요청과 인증 정책: 변경 없음
### 7.2 응답 확장
`data.notices[*]`와 `data.communities[*]`에 다음 필드를 추가한다.
| 필드 | 타입 | nullable | 의미 |
|---|---|---:|---|
| `isPinned` | Boolean | 아니요 | 해당 커뮤니티 게시글의 고정 여부 |
| `isCommentAvailable` | Boolean | 아니요 | 해당 커뮤니티 게시글의 댓글 작성 허용 여부 |
예시:
```json
{
"data": {
"notices": [
{
"postId": 301,
"isPinned": true,
"isCommentAvailable": true
}
],
"communities": [
{
"postId": 302,
"isPinned": false,
"isCommentAvailable": false
}
]
}
}
```
예시는 추가 필드와 배열별 의미만 나타내며 기존 게시글 응답 필드는 그대로 유지한다.
## 8. 기술적 제약
- Kotlin + Java 17, Spring Boot 2.7.14와 기존 Jackson 직렬화 방식을 유지한다.
- 기존 공유 `CreatorChannelCommunityPostResponse`와 `from` 변환을 재사용한다.
- `is*` JSON 이름이 변경되지 않도록 기존 Boolean 응답 필드의 `@JsonProperty` 관례를 따른다.
- 신규 dependency와 별도 abstraction을 추가하지 않는다.
- 구현은 응답 DTO와 직접 영향받는 테스트로 제한한다.
## 9. 성공 기준
- [x] `notices[*].isPinned`와 `notices[*].isCommentAvailable`이 실제 값으로 응답된다. (`CCHC-001~003`)
- [x] `communities[*].isPinned`와 `communities[*].isCommentAvailable`이 실제 값으로 응답된다. (`CCHC-001~003`)
- [x] 기존 홈 API 응답 및 조회 흐름 회귀 테스트가 통과한다. (`CCHC-004`)
- [x] `ktlintCheck`가 통과한다.
- [x] 전체 회귀 테스트를 생략하면 작은 응답 DTO 변경이라는 근거와 대신 실행한 focused·영향 범위 테스트를 검증 기록에 남긴다.
## 10. Open Questions
없음.
## 11. 요구사항 추적표
| 요구사항 범위 | 계획 Phase | Goal | 자동 검증 | 수동 검증 |
|---|---:|---|---|---|
| `CCHC-001~003` | 1 | `P1-T1` | `CreatorChannelHomeControllerTest` | 홈 응답 JSON 필드명과 Boolean 값 확인 |
| `CCHC-004` | 1 | `P1-GATE` | `CreatorChannelHomeEndToEndTest`, `ktlintCheck` | 기존 필드 유지 여부 확인 |
## 12. Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항·Goal |
|---|---|---|---|---|---|
| 2026-08-10 | `DEC-001` | 확정 | `isPinned`, `isCommentAvailable`을 `notices`와 `communities` 모두에 추가한다. | 두 배열이 같은 게시글 응답 DTO를 사용하며 사용자가 인터뷰 선택지 A를 승인했다. | `CCHC-001~004`, `P1-T1`, `P1-GATE` |
| 2026-08-10 | `DEC-002` | 확정 | 공유 응답 DTO를 확장하고 전용 DTO는 분리하지 않는다. | 기존 도메인 값과 변환 경로를 재사용하는 최소 변경이다. | `CCHC-001~004`, `P1-T1` |
| 2026-08-10 | `DEC-003` | 확정 | PRD를 구현 기준으로 승인한다. | 사용자가 작성된 PRD를 검토하고 승인했다. | 문서 전체, `plan-task.md` |
@@ -1,41 +0,0 @@
SET @schema_name := DATABASE();
SET @lang_column_exists := (
SELECT COUNT(1)
FROM information_schema.columns
WHERE table_schema = @schema_name
AND table_name = 'event'
AND column_name = 'lang'
);
SET @add_lang_column_sql := IF(
@lang_column_exists = 0,
'ALTER TABLE `event` ADD COLUMN lang VARCHAR(10) NULL COMMENT ''이벤트 노출 언어'' AFTER title',
'SELECT ''event.lang already exists'' AS message'
);
PREPARE add_lang_column_stmt FROM @add_lang_column_sql;
EXECUTE add_lang_column_stmt;
DEALLOCATE PREPARE add_lang_column_stmt;
UPDATE `event`
SET lang = 'KO'
WHERE lang IS NULL;
SET @lang_column_nullable := (
SELECT IS_NULLABLE
FROM information_schema.columns
WHERE table_schema = @schema_name
AND table_name = 'event'
AND column_name = 'lang'
);
SET @alter_lang_column_sql := IF(
@lang_column_nullable = 'YES',
'ALTER TABLE `event` MODIFY COLUMN lang VARCHAR(10) NOT NULL DEFAULT ''KO'' COMMENT ''이벤트 노출 언어 (KO 기본, EN/JA 등록 가능)''',
'SELECT ''event.lang already normalized'' AS message'
);
PREPARE alter_lang_column_stmt FROM @alter_lang_column_sql;
EXECUTE alter_lang_column_stmt;
DEALLOCATE PREPARE alter_lang_column_stmt;
@@ -1,900 +0,0 @@
# 이벤트 접속 국가별 언어 필터 Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` or `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 관리자가 언어를 지정해 이벤트를 등록·식별하고, 앱 이벤트 목록과 팝업이 기존 국가 판정에 맞는 언어만 반환하게 한다.
**Architecture:** 기존 `Lang`과 `MemberContentPreferenceService.resolveCountryCode(member)`를 재사용한다. 앱 목록·팝업은 KO/JA를 조회하고, Phase 3에서 콘텐츠 메인 탭 6곳도 회원 국가 판정에 따른 필수 언어를 조회한다. 관리자 목록은 언어 전체 조회를 유지한다.
**Tech Stack:** Kotlin, Java 17, Spring Boot 2.7.14, JPA/QueryDSL, JUnit 5, Mockito, MockMvc, Gradle Wrapper, MySQL
**Spec:** `docs/20260819_이벤트_접속국가별_언어필터/prd.md`
| 문서 항목 | 내용 |
|---|---|
| 상태 | Phase 3 후속 언어 필터 구현·전체 검증·독립 리뷰 완료, 미배포 |
| 작성일 | 2026-08-19 |
| 요구사항 기준 | `docs/20260819_이벤트_접속국가별_언어필터/prd.md` |
| API 기준 | PRD 8절 |
| 현재 Phase | Phase 1~3 완료 |
| 현재 활성 Goal | 없음 |
| 다음 Goal | 없음 |
## Global Constraints
- `Event.lang`은 기존 `Lang` enum을 재사용하고 별도 언어 타입을 만들지 않는다.
- 관리자 등록은 `KO`, `EN`, `JA`를 허용하고 누락·잘못된 값은 저장·S3 업로드 전에 거부한다.
- 이벤트 수정 API와 레거시 `POST /event`의 요청 계약은 변경하지 않는다.
- 기존 이벤트와 레거시 등록의 기본 언어는 `KO`다.
- 관리자 목록은 기존 활성·종료 시각 조건을 유지하고 언어 조건을 추가하지 않는다.
- `GET /event`, `GET /event/popup`과 Phase 3의 메인 탭 이벤트 배너는 `JP -> Lang.JA`, 그 외 `Lang.KO`를 사용한다.
- 로그인 회원은 기존 강제 KR/JP 매핑을 유지하고, 비로그인·국가 누락은 기존 정규화·KR 기본값을 사용한다.
- [과거 기준, `DEC-009`에서 정정] 콘텐츠 메인 탭 6곳은 원래 언어 필터 없이 조회했으나 이번 후속 Phase에서 국가별 언어 필터를 적용한다. 과거 P2 구현·검증 기록은 당시 상태로 보존한다.
- 언어 필터는 QueryDSL `where`에서 정렬·`fetchFirst()` 전에 적용하고 메모리 후처리를 추가하지 않는다.
- 신규 dependency·cache·resolver abstraction·관련 없는 refactoring을 추가하지 않는다.
- 모든 구현 Task는 RED → RED 확인 → GREEN → GREEN 확인 → REFACTOR 순서를 지킨다.
- 전체 회귀는 focused·직접 영향 테스트로 범위를 판단할 수 없거나 공통 경계 회귀가 발생할 때만 실행한다.
---
## 현재 상태
| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
|---:|---|---:|---|---|
| 1 | 완료 | `3/3` | 없음 | 없음 |
| 2 | 완료 | `2/2` + Gate + `P2-R1` | 없음 | 없음 |
| 3 | 완료 | `1/1` + Gate | 없음 | 운영 배포 제외 |
- 동시에 하나의 미완료 goal만 운용한다.
- 구현 완료 즉시 해당 Task 체크박스와 현재 상태를 갱신한다.
- 실제 검증 결과는 기존 기록을 덮어쓰지 않고 `Progress`에 누적한다.
## 범위
### 포함
- `event.lang` 운영 DDL과 KO backfill
- `Event` 엔티티의 `Lang.KO` 기본 언어
- 관리자 이벤트 등록 `lang` 입력·검증·저장
- 관리자 이벤트 목록 `lang` 응답과 언어 전체 조회
- 앱 이벤트 목록·팝업의 접속 국가별 KO/JA 필터
- 기존 강제 국가 매핑과 비로그인 KR 기본값 재사용
- P2 당시 콘텐츠 메인 탭 6곳의 언어 전체 조회 비회귀 기록. `DEC-009`로 후속 언어 필터가 승인되어 현재 Phase 3에서 대체한다.
### 제외
- 이벤트 수정 시 언어 변경
- 레거시 `POST /event`의 `lang` request parameter
- 과거 제외 범위: 콘텐츠 메인 탭 6곳의 국가별 이벤트 필터. `DEC-009` 후속 승인으로 현재 범위에 포함하며 과거 체크박스·검증은 당시 이력으로 유지한다.
- EN 이벤트를 반환할 앱 국가 정책
- 다른 언어 fallback, `Accept-Language` 판정, 신규 dependency·공통 abstraction
- 기존 이벤트 성인·활성·게시 기간·정렬·URL 정책 변경
## 요구사항별 Goal 매핑
| 요구사항 | 소유 Goal | 완료 증거 |
|---|---|---|
| `EVENT-LANG-001` | `P1-T2` | KO/EN/JA 등록과 잘못된 언어 거부 통합 테스트 |
| `EVENT-LANG-002` | `P1-GATE` | 관리자·레거시 수정 API request 스키마 diff 검토 |
| `EVENT-LANG-003` | `P1-T2` | KO/EN/JA 관리자 목록과 `lang` 응답 통합 테스트 |
| `EVENT-LANG-004` | `P2-T1` | JP·비JP 목록 Repository·controller 통합 테스트 |
| `EVENT-LANG-005` | `P2-T1` | 다른 언어의 더 최신 팝업 fixture를 포함한 Repository·controller 통합 테스트 |
| `EVENT-LANG-006` | `P2-T1`, `P2-GATE` | 기존 강제 국가 매핑 회귀와 service Lang 전달 테스트 |
| `EVENT-LANG-007` | `P2-T2` | `lang = null`의 KO/EN/JA 전체 조회 mutation RED·GREEN |
| `EVENT-LANG-008` | `P1-T1`, `P1-GATE` | KO 기본 저장 테스트와 KO backfill DDL 대조 |
| `EVENT-LANG-009` | `P2-T1`, `P2-GATE` | QueryDSL `where` 조건과 정렬·`fetchFirst()` 선행 검증 |
| `EVENT-LANG-010` | `P3-T1`, `P3-GATE` | 여섯 메인 탭의 JP→JA/그 외→KO HTTP·service 검증 및 기존 `isAdult` 계산 비회귀 |
## 파일 구조
| 책임 | 파일 |
|---|---|
| 엔티티 언어 저장 | `src/main/kotlin/kr/co/vividnext/sodalive/event/Event.kt` |
| 운영 DB 이관 | `docs/20260819_이벤트_접속국가별_언어필터/20260819_event_lang_ddl.sql` |
| 관리자 등록·목록 API | `src/main/kotlin/kr/co/vividnext/sodalive/admin/event/banner/AdminEventBannerController.kt` |
| 관리자 등록 검증·저장 | `src/main/kotlin/kr/co/vividnext/sodalive/admin/event/banner/AdminEventBannerService.kt` |
| 관리자 언어 전체 목록 | `src/main/kotlin/kr/co/vividnext/sodalive/admin/event/banner/AdminEventBannerRepository.kt` |
| 관리자 응답 | `src/main/kotlin/kr/co/vividnext/sodalive/admin/event/banner/GetAdminEventResponse.kt` |
| 앱 HTTP 진입점 | `src/main/kotlin/kr/co/vividnext/sodalive/event/EventController.kt` |
| 앱 성인·국가·언어 조립 | `src/main/kotlin/kr/co/vividnext/sodalive/event/EventService.kt` |
| 앱 DB 언어 필터 | `src/main/kotlin/kr/co/vividnext/sodalive/event/EventRepository.kt` |
| 관리자 API 통합 검증 | `src/test/kotlin/kr/co/vividnext/sodalive/admin/event/banner/AdminEventBannerControllerIntegrationTest.kt` |
| 앱 서비스 언어 전달 검증 | `src/test/kotlin/kr/co/vividnext/sodalive/event/EventServiceTest.kt` |
| 앱 Repository 필터·비회귀 검증 | `src/test/kotlin/kr/co/vividnext/sodalive/event/EventRepositoryTest.kt` |
| 앱 요청 헤더부터 응답까지 검증 | `src/test/kotlin/kr/co/vividnext/sodalive/event/EventControllerIntegrationTest.kt` |
## Phase 1: 이벤트 언어 저장과 관리자 API
**Phase 결과:** 이벤트가 언어를 안전하게 저장하고, 관리자가 KO/EN/JA를 지정해 등록한 뒤 언어 전체 목록에서 식별한다.
**선행조건:** 승인된 PRD `EVENT-LANG-001~003`, `EVENT-LANG-008`.
**Phase 완료 조건:** `P1-T1`, `P1-T2`, `P1-GATE` 완료와 실제 검증 결과 누적.
### Task 1.1 이벤트 언어 모델과 운영 DDL
**Goal 실행 `P1-T1`:** `Event`가 `Lang`을 필수로 저장하고 기존 데이터를 손실 없이 KO로 이관할 수 있게 한다.
- **시작 조건:** PRD `EVENT-LANG-008`, `DEC-006`, `DEC-007` 확정.
- **완료 증거:** 엔티티 저장 테스트 RED/GREEN, 재실행 가능한 MySQL DDL, 문서·포맷 검증 기록.
- **범위 밖:** 관리자 request 처리와 앱 언어 조회.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/event/Event.kt`
- Create: `docs/20260819_이벤트_접속국가별_언어필터/20260819_event_lang_ddl.sql`
- Create: `src/test/kotlin/kr/co/vividnext/sodalive/event/EventRepositoryTest.kt`
**Interfaces:**
- Consumes: `kr.co.vividnext.sodalive.i18n.Lang`.
- Produces: `Event.lang: Lang = Lang.KO`, DB `event.lang VARCHAR(10) NOT NULL DEFAULT 'KO'`.
- [x] **RED:** `EventRepositoryTest`에 명시적 `Lang.JA` 저장과 기본 `Lang.KO` 저장을 검증하는 테스트를 작성한다.
```kotlin
@Test
@DisplayName("이벤트 언어는 명시적 값을 저장하고 누락 시 KO를 사용한다")
fun shouldPersistEventLanguageAndDefaultToKorean() {
val japanese = repository.saveAndFlush(activeEvent("ja").apply { lang = Lang.JA })
val korean = repository.saveAndFlush(activeEvent("ko"))
entityManager.clear()
assertEquals(Lang.JA, repository.findById(japanese.id!!).orElseThrow().lang)
assertEquals(Lang.KO, repository.findById(korean.id!!).orElseThrow().lang)
}
```
같은 테스트 파일에 사용할 fixture helper는 아래 계약으로 정의한다.
```kotlin
private fun activeEvent(
seed: String,
isPopup: Boolean = false
): Event {
return Event(
thumbnailImage = "$seed-thumbnail.png",
detailImage = "$seed-detail.png",
popupImage = if (isPopup) "$seed-popup.png" else null,
link = null,
title = seed,
isAdult = false,
isPopup = isPopup,
startDate = LocalDateTime.now().minusDays(1),
endDate = LocalDateTime.now().plusDays(1)
)
}
```
- [x] **RED 확인:** 아래 focused test를 실행해 `Event` 생성자와 `lang` property가 없어 발생하는 컴파일 실패를 확인한다.
```bash
./gradlew test --tests "kr.co.vividnext.sodalive.event.EventRepositoryTest"
```
**Expected RED:** `Cannot find a parameter with this name: lang` 또는 `Unresolved reference: lang`.
- [x] **GREEN:** `Event`에 다음 필드를 추가한다. 기존 생성자는 기본값으로 KO를 사용하므로 변경하지 않는다.
```kotlin
@Column(nullable = false)
@Enumerated(value = EnumType.STRING)
var lang: Lang = Lang.KO,
```
- [x] **GREEN:** `docs/20260819_이벤트_접속국가별_언어필터/20260819_event_lang_ddl.sql`에 다음 3단계 DDL을 작성한다.
```sql
SET @schema_name := DATABASE();
SET @lang_column_exists := (
SELECT COUNT(1)
FROM information_schema.columns
WHERE table_schema = @schema_name
AND table_name = 'event'
AND column_name = 'lang'
);
SET @add_lang_column_sql := IF(
@lang_column_exists = 0,
'ALTER TABLE `event` ADD COLUMN lang VARCHAR(10) NULL COMMENT ''이벤트 노출 언어'' AFTER title',
'SELECT ''event.lang already exists'' AS message'
);
PREPARE add_lang_column_stmt FROM @add_lang_column_sql;
EXECUTE add_lang_column_stmt;
DEALLOCATE PREPARE add_lang_column_stmt;
UPDATE `event`
SET lang = 'KO'
WHERE lang IS NULL;
SET @lang_column_nullable := (
SELECT IS_NULLABLE
FROM information_schema.columns
WHERE table_schema = @schema_name
AND table_name = 'event'
AND column_name = 'lang'
);
SET @alter_lang_column_sql := IF(
@lang_column_nullable = 'YES',
'ALTER TABLE `event` MODIFY COLUMN lang VARCHAR(10) NOT NULL DEFAULT ''KO'' COMMENT ''이벤트 노출 언어 (KO 기본, EN/JA 등록 가능)''',
'SELECT ''event.lang already normalized'' AS message'
);
PREPARE alter_lang_column_stmt FROM @alter_lang_column_sql;
EXECUTE alter_lang_column_stmt;
DEALLOCATE PREPARE alter_lang_column_stmt;
```
- [x] **GREEN 확인:** 같은 focused test를 재실행해 JA와 KO 저장이 통과하는지 확인한다.
- [x] **REFACTOR:** 새 언어 타입·converter·migration framework를 추가하지 않고 import와 필드 위치만 정리한다. focused test·`ktlintCheck`·`git diff --check`를 재실행해 `Progress`에 기록한다.
DDL은 실행 대상 운영 MySQL에 접속하지 않는 코드 작성 단계에서는 자동 실행하지 않는다. 운영 반영 전에 `information_schema` 조회 결과와 백업을 확인하고 검증 환경에서 2회 실행해 재실행 결과를 기록한다.
### Task 1.2 관리자 언어 등록과 언어 전체 목록
**Goal 실행 `P1-T2`:** 관리자가 KO/EN/JA 이벤트를 등록하고 현재 목록 조건 안의 모든 언어를 `lang`과 함께 조회한다.
- **시작 조건:** `P1-T1` 완료, PRD `EVENT-LANG-001~003`.
- **완료 증거:** 관리자 multipart 등록·잘못된 언어 거부·언어 전체 목록 통합 테스트 RED/GREEN, 수정 API 스키마 미변경 diff 확인.
- **범위 밖:** 수정·삭제 동작 변경, 앱 국가별 조회.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/admin/event/banner/AdminEventBannerController.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/admin/event/banner/AdminEventBannerService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/admin/event/banner/AdminEventBannerRepository.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/admin/event/banner/GetAdminEventResponse.kt`
- Create: `src/test/kotlin/kr/co/vividnext/sodalive/admin/event/banner/AdminEventBannerControllerIntegrationTest.kt`
- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/event/EventRepositoryTest.kt`
**Interfaces:**
- Consumes: multipart request parameter `lang: String`, `Lang.fromCode(value: String): Lang`.
- Produces: `AdminEventBannerService.save(..., lang: String): Long`, `GetAdminEventResponse.lang: Lang`.
- Preserves: `AdminEventBannerService.update` 시그니처와 `PUT /admin/event/banner` request parameter 목록.
- [x] **RED:** 관리자 통합 테스트에 `lang=en`으로 등록한 이벤트가 `Lang.EN`으로 저장되는 케이스를 작성한다.
```kotlin
val thumbnail = MockMultipartFile(
"thumbnail",
"thumbnail.png",
"image/png",
"thumbnail".toByteArray()
)
mockMvc.perform(
multipart("/admin/event/banner")
.file(thumbnail)
.param("link", "https://event.test/en")
.param("isPopup", "false")
.param("startDate", "2099-01-01 00:00")
.param("endDate", "2099-01-02 00:00")
.param("lang", "en")
.with(user("admin").roles("ADMIN"))
)
.andExpect(status().isOk)
.andExpect(jsonPath("$.success").value(true))
assertEquals(Lang.EN, eventRepository.findAll().single().lang)
```
- [x] **RED:** `lang=fr`을 보내면 `success=false`이고 DB row·S3 upload이 생성되지 않는 케이스를 추가한다.
- [x] **RED:** KO·JA·EN 활성 이벤트를 준비한 뒤 `GET /admin/event/banner`가 세 항목의 `lang`을 모두 반환하는 케이스를 추가한다.
```kotlin
mockMvc.perform(
get("/admin/event/banner")
.with(user("admin").roles("ADMIN"))
)
.andExpect(status().isOk)
.andExpect(jsonPath("$.data.length()").value(3))
.andExpect(jsonPath("$.data[*].lang").value(containsInAnyOrder("KO", "EN", "JA")))
```
- [x] **RED 확인:** 아래 focused test를 실행해 `lang` request parameter·service parameter·response projection이 없어 발생하는 컴파일 또는 assertion 실패를 확인한다.
```bash
./gradlew test \
--tests "kr.co.vividnext.sodalive.admin.event.banner.AdminEventBannerControllerIntegrationTest" \
--tests "kr.co.vividnext.sodalive.event.EventRepositoryTest"
```
- [x] **GREEN:** controller의 등록 메서드에 `@RequestParam("lang") lang: String`을 추가하고 service 호출의 마지막 인자로 전달한다.
- [x] **GREEN:** service는 엔티티 생성과 S3 업로드 전에 다음 기존 패턴으로 언어를 변환한다.
```kotlin
val eventLang = try {
Lang.fromCode(lang)
} catch (_: IllegalArgumentException) {
throw SodaException(messageKey = "common.error.invalid_request")
}
```
- [x] **GREEN:** `Event` 생성 시 `lang = eventLang`을 넘긴다. 레거시 `EventService.save`는 수정하지 않아 `Lang.KO` 기본값을 사용하게 둔다.
- [x] **GREEN:** `GetAdminEventResponse`에 `lang`을 추가하고 QueryDSL projection에 `event.lang`을 동일 순서로 추가한다.
```kotlin
data class GetAdminEventResponse @QueryProjection constructor(
val id: Long,
val title: String? = null,
val lang: Lang,
val thumbnailImageUrl: String,
val detailImageUrl: String? = null,
val popupImageUrl: String? = null,
val startDate: String,
val endDate: String,
val link: String? = null,
val isAdult: Boolean? = null,
val isPopup: Boolean
)
```
- [x] **GREEN 확인:** focused test를 재실행해 소문자 코드 저장, 잘못된 코드 거부, 언어 전체 목록과 `lang` 응답이 통과하는지 확인한다.
- [x] **REFACTOR:** 수정 API에 `lang`을 추가하지 않고, 기존 `Lang.fromCode`와 `common.error.invalid_request`만 재사용한다. focused test·`ktlintCheck`·`git diff --check`를 재실행해 결과를 기록한다.
### Phase 1 Gate
**Goal 실행 `P1-GATE`:** 이벤트 언어 저장과 관리자 등록·전체 목록 계약을 최종 판정한다.
- **시작 조건:** `P1-T1`, `P1-T2` 완료.
- **완료 증거:** 아래 명령과 수동 diff 검토 통과, `Progress` 기록.
- **범위 밖:** Gate 통과를 위한 테스트 삭제·skip·assertion 완화.
```bash
./gradlew test \
--tests "kr.co.vividnext.sodalive.admin.event.banner.AdminEventBannerControllerIntegrationTest" \
--tests "kr.co.vividnext.sodalive.event.EventRepositoryTest"
./gradlew ktlintCheck
./gradlew tasks --all
git diff --check
```
**Expected:** 모든 명령이 exit code `0`으로 끝난다. KO/EN/JA 등록과 목록 응답이 통과하고, 잘못된 언어는 저장·업로드 전에 거부된다.
수동 검증:
- [x] `git diff`에서 `PUT /admin/event/banner`, `PUT /event`, `POST /event`의 request parameter에 `lang`이 추가되지 않았는지 확인한다.
- [x] 관리자 Repository의 `where`에 `event.lang` 조건이 없고 기존 활성·종료 시각 조건이 유지되는지 확인한다.
- [x] DDL이 컬럼 추가 → KO backfill → `NOT NULL DEFAULT 'KO'` 순서이고 모든 신규 컬럼에 COMMENT가 있는지 확인한다.
## Phase 2: 앱 접속 국가별 이벤트 조회
**Phase 결과:** `GET /event`, `GET /event/popup`이 기존 국가 판정에 따라 JA 또는 KO만 반환하고, 콘텐츠 메인 탭 6곳은 기존 언어 전체 조회를 유지한다.
**선행조건:** `P1-GATE` 완료, PRD `EVENT-LANG-004~007`, `EVENT-LANG-009`.
**Phase 완료 조건:** `P2-T1`, `P2-T2`, `P2-GATE` 완료와 실제 검증 결과 누적.
### Task 2.1 앱 목록·팝업 국가별 언어 필터
**Goal 실행 `P2-T1`:** 두 앱 API가 판정 국가 JP에서 JA, 그 외에서 KO 이벤트만 DB에서 조회한다.
- **시작 조건:** `P1-GATE` 완료, PRD `EVENT-LANG-004~006`, `EVENT-LANG-009`.
- **완료 증거:** service 언어 전달, Repository 목록·팝업 필터, 요청 헤더부터 API 응답까지의 RED/GREEN 테스트.
- **범위 밖:** 콘텐츠 메인 탭의 `getEventList(isAdult)` 경로와 이벤트 응답 DTO.
- **범위 내 보정:** 실제 security chain에서 두 앱 GET API의 기존 비로그인 접근 계약을 검증하고, 누락된 `GET /event/popup` exact matcher만 복구한다.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/event/EventController.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/event/EventService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/event/EventRepository.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/configs/SecurityConfig.kt`
- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/event/EventServiceTest.kt`
- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/event/EventRepositoryTest.kt`
- Create: `src/test/kotlin/kr/co/vividnext/sodalive/event/EventControllerIntegrationTest.kt`
**Interfaces:**
- Consumes: `Member?`, `MemberContentPreferenceService.resolveCountryCode(member: Member?): String`.
- Produces: `EventService.getEventList(member: Member?): GetEventResponse`, `EventService.getEventPopup(member: Member?): EventItem?`.
- Produces: `EventRepository.getEventList(isAdult: Boolean?, lang: Lang?): List<EventItem>`, `getMainEventPopup(isAdult: Boolean, lang: Lang?): EventItem?`.
- Preserves: `EventService.getEventList(isAdult: Boolean?, lang: Lang? = null)`의 null 언어 조회.
- Preserves: 기존 `GET /event` 비로그인 접근과 다른 SecurityConfig matcher 순서·인증 정책. `GET /event/popup`만 exact path로 비로그인 접근을 허용한다.
- [x] **RED:** `EventServiceTest`에 국가 판정 `JP`가 `Lang.JA`로 목록 Repository에 전달되는 케이스를 추가한다.
`EventServiceTest`의 fixture에 `MemberContentPreferenceService` mock을 추가하고 `EventService` 생성자에 전달한다.
```kotlin
private val preferenceService = Mockito.mock(MemberContentPreferenceService::class.java)
```
```kotlin
@Test
@DisplayName("JP 판정 회원의 이벤트 목록은 JA를 조회한다")
fun shouldQueryJapaneseEventListForJapan() {
val member = Member(password = "password", nickname = "jp-user").apply { id = 10L }
Mockito.`when`(authRepository.getAuthIdByMemberId(10L)).thenReturn(null)
Mockito.`when`(preferenceService.resolveCountryCode(member)).thenReturn("JP")
Mockito.`when`(repository.getEventList(false, Lang.JA)).thenReturn(emptyList())
service.getEventList(member)
Mockito.verify(repository).getEventList(false, Lang.JA)
}
```
- [x] **RED:** 비로그인·KR 판정 팝업이 `Lang.KO`를 조회하는 케이스와 관리자 목록의 기존 `isAdult = null` 정책을 추가한다.
- [x] **RED:** `EventRepositoryTest`에 KO·JA 활성 이벤트가 함께 있어도 요청 언어의 목록만 반환하는 케이스를 추가한다.
- [x] **RED:** JA 팝업을 먼저 저장하고 더 최신 ID인 KO 팝업을 나중에 저장한 뒤, JA 조회가 앞선 JA 팝업을 반환하는 케이스를 추가한다.
```kotlin
val japanesePopup = repository.saveAndFlush(activeEvent("ja-popup", Lang.JA, isPopup = true))
repository.saveAndFlush(activeEvent("newer-ko-popup", Lang.KO, isPopup = true))
val result = repository.getMainEventPopup(isAdult = false, lang = Lang.JA)
assertEquals(japanesePopup.id, result?.id)
```
- [x] **RED:** `EventControllerIntegrationTest`에 비로그인 `CloudFront-Viewer-Country: JP`의 목록·팝업이 JA만 반환하고, 헤더 누락 요청이 KO만 반환하는 케이스를 추가한다.
```kotlin
val japaneseEventId = saveControllerEvent("controller-ja", Lang.JA).id!!
saveControllerEvent("controller-ko", Lang.KO)
mockMvc.perform(
get("/event")
.header("CloudFront-Viewer-Country", "JP")
.with(anonymous())
)
.andExpect(status().isOk)
.andExpect(jsonPath("$.data.eventList.length()").value(1))
.andExpect(jsonPath("$.data.eventList[0].id").value(japaneseEventId))
```
`EventControllerIntegrationTest`의 fixture helper는 다음처럼 해당 테스트 파일 내에 정의한다.
```kotlin
private fun saveControllerEvent(seed: String, lang: Lang): Event {
return eventRepository.saveAndFlush(
Event(
thumbnailImage = "$seed-thumbnail.png",
detailImage = "$seed-detail.png",
popupImage = "$seed-popup.png",
link = null,
title = seed,
lang = lang,
isAdult = false,
isPopup = true,
startDate = LocalDateTime.now().minusDays(1),
endDate = LocalDateTime.now().plusDays(1)
)
)
}
```
- [x] **RED 확인:** 아래 focused test를 실행해 `MemberContentPreferenceService` 의존성, `Member?` 서비스 시그니처, Repository `lang` 인자와 필터가 없어 발생하는 컴파일·assertion 실패를 확인한다.
```bash
./gradlew test \
--tests "kr.co.vividnext.sodalive.event.EventServiceTest" \
--tests "kr.co.vividnext.sodalive.event.EventRepositoryTest" \
--tests "kr.co.vividnext.sodalive.event.EventControllerIntegrationTest"
```
- [x] **GREEN:** `EventService`에 `MemberContentPreferenceService`를 생성자 주입하고 앱 진입점 두 개가 `Member?`를 받도록 최소 변경한다.
```kotlin
@Transactional(readOnly = true)
fun getEventList(member: Member?): GetEventResponse {
val isAdult = if (member?.role == MemberRole.ADMIN) {
null
} else {
member?.id?.let { authRepository.getAuthIdByMemberId(it) != null } ?: false
}
return getEventList(isAdult = isAdult, lang = resolveEventLang(member))
}
@Transactional(readOnly = true)
fun getEventPopup(member: Member?): EventItem? {
val isAdult = member?.id?.let { authRepository.getAuthIdByMemberId(it) != null } ?: false
return getEventPopup(isAdult = isAdult, lang = resolveEventLang(member))
}
private fun resolveEventLang(member: Member?): Lang {
return if (memberContentPreferenceService.resolveCountryCode(member) == "JP") Lang.JA else Lang.KO
}
```
- [x] **GREEN:** 기존 저수준 조회 메서드는 nullable `lang`을 받고 Repository에 전달한다.
```kotlin
fun getEventList(isAdult: Boolean? = null, lang: Lang? = null): GetEventResponse
fun getEventPopup(isAdult: Boolean, lang: Lang? = null): EventItem?
```
- [x] **GREEN:** Repository 계약과 구현에 nullable `lang`을 추가하고, null이 아닐 때만 기존 `where`에 언어 조건을 합성한다.
```kotlin
if (lang != null) {
where = where.and(event.lang.eq(lang))
}
```
- [x] **GREEN:** `EventController.getEventList`, `getEventPopup`은 인증 principal에서 얻은 `Member?`를 그대로 새 service 진입점에 전달한다.
```kotlin
service.getEventList(member = member)
service.getEventPopup(member = member)
```
- [x] **GREEN 확인:** 같은 focused test를 재실행해 JP·비JP 언어 전달, Repository 목록·팝업 필터, CloudFront 헤더부터 응답까지 통과하는지 확인한다.
- [x] **REFACTOR:** 국가→언어 선택은 두 호출이 공유하는 한 줄 helper로만 유지하고 신규 resolver·DTO·response field를 만들지 않는다. focused test·`ktlintCheck`를 재실행해 결과를 기록한다.
### Task 2.2 콘텐츠 메인 탭 언어 전체 조회 비회귀
**Goal 실행 `P2-T2`:** 국가별 필터가 지정된 두 API 밖으로 확산되지 않아 `getEventList(isAdult)` 기존 경로가 KO/EN/JA 전체를 조회함을 고정한다.
- **시작 조건:** `P2-T1` 완료, PRD `EVENT-LANG-007`.
- **완료 증거:** service null 언어 전달과 Repository 언어 전체 조회 테스트, mutation RED·복구 후 GREEN 기록.
- **범위 밖:** 콘텐츠 메인 탭 service 6곳의 시그니처·응답 변경.
- **TDD 예외 사유:** `P2-T1`에서 nullable 언어로 호환성을 이미 구현한 뒤 기존 경로를 고정하는 테스트 전용 Task다.
- **대체 검증 방법:** null 조건 테스트 추가 후 Repository에 일시로 KO 강제 조건을 넣어 assertion 실패를 확인하고 즉시 복구한 뒤 동일 테스트의 통과를 확인한다.
**Files:**
- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/event/EventServiceTest.kt`
- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/event/EventRepositoryTest.kt`
- Mutation 후 원상 복구 확인: `src/main/kotlin/kr/co/vividnext/sodalive/event/EventRepository.kt`
**Interfaces:**
- Consumes: `EventService.getEventList(isAdult: Boolean?, lang: Lang? = null)`.
- Produces: `lang = null`이면 `event.lang` 조건을 추가하지 않는 호환성 계약.
- [x] `EventService.getEventList(isAdult = false)`가 `repository.getEventList(false, null)`을 호출함을 검증한다.
- [x] KO·EN·JA 활성 이벤트를 저장하고 `repository.getEventList(isAdult = false, lang = null)`이 세 건을 모두 반환함을 검증한다.
- [x] Repository의 null guard를 일시로 KO 강제 조건으로 변경해 언어 전체 테스트가 의도한 assertion 실패를 보이는지 확인한다.
- [x] 임시 mutation을 즉시 복구하고 아래 focused test를 재실행해 통과를 확인한다.
- [x] `git diff`에 콘텐츠 메인 탭 6곳의 production 파일 변경이 없는지 확인한다.
```bash
./gradlew test \
--tests "kr.co.vividnext.sodalive.event.EventServiceTest" \
--tests "kr.co.vividnext.sodalive.event.EventRepositoryTest"
```
### Phase 2 Gate
**Goal 실행 `P2-GATE`:** 두 앱 API의 국가별 언어 필터와 지정 밖 경로의 비회귀를 최종 판정한다.
- **시작 조건:** `P2-T1`, `P2-T2` 완료.
- **완료 증거:** 아래 focused·직접 영향 test, lint, 문서 명령, 수동 diff 검토 통과와 `Progress` 기록.
- **범위 밖:** 관련 없는 패키지 테스트 수정과 Gate 통과를 위한 테스트 완화.
```bash
./gradlew test \
--tests "kr.co.vividnext.sodalive.admin.event.banner.AdminEventBannerControllerIntegrationTest" \
--tests "kr.co.vividnext.sodalive.event.EventServiceTest" \
--tests "kr.co.vividnext.sodalive.event.EventRepositoryTest" \
--tests "kr.co.vividnext.sodalive.event.EventControllerIntegrationTest" \
--tests "kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceIntegrationTest"
./gradlew ktlintCheck
./gradlew tasks --all
git diff --check
```
**Expected:** 모든 명령이 exit code `0`으로 끝난다. 강제 매핑을 포함한 JP 판정은 JA, 그 외은 KO 목록·팝업만 반환하고 null 언어 내부 조회는 KO/EN/JA 모두를 반환한다.
수동 검증:
- [x] `EventController`의 변경이 `getEventList`, `getEventPopup`에만 있고 레거시 관리자 등록·수정·삭제 계약은 유지되는지 확인한다.
- [x] `EventRepository`의 언어 조건이 `where`에 있고 팝업 `orderBy(event.id.desc()).fetchFirst()`보다 먼저 적용되는지 확인한다.
- [x] `GetEventResponse`, `EventItem`에 신규 필드가 없고 기존 URL 변환과 성인 조건이 유지되는지 확인한다.
- [x] 콘텐츠 메인 탭 6곳의 production 파일과 응답 DTO가 변경되지 않았는지 확인한다.
전체 회귀 `./gradlew test`는 기본 생략한다. 변경이 이벤트·관리자 이벤트·기존 국가 판정 소비 경로에 한정되고 Gate가 persistence·service·controller integration을 모두 포함하기 때문이다. focused test로 영향 범위를 판단할 수 없는 실패, 공통 인증·예외·설정 회귀, 또는 사용자 요청이 있을 때만 실행하고 생략 근거와 대체 명령을 `Progress`에 기록한다.
### Task 2.R1 팝업의 기존 인증 경계 복원
**Goal 실행 `P2-R1`:** `REV-EVENT-LANG-001`에서 확인한 `/event/popup` 익명 공개를 제거하고, 인증 사용자의 국가별 언어 필터만 유지한다.
- **시작 조건:** `P2-GATE` 완료, `reviews/implementation-review.md`의 `REV-EVENT-LANG-001` 확정.
- **완료 증거:** 익명 팝업 401 RED, exact `permitAll()` 제거 후 controller focused GREEN, 직접 영향 5개 클래스와 lint·문서 명령 통과, review·Progress 기록.
- **범위 밖:** `GET /event` 익명 접근, JWT 구현, 언어 선택·Repository 조건, 다른 SecurityConfig matcher.
**Files:**
- Modify: `docs/20260819_이벤트_접속국가별_언어필터/prd.md`
- Modify: `docs/20260819_이벤트_접속국가별_언어필터/plan-task.md`
- Modify: `docs/20260819_이벤트_접속국가별_언어필터/reviews/implementation-review.md`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/configs/SecurityConfig.kt`
- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/event/EventControllerIntegrationTest.kt`
- [x] **RED:** security-on 통합 테스트에 인증 없는 `GET /event/popup`이 HTTP 401을 반환하는 케이스를 추가한다.
- [x] **RED:** JP·국가 누락 팝업 언어 테스트를 기존 `MemberAdapter` 인증 방식으로 전환해 인증 사용자 경로의 KO/JA 응답을 유지한다.
- [x] **RED 확인:** `EventControllerIntegrationTest`를 실행해 익명 401 테스트가 현재 HTTP 200으로 실패하고, 인증 사용자 팝업 테스트는 통과함을 확인한다.
- [x] **GREEN:** `SecurityConfig`에 추가된 `GET /event/popup` exact `permitAll()` 한 줄만 제거한다.
- [x] **GREEN 확인:** `EventControllerIntegrationTest`를 재실행해 익명 401, 익명 목록 200, 인증 사용자 JP→JA·국가 누락→KO가 모두 통과함을 확인한다.
- [x] **REFACTOR:** 추가 abstraction 없이 테스트 helper만 최소화하고 직접 영향 5개 클래스, `ktlintCheck`, `tasks --all`, `git diff --check`를 실행한다.
- [x] PRD 접근 계약, review 상태와 Progress에 실제 결과를 누적한다.
## 실행 순서와 의존성
| 순서 | Goal | 선행조건 | 병행 가능 | 차단 시 다음 행동 |
|---:|---|---|---|---|
| 1 | `P1-T1` | 승인된 PRD | 아니요 | `Event` 실제 테이블·생성자·기존 DDL 패턴 재확인 |
| 2 | `P1-T2` | `P1-T1` | 아니요 | 관리자 controller → service → entity → projection 순으로 계약 대조 |
| 3 | `P1-GATE` | Phase 1 Task 전체 | 아니요 | 실패를 소유한 Task에 회귀 수정 Goal 추가 |
| 4 | `P2-T1` | `P1-GATE` | 아니요 | 국가 판정 → Lang 전달 → QueryDSL 조건 순으로 대조 |
| 5 | `P2-T2` | `P2-T1` | 아니요 | null 조건 호출자와 mutation 복구 상태 확인 |
| 6 | `P2-GATE` | Phase 2 Task 전체 | 아니요 | 실패를 소유한 Task에 회귀 수정 Goal 추가 |
| 7 | `P2-R1` | `P2-GATE`, `REV-EVENT-LANG-001` | 아니요 | 기준 HEAD matcher와 security-on controller test 재대조 |
```text
P1-T1 → P1-T2 → P1-GATE → P2-T1 → P2-T2 → P2-GATE → P2-R1
```
## 변경 금지 항목
- 확정된 PRD와 API 계약을 근거 없이 변경하지 않는다.
- 이벤트 수정 API와 레거시 `POST /event`에 `lang`을 추가하지 않는다.
- 관리자 목록과 콘텐츠 메인 탭 내부 조회에 언어 조건을 추가하지 않는다.
- `EN` 노출 국가, 다른 언어 fallback, `Accept-Language` 정책을 추가하지 않는다.
- `Lang`, `MemberContentPreferenceService`, `CountryContext`와 중복되는 enum·converter·resolver를 만들지 않는다.
- 조회 후 collection filter로 언어를 제거하지 않는다.
- 요청 범위 밖 production 파일·dependency·설정을 변경하지 않는다.
- 테스트를 삭제·skip·완화하거나 타입 오류를 우회해 Gate를 통과하지 않는다.
- JWT, password, signed URL, 파일 본문과 실제 회원 식별자를 문서·fixture·로그에 남기지 않는다.
## 의사결정 및 중단 규칙
- PRD와 현재 구현이 충돌하면 `prd.md` Decision Log와 이 계획을 먼저 갱신한 뒤 구현한다.
- `CloudFront-Viewer-Country`, 기존 강제 KR/JP 매핑 또는 누락 시 KR 정책을 변경해야 하면 범위 확장으로 보고 사용자 승인 전 중단한다.
- 수정 API 언어 변경, 레거시 등록 언어 입력, 콘텐츠 메인 탭 필터가 필요해지면 구현 전에 새 Decision Log와 Task를 추가한다.
- 실제 DB 테이블명이 `event`가 아니거나 DDL 권한·백업이 준비되지 않았으면 DDL 반영만 중단하고 확인 결과를 기록한다.
- 동일한 차단 사유가 최초 시도와 자동 후속을 포함해 3회 연속 반복되고 문서화나 독립 작업도 불가능할 때만 goal을 `blocked`로 갱신한다.
- 체크박스·focused test·완료 증거·Progress 기록이 모두 충족된 뒤에만 goal을 `complete`로 갱신한다.
## Progress
기존 기록을 삭제하거나 덮어쓰지 않고 실제 실행 결과를 차수별로 누적한다.
### 문서 작성 — 2026-08-19
- 상태: 구현 대기
- 무엇을: 사용자 인터뷰 결정을 반영한 PRD와 goal 실행형 구현 계획을 작성했다.
- 왜: 구현 전 PRD·`plan-task.md` 준비 규칙과 코드 구현 금지 요청을 충족하기 위해서다.
- 어떻게: 기존 이벤트·콘텐츠 배너·국가 판정·DDL·테스트 패턴을 대조했고, 모호성 0.02까지 인터뷰한 설계를 사용자가 승인했다.
- 검증:
- placeholder·트레일링 공백·요구사항 ID 누락 검사 결과 문제가 없었다.
- 두 신규 문서에 `git diff --no-index --check` 적용 시 신규 파일 diff를 의미하는 exit code `1`이고 whitespace 오류 출력은 없었다.
- `./gradlew tasks --all`은 최초 sandbox에서 Gradle wrapper lock 접근 제한으로 실패했고, 승인된 동일 명령 재실행에서 `BUILD SUCCESSFUL`을 확인했다.
- `git status --short`에는 이 작업의 신규 문서 디렉터리만 표시되었다.
- 남은 항목: `P1-T1` 이후 구현 전체. production·test·DDL 파일은 아직 변경하지 않았다.
- 다음 행동: 별도 구현 요청이 있을 때 `P1-T1` RED부터 시작한다.
### P1-T1 이벤트 언어 모델과 운영 DDL — 2026-08-20
- 상태: 완료
- 무엇을: `Event.lang`을 `EnumType.STRING`, `nullable = false`, 기본값 `Lang.KO`로 추가하고, JA/KO 영속성 테스트와 3단계 멱등 MySQL DDL을 작성했다.
- 왜: 신규 이벤트의 언어를 필수 저장하고 기존 행은 손실 없이 KO로 이관하기 위해서다.
- 어떻게: 기존 `Lang`, JPA enum 매핑, `@DataJpaTest(properties = ["spring.cache.type=none"])`, `QueryDslConfig` 패턴만 재사용했다.
- 검증:
- RED: `./gradlew test --tests "kr.co.vividnext.sodalive.event.EventRepositoryTest"` 실행 시 `Unresolved reference: lang` 2건과 `Cannot find a parameter with this name: lang` 1건으로 `:compileTestKotlin`이 실패했고 `BUILD FAILED in 20s`를 확인했다.
- GREEN: 같은 focused test 재실행 결과 `BUILD SUCCESSFUL in 48s`, `10 actionable tasks: 8 executed, 2 up-to-date`를 확인했다.
- REFACTOR: `./gradlew ktlintCheck` 결과 `BUILD SUCCESSFUL in 22s`, `7 actionable tasks: 5 executed, 2 up-to-date`를 확인했다.
- `git diff --check`는 exit code `0`이며 출력이 없었다.
- 운영 DDL은 계획 범위에 따라 데이터베이스에 실행하지 않았다.
- 전체 회귀 테스트는 엔티티 필드·focused persistence test·DDL만 변경했고 직접 영향 범위를 focused test로 확인할 수 있어 생략했다.
- 품질 수정: fixture의 `lang` 기본 파라미터와 `Event` 전달을 제거해 KO 케이스가 실제 `Event.lang = Lang.KO` 생성자 기본값을 사용하도록 했다. JA 케이스는 생성 후 `Lang.JA`를 명시 설정해 비기본 enum round-trip을 유지했다.
- 품질 수정 재검증: `./gradlew --no-daemon test --tests "kr.co.vividnext.sodalive.event.EventRepositoryTest"` 결과 `BUILD SUCCESSFUL in 51s`, `10 actionable tasks: 3 executed, 7 up-to-date`를 확인했다.
- 품질 수정 재검증: `./gradlew --no-daemon ktlintCheck` 결과 `BUILD SUCCESSFUL in 22s`, `7 actionable tasks: 2 executed, 5 up-to-date`를 확인했고, `git diff --check`는 exit code `0`이며 출력이 없었다.
- 남은 항목: `P1-T2` 이후 구현 전체. 어떤 Gate도 완료 처리하지 않았다.
- 다음 행동: 별도 구현 요청이 있을 때 `P1-T2` RED부터 시작한다.
### P1-T2 관리자 언어 등록과 언어 전체 목록 — 2026-08-20
- 상태: 완료
- 무엇을: 관리자 이벤트 등록에 필수 `lang`을 추가해 소문자 코드를 `KO`·`EN`·`JA`로 저장하고, 관리자 목록 응답에 모든 활성·미만료 이벤트의 `lang`을 추가했다.
- 왜: 잘못된 언어가 DB나 S3에 부작용을 만들기 전에 거부되고 관리자가 언어별 이벤트를 식별하게 하기 위해서다.
- 어떻게: 기존 `Lang.fromCode`와 `SodaException(messageKey = "common.error.invalid_request")`만 재사용하고, 관리자 QueryDSL projection에 `event.lang`만 추가했다. 조회 `where`는 기존 활성·종료 시각 조건만 유지했다.
- 검증:
- RED: `./gradlew test --tests "kr.co.vividnext.sodalive.admin.event.banner.AdminEventBannerControllerIntegrationTest"` 결과 `shouldPersistLowercaseLanguageWhenAdminCreatesEventBanner`, `shouldRejectInvalidLanguageWithoutPersistenceOrUpload`, `shouldRejectMissingLanguageWithoutPersistenceOrUpload`, `shouldReturnAllActiveNonExpiredLanguagesForAdmin` 4개가 기능 미지원 assertion으로 실패했고 `BUILD FAILED in 49s`를 확인했다.
- RED: 계획의 두 focused test를 함께 실행한 결과 `EventRepositoryTest.kt:48 Unresolved reference: lang`으로 `:compileTestKotlin`이 실패했고 `BUILD FAILED in 7s`를 확인했다.
- GREEN: `./gradlew test --tests "kr.co.vividnext.sodalive.admin.event.banner.AdminEventBannerControllerIntegrationTest" --tests "kr.co.vividnext.sodalive.event.EventRepositoryTest"` 결과 6개 테스트가 통과했고 `BUILD SUCCESSFUL in 36s`, `10 actionable tasks: 3 executed, 7 up-to-date`를 확인했다.
- 최종 focused 재검증: `./gradlew cleanTest test --tests "kr.co.vividnext.sodalive.admin.event.banner.AdminEventBannerControllerIntegrationTest" --tests "kr.co.vividnext.sodalive.event.EventRepositoryTest"`로 `shouldPersistLowercaseLanguageWhenAdminCreatesEventBanner`, `shouldRejectInvalidLanguageWithoutPersistenceOrUpload`, `shouldRejectMissingLanguageWithoutPersistenceOrUpload`, `shouldReturnAllActiveNonExpiredLanguagesForAdmin`와 Repository의 `shouldPersistEventLanguageAndDefaultToKorean`, `shouldReturnAllActiveNonExpiredLanguagesForAdmin`을 실제 재실행했다. 6개 모두 통과했고 `BUILD SUCCESSFUL in 58s`, `11 actionable tasks: 2 executed, 9 up-to-date`를 확인했다.
- REFACTOR: 최초 `ktlintCheck`가 관리자 projection 들여쓰기 5건을 검출해 바로 정리했고, 재실행 결과 `BUILD SUCCESSFUL in 23s`, `7 actionable tasks: 2 executed, 5 up-to-date`를 확인했다.
- `git diff --check`는 exit code `0`이며 출력이 없었다.
- 수동 diff에서 `PUT /admin/event/banner`, `PUT /event`, `POST /event` 요청 파라미터와 `EventController`·`EventService`·`EventRepository`가 변경되지 않았고, 관리자 Repository `where`에 언어 조건이 없음을 확인했다.
- 전체 회귀 테스트는 관리자 이벤트 등록·projection과 직접 영속성 경계를 focused Spring 통합·Repository 테스트가 모두 포함하므로 계획 기준에 따라 생략했다.
- 남은 항목: `P1-GATE` 이후 구현 전체. `P1-GATE`는 완료 처리하지 않았다.
- 다음 행동: 별도 요청이 있을 때 `P1-GATE`를 실행한다.
### P1-GATE 최종 검증 — 2026-08-20
- 상태: 완료
- 무엇을: P1-T1·P1-T2 구현의 focused test, lint, Gradle task 목록, diff whitespace와 세 가지 수동 계약을 최종 검증했다.
- 검증:
- `./gradlew test --tests "kr.co.vividnext.sodalive.admin.event.banner.AdminEventBannerControllerIntegrationTest" --tests "kr.co.vividnext.sodalive.event.EventRepositoryTest"` — exit code `0`, `BUILD SUCCESSFUL in 3s`, 6개 테스트 대상.
- `./gradlew ktlintCheck` — exit code `0`, `BUILD SUCCESSFUL in 10s`.
- `./gradlew tasks --all` — exit code `0`, `BUILD SUCCESSFUL in 9s`.
- `git diff --check` — exit code `0`, 출력 없음.
- 수동 검증 1: diff에서 `PUT /admin/event/banner`, `PUT /event`, `POST /event` request parameter에 `lang` 추가 없음.
- 수동 검증 2: 관리자 Repository `where`는 `event.isActive.isTrue`와 `event.endDate.goe(now)`만 유지하고 `event.lang` 조건 없음.
- 수동 검증 3: DDL이 컬럼 추가 → `KO` backfill → `NOT NULL DEFAULT 'KO'` 순서이며 신규 컬럼 정의에 COMMENT 포함.
- `git status --short --untracked-files=all`과 diff를 확인했으며, 요청대로 plan-task.md만 수정했다. Gradle은 deprecated features 경고를 출력했지만 모든 명령은 exit code `0`이었다.
- 다음 행동: `P2-T1` RED부터 시작한다. P2 체크박스는 변경하지 않았다.
### P2-T1 앱 목록·팝업 국가별 언어 필터 — 2026-08-20
- 상태: 완료
- 무엇을: `GET /event`, `GET /event/popup`이 기존 국가 판정 결과 `JP`에서는 `Lang.JA`, 그 외에는 `Lang.KO`를 QueryDSL `where`에서 적용하도록 구현했다.
- 왜: 정렬과 `fetchFirst()` 전에 언어를 제한해 더 최신인 다른 언어 팝업이 요청 언어 팝업을 가리는 문제를 막기 위해서다.
- 어떻게: controller는 `Member?`를 그대로 전달하고, service는 기존 `MemberContentPreferenceService.resolveCountryCode(member)`와 한 줄 언어 선택 helper를 재사용했다. 저수준 service·Repository 메서드는 nullable `lang = null` 기본값을 유지했으며 콘텐츠 메인 production 호출자 6곳은 수정하지 않았다.
- 검증:
- RED: `./gradlew test --tests "kr.co.vividnext.sodalive.event.EventServiceTest" --tests "kr.co.vividnext.sodalive.event.EventRepositoryTest" --tests "kr.co.vividnext.sodalive.event.EventControllerIntegrationTest"` 실행 시 `memberContentPreferenceService` 생성자 인자, `Member?` service overload, Repository `lang` 인자가 없어 `:compileTestKotlin`이 예상대로 실패했고 `BUILD FAILED in 12s`를 확인했다.
- GREEN: `./gradlew cleanTest test --tests "kr.co.vividnext.sodalive.event.EventServiceTest" --tests "kr.co.vividnext.sodalive.event.EventRepositoryTest" --tests "kr.co.vividnext.sodalive.event.EventControllerIntegrationTest"` 결과 11개 테스트가 통과했고 `BUILD SUCCESSFUL in 39s`를 확인했다.
- service test ID: `shouldQueryJapaneseEventListForJapan`, `shouldQueryKoreanEventPopupForAnonymousKorea`, `shouldKeepAdminAdultFilterNullWhileApplyingResolvedLanguage`.
- Repository test ID: `shouldFilterEventListByKoreanAndJapaneseLanguage`, `shouldFilterPopupByLanguageBeforeSelectingNewestEvent`. JA 팝업을 먼저, 더 최신 KO 팝업을 나중에 저장한 뒤 JA를 반환함을 확인했다.
- controller 통합 test ID: `shouldReturnOnlyJapaneseEventListForAnonymousJapanRequest`, `shouldReturnOnlyJapanesePopupForAnonymousJapanRequest`, `shouldReturnOnlyKoreanEventListWhenCountryHeaderIsMissing`, `shouldReturnOnlyKoreanPopupWhenCountryHeaderIsMissing`. `MemberContentPreferenceService`를 stubbing하지 않고 실제 `CountryInterceptor`와 request-scoped `CountryContext`를 통과시켰다.
- 통합 테스트는 P2-T1 국가·언어 경계에 집중하도록 security filter를 제외하고 인증 정보 없는 요청을 사용했다. 실제 security filter 포함 진단에서 기존 `/event/popup` 익명 요청은 401이었으며 SecurityConfig 변경은 이 Goal의 production 파일 범위 밖이라 변경하지 않았다.
- REFACTOR: 최초 `./gradlew ktlintCheck`가 신규 Repository fixture 들여쓰기 6건을 검출해 정리했고, 재실행 결과 `BUILD SUCCESSFUL in 22s`를 확인했다.
- 최종 focused 재검증: 같은 `cleanTest` 포함 3개 테스트 클래스 명령으로 11개 테스트를 다시 실행해 `BUILD SUCCESSFUL in 1m 26s`를 확인했다.
- 최종 lint 재검증: `./gradlew ktlintCheck` 결과 `BUILD SUCCESSFUL in 13s`를 확인했다.
- `./gradlew tasks --all` 결과 `BUILD SUCCESSFUL in 9s`를 확인했다.
- `git diff --check`는 exit code `0`이며 출력이 없었다.
- 전체 회귀 테스트는 변경이 Event controller/service/Repository와 해당 persistence·Spring MVC 통합 경계에 한정되고 focused 11개 테스트로 직접 영향 범위를 확인할 수 있어 계획 기준에 따라 생략했다.
- 남은 항목: `P2-T2`, `P2-GATE`. 두 Goal은 완료 처리하지 않았다.
### P2-T2 콘텐츠 메인 탭 언어 전체 조회 비회귀 — 2026-08-20
- 상태: 완료
- 무엇을: 저수준 `EventService.getEventList(isAdult = false)`의 `repository.getEventList(false, null)` 전달과 null 언어의 활성 KO·EN·JA 전체 조회 회귀 테스트를 추가했다.
- 검증:
- service test `shouldQueryNonAdultEventListWithoutLanguage`가 `getEventList(false, null)` 호출을 검증한다.
- Repository test `shouldReturnAllActiveLanguagesWhenLanguageIsNull`이 활성 KO·EN·JA 이벤트를 저장하고 세 이벤트 ID와 count 3을 검증한다.
- RED mutation: `EventRepository.kt`의 nullable `lang` guard에 임시 `else event.lang.eq(Lang.KO)`를 추가한 뒤 Repository focused test가 `EventRepositoryTest.kt:101` assertion failure로 종료됨을 확인했다.
- GREEN: mutation을 즉시 제거해 원래 `if (lang != null)` guard를 복구한 뒤 focused EventService/EventRepository test가 `BUILD SUCCESSFUL`로 통과했다.
- 콘텐츠 메인 탭 production 6곳 변경 여부와 `EventRepository` 복구 상태를 diff에서 확인했다.
- `./gradlew ktlintCheck`와 `git diff --check`를 재실행했다.
- 남은 항목: `P2-GATE`. Gate는 완료 처리하지 않았다.
- 다음 행동: `P2-GATE`를 실행한다.
### P2-T1 QA 보안 경계 발견 — 2026-08-20
- 상태: 교정 진행 중
- 발견: `EventControllerIntegrationTest`가 `@AutoConfigureMockMvc(addFilters = false)`로 전체 security filter를 제외해 실제 익명 접근 계약을 검증하지 못했다. 실제 `SecurityConfig`에는 `GET /event`만 `permitAll()`이고 `GET /event/popup` exact matcher가 없어 익명 팝업 요청이 401이었다.
- 계획 보정: P2-T1 production Files에 `SecurityConfig.kt`를 추가하고, 범위를 `GET /event/popup` exact matcher 한 줄로 제한했다. `/event/**` 광역 허용, JWT/auth filter 수정, 다른 matcher 변경은 범위 밖이다.
- 다음 행동: security filter를 켠 controller 통합 테스트로 목록 통과와 팝업 401 RED를 확인한 뒤 exact matcher를 추가한다.
### P2-T1 QA 보안 경계 교정 완료 — 2026-08-20
- 상태: 완료
- 무엇을: `EventControllerIntegrationTest`에서 security filter 제외를 제거하고, `SecurityConfig`에 `HttpMethod.GET`, `/event/popup` exact `permitAll()` matcher만 추가했다.
- RED: `./gradlew cleanTest test --tests "kr.co.vividnext.sodalive.event.EventControllerIntegrationTest"` 결과 4개 중 `shouldReturnOnlyJapanesePopupForAnonymousJapanRequest`, `shouldReturnOnlyKoreanPopupWhenCountryHeaderIsMissing` 2개가 각각 `Status expected:<200> but was:<401>`로 실패했다. 목록 2개는 통과했고 `BUILD FAILED in 46s`였다.
- GREEN: exact matcher 추가 후 같은 security-on controller 통합 테스트 4개가 모두 통과했고 `BUILD SUCCESSFUL in 52s`였다.
- 최종 focused: `./gradlew cleanTest test --tests "kr.co.vividnext.sodalive.event.EventServiceTest" --tests "kr.co.vividnext.sodalive.event.EventRepositoryTest" --tests "kr.co.vividnext.sodalive.event.EventControllerIntegrationTest"` 결과 11개 테스트가 통과했고 `BUILD SUCCESSFUL in 1m 21s`였다.
- 최종 검증: `./gradlew ktlintCheck`는 `BUILD SUCCESSFUL in 36s`, `./gradlew tasks --all`은 `BUILD SUCCESSFUL in 13s`, `git diff --check`는 exit code `0`이며 출력이 없었다.
- 수동 검증: `@AutoConfigureMockMvc`가 실제 security chain을 사용하고 요청은 security postprocessor 없이 익명으로 전송된다. `CountryInterceptor`와 request-scoped `CountryContext` 경로를 유지했으며 `/event/**` 광역 허용이나 다른 SecurityConfig 규칙·순서 변경은 없다.
- 남은 항목: `P2-T2`, `P2-GATE`. 두 Goal은 완료 처리하지 않았다.
- 다음 행동: `P2-T2`에서 nullable 언어의 콘텐츠 메인 전체 조회 비회귀를 mutation RED·GREEN으로 고정한다.
### P2-GATE 최종 검증 — 2026-08-20
- 상태: 완료
- 무엇을: 앱 이벤트 목록·팝업의 국가별 언어 필터, 관리자 이벤트 직접 영향 경로, 기존 국가 판정, 콘텐츠 메인 언어 전체 조회와 네 가지 수동 계약을 최종 판정했다.
- 검증:
- `./gradlew cleanTest test --tests "kr.co.vividnext.sodalive.admin.event.banner.AdminEventBannerControllerIntegrationTest" --tests "kr.co.vividnext.sodalive.event.EventServiceTest" --tests "kr.co.vividnext.sodalive.event.EventRepositoryTest" --tests "kr.co.vividnext.sodalive.event.EventControllerIntegrationTest" --tests "kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceIntegrationTest"` — exit code `0`, `BUILD SUCCESSFUL in 48s`, `11 actionable tasks: 2 executed, 9 up-to-date`. `cleanTest` 후 5개 클래스의 27개 테스트를 실제 실행했고 클래스별 `4 + 4 + 5 + 4 + 10`, failures `0`, errors `0`, skipped `0`이었다.
- `./gradlew ktlintCheck` — exit code `0`, `BUILD SUCCESSFUL in 1s`, `7 actionable tasks: 7 up-to-date`.
- `./gradlew tasks --all` — exit code `0`, `BUILD SUCCESSFUL in 6s`, `1 actionable task: 1 executed`.
- `git diff --check` — exit code `0`, 출력 없음.
- security-on 익명 검증: `EventControllerIntegrationTest`는 `@AutoConfigureMockMvc`에서 filter를 끄지 않고 security postprocessor 없이 `GET /event`, `GET /event/popup`을 호출한다. JP·국가 누락 목록·팝업 4개가 모두 통과했고 `SecurityConfig` diff는 `GET /event/popup` exact `permitAll()` 한 줄뿐이다.
- 수동 검증 1: `EventController` diff는 `getEventList`, `getEventPopup`의 service 전달만 변경했다. 레거시 `POST /event`, `PUT /event`, `DELETE /event/{id}`와 관리자 수정·삭제 파라미터는 변경되지 않았다.
- 수동 검증 2: 목록·팝업의 `event.lang.eq(lang)`은 QueryDSL `where`에 합성되고, 팝업 `.where(where)` 뒤의 `.orderBy(event.id.desc()).fetchFirst()`보다 먼저 적용된다.
- 수동 검증 3: `GetEventResponse`와 같은 파일의 `EventItem` diff는 없었다. `EventService`의 기존 URL 변환은 유지됐고 Repository의 활성·기간·성인 조건과 ID 내림차순 정렬은 언어 조건과 함께 focused test로 통과했다.
- 수동 검증 4: `git diff HEAD --name-only -- src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab`과 `GetEventResponse.kt` 확인 결과 출력이 없었다. 기존 6개 production 호출자는 모두 `eventService.getEventList(isAdult = isAdult)`를 유지한다.
- `git status --short --untracked-files=all`로 staged·unstaged·untracked 파일을 확인했으며 Gate 중 production·test·DDL은 수정하지 않았다.
- 전체 회귀 생략: 변경이 이벤트·관리자 이벤트·기존 국가 판정 소비 경로에 한정되고, 위 5개 클래스가 persistence·service·security-on controller integration과 기존 국가 강제 매핑을 직접 포함해 영향 범위를 판정할 수 있었다. 계획 592행의 확장 조건에 해당하는 실패나 공통 경계 회귀가 없어 `./gradlew test` 전체 실행은 생략했다.
- PRD 감사: 11절 8개 성공 기준을 테스트·diff·DDL로 개별 대조해 구현 증거가 충분한 7개를 완료 처리했다. 운영 DB DDL은 실행 금지 범위이므로 실제 기존 row 이관 완료 항목 1개는 증명하지 않고 미완료로 유지했다.
- 남은 구현 Goal: 없음.
### P2-R1 팝업의 기존 인증 경계 복원 — 2026-08-20
- 상태: 완료
- 발견: 독립 구현 리뷰에서 기준 HEAD의 `GET /event/popup`은 `anyRequest().authenticated()`를 적용받지만, 구현 중 exact `permitAll()`이 추가되어 익명 공개로 확장된 점을 `REV-EVENT-LANG-001`로 확정했다.
- 계획 선반영: production 변경 전에 `Task 2.R1`, `PLAN-DEC-005`, review 문서를 추가하고 PRD의 기존 접근 계약을 기준 HEAD와 일치시켰다.
- RED: security-on `EventControllerIntegrationTest`에 익명 팝업 401을 추가하고 JP·국가 누락 팝업을 `MemberAdapter` 인증 사용자로 전환했다. 5개 중 신규 테스트 1개만 `Status expected:<401> but was:<200>`으로 실패했고, 인증 팝업 2개와 익명 목록 2개는 통과했다. `BUILD FAILED in 34s`였다.
- GREEN: `SecurityConfig`의 신규 `GET /event/popup` exact `permitAll()` 한 줄을 제거했다. 같은 controller 통합 테스트 5개가 모두 통과했고 `BUILD SUCCESSFUL in 38s`였다.
- 직접 영향 회귀: `./gradlew --no-daemon cleanTest test`에 관리자 controller, 이벤트 service/repository/controller, 기존 국가 판정 통합 5개 클래스를 지정해 `4 + 4 + 5 + 5 + 10 = 28`개를 실행했다. failures `0`, errors `0`, skipped `0`, `BUILD SUCCESSFUL in 42s`였다.
- 정적 검증: `./gradlew --no-daemon ktlintCheck`는 `BUILD SUCCESSFUL in 22s`, `./gradlew --no-daemon tasks --all`은 `BUILD SUCCESSFUL in 5s`, `git diff --check HEAD`는 exit code `0`이고 출력이 없었다.
- 수동 검증: 기준 HEAD 대비 `SecurityConfig.kt` diff가 없고, `GET /event` 익명 matcher와 마지막 `anyRequest().authenticated()`가 유지된다. 언어 predicate 두 곳은 QueryDSL `where`에 있으며 콘텐츠 메인 6개 호출자는 기존 `getEventList(isAdult = isAdult)`를 유지한다.
- 독립 재리뷰: 수정 후 최종 diff·PRD·plan·review를 다시 검토해 Critical·Important·Minor 모두 추가 발견 없음, Ready to merge로 판정했다.
- 전체 회귀 생략: security production 변경을 기준 HEAD 상태로 복원했고, 직접 영향 28개가 관리자 등록·목록, persistence, service, security-on controller, 강제 국가 매핑을 포함한다. focused 결과로 영향 범위를 판정할 수 없는 실패가 없어 전체 `./gradlew test`로 확장하지 않았다.
- 남은 구현 Goal: 없음.
## Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 Goal/문서 |
|---|---|---|---|---|---|
| 2026-08-19 | `PLAN-DEC-001` | 확정 | 기존 `Lang`, `Lang.fromCode`, `MemberContentPreferenceService.resolveCountryCode` 조합만 재사용한다. | 중복 없는 최소 구현과 기존 콘텐츠·추천 배너 패턴 | `P1-T2`, `P2-T1` |
| 2026-08-19 | `PLAN-DEC-002` | 확정 | Repository `lang`은 nullable로 두고 두 앱 API만 non-null KO/JA를 전달한다. | 지정된 API만 필터하고 기존 내부 호출을 변경하지 않기 위함 | `P2-T1`, `P2-T2` |
| 2026-08-19 | `PLAN-DEC-003` | 확정 | 국가→언어 변환은 `EventService`의 작은 private helper로 두 앱 조회가 공유한다. | controller의 정책 중복을 피하면서 별도 resolver는 만들지 않는 최소 경계 | `P2-T1` |
| 2026-08-19 | `PLAN-DEC-004` | 확정 | 언어 필터는 QueryDSL `where`에서 적용하고 팝업 정렬·`fetchFirst()` 이전임을 테스트한다. | 잘못된 언어의 최신 팝업이 선택되는 회귀 방지 | `P2-T1`, `P2-GATE` |
| 2026-08-20 | `PLAN-DEC-005` | 확정 | `GET /event`의 익명 접근은 유지하고 `GET /event/popup`은 기준 HEAD의 인증 필수 경계를 복원한다. | 언어 필터 요청과 무관한 보안 범위 확장을 제거 | `P2-R1`, `REV-EVENT-LANG-001` |
## 발견된 문제
- `REV-EVENT-LANG-001`: `GET /event/popup`이 기준 HEAD와 달리 익명 공개된 문제. `P2-R1`에서 수정 완료.
## 최종 보고 규칙
- 첫 문장에 완료한 Phase와 사용자가 얻는 결과를 적는다.
- 변경 항목에 실제 수정한 주요 파일과 동작을 적는다.
- 결정 항목에 적용한 Decision Log ID와 내용을 적는다.
- 검증 항목에 실행 명령·실제 결과·수동 검증 결과를 적는다.
- 전체 회귀를 실행하지 않았으면 생략 근거와 대신 실행한 focused·직접 영향 명령을 적는다.
- 남은 항목과 갱신한 PRD·plan·review 경로를 적는다.
- 성공을 추정하지 않고 실제 실행한 최신 검증 결과와 완료되지 않은 범위를 함께 전달한다.
## Phase 3: 콘텐츠 메인 탭 이벤트 언어 필터 후속
2026-11-02 승인에 따라 과거 `EVENT-LANG-007`의 언어 미필터 요구를 정정한다. P2 완료 체크박스와 검증 기록은 당시 요구 범위의 이력이며 되돌리지 않는다.
### Task 3.1 여섯 메인 탭의 국가별 이벤트 언어 조회
**Goal `P3-T1`:** 콘텐츠 메인 탭 여섯 `eventBannerList`가 기존 회원 국가 판정에 따른 JA 또는 KO 이벤트만 조회하고 기존 성인 계산을 유지한다.
- 시작 조건: `DEC-009`, `EVENT-LANG-010` 승인.
- 완료 증거: 기준 테스트의 사전 통과 기록, RED에서 국가별 언어·기존 성인 조건 assertion 실패, GREEN focused 통과, 실제 HTTP 경로 검증, 전체 회귀·ktlint·bootJar 및 독립 리뷰 결과.
- 범위 밖: 이벤트 상세·팝업 정책, 메인 탭 응답 DTO/URL 변경, 링크·이벤트 파싱, 새 dependency, 운영 DDL 실행, UI 및 기존 성인 계산 변경.
- **Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/alarm/AudioContentMainTabAlarmService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/replay/AudioContentMainTabLiveReplayService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/series/AudioContentMainTabSeriesService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/asmr/AudioContentMainTabAsmrService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/content/AudioContentMainTabContentService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/home/AudioContentMainTabHomeService.kt`
- Verify/reuse (변경 불필요): `src/main/kotlin/kr/co/vividnext/sodalive/event/EventService.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/event/EventRepository.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/event/EventServiceTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/event/EventRepositoryTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/event/EventBannerLanguageIntegrationTest.kt` (new; actual HTTP coverage for the six main-tab endpoints)
- Baseline/related HTTP regression: `src/test/kotlin/kr/co/vividnext/sodalive/content/main/tab/home/AudioContentMainTabHomeServiceIntegrationTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/event/EventControllerIntegrationTest.kt`
- **Interfaces:** reuse `MemberContentPreferenceService.resolveCountryCode(member)` and existing `Lang`; each current caller supplies member-derived language while retaining its existing `isAdult` value. Repository language is non-null on these six paths; existing low-level callers without requested filtering retain their nullable contract. No public response field is added.
- [x] **Baseline:** 부모의 사전 통과 113개 중 기존 `EventServiceTest`, `EventRepositoryTest`, `EventControllerIntegrationTest`, `AudioContentMainTabHomeServiceIntegrationTest` 15개를 재사용했다. 원본: `/tmp/soda-banner-ulw.HDkpg4/baseline.log`.
- [x] **RED:** 여섯 실제 HTTP 경로가 실제 EventService/Repository를 사용하도록 mixed KO/JA/EN 및 성인 true/false/null 행을 추가했다. 국가별 언어와 기존 성인 조건을 응답 ID로 검증한다.
- [x] **RED 확인:** 신규 HTTP 7개 모두 언어 미필터 assertion으로 실패했다. 컴파일·설정 실패가 아니다. `/tmp/soda-banner-impl.CfAkhD/event-red.log`, `event-red.xml`.
- [x] **GREEN:** 여섯 기존 호출부에 member 국가로 선택한 `Lang`만 추가했다. 기존 성인 계산식·EventService/Repository production code·공개 DTO는 변경하지 않았다.
- [x] **GREEN 확인:** focused 22개가 실패·오류·무시 0으로 통과했다. JP/KR/US/누락, 성인 설정 false/true, 강제 JP/KR 회원 및 익명 홈을 실제 HTTP 64건으로 확인했다.
- [x] **REFACTOR:** 전체 2,928개 테스트, 공백 수정 후 영향 26개 HTTP 테스트·전체 ktlint·bootJar 및 독립 리뷰를 확인했다. 운영 DDL은 실행하지 않았다.
```bash
export TMPDIR=/tmp/soda-banner-impl.CfAkhD NODE_COMPILE_CACHE=/tmp/soda-banner-impl.CfAkhD/node-compile-cache BUN_RUNTIME_TRANSPILER_CACHE_PATH=/tmp/soda-banner-impl.CfAkhD/bun-transpiler
./gradlew test --tests 'kr.co.vividnext.sodalive.event.EventServiceTest' --tests 'kr.co.vividnext.sodalive.event.EventRepositoryTest' --tests 'kr.co.vividnext.sodalive.event.EventBannerLanguageIntegrationTest' --tests 'kr.co.vividnext.sodalive.event.EventControllerIntegrationTest' --tests 'kr.co.vividnext.sodalive.content.main.tab.home.AudioContentMainTabHomeServiceIntegrationTest' --console=plain --no-daemon -Pkotlin.compiler.execution.strategy=in-process
./gradlew test ktlintCheck bootJar --continue --console=plain
```
**Expected:** focused tests exercise real country-to-language and HTTP paths; full suite, lint, and bootJar exit 0. LSP diagnostics are unavailable in this environment and must be reported as not run, not as passing.
### Phase 3 Gate `P3-GATE`
- 시작 조건: `P3-T1` 완료.
- 완료 증거: six-caller diff confirms preserved `isAdult`, real HTTP tests show country language filtering, focused/full tests and lint/build pass, independent review has no unresolved blocker.
- 범위 밖: UI, production DB/DDL execution, event detail/adult policy changes.
- [x] 여섯 호출부·반환 언어·공개 DTO 불변을 확인하고 P1/P2 이력을 보존했다. 전체 검증 및 최종 Oracle 승인으로 Gate를 완료했다.
### Phase 3 구현 Progress, 2026-11-02
- 현재 `test` 브랜치/HEAD `7fce26ad`에서 구현했으며 worktree·commit·stage·push는 하지 않았다. 기존 P1/P2 기록과 부모가 승인한 PRD 변경은 보존했다.
- RED 명령은 위 focused 명령에서 `--tests 'kr.co.vividnext.sodalive.event.EventBannerLanguageIntegrationTest'` 하나만 선택했다. JP의 예상 2개 대신 KO/EN까지 6개가 반환되는 assertion 실패 7건을 확인했다. 로그 `event-red.log`, 원본 HTTP/XML `event-red.xml`은 모두 `/tmp/soda-banner-impl.CfAkhD/` 아래에 있다.
- GREEN은 위 focused 명령이며 `event-green-retry.log`에 `BUILD SUCCESSFUL in 4m 15s`가 남는다. Service 4, Repository 5, 기존 Controller 5, 신규 Banner HTTP 7, 기존 Home HTTP 1로 총 22개가 통과했다. 첫 `event-green.log` 실행은 test compilation 중 600초 도구 제한으로 종료되어 통과 근거로 사용하지 않았다. 프로세스 종료 확인 후 제한을 늘려 순차 재실행했다.
- 실제 JWT/랜덤 포트/H2 Event 행/기존 resolver를 사용했다. 여섯 경로 각각 10개 국가·성인·강제 매핑 조합과 익명 홈 4개를 확인했고 `Accept-Language: en`에도 국가 기준 언어가 선택됐다. `event-http-evidence.log`의 64건과 `event-green.xml`에 실제 상태·본문이 남으며 토큰은 출력하지 않았다.
- 구현 및 focused/HTTP 범위만 완료했다. 사용자 지정 종료 경계에 따라 전체 suite·ktlint·bootJar·독립 리뷰와 `P3-GATE`는 부모 작업으로 미완료 유지한다. LSP 진단 도구는 없어 실행하지 않았다. 구현 보고서: `/tmp/soda-banner-impl.CfAkhD/implementation-report.md`.
- 최종 source 상태에서 위 5개 클래스와 Phase 7의 6개 클래스를 하나의 focused 명령으로 순차 재검증했다. `final-focused.log`: `BUILD SUCCESSFUL in 8m 8s`, 11개 클래스 145개, 실패·오류·무시 0. 최종 원본은 같은 root의 `final-TEST-*.xml`, 실제 HTTP 본문은 `final-http-db-evidence.log`다. 전체 suite 실행은 아니다.
### Phase 3 최종 검증 Progress, 2026-11-03
- 부모 실행: `./gradlew test ktlintCheck bootJar --continue --console=plain --no-daemon -Pkotlin.compiler.execution.strategy=in-process`. 전체 XML 집계는 336 suites / 2,928 tests / failures=0 / errors=0 / skipped=0이며 `bootJar`도 성공했다. 최초 명령은 서브 배너 테스트 팩토리 인자 줄바꿈 한 곳의 ktlint 오류로 exit 1 (15m 50s)이었다. 테스트 실패나 제품 코드 오류는 아니었다.
- 해당 테스트 인자 여섯 개를 값·순서 변경 없이 줄별로 배치한 뒤 `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.subbanner.adapter.in.web.RecommendationSubBannerIntegrationTest' ktlintCheck bootJar --continue --console=plain --no-daemon -Pkotlin.compiler.execution.strategy=in-process`를 실행했다. exit 0, `BUILD SUCCESSFUL in 4m 32s`, 26 tests / failures=0 / errors=0 / skipped=0, 전체 lint 통과, bootJar UP-TO-DATE다.
- 전체 회귀 후 변경은 테스트의 공백뿐이므로 전체 2,928개를 다시 실행하지 않고 영향받은 26개 HTTP 시나리오를 재실행했다. 최신 `build/test-results/test`와 HTML은 이 26개 실행으로 갱신됐다. 전체 집계는 갱신 전 부모가 직접 확인한 기록이다.
- 부모는 전체 실행으로 실제 HTTP 테스트를 다시 구동하고 두 추천의 JP/KR/US/누락·강제 국가, 기간·소프트 삭제·공개 6필드 재검증 결과를 확인했다. 제품 JAR: `build/libs/sodalive-0.0.1-SNAPSHOT.jar`.
- LSP 도구 부재로 미실행이며 Gradle Kotlin compile 및 ktlint를 대체 진단으로 사용했다. 기존 무관 파일의 컴파일/Gradle 경고와 H2 scheduler의 MySQL 문법 로그는 테스트 실패와 구분하며 수정하지 않았다.
- 원본 로그는 실행 당시 `/tmp/soda-banner-ulw.HDkpg4/full-verification.log`, `final-verification.log`에 보관했다. 소유 임시 자료는 종료 시 정리하고 핵심 결과는 본 기록과 [공동 리뷰](../20261029_가로형서브배너/reviews/banner-language-review.md)에 보존한다.
- 독립 Oracle 리뷰는 명세·코드·시나리오를 승인했고, 후속 공백 delta와 최종 검증 증거도 APPROVE했다. 미해결 발견 사항 없음. `P3-T1/P3-GATE` 완료이며 운영 배포는 별도다.
- 메인 탭 구현·테스트 커밋 `255da2b6`, hook/메시지 검사 통과. 소유 QA 프로세스와 임시 경로 정리는 공동 리뷰의 종료 증거에 기록했다. 운영 배포·push는 하지 않았다.
@@ -1,215 +0,0 @@
# 이벤트 접속 국가별 언어 필터 PRD
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | Phase 3 메인 탭 후속 언어 필터 구현·전체 검증·독립 리뷰 완료, 미배포 |
| 작성일 | 2026-08-19 |
| 최종 수정일 | 2026-11-03 |
| 대상 제품 | 관리자 이벤트 배너, 앱 이벤트 목록·팝업 |
| 작성자·결정권자 | 사용자 |
| 관련 API Contract | 별도 문서 없음. 이 문서 8절을 기준으로 사용 |
| 관련 구현 계획 | `docs/20260819_이벤트_접속국가별_언어필터/plan-task.md` |
| 관련 기존 문서 | `docs/20260819_추천탭_배너_접속국가별_언어필터/prd.md` |
## 1. Overview
관리자가 이벤트를 등록할 때 기존 콘텐츠 배너처럼 언어를 지정한다. 관리자 목록은 언어로 필터링하지 않고 각 이벤트의 언어를 표시한다. 앱의 `GET /event`, `GET /event/popup`은 기존 접속 국가 판정 결과가 `JP`이면 일본어, 그 외에는 한국어 이벤트만 반환한다.
## 2. Problem Statement
- `Event`에는 언어 필드가 없어 관리자가 한국어·일본어 이벤트를 구분해 등록할 수 없다.
- 앱 이벤트 목록과 팝업 조회는 접속 국가를 고려하지 않아 여러 언어의 이벤트가 섞일 수 있다.
- 팝업을 조회한 뒤 메모리에서 언어를 걸러내면 다른 언어의 최신 팝업이 `fetchFirst()`를 차지해 필요한 팝업을 놓칠 수 있다.
문제를 해결했다는 판단은 관리자가 허용된 언어로 이벤트를 등록·식별할 수 있고, 두 앱 API가 기존 조회 조건을 유지하면서 DB 조회 단계에서 판정 언어만 반환하는 것으로 한다.
## 3. Goals
- 관리자는 이벤트 등록 시 `KO`, `EN`, `JA` 중 하나를 필수로 지정한다.
- 관리자 이벤트 목록은 기존 활성·종료 시각 조건 안에서 모든 언어를 반환하고 `lang`을 포함한다.
- 기존 `MemberContentPreferenceService.resolveCountryCode(member)`로 강제 KR/JP 회원 매핑, 요청 국가 정규화, 누락 시 KR 기본값을 그대로 재사용한다.
- 판정 국가가 `JP`이면 `Lang.JA`, 그 외에는 `Lang.KO`를 선택한다.
- 언어 조건을 QueryDSL `where`에 적용해 정렬과 `fetchFirst()`보다 먼저 필터링한다.
- 기존 이벤트 데이터와 레거시 등록 경로의 기본 언어는 `KO`로 유지한다.
## 4. Non-Goals
- 이벤트 수정 API에서 `lang`을 변경하지 않는다.
- `EventController.createEvent`의 `POST /event` 요청 계약을 변경하지 않는다.
- [2026-11-02 정정, DEC-009] 콘텐츠 메인 탭 6곳의 `eventBannerList`는 Phase 2 당시 언어 필터 제외 결정의 범위였으나, 이번 후속 요구로 각 호출에 기존 접속 국가 판정에 따른 언어 필터를 적용한다. 과거 구현·검증 기록은 당시 범위로 보존한다.
- `Lang`에 새 enum을 추가하거나 `EN`을 노출할 접속 국가 정책을 추가하지 않는다.
- `Accept-Language`를 이벤트 언어 판정에 사용하지 않는다.
- 요청 언어의 이벤트가 없을 때 다른 언어로 fallback하지 않는다.
- 기존 이벤트의 성인·활성·시작·종료·정렬 정책과 응답 이미지 URL 처리를 변경하지 않는다.
## 5. 대상 사용자와 권한
| 사용자 | 주요 동작 | 국가·언어 정책 |
|---|---|---|
| 관리자 | 이벤트 등록, 언어 전체 목록 조회 | 등록 시 `KO`/`EN`/`JA` 중 하나를 지정, 목록에서 `lang` 확인 |
| 강제 JP 매핑 회원 | 앱 목록·팝업 조회 | 요청 헤더보다 우선하는 `JP` 판정, `JA` 조회 |
| 강제 KR 매핑 회원 | 앱 목록·팝업 조회 | 요청 헤더보다 우선하는 `KR` 판정, `KO` 조회 |
| 일반 로그인 회원 | 앱 목록·팝업 조회 | 정규화한 `CloudFront-Viewer-Country`가 `JP`이면 `JA`, 그 외 `KO` |
| 비로그인 사용자 | 앱 목록 조회 | 정규화한 요청 국가가 `JP`이면 `JA`, 누락·그 외 `KO` |
- 관리자 이벤트 API의 기존 `ROLE_ADMIN` 인가를 유지한다.
- 앱 이벤트 목록은 기존 비로그인 접근을 유지하고, 팝업은 기존처럼 인증 사용자만 접근한다.
## 6. 핵심 흐름
### 6.1 관리자 등록·조회
1. 관리자가 `POST /admin/event/banner` multipart 요청에 `lang`을 필수로 보낸다.
2. 서버는 기존 `Lang.fromCode` 규칙으로 `ko`/`KO`, `en`/`EN`, `ja`/`JA`를 처리한다.
3. 허용되지 않는 값은 `common.error.invalid_request`로 거부하고 이벤트를 저장하지 않는다.
4. `GET /admin/event/banner`는 기존처럼 활성 상태이고 종료 시각이 지나지 않은 이벤트를 언어 조건 없이 반환한다.
5. 각 관리자 응답 항목은 `lang`을 포함한다.
### 6.2 앱 목록·팝업 조회
1. `CountryInterceptor`가 `CloudFront-Viewer-Country`를 `CountryContext`에 저장한다.
2. `EventController`는 인증 사용자 `Member?`를 `EventService`에 전달한다.
3. `EventService`는 `MemberContentPreferenceService.resolveCountryCode(member)`를 호출한다.
4. 국가 결과가 `JP`이면 `Lang.JA`, 그 외에는 `Lang.KO`를 선택한다.
5. `EventRepository`는 기존 성인·활성·게시 기간 조건과 언어 조건을 DB에서 함께 적용한다.
6. 해당 언어의 이벤트가 없으면 목록은 빈 `eventList`, 팝업은 `null`을 반환한다.
### 6.3 기존 내부 조회
1. 콘텐츠 메인 탭 6곳은 기존 `EventService.getEventList(isAdult)`를 유지한다.
2. 이 경로는 Repository에 `lang = null`을 전달해 언어 조건을 추가하지 않는다.
3. 기존 응답 조립 범위와 순서를 변경하지 않는다.
## 7. 기능 요구사항
| ID | 상태 | 요구사항 | 수용 기준 | Goal 연결 |
|---|---|---|---|---|
| `EVENT-LANG-001` | 확정 | 관리자 이벤트 등록은 `lang`을 필수로 받는다. | `KO`, `EN`, `JA`가 저장되고 누락·잘못된 값은 저장 전 거부된다. | `P1-T2` |
| `EVENT-LANG-002` | 확정 | 이벤트 언어는 등록 후 수정하지 않는다. | 두 수정 API의 요청·서비스 시그니처에 `lang`이 추가되지 않는다. | `P1-GATE` |
| `EVENT-LANG-003` | 확정 | 관리자 목록은 모든 언어를 조회하고 `lang`을 반환한다. | 기존 활성·종료 시각 조건을 만족하는 KO/EN/JA 항목이 언어 필터 없이 반환되고 각 항목에 `lang`이 있다. | `P1-T2` |
| `EVENT-LANG-004` | 확정 | `GET /event`는 판정 국가가 JP이면 JA, 그 외에는 KO 이벤트만 반환한다. | 서로 다른 언어의 활성 이벤트가 함께 있어도 판정 언어만 `eventList`에 있다. | `P2-T1` |
| `EVENT-LANG-005` | 확정 | `GET /event/popup`은 판정 국가가 JP이면 JA, 그 외에는 KO 팝업만 반환한다. | 다른 언어 팝업의 ID가 더 최신이어도 언어 필터 후 선택된 팝업을 반환한다. | `P2-T1` |
| `EVENT-LANG-006` | 확정 | 로그인 회원은 기존 강제 KR/JP 매핑을 포함한 국가 판정을 사용한다. | 강제 JP 회원은 비JP 헤더에서도 JA, 강제 KR 회원은 JP 헤더에서도 KO를 선택한다. | `P2-T1` |
| `EVENT-LANG-007` | 과거 요구, `DEC-009`에서 정정 | Phase 2 당시 콘텐츠 메인 탭 `eventBannerList`는 언어 필터 없이 조회하도록 확정했다. 이 요구는 `EVENT-LANG-010`으로 대체됐으며 현재 적용하지 않는다. | P2 당시 `lang = null`의 전체 언어 조회를 검증한 완료 증거는 역사적 기록으로 보존한다. | `P2-T2` (당시), `P3-T1` (대체) |
| `EVENT-LANG-008` | 확정 | 기존 이벤트와 레거시 등록 경로의 언어는 KO다. | 기존 row를 KO로 backfill하고 `NOT NULL DEFAULT 'KO'`를 적용하며 `POST /event`에 `lang`을 추가하지 않는다. | `P1-T1` |
| `EVENT-LANG-009` | 확정 | 앱 언어 필터는 DB 조회 조건으로 적용한다. | QueryDSL `where` 내 `event.lang.eq(lang)`이 정렬·`fetchFirst()` 전에 적용된다. | `P2-T1` |
| `EVENT-LANG-010` | 확정, 2026-11-02 후속 | 콘텐츠 메인 탭 6곳의 `eventBannerList`도 접속 국가별 이벤트 언어를 조회한다. | 기존 `resolveCountryCode(member)` 결과가 JP이면 JA, 그 외에는 KO만 반환하며 각 호출부의 기존 `isAdult` 계산과 응답 계약은 유지한다. | `P3-T1`, `P3-GATE` |
## 8. API 계약
### 8.1 관리자 등록
| 항목 | 내용 |
|---|---|
| Method / Path | `POST /admin/event/banner` |
| 인증 | `ROLE_ADMIN` |
| Content-Type | `multipart/form-data` |
| 신규 필수 파라미터 | `lang`: `ko`, `en`, `ja` 또는 대소문자를 달리한 동일 enum 코드 |
| 잘못된 값 | `common.error.invalid_request`, 저장·업로드 없음 |
| 기존 파라미터 | 스키마와 필수·선택 정책 유지 |
### 8.2 관리자 목록
| 항목 | 내용 |
|---|---|
| Method / Path | `GET /admin/event/banner` |
| 조회 조건 | 기존 `is_active = true`, `end_date >= now`; 언어 조건 없음 |
| 응답 변경 | `GetAdminEventResponse.lang: Lang` 추가 |
| 기존 응답 필드 | 이름·타입·URL 처리 유지 |
### 8.3 앱 조회
| Method / Path | 변경 내용 | 빈 결과 |
|---|---|---|
| `GET /event` | 기존 응답 스키마를 유지하고 판정 언어 조건만 추가 | `eventList = []` |
| `GET /event/popup` | 기존 응답 스키마를 유지하고 판정 언어 조건만 추가 | `data = null` |
- 신규 request header를 추가하지 않고 기존 `CloudFront-Viewer-Country`를 사용한다.
- `GET /event`는 기존처럼 비로그인 접근을 허용하고, `GET /event/popup`은 기존 인증 필수 정책을 유지한다.
- 앱 응답에 `lang`을 추가하지 않는다.
- `EN` 이벤트는 관리자가 등록·조회할 수 있지만 현재 두 앱 API의 국가 정책으로는 노출되지 않는다.
## 9. 데이터 정책
- `Event.lang`은 기존 `kr.co.vividnext.sodalive.i18n.Lang`을 `EnumType.STRING`으로 저장한다.
- 엔티티 기본값은 `Lang.KO`로 둔다.
- 운영 DB DDL은 `event.lang VARCHAR(10)`을 nullable로 추가한 뒤 기존 `NULL`을 `KO`로 backfill하고 `NOT NULL DEFAULT 'KO'`로 변경한다.
- DDL은 두 번 실행해도 이미 적용된 단계를 건너뛸는 기존 `information_schema` + `PREPARE` 패턴을 따른다.
- 기존 row의 언어를 별도로 추론하거나 이미지·제목을 분석해 자동 분류하지 않는다.
## 10. 성능·품질·보안 요구사항
- 언어 조건은 Repository QueryDSL `where`에서 적용하고 메모리 후처리를 추가하지 않는다.
- 기존 `Lang`, `MemberContentPreferenceService`, `CountryContext`를 재사용하고 신규 dependency·resolver abstraction을 추가하지 않는다.
- 언어 파라미터는 `Lang.fromCode`로 정규화·검증하고 잘못된 값을 엔티티 생성과 S3 업로드 전에 거부한다.
- 민감정보·헤더·파일 본문을 신규 로그에 기록하지 않는다.
- TDD는 관리자 등록·목록, 앱 국가별 목록·팝업, 기존 내부 전체 언어 조회 비회귀를 포함한다.
- focused test 후 직접 영향 회귀와 `ktlintCheck`를 실행한다. 전체 회귀는 targeted test로 영향 범위를 판단할 수 없거나 공통 경계 회귀가 발생할 때만 확장한다.
## 11. 성공 기준
- [x] 관리자가 `KO`, `EN`, `JA` 이벤트를 등록하고 목록에서 각 언어를 확인한다. (`EVENT-LANG-001`, `EVENT-LANG-003`)
- [x] 수정 API와 레거시 `POST /event`의 요청 계약이 변경되지 않는다. (`EVENT-LANG-002`, `EVENT-LANG-008`)
- [ ] 기존 이벤트 모두가 KO로 이관되고 신규 언어 누락 row가 생성되지 않는다. (`EVENT-LANG-008`)
- [x] 판정 국가 JP에서 `GET /event`, `GET /event/popup`이 JA만 반환한다. (`EVENT-LANG-004~006`)
- [x] JP 이외와 국가 누락에서 두 API가 KO만 반환한다. (`EVENT-LANG-004`, `EVENT-LANG-005`)
- [x] 다른 언어의 최신 팝업이 있어도 언어 필터 후 선택된 팝업이 반환된다. (`EVENT-LANG-005`, `EVENT-LANG-009`)
- [x] Phase 2 당시 콘텐츠 메인 탭 6곳의 `eventBannerList`가 언어 필터 없이 조회됨을 검증했다. 이는 당시 요구에 대한 완료 이력이다. (`EVENT-LANG-007`)
- [x] 후속 요구: 콘텐츠 메인 탭 6곳의 `eventBannerList`가 JP→JA, 그 외→KO만 조회하며 기존 `isAdult` 계산을 유지한다. (`EVENT-LANG-010`, `P3-T1`, `P3-GATE`; 2026-11-03 전체 2,928개 및 실제 HTTP 검증 완료)
- [x] 기존 성인·활성·게시 기간·정렬·URL·응답 스키마 정책이 유지된다.
### 11.1 구현 완료 검증 — 2026-08-20
- 관리자 등록·목록: `AdminEventBannerControllerIntegrationTest` 4개와 `EventRepositoryTest`의 관리자 전체 언어 조회가 통과했다. `Lang.fromCode`는 기존 `KO`, `EN`, `JA` enum의 code/name을 대소문자 무시로 처리하며, 누락·잘못된 값은 저장·업로드 없이 거부된다.
- 레거시 계약: controller·service diff에서 관리자 수정·삭제와 `POST /event`, `PUT /event`, `DELETE /event/{id}`에 `lang`이 추가되지 않았다.
- DB 이관: `20260819_event_lang_ddl.sql`이 nullable 컬럼 추가 → `NULL`의 KO backfill → `NOT NULL DEFAULT 'KO'` 순서를 갖고, 엔티티 기본값과 JA/KO 영속성 테스트도 통과했다. 다만 운영 DDL은 실행하지 않았으므로 실제 기존 row 전체 이관 완료는 증명하지 않고 체크하지 않았다.
- JP·강제 매핑: security-on 익명 JP 목록과 인증 JP 팝업 통합 테스트, `EventServiceTest`의 JP→JA 전달, `MemberContentPreferenceIntegrationTest`의 강제 JP/KR 매핑이 통과했다.
- 비JP·누락: 국가 누락의 익명 KO 목록과 인증 KO 팝업 통합 테스트, 일반 회원의 US·누락 판정과 비로그인 JP 정규화·누락 KR 테스트가 통과했다. service의 `JP` 이외→`KO` 분기도 diff로 확인했다.
- 팝업 선필터: 더 최신 KO와 성인 JA 팝업이 있어도 비성인 JA 조회가 대상 JA를 반환하는 Repository 테스트가 통과했고, 언어 predicate가 `where`에서 정렬·`fetchFirst()` 전에 적용됨을 확인했다.
- 콘텐츠 메인: 저수준 service의 `lang = null` 전달과 Repository의 KO/EN/JA 3건 전체 조회 테스트가 통과했다. 6개 production 호출자와 해당 응답 DTO 디렉터리 diff는 없었다.
- 기존 정책: Repository 테스트가 활성·시작·종료·성인·ID 내림차순 조건을 함께 검증했고, `EventService` URL 변환 및 `GetEventResponse`·`EventItem` diff가 없음을 확인했다. 구현 리뷰 후 익명 팝업 401과 인증 팝업의 국가별 언어를 함께 검증했고 기준 HEAD 대비 `SecurityConfig` diff가 없음을 확인했다.
## 12. Open Questions
- 없음.
## 13. 요구사항 추적표
| 요구사항 범위 | 계획 Phase | Goal | 자동 검증 |
|---|---:|---|---|
| `EVENT-LANG-001~003`, `EVENT-LANG-008` | 1 | `P1-T1`, `P1-T2`, `P1-GATE` | 엔티티·관리자 controller/service/repository 통합 테스트 |
| `EVENT-LANG-004~006`, `EVENT-LANG-009` | 2 | `P2-T1`, `P2-GATE` | `EventServiceTest`, `EventRepositoryTest`, `EventControllerIntegrationTest` |
| `EVENT-LANG-007` | 2 | `P2-T2`, `P2-GATE` | 언어 없는 기존 서비스 호출과 Repository null 조건 비회귀 테스트 |
| `EVENT-LANG-010` | 3 | `P3-T1`, `P3-GATE` | 여섯 호출부의 국가별 language filter, adult 조건 비회귀, 실제 HTTP 테스트 |
## 14. Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항·Goal |
|---|---|---|---|---|---|
| 2026-08-19 | `DEC-001` | 확정 | 앱 국가 판정은 기존 `MemberContentPreferenceService.resolveCountryCode(member)`를 사용한다. | 사용자 인터뷰 A | `EVENT-LANG-004~006`, `P2-T1` |
| 2026-08-19 | `DEC-002` | 확정 | 등록 언어는 기존 `Lang`의 `KO`, `EN`, `JA` 모두를 허용한다. | 사용자가 A를 철회하고 B로 확정, 신규 언어 타입·검증 중복 방지 | `EVENT-LANG-001`, `P1-T2` |
| 2026-08-19 | `DEC-003` | 확정 | 언어는 등록할 때만 지정하고 수정하지 않는다. | 사용자 인터뷰 A, 콘텐츠 배너의 현재 패턴 | `EVENT-LANG-002`, `P1-GATE` |
| 2026-08-19 | `DEC-004` | 확정 | 관리자 목록은 언어 전체를 조회하고 `lang`을 응답한다. | 사용자 인터뷰 A | `EVENT-LANG-003`, `P1-T2` |
| 2026-08-19 | `DEC-005` | 확정 | 국가별 필터는 `EventController.getEventList`, `getEventPopup`에만 적용한다. | 사용자 인터뷰 A | `EVENT-LANG-004`, `EVENT-LANG-005`, `EVENT-LANG-007`, `P2-T1~T2` |
| 2026-08-19 | `DEC-006` | 확정 | 기존 이벤트는 KO로 backfill하고 `NOT NULL DEFAULT 'KO'`를 적용한다. | 사용자 인터뷰 A, 기존 배너 DDL 패턴 | `EVENT-LANG-008`, `P1-T1` |
| 2026-08-19 | `DEC-007` | 확정 | 언어 입력은 `AdminEventBannerController`에만 추가하고 레거시 `POST /event`는 KO 기본값을 사용한다. | 사용자 인터뷰 A | `EVENT-LANG-002`, `EVENT-LANG-008`, `P1-T1~T2` |
| 2026-08-20 | `DEC-008` | 확정 | `GET /event`의 익명 접근은 유지하고 `GET /event/popup`은 기준 HEAD의 인증 필수 정책을 유지한다. | 구현 리뷰에서 언어 필터와 무관한 익명 공개 확장을 확인 | `EVENT-LANG-005`, `P2-R1` |
| 2026-11-02 | `DEC-009` | 정정 | 기존 콘텐츠 메인 탭 6곳의 언어 미필터 요구를 대체한다. 각 `eventBannerList` 호출은 기존 회원 국가 판정 `resolveCountryCode(member)`를 사용해 JP→JA, 그 외→KO로 필터링한다. 기존 `isAdult` 계산, 응답 계약 및 과거 구현 기록은 보존한다. | 승인된 최소 후속 언어 수정 | `EVENT-LANG-007`의 과거 범위, `EVENT-LANG-010`, `P3-T1` |
## 15. 변경 관리
요구사항이 변경되면 다음 순서로 갱신한다.
1. 이 문서의 Decision Log에 변경 이유와 날짜를 추가한다.
2. 관련 요구사항·수용 기준·API 계약을 갱신한다.
3. `plan-task.md`의 범위·Files·Interfaces·체크박스를 코드 변경 전에 먼저 갱신한다.
4. 기존 Progress·검증 기록을 삭제하거나 덮어쓰지 않는다.
## 16. 후속 요구사항: 메인 탭 이벤트 언어 — 2026-11-02
- 승인된 변경은 콘텐츠 메인 탭의 기존 `eventBannerList`를 조립하는 6개 호출부에만 적용한다. 접속 국가 판정은 기존 `MemberContentPreferenceService.resolveCountryCode(member)`를 재사용해 `JP`는 `Lang.JA`, 그 외는 `Lang.KO`로 변환한다.
- 기존 각 호출부의 `isAdult` 계산과 성인 필터 동작은 변경하지 않는다. 언어 조건은 기존 Event Repository 조회 경로에서 DB 조건으로 적용한다.
- 이벤트 상세, 팝업/API 이외 정책, 공개 응답 DTO·URL 처리, 이벤트 연결 파싱은 변경하지 않는다. 새 dependency와 별도 resolver를 추가하지 않는다.
- 관련 성공 기준·추적표는 `EVENT-LANG-010` 및 `P3-T1`/`P3-GATE`에 연결한다. 과거 `EVENT-LANG-007`과 완료된 P2 증거는 당시 언어 전체 조회 계약의 기록이며 현재 메인 탭 요구사항을 지배하지 않는다.
@@ -1,148 +0,0 @@
# 이벤트 접속 국가별 언어 필터 구현 리뷰
## 1. 리뷰 정보
| 항목 | 내용 |
|---|---|
| 리뷰 대상 | Phase 1~2 전체 구현과 `P1-GATE`, `P2-GATE` |
| 기준 commit 또는 working tree | 기준 `2ad30f90699a03162000d3b87be39f45b92740af` + 미커밋 구현 변경 |
| 리뷰 일자 | 2026-08-20 |
| 리뷰어 | Codex, 독립 리뷰 agent `event_language_review` |
| 기준 문서 | `prd.md`, `plan-task.md` |
| 리뷰 상태 | 수정 검증 완료 |
## 2. 리뷰 목적과 범위
### 목적
- 구현이 `EVENT-LANG-001~009`와 기존 API 경계를 충족하는지 확인한다.
- 완료 기록과 실제 코드·테스트 결과가 일치하는지 확인한다.
### 포함 범위
- 코드: 관리자 이벤트 등록·목록, 앱 이벤트 controller/service/repository, `Event`, `SecurityConfig`
- 테스트: 관리자·앱 controller 통합, service, repository, 기존 국가 판정 통합 테스트
- 문서: `prd.md`, `plan-task.md`, 운영 DDL
### 제외 범위
- 운영 DB DDL 실제 실행과 배포
- 이벤트 언어와 관계없는 기능
## 3. 판정 기준
| 심각도 | 기준 |
|---|---|
| Blocker | 보안·데이터 손실 위험 또는 핵심 흐름 불능 |
| High | 확정 요구사항·기존 API 경계 위반 또는 주요 회귀 |
| Medium | 제한된 조건의 기능·복구 문제 |
| Low | 비핵심 유지보수성·문서 정합성 문제 |
## 4. 검토한 근거
### 문서와 코드
- 요구사항: `EVENT-LANG-001~009`
- 계획: `P1-T1~P2-GATE`
- 코드: `AdminEventBannerController`, `AdminEventBannerService`, `AdminEventBannerRepository`, `EventController`, `EventService`, `EventRepository`, `Event`, `SecurityConfig`
- 테스트: `AdminEventBannerControllerIntegrationTest`, `EventControllerIntegrationTest`, `EventServiceTest`, `EventRepositoryTest`, `MemberContentPreferenceIntegrationTest`
### 실행 환경
```text
OS: Darwin 25.0.0 x86_64
Java: OpenJDK 17.0.15
Build: Gradle Wrapper 8.1.1
DB: 테스트용 H2 MySQL mode
```
### 실행한 검증
| 명령 또는 수동 검증 | 결과 | 핵심 증거 |
|---|---|---|
| 직접 영향 5개 클래스 `cleanTest test` | 성공 | 겹침 제거 후 exit code 0, 27개 테스트 통과, `BUILD SUCCESSFUL in 46s` |
| 독립 리뷰의 동일 5개 클래스 실행 | 성공 | exit code 0, `BUILD SUCCESSFUL in 56s` |
| 전체 호출자·기준 HEAD 보안 설정 diff 대조 | 발견 | 기준 HEAD의 `/event/popup`은 `anyRequest().authenticated()` 적용 |
| 수정 후 독립 정적 재리뷰 | 성공 | Critical·Important·Minor 추가 발견 없음, Ready to merge 판정 |
| `git diff --check HEAD` | 성공 | exit code 0, whitespace 오류 없음 |
동시에 실행된 두 Gradle `cleanTest`가 같은 XML 결과 경로를 사용해 한 차례 writer 경합이 발생했다. 테스트 assertion은 모두 통과했고, 병행 실행을 중단한 뒤 동일 명령을 재실행해 성공 종료를 확인했다.
## 5. 발견 사항 요약
| ID | 심각도 | 상태 | 제목 | 소유 Task | 후속 goal |
|---|---|---|---|---|---|
| `REV-EVENT-LANG-001` | High | 수정 완료 | `GET /event/popup`의 기존 인증 경계가 익명 공개로 확장됨 | `P2-T1` | `P2-R1` |
언어 저장·관리자 전체 언어 조회·앱 KO/JA QueryDSL 필터·콘텐츠 메인 null 언어 경로에서는 추가 확정 문제를 찾지 못했다.
## 6. 발견 사항 상세
### REV-EVENT-LANG-001 — `GET /event/popup`의 기존 인증 경계가 익명 공개로 확장됨
- **심각도:** High
- **상태:** 수정 완료
- **관련 요구사항:** `EVENT-LANG-005`, 기존 접근 정책 유지
- **소유 Task:** `P2-R1`
**관찰 내용**
기준 HEAD의 `SecurityConfig`는 `GET /event`만 `permitAll()`이고, `/event/popup`은 마지막 `anyRequest().authenticated()`를 적용받는다. 수정 전 구현은 `/event/popup` exact matcher를 추가해 익명 요청도 허용했다. 국가별 언어 필터에는 인증 정책 변경이 필요하지 않으므로 요청 범위를 넘어선 보안 경계 확장이었다.
**근거**
- 기준 코드: `SecurityConfig.kt`의 `/event` matcher 다음에 `/event/popup` matcher가 없고 마지막 규칙은 `anyRequest().authenticated()`다.
- 수정 전 코드: `SecurityConfig.kt`에 `GET /event/popup` `permitAll()` 한 줄이 추가됐다.
- 수정 전 테스트: `EventControllerIntegrationTest`의 팝업 2개가 익명 200을 기대해 확장된 동작을 고정했다.
- 문서: `prd.md`가 두 API 모두 기존 로그인·비로그인 접근이라고 잘못 기술했다.
**재현 또는 검증 절차**
1. 수정 전 security filter를 켠 상태로 인증 없이 `GET /event/popup`을 호출한다.
2. 수정 전 결과는 HTTP 200이다.
3. 기준 HEAD의 matcher 순서에서는 HTTP 401이다.
4. 요구되는 결과는 기존 인증 경계를 유지하는 HTTP 401이며, 인증 사용자의 국가별 팝업 필터는 계속 동작해야 한다.
**영향**
명시 승인 없이 endpoint 접근 범위가 넓어지고, PRD가 실제 기준 동작과 불일치한다.
**권장 조치**
`SecurityConfig`의 신규 matcher 한 줄을 제거한다. 통합 테스트에는 익명 팝업 401 회귀를 추가하고, JP·국가 누락 팝업 언어 테스트는 `MemberAdapter` 인증 사용자로 실행한다. `/event`의 기존 익명 접근과 언어 조회 구현은 변경하지 않는다.
**판정 기록**
- 2026-08-20 — 기준 HEAD·현재 diff·security-on 통합 테스트를 대조해 확정했다.
- 2026-08-20 — `P2-R1`에서 exact `permitAll()`을 제거하고 익명 401·인증 사용자 KO/JA 팝업과 직접 영향 28개 테스트를 통과해 수정 완료로 판정했다.
## 7. 확정 항목의 plan·goal 전환
`REV-EVENT-LANG-001`을 `plan-task.md`의 `P2-R1` 회귀 수정 Goal로 전환했다.
## 8. 리뷰 종료 판정
| 판정 항목 | 결과 | 근거 |
|---|---|---|
| 리뷰 범위 전체 확인 | 충족 | 문서·production diff·전체 호출자·DDL·직접 영향 테스트 확인 |
| 후보 항목 판정 완료 | 충족 | 1건 확정, 나머지 substantive issue 없음 |
| 확정 항목 plan 반영 | 충족 | `P2-R1` 추가 |
| 검증 명령과 결과 기록 | 충족 | 4절 기록 |
**최종 결론:** 수정 검증 완료
**남은 항목:** 없음
## 9. 수정 후 검증 기록
### 1차 수정 검증 — 2026-08-20
- 무엇을: `REV-EVENT-LANG-001`의 익명 팝업 공개를 제거하고 기존 인증 경계를 복원했다.
- 왜: 국가별 언어 필터와 무관한 보안 접근 범위 확장을 제거하기 위해서다.
- 어떻게:
- RED: `EventControllerIntegrationTest` 5개 중 익명 팝업 401만 실제 200으로 실패했고 인증 팝업·익명 목록 4개는 통과했다.
- GREEN: `SecurityConfig`의 exact matcher 한 줄 제거 후 controller 통합 테스트 5개가 `BUILD SUCCESSFUL in 38s`로 통과했다.
- 회귀: 직접 영향 5개 클래스 28개가 failures `0`, errors `0`, skipped `0`, `BUILD SUCCESSFUL in 42s`로 통과했다.
- 정적 검증: `ktlintCheck`, `tasks --all`, `git diff --check HEAD`가 모두 성공했고 기준 HEAD 대비 `SecurityConfig` diff가 없다.
- 독립 재리뷰: 수정 후 최종 diff와 문서를 다시 검토해 Critical·Important·Minor 모두 추가 발견 없음으로 판정했다.
- 남은 항목: 운영 DB DDL 실제 반영은 기존 범위대로 미실행이며, 리뷰 확정 항목은 남아 있지 않다.
@@ -1,518 +0,0 @@
# 추천 탭 배너 접속 국가별 언어 필터 Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` or `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
| 문서 항목 | 내용 |
|---|---|
| 상태 | 구현 완료 |
| 작성일 | 2026-08-19 |
| 요구사항 기준 | `docs/20260819_추천탭_배너_접속국가별_언어필터/prd.md` |
| API 기준 | 기존 공개 API 계약 유지 |
| 현재 Phase | Phase 2: 언어 필터 limit 선행 회귀 테스트 보완 완료 |
| 현재 활성 Goal | 없음 |
## 목표
메인 홈 추천과 메인 콘텐츠 추천에서 로그인 여부와 기존 강제 국가 매핑을 반영해 일본은 일본어, 그 외 국가는 한국어 배너만 조회한다.
## Architecture
기존 `MemberContentPreferenceService.resolveCountryCode`가 비로그인 사용자까지 처리하도록 입력만 확장하고 강제 국가 매핑과 국가 정규화를 재사용한다. 두 추천 application 진입점에서 국가를 `Lang.JA` 또는 `Lang.KO`로 변환해 기존 port에 전달하며, 두 QueryDSL Repository가 `content_banner.lang`을 정렬·limit 전 조회 조건으로 적용한다.
## Tech Stack
Kotlin, Java 17, Spring Boot 2.7.14, JPA/QueryDSL, JUnit 5, Mockito, Gradle Wrapper
## Global Constraints
- `JP`는 `Lang.JA`, 그 외 국가와 국가 정보 누락은 `Lang.KO`로 고정한다.
- 로그인 회원의 기존 강제 KR/JP 매핑은 요청 헤더보다 우선한다.
- `Accept-Language`, DB 스키마, 공개 API endpoint/DTO/응답 스키마를 변경하지 않는다.
- 기존 탭·성인·활성·차단·대상 유효성·정렬·limit 조건을 유지한다.
- 신규 dependency, 언어 resolver abstraction과 메모리 후처리를 추가하지 않는다.
- 모든 구현 Task는 RED → GREEN → REFACTOR 순서로 진행한다.
---
## 현재 상태
| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
|---:|---|---:|---|---|
| 1 | 완료 | `3/3` | 없음 | 없음 |
| 2 | 완료 | `1/1` | 없음 | 없음 |
- 동시에 하나의 미완료 goal만 운용한다.
- 구현 완료 즉시 해당 Task 체크박스와 현재 상태를 갱신한다.
- 실제 검증 결과는 기존 기록을 덮어쓰지 않고 `Progress`에 누적한다.
## 범위
### 포함
- 로그인·비로그인 사용자 공통 국가 코드 판정
- 홈 추천 `tab_id IS NULL` 배너의 `KO`/`JA` 필터
- 콘텐츠 추천 `tab_id = 2` 배너의 `KO`/`JA` 필터
- application → port → persistence 언어 전달
- focused application/Repository 테스트와 직접 영향 controller/E2E 회귀
### 제외
- `Lang.EN`을 선택하는 국가 정책
- 배너 외 추천 섹션의 국가·언어 필터
- 관리자/v1 배너 조회 변경
- DB 데이터·스키마, API 계약과 dependency 변경
- 기존 배너 정책의 리팩터링
## 파일 구조
| 책임 | 파일 |
|---|---|
| 공통 국가 판정 | `src/main/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceService.kt`, `MemberContentPreferenceCountryResolver.kt` |
| 홈 application 언어 선택·전달 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacade.kt`, `v2/recommendation/application/HomeRecommendationQueryService.kt` |
| 홈 port·조회 조건 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/port/out/HomeRecommendationQueryPort.kt`, `v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt` |
| 콘텐츠 추천 application 언어 선택·전달 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/application/AudioRecommendationQueryService.kt` |
| 콘텐츠 추천 port·조회 조건 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/port/out/AudioRecommendationQueryPort.kt`, `v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepository.kt` |
## Phase 1: 접속 국가별 배너 언어 필터
**Phase 결과:** 두 추천 API가 판정 국가에 대응하는 한 언어의 배너만 기존 정책대로 반환한다.
**선행조건:** 승인된 PRD `BANNER-LANG-001~006`.
**Phase 완료 조건:** `P1-T1`~`P1-T3`과 `P1-GATE` 완료, 실제 검증 결과 누적.
### 구현 항목
#### Task 1.1 로그인·비로그인 공통 국가 판정 (`P1-T1`)
**Goal 실행 `P1-T1`:** 기존 강제 국가 매핑을 유지하면서 비로그인 사용자도 동일한 정규화와 기본값으로 국가 코드를 판정한다.
- **시작 조건:** PRD `BANNER-LANG-003`, `BANNER-LANG-004` 확정.
- **완료 증거:** nullable 회원 국가 판정 테스트가 RED 후 GREEN이고 기존 강제 KR/JP 매핑 테스트가 통과한다.
- **범위 밖:** 국가를 배너 언어로 변환하거나 배너를 조회하는 로직.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceCountryResolver.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceIntegrationTest.kt`
**Interfaces:**
- Consumes: `CountryContext.countryCode`, 기존 강제 KR/JP 회원 ID 매핑.
- Produces: `MemberContentPreferenceService.resolveCountryCode(member: Member?): String` — 정규화한 국가 코드이며 null·blank는 `KR`.
- [x] **RED:** 비로그인 `JP`, 소문자/공백 포함 JP, 헤더 누락을 검증하는 테스트를 추가한다.
```kotlin
countryContext.setCountryCode(" jp ")
assertEquals("JP", service.resolveCountryCode(null))
countryContext.setCountryCode(null)
assertEquals("KR", service.resolveCountryCode(null))
```
- [x] **RED 확인:** 아래 focused test를 실행해 현재 `Member` non-null 계약 때문에 컴파일이 실패하는지 확인한다.
```bash
./gradlew test --tests "kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceIntegrationTest"
```
**Expected:** `resolveCountryCode(null)` 호출의 타입 불일치로 실패한다.
- [x] **GREEN:** 기존 helper가 nullable 회원을 받고, non-null 회원만 기존 ID 필수 조건을 검사하도록 최소 변경한다.
```kotlin
fun resolveCountryCode(member: Member?): String {
if (member != null) requireMemberId(member)
return resolveCountryCodeWithForcedMapping(member, countryContext.countryCode)
}
fun resolveCountryCodeWithForcedMapping(member: Member?, requestCountryCode: String?): String {
val memberId = member?.id
if (memberId != null && FORCED_KR_MEMBER_IDS.contains(memberId)) {
return "KR"
}
if (memberId != null && FORCED_JP_MEMBER_IDS.contains(memberId)) {
return "JP"
}
return requestCountryCode
?.trim()
?.takeIf { it.isNotBlank() }
?.uppercase()
?: "KR"
}
```
- [x] **GREEN 확인:** 같은 focused test를 다시 실행해 비로그인과 기존 강제 매핑 테스트가 모두 통과하는지 확인한다.
- [x] **REFACTOR:** 이번 변경에서 생긴 중복만 정리하고 공개 국가 정책 메서드를 추가하지 않는다. focused test를 재실행해 결과를 `Progress`에 기록한다.
#### Task 1.2 홈 추천 배너 언어 필터 (`P1-T2`)
**Goal 실행 `P1-T2`:** 홈 추천 배너가 판정 국가에 맞는 `JA` 또는 `KO`만 DB에서 조회한다.
- **시작 조건:** `P1-T1` 완료, PRD `BANNER-LANG-001`, `BANNER-LANG-005` 확정.
- **완료 증거:** facade·query service 전달 테스트와 홈 Repository 언어 필터 테스트가 RED 후 GREEN이다.
- **범위 밖:** 콘텐츠 추천 탭 배너와 홈의 다른 추천 섹션.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacade.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/application/HomeRecommendationQueryService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/port/out/HomeRecommendationQueryPort.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacadeTest.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/recommendation/application/HomeRecommendationQueryServiceTest.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepositoryTest.kt`
**Interfaces:**
- Consumes: `MemberContentPreferenceService.resolveCountryCode(member: Member?): String`.
- Produces: `findHomeBanners(..., lang: Lang = Lang.KO)` application/port 계약과 QueryDSL `audioContentBanner.lang.eq(lang)` 조건.
- [x] **RED:** facade가 `JP`를 `Lang.JA`, 그 외를 `Lang.KO`로 전달하고 query service가 `Lang`을 port에 위임하는 테스트를 추가한다.
```kotlin
Mockito.doReturn("JP").`when`(preferenceService).resolveCountryCode(member)
facade.getHomeRecommendations(member)
assertEquals(Lang.JA, queryPort.bannerLang)
```
- [x] **RED:** 홈 Repository fixture helper에 `lang: Lang = Lang.KO`를 추가하고 같은 조건의 KO/JA 배너 중 요청 언어만 반환하는 테스트를 추가한다.
```kotlin
val koBanner = saveBanner("ko.png", AudioContentBannerType.LINK, 1, isActive = true, lang = Lang.KO)
val jaBanner = saveBanner("ja.png", AudioContentBannerType.LINK, 2, isActive = true, lang = Lang.JA)
assertEquals(listOf(koBanner.thumbnailImage), repository.findHomeBanners(20, lang = Lang.KO).map { it.thumbnailImage })
assertEquals(listOf(jaBanner.thumbnailImage), repository.findHomeBanners(20, lang = Lang.JA).map { it.thumbnailImage })
```
- [x] **RED 확인:** 아래 focused test를 실행해 `Lang` 전달 계약과 Repository 조건이 없어 발생하는 컴파일/assertion 실패를 확인한다.
```bash
./gradlew test \
--tests "kr.co.vividnext.sodalive.v2.api.home.application.HomeRecommendationFacadeTest" \
--tests "kr.co.vividnext.sodalive.v2.recommendation.application.HomeRecommendationQueryServiceTest" \
--tests "kr.co.vividnext.sodalive.v2.recommendation.adapter.out.persistence.DefaultHomeRecommendationQueryRepositoryTest"
```
- [x] **GREEN:** facade에서 국가를 언어로 변환해 전달한다. service와 port 시그니처 끝에는 기본값 `Lang.KO`인 인자를 추가하고 Repository override는 같은 `Lang` 인자를 받는다.
```kotlin
val bannerLang = if (memberContentPreferenceService.resolveCountryCode(member) == "JP") Lang.JA else Lang.KO
queryService.findHomeBanners(
limit = HOME_BANNER_LIMIT,
memberId = member?.id,
includeAdultBanners = includeAdult,
lang = bannerLang
)
```
```kotlin
.where(
audioContentBanner.isActive.isTrue,
audioContentBanner.tab.isNull,
audioContentBanner.lang.eq(lang),
includeAdultBannerCondition(includeAdultBanners),
activeBannerTargetCondition(memberId, bannerCreator, seriesOwner)
)
```
- [x] **GREEN 확인:** 같은 focused test를 다시 실행해 언어 전달·필터와 기존 홈 배너 조건이 통과하는지 확인한다.
- [x] **REFACTOR:** 국가→언어 변환을 별도 abstraction으로 만들지 않고 한 줄 정책으로 유지한다. 이번 Task가 만든 중복만 정리하고 focused test 결과를 `Progress`에 기록한다.
#### Task 1.3 콘텐츠 추천 배너 언어 필터 (`P1-T3`)
**Goal 실행 `P1-T3`:** 콘텐츠 추천 배너가 판정 국가에 맞는 `JA` 또는 `KO`만 DB에서 조회한다.
- **시작 조건:** `P1-T1` 완료, PRD `BANNER-LANG-002`, `BANNER-LANG-005` 확정.
- **완료 증거:** query service 전달 테스트와 콘텐츠 추천 Repository 언어 필터 테스트가 RED 후 GREEN이다.
- **범위 밖:** 홈 추천 배너와 오디오 추천의 배너 외 섹션.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/application/AudioRecommendationQueryService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/port/out/AudioRecommendationQueryPort.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepository.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/application/AudioRecommendationQueryServiceTest.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepositoryTest.kt`
**Interfaces:**
- Consumes: `MemberContentPreferenceService.resolveCountryCode(member: Member?): String`.
- Produces: `AudioRecommendationQueryPort.findBanners(..., lang: Lang = Lang.KO)`와 QueryDSL `audioContentBanner.lang.eq(lang)` 조건.
- [x] **RED:** 기존 `shouldUseStoredPreferenceForMemberAdultVisibility`에 JP 국가 stub과 배너 호출 검증을 추가하고, 비로그인 조립 테스트는 `Lang.KO` 전달을 검증하도록 보강한다.
```kotlin
Mockito.doReturn("JP").`when`(preferenceService).resolveCountryCode(member)
service.getRecommendations(member)
Mockito.verify(queryPort).findBanners(
AudioRecommendationQueryService.BANNER_LIMIT,
member.id,
true,
Lang.JA
)
```
- [x] **RED:** 콘텐츠 추천 Repository fixture helper에 `lang: Lang = Lang.KO`를 추가하고 동일 탭의 KO/JA 배너가 요청 언어별로 분리되는 테스트를 추가한다.
```kotlin
val koBanner = saveBanner(
"ko.png",
AudioContentBannerType.LINK,
1,
link = "https://ko.test",
tab = recommendationTab,
lang = Lang.KO
)
val jaBanner = saveBanner(
"ja.png",
AudioContentBannerType.LINK,
2,
link = "https://ja.test",
tab = recommendationTab,
lang = Lang.JA
)
assertEquals(listOf("https://cdn.test/${koBanner.thumbnailImage}"), repository.findBanners(20, null, false, Lang.KO).map { it.imageUrl })
assertEquals(listOf("https://cdn.test/${jaBanner.thumbnailImage}"), repository.findBanners(20, null, false, Lang.JA).map { it.imageUrl })
```
- [x] **RED 확인:** 아래 focused test를 실행해 `Lang` 인자와 Repository 필터가 없어 발생하는 컴파일/assertion 실패를 확인한다.
```bash
./gradlew test \
--tests "kr.co.vividnext.sodalive.v2.content.recommendation.application.AudioRecommendationQueryServiceTest" \
--tests "kr.co.vividnext.sodalive.v2.content.recommendation.adapter.out.persistence.DefaultAudioRecommendationQueryRepositoryTest"
```
- [x] **GREEN:** `getRecommendations`에서 국가를 언어로 변환해 배너 호출에만 전달한다. port에는 기본값 `Lang.KO`인 인자를 추가하고 Repository override는 같은 `Lang` 인자를 받는다.
```kotlin
val bannerLang = if (memberContentPreferenceService.resolveCountryCode(member) == "JP") Lang.JA else Lang.KO
banners = queryPort.findBanners(BANNER_LIMIT, memberId, canViewAdultContent, bannerLang)
```
```kotlin
.where(
audioContentBanner.isActive.isTrue,
audioContentBanner.tab.id.eq(2L),
audioContentBanner.lang.eq(lang),
adultBannerCondition(canViewAdultContent),
activeBannerTargetCondition(memberId, bannerCreator, seriesOwner)
)
```
- [x] **GREEN 확인:** 같은 focused test를 다시 실행해 언어 필터와 기존 탭·성인·차단 조건이 함께 통과하는지 확인한다.
- [x] **REFACTOR:** 배너 외 오디오 추천 로직을 변경하지 않는다. 이번 Task가 만든 중복만 정리하고 focused test 결과를 `Progress`에 기록한다.
### 완료 조건
- [x] `P1-T1`~`P1-T3`의 체크박스와 완료 증거가 모두 충족됐다.
- [x] `BANNER-LANG-001~006`이 구현 또는 명시적 제외로 추적된다.
- [x] 공개 API와 DB 스키마 변경이 없다.
- [x] 실제 검증 결과가 `Progress`에 기록됐다.
### 검증 방법
#### Phase 1 Gate
**Goal 실행 `P1-GATE`:** 두 추천 API의 국가별 배너 언어 필터와 기존 배너 정책의 비회귀를 최종 판정한다.
- **시작 조건:** `P1-T1`~`P1-T3` 완료.
- **완료 증거:** 아래 focused/영향 범위 test, lint, 문서 명령과 수동 검증 통과 및 `Progress` 기록.
- **범위 밖:** Gate 통과를 위한 test 삭제·skip·완화와 관련 없는 코드 수정.
```bash
./gradlew test \
--tests "kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceIntegrationTest" \
--tests "kr.co.vividnext.sodalive.v2.api.home.application.HomeRecommendationFacadeTest" \
--tests "kr.co.vividnext.sodalive.v2.recommendation.application.HomeRecommendationQueryServiceTest" \
--tests "kr.co.vividnext.sodalive.v2.recommendation.adapter.out.persistence.DefaultHomeRecommendationQueryRepositoryTest" \
--tests "kr.co.vividnext.sodalive.v2.content.recommendation.application.AudioRecommendationQueryServiceTest" \
--tests "kr.co.vividnext.sodalive.v2.content.recommendation.adapter.out.persistence.DefaultAudioRecommendationQueryRepositoryTest" \
--tests "kr.co.vividnext.sodalive.v2.api.home.HomeRecommendationControllerTest" \
--tests "kr.co.vividnext.sodalive.v2.api.content.recommendation.adapter.in.web.AudioRecommendationControllerTest" \
--tests "kr.co.vividnext.sodalive.v2.api.content.recommendation.adapter.in.web.AudioRecommendationEndToEndTest"
./gradlew ktlintCheck
./gradlew tasks --all
git diff --check
```
**Expected:** 모든 명령이 exit code `0`으로 끝난다. JP 판정은 두 API에서 JA 배너만, 그 외 판정은 KO 배너만 반환하며 기존 탭·성인·활성·차단·대상 유효성·정렬·limit와 응답 스키마가 유지된다.
수동 검증:
- [x] `git diff --name-only`에 계획된 production/test 파일과 이 작업 문서 이외의 변경이 없는지 확인한다.
- [x] `git diff`에서 endpoint, request/response DTO, DB 스키마, dependency와 `Accept-Language` 사용이 추가되지 않았는지 확인한다.
- [x] 두 Repository 모두 `lang` 조건이 `orderBy`와 `limit`보다 앞선 `where`에 있는지 확인한다.
전체 회귀 `./gradlew test`는 변경이 국가 판정과 두 배너 조회 경로에 한정되고 위 명령이 application, persistence, controller/E2E를 포함하므로 기본 생략한다. focused test로 영향 범위를 판단할 수 없는 실패가 발생하거나 공통 국가 판정 변경의 회귀 범위가 확대되면 전체 회귀를 실행하고 결과를 `Progress`에 기록한다.
## 실행 순서와 의존성
| 순서 | Goal | 선행조건 | 병행 가능 | 차단 시 다음 행동 |
|---:|---|---|---|---|
| 1 | `P1-T1` | 승인된 PRD | 아니요 | 기존 국가 정규화·강제 매핑 테스트와 구현을 다시 대조 |
| 2 | `P1-T2` | `P1-T1` | 아니요 | 홈 application/port/repository 계약을 한 단계씩 대조 |
| 3 | `P1-T3` | `P1-T1` | 아니요 | 콘텐츠 추천 application/port/repository 계약을 한 단계씩 대조 |
| 4 | `P1-GATE` | `P1-T1`~`P1-T3` | 아니요 | 실패를 소유한 Task에 회귀 수정 Goal 추가 |
```text
P1-T1 → P1-T2 → P1-T3 → P1-GATE
```
## 변경 금지 항목
- 기존 완료 문서와 검증 기록을 삭제하거나 덮어쓰지 않는다.
- 공개 endpoint, request/response DTO와 API envelope를 변경하지 않는다.
- DB schema, 배너 데이터, 관리자/v1 배너 API를 변경하지 않는다.
- `Accept-Language`나 회원 저장 언어를 국가 판정 대신 사용하지 않는다.
- 조회 후 컬렉션 filter로 언어를 제거하지 않는다.
- 신규 dependency, enum, 공통 abstraction과 관련 없는 리팩터링을 추가하지 않는다.
- test를 삭제·skip·완화하지 않는다.
## 의사결정 및 중단 규칙
- PRD와 구현이 충돌하면 `prd.md`의 Decision Log와 이 계획을 먼저 갱신한 뒤 구현한다.
- `CloudFront-Viewer-Country` 또는 기존 강제 국가 매핑 정책을 바꿔야 하면 범위 확장으로 보고 사용자 승인 전 중단한다.
- `Lang.EN`, 다른 국가별 언어 또는 배너 외 추천 섹션이 필요해지면 별도 요구사항으로 분리한다.
- 공개 API, DB schema 또는 관리자/v1 조회 변경이 필요해지면 사용자 승인 전 진행하지 않는다.
- 체크박스, test와 `Progress` 기록이 모두 충족된 뒤에만 Goal을 완료 처리한다.
## Progress
### 2026-08-19 문서 작성
- 사용자 인터뷰로 `JP → JA`, 그 외 국가 → `KO` 정책과 로그인 회원의 기존 강제 국가 매핑 적용을 확정했다.
- PRD와 구현 계획만 작성했으며 production/test 코드는 변경하지 않았다.
- placeholder 검색과 `git diff --check`에서 문제가 없음을 확인했다.
- `./gradlew tasks --all`은 최초 sandbox의 Gradle wrapper lock 접근 제한으로 실패했으며, 승인된 동일 명령 재실행에서 `BUILD SUCCESSFUL`을 확인했다.
### 2026-08-19 P1-T1 완료
- RED: `./gradlew test --tests "kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceIntegrationTest"` 실행 결과 `resolveCountryCode(null)` 4곳이 `Member` non-null 타입 불일치로 `:compileTestKotlin FAILED`가 됨을 확인했다.
- GREEN/REFACTOR: `MemberContentPreferenceService.resolveCountryCode`와 `resolveCountryCodeWithForcedMapping`만 nullable 회원을 받도록 최소 변경했다. 같은 focused test 재실행 결과 `BUILD SUCCESSFUL`을 확인했다.
### 2026-08-19 P1-T2 완료
- RED: 홈 facade/service/repository 테스트에 `Lang` 전달과 `content_banner.lang` 조건 기대를 추가한 뒤 focused test를 실행했고, `findHomeBanners`의 `lang` 파라미터 부재로 `:compileTestKotlin FAILED`가 됨을 확인했다.
- GREEN/REFACTOR: 홈 facade에서 `JP`만 `Lang.JA`, 그 외 `Lang.KO`를 한 줄로 선택해 service/port/repository에 전달하고, QueryDSL `where`에 `audioContentBanner.lang.eq(lang)`을 추가했다. 같은 focused test 재실행 결과 `BUILD SUCCESSFUL`을 확인했다.
### 2026-08-19 P1-T3 완료
- RED: 콘텐츠 추천 service/repository 테스트에 `Lang.KO` 기본 전달, `JP`의 `Lang.JA` 전달, 추천 탭 배너 언어 분리 기대를 추가한 뒤 focused test를 실행했고, `findBanners`의 `Lang` 인자 부재로 `:compileTestKotlin FAILED`가 됨을 확인했다.
- GREEN/REFACTOR: `AudioRecommendationQueryService.getRecommendations`에서 배너 호출에만 `JP → Lang.JA`, 그 외 `Lang.KO`를 전달하고, QueryDSL `where`에 `audioContentBanner.lang.eq(lang)`을 추가했다. 같은 focused test 재실행 결과 `BUILD SUCCESSFUL`을 확인했다.
### 2026-08-19 P1-GATE 완료
- Phase Gate focused/controller/E2E 명령 실행 결과 `BUILD SUCCESSFUL`을 확인했다.
- `./gradlew ktlintCheck`는 최초 실행에서 테스트 import 순서 2곳으로 실패했고, import 정렬 후 재실행 결과 `BUILD SUCCESSFUL`을 확인했다.
- `./gradlew tasks --all` 실행 결과 `BUILD SUCCESSFUL`을 확인했다.
- `git diff --check` 실행 결과 출력 없이 통과했다.
- `git diff --name-only`와 diff 검토로 계획된 production/test 파일 및 이 작업 문서 외 변경이 없고, 공개 endpoint/request/response DTO, DB 스키마, dependency, `Accept-Language` 정책이 추가되지 않았음을 확인했다.
- 두 Repository 모두 `audioContentBanner.lang.eq(lang)` 조건이 `where` 안에서 `orderBy`와 `limit`보다 먼저 적용됨을 확인했다.
- Reviewer Gate에서 요구사항 차단 이슈 없음으로 승인받았다.
## Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 Goal/문서 |
|---|---|---|---|---|---|
| 2026-08-19 | `DEC-001` | 확정 | 공통 국가 판정을 먼저 nullable 회원까지 확장한 뒤 두 배너 경로가 소비한다. | 기존 강제 매핑·정규화 재사용과 중복 방지 | `P1-T1`~`P1-T3` |
| 2026-08-19 | `DEC-002` | 확정 | 두 port의 `lang`은 기존 직접 호출 호환을 위해 기본값 `Lang.KO`를 사용한다. | 비JP 정책과 기존 KO fixture 일치 | `P1-T2`, `P1-T3` |
| 2026-08-19 | `DEC-003` | 확정 | 국가→언어 변환은 두 application 진입점의 한 줄 정책으로 두고 별도 abstraction을 만들지 않는다. | 사용처가 두 곳뿐인 고정 정책의 최소 구현 | `P1-T2`, `P1-T3` |
## 발견된 문제
### 2026-08-19 2차 리뷰
- production 호출 흐름과 QueryDSL 조건에는 요구사항 차단 문제가 없다.
- 두 Repository 언어 테스트가 `limit = 20`으로 배너 2개를 모두 수용해 `BANNER-LANG-005`의 "다른 언어 배너가 limit을 차지하지 않음" 회귀를 직접 방어하지 못하는 테스트 공백을 확인했다.
## Phase 2: 언어 필터 limit 선행 회귀 테스트 보완
**Phase 결과:** 두 Repository 테스트가 언어 조건이 제거되거나 limit 이후로 밀리는 회귀를 직접 검출한다.
**선행조건:** `P1-GATE` 완료와 2차 리뷰 테스트 공백 확정.
**Phase 완료 조건:** `P2-T1`과 `P2-GATE` 완료, mutation RED와 복구 후 GREEN 결과 누적.
### 구현 항목
#### Task 2.1 언어 필터가 limit보다 먼저 적용되는 회귀 테스트 (`P2-T1`)
**Goal 실행 `P2-T1`:** 낮은 `orders`의 반대 언어 배너가 있어도 `limit = 1` 조회는 요청 언어 배너를 반환함을 두 Repository에서 검증한다.
- **시작 조건:** PRD `BANNER-LANG-005`, 2차 리뷰 결과 확정.
- **완료 증거:** 두 테스트가 정상 구현에서 통과하고, 각 Repository의 언어 조건 제거 mutation에서 의도한 assertion 실패를 보인 뒤 복구 후 다시 통과한다.
- **범위 밖:** production query, 배너 정렬 정책, API 계약 변경.
- **TDD 예외 사유:** production 동작은 이미 올바르고 이번 보완은 기존 테스트가 특정 회귀를 검출하는지 확인하는 테스트 전용 변경이다.
- **대체 검증 방법:** 테스트를 먼저 보강한 뒤 각 Repository의 `audioContentBanner.lang.eq(lang)`을 일시 제거해 실패를 확인하고 즉시 복구한 뒤 같은 테스트의 통과를 확인한다.
**Files:**
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepositoryTest.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepositoryTest.kt`
- Mutation 후 원상 복구 확인: `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt`
- Mutation 후 원상 복구 확인: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepository.kt`
- [x] **RED:** 각 언어 테스트에서 `orders = 1`인 반대 언어와 `orders = 2`인 요청 언어를 만들고 `limit = 1` 결과가 요청 언어 한 건인지 검증한다.
- [x] **RED 확인:** 홈 Repository의 언어 조건을 일시 제거하고 홈 단일 테스트가 반대 언어를 반환해 실패하는지 확인한 뒤 원상 복구한다.
- [x] **RED 확인:** 콘텐츠 추천 Repository의 언어 조건을 일시 제거하고 콘텐츠 추천 단일 테스트가 반대 언어를 반환해 실패하는지 확인한 뒤 원상 복구한다.
- [x] **GREEN:** production 변경 없이 두 테스트의 최종 fixture와 `limit = 1` assertion만 유지한다.
- [x] **GREEN 확인:** 아래 두 focused test class가 통과하는지 확인한다.
- [x] **REFACTOR:** 테스트 이름·fixture 중복만 최소 정리하고 production diff가 Phase 1 구현과 동일한지 확인한다.
```bash
./gradlew test \
--tests "kr.co.vividnext.sodalive.v2.recommendation.adapter.out.persistence.DefaultHomeRecommendationQueryRepositoryTest" \
--tests "kr.co.vividnext.sodalive.v2.content.recommendation.adapter.out.persistence.DefaultAudioRecommendationQueryRepositoryTest"
```
### Phase 2 Gate (`P2-GATE`)
- **시작 조건:** `P2-T1` 완료.
- **완료 증거:** Phase 1 Gate focused/controller/E2E 테스트, `ktlintCheck`, `tasks --all`, `git diff --check` 통과와 재리뷰 결과 기록.
- **범위 밖:** 새 production 동작과 관련 없는 테스트 확장.
```bash
./gradlew test \
--tests "kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceIntegrationTest" \
--tests "kr.co.vividnext.sodalive.v2.api.home.application.HomeRecommendationFacadeTest" \
--tests "kr.co.vividnext.sodalive.v2.recommendation.application.HomeRecommendationQueryServiceTest" \
--tests "kr.co.vividnext.sodalive.v2.recommendation.adapter.out.persistence.DefaultHomeRecommendationQueryRepositoryTest" \
--tests "kr.co.vividnext.sodalive.v2.content.recommendation.application.AudioRecommendationQueryServiceTest" \
--tests "kr.co.vividnext.sodalive.v2.content.recommendation.adapter.out.persistence.DefaultAudioRecommendationQueryRepositoryTest" \
--tests "kr.co.vividnext.sodalive.v2.api.home.HomeRecommendationControllerTest" \
--tests "kr.co.vividnext.sodalive.v2.api.content.recommendation.adapter.in.web.AudioRecommendationControllerTest" \
--tests "kr.co.vividnext.sodalive.v2.api.content.recommendation.adapter.in.web.AudioRecommendationEndToEndTest"
./gradlew ktlintCheck
./gradlew tasks --all
git diff --check
```
**Expected:** 모든 명령이 exit code `0`으로 끝나고, 두 언어 테스트는 반대 언어가 더 낮은 `orders`여도 요청 언어 배너를 한 건 반환한다.
## Phase 2 Progress
### 2026-08-19 `P2-T1` 완료
- 테스트 보완: 두 Repository 언어 테스트를 `limit = 1`로 강화하고 이름을 limit 선행 동작이 드러나도록 변경했다.
- 홈 mutation RED: `DefaultHomeRecommendationQueryRepository`의 언어 조건을 일시 제거한 단일 테스트가 `DefaultHomeRecommendationQueryRepositoryTest.kt:276`에서 assertion 실패함을 확인하고 즉시 복구했다.
- 콘텐츠 추천 mutation RED: `DefaultAudioRecommendationQueryRepository`의 언어 조건을 일시 제거한 단일 테스트가 `DefaultAudioRecommendationQueryRepositoryTest.kt:126`에서 assertion 실패함을 확인하고 즉시 복구했다.
- GREEN: 복구 후 두 Repository focused test class를 함께 실행해 `BUILD SUCCESSFUL`을 확인했다.
### 2026-08-19 `P2-GATE` 완료
- Phase 1 Gate와 같은 focused/application/Repository/controller/E2E 테스트 9개 class를 실행해 `BUILD SUCCESSFUL`을 확인했다.
- `./gradlew ktlintCheck`와 `./gradlew tasks --all`이 각각 `BUILD SUCCESSFUL`로 끝났다.
- `git diff --check` 결과 오류가 없고, 두 production Repository에 `audioContentBanner.lang.eq(lang)`이 복구된 상태임을 확인했다.
- 최종 독립 재리뷰에서 최초 Important 이슈 해소와 Critical/Important/Minor 추가 이슈 없음 판정을 받았다.
- 전체 회귀 `./gradlew test`는 실행하지 않았다. 변경이 두 기존 Repository 테스트의 limit 경계 강화에 한정되고 Phase Gate가 직접 영향 application/persistence/controller/E2E 범위를 포함하므로 생략했다.
@@ -1,113 +0,0 @@
# 추천 탭 배너 접속 국가별 언어 필터 PRD
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | 구현 기준 확정 |
| 작성일 | 2026-08-19 |
| 최종 수정일 | 2026-08-19 |
| 대상 제품 | 메인 홈 추천 탭, 메인 콘텐츠 추천 탭 |
| 작성자·결정권자 | 사용자 |
| 관련 API Contract | 신규 없음. 기존 공개 API 계약 유지 |
| 관련 구현 계획 | `docs/20260819_추천탭_배너_접속국가별_언어필터/plan-task.md` |
| 관련 기존 문서 | `docs/20260805_추천탭_배너_조회조건/prd.md`, `docs/20260529_메인_홈_추천_API/prd.md`, `docs/20260623_메인_콘텐츠_추천_탭_API/prd.md` |
## 1. Overview
메인 홈 추천 API와 메인 콘텐츠 추천 API에서 접속 국가에 맞는 언어의 배너만 반환한다. 로그인 회원은 기존 강제 국가 매핑을 포함한 국가 판정 결과를 사용하고, 비로그인 사용자는 `CloudFront-Viewer-Country` 요청 헤더를 기준으로 판정한다.
## 2. Problem Statement
- 두 추천 API의 현재 배너 QueryDSL 조회에는 `content_banner.lang` 조건이 없다.
- 그 결과 한국어·일본어·영어 배너가 같은 응답에 섞일 수 있다.
- 언어 필터가 조회 후 적용되면 다른 언어 배너가 limit을 차지해 필요한 배너가 누락될 수 있다.
문제를 해결했다는 판단은 두 API가 배너 정렬과 limit 적용 전에 확정된 언어 조건을 적용하고, 기존 배너 조회 조건과 공개 응답 스키마를 유지하는 것으로 한다.
## 3. Goals
- 접속 국가 판정 결과가 `JP`이면 `Lang.JA` 배너만 반환한다.
- `JP` 이외의 국가와 국가 정보가 없는 경우에는 `Lang.KO` 배너만 반환한다.
- 로그인 회원은 `MemberContentPreferenceService.resolveCountryCode`의 기존 강제 국가 매핑을 유지한다.
- 비로그인 사용자도 요청 국가를 판정할 수 있도록 동일한 국가 정규화와 기본값 정책을 사용한다.
- 언어 조건을 DB 조회 단계에서 정렬·limit보다 먼저 적용한다.
## 4. Non-Goals
- `Lang.EN` 배너를 반환하는 국가 정책을 추가하지 않는다.
- `Accept-Language`를 배너 언어 판정에 사용하지 않는다.
- `CloudFront-Viewer-Country` 헤더 계약이나 `CountryInterceptor`를 변경하지 않는다.
- 공개 API endpoint, request/response DTO와 응답 스키마를 변경하지 않는다.
- 기존 배너의 탭·성인·활성·차단·대상 유효성·정렬·limit 정책을 변경하지 않는다.
- DB 스키마, 배너 데이터, 관리자 배너 API와 기존 v1 배너 조회를 변경하지 않는다.
- 배너 이외의 추천 섹션에 국가 또는 언어 필터를 추가하지 않는다.
## 5. 대상 사용자와 국가 판정
| 사용자 | 국가 판정 | 언어 선택 |
|---|---|---|
| 강제 JP 매핑 로그인 회원 | 기존 강제 매핑 결과 `JP` | `Lang.JA` |
| 강제 KR 매핑 로그인 회원 | 기존 강제 매핑 결과 `KR` | `Lang.KO` |
| 일반 로그인 회원 | 정규화한 `CloudFront-Viewer-Country`, 누락 시 `KR` | `JP`이면 `JA`, 그 외 `KO` |
| 비로그인 사용자 | 정규화한 `CloudFront-Viewer-Country`, 누락 시 `KR` | `JP`이면 `JA`, 그 외 `KO` |
국가 코드는 기존 정책처럼 앞뒤 공백을 제거하고 대문자로 정규화한다.
## 6. 핵심 조회 흐름
1. `CountryInterceptor`가 `CloudFront-Viewer-Country`를 `CountryContext`에 저장한다.
2. `HomeRecommendationFacade.getHomeRecommendations`와 `AudioRecommendationQueryService.getRecommendations`가 회원과 요청 국가로 국가 코드를 판정한다.
3. 국가 코드가 `JP`이면 `Lang.JA`, 그 외에는 `Lang.KO`를 선택한다.
4. 선택한 `Lang`을 기존 application → port → persistence 경로로 전달한다.
5. Repository가 `content_banner.lang = :lang`을 기존 조건과 함께 적용한 뒤 정렬하고 limit을 적용한다.
## 7. 기능 요구사항
| ID | 상태 | 요구사항 | 수용 기준 | Goal 연결 |
|---|---|---|---|---|
| `BANNER-LANG-001` | 확정 | `GET /api/v2/home/recommendations`는 판정 국가가 `JP`이면 `JA`, 그 외에는 `KO` 홈 배너만 반환한다. | `tab_id IS NULL`인 활성 배너 중 선택 언어와 일치하는 배너만 응답한다. | `P1-T2` |
| `BANNER-LANG-002` | 확정 | `GET /api/v2/audio/recommendations`는 판정 국가가 `JP`이면 `JA`, 그 외에는 `KO` 콘텐츠 추천 배너만 반환한다. | `tab_id = 2`인 활성 배너 중 선택 언어와 일치하는 배너만 응답한다. | `P1-T3` |
| `BANNER-LANG-003` | 확정 | 로그인 회원의 국가 판정은 기존 강제 KR/JP 매핑을 요청 헤더보다 우선한다. | 강제 JP 회원은 비JP 헤더에서도 `JP`, 강제 KR 회원은 JP 헤더에서도 `KR`로 판정된다. | `P1-T1` |
| `BANNER-LANG-004` | 확정 | 비로그인 사용자는 요청 국가를 정규화해 사용하고, 헤더가 없거나 비어 있으면 `KR`로 판정한다. | `JP`·`jp`·공백 포함 JP는 `JP`, null·blank는 `KR`로 판정된다. | `P1-T1` |
| `BANNER-LANG-005` | 확정 | 언어 필터는 정렬·limit 전에 DB 조회 조건으로 적용한다. | 다른 언어 배너가 limit을 차지하지 않고, Repository 테스트가 언어별 결과를 검증한다. | `P1-T2`, `P1-T3` |
| `BANNER-LANG-006` | 확정 | 기존 배너 조회 정책과 공개 API 계약을 유지한다. | 기존 탭·성인·활성·차단·대상 유효성·정렬·limit 테스트와 controller/E2E 회귀가 통과한다. | `P1-GATE` |
## 8. API 계약
| Method | Path | 변경 내용 |
|---|---|---|
| `GET` | `/api/v2/home/recommendations` | 응답 스키마 변경 없이 접속 국가별 배너 언어 조회 조건만 추가한다. |
| `GET` | `/api/v2/audio/recommendations` | 응답 스키마 변경 없이 접속 국가별 배너 언어 조회 조건만 추가한다. |
- 신규 request header는 추가하지 않는다.
- 기존 `CloudFront-Viewer-Country` 처리 경로를 재사용한다.
- 배너가 없으면 기존처럼 빈 목록을 반환한다.
## 9. 성능과 품질 요구사항
- `content_banner.lang` 조건은 QueryDSL `where`에 포함하고 메모리 후처리를 사용하지 않는다.
- 신규 dependency, 캐시, 공통 resolver abstraction을 추가하지 않는다.
- 기존 `Lang`, `CountryContext`, `MemberContentPreferenceService`를 재사용한다.
- application 전달 테스트와 두 Repository 조회 테스트를 TDD로 보강한다.
- 직접 영향 controller/E2E 회귀와 `ktlintCheck`를 Phase Gate에서 검증한다.
## 10. 성공 기준
- [x] 강제 매핑을 포함한 판정 국가가 `JP`이면 두 API의 배너가 모두 `JA`로 제한된다. (`BANNER-LANG-001~003`)
- [x] 일반 국가와 국가 정보가 없는 경우 두 API의 배너가 모두 `KO`로 제한된다. (`BANNER-LANG-001`, `BANNER-LANG-002`, `BANNER-LANG-004`)
- [x] 다른 언어 배너가 정렬·limit 대상에 포함되지 않는다. (`BANNER-LANG-005`)
- [x] 기존 배너 필터와 공개 응답 계약이 유지된다. (`BANNER-LANG-006`)
## 11. Open Questions
- 없음.
## 12. Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항·Goal |
|---|---|---|---|---|---|
| 2026-08-19 | `DEC-001` | 확정 | `JP`는 `JA`, 그 외 국가는 `KO` 배너만 조회한다. | 사용자 인터뷰 답변 B | `BANNER-LANG-001`, `BANNER-LANG-002`, `BANNER-LANG-005` |
| 2026-08-19 | `DEC-002` | 확정 | 로그인 회원은 기존 강제 국가 매핑을 포함한 국가 판정을 사용한다. | 사용자 인터뷰 답변 B | `BANNER-LANG-003`, `P1-T1` |
| 2026-08-19 | `DEC-003` | 확정 | 비로그인은 요청 국가를 사용하고 국가 정보가 없으면 기존 기본값 `KR`을 사용한다. | 승인된 설계 | `BANNER-LANG-004`, `P1-T1` |
| 2026-08-19 | `DEC-004` | 확정 | 언어 필터는 Repository 조회 조건으로 적용한다. | limit 이전 필터링과 기존 QueryDSL 패턴 유지 | `BANNER-LANG-005`, `P1-T2`, `P1-T3` |
@@ -1,280 +0,0 @@
# 홈 팔로잉 최근 대화 팔로우 필터 구현 계획
> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` or `superpowers:executing-plans` to implement this plan task-by-task. 체크박스는 구현 시 실제 진행 상태에 맞게 갱신한다.
**Goal:** 홈 팔로잉 탭에서 현재 팔로우 중인 크리에이터의 DM 및 AI 채팅만 최근 대화로 제공한다.
**Architecture:** 기존 `ChatRoomListService`의 병합·정렬·응답 변환을 재사용하고, 홈 팔로잉 호출만 `followedCreatorsOnly = true`를 전달한다. AI/DM 저장소 query는 활성 `CreatorFollowing` 존재 조건을 pagination 전에 적용하며, 기본값 `false`로 일반 채팅 목록 동작을 유지한다.
**Tech Stack:** Kotlin, Java 17, Spring Boot 2.7.14, Spring Data JPA/JPQL, Gradle, JUnit 5, Mockito, MockMvc
**Spec:** `docs/20260819_홈_팔로잉_최근대화_팔로우필터/prd.md`
## Global Constraints
- 공개 API request/response schema를 변경하지 않는다.
- DM과 AI 채팅을 모두 포함하고 현재 `CreatorFollowing.isActive = true`인 대상만 허용한다.
- 팔로우 조건은 DB query에서 pagination보다 먼저 적용한다.
- 일반 `GET /api/v2/chat/rooms`는 기존 전체 조회 동작을 유지한다.
- DB schema, index, dependency를 추가하지 않는다.
- 메시지 본문, 인증 정보와 식별자를 새 log에 기록하지 않는다.
- 요청 범위 밖 리팩터링을 하지 않는다.
---
| 문서 항목 | 내용 |
|---|---|
| 상태 | 구현 완료 |
| 작성일 | 2026-08-19 |
| 요구사항 기준 | `docs/20260819_홈_팔로잉_최근대화_팔로우필터/prd.md` |
| API 기준 | 기존 `GET /api/v2/home/following`, `GET /api/v2/chat/rooms` 계약 유지 |
| 현재 Phase | Phase 1 완료 |
| 현재 활성 Goal | 없음 |
## 현재 상태
| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
|---:|---|---:|---|---|
| 1 | 완료 | `1/1` | 없음 | 없음 |
- 동시에 하나의 미완료 goal만 운용한다.
- 사용자가 명시적으로 요청하지 않았으므로 goal token budget은 설정하지 않는다.
- 이 문서 작성 단계에서는 production/test 코드를 수정하거나 테스트를 실행하지 않는다.
## 범위
### 포함
- 홈 팔로잉 최근 대화에 활성 팔로우 DM/AI filter 적용
- 기존 정렬, cursor 해석, 최대 10개와 응답 변환 재사용
- 일반 채팅 목록의 전체 조회 기본값 유지
- facade, service, repository query와 홈 팔로잉 E2E 회귀 검증
### 제외
- 공개 API schema, 채팅방 생성과 메시지 전송 정책 변경
- 팔로우/언팔로우 쓰기 로직과 알림 정책 변경
- 차단·계정 활성 상태 등 추가 노출 정책
- DB migration, index와 dependency 추가
- 홈 팔로잉의 최근 대화 외 섹션 변경
## 파일 책임과 변경 범위
| 파일 | 계획된 책임 |
|---|---|
| `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/home/following/application/HomeFollowingFacade.kt` | 홈 팔로잉 최근 대화 호출에 `followedCreatorsOnly = true` 전달 |
| `src/main/kotlin/kr/co/vividnext/sodalive/v2/chat/service/ChatRoomListService.kt` | 팔로우 필터 옵션을 AI/DM repository에 전달하고 기존 병합·정렬 유지 |
| `src/main/kotlin/kr/co/vividnext/sodalive/chat/room/repository/ChatRoomRepository.kt` | AI 캐릭터 `creatorMember.id` 기준 활성 팔로우 조건 적용 |
| `src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/repository/UserCreatorChatRoomRepository.kt` | DM 상대 `member.id` 기준 활성 팔로우 조건 적용 |
| `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/following/application/HomeFollowingFacadeTest.kt` | facade가 홈 전용 팔로우 필터를 요청하는지 검증 |
| `src/test/kotlin/kr/co/vividnext/sodalive/v2/chat/ChatRoomListServiceTest.kt` | filter 옵션 전달과 기존 전체 조회 회귀 검증 |
| `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/following/adapter/in/web/HomeFollowingEndToEndTest.kt` | 활성 팔로우 DM/AI 포함과 미팔로우·비활성 팔로우 제외 검증 |
| `src/test/kotlin/kr/co/vividnext/sodalive/v2/chat/ChatRoomListControllerTest.kt` | 수정 없이 일반 채팅 목록 위임 회귀 확인 |
## Phase 1: 최근 대화 팔로우 필터 적용
**Phase 결과:** 홈 팔로잉 탭은 활성 팔로우 크리에이터의 DM/AI 최근 대화만 반환하고 일반 채팅 목록은 기존 동작을 유지한다.
**선행조건:** 승인된 PRD `HFC-001~008`.
**Phase 완료 조건:** `P1-T1`과 `P1-GATE` 완료, 실제 검증 결과를 Progress에 기록한다.
### 구현 항목
#### Task 1.1 홈 팔로잉 최근 대화 필터
**Goal 실행 `P1-T1`:** 활성 팔로우 관계를 AI/DM query에 적용하고 홈 팔로잉 facade에서만 해당 필터를 활성화한다.
- **시작 조건:** `HFC-001~008` 확정, 현재 코드와 공개 API 계약 재확인.
- **완료 증거:** 아래 체크박스 전체 완료, focused test 성공, 변경 파일과 실제 결과를 Progress에 기록.
- **범위 밖:** 채팅 목록 공개 filter enum 추가, 별도 query 복제, 메모리 후처리, 신규 abstraction·dependency·migration.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/home/following/application/HomeFollowingFacade.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/chat/service/ChatRoomListService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/chat/room/repository/ChatRoomRepository.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/repository/UserCreatorChatRoomRepository.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/following/application/HomeFollowingFacadeTest.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/chat/ChatRoomListServiceTest.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/following/adapter/in/web/HomeFollowingEndToEndTest.kt`
**Interfaces:**
- Consumes: 요청 회원 `Member.id`, DM 상대 `opponent.member.id`, AI 대상 `pc.character.creatorMember.id`, `CreatorFollowing.isActive`.
- Produces: 기존 반환형 `ChatRoomListPageResponse`; 공개 DTO와 endpoint 계약 변경 없음.
- `ChatRoomListService.getRooms`는 아래 parameter만 마지막에 추가하고 기본값으로 기존 호출을 보존한다.
```kotlin
fun getRooms(
member: Member,
filter: String = ChatRoomListFilter.ALL.name,
cursor: String? = null,
limit: Int = DEFAULT_LIMIT,
followedCreatorsOnly: Boolean = false
): ChatRoomListPageResponse
```
- `ChatRoomRepository.findAiChatListRooms`와 `UserCreatorChatRoomRepository.findDmChatListRooms`에는 `@Param("followedCreatorsOnly") followedCreatorsOnly: Boolean`을 추가한다.
- [x] **RED:** `HomeFollowingEndToEndTest.shouldAssembleFollowingTabForMember` fixture에 활성 팔로우 DM, 활성 팔로우 AI, 더 최신인 미팔로우 DM 11개, `isActive = false` 팔로우 DM을 만든다. 응답에는 활성 팔로우 AI/DM room 두 개만 기존 최신순으로 남는 assertion을 추가해 저장소 filter가 pagination보다 먼저 적용되는지도 함께 검증한다.
```kotlin
.andExpect(jsonPath("$.data.recentChats.length()").value(2))
.andExpect(jsonPath("$.data.recentChats[0].roomId").value(fixture.aiChatRoomId))
.andExpect(jsonPath("$.data.recentChats[0].chatType").value("AI"))
.andExpect(jsonPath("$.data.recentChats[1].roomId").value(fixture.dmChatRoomId))
.andExpect(jsonPath("$.data.recentChats[1].chatType").value("DM"))
.andExpect(jsonPath("$.data.recentChats[?(@.roomId == ${fixture.unfollowedDmRoomIds.first()})]").isEmpty)
.andExpect(jsonPath("$.data.recentChats[?(@.roomId == ${fixture.inactiveFollowingDmRoomId})]").isEmpty)
```
- [x] **RED 확인:** 아래 명령을 실행해 현재 구현이 더 최신인 미팔로우·비활성 팔로우 DM을 최대 10개 반환하므로 `recentChats.length()` 또는 room 순서 assertion이 실패하는지 확인한다.
```bash
./gradlew test --tests "kr.co.vividnext.sodalive.v2.api.home.following.adapter.in.web.HomeFollowingEndToEndTest.shouldAssembleFollowingTabForMember"
```
- [x] **GREEN:** AI/DM repository query parameter를 service에서 전달하고, query의 기존 방·참가자·메시지 활성 조건 뒤에 아래 활성 팔로우 존재 조건을 추가한다. 조건은 `Pageable` 적용 전에 평가한다.
AI query:
```sql
AND (
:followedCreatorsOnly = false
OR EXISTS (
SELECT 1 FROM CreatorFollowing cf
WHERE cf.member.id = :memberId
AND cf.creator.id = pc.character.creatorMember.id
AND cf.isActive = true
)
)
```
DM query:
```sql
AND (
:followedCreatorsOnly = false
OR EXISTS (
SELECT 1 FROM CreatorFollowing cf
WHERE cf.member.id = :memberId
AND cf.creator.id = opponent.member.id
AND cf.isActive = true
)
)
```
- [x] **GREEN:** `HomeFollowingFacade`만 아래처럼 filter를 활성화한다. 일반 `ChatRoomListController` 호출은 기본값 `false`를 사용한다.
```kotlin
val recentChats = chatRoomListService.getRooms(
member,
filter = "ALL",
cursor = null,
limit = 10,
followedCreatorsOnly = true
).rooms
```
- [x] **GREEN:** `ChatRoomListServiceTest`의 repository stub/verify에 `followedCreatorsOnly` 인자를 반영하고, `true`가 AI와 DM repository 양쪽에 전달되는 test를 추가한다. 기존 test는 `false` 전달과 병합·정렬·cursor·preview가 유지되는지 검증한다.
- [x] **GREEN:** `HomeFollowingFacadeTest`가 `followedCreatorsOnly = true` 호출을 stub/verify하고 비로그인 시 무호출을 계속 검증하도록 수정한다.
- [x] **GREEN 확인:** 아래 focused test를 실행해 facade, service, query와 endpoint 동작을 함께 확인한다.
```bash
./gradlew test \
--tests "kr.co.vividnext.sodalive.v2.chat.ChatRoomListServiceTest" \
--tests "kr.co.vividnext.sodalive.v2.api.home.following.application.HomeFollowingFacadeTest" \
--tests "kr.co.vividnext.sodalive.v2.api.home.following.adapter.in.web.HomeFollowingEndToEndTest"
```
**Expected:** 모든 test가 통과하고 홈 팔로잉 E2E에서 활성 팔로우 AI/DM 두 방만 기존 최신순으로 반환된다.
- [x] **REFACTOR:** 이번 Task에서 생긴 중복만 정리한다. 별도 filter enum, query method 복제와 공통 abstraction은 만들지 않는다. focused test와 아래 직접 영향 회귀·lint를 다시 실행하고 실제 결과를 Progress에 기록한다.
### 완료 조건
- [x] `P1-T1`의 체크박스와 완료 증거가 모두 충족됐다.
- [x] `HFC-001~008`이 구현 또는 명시적 제외로 추적된다.
- [x] 공개 API와 DB schema 변경이 없다.
- [x] 실제 검증 결과가 Progress에 기록됐다.
### 검증 방법
#### Phase 1 Gate
**Goal 실행 `P1-GATE`:** 홈 팔로잉 필터와 일반 채팅 목록 비회귀를 최종 판정한다.
- **시작 조건:** `P1-T1` 완료.
- **완료 증거:** 아래 test와 lint 성공, 전체 회귀 실행 여부와 근거를 Progress에 기록.
- **범위 밖:** Gate 통과를 위한 test 삭제·skip·완화와 관련 없는 코드 수정.
```bash
./gradlew test \
--tests "kr.co.vividnext.sodalive.v2.chat.ChatRoomListServiceTest" \
--tests "kr.co.vividnext.sodalive.v2.chat.ChatRoomListControllerTest" \
--tests "kr.co.vividnext.sodalive.v2.api.home.following.application.HomeFollowingFacadeTest" \
--tests "kr.co.vividnext.sodalive.v2.api.home.following.adapter.in.web.HomeFollowingEndToEndTest"
./gradlew ktlintCheck
```
**Expected:** 모든 focused/영향 범위 test와 `ktlintCheck`가 exit code `0`으로 끝난다. 홈 팔로잉은 활성 팔로우 AI/DM만 반환하고 일반 채팅 목록은 팔로우 filter 없이 기존 전체 조회를 위임한다.
수동 검증:
- [x] `git diff --name-only`에 계획된 production/test 파일과 이 작업 문서 이외의 변경이 없는지 확인한다.
- [x] `git diff`에서 endpoint, response DTO, DB schema와 dependency 변경이 없는지 확인한다.
- [x] 새 log에 회원·채팅·팔로우 식별자 또는 메시지 본문이 추가되지 않았는지 확인한다.
전체 회귀 `./gradlew test`는 작은 조회 조건 변경이며 위 test가 service, repository query, facade, endpoint와 인접 일반 채팅 목록을 포함하므로 기본 생략한다. 위 명령으로 영향 범위를 판단할 수 없는 실패가 발생하거나 공통 코드로 범위가 확장되면 전체 회귀를 실행하고 결과를 Progress에 기록한다.
## 실행 순서와 의존성
| 순서 | Goal | 선행조건 | 병행 가능 | 차단 시 다음 행동 |
|---:|---|---|---|---|
| 1 | `P1-T1` | 승인된 PRD | 아니요 | query mapping과 fixture 근거를 PRD·현재 코드와 다시 대조 |
| 2 | `P1-GATE` | `P1-T1` 완료 | 아니요 | 실패를 소유한 Task에 회귀 수정 goal 추가 |
```text
P1-T1 → P1-GATE
```
## 변경 금지 항목
- 기존 완료 문서와 검증 기록을 삭제하거나 덮어쓰지 않는다.
- 공개 endpoint, request/response DTO와 chat type filter enum을 변경하지 않는다.
- `followingCreators` 최대 20개 결과로 최근 대화를 메모리 후처리하지 않는다.
- AI/DM query 전체를 새 method로 복제하지 않는다.
- 신규 dependency, DB migration과 index를 추가하지 않는다.
- 관련 없는 리팩터링 또는 포맷 변경을 하지 않는다.
- test를 삭제·skip·완화하지 않는다.
## 의사결정 및 중단 규칙
- PRD와 구현이 충돌하면 `prd.md`의 Decision Log를 먼저 갱신하고 이 계획을 동기화한 뒤 구현한다.
- `ChatCharacter.creatorMember.id` 또는 DM `opponent.member.id`로 활성 팔로우를 판정할 수 없으면 추정 구현을 중단하고 새 근거를 확인한다.
- 구현 범위가 공개 API, DB schema 또는 팔로우 쓰기 로직으로 확장되면 사용자 승인 전 진행하지 않는다.
- 체크박스, test와 Progress 기록이 모두 충족된 뒤에만 goal을 완료 처리한다.
## Progress
### 2026-08-19 `P1-T1`, `P1-GATE` 완료
- RED: `HomeFollowingEndToEndTest.shouldAssembleFollowingTabForMember`를 실행해 `$.data.recentChats.length()`가 기대값 `2` 대신 `10`을 반환하는 실패를 확인했다.
- GREEN: `ChatRoomListServiceTest`, `HomeFollowingFacadeTest`, `HomeFollowingEndToEndTest` focused test가 exit code `0`으로 통과했다.
- Phase Gate: 위 focused test에 `ChatRoomListControllerTest`를 추가한 영향 범위 회귀와 `./gradlew ktlintCheck`가 exit code `0`으로 통과했다.
- 전체 회귀: `./gradlew test`가 exit code `0`으로 통과했다.
- 수동 검증: 변경 파일은 계획된 production/test 7개와 이 작업의 `prd.md`, `plan-task.md`뿐이며 endpoint, response DTO, DB schema, dependency와 log 변경이 없음을 `git diff`로 확인했다.
- LSP: 로컬에 `kotlin-ls`가 설치되어 있지 않아 실행하지 못했으며, Kotlin compile, 전체 test와 ktlint 성공으로 대체 검증했다.
## Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 Goal/문서 |
|---|---|---|---|---|---|
| 2026-08-19 | `DEC-001` | 확정 | DM과 AI 채팅을 모두 활성 팔로우 대상으로 filter한다. | 사용자 인터뷰 승인 | `P1-T1`, PRD `HFC-001~003` |
| 2026-08-19 | `DEC-002` | 확정 | 기존 service/query에 기본값 `false`인 최소 옵션을 추가하고 홈 facade만 활성화한다. | 일반 채팅 목록 회귀 없이 기존 병합·정렬을 재사용하는 최소 변경 | `P1-T1` |
| 2026-08-19 | `DEC-003` | 확정 | filter는 DB query에서 pagination 전에 적용한다. | 후처리 시 최신 미팔로우 대화가 limit을 차지해 팔로우 대화가 누락될 수 있음 | `P1-T1`, PRD `HFC-004` |
## 발견된 문제
현재 확정된 범위 내 발견된 문제는 없다.
@@ -1,141 +0,0 @@
# 홈 팔로잉 최근 대화 팔로우 필터 PRD
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | 구현 기준 확정 |
| 작성일 | 2026-08-19 |
| 최종 수정일 | 2026-08-19 |
| 대상 제품 | 메인 홈 팔로잉 탭 API의 최근 대화 섹션 |
| 작성자·결정권자 | Codex 작성, 사용자 승인 |
| 선행 PRD | `docs/20260625_메인_홈_팔로잉_탭_API/prd.md` |
| 관련 API Contract | 별도 문서 없음. 기존 `GET /api/v2/home/following` 계약을 유지한다. |
| 관련 구현 계획 | `docs/20260819_홈_팔로잉_최근대화_팔로우필터/plan-task.md` |
| 관련 review | 없음 |
### 선행 문서와의 관계
- 이 문서는 선행 PRD의 Feature D와 "최근 대화는 팔로잉 여부와 무관하다"는 Edge Case만 대체한다.
- 선행 PRD에서 정의한 나머지 팔로잉 탭 요구사항과 완료 기록은 변경하지 않는다.
## 1. Overview
로그인 사용자가 메인 홈 팔로잉 탭을 조회할 때 `recentChats`에는 현재 팔로우 중인 크리에이터와의 DM 및 AI 채팅만 노출한다. 기존 응답 스키마, 최신순 정렬, 최대 10개, 메시지 미리보기 정책은 유지한다.
## 2. Problem Statement
- `HomeFollowingFacade`는 현재 `ChatRoomListService.getRooms(member, filter = "ALL", cursor = null, limit = 10)`을 호출한다.
- 이 호출은 사용자의 모든 DM 및 AI 채팅방을 조회하므로, 팔로우하지 않은 크리에이터와의 대화도 팔로잉 탭에 노출된다.
- 팔로잉 탭의 최근 대화 섹션이 탭의 목적과 다른 대상을 보여준다.
문제를 해결했다는 판단은 팔로잉 탭 응답에서 활성 팔로우 대상의 DM 및 AI 채팅만 최신순 최대 10개로 반환되고, 일반 채팅 목록 API의 결과는 바뀌지 않는 것으로 한다.
## 3. Goals
- 팔로잉 탭의 `recentChats`를 현재 활성 팔로우 관계가 있는 크리에이터의 대화로 제한한다.
- DM과 AI 채팅을 모두 포함한다.
- 팔로우 필터를 저장소 조회에 적용한 뒤 최대 10개를 선택해, 더 최신인 미팔로우 대화 때문에 결과 수가 줄지 않게 한다.
- 기존 공개 API 스키마, 정렬, 미리보기, 최대 개수 정책을 유지한다.
- 일반 채팅 목록 API의 기존 전체 조회 동작을 유지한다.
## 4. Non-Goals
- `GET /api/v2/home/following` 또는 `GET /api/v2/chat/rooms`의 request/response 스키마를 변경하지 않는다.
- 채팅방 생성, 메시지 전송, 읽음 처리, cursor 형식과 메시지 미리보기 정책을 변경하지 않는다.
- 팔로우/언팔로우 처리 자체와 알림 설정 정책을 변경하지 않는다.
- 차단 관계, 크리에이터 계정 활성 상태 등 이번 요청에 포함되지 않은 추가 노출 조건을 도입하지 않는다.
- DB schema, index, dependency를 추가하지 않는다.
- 선행 홈 팔로잉 PRD의 최근 대화 이외 섹션을 변경하지 않는다.
## 5. Target Users and Permissions
| 사용자 | 기대 결과 |
|---|---|
| 로그인 회원 | 팔로우 중인 크리에이터와의 최근 DM 및 AI 채팅을 확인한다. |
| 비로그인 사용자 | 기존과 동일하게 로그인 필요 상태와 빈 `recentChats`를 받는다. |
| 앱 클라이언트 | 변경 없는 응답 스키마로 최근 대화 섹션을 표시한다. |
- 인증 회원의 `Member.id`를 팔로우 관계와 채팅 참가자 조회 기준으로 사용한다.
- 비로그인 요청에서는 기존과 동일하게 채팅 조회를 실행하지 않는다.
## 6. 핵심 사용자 흐름
1. 사용자가 `GET /api/v2/home/following`을 호출한다.
2. 서버는 로그인 회원의 홈 팔로잉 데이터와 최근 대화를 조회한다.
3. 최근 대화 조회는 현재 `CreatorFollowing.isActive = true`인 크리에이터의 채팅만 선택한다.
4. DM과 AI 결과를 기존 정렬 규칙으로 병합하고 최대 10개를 반환한다.
5. 앱은 기존 `recentChats` 응답 필드로 채팅방 진입 화면을 구성한다.
## 7. 기능 요구사항
| ID | 상태 | 요구사항 | 수용 기준 | Goal 연결 |
|---|---|---|---|---|
| `HFC-001` | 확정 | 팔로잉 탭의 최근 대화는 요청 회원이 현재 활성 팔로우 중인 크리에이터의 채팅만 포함한다. | 활성 팔로우 대상은 포함되고 팔로우 row가 없거나 `isActive = false`인 대상은 제외된다. | `P1-T1`, `P1-GATE` |
| `HFC-002` | 확정 | DM 채팅의 크리에이터 식별자는 `UserCreatorChatParticipant`의 상대 회원 `opponent.member.id`를 사용한다. | 상대 회원과 요청 회원의 활성 `CreatorFollowing`이 있을 때만 DM 방이 반환된다. | `P1-T1` |
| `HFC-003` | 확정 | AI 채팅의 크리에이터 식별자는 `ChatCharacter.creatorMember.id`를 사용한다. | AI 캐릭터의 `creatorMember`와 요청 회원의 활성 `CreatorFollowing`이 있을 때만 AI 방이 반환된다. | `P1-T1` |
| `HFC-004` | 확정 | 팔로우 필터는 저장소 조회에서 pagination보다 먼저 적용한다. | 최신 미팔로우 대화가 10개 이상이어도 그보다 오래된 팔로우 대화를 최대 10개까지 조회할 수 있다. | `P1-T1` |
| `HFC-005` | 확정 | DM과 AI 결과는 기존 `lastMessageAt`, `chatType`, `roomId` 내림차순으로 병합하고 최대 10개를 반환한다. | 기존 정렬·limit·`ChatRoomListItemResponse` 변환 테스트가 통과한다. | `P1-T1` |
| `HFC-006` | 확정 | 일반 채팅 목록은 기존처럼 팔로잉 여부와 무관하게 조회한다. | `GET /api/v2/chat/rooms`가 팔로우 필터를 요청하지 않고 기존 서비스 테스트가 통과한다. | `P1-T1`, `P1-GATE` |
| `HFC-007` | 확정 | 비로그인 홈 팔로잉 요청 동작은 유지한다. | `isLoginRequired = true`, 빈 `recentChats`, 채팅 서비스 미호출이 유지된다. | `P1-GATE` |
| `HFC-008` | 확정 | 홈 팔로잉의 크리에이터 목록 최대 20개와 관계없이 모든 활성 팔로우 관계를 최근 대화 필터에 사용한다. | `followingCreators` 응답 목록을 후처리 필터로 재사용하지 않고 DB의 활성 팔로우 관계를 직접 판정한다. | `P1-T1` |
### Edge Cases
- 활성 팔로우 관계가 없으면 `recentChats`는 빈 배열이다.
- 과거에 팔로우했더라도 현재 `CreatorFollowing.isActive = false`이면 해당 대화를 제외한다.
- 활성 팔로우 관계가 있는 AI와 DM 대화가 함께 있으면 두 유형 모두 기존 최신순 정렬에 포함한다.
- 방, 참가자 또는 메시지가 비활성인 경우 기존 채팅 목록 조회 조건대로 제외한다.
- 메시지가 없는 방은 기존 채팅 목록 정책대로 최근 대화에 포함하지 않는다.
## 8. API 계약
### Endpoint
- Method/Path: `GET /api/v2/home/following`
- request parameter: 변경 없음
- 인증 처리: 변경 없음
- response wrapper: 변경 없음
- `recentChats`: 기존 `List<ChatRoomListItemResponse>` 유지
- `roomId`, `chatType`, `targetName`, `targetImageUrl`, `lastMessage`, `lastMessageAt`: 필드와 의미 변경 없음
`GET /api/v2/chat/rooms`의 공개 계약과 전체 조회 의미도 변경하지 않는다.
## 9. 데이터·보안·성능 요구사항
- 팔로우 판정은 `creator_following.member_id`, `creator_following.creator_id`, `creator_following.is_active = true`를 사용한다.
- `creator_following`의 기존 `(member_id, creator_id)` unique constraint를 활용하고 신규 index를 추가하지 않는다.
- 팔로우 여부는 응답 생성 시점의 DB 상태를 기준으로 한다.
- 회원·채팅·팔로우 식별자와 메시지 본문을 새 log로 남기지 않는다.
- 팔로우 필터는 DB query에 포함해 미팔로우 결과를 메모리에서 제거하거나 전체 대화를 로드하지 않는다.
- 신규 dependency와 DB migration을 추가하지 않는다.
## 10. 성공 기준
- [x] 활성 팔로우 중인 일반 크리에이터와의 DM이 `recentChats`에 포함된다. (`HFC-001`, `HFC-002`)
- [x] 활성 팔로우 중인 AI 캐릭터와의 AI 채팅이 `recentChats`에 포함된다. (`HFC-001`, `HFC-003`)
- [x] 팔로우하지 않았거나 현재 비활성 팔로우인 크리에이터의 대화는 제외된다. (`HFC-001`)
- [x] 필터 적용 후 최신순 최대 10개와 기존 응답 필드가 유지된다. (`HFC-004`, `HFC-005`)
- [x] 일반 채팅 목록과 비로그인 홈 팔로잉 응답이 회귀하지 않는다. (`HFC-006`, `HFC-007`)
- [x] 공개 API schema, DB schema와 dependency 변경이 없다.
## 11. Open Questions
없음.
인터뷰 종료 시 최종 모호성은 `0.07`이며, 명확성 점수는 Goal `1.00`, Scope `1.00`, Constraints `1.00`, Success `0.75`, Context `0.90`이다.
## 12. 요구사항 추적표
| 요구사항 범위 | 계획 Phase | Goal | 자동 검증 |
|---|---:|---|---|
| `HFC-001~005`, `HFC-008` | 1 | `P1-T1` | `ChatRoomListServiceTest`, `HomeFollowingFacadeTest`, `HomeFollowingEndToEndTest` |
| `HFC-006~007` | 1 | `P1-GATE` | `ChatRoomListControllerTest`, `HomeFollowingFacadeTest`, `HomeFollowingEndToEndTest` |
## 13. Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항·Goal |
|---|---|---|---|---|---|
| 2026-08-19 | `DEC-001` | 확정 | 최근 대화는 DM과 AI 채팅을 모두 포함한다. | 사용자는 AI 채팅 가능 캐릭터도 크리에이터라고 확정했다. | `HFC-001~003`, `P1-T1` |
| 2026-08-19 | `DEC-002` | 확정 | 일반 채팅 목록은 유지하고 홈 팔로잉 조회에서만 활성 팔로우 필터를 사용한다. | 변경 범위를 홈 팔로잉 탭으로 제한하고 기존 공개 API 회귀를 방지한다. | `HFC-006`, `P1-T1` |
| 2026-08-19 | `DEC-003` | 확정 | 기존 완료 문서는 유지하고 이 PRD가 최근 대화 규칙만 대체한다. | 완료 이력을 보존하면서 새 변경의 범위와 검증을 독립적으로 추적한다. | 문서 전체 |
@@ -1,332 +0,0 @@
# v2 콘텐츠 목록 요청 언어별 번역 구현 계획
- 작성일: 2026-09-09
- 상태: Phase 1·2 구현 및 자동 검증 완료, test 서버 HTTP Gate 대기
- 요구사항·API 기준: [prd.md](prd.md)
- 현재 활성 Goal: P1-GATE test 서버 HTTP 확인 대기
- 다음 Goal: P2-GATE test 서버 HTTP 확인
- 실행 여부와 결과는 각 Task/Gate 실행 기록을 기준으로 한다.
## 목표와 범위
PRD의 7개 GET API에서 오디오 제목·시리즈 제목/시리즈명·테마명을 요청 언어로 표시하고,
번역이 없거나 공백이면 기존 원문을 반환한다. 제외 항목은 PRD §2와 동일하다.
| Phase | 결과 | 상태 | 완료 Task |
|---|---|---|---|
| 1 | 채널·메인 전체 목록 번역 통일 | 자동 검증 완료, test 서버 HTTP Gate 대기 | 2/2 |
| 2 | 추천·더보기·랭킹 번역 통일 | 자동 검증 완료, test 서버 HTTP Gate 대기 | 2/2 |
## 구현 원칙
- 조사는 v2 패키지에서 시작하고 연결된 기존 번역 저장·조회 코드를 확인한다.
- 기존 LangInterceptor/LangContext와 ko/en/ja 파싱을 재사용하며 공통 언어 파서를 변경하지 않는다.
- Kotlin/Spring 기존 계층과 스타일을 따른다. 공개 응답 스키마와 인증·필터·정렬·페이지 조건은 유지한다.
- 번역 테이블 locale 조인 또는 기존 일괄 조회를 재사용한다. 항목 수만큼 추가 조회하는 N+1은 금지한다.
- 랭킹·추천 스냅샷의 집계/저장과 요청별 번역 표시를 분리한다.
- 저장 데이터·DDL·번역 생성 파이프라인·배너 국가별 선택 정책은 변경하지 않는다.
- 파일 목록은 수정 후보 및 확인 책임 범위다. 기존 동작이 맞는 파일은 테스트로만 확인한다.
- 기존 함수의 모든 호출자를 확인하고 공용 호출에 변경이 전파되면 관련 테스트와 이 문서에 기록한다.
- 새 추상화·의존성 없이 기존 Port/Repository를 최소 확장한다.
## 공통 참조 파일
- src/main/kotlin/kr/co/vividnext/sodalive/i18n/LangInterceptor.kt
- src/main/kotlin/kr/co/vividnext/sodalive/i18n/LangContext.kt
- src/main/kotlin/kr/co/vividnext/sodalive/i18n/Lang.kt
- src/main/kotlin/kr/co/vividnext/sodalive/content/translation/ContentTranslationRepository.kt
- src/main/kotlin/kr/co/vividnext/sodalive/content/series/translation/SeriesTranslationRepository.kt
## 공통 테스트 데이터
같은 원문에 서로 다른 ko/en/ja 번역을 저장한다. 번역 행 없음·빈 문자열·공백·다른 locale만 존재·
오디오와 시리즈 중 한쪽만 번역된 경우를 포함한다.
조회 요청에는 ko/en/ja, en-US, ja-JP, 누락, 빈 값, 미지원 fr를 사용한다.
en→ja→en 연속 요청에서 언어가 섞이지 않아야 한다.
언어별 응답은 대상 문자열만 달라지고 ID·개수·순서·필터·페이지·가격·제외 필드는 같아야 한다.
### Phase 1: 채널·메인 전체 목록
시작 조건: 사용자 구현 요청. 결과: LIST-01~04의 번역 표시와 기존 동작 유지.
- [x] **Task 1.1: 채널 오디오·시리즈·홈의 번역 표시 통일**
**Goal P1-T1**
- Objective: 오디오 title·seriesName·테마명, 홈 오디오/시리즈/AUDIO 일정 제목의 번역과 필드별 fallback을 검증한다. 이미 구현된 시리즈·테마 번역은 회귀를 먼저 확인하며 불필요하게 수정하지 않는다.
- 요구사항: LIST-01, LIST-02, LIST-04, LANG-01/02, TEXT-01/02, COMPAT-01, READ-01, ISOLATE-01
- 시작 조건: 사용자의 구현 착수 요청과 PRD 확인.
- 완료 증거: 아래 TDD 체크박스, focused test 성공, 실제 결과 기록.
- 범위 밖: 메인 목록·추천·랭킹 변경.
- Consumes: 기존 원문·저장된 번역·LangContext.lang.code.
- Produces: 기존 응답 계약을 유지한 요청 locale별 표시 문자열.
**확인/수정 후보 파일**
- src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/audio/application/CreatorChannelAudioQueryService.kt
- src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/audio/port/out/CreatorChannelAudioQueryPort.kt
- src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/audio/adapter/out/persistence/DefaultCreatorChannelAudioQueryRepository.kt
- src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/home/application/CreatorChannelHomeQueryService.kt
- src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/home/port/out/CreatorChannelHomeQueryPort.kt
- src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/home/adapter/out/persistence/DefaultCreatorChannelHomeQueryRepository.kt
- src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/series/application/CreatorChannelSeriesQueryService.kt
- src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/series/adapter/out/persistence/DefaultCreatorChannelSeriesQueryRepository.kt
**테스트 파일**
- src/test/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/audio/adapter/out/persistence/DefaultCreatorChannelAudioQueryRepositoryTest.kt
- src/test/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/home/adapter/out/persistence/DefaultCreatorChannelHomeQueryRepositoryTest.kt
- src/test/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/series/adapter/out/persistence/DefaultCreatorChannelSeriesQueryRepositoryTest.kt
- src/test/kotlin/kr/co/vividnext/sodalive/v2/api/creator/channel/audio/adapter/in/web/CreatorChannelAudioEndToEndTest.kt
- src/test/kotlin/kr/co/vividnext/sodalive/v2/api/creator/channel/series/adapter/in/web/CreatorChannelSeriesEndToEndTest.kt
- src/test/kotlin/kr/co/vividnext/sodalive/v2/api/creator/channel/home/CreatorChannelHomeEndToEndTest.kt
- [x] **RED:** 위 테스트에서 대상 경로의 언어 선택·원문 fallback·기존 값 불변을 검증하는 가장 작은 실패 사례를 작성한다.
- [x] **RED 확인:** 아래 명령으로 미구현 번역 때문에 발생한 제목 assertion 실패를 확인한다. 환경 실패는 RED 증거가 아니다.
- [x] **GREEN:** 기존 계층에서 locale 전달과 번역 조회/매핑만 최소 구현한다.
- [x] **GREEN 확인:** 같은 명령으로 의도한 번역·fallback 성공을 확인한다.
- [x] **REFACTOR:** 이번 변경이 만든 중복만 정리하고 아래 focused test 및 직접 호출자 회귀를 확인한다. 실행 결과를 Task 기록에 누적한다.
```bash
./gradlew test --tests '*DefaultCreatorChannelAudioQueryRepositoryTest' --tests '*DefaultCreatorChannelHomeQueryRepositoryTest' --tests '*DefaultCreatorChannelSeriesQueryRepositoryTest' --tests '*CreatorChannelAudioEndToEndTest' --tests '*CreatorChannelSeriesEndToEndTest' --tests '*CreatorChannelHomeEndToEndTest'
```
기대 결과: 종료 코드 0. 번역이 없어서 콘텐츠가 누락되거나 순서·개수·페이지가 달라지는 사례 0건.
**Task 실행 기록:**
- 2026-09-09: 사용자가 현재 브랜치 구현을 지시해 worktree 없이 `test` 브랜치에서 진행했다.
- RED: `./gradlew test --tests '*DefaultCreatorChannelAudioQueryRepositoryTest.shouldFindAudioContentsWithTranslatedTitleFallback' --tests '*DefaultCreatorChannelHomeQueryRepositoryTest.shouldFindHomeAudioContentsWithTranslatedTitleFallback' --tests '*DefaultCreatorChannelHomeQueryRepositoryTest.shouldFindHomeSchedulesAndSeriesWithTranslatedTitleFallback'` 실행. 종료 코드 1, 3개 테스트가 제목 assertion 실패로 실패했다.
- GREEN: 같은 RED 명령 재실행. 종료 코드 0, 오디오 title·홈 오디오 title/seriesName·AUDIO 스케줄 title·홈 시리즈 title의 번역 및 공백 fallback을 확인했다.
- Focused: `./gradlew test --tests '*DefaultCreatorChannelAudioQueryRepositoryTest' --tests '*DefaultCreatorChannelHomeQueryRepositoryTest' --tests '*DefaultCreatorChannelSeriesQueryRepositoryTest' --tests '*CreatorChannelAudioEndToEndTest' --tests '*CreatorChannelSeriesEndToEndTest' --tests '*CreatorChannelHomeEndToEndTest'` 실행. 종료 코드 0.
- 리뷰 보완: 같은 콘텐츠에 en/ja 번역을 함께 저장해 locale별 제목 선택과 ID 순서 불변을 추가 검증했다. 홈 service는 `LangContext.lang.code`가 최신 오디오·오디오 목록·스케줄·시리즈 port 호출에 전달되는지 확인했다.
- 보완 후 Focused 재실행: 위 P1-T1 focused command 실행. 종료 코드 0.
- [x] **Task 1.2: 메인 전체 목록 오디오 번역과 시리즈 회귀 확인**
**Goal P1-T2**
- Objective: 각 기존 type에서 오디오 제목 번역을 확인하고 기존 시리즈 locale 전달·fallback을 보존한다. 기존 요일·정렬·유료/무료 필터와 페이지 결과가 동일해야 한다.
- 요구사항: LIST-03, LANG-01/02, TEXT-01/02, COMPAT-01, READ-01, ISOLATE-01
- 시작 조건: P1-T1 완료.
- 완료 증거: 아래 TDD 체크박스, focused test 성공, 실제 결과 기록.
- 범위 밖: 추천·랭킹 변경.
- Consumes: 기존 원문·저장된 번역·LangContext.lang.code.
- Produces: 기존 응답 계약을 유지한 요청 locale별 표시 문자열.
**확인/수정 후보 파일**
- src/main/kotlin/kr/co/vividnext/sodalive/v2/content/all/application/MainContentAllQueryService.kt
- src/main/kotlin/kr/co/vividnext/sodalive/v2/content/all/port/out/MainContentAllQueryPort.kt
- src/main/kotlin/kr/co/vividnext/sodalive/v2/content/all/adapter/out/persistence/DefaultMainContentAllQueryRepository.kt
**테스트 파일**
- src/test/kotlin/kr/co/vividnext/sodalive/v2/content/all/adapter/out/persistence/DefaultMainContentAllQueryRepositoryTest.kt
- src/test/kotlin/kr/co/vividnext/sodalive/v2/content/all/application/MainContentAllQueryServiceTest.kt
- src/test/kotlin/kr/co/vividnext/sodalive/v2/api/content/all/adapter/in/web/MainContentAllEndToEndTest.kt
- [x] **RED:** 위 테스트에서 대상 경로의 언어 선택·원문 fallback·기존 값 불변을 검증하는 가장 작은 실패 사례를 작성한다.
- [x] **RED 확인:** 아래 명령으로 미구현 번역 때문에 발생한 제목 assertion 실패를 확인한다. 환경 실패는 RED 증거가 아니다.
- [x] **GREEN:** 기존 계층에서 locale 전달과 번역 조회/매핑만 최소 구현한다.
- [x] **GREEN 확인:** 같은 명령으로 의도한 번역·fallback 성공을 확인한다.
- [x] **REFACTOR:** 이번 변경이 만든 중복만 정리하고 아래 focused test 및 직접 호출자 회귀를 확인한다. 실행 결과를 Task 기록에 누적한다.
```bash
./gradlew test --tests '*DefaultMainContentAllQueryRepositoryTest' --tests '*MainContentAllQueryServiceTest' --tests '*MainContentAllEndToEndTest'
```
기대 결과: 종료 코드 0. 번역이 없어서 콘텐츠가 누락되거나 순서·개수·페이지가 달라지는 사례 0건.
**Task 실행 기록:**
- RED: `./gradlew test --tests '*MainContentAllQueryServiceTest.shouldQueryAudiosForAudioType' --tests '*DefaultMainContentAllQueryRepositoryTest.shouldFindAudiosWithTranslatedTitleFallback'` 실행. 종료 코드 1, service locale 전달 assertion과 repository 오디오 title assertion이 실패했다.
- GREEN/Focused: `./gradlew test --tests '*DefaultMainContentAllQueryRepositoryTest' --tests '*MainContentAllQueryServiceTest' --tests '*MainContentAllEndToEndTest'` 실행. 종료 코드 0, 오디오 title 번역·공백 fallback과 기존 시리즈 번역 회귀를 확인했다.
- 리뷰 보완: 같은 오디오에 en/ja 번역을 함께 저장해 locale별 title 선택과 ID 순서 불변을 추가 검증했다.
- 보완 후 Focused 재실행: 위 P1-T2 focused command 실행. 종료 코드 0.
#### Phase 1 Gate — P1-GATE
- Objective: Phase 1의 요청 헤더부터 DB 번역 선택·HTTP 응답까지 확인한다.
- 시작 조건: P1-T1, P1-T2 완료.
- 완료 증거: 해당 Task 명령 통과, 아래 수동 확인과 실제 명령·결과·환경 기록.
- 범위 밖: 운영 데이터 변경, Papago 실행, 테스트 삭제·완화.
- [x] 해당 Phase의 모든 focused test 명령을 실행하여 종료 코드 0을 확인한다.
- [ ] test 서버에서 같은 API·query를 유지하고 Accept-Language만 바꿔 GET 요청한다.
- [ ] ko/en/ja 번역·없는 번역·공백 번역·기본 언어 동작을 실제 JSON에서 확인한다.
- [ ] 대상 외 필드, 순서·개수·페이지·인증·성인/차단/구매 정책이 보존되는지 확인한다.
- [ ] 요청별 번역 조회가 항목 수에 비례해 늘지 않고 GET에서 번역 작업/외부 API/쓰기 호출이 없는지 확인한다.
- [ ] 검증 로그는 인증 토큰·개인정보를 제거해 기록한다.
수동 HTTP는 test 서버와 합성 테스트 계정을 사용한다. 인증이 필요한 API는 test 서버용 토큰을 사용하고 문서에 값을 기록하지 않는다.
test 서버 배포·DB 준비가 안 되면 수동 Gate를 완료 처리하지 않고 원인과 재개 조건을 남긴다.
**Phase 1 Gate 실행 기록:**
- 2026-09-09: P1-T1 focused command 재실행. 종료 코드 0.
- 2026-09-09: P1-T2 focused command 실행. 종료 코드 0.
- 2026-09-09: `./gradlew ktlintCheck`는 신규 테스트 호출 줄바꿈과 import 정렬 지적 후 수정해 재실행했다. 최종 종료 코드 0.
- 2026-09-09: `./gradlew assemble` 실행. 종료 코드 0.
- 2026-09-09: Oracle 리뷰에서 자동 검증 공백을 지적받아 다중 locale 선택, 홈 locale 전달, 공백 fallback 보강 테스트를 추가했다. 보강 focused test 종료 코드 0.
- 2026-09-09: 보강 후 P1-T1 focused command, P1-T2 focused command, `./gradlew ktlintCheck`, `./gradlew assemble`을 다시 실행했다. 각 종료 코드 0.
- 로컬 수동 테스트가 불가능하다는 사용자 확인에 따라 HTTP Gate를 test 서버로 이관했다. 재개 조건: test 서버 배포와 합성 인증 수단 준비 후 동일 query에서 `Accept-Language`만 바꿔 LIST-01~04 JSON을 확인한다.
### Phase 2: 추천·더보기·랭킹
시작 조건: P1-GATE 통과. 결과: LIST-05~07의 번역 표시와 요청 간 격리.
- [x] **Task 2.1: 추천·더보기의 모든 오디오 제목 번역**
**Goal P2-T1**
- Objective: 일반 카드와 별도 SQL을 쓰는 mostCommentedAudios를 모두 검증한다. 더보기 두 type과 FIRST_AUDIO_CONTENT 공유 호출자를 확인한다. 추천 스냅샷·백그라운드 작업에 요청 범위 의존을 추가하지 않으며, 공유 홈 추천 호출의 기존 응답을 회귀 검증한다.
- 요구사항: LIST-05, LIST-07, LANG-01/02, TEXT-01/02, COMPAT-01, READ-01, ISOLATE-01
- 시작 조건: P1-GATE 완료.
- 완료 증거: 아래 TDD 체크박스, focused test 성공, 실제 결과 기록.
- 범위 밖: 배너·댓글·닉네임 및 다른 API의 신규 번역 기능.
- Consumes: 기존 원문·저장된 번역·LangContext.lang.code.
- Produces: 기존 응답 계약을 유지한 요청 locale별 표시 문자열.
**확인/수정 후보 파일**
- src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/application/AudioRecommendationQueryService.kt
- src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/port/out/AudioRecommendationQueryPort.kt
- src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepository.kt
- src/main/kotlin/kr/co/vividnext/sodalive/v2/api/content/overview/application/ContentOverviewFacade.kt
- src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/application/HomeRecommendationQueryService.kt
- src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/port/out/HomeRecommendationQueryPort.kt
- src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt
**테스트 파일**
- src/test/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepositoryTest.kt
- src/test/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepositoryTest.kt
- src/test/kotlin/kr/co/vividnext/sodalive/v2/api/content/overview/application/ContentOverviewFacadeTest.kt
- src/test/kotlin/kr/co/vividnext/sodalive/v2/api/content/recommendation/adapter/in/web/AudioRecommendationEndToEndTest.kt
- src/test/kotlin/kr/co/vividnext/sodalive/v2/api/content/overview/adapter/in/web/ContentOverviewEndToEndTest.kt
- src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacadeTest.kt
- [x] **RED:** 위 테스트에서 대상 경로의 언어 선택·원문 fallback·기존 값 불변을 검증하는 가장 작은 실패 사례를 작성한다.
- [x] **RED 확인:** 아래 명령으로 미구현 번역 때문에 발생한 제목 assertion 실패를 확인한다. 환경 실패는 RED 증거가 아니다.
- [x] **GREEN:** 기존 계층에서 locale 전달과 번역 조회/매핑만 최소 구현한다.
- [x] **GREEN 확인:** 같은 명령으로 의도한 번역·fallback 성공을 확인한다.
- [x] **REFACTOR:** 이번 변경이 만든 중복만 정리하고 아래 focused test 및 직접 호출자 회귀를 확인한다. 실행 결과를 Task 기록에 누적한다.
```bash
./gradlew test --tests '*DefaultAudioRecommendationQueryRepositoryTest' --tests '*DefaultHomeRecommendationQueryRepositoryTest' --tests '*ContentOverviewFacadeTest' --tests '*AudioRecommendationEndToEndTest' --tests '*ContentOverviewEndToEndTest' --tests '*HomeRecommendationFacadeTest'
```
기대 결과: 종료 코드 0. 번역이 없어서 콘텐츠가 누락되거나 순서·개수·페이지가 달라지는 사례 0건.
**Task 실행 기록:**
- 2026-09-09: RED는 이전 구현 담당자가 아래 focused command로 포착했다. 원시 Gradle 콘솔 로그는 현재 세션에 보관되어 있지 않아 출력은 재구성하지 않는다. LIST-05 전체 카드와 LIST-07 NEW_AND_HOT_AUDIO/FIRST_AUDIO_CONTENT가 요청 locale 번역 대신 원문 제목을 반환한 assertion 실패였다.
- 2026-09-09: GREEN 구현 후 저장소에서 locale별 배치 조회와 nonblank title fallback을 적용했다. Oracle 보완으로 같은 fixture의 en→ja→en MockMvc 격리와 빈 문자열·공백·누락·다른 locale fallback, most-commented의 ID 순서·댓글·작성자 프로필 필드 보존을 추가 검증했다.
- 2026-09-09: Focused: 위 command 실행, `BUILD SUCCESSFUL in 1m 43s`. production 코드는 Oracle 보완에서 변경하지 않았고, `pointAudios`의 기존 개수·인덱스 검증을 누적 fixture와 `rand()` 정렬에 독립적인 fixture ID·가격 조건으로 교체했다.
- 수동 HTTP는 로컬 실행이 불가능하다는 사용자 확인에 따라 test 서버 P2-GATE에서 대기한다.
- [x] **Task 2.2: 랭킹 응답 제목을 요청 언어로 표시**
**Goal P2-T2**
- Objective: 같은 랭킹 스냅샷의 contentId로 요청 locale 번역을 일괄 조회하여 표시 제목에만 반영한다. 번역 없음·공백이면 기존 snapshot.title을 사용한다. 집계 재실행 없이 번역 반영과 rank·rankChange·점수 불변을 검증한다.
- 요구사항: LIST-06, RANK-01, LANG-01/02, TEXT-01/02, COMPAT-01, READ-01, ISOLATE-01
- 시작 조건: P2-T1 완료.
- 완료 증거: 아래 TDD 체크박스, focused test 성공, 실제 결과 기록.
- 범위 밖: 집계·점수·스냅샷 저장 형식 변경.
- Consumes: 기존 원문·저장된 번역·LangContext.lang.code.
- Produces: 기존 응답 계약을 유지한 요청 locale별 표시 문자열.
**확인/수정 후보 파일**
- src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingQueryService.kt
- src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/port/out/AudioRankingSnapshotPort.kt
- src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/DefaultAudioRankingSnapshotPersistenceAdapter.kt
**테스트 파일**
- src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingQueryServiceTest.kt
- src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/DefaultAudioRankingSnapshotPersistenceAdapterTest.kt
- src/test/kotlin/kr/co/vividnext/sodalive/v2/api/content/ranking/adapter/in/web/AudioRankingControllerTest.kt
- [x] **RED:** 위 테스트에서 대상 경로의 언어 선택·원문 fallback·기존 값 불변을 검증하는 가장 작은 실패 사례를 작성한다.
- [x] **RED 확인:** 아래 명령으로 미구현 번역 때문에 발생한 제목 assertion 실패를 확인한다. 환경 실패는 RED 증거가 아니다.
- [x] **GREEN:** 기존 계층에서 locale 전달과 번역 조회/매핑만 최소 구현한다.
- [x] **GREEN 확인:** 같은 명령으로 의도한 번역·fallback 성공을 확인한다.
- [x] **REFACTOR:** 이번 변경이 만든 중복만 정리하고 아래 focused test 및 직접 호출자 회귀를 확인한다. 실행 결과를 Task 기록에 누적한다.
```bash
./gradlew test --tests '*AudioRankingQueryServiceTest' --tests '*DefaultAudioRankingSnapshotPersistenceAdapterTest' --tests '*AudioRankingControllerTest'
```
기대 결과: 종료 코드 0. 번역이 없어서 콘텐츠가 누락되거나 순서·개수·페이지가 달라지는 사례 0건.
**Task 실행 기록:**
- 2026-09-09: RED: `./gradlew test --tests '*AudioRankingQueryServiceTest' --tests '*DefaultAudioRankingSnapshotPersistenceAdapterTest' --tests '*AudioRankingControllerTest'` 종료 코드 1. `AudioRankingQueryServiceTest.shouldUseRequestedLocaleTitlesWithoutChangingRankingValues`의 `expected: <[en-title-2, en-title-1]> but was: <[audio-2, audio-1]>` 및 `AudioRankingControllerTest.shouldIsolateRequestedLocaleTitlesWithoutChangingRankingResponse`의 `JSON path "$.data.items[0].title" expected:<en-title-2> but was:<audio-2>`를 확인했다. `DefaultAudioRankingSnapshotPersistenceAdapterTest.shouldTranslateSnapshotTitlesInBatchesWithSnapshotFallback`도 snapshot title 반환 assertion으로 실패했다.
- 2026-09-09: GREEN: `LangContext.lang.code`을 조회 port에만 전달하고, 최신·이전 각 스냅샷 결과 집합에서 `findByContentIdInAndLocale` 한 번으로 유효한 title만 적용했다. 빈 문자열·공백·누락·다른 locale 전용 번역은 각 snapshot.title로 fallback하며, replace/집계/refresh 경로는 변경하지 않았다.
- 2026-09-09: Focused: 위 명령 종료 코드 0, `BUILD SUCCESSFUL in 40s`. query service의 en→ja→en locale 전달과 title 외 `showRankChange`·type·순서·rank·rankChange·isNew·닉네임·cover URL 불변, 실제 adapter의 최신·이전 조회 배치 8회 statement, controller의 en→ja→en JSON을 검증했다.
- 2026-09-09: 직접 호출자 회귀: `./gradlew test --tests '*AudioRankingSnapshotRefreshServiceTest'` 종료 코드 0, `BUILD SUCCESSFUL in 6s`.
- 수동 HTTP는 test 서버 배포 후 P2-GATE에서 수행한다.
- 2026-09-09: P2-T2 spec-review 보강: `./gradlew test --tests '*DefaultAudioRankingSnapshotPersistenceAdapterTest'` 종료 코드 0, `BUILD SUCCESSFUL in 34s`. `rendered_payload`를 SQL NULL로 저장한 실제 translation row는 converter의 빈 payload로 읽혀 snapshot.title으로 fallback했다. `{ "title": null }` JSON은 non-null `ContentTranslationPayload.title` 계약 밖이라 생성하지 않았다.
- 2026-09-09: 빈 latest 조회 후 Hibernate `prepareStatementCount=1`, 이어진 빈 previous 조회 후 누적 `=2`를 확인했다. 각 snapshot native SELECT만 발생했고 ContentTranslation SELECT는 0회다. non-empty latest·previous en→ja→en 여섯 조회는 snapshot+batch translation 각 1회씩 총 12 statements였으며, title만 빈 문자열로 정규화한 전체 `AudioRankingSnapshotRecord`가 locale 간 동일했다. latest score base 10~14와 previous 20~24의 final/normalized/raw·count·growth·boost 필드를 포함했고, 재조회한 저장 snapshot title과 모든 score 값도 변경되지 않았다.
#### Phase 2 Gate — P2-GATE
- Objective: Phase 2의 요청 헤더부터 DB 번역 선택·HTTP 응답까지 확인한다.
- 시작 조건: P2-T1, P2-T2 완료.
- 완료 증거: 해당 Task 명령 통과, 아래 수동 확인과 실제 명령·결과·환경 기록.
- 범위 밖: 운영 데이터 변경, Papago 실행, 테스트 삭제·완화.
- [x] 해당 Phase의 모든 focused test 명령을 실행하여 종료 코드 0을 확인한다.
- [ ] test 서버에서 같은 API·query를 유지하고 Accept-Language만 바꿔 GET 요청한다.
- [ ] ko/en/ja 번역·없는 번역·공백 번역·기본 언어 동작을 실제 JSON에서 확인한다.
- [ ] 대상 외 필드, 순서·개수·페이지·인증·성인/차단/구매 정책이 보존되는지 확인한다.
- [ ] 요청별 번역 조회가 항목 수에 비례해 늘지 않고 GET에서 번역 작업/외부 API/쓰기 호출이 없는지 확인한다.
- [ ] 검증 로그는 인증 토큰·개인정보를 제거해 기록한다.
수동 HTTP는 test 서버와 합성 테스트 계정을 사용한다. 인증이 필요한 API는 test 서버용 토큰을 사용하고 문서에 값을 기록하지 않는다.
test 서버 배포·DB 준비가 안 되면 수동 Gate를 완료 처리하지 않고 원인과 재개 조건을 남긴다.
**Phase 2 Gate 실행 기록:**
- 2026-09-09: P2-T1 focused command를 `--rerun-tasks`로 강제 재실행했다. 종료 코드 0, `BUILD SUCCESSFUL in 5m 12s`, 10 tasks executed.
- 2026-09-09: P2-T2 focused command를 `--rerun-tasks`로 강제 재실행했다. 종료 코드 0, `BUILD SUCCESSFUL in 5m 14s`, 10 tasks executed.
- 2026-09-09: `AudioRankingSnapshotRefreshServiceTest` 직접 호출자 회귀를 실행했다. 종료 코드 0, `BUILD SUCCESSFUL in 6s`.
- 로컬 수동 테스트는 불가능하다는 사용자 확인에 따라 LIST-01~07 HTTP 검증을 test 서버 배포 후 수행한다.
## 실행 순서와 완료 기준
P1-T1 → P1-T2 → P1-GATE → P2-T1 → P2-T2 → P2-GATE. 2026-09-09 사용자 지시로 로컬 P1-GATE를 test 서버로 이관하고 P2 자동 구현·검증을 먼저 완료했다.
한 번에 하나의 Task 또는 Gate만 활성화하며, 완료된 기록은 되돌리거나 삭제하지 않는다.
최종 품질 명령:
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.*' --tests 'kr.co.vividnext.sodalive.v2.content.*' --tests 'kr.co.vividnext.sodalive.v2.api.content.*' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.*' --tests '*HomeRecommendation*'
./gradlew ktlintCheck
./gradlew assemble
```
기대 결과: 각 자동 검증 명령 종료 코드 0. 대상 7개 API의 실제 HTTP 확인은 test 서버 Gate에서 별도 완료한다.
전체 test는 공통 인증·언어 파서·serialization 변경 또는 targeted 결과로 영향 판단이 불가능할 때 추가한다.
생략 시 국소적인 표시값 변경이라는 근거와 대신 실행한 위 영향 범위 회귀를 기록한다.
초기 문서 작성 단계에서는 위 구현 검증 명령을 실행하지 않았으며, 구현 후 결과는 각 Task/Gate 기록에 누적한다.
## 결정 기록
PRD의 DEC-LIST-01~07을 따른다.
기존 파싱·API 계약·원문 fallback을 유지하며, 요청 외 영역으로 확대해야 할 경우 먼저 문서와 사용자 결정을 갱신한다.
## 문서 검증 기록
- 2026-09-09: 사용자 인터뷰의 원문 fallback과 댓글·닉네임·배너 유지 결정을 PRD와 Task에 반영.
- 초기 문서 작성 당시 코드·테스트·운영 데이터 변경 없이 구현 Task와 Gate는 전부 미착수였다.
- 경로 존재 확인 및 필수 Gradle 명령 확인 결과는 아래에 누적한다.
- 2026-09-09: Task의 기존 소스·테스트 경로 존재를 확인했다. 채널 홈 EndToEndTest는 현재 없으므로 신규 작성 예정으로 구분했다. 구현 완료 체크박스와 템플릿 placeholder가 남아 있지 않음을 확인했다.
- 2026-09-09: 문서 유지보수 규칙에 따라 `./gradlew tasks --all` 실행. 종료 코드 0, `BUILD SUCCESSFUL in 26s`; test·ktlintCheck·assemble 태스크를 확인했다. 기능 테스트·빌드·HTTP 검증은 구현하지 않은 문서 작업이므로 실행하지 않았다.
- 2026-09-09: Phase 1·2 전체 영향 범위 test 명령 실행. 종료 코드 0, `BUILD SUCCESSFUL in 3m 23s`.
- 2026-09-09: 최초 `./gradlew ktlintCheck`에서 신규 랭킹·추천 테스트의 들여쓰기와 긴 줄 위반을 확인해 포맷만 수정했다. 관련 두 repository test 종료 코드 0, 최종 `./gradlew ktlintCheck` 종료 코드 0.
- 2026-09-09: `./gradlew assemble` 실행. 종료 코드 0, `BUILD SUCCESSFUL in 6s`.
- 2026-09-09: 전체 `./gradlew test` 실행. 종료 코드 0, `BUILD SUCCESSFUL in 8m 19s`.
- 2026-09-09: 문서 상태를 Phase 1·2 자동 검증 완료와 test 서버 HTTP Gate 대기로 갱신하고 `./gradlew tasks --all`로 명령 유효성을 재확인했다. 종료 코드 0.
- 2026-09-09: 전체 영향 범위 회귀 명령을 실행했다. 종료 코드 0, `BUILD SUCCESSFUL in 3m 23s`.
- 2026-09-09: `./gradlew ktlintCheck` 최초 실행에서 신규 테스트 두 파일의 들여쓰기·긴 줄 위반을 확인해 포맷만 수정했다. 관련 ranking adapter·recommendation repository 테스트 재실행 종료 코드 0, 최종 `ktlintCheck` 종료 코드 0.
- 2026-09-09: `./gradlew assemble` 실행. 종료 코드 0, `BUILD SUCCESSFUL in 6s`.
- 2026-09-09: 문서 상태와 test 서버 Gate 갱신 후 `./gradlew tasks --all` 재실행. 종료 코드 0, `BUILD SUCCESSFUL in 928ms`.
- 로컬 수동 테스트는 불가능하므로 자동 검증 완료 상태로 test 서버 배포를 준비한다. 배포 후 P1-GATE부터 LIST-01~07의 실제 HTTP 응답을 순서대로 확인한다.
@@ -1,99 +0,0 @@
# v2 콘텐츠 목록 요청 언어별 번역 PRD
## 문서 정보
- 작성일: 2026-09-09
- 상태: Phase 1·2 구현 및 자동 검증 완료, test 서버 HTTP Gate 대기
- 결정권자: 사용자
- 관련 계획: [plan-task.md](plan-task.md)
- 공개 API 경로·요청·응답 스키마는 유지하며 별도 API 계약 문서는 만들지 않는다.
- 사용자의 2026-09-09 구현 지시 이후 Phase 1·2 코드·테스트 구현을 진행했다. 운영 데이터 변경과 번역 실행은 수행하지 않는다.
## 1. 문제와 목표
동일한 콘텐츠라도 v2 조회 위치에 따라 번역 제목과 원문이 혼재한다.
요청의 Accept-Language로 결정된 언어에 맞춰 이미 저장된 번역을 표시하고,
번역이 없거나 공백이면 해당 필드의 기존 원문을 표시한다.
서버의 언어 결정은 기존 LangInterceptor → 요청 범위 LangContext를 재사용한다.
앱의 설정 언어가 실제 헤더로 전송되는지는 이 서버 작업에서 보장하지 않는다.
## 2. 대상 API와 필드
아래 경로는 모두 GET이다. 기존 응답에 존재하는 필드만 변경하며 설명·태그 같은 새 필드를 추가하지 않는다.
| ID | API | 대상 |
|---|---|---|
| LIST-01 | /api/v2/creator-channels/{creatorId}/audio | 오디오 title, 연결된 seriesName, 테마명 |
| LIST-02 | /api/v2/creator-channels/{creatorId}/series | 시리즈 title. 기존 연재 요일 언어 처리 유지 |
| LIST-03 | /api/v2/audio/contents | 오디오 title, 시리즈 title. 기존 type·정렬·요일 필터 유지 |
| LIST-04 | /api/v2/creator-channels/{creatorId}/home | 오디오 카드 title·seriesName, 시리즈 title, 일정 중 AUDIO 유형의 title |
| LIST-05 | /api/v2/audio/recommendations | latestAudios, newAndHotAudios, freeAudios, pointAudios, mostCommentedAudios, recommendedAudios의 title |
| LIST-06 | /api/v2/audio/rankings | 각 랭킹 항목 title |
| LIST-07 | /api/v2/contents | NEW_AND_HOT_AUDIO, FIRST_AUDIO_CONTENT의 title |
- LIST-05의 originalSeries는 현재 seriesId·coverImageUrl만 반환한다. 번역용 title 필드를 추가하지 않는다.
- LIST-04의 라이브 제목, 후원·팬톡 문구 등 오디오·시리즈·테마 외 필드는 대상이 아니다.
- /api/v2/home/recommendations 등 다른 경로는 신규 기능 범위가 아니다. 공유 조회 코드 변경 시 기존 동작 회귀를 검증한다.
- 관리자 목록, 상세·검색 API, 음성 파일 번역, 설명·태그 응답 확장은 제외한다.
## 3. 기능 요구사항과 수용 기준
| ID | 상태/근거 | 요구사항 | 수용 기준 | 연결 |
|---|---|---|---|---|
| LANG-01 | 사용자 확정 | 대상 API 전체에서 Accept-Language 기준 번역 선택 | 동일 데이터에 ko/en/ja 요청 시 해당 locale 번역 표시 | 모든 Task |
| LANG-02 | 기존 동작 유지 | Lang.fromAcceptLanguage 파싱 재사용 | 헤더 누락·빈 값·미지원 값은 ko, en-US는 en, ja-JP는 ja. q 가중치 파싱 확장 없음 | P1-GATE |
| TEXT-01 | 사용자 확정 | 번역 없음·빈 문자열·공백 문자열은 원문 표시 | null/빈 문자열/공백별 원문 일치, 다른 언어 번역으로 대체하지 않음 | 모든 Task |
| TEXT-02 | 사용자 확정 | 오디오 제목·시리즈 제목/시리즈명·테마명만 적용 | 댓글·닉네임·배너는 기존 값·선택 정책 유지 | 모든 Task |
| COMPAT-01 | 기존 기능 유지 | 언어는 표시 문자열에만 영향 | ID·개수·순서·hasNext·권한·성인/차단/구매 필터·가격·이미지 불변 | 각 Gate |
| RANK-01 | 구현 제약 | 랭킹 집계와 번역 표시를 분리 | 같은 스냅샷으로 언어만 바꿔 제목 변경, 순위·점수·rankChange 불변 | P2-T2 |
| READ-01 | 범위 제약 | 저장된 번역만 조회 | GET에서 Papago 호출·번역 작업 생성·DB 쓰기 없음 | 각 Gate |
| ISOLATE-01 | 기존 요청 범위 유지 | 언어가 다른 요청끼리 값 공유 금지 | en→ja→en 요청에서도 언어 혼입 없음 | 각 Gate |
원문이란 번역 적용 전 해당 경로에서 반환하던 문자열이다.
랭킹은 기존 스냅샷 title을 fallback으로 유지하며 최신 콘텐츠 제목으로 갱신하는 별도 기능을 추가하지 않는다.
번역 완료 전 원문이 보이는 것은 정상이다. 원문과 요청 언어가 같아도 별도 추정 없이 같은 locale 번역 조회/fallback 규칙을 적용한다.
## 4. 기술 근거와 최소 변경 방향
모든 경로는 src/main/kotlin/kr/co/vividnext/sodalive/ 아래를 기준으로 한다.
| 근거 파일 | 현재 확인한 동작 |
|---|---|
| i18n/LangInterceptor.kt, i18n/Lang.kt, configs/WebConfig.kt | 전체 경로에서 헤더를 읽고 ko/en/ja로 결정 |
| content/translation/ContentTranslationRepository.kt | findByContentIdInAndLocale 일괄 조회가 이미 존재 |
| i18n/translation/TranslationReadModelMaterializer.kt | content·series 번역을 renderedPayload에 저장 |
| v2/creator/channel/audio/adapter/out/persistence/DefaultCreatorChannelAudioQueryRepository.kt | 오디오 title·seriesName·테마는 요청 locale 번역 우선 |
| v2/creator/channel/series/adapter/out/persistence/DefaultCreatorChannelSeriesQueryRepository.kt | 시리즈 번역 우선과 원문 fallback 구현됨 |
| v2/creator/channel/home/adapter/out/persistence/DefaultCreatorChannelHomeQueryRepository.kt | 오디오·시리즈 제목 및 AUDIO 일정 제목은 요청 locale 번역 우선 |
| v2/content/all/adapter/out/persistence/DefaultMainContentAllQueryRepository.kt | 오디오·시리즈 제목은 요청 locale 번역 우선 |
| v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepository.kt | 일반 카드 및 mostCommentedAudios 제목은 요청 locale 번역 우선 |
| v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt | FIRST_AUDIO_CONTENT 제목은 요청 locale 번역 우선 |
| v2/content/ranking/application/AudioRankingQueryService.kt | 요청 locale을 조회 port에 전달하고 snapshot 표시 제목만 번역 |
기존 QueryService → Port → Persistence 경계를 유지하며 필요한 locale을 전달한다.
기존 번역 조인 또는 ID 일괄 조회를 재사용한다. 항목별 단건 조회로 N+1을 만들지 않는다.
페이지·정렬·필터 결과를 유지한 채 제목을 매핑한다. 별도 범용 번역 프레임워크·캐시·의존성·DDL은 추가하지 않는다.
랭킹/추천 스냅샷 생성 작업에 요청 범위 LangContext를 주입하지 않는다.
## 5. 검증 시나리오
1. 같은 원문에 ko/en/ja별 서로 다른 번역을 준비하고 7개 API의 대상 필드가 헤더에 맞는지 확인한다.
2. 번역 행 없음, 빈 제목, 공백 제목, 다른 locale 번역만 존재하는 경우 필드별 원문 fallback을 확인한다.
3. 오디오 번역만 있고 시리즈 번역이 없는 혼합 사례에서 각 필드가 독립적으로 선택되는지 확인한다.
4. 언어를 바꿔도 콘텐츠 ID·순서·페이지·필터·랭킹과 제외 필드가 동일한지 확인한다.
5. 실제 HTTP 요청과 DB 조회 테스트로 연결을 검증한다. Mock 응답의 문자열 확인만으로 완료 처리하지 않는다.
## 6. 결정 기록
| 날짜 | ID | 구분 | 내용 |
|---|---|---|---|
| 2026-09-09 | DEC-LIST-01 | 사용자 확정 | 앞서 조사한 조회 위치 모두 Accept-Language에 따른 번역 표시 |
| 2026-09-09 | DEC-LIST-02 | 사용자 확정 | 번역 없음·공백이면 원문 표시 |
| 2026-09-09 | DEC-LIST-03 | 사용자 확정 | 오디오 제목·시리즈 제목/시리즈명·테마명 대상, 댓글·닉네임·배너 유지 |
| 2026-09-09 | DEC-LIST-04 | 기존 동작 유지 | 언어 파싱·기본 언어·인증·조회 조건·응답 스키마 유지 |
| 2026-09-09 | DEC-LIST-05 | 사용자 제한 | 문서만 작성, 구현하지 않음 |
| 2026-09-09 | DEC-LIST-06 | 사용자 지시 | 현재 브랜치에서 Phase 1 구현 진행. PRD에도 구현 상태를 최종 갱신 |
| 2026-09-09 | DEC-LIST-07 | 사용자 지시 | 로컬 수동 테스트가 불가능하므로 Phase 2까지 자동 검증을 완료하고 test 서버에서 HTTP 검증 |
제품 결정이 필요한 미결 항목은 없다. test 서버 배포 후 대상 7개 API의 수동 HTTP 검증이 남아 있다.
@@ -1,965 +0,0 @@
# 크리에이터 커뮤니티 게시물 본문 번역 구현 계획
| 문서 항목 | 내용 |
|---|---|
| 상태 | 기존 로컬 Gate 기록 유지 · `P1-R4` 구현·자동 회귀·수정 후 리뷰 완료 · 테스트 서버 수동 검증 대기 |
| 작성일 | 2026-09-10 |
| 요구사항 / API 기준 | [PRD](prd.md), 특히 §3 요구사항과 §5 API 계약 |
| 기준 템플릿 | `docs/sample/sample-plan-task.md` |
| 현재 Phase / 활성 Goal | `P1-R4` 및 P1/P2 영향 회귀 완료 / 활성 구현 Goal 없음 |
| 다음 Goal | 테스트 브랜치 배포 후 실제 MySQL/Papago/HTTP 수동 검증 |
## 목표·범위·제약
본문 원문을 보존하면서 한국어·영어·일본어 번역을 저장하고, 상세·목록·미리보기 전체에 일관되게 제공한다.
신규/본문 수정은 전체 목표 언어를 처리하고, 기존 게시물의 누락 번역은 상세에서 요청 언어만 예약한다.
기존 Kotlin, Java 17, Spring Boot 2.7.14, Gradle Wrapper, JUnit 5, QueryDSL/JPA, Papago를 사용한다.
새 큐·스케줄러·외부 의존성·공개 API 필드를 추가하지 않는다. 원문과 번역을 분리하며 구매/차단/성인 정책을 유지한다.
새 재사용 기능은 `v2/creator/channel/community/translation` 아래에 두고 기존 공통 번역 연결부만 확장한다.
현재 PRD의 제외 범위는 모든 Goal에 적용한다. 신규 파일 경로는 아래 표에서 `생성`으로 구분한다.
로컬 검증은 Gradle 자동 테스트와 ktlint으로 한정한다. DDL·HTTP·실제 MySQL 동시성은 로컬에서 실행하지 않고,
테스트 브랜치 배포 후 이 문서의 수동 체크리스트에서 확인한다.
## 현재 상태와 실행 순서
| Phase | 결과 | 상태 | 완료 Task | 다음 Goal |
|---|---|---|---|---|
| 1 | 현재 본문에 대응하는 번역 저장·감지 기반 | `P1-R4` 포함 로컬 자동 검증 완료 | 6/6 | 테스트 서버 수동 검증 |
| 2 | 작성·수정·상세의 비동기 연결과 폴백 | 완료 | 2/2 | 테스트 서버 수동 검증 |
| 3 | 모든 목록·홈 적용과 전체 사용자 흐름 검증 | 로컬 Gate 완료 | 2/2 | 테스트 서버 수동 검증 |
실행 순서: `P1-T1 → P1-T2 → P1-GATE → P1-R1 → P1-GATE 재검증 → P1-R2 → P1-GATE 재검증 → P1-R3 → P1-GATE 재검증 → P2-T1 → P2-T2 → P2-GATE → P3-T1 → P3-T2 → P3-GATE → P3-R1 → P3-GATE 재검증 → P1-R4 → P1/P2 영향 회귀 → 수정 후 리뷰`.
Task 또는 Gate 하나만 활성 Goal로 운용한다. 각 Goal의 시작 조건·체크박스·완료 증거·검증 기록을 모두 충족해야 완료한다.
과거 완료 기록은 되돌리지 않고 후속 문제를 별도 수정 Task로 누적한다.
2026-09-10 후속 리뷰: [Phase 1](reviews/phase-1-review.md)은 수정 1건, [Phase 2](reviews/phase-2-review.md)와
[Phase 3](reviews/phase-3-review.md)는 추가 확정 발견 사항 없음.
당시 후속 실행 순서: `P1-R4 → P1-GATE 영향 범위 재검토 → P2 상세 경로 영향 재검토 → 기존 테스트 서버 수동 검증`.
당시 정적 리뷰는 사용자 지시에 따라 테스트를 재실행하지 않았다. 이후 `P1-R4`의 RED/GREEN, P1/P2 영향 회귀와
수정 후 리뷰를 완료했다. 기존 Task/Gate 기록은 유지하며 남은 단계는 테스트 서버 수동 검증이다.
## 설계 계약
### 데이터와 공통 파이프라인
- `CreatorCommunity.languageCode: String?`, `contentRevision: Long`을 추가한다. 기존 행은 NULL/0, 신규 행도 0부터 시작한다.
실제 원문 문자열 변경 때만 개정 번호를 증가시키고 언어를 NULL로 초기화한다. 동시 수정 시 개정 번호가 충돌하지 않도록
기존 소유권 조건을 유지한 행 잠금 조회를 사용한다.
- 신규 `CreatorCommunityTranslation`에는 `creatorCommunityId`, `locale`, `content`, `sourceRevision`, `sourceHash`,
`sourceLanguage`와 기존 BaseEntity 시각 필드를 둔다. 게시물 ID와 locale 조합을 유일하게 만든다.
- `LanguageDetectTargetType`과 `LanguageTranslationTargetType`에 `CREATOR_COMMUNITY`를 추가한다.
번역 필드 키는 `content` 하나다. 다른 리소스 분기는 수정하지 않는다.
- `TranslationSource`에 커뮤니티 원문의 개정 번호를 전달할 선택 필드를 추가하고 기존 호출은 기본값으로 유지한다.
`TranslationSourceExtractor`는 활성 커뮤니티의 본문·언어·개정 번호를 같은 스냅샷으로 추출한다.
- materializer는 추출된 개정 번호에 대응하는 메모리만 사용한다. 저장 시 현재 행의 개정 번호·언어·활성을 다시 검사하고
동일한 짧은 DB 트랜잭션 안에서 upsert한다. 오래된 값이 새 번역을 덮어쓰지 않도록 개정 검사와 쓰기를 직렬화한다.
외부 Papago 호출은 해당 잠금 밖에서 기존 워커가 처리한다.
- 기존 `translation_job` 유일 키와 메모리 키는 유지한다. 이미 완료한 원문으로 복원되는 경우에는 메모리에서
현재 개정 번호의 조회 모델을 먼저 materialize하고, 부족한 경우에만 기존 scheduler를 호출한다.
### 신규 공유 서비스 경계
`CreatorCommunityTranslationService` 하나에 다음의 명확히 분리된 진입점을 둔다. 단순 내부 호출을 위한 별도 port는 만들지 않는다.
| 인터페이스 | 책임 / 호출 조건 |
|---|---|
| `findDisplayContents(postIds: List<Long>, locale: String): Map<Long, CreatorCommunityDisplayContent>` | 읽기 전용. 현재 게시물과 번역을 일괄 조회해 표시 본문과 유효 번역 여부를 반환한다. 감지·예약·materialize 금지. 조회 권한 판정은 호출자가 먼저 수행한다. |
| `requestTranslations(postId: Long, targetLanguage: String? = null)` | 별도 쓰기 트랜잭션. NULL이면 원문 외 지원 언어 전체, 값이 있으면 그 언어만 처리한다. 언어가 없으면 감지 이벤트를 발행하고, 있으면 메모리 복원 후 누락 작업을 예약한다. |
감지 이벤트에는 커뮤니티용 `sourceRevision: Long? = null`, `targetLanguage: String? = null` 정보를 추가한다.
기존 이벤트 발행자는 기본값으로 동작한다. 커뮤니티 핸들러는 감지 요청 당시 개정과 현재 개정을 비교한다.
감지 결과 저장은 개정 번호·활성 상태 조건을 포함한 갱신으로 처리하고, 저장 커밋 후 공유 서비스를 호출한다.
상세에서 넘어온 targetLanguage를 유지해야 기존 글의 첫 감지가 전체 언어 번역으로 확대되지 않는다.
이미 감지된 본문에는 감지를 반복하지 않고 해당 언어로 예약을 이어간다. 다중 상세 요청에서 감지 API의 동시 중복 호출을
완전히 제거하는 신규 분산 잠금은 추가하지 않는다. 기존 감지 캐시를 재사용하고 작업 중복/유일성 경합은 기존 DB 키와
커뮤니티 예약 경계에서 제어한다. 유일 키 경합으로 정상 상세 응답이 실패하지 않도록 통합 검증한다.
### 트랜잭션과 표시 순서
- 작성·수정 커밋 후 처리에는 기존 커밋 후 실행 패턴을 재사용한다. 감지·예약은 롤백된 원문을 소비하지 않는다.
- 레거시 서비스와 v2 facade/query service는 읽기 전용 트랜잭션이 있으므로 상세의 감지/예약은 별도 Spring bean의
`REQUIRES_NEW` 진입점을 통해 처리한다. 자기 호출로 트랜잭션 프록시를 우회하지 않는다.
- 권한/노출 판정 → 현재 원문/유효 번역 선택 → 기존 유료 마스킹 → 응답 조립 순서로 적용한다.
- 목록·채널 홈·홈 추천·팔로잉은 일괄 읽기 메서드만 호출한다. 추천 스냅샷에는 언어별 본문을 넣지 않고
기존 후보 ID로 얻은 상세 레코드의 본문만 응답 조립 전에 치환한다.
- 원문을 담은 관리자 편집 응답, 댓글·답글, 푸시 이벤트와 정산 조회는 그대로 둔다.
### Phase 1: 번역 저장과 원문 언어 감지 기반
#### 구현 항목
- [x] **Task 1.1: 개정 번호에 대응하는 본문 번역 저장·조회·메모리 복원**
**Goal ID / objective:** `P1-T1` — 현재 본문과 일치하는 번역만 저장·조회할 수 있다.
- 시작 조건: PRD `CCT-001`, `CCT-007`, `CCT-010` 확인, 사용자 구현 요청.
- 완료 증거: 아래 파일과 local automatic gate, 원문 복원/오래된 번역 차단 검증 기록.
실제 MySQL DDL·HTTP·동시성 확인은 테스트 브랜치 배포 후 수동 체크리스트로 이관한다.
- 범위 밖: 언어 감지 이벤트 연결, HTTP 진입점 변경.
- 생산 인터페이스: 설계 계약의 `findDisplayContents`, 언어 확정 상태의 `requestTranslations`, 커뮤니티 source/materializer 분기.
| 작업 | 정확한 파일 경로 |
|---|---|
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/CreatorCommunity.kt` |
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/CreatorCommunityRepository.kt` |
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/LanguageTranslationEvent.kt` |
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationSourceExtractor.kt` |
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationReadModelMaterializer.kt` |
| 생성 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/community/translation/adapter/out/persistence/CreatorCommunityTranslation.kt` |
| 생성 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/community/translation/adapter/out/persistence/CreatorCommunityTranslationRepository.kt` |
| 생성 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/community/translation/application/CreatorCommunityTranslationService.kt` |
| 생성 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/community/translation/CreatorCommunityTranslationServiceTest.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationJobWorkerTest.kt` |
| 생성 | `docs/20260910_크리에이터커뮤니티게시물본문번역/schema.sql` |
- [x] **RED:** 번역 없음/동일 언어/현재 개정 일치/이전 개정/다른 언어 결과의 표시 테스트와 본문 A→B→A 복원 테스트를 작성한다.
materializer는 작업 실행 도중 원문 변경·비활성화 시 오래된 번역을 저장/노출하지 않는 테스트로 보호한다.
- [x] **RED 확인:** 아래 focused 명령에서 해당 동작의 assertion 실패를 확인한다. 컴파일 오류만으로 RED를 완료하지 않는다.
- [x] **GREEN:** 기존 메모리/워커를 연결하고 일괄 읽기, 개정 검사, 현재 메모리 복원을 최소 구현한다.
MySQL DDL은 기존 행 NULL/0 보존, locale 유일 키, 모든 컬럼 COMMENT, 테이블 COMMENT를 포함한다.
시각은 `TIMESTAMP`, created/updated 기본값은 `docs/agent-guides/문서유지보수.md`를 따른다.
- [x] **GREEN 확인:** focused test에서 원문 보존·중복 키·동시 upsert·이전 결과 차단·캐시 복원 통과를 확인한다.
- [x] **REFACTOR:** 이번 변경의 중복만 정리하고 focused test와 공통 번역 회귀를 실행한다. 자동 검증 결과와 배포 후 DDL 확인 항목을 이 Task 아래에 기록한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.CreatorCommunityTranslationServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobWorkerTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.i18n.translation.*'
```
DDL은 테스트 브랜치 배포 후 격리된 MySQL 테스트 DB에 적용해 기존 행의 언어 NULL/개정 0, 원문 유지, locale 유일 키를 확인한다.
운영 DB 적용은 이 Task의 검증으로 실행하지 않는다.
#### P1-T1 검증 기록 — 2026-09-10
- RED: `CreatorCommunityTranslationServiceTest.shouldRequireCreatorCommunityTranslationPersistenceContract`를 먼저 작성했다.
`./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.CreatorCommunityTranslationServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobWorkerTest'`는
exit 1로 실패했고, `CreatorCommunityTranslationServiceTest.kt:13`의 `languageCode` 누락 assertion이 원인이었다.
- GREEN/REFACTOR: `CreatorCommunity`의 nullable 언어·0 시작 개정, 현재 개정/해시/언어/활성 상태를 잠금으로 재확인하는
materializer, 메모리 우선 복원 후 기존 scheduler를 쓰는 서비스, 일괄 표시 조회와 locale 유일 번역 저장을 추가했다.
같은 focused 명령은 exit 0, `BUILD SUCCESSFUL`로 통과했다.
- 동시성: H2 MySQL 모드 `@DataJpaTest`에서 두 worker를 같은 원문 메모리 재료화 지점에 동시에 진입시켜,
게시물 `PESSIMISTIC_WRITE` 잠금과 locale 유일 키 후 번역 행 1개·오류 0개를 확인했다.
- 공통 회귀: `./gradlew test --tests 'kr.co.vividnext.sodalive.i18n.translation.*'` — exit 0, `BUILD SUCCESSFUL`.
`./gradlew ktlintCheck` — exit 0, `BUILD SUCCESSFUL`.
- DDL: `schema.sql`에 기존 행의 `language_code` NULL 및 `content_revision` 0 기본값, locale 유일 키, 전 컬럼/테이블 COMMENT,
BaseEntity 시각 컬럼 규칙을 기록했다. 운영 DB에는 적용하지 않았다.
- 전체 회귀/수동 HTTP/Papago/MySQL 적용 검증은 이 Task의 지정 focused/common Gradle 검증 범위를 넘어 실행하지 않았다.
#### P1-T1 검토 수정 — 2026-09-10
- 검토 확인 RED: `CreatorCommunityTranslationServiceTest.shouldRejectStaleManagedCreatorCommunityAfterConcurrentCommit`를
실제 JPA transaction으로 추가했다. focused 명령은 exit 1, 20개 테스트 중 1개 실패였고,
stale managed `CreatorCommunity`로 이전 번역을 저장한 `CreatorCommunityTranslationServiceTest.kt:358` assertion이 원인이었다.
- GREEN: `EntityManager.refresh(..., PESSIMISTIC_WRITE)`로 잠긴 게시물의 최신 상태를 다시 읽고,
번역 행도 `findByCreatorCommunityIdAndLocaleForUpdate`의 잠금 현재 읽기로 조회하게 했다. provider 호출은 기존처럼
materializer transaction 밖의 worker에 남는다. 같은 focused 명령은 exit 0, `BUILD SUCCESSFUL`로 통과했다.
- 테스트 보강: 번역 없음·원문 언어 불일치·원문 해시 불일치의 원문 폴백, 실제 JPA stale persistence-context 차단,
A→B→A 기존 번역 행 갱신, repeatable-read snapshot 뒤 동시 upsert를 확인했다.
- H2 설정: `@AutoConfigureTestDatabase(replace = NONE)`와 `jdbc:h2:mem:creator-community-translation;MODE=MySQL`을
사용한다. 이는 H2 호환 모드일 뿐 실제 MySQL DDL·REPEATABLE READ 검증 증거가 아니다.
- 기록 정정: 이전 검증 기록의 H2 MySQL 모드 표기는 datasource replacement를 끄기 전에는 성립하지 않았다.
현재 H2 설정을 바로잡았지만, 과거 결과를 실제 MySQL 결과로 소급하지 않는다.
- 회귀: `./gradlew test --tests 'kr.co.vividnext.sodalive.i18n.translation.*'` — exit 0, `BUILD SUCCESSFUL`.
`./gradlew ktlintCheck` — exit 0, `BUILD SUCCESSFUL`.
- 사용자 검증 정책 변경: local acceptance는 automatic Gradle test와 ktlint으로 한정한다. 위 자동 검증이 통과했으므로
Task 1.1과 GREEN 확인/REFACTOR 체크박스를 완료로 표시한다. Docker, 서버, HTTP, MySQL은 local에서 실행하지 않는다.
- 배포 후 보류: `schema.sql` 적용, 기존 행 NULL/0, locale 유일 키, 실제 MySQL REPEATABLE READ 동작은
테스트 브랜치 배포 후 아래 수동 체크리스트에서만 확인하며 아직 통과로 기록하지 않는다.
- [x] **Task 1.2: 미확정 원문 언어의 비동기 감지와 목표 언어 전달**
**Goal ID / objective:** `P1-T2` — 본문 언어가 없으면 현재 본문을 감지하고 요청 범위의 번역으로 이어진다.
- 시작 조건: `P1-T1` 완료.
- 완료 증거: 한국어/영어/일본어 감지, 단일/전체 목표 언어 전달, 지연 감지·실패 테스트 통과.
- 범위 밖: 사용자 언어 입력 필드, 다른 리소스의 감지 정책 변경.
- 소비/생산: 기존 `LanguageDetectionCacheService.detectWithCache`를 소비하고 커뮤니티 감지 분기와 완성된 `requestTranslations`를 제공한다.
| 작업 | 정확한 파일 경로 |
|---|---|
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectEvent.kt` |
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/CreatorCommunityRepository.kt` |
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/community/translation/application/CreatorCommunityTranslationService.kt` |
| 생성 | `src/test/kotlin/kr/co/vividnext/sodalive/content/CreatorCommunityLanguageDetectTest.kt` |
| 확인 | `src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectionCacheService.kt` |
| 확인 | `src/test/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectionCacheServiceTest.kt` |
- [x] **RED:** 언어 NULL인 본문 감지 후 `targetLanguage=ja`는 일본어만, NULL은 원문 외 두 언어로 이어지는 실패 테스트를 작성한다.
빈 본문·미지원 원문 언어·감지 실패·감지 중 본문 수정·중복 이벤트도 포함한다.
- [x] **RED 확인:** 아래 focused 명령으로 목표 언어 유실과 오래된 감지 결과 적용의 assertion 실패를 확인한다.
- [x] **GREEN:** 기존 감지 이벤트에 기본값이 있는 커뮤니티 메타데이터를 추가하고 개정 조건부 저장·커밋 후 예약을 연결한다.
다른 리소스 이벤트와 동작은 유지한다.
- [x] **GREEN 확인:** 외부 감지 provider 경계만 통제한 통합 테스트로 실제 커밋 후 이벤트/별도 트랜잭션을 확인한다.
테스트를 감싼 트랜잭션이 커밋되지 않아 AFTER_COMMIT이 실행되지 않는 문제를 피한다.
- [x] **REFACTOR:** focused test와 기존 감지 캐시/번역 scheduler 회귀 결과를 기록한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobSchedulerTest'
```
#### P1-T2 검증 기록 — 2026-09-10
- RED: `CreatorCommunityLanguageDetectTest.shouldKeepLegacyDefaultsAndDeclareCreatorCommunityMetadata`를 먼저 작성했다.
`./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest'`는 exit 1,
`CreatorCommunityLanguageDetectTest.kt:14`의 `CREATOR_COMMUNITY` 누락 assertion으로 실패했다.
- 행위 RED: 커밋 후 단일/전체 목표 언어 전달, 빈 본문·미지원 감지값·provider 실패·stale 본문·중복 이벤트를 추가했다.
같은 명령은 exit 1, `CreatorCommunityLanguageDetectTest.kt:85`, `:106`, `:179`의
`CreatorCommunityTranslationService.requestTranslations(...)` `WantedButNotInvoked` assertion으로 실패했다.
- GREEN: `LanguageDetectEvent`의 기본값 있는 커뮤니티 메타데이터, 언어 미확정 본문의 현재 content/revision 이벤트 발행,
감지 외부 호출 전 무잠금 상태 확인과 잠금 후 active/revision/content 재확인, 저장 커밋 뒤 기존 번역 서비스 호출을 연결했다.
감지 언어가 지원 범위 밖이거나 비어 있으면 원문·작업 상태를 유지한다.
- AFTER_COMMIT: `@Transactional(propagation = Propagation.NOT_SUPPORTED)` 테스트와 명시적 `TransactionTemplate` 커밋으로
이벤트를 발행했다. 테스트용 감지 provider 경계만 제어하고 실제 행 언어 저장 뒤 `requestTranslations(postId, "ja")` 또는
`requestTranslations(postId, null)` 호출을 검증했다.
- focused: 위 P1-T2 명령 — exit 0, `BUILD SUCCESSFUL`.
- 범위: local automatic 정책에 따라 Docker, HTTP, 실제 Papago, MySQL DDL/동시성은 실행하지 않았다.
#### Phase 1 Gate
- [x] **Goal `P1-GATE`: 현재 본문 기반의 감지·번역 저장 경계 판정**
- 시작 조건: `P1-T1`, `P1-T2` 체크박스와 검증 기록 완료.
- 완료 증거: 아래 명령 exit 0, DDL·엔티티 정적 대조, 개정/언어 불일치 미노출 기록.
- 범위 밖: API 연결 구현. TDD 예외 사유: 이미 작성한 동작과 DDL의 Gate 검증이며 별도 제품 코드가 아니다.
- 대체 검증: 기존 통합 테스트를 실행하고 DB의 현재 개정/번역 개정/언어를 대조한다.
- 확인 파일: 두 Task의 source/test 파일 및 `docs/20260910_크리에이터커뮤니티게시물본문번역/schema.sql`.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.*' --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.*'
```
#### P1-GATE 검증 기록 — 2026-09-10
- 자동 Gate: 위 명령 — exit 0, `BUILD SUCCESSFUL`. 현재 개정 번역 저장/메모리 복원/작업 예약과 커밋 후 감지 경계를 함께 회귀했다.
- 형식: `./gradlew ktlintCheck` — exit 0, `BUILD SUCCESSFUL`.
- 보류: 사용자 정책에 따라 실제 MySQL DDL·격리 수준, HTTP, Docker, 실제 Papago 검증은 실행하지 않았다.
테스트 브랜치 배포 후 수동 체크리스트는 모두 미완료 상태로 유지한다.
#### Task 1.R: P1-T2 리뷰 회귀 수정
**Goal ID / objective:** `P1-R1` — 감지 커밋 후 독립 트랜잭션에서 현재 본문만 요청 범위대로 번역 작업으로 예약한다.
- 시작 조건: `reviews/p1-t2-review.md`의 `REV-P1-T2-001~004` 확정, `P1-T2` 및 `P1-GATE` 기존 기록 확인.
- 완료 증거: 실제 Spring 감지 listener와 scheduler를 사용하는 실패 재현 test, 최소 수정 후 focused test와 P1 Gate 재검증, 검증 기록.
- 범위 밖: 다른 리소스 감지 정책, 공개 API, Docker·HTTP·실제 Papago·MySQL 수동 검증.
| 작업 | 정확한 파일 경로 |
|---|---|
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectEvent.kt` |
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/community/translation/application/CreatorCommunityTranslationService.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/content/CreatorCommunityLanguageDetectTest.kt` |
| 생성 | `docs/20260910_크리에이터커뮤니티게시물본문번역/reviews/p1-t2-review.md` |
- [x] **RED:** `REQUIRES_NEW`, 실제 `translation_job` 저장, stale 본문 차단, known-language 다중 target continuation을 실제 Spring 경계로 재현한다.
- [x] **RED 확인:** `./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest'`에서 7개 중 5개 assertion 실패를 확인한다.
- [x] **GREEN:** 감지 listener의 잠금 현재 읽기와 커밋 후 독립 번역 요청 트랜잭션을 최소 수정한다.
- [x] **GREEN 확인:** 같은 focused test가 성공하는지 확인한다.
- [x] **REFACTOR:** P1-T2 직접 영향 회귀, P1 Gate, ktlint을 실행하고 실제 결과를 기록한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobSchedulerTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.*' --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.*'
./gradlew ktlintCheck
```
#### P1-R1 진행 기록 — 2026-09-10
- RED: 새 `CreatorCommunityLanguageDetectTest`는 초기 Kotlin generic 추론과 `AudioContentThemeQueryRepository` test bean 누락을 바로잡은 뒤 실행했다.
focused 명령은 exit 1, 7개 중 5개 assertion 실패였다. `REQUIRES_NEW` annotation 부재, 커밋 뒤 job 미저장,
stale 감지 결과의 언어 저장, 이미 언어가 있는 두 target 이벤트의 job 미저장을 확인했다.
- GREEN: `requestTranslations`를 `REQUIRES_NEW`로 분리하고, listener는 잠금 조회 뒤 `EntityManager.refresh(..., PESSIMISTIC_WRITE)`로
현재 본문을 확인한다. 이미 언어가 있는 이벤트도 감지 없이 after-commit에서 원 target을 요청한다.
- GREEN 확인: `./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest'` — exit 0, `BUILD SUCCESSFUL`.
실제 Spring listener와 scheduler를 통해 단일/전체 target job 저장, stale 본문 차단, known-language 두 target continuation을 확인했다.
- REFACTOR/Phase Gate 재검증: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.*' --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.*' ktlintCheck bootJar`
— exit 0, `BUILD SUCCESSFUL`. focused/공통 번역 회귀, ktlint, bootJar를 함께 확인했다.
- 범위: 사용자 정책에 따라 Docker, HTTP, 실제 Papago, MySQL 수동 동시성 검증은 실행하지 않았다.
#### Task 1.R3: P1-T2 동일 게시물 작업 예약 직렬화
**Goal ID / objective:** `P1-R3` — 같은 게시물·target의 동시 `requestTranslations`가 누락 메모리에서도 하나의 translation job만 예약한다.
- 시작 조건: `reviews/p1-t2-review.md`의 `REV-P1-T2-006` 확정, `P1-R2` 완료 기록 확인.
- 완료 증거: 실제 Spring/JPA service와 job repository의 concurrent missing-memory RED test, 최소 lock 수정 후 두 호출 정상 종료·job 1개, P1 Gate 재검증.
- 범위 밖: 공통 scheduler 동작, 다른 resource type, 분산 lock·의존성, P2/P3, Docker·HTTP·실제 Papago·MySQL 수동 검증.
| 작업 | 정확한 파일 경로 |
|---|---|
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/community/translation/application/CreatorCommunityTranslationService.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/community/translation/CreatorCommunityTranslationServiceTest.kt` |
| 수정 | `docs/20260910_크리에이터커뮤니티게시물본문번역/reviews/p1-t2-review.md` |
- [x] **RED:** 같은 언어 확정 게시물·target의 두 요청을 동시에 시작해 실제 `translation_job` unique insert 경합을 재현한다.
- [x] **RED 확인:** `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.CreatorCommunityTranslationServiceTest'`에서 unique-key 오류 또는 정상 완료/job 1개 위반을 확인한다.
- [x] **GREEN:** `REQUIRES_NEW` request transaction 시작에 active post write lock과 refresh를 추가한다.
- [x] **GREEN 확인:** 같은 focused test가 두 호출 정상 종료와 job 1개를 확인한다.
- [x] **REFACTOR:** P1-T2 직접 영향 회귀, P1 Gate, ktlint을 실행하고 실제 결과를 기록한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.CreatorCommunityTranslationServiceTest' --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobSchedulerTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.*' --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.*'
./gradlew ktlintCheck
```
#### P1-R3 진행 기록 — 2026-09-10
- 원인: `requestTranslations`가 post lock 없이 memory lookup과 `TranslationJobScheduler`의 select-then-insert를 수행해,
동일 post·target의 두 request transaction이 unique key에 경합할 수 있다.
- RED: actual JPA `translation_job` 저장을 사용하는 두 `REQUIRES_NEW` transaction의 missing-job 조회 창을 동기화했다.
focused 명령은 exit 1이었고, H2 `SQLState 23505`의 `uk_translation_job_resource_field_target_hash` unique index 충돌을 확인했다.
- GREEN: `requestTranslations` 시작에서 active post를 `findByIdAndIsActiveTrueForUpdate`로 잠그고
`EntityManager.refresh(..., PESSIMISTIC_WRITE)`한 뒤 source extraction, memory lookup, job 조회·저장을 진행한다.
- GREEN 확인: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.CreatorCommunityTranslationServiceTest'`
— exit 0, `BUILD SUCCESSFUL`; 두 호출이 정상 종료하고 job 1개만 저장됨을 확인했다.
- REFACTOR/Phase Gate 재검증:
`./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.CreatorCommunityTranslationServiceTest' --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobSchedulerTest'`
— exit 0, `BUILD SUCCESSFUL`.
`./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.*' --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.*'`
— exit 0, `BUILD SUCCESSFUL`.
`./gradlew ktlintCheck` — exit 0, `BUILD SUCCESSFUL`.
- 전체 `./gradlew test`는 private scheduling service의 직접 영향 회귀와 P1 Gate가 통과했으므로 실행하지 않았다.
Docker, HTTP, 실제 Papago, MySQL 수동 동시성 검증도 사용자 정책에 따라 실행하지 않았다.
#### Task 1.R2: P1-T2 동시 감지 target 보존
**Goal ID / objective:** `P1-R2` — 두 언어 미확정 감지가 같은 현재 본문에서 경합해도 각 이벤트의 요청 target을 커밋 후 예약한다.
- 시작 조건: `reviews/p1-t2-review.md`의 `REV-P1-T2-005` 확정, `P1-R1` 완료 기록 확인.
- 완료 증거: 두 감지가 언어 NULL에서 시작한 뒤 한 감지만 먼저 커밋하는 실제 Spring failure test, 최소 수정 후 focused test와 P1 Gate 재검증, 검증 기록.
- 범위 밖: 다른 리소스 감지 정책, 공개 API, Docker·HTTP·실제 Papago·MySQL 수동 검증.
| 작업 | 정확한 파일 경로 |
|---|---|
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectEvent.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/content/CreatorCommunityLanguageDetectTest.kt` |
| 수정 | `docs/20260910_크리에이터커뮤니티게시물본문번역/reviews/p1-t2-review.md` |
- [x] **RED:** 두 감지가 `languageCode=NULL`에서 시작하고 첫 감지 커밋 뒤 두 번째가 lock을 얻는 실제 `ja`/`en` target 보존 test를 작성한다.
- [x] **RED 확인:** `./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest'`에서 두 번째 target job 미저장 assertion 실패를 확인한다.
- [x] **GREEN:** lock/refresh 뒤 현재 revision/content가 유효하고 언어만 이미 설정된 경우 after-commit에 원 target을 등록한다.
- [x] **GREEN 확인:** 같은 focused test가 성공하는지 확인한다.
- [x] **REFACTOR:** P1-T2 직접 영향 회귀, P1 Gate, ktlint을 실행하고 실제 결과를 기록한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobSchedulerTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.*' --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.*'
./gradlew ktlintCheck
```
#### P1-R2 진행 기록 — 2026-09-10
- 원인: `handleCreatorCommunityLanguageDetect`는 lock과 refresh 뒤 다른 감지가 저장한 languageCode를 발견하면,
현재 revision/content가 일치해도 return하여 두 번째 이벤트의 target을 잃는다.
- RED: `shouldPreserveSecondTargetAfterConcurrentDetectionSetsLanguage`는 두 감지가 languageCode NULL에서 시작한 뒤,
첫 감지의 `ja` 예약·커밋 후 두 번째 감지의 `en` 진행을 순서대로 제어했다. focused 명령은 exit 1, 8개 중 1개 assertion 실패였고,
`translation_job`의 `en` 누락이 원인이었다.
- GREEN: lock/refresh 뒤 revision/content가 같고 languageCode만 이미 설정되어 있으면 이를 덮어쓰지 않고,
기존 `requestTranslationsAfterCommit`에 두 번째 이벤트의 원 target을 등록한다. lock 보유 중 `REQUIRES_NEW` 호출은 하지 않는다.
- GREEN 확인: `./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest'` — exit 0, `BUILD SUCCESSFUL`.
실제 listener/scheduler/repository에서 `ja`와 `en` job 저장 및 source language `ko` 유지를 확인했다.
- REFACTOR/Phase Gate 재검증: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.*' --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.*' ktlintCheck`
— exit 0, `BUILD SUCCESSFUL`.
- 범위: 사용자 정책에 따라 Docker, HTTP, 실제 Papago, MySQL 수동 동시성 검증은 실행하지 않았다.
#### Task 1.R4: 최초 언어 감지 캐시 경합에서도 요청 target 보존
- [x] **Goal `P1-R4`: 동일 본문의 최초 감지 캐시 저장이 경합해도 각 이벤트의 목표 언어 번역을 예약한다**
- 시작 조건: [Phase 1 리뷰](reviews/phase-1-review.md)의 `REV-P1-007` 확인 및 후속 구현 요청.
기존 `P1-R1~R3` 완료 기록을 유지한다.
- 관련 요구사항: `CCT-002`, `CCT-005`, `CCT-010`, 기존 `P1-R2`의 요청 target 보존.
- 완료 증거: 실제 감지 캐시 INSERT 경합의 실패 회귀 테스트 → 최소 수정 → focused 성공 →
P1 감지/번역 및 P2 상세 영향 회귀 → 실행 결과와 리뷰 재판정 기록.
- 범위 밖: 외부 감지 중 게시물 행 잠금, 새 분산 잠금/큐/스케줄러, 번역 지원 언어·공개 API 변경,
감지 provider 실패를 무조건 성공으로 처리, 다른 리소스의 제품 정책 변경, 운영 DB 작업.
| 작업 | 정확한 파일 경로 |
|---|---|
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectionCacheService.kt` |
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectionResultRepository.kt` |
| 확인 | `src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectionResult.kt` |
| 확인 | `src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectEvent.kt` |
| 생성 | `src/test/kotlin/kr/co/vividnext/sodalive/content/CreatorCommunityLanguageDetectionCacheConcurrencyTest.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectionCacheServiceTest.kt` |
| 확인 | `src/test/kotlin/kr/co/vividnext/sodalive/content/CreatorCommunityLanguageDetectTest.kt` |
| 기록 | `docs/20260910_크리에이터커뮤니티게시물본문번역/reviews/phase-1-review.md` |
| 기록 | `docs/20260910_크리에이터커뮤니티게시물본문번역/plan-task.md` |
설계 기준:
- 캐시 miss → detector → 무조건 INSERT를 같은 키의 원자적 저장으로 바꾸고 저장된 결과로 수렴시켰다.
MySQL `ON DUPLICATE KEY UPDATE id=id`와 scalar `SELECT ... FOR UPDATE`를 사용한다. DB 예외를 잡아 무시하지 않는다.
- 동일 해시/provider/normalizationVersion의 승자 결과를 사용하며, 반복 읽기 격리에서도 최초 miss 스냅샷에 갇히지 않도록
저장 후 current read를 보장한다. 기본 언어를 임의로 지정하거나 감지 결과를 최신 본문에 무조건 적용하지 않는다.
- 이미 rollback-only가 된 같은 JPA 트랜잭션에서 예외만 잡고 target 예약을 계속하는 방식은 금지한다.
공통 캐시 저장 수정이 다른 리소스의 기존 감지/캐시 재사용 동작을 바꾸지 않도록 회귀 검증한다.
- 새 테스트는 실제 `LanguageDetectionCacheService`와 repository를 사용한다. `detectWithCache` 전체를 override하지 않고
감지 HTTP 응답/provider 경계만 통제해 두 트랜잭션이 모두 캐시 miss를 읽는 순서를 제어한다.
- [x] **RED:** `shouldPreserveBothTargetsWhenInitialDetectionCacheWritesRace`를 추가한다.
언어 NULL/캐시 없음의 동일 게시물에서 `ja`, `en` 감지를 동시에 시작하고 두 cache miss 이후 첫 저장/커밋,
후발 저장 순서로 진행한다. 두 흐름의 정상 완료, 캐시 1행, `ja`/`en` 작업 모두 존재를 assertion으로 검증한다.
- [x] **RED 확인:** 아래 focused 명령으로 후발 중복 키 예외 또는 target 누락의 의도한 실패를 확인한다.
두 이벤트가 애초에 cache miss에 진입하지 않은 테스트를 경합 재현으로 인정하지 않는다.
- [x] **GREEN:** 원자적 캐시 저장과 저장 결과 재사용만 최소 수정한다. 감지 후 기존 개정/본문 검사와
커밋 후 요청 target 전달을 유지한다.
- [x] **GREEN 확인:** 같은 focused 테스트를 통과시키고, 같은 본문의 서로 다른 게시물 생성도 캐시 1행을 공유하면서
각 게시물의 원문 외 두 언어 작업이 보존되는지 검증한다.
- [x] **REFACTOR:** 감지 캐시·listener·scheduler·materializer 및 실제 상세 프록시 영향 회귀를 실행한다.
선택한 DB 저장 문법의 MySQL 동작과 H2 테스트 지원 범위를 구분하고 실제 MySQL 미검증은 기존 수동 체크리스트에 남긴다.
관련 없는 변경 없이 아래 명령 결과와 `REV-P1-007` 수정 판정을 누적한다.
실행한 focused/영향 회귀 명령이다. focused의 fresh 재실행에는 `--rerun-tasks --no-parallel`을 추가했다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectionCacheConcurrencyTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.*' --tests 'kr.co.vividnext.sodalive.i18n.translation.*'
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.*' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.community.*'
./gradlew ktlintCheck
```
공통 캐시 동작 변경의 영향이 위 회귀로 판정되지 않으면 전체 테스트로 확장한다. 전체 테스트 생략 시 대체 명령과 근거를 기록한다.
현재 상태: RED/GREEN·영향 회귀·수정 후 리뷰 완료. 실제 MySQL 검증은 미완료다.
#### P1-R4 실행 기록 · 2026-09-10
- RED: 위 focused 명령은 두 provider 진입을 모두 확인한 뒤 exit 1로 실패했다.
`ExecutionException → DataIntegrityViolationException → H2 23505`로 감지 캐시 유일 키 충돌을 재현했다.
- GREEN: native MySQL `ON DUPLICATE KEY UPDATE id=id`로 승자 행을 보존하고 scalar `SELECT ... FOR UPDATE`로
저장 결과를 현재 읽기한다. native INSERT의 audit 시각을 명시하며 DB 예외를 잡고 계속 진행하지 않는다.
- GREEN 확인: 실제 캐시 service/repository를 사용해 같은 게시물의 `ja`/`en` 이중 miss 및
서로 다른 게시물의 동일 본문 경합을 검증했다. 캐시 1행으로 수렴하며 각 요청의 목표 언어 작업을 보존한다.
- focused fresh 재실행: 위 첫 명령 + `--rerun-tasks --no-parallel`, `BUILD SUCCESSFUL` (5분 19초).
- P1 listener/scheduler/materializer 회귀: 위 두 번째 명령, `BUILD SUCCESSFUL` (1분 09초).
- P2 상세/API 회귀: 위 세 번째 명령, `BUILD SUCCESSFUL` (1분 42초).
- 형식: `./gradlew ktlintCheck`, `BUILD SUCCESSFUL` (44초).
- 수정 후 리뷰: spec `PASS` (`ses_f7657d350ffe3YUYhEHvHPuikK`), quality `APPROVED`
(`ses_f7656994dffeR2odTLswaw6RTo`). `REV-P1-007`은 로컬 자동 검증 범위에서 수정 완료로 재판정했다.
- 전체 `./gradlew test`는 생략했다. 공통 캐시 계약, 실제 repository 경합, 모든 직접 listener/scheduler/materializer
테스트와 P2 상세/API 소비자가 위 대체 명령으로 통과했고, 미해결 상태로 남은 별도의 공통 경계가 없었다.
- 범위: H2 `MODE=MySQL`은 실제 MySQL 8/InnoDB 검증이 아니다. 실제 MySQL/Papago/HTTP, Docker, 배포는
실행하지 않았다. 상세 명령·리뷰 출처는 [후속 증거](reviews/review-evidence.md)에 누적한다.
### Phase 2: 작성·수정·상세에서 번역 처리
#### 구현 항목
- [x] **Task 2.1: 작성 커밋과 실제 본문 변경에 감지·번역 연결**
**Goal ID / objective:** `P2-T1` — 생성과 본문 수정이 현재 원문 기준의 전체 목표 언어 번역으로 이어진다.
- 시작 조건: `P1-GATE` 완료, `CCT-003~004`, `CCT-007` 확인.
- 완료 증거: 신규·실제 변경·동일 본문·롤백·관리자 공용 경로·동시 수정 검증.
- 범위 밖: 이미지·오디오 업로드, 알림 발행, 소유권 정책 변경.
- 소비 인터페이스: `requestTranslations(postId, targetLanguage = null)`.
| 작업 | 정확한 파일 경로 |
|---|---|
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/CreatorCommunityService.kt` |
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/CreatorCommunityRepository.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/CreatorCommunityServiceTest.kt` |
| 확인 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/admin/aicharacter/community/AiCharacterAdminCommunityPostFacade.kt` |
| 확인/테스트 보강 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/admin/aicharacter/community/AiCharacterAdminCommunityPostCreateTest.kt` |
| 확인/테스트 보강 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/admin/aicharacter/community/AiCharacterAdminCommunityPostUpdateTest.kt` |
- [x] **RED:** 생성 커밋 후 감지, 본문 변경 때만 언어 NULL/개정 증가, 롤백 시 작업 없음의 실패 테스트를 작성한다.
수정 후 새 요청에서 이전 번역 미노출, 실제 언어 변경, 관리자 공용 경로도 포함한다.
- [x] **RED 확인:** 아래 focused 명령으로 번역 연결 부재/개정 미변경의 assertion 실패를 확인한다.
- [x] **GREEN:** 기존 커밋 후 실행 패턴으로 공유 서비스를 연결하고 본문 문자열이 다른 경우에만 언어·개정 상태를 갱신한다.
소유권 조건을 유지한 잠금 조회로 동시 본문 수정의 개정을 직렬화한다.
- [x] **GREEN 확인:** 테스트를 다시 실행하고 동일 본문/본문 외 변경은 감지·번역 요청 0건인지 확인한다.
- [x] **REFACTOR:** 공용 서비스 호출자 회귀를 확인한다. 관리자 facade의 중복 번역 연결은 추가하지 않는다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.CreatorCommunityServiceTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.community.AiCharacterAdminCommunityPostCreateTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.community.AiCharacterAdminCommunityPostUpdateTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.community.AiCharacterAdminCommunityPostConcurrencyTest'
```
#### P2-T1 검증 기록 — 2026-09-10
- RED: focused 명령은 exit 1이었다. 생성 뒤 번역 요청 누락, 본문 변경 뒤 개정/언어 상태 미갱신의 assertion 실패를
`CreatorCommunityServiceTest.kt:333`, `AiCharacterAdminCommunityPostCreateTest.kt:93`,
`AiCharacterAdminCommunityPostUpdateTest.kt:91`에서 확인했다.
- GREEN: `CreatorCommunityService`는 생성과 실제 본문 변경 뒤 기존 after-commit 패턴으로
`requestTranslations(postId, null)`을 요청한다. 본문 변경은 `languageCode`를 NULL로 초기화하고
`contentRevision`을 증가시키며, 수정 조회는 소유권 조건의 `PESSIMISTIC_WRITE` 잠금 후 refresh한다.
- 동시성: 실제 H2/JPA 비관적 잠금 조회를 latch로 제어한 관리자 MockMvc 요청 두 건이 모두 200으로 종료하고,
최종 revision 2와 번역 요청 2건을 확인했다.
- focused: 위 명령과 `LegacyCommunityPostCharacterizationTest`를 포함한 실행 — exit 0, `BUILD SUCCESSFUL`.
생성·수정·동일 본문·롤백·관리자 공용 경로·동시 수정과 변경된 수동 생성자 호출을 함께 확인했다.
- P1 회귀: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.*' --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.*'`
— exit 0, `BUILD SUCCESSFUL`.
- 형식: `./gradlew ktlintCheck` — exit 0, `BUILD SUCCESSFUL`.
- 범위: local acceptance 정책에 따라 Docker, 서버 HTTP, 실제 Papago, MySQL 수동 동시성 검증은 실행하지 않았다.
#### Task 2.R: P2-T1 spec-review 실제 트랜잭션 증거
**Goal ID / objective:** `P2-R1` — 실제 Spring transaction에서 생성 롤백과 본문 변경 뒤 stale 번역 폴백·감지 예약을 증명한다.
- 시작 조건: `P2-T1` 완료, spec-review의 실제 transaction 증거 보강 요구 확인.
- 완료 증거: proxied `CreatorCommunityService` 생성 롤백 뒤 post/job/detection 미영속과, 한글→영문 수정 커밋 뒤
revision·stale 번역 폴백·영문 감지·새 target job을 별도 transaction에서 확인한다.
- 범위 밖: P2-T2 상세/목록 API, production 리팩터링, Docker·HTTP·실제 Papago/MySQL 검증.
| 작업 | 정확한 파일 경로 |
|---|---|
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/content/CreatorCommunityLanguageDetectTest.kt` |
| 수정 | `docs/20260910_크리에이터커뮤니티게시물본문번역/plan-task.md` |
| 확인 | `src/main/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/CreatorCommunityService.kt` |
- [x] **TEST-FIRST:** 실제 outer transaction rollback 뒤 생성 post와 감지/번역 작업이 남지 않는 test를 작성한다.
기존 한글 translation 행이 있는 post의 실제 영문 수정 뒤, 감지 전 stale 번역 폴백과 감지 후 언어·target job을 test한다.
- [x] **TEST-FIRST 확인:** 첫 실행에서 async 감지 완료 전 `languageCode`를 읽은 assertion 실패를 확인하고, 기존 `await` 방식의 완료 조건으로 test 경계를 바로잡는다.
- [x] **GREEN:** test가 production 결함을 드러내면 실패 test를 유지한 최소 수정만 적용하고, 아니면 실제 경계 증거만 보강한다.
- [x] **GREEN 확인:** 실제 post-commit 경로가 완료될 때까지 latch/새 transaction으로 대기한 assertion을 통과시킨다.
- [x] **REFACTOR:** P2 focused, P1 번역/감지 회귀, ktlint 결과를 기록한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.CreatorCommunityServiceTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.community.AiCharacterAdminCommunityPostCreateTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.community.AiCharacterAdminCommunityPostUpdateTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.community.AiCharacterAdminCommunityPostConcurrencyTest'
```
#### P2-R1 검증 기록 — 2026-09-10
- test-first: `CreatorCommunityLanguageDetectTest`에 실제 `CreatorCommunityService` bean을 등록하고 AOP proxy를 확인했다.
JPA repository, listener, translation service, scheduler는 실제 bean을 사용하며 S3·FCM 연관 의존성과 external detector만 test 경계로 제어했다.
- 생성 rollback: 실제 outer `TransactionTemplate`에서 `createCommunityPost`를 호출하고 rollback-only로 종료했다.
새 transaction에서 생성 post 부재, 해당 post ID의 translation read-model 및 `translation_job` 0건, detector query 0건을 확인했다.
- 영문 수정: 기존 한글 원문과 유효한 이전 영어 translation 행을 만들고 실제 `modifyCommunityPost`를 commit했다.
차단된 detector가 시작된 뒤 새 transaction에서 `languageCode=NULL`, revision 1, 현재 영문 원문 반환과 이전 영어 translation 행의
미사용을 확인했다. detector 해제 뒤 `languageCode=en`, `ko`·`ja` job 예약을 대기해 확인했다.
- 첫 실행: rollback test는 통과했고 수정 test는 async `@TransactionalEventListener` 완료 전 state를 읽어 `expected en but was null`로 실패했다.
이는 production 결함이 아니라 outer service future가 async 감지 완료를 기다리지 않는 test synchronization 문제였으며,
기존 조건 기반 `await`로 post-commit 완료를 기다리도록 바로잡았다. production 파일은 변경하지 않았다.
- focused: 위 P2-R1 명령에 `--rerun-tasks`를 추가해 재실행 — exit 0, `BUILD SUCCESSFUL`.
- P1 회귀: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.*' --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.*'`
에 `--rerun-tasks`를 추가해 재실행 — exit 0, `BUILD SUCCESSFUL`.
- 형식: `./gradlew ktlintCheck --rerun-tasks` — exit 0, `BUILD SUCCESSFUL`.
- 범위: Docker, 서버 HTTP, detail/list API, 실제 Papago/MySQL 검증은 실행하거나 변경하지 않았다.
#### Task 2.R: P2-T1 quality-review 고정 상태 경쟁 회귀
**Goal ID / objective:** `P2-R2` — 관리자/레거시 고정 상태 변경이 최신 본문·개정·언어 상태를 덮어쓰지 않는다.
- 시작 조건: P2-T1 완료, quality-review의 stale flush 및 test pseudo-lock 지적 확정.
- 완료 증거: stale admin read 뒤 동시 본문 변경을 commit하고 고정+본문 요청을 재개하는 실제 JPA race test에서
최신 본문·revision·language와 fixed 상태를 확인한다. test는 production 소유권 조건 `PESSIMISTIC_WRITE` query를 사용한다.
- 범위 밖: P2-T2/P3, API schema, `@DynamicUpdate`/`@Version`, dependency, Docker·HTTP·실제 MySQL 검증.
| 작업 | 정확한 파일 경로 |
|---|---|
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/CreatorCommunityService.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/admin/aicharacter/community/AiCharacterAdminCommunityPostConcurrencyTest.kt` |
| 수정 | `docs/20260910_크리에이터커뮤니티게시물본문번역/plan-task.md` |
| 확인 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/admin/aicharacter/community/AiCharacterAdminCommunityPostFacade.kt` |
| 확인 | `src/main/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/CreatorCommunityRepository.kt` |
- [x] **RED:** stale admin read 뒤 별도 transaction의 본문/개정/언어 변경을 commit하고, 재개한 fixed+content 요청이 최신 상태에서 적용돼야 한다는 실제 JPA race test를 작성한다.
- [x] **RED 확인:** 현재 구현으로 최신 state 보존 assertion이 실패하는지 확인한다.
- [x] **GREEN:** `updateCommunityPostFixed`가 소유권 조건 post lock과 refresh를 통해 최신 행을 얻은 뒤에만 고정 상태를 변경하도록 최소 수정한다.
관리자 흐름의 member→post lock 순서는 유지한다.
- [x] **GREEN 확인:** production repository lock query를 사용하는 test에서 두 번째 요청의 pre-lock/lock 도착을 latch로 제어하고 executor 종료까지 확인한다.
- [x] **REFACTOR:** P2 focused, P1 번역/감지 회귀, ktlint, diff check 결과를 기록한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.CreatorCommunityServiceTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.community.AiCharacterAdminCommunityPostCreateTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.community.AiCharacterAdminCommunityPostUpdateTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.community.AiCharacterAdminCommunityPostConcurrencyTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.*' --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.*'
./gradlew ktlintCheck
```
#### P2-R2 검증 기록 — 2026-09-10
- RED: `shouldApplyFixedAndContentUpdateAfterConcurrentContentCommit`는 admin facade의 활성 post read 뒤 첫 요청을 멈추고,
별도 worker의 실제 `CreatorCommunityService.modifyCommunityPost`가 production `findByIdAndMemberIdForUpdate` 경로로
`after concurrent` 본문·revision 1·language NULL을 commit한 뒤 mixed `isFixed=true`/`after fixed` 요청을 재개했다.
현재 구현에서 `contentRevision` 2 assertion은 실제 1로 실패했다.
- GREEN: `updateCommunityPostFixed`의 비잠금 조회를 소유권 조건 `findByIdAndMemberIdForUpdate`와
`EntityManager.refresh(..., PESSIMISTIC_WRITE)`로 교체했다. facade의 기존 member lock 뒤 post lock 순서는 바꾸지 않았다.
- 동시성 test: 기존 본문 race의 test-only JPQL lock 대체를 제거하고 두 worker start gate와 실제 production repository query를 사용한다.
새 race는 concurrent content worker가 실제 lock 호출 직전임을 latch로 알리고 commit 완료 뒤 mixed request를 재개한다.
모든 executor는 release 뒤 `shutdown`과 `awaitTermination`으로 종료를 확인한다.
- focused: P2 명령에 `--rerun-tasks`를 추가해 재실행 — 67 tests, exit 0, `BUILD SUCCESSFUL`.
- P1 회귀: P1 명령에 `--rerun-tasks`를 추가해 재실행 — exit 0, `BUILD SUCCESSFUL`.
- 형식: `./gradlew ktlintCheck --rerun-tasks` — exit 0, `BUILD SUCCESSFUL`.
- diff: `GIT_MASTER=1 git diff --check` — exit 0.
- 범위: P2-T2/P3, API schema, `@DynamicUpdate`/`@Version`, dependency, Docker, HTTP, 실제 MySQL 검증은 변경하거나 실행하지 않았다.
- [x] **Task 2.2: 레거시·v2 상세의 저장 번역 표시와 누락 예약**
**Goal ID / objective:** `P2-T2` — 상세에서 원문을 즉시 제공하고 요청 언어의 누락 번역만 예약한다.
- 시작 조건: `P2-T1` 완료, PRD §5 상세 계약 확인.
- 완료 증거: 두 상세 API의 기존 응답 구조·언어 처리·권한·별도 쓰기 트랜잭션·비동기 폴백 테스트 통과.
- 범위 밖: 목록 연결, 댓글 API에서 번역 예약, 번역 상태/원문 필드 추가.
- 소비 인터페이스: 권한 확인 후 `findDisplayContents`를 조회하고, 유효 번역이 없을 때만
`requestTranslations(postId, langContext.lang.code)`를 호출한다.
| 작업 | 정확한 파일 경로 |
|---|---|
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/CreatorCommunityService.kt` |
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/community/application/CreatorChannelCommunityQueryService.kt` |
| 확인 | `src/main/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/SelectCommunityPostResponse.kt` |
| 확인 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/creator/channel/community/application/CreatorChannelCommunityFacade.kt` |
| 확인 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/community/domain/CreatorChannelCommunityQueryPolicy.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/CreatorCommunityServiceTest.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/community/application/CreatorChannelCommunityQueryServiceTest.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/creator/channel/community/adapter/in/web/CreatorChannelCommunityEndToEndTest.kt` |
| 생성 | `src/test/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/CreatorCommunityTranslationEndToEndTest.kt` |
- [x] **RED:** `Accept-Language: ja`에서 기존 언어 미확정 글의 최초 상세는 원문, 감지 후 일본어만 예약,
완료 후 일본어 제공을 테스트한다. 같은 언어·반복 상세·차단·비활성·미구매·댓글 API도 포함한다.
- [x] **RED 확인:** 아래 focused 명령에서 저장 번역 미사용/누락 예약 부재를 확인한다.
- [x] **GREEN:** 기존 권한 확인 뒤 상세에서 유효 번역이 없을 때만 공유 쓰기 진입점을 호출한다. 읽기 전용 부모 트랜잭션과 분리하고
번역 선택은 기존 마스킹 전에 DTO/레코드 `copy(content = ...)`로 반영한다. 원문 엔티티는 조회 중 변경하지 않는다.
- [x] **GREEN 확인:** 실제 HTTP 계약 테스트와 중복 상세 경합에서 정상 응답·중복 작업 방지·원문 즉시 응답을 확인한다.
- [x] **REFACTOR:** 같은 내부 조회를 사용하는 댓글/답글이 예약 진입점을 호출하지 않는지 회귀 검사한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.CreatorCommunityTranslationEndToEndTest' --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.CreatorCommunityServiceTest' --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.application.CreatorChannelCommunityQueryServiceTest' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.community.adapter.in.web.CreatorChannelCommunityEndToEndTest'
```
#### P2-T2 검증 기록 — 2026-09-10
- RED: 상세 경로에 번역 선택과 예약 연결이 없던 상태에서 legacy/v2 focused test의 저장 번역 미사용과 누락 예약 assertion 실패를 확인했다.
컴파일 오류는 RED 증거로 사용하지 않았으며, 새 통합 test의 `viewerId` named argument를 실제 `memberId` 계약에 맞춰 바로잡았다.
- GREEN: `CreatorCommunityService`와 `CreatorChannelCommunityQueryService`는 권한/차단 확인 뒤
`findDisplayContents(...)[postId] ?: content`를 선택하고 `requestTranslations(postId, 요청 언어)`를 호출한다.
선택한 본문은 기존 유료 마스킹 전 DTO/record `copy(content = ...)`에만 반영하며, 엔티티 원문은 변경하지 않는다.
- 통합: `CreatorCommunityTranslationEndToEndTest`는 저장된 번역의 유료 마스킹 전 선택과, 언어 NULL 원문의 즉시 폴백 및
`targetLanguage=ja` 단일 감지 이벤트를 실제 JPA 경계에서 확인했다.
- HTTP 계약: legacy/v2 detail test는 번역 존재/누락, 구매자·소유자의 전체 본문, 미구매자의 기존 마스킹,
차단·비활성 경로, 댓글·답글의 예약 비진입을 확인했다. 같은 언어 예약 없음과 동시 예약의 유일성은 기존
`CreatorCommunityTranslationServiceTest`/통합 test로 회귀했다.
- focused: 위 명령 — exit 0, `BUILD SUCCESSFUL`.
- P1 회귀: `./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.CreatorCommunityTranslationServiceTest' --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.CreatorCommunityTranslationServiceIntegrationTest'`
— exit 0, `BUILD SUCCESSFUL`.
- 호출자 회귀: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.home.application.CreatorChannelHomeQueryServiceTest'`
— exit 0, `BUILD SUCCESSFUL`.
#### Task 2.R: P2-T2 실제 상세 파이프라인 증거 보강
**Goal ID / objective:** `P2-R3` — 실제 Spring 프록시 상세 조회가 감지, 단일 작업 예약, 재료화와 유효 번역 재사용을 올바르게 연결한다.
- 시작 조건: `P2-T2` 완료, 상세 경로의 실제 transaction 증거 보강 요구 확인.
- 완료 증거: 원문 즉시 반환, 감지 후 요청 언어 하나의 job, 반복·동시 상세의 단일 job, memory 재료화 후 번역 반환,
유효 번역 상세의 예약 미호출을 확인한다.
- 범위 밖: 목록/홈, 외부 감지·번역 API, Docker, live HTTP, 실제 MySQL 검증.
| 작업 | 정확한 파일 경로 |
|---|---|
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/content/CreatorCommunityLanguageDetectTest.kt` |
| 확인 | `src/test/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/CreatorCommunityServiceTest.kt` |
| 확인 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/community/application/CreatorChannelCommunityQueryServiceTest.kt` |
- [x] **RED:** 병렬 상세 응답 본문 검증은 `ExecutorService.submit { ... }`가 `Runnable` 오버로드를 선택해
`Future.get()`이 `null`을 반환하며 실패하는 것을 확인한다. 이는 production 동작이 아닌 수용 테스트의 반환값 폐기 문제다.
- [x] **GREEN:** `Callable`을 명시해 두 병렬 상세의 실제 원문 반환과 translation job 1개를 검증한다.
- [x] **GREEN 확인:** 실제 `CreatorCommunityService`, `LanguageDetectListener`, `ResourceTranslationJobScheduler`,
`TranslationReadModelMaterializer` 경로에서 원문 즉시 반환, `ko` job 하나, memory 재료화 후 번역 반환을 확인한다.
legacy/v2 unit test는 유효 번역의 문자열이 원문과 같아도 `requestTranslations`를 호출하지 않음을 확인한다.
- [x] **REFACTOR:** P2 focused, P1 번역/감지 회귀, Phase 2 Gate를 실행한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.CreatorCommunityTranslationEndToEndTest' --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.CreatorCommunityServiceTest' --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.application.CreatorChannelCommunityQueryServiceTest' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.community.adapter.in.web.CreatorChannelCommunityEndToEndTest' --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.CreatorCommunityTranslationServiceTest' --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.CreatorCommunityTranslationServiceIntegrationTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.*'
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.*' --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.*' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.community.*' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.community.*'
```
#### P2-R3 검증 기록 — 2026-09-10
- RED: 병렬 lambda의 반환값을 확인하는 assertion은 `expected: [detail source content, detail source content] but was: [null, null]`로 실패했다.
`submit`의 `Runnable` 오버로드가 반환값을 폐기한 것이 원인이었고, production 상세 응답이나 DB 본문 손실은 아니었다.
- GREEN: `Callable` 명시 뒤 실제 두 상세 응답은 원문을 반환하고, 감지 완료 후 `ko` translation job은 하나만 유지됐다.
수동으로 저장한 translation memory를 실제 materializer가 적용한 뒤 상세는 번역문을 반환했다.
- 유효 저장 번역: legacy/v2 상세 unit test는 `CreatorCommunityDisplayContent.hasValidTranslation`으로 판정하므로,
번역문이 원문과 같아도 `requestTranslations`를 호출하지 않는다. 실제 상세 파이프라인 test는 재료화 뒤 번역문을 반환하고
job 수가 증가하지 않음을 확인했다.
- focused: 첫 번째 명령 — exit 0, `BUILD SUCCESSFUL` (41초).
- P1 회귀: 두 번째 명령 — exit 0, `BUILD SUCCESSFUL` (26초).
- Phase 2 Gate: 세 번째 명령 — exit 0, `BUILD SUCCESSFUL` (1분 30초).
- latch RED: `CreatorCommunityLanguageDetectTest.shouldNotCompleteNextTaskWhenPreviousTaskFinishesAfterLatchIsReassigned`에서 A를 멈춘 뒤 B가 다음 task의 latch를 준비하게 했다.
`./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest.shouldNotCompleteNextTaskWhenPreviousTaskFinishesAfterLatchIsReassigned'`는
exit 1, `expected: <false> but was: <true>`로 실패했다. A 종료가 `completion.get()`으로 B의 latch를 감소시킨 것이 원인이었다.
- latch GREEN: decorator 생성 시점의 `taskCompletion`을 캡처해 해당 task 종료에만 사용하도록 했고, latch regression과 상세 파이프라인 detector는 `finally`에서 release하도록 정리했다.
`./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest'` — exit 0, `BUILD SUCCESSFUL` (20초).
- P2 재회귀: 첫 번째 명령 — exit 0, `BUILD SUCCESSFUL` (44초).
- 형식: `./gradlew ktlintCheck` — exit 0, `BUILD SUCCESSFUL` (17초).
#### Phase 2 Gate
- [x] **Goal `P2-GATE`: 생성·수정·기존 글 상세 흐름 판정**
- 시작 조건: Phase 2 두 Task 완료.
- 완료 증거: 생성→커밋→감지→번역 저장과 기존 글 상세→요청 언어만 예약의 실제 통합 결과.
- 범위 밖: 목록/홈 구현. TDD 예외 사유: 앞선 Task의 사용자 흐름 검증 Gate다.
- 대체 검증: 테스트 HTTP 요청과 실제 커밋 후 DB 상태를 대조하고 롤백 케이스에 작업이 없는지 확인한다.
- 확인 파일: Phase 2의 두 EndToEndTest, 서비스 테스트, PRD §4~5.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.*' --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.*' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.community.*' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.community.*'
```
#### P2-GATE 검증 기록 — 2026-09-10
- gate: 위 명령 — exit 0, `BUILD SUCCESSFUL`. 생성·수정·기존 글 상세, 레거시 서비스/JPA 및 v2 MockMvc 계약, 관리자 공용 경로를 함께 확인했다.
- 형식: `./gradlew ktlintCheck` — exit 0, `BUILD SUCCESSFUL`.
- diff: `GIT_MASTER=1 git diff --check` — exit 0.
- 범위: local automatic 정책에 따라 Docker, live server/curl, 실제 Papago, 실제 MySQL DDL·동시성은 실행하지 않았다.
HTTP 동작은 자동 MockMvc 통합 테스트로만 검증했다.
### Phase 3: 목록·홈·미리보기 번역과 최종 검증
#### 구현 항목
- [x] **Task 3.1: 레거시 목록과 v2 커뮤니티·채널 홈에 저장 번역 적용**
**Goal ID / objective:** `P3-T1` — 커뮤니티 목록과 채널 홈이 작업 예약 없이 저장된 번역을 제공한다.
- 시작 조건: `P2-GATE` 완료.
- 완료 증거: 언어별 목록·최신 목록·고정/일반 채널 홈, 유료 마스킹, 추가 N+1 없음, 감지/작업 증가 0건.
- 범위 밖: 추천/팔로잉 소식, 정렬·페이지·고정 정책 변경.
- 소비 인터페이스: `findDisplayContents`만 호출. 레거시 DTO와 v2 레코드를 표시 직전에 복사해 기존 마스킹을 재사용한다.
| 작업 | 정확한 파일 경로 |
|---|---|
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/CreatorCommunityService.kt` |
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/community/application/CreatorChannelCommunityQueryService.kt` |
| 확인 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/home/application/CreatorChannelHomeQueryService.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/CreatorCommunityServiceTest.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/community/application/CreatorChannelCommunityQueryServiceTest.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/creator/channel/community/adapter/in/web/CreatorChannelCommunityEndToEndTest.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/creator/channel/home/CreatorChannelHomeEndToEndTest.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/CreatorCommunityTranslationEndToEndTest.kt` |
- [x] **RED:** 번역 존재/누락·이전 개정 혼합 페이지와 무료·유료·소유자·구매자 응답을 테스트한다.
이모지 포함 유료 본문에서 기존 코드포인트 기준 미리보기를 확인한다.
- [x] **RED 확인:** 아래 명령으로 번역 미사용 assertion 실패를 확인한다.
- [x] **GREEN:** 페이지별 번역 일괄 조회 후 기존 마스킹 전에 반영한다. 채널 홈은 이미 호출하는
`findHomeCommunityPosts` 공통 경로를 통해 고정/일반 게시물을 모두 처리한다.
- [x] **GREEN 확인:** 목록만 호출했을 때 감지 이벤트/번역 작업 생성 0건, 페이지·개수·순서 유지,
페이지 크기에 비례한 추가 번역 SELECT 증가 없음까지 확인한다.
- [x] **REFACTOR:** 기존 권한·홈 응답 회귀와 focused test 결과를 기록한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.*' --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.*' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.community.*' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.home.CreatorChannelHomeEndToEndTest'
```
##### 실행·검증 기록 — 2026-09-10
- 무엇을: 레거시 목록·최신 목록, v2 커뮤니티 탭, 채널 홈의 고정/일반 게시물에 저장된 표시 번역을 한 번에 조회해 본문에 복사했다.
상세 경로의 작업 예약 정책은 변경하지 않았고, 목록/홈에서는 `findDisplayContents`만 호출한다.
- 왜: 목록 응답은 번역 누락 시 원문으로 안전하게 폴백하면서도 감지·번역 작업을 만들지 않아야 한다.
- RED 확인: 새 테스트 6개를 대상으로 `./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.CreatorCommunityServiceTest.shouldUseStoredTranslationsOnceForLegacyCommunityListBeforePaidMasking' --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.CreatorCommunityServiceTest.shouldUseStoredTranslationsForVisibleLatestCommunityPostsWithoutScheduling' --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.application.CreatorChannelCommunityQueryServiceTest.shouldUseStoredTranslationsOnceForCommunityTabBeforePaidMasking' --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.application.CreatorChannelCommunityQueryServiceTest.shouldUseStoredTranslationsForPinnedAndNormalHomeCommunityPostsWithoutScheduling' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.community.adapter.in.web.CreatorChannelCommunityEndToEndTest.shouldUseStoredTranslationsForCommunityTabWithoutScheduling' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.home.CreatorChannelHomeEndToEndTest.shouldUseStoredTranslationsForPinnedAndNormalHomeCommunityPosts'`를 실행했다.
exit 1의 기대된 assertion 실패로 번역 적용 전 원문이 반환됨을 확인했다.
- GREEN/영향 범위 회귀: 위 focused 명령 — exit 0, `BUILD SUCCESSFUL` (1분 3초). 저장 번역·원문 폴백·이전 개정 무시,
유료 미구매자/구매자/소유자 마스킹, 차단 필터 후 일괄 조회, 목록/홈 호출의 감지·번역 작업 미생성을 단위·MockMvc 통합 테스트로 확인했다.
- 형식: `./gradlew ktlintCheck` — exit 0, `BUILD SUCCESSFUL` (45초).
- 전체 회귀와 수동 HTTP: 공통 번역 API 또는 모든 Phase를 변경하지 않았으므로 직접 영향받은 package/API 회귀까지만 실행했다.
운영과 분리된 DB·Redis·S3·Papago 및 테스트 계정이 준비되지 않아 live server/curl·실제 Papago 검증은 실행하지 않았고,
HTTP 응답은 MockMvc 통합 테스트로 검증했다.
- 추가 실제 통합 증거: `CreatorCommunityTranslationEndToEndTest`는 실제 `CreatorCommunityTranslationService`와 H2 저장소를 사용한다.
영속성 컨텍스트와 Hibernate 통계를 매 배치 전 초기화한 뒤 1개와 4개 ID를 각각 읽어, 게시글 `IN` 조회 1회와
`creator_community_translation` 조회 1회의 합계인 prepared statement 2회를 동일하게 확인했다.
따라서 페이지 크기는 번역 읽기 SELECT 수를 늘리지 않는다.
- 추가 부작용 증거: 같은 실제 읽기 서비스를 레거시 목록의 번역 누락 게시물에 연결하고, 실제 `translation_job` 행 수의 전후 동일성과
`ApplicationEventPublisher`·재료화기·resource scheduler의 무상호작용을 확인했다. 읽기 서비스 자체는 mock으로 대체하지 않았다.
v2 탭의 mock 경계 테스트는 별도로 반환 50개 ID만 전달하고 51번째 `fetchLimit + 1` ID를 제외함을 확인한다.
- TDD 예외: 이번 추가는 이미 올바른 production 동작을 직접 측정하는 증거 테스트뿐이므로 RED assertion을 만들 수 없었다.
새 테스트는 즉시 통과했으며 production P3-T1 파일은 변경하지 않았다.
- 재검증: `./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.*' --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.*' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.community.*' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.home.CreatorChannelHomeEndToEndTest'` — exit 0, `BUILD SUCCESSFUL` (1분 18초).
`./gradlew ktlintCheck` — exit 0, `BUILD SUCCESSFUL` (17초).
- [x] **Task 3.2: 홈 추천과 팔로잉 소식 본문에 저장 번역 적용**
**Goal ID / objective:** `P3-T2` — 홈 추천·팔로잉 소식의 커뮤니티 본문과 파생 미리보기가 요청 언어로 표시된다.
- 시작 조건: `P3-T1` 완료.
- 완료 증거: 두 API의 번역/원문 폴백·일괄 조회·작업 미생성·다른 소식 유형 불변 테스트.
- 범위 밖: 추천 스냅샷/순위 변경, FCM·알림 이력·오디오 소식 번역.
- 소비 인터페이스: `LangContext`의 언어와 `findDisplayContents`. 추천 상세 레코드/팔로잉 도메인의 커뮤니티 항목만 복사한다.
| 작업 | 정확한 파일 경로 |
|---|---|
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/application/HomeRecommendationQueryService.kt` |
| 수정 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/home/following/application/HomeFollowingQueryService.kt` |
| 확인 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt` |
| 확인 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/home/following/adapter/out/persistence/DefaultHomeFollowingQueryRepository.kt` |
| 확인 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/home/following/domain/HomeFollowing.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/recommendation/application/HomeRecommendationQueryServiceTest.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/home/following/application/HomeFollowingQueryServiceTest.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/HomeRecommendationControllerTest.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacadeTest.kt` |
| 수정 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/following/adapter/in/web/HomeFollowingEndToEndTest.kt` |
- [x] **RED:** 일본어·영어 요청의 인기 커뮤니티/팔로잉 소식, 누락·이전 개정 폴백,
비커뮤니티 항목 유지, 조회만으로 작업이 늘지 않는 테스트를 작성한다.
- [x] **RED 확인:** 아래 focused 명령으로 해당 응답이 원문에 머무르는 assertion 실패를 확인한다.
- [x] **GREEN:** 이미 필터링된 게시물 ID를 모아 공유 읽기 메서드로 처리한다. 팔로잉 서비스에 기존 `LangContext`를 전달한다.
본문은 DB 게시물의 현재 내용에서 가져오므로 과거 소식 발행 문자열을 번역 소스로 쓰지 않는다.
- [x] **GREEN 확인:** 언어 전환·익명 허용 추천·인증된 팔로잉 흐름을 검증하고 기존 필터/추천 순서를 대조한다.
- [x] **REFACTOR:** 변경된 생성자 호출 테스트를 갱신하고 두 기능의 직접 영향 회귀 결과를 기록한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.recommendation.application.HomeRecommendationQueryServiceTest' --tests 'kr.co.vividnext.sodalive.v2.home.following.application.HomeFollowingQueryServiceTest' --tests 'kr.co.vividnext.sodalive.v2.api.home.HomeRecommendationControllerTest' --tests 'kr.co.vividnext.sodalive.v2.api.home.following.adapter.in.web.HomeFollowingEndToEndTest'
```
##### 실행·검증 기록 — 2026-09-10
- 무엇을: 인기 커뮤니티 추천의 최종 노출 게시물과 팔로잉 최근 소식의 커뮤니티 게시물만 요청 언어의 저장 본문으로 복사했다.
추천 중복 제거·limit와 팔로잉 필터·순서·다른 소식 유형은 변경하지 않았다.
- RED 확인: 서비스·API 테스트 4개가 번역 연결 전 원문 본문 assertion으로 실패함을 확인했다.
- GREEN/회귀: 관련 5개 테스트 클래스에 `--rerun-tasks`를 적용해 exit 0, `BUILD SUCCESSFUL` (2분 38초)을 확인했다.
일본어 비회원 추천, 영어 인증 팔로잉, 현재 원문 폴백, 최종 ID 단일 배치, 비커뮤니티 불변을 검증했다.
- 리뷰: 명세 리뷰 `APPROVED` (`ses_f7757315dffeoDl3Ef2bhCO684`), 품질 리뷰 `APPROVED` (`ses_f774b8bf4ffehbjDvQWo6yE84S`).
- 형식/diff: `./gradlew ktlintCheck --rerun-tasks` — exit 0, `BUILD SUCCESSFUL` (26초).
`GIT_MASTER=1 git diff --check` — exit 0.
- 범위: Docker, live HTTP, 실제 Papago/MySQL은 실행하지 않았으며 테스트 브랜치 배포 후 수동 체크리스트에서 확인한다.
#### Task P3-R1: DDL 해시 컬럼 타입 정합화
- [x] **Goal `P3-R1`: `source_hash` DDL을 Hibernate 엔티티 매핑과 일치시킨다**
- 시작 조건: `P3-GATE` 코드 품질 리뷰에서 `CHAR(64)`와 `VARCHAR(64)` 불일치가 차단 이슈로 확정됨.
- 완료 증거: `schema.sql`의 `source_hash VARCHAR(64)` 확인, `./gradlew tasks --all`, `git diff --check`, 해당 delta 코드 품질 재검토 통과.
- 범위 밖: 엔티티 매핑 변경, 실제 MySQL DDL 적용, 비차단 로그·테스트 종료 개선.
- RED: `rg -n 'source_hash VARCHAR\(64\)' schema.sql`이 일치 항목 없이 실패하는지 확인한다.
- GREEN: DDL 한 줄만 `VARCHAR(64)`로 변경하고 동일 명령이 성공하는지 확인한다.
- REFACTOR: 추가 구조 변경 없이 문서 상태와 Gate 증거만 동기화한다.
- 수정 파일: `docs/20260910_크리에이터커뮤니티게시물본문번역/schema.sql`, `prd.md`, `plan-task.md`.
##### 실행·검증 기록 — 2026-09-10
- RED: `rg -n 'source_hash VARCHAR\(64\)' schema.sql` — 일치 항목 없이 exit 1.
- GREEN: `source_hash`를 엔티티의 `String` + `@Column(length = 64)`와 같은 `VARCHAR(64)`로 변경했고 동일 `rg`가 11행을 반환했다.
- 회귀: `./gradlew tasks --all` — exit 0, `BUILD SUCCESSFUL`; `GIT_MASTER=1 git diff --check` — exit 0.
- delta 품질 재검토: `PASS` (`ses_f772f064cffeKa532hsf1Pa3GU`). 실제 MySQL 적용과 `ddl-auto: validate` 기동 확인은 수동 검증에 유지한다.
#### Phase 3 Gate
- [x] **Goal `P3-GATE`: 전체 노출 표면과 비동기 정합성 최종 판정**
- 시작 조건: `P3-T1`, `P3-T2` 및 이전 Gate의 증거 완료.
- 완료 증거: 아래 자동 검증, PRD `CCT-001~010` 대조 및 5개 리뷰 레인 통과. HTTP·실제 MySQL/Papago는 배포 후 수동 체크리스트로 분리한다.
- 범위 밖: 테스트 삭제/완화, 운영 데이터 번역/배포, 다른 기능의 결함 수정.
- TDD 예외 사유: 기능 추가가 아닌 전체 수용 기준 검증 Gate다.
- 대체 검증: 자동 회귀, 격리된 실행 서버의 HTTP 응답/DB 작업 수 대조, 문서와 실제 동작 대조.
- 확인 파일: 모든 Task의 변경 파일, `prd.md`, `plan-task.md`, `schema.sql`.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.i18n.translation.*' --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.*' --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.*' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.community.*' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.home.*' --tests 'kr.co.vividnext.sodalive.v2.recommendation.*' --tests 'kr.co.vividnext.sodalive.v2.home.following.*' --tests 'kr.co.vividnext.sodalive.v2.api.home.*' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.community.*'
./gradlew ktlintCheck
./gradlew bootJar
```
기본 최종 검증은 위 직접 영향 범위다. 이번 변경이 공통 번역 API의 기존 리소스 동작까지 바꾸거나,
위 범위로 판정할 수 없는 실패가 발견되거나, 사용자/릴리스 기준이 전체 검증을 요구하면 `./gradlew test`를 추가한다.
전체 테스트 생략 시 공통 번역 및 영향받은 각 기능을 위 명령으로 검증했다는 근거와 실제 결과를 기록한다.
##### 최종 Gate 기록 — 2026-09-10
- 직접 영향 테스트 — clean 후 `--no-parallel` 순차 실행, exit 0, `BUILD SUCCESSFUL` (5분 20초). 53개 클래스 493개 테스트, 실패·오류·skip 0을 XML에서 확인했다.
- `./gradlew ktlintCheck` — exit 0, `BUILD SUCCESSFUL` (20초). `./gradlew bootJar` — exit 0, `BUILD SUCCESSFUL` (1분 31초).
- `GIT_MASTER=1 git diff --check` — exit 0. 최초 병렬 Gradle의 kapt 출력 경합은 clean 후 순차 성공으로 대체했다.
- 최종 리뷰: 목표·제약 PASS, 자동 QA PASS, 보안 PASS, 문맥 PASS. 코드 품질의 DDL 타입 차단 이슈는 `P3-R1`로 수정 후 delta 재검토 PASS.
- 비차단 관찰: 번역 예약 실패 로그 분류, 일부 경합 테스트 executor 종료 확인, 언어 감지 완료 전 반복 상세 요청의 호출 증폭은 이번 범위에서 변경하지 않았다.
- 간접 소비자: `LiveApiService`, `ExplorerService`도 기존 목록 서비스를 통해 저장 번역을 사용하며 추가 예약은 하지 않는다.
- 로컬 자동 Gate는 완료했다. 실제 DDL·MySQL 격리 수준·HTTP·Papago 검증은 아래 테스트 서버 수동 체크리스트에서 미완료로 유지한다.
### 테스트 브랜치 배포 후 수동 체크리스트
수동 HTTP 검증은 운영과 분리된 DB·Redis·S3/Papago 설정 및 테스트 계정이 준비된 테스트 서버에서 실행한다.
기존 `./gradlew bootRun`을 사용하며 토큰·키·본문 전문은 기록물에서 제거한다.
1. `schema.sql`을 테스트 DB에 적용한다. 기존 행은 `language_code` NULL, `content_revision` 0, 원문이 유지되고,
`creator_community_id + locale` 유일 키가 생성됐는지 확인한다.
2. 같은 게시물·locale의 번역 요청을 동시에 보낸다. duplicate-key 오류나 API 실패 없이, 현재 원문과 일치하는 번역 행이 정확히 1개인지 확인한다.
3. 언어 NULL인 기존 무료 게시물로 PRD §5의 모든 목록/홈 API를 조회한다. 원문 표시, 감지/번역 작업 증가 0건을 확인한다.
4. 같은 글을 `Accept-Language: ja`로 상세 조회한다. 최초 원문 응답, 감지 후 일본어 작업만 예약,
워커 완료 후 상세/목록/채널 홈/추천/팔로잉에서 저장 번역 사용을 확인한다.
5. 한·영·일 원문의 신규 게시물과 실제 본문 수정을 실행한다. 다른 두 언어 생성,
수정 직후 현재 원문 폴백, 지연된 이전 감지/번역 결과 미노출, A→B→A 메모리 복원을 확인한다.
6. 유료 글을 미구매자/구매자/소유자로 조회하고 번역 선택 후 기존 마스킹이 적용되는지 확인한다.
차단·성인·비활성·댓글/답글 노출과 미디어 URL 규칙은 기존 결과와 대조한다.
7. 감지/번역 provider 실패와 반복 상세 요청을 재현한다. 원문 응답, 기존 재시도 정책, 작업 중복 방지,
페이지 크기 증가 시 추가 번역 조회 수가 선형으로 늘지 않음을 확인한다.
#### P1-R4 실제 MySQL 수동 확인 · 2026-09-10 추가
- [ ] 테스트 서버가 실제 MySQL 8/InnoDB인지 확인하고 버전·테이블 엔진·세션 격리 수준을 기록한다.
감지 캐시의 해시/provider/normalizationVersion 유일 키와 audit 컬럼의 타입·NULL/default 조건을 확인한다.
native INSERT 후 생성/수정 시각이 채워지고 중복 upsert가 승자 감지값과 생성 시각을 덮어쓰지 않는지 대조한다.
- [ ] 언어 NULL이고 해당 캐시 키가 없는 동일 한국어 게시물에 `ja`/`en` 상세 요청을 보낸다.
테스트용 provider 제어로 두 miss와 provider 진입을 확인한 뒤 첫 감지 저장·커밋·`ja` 예약을 완료하고
후발 감지를 해제한다. 실제 `REPEATABLE READ`에서 예외/rollback 없이 두 흐름이 끝나고 캐시 1행,
`ja`/`en` 작업이 모두 남는지 확인한다. 단순 동시 HTTP 요청만으로 이 실행 순서를 증명했다고 보지 않는다.
- [ ] 서로 다른 게시물을 동일 본문으로 생성하고 캐시 miss 두 건의 저장 순서를 같은 방식으로 제어한다.
공통 캐시 1행과 승자 결과 재사용, 각 게시물의 원문 외 두 언어 작업 보존을 확인한다.
- [ ] provider 감지 응답을 차단한 동안 별도 연결에서 해당 게시물 본문 수정을 커밋할 수 있는지 확인한다.
수정 후 개정 증가·언어 초기화와 현재 원문 폴백을 확인하고 이전 감지를 해제한다. 오래된 결과가
새 본문·개정·언어·번역을 덮어쓰거나 이전 원문의 작업을 새 개정에 적용하지 않는지 확인한다.
필요한 테스트 환경이 없으면 수동 검증은 미완료로 기록한다. MockMvc/provider 대체 테스트를 실제 Papago 검증으로 표기하지 않는다.
실제 Papago 확인은 비민감한 테스트 문장을 사용하며 수동 검증 환경에서만 수행한다.
## Progress와 검증 기록
### 문서 작성 — 2026-09-10
- 상태: PRD·구현 계획 작성. 구현 Task/Gate는 모두 미실행.
- 무엇을: 사용자 인터뷰 결정과 레거시/v2 생성·상세·목록·홈 경로를 이 계획의 6개 Task에 연결했다.
- 왜: 구현 전 모호한 범위를 없애고 정확한 변경 위치·수용 기준·TDD 순서를 제공하기 위해서다.
- 실행 확인: `./gradlew tasks --all` — exit 0, `BUILD SUCCESSFUL`. `test`, `bootRun`, `bootJar`, `ktlintCheck` task를 확인했다.
- 관찰: 기존 Gradle 설정에서 Gradle 9.0 비호환 예정 deprecation 안내가 출력됐다. 이번 문서 범위에서 변경하지 않는다.
- 미실행: 코드 구현, 신규 테스트 작성/실행, 서버 실행, Papago 호출, DDL 작성/적용, 운영 작업.
- 테스트 생략 근거: 제품 코드를 변경하지 않는 문서 작업이다. 미래 테스트 명령을 계획에 적은 것은 테스트 통과 증거가 아니다.
- 남은 실행 조건: 사용자의 별도 구현 요청과 각 Task의 검증 환경 확보.
### 문서 검증 — 2026-09-10
- `./gradlew tasks --all` — 문서 생성 후 재실행, exit 0, `BUILD SUCCESSFUL`.
- 문서 경로·링크·템플릿 잔여값·공백 검사 — exit 0, `Document validation: PASS`.
기존 파일 참조가 존재하며 미래 생성 파일 7개는 생성 항목으로 구분했다.
- 요구사항/계획 대조 — 요구사항 10개, 구현 Task 6개, Gate 3개가 연결되어 있고 구현 완료 체크는 없다.
- `git diff --check` — exit 0. 신규 미추적 문서의 공백은 별도 문서 검사로 확인했다.
- `git -c core.quotePath=false status --short --untracked-files=all` — 이 작업 폴더의 `prd.md`, `plan-task.md` 두 파일만 추가됨을 확인했다.
### P2-R3 최종 검증 — 2026-09-10
- `./gradlew tasks --all` — exit 0, `BUILD SUCCESSFUL`; `test`, `ktlintCheck`, `build` task가 유효함을 확인했다.
- `./gradlew ktlintCheck` — exit 0, `BUILD SUCCESSFUL`. P2 변경 테스트의 import 순서와 `Callable` 호출 줄바꿈을 정정했다.
- `./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest.shouldRunDetailTranslationPipelineThroughProxyListenerAndScheduler'`
— exit 0, `BUILD SUCCESSFUL`. 실제 Spring 상세 파이프라인에서 원문 즉시 반환, 단일 job, 재료화 후 번역 반환을 확인했다.
- `./gradlew build` — exit 0, `BUILD SUCCESSFUL` (8분 16초). 컴파일, 전체 테스트, ktlint, 패키징을 포함한다.
- `GIT_MASTER=1 git diff --check` — exit 0. Docker, live HTTP, 실제 Papago, 실제 MySQL 검증은 실행하지 않았다.
### Phase별 후속 정적 리뷰 — 2026-09-10
- 기준: 인터뷰를 반영한 `prd.md`와 이 계획, 현재 source/test/DDL. HEAD와 작업 트리 지문은
[리뷰 증거](reviews/review-evidence.md)에 기록했다.
- Phase 1: 감지 캐시 최초 INSERT 경합으로 후발 target 예약이 누락되는 정적 경로 1건 확정.
`REV-P1-007`을 신규 `P1-R4`로 추가했다. 기존 완료 기록과 이전 리뷰는 유지했다.
- Phase 2: 생성·실제 본문 수정·상세 단일 언어 예약·권한/마스킹 기준 충족. 자체 추가 수정 사항 없음.
Phase 1 결함의 상세 영향은 `P1-R4`에서 처리한다.
- Phase 3: 목록·채널 홈·추천·팔로잉 저장 번역 및 비예약 기준 충족. 신규 Task 없음.
- 실행 제약: 사용자 요청대로 테스트·컴파일·서버·HTTP·Papago·DB 재현은 실행하지 않았다.
기존 XML 성공 기록은 과거 실행 증거로만 읽었다.
- 검증 한계: 실제 캐시 저장 경합은 새 Task의 RED로 재현할 예정이다. 한·영·일 전체 생성→워커 통합 검증과
실제 MySQL/Papago/HTTP는 기존 테스트 서버 수동 확인 범위로 남겼다. 구성요소 테스트 통과를 실환경 전체 흐름 통과로 확대하지 않는다.
- 문서 검증: `./gradlew tasks --all` — exit 0(task 목록 조회만 수행, 테스트·컴파일 미실행).
`git diff --check`와 문서 링크/공백 검사 통과. 리뷰 전후 source/test/DDL 32개 파일 지문이 같음을 확인했다.
### P1-R4 문서 동기화 · 2026-09-10
- 완료된 RED/GREEN·P1/P2 영향 회귀·spec/quality 리뷰를 P1-R4 실행 기록과 리뷰 문서 두 곳에 누적했다.
기존 정적 리뷰 지문과 과거 기록은 당시 증거로 보존하며 실제 MySQL 수동 확인 네 항목은 미완료로 추가했다.
- 문서 검증: `./gradlew tasks --all`, exit 0, `BUILD SUCCESSFUL` (2초). `test`, `ktlintCheck` task를 확인했다.
`rg`로 P1-R4 Goal 및 RED/GREEN/REFACTOR 완료 체크, 실행 시간·리뷰 출처·실환경 검증 보류 표기를 대조했다.
- 이번 작업은 지정된 계획·리뷰 문서 3개만 수정했다. PRD·source·test·schema 변경이나 제품 테스트 재실행은 하지 않았다.
## 변경 관리
기술 선택은 PRD `DEC-009~010`, 제품 결정은 `DEC-001~008`을 따른다.
후속 요구사항은 PRD 결정 기록 → 요구사항/API 계약 → 이 계획의 파일·검증·체크박스 순서로 갱신한다.
미래 구현에서는 각 Task 아래에 실행일·무엇/왜/어떻게·정확한 명령·결과·남은 항목을 누적한다.
새 테스트 클래스를 만들 때는 이 문서의 focused 실행 예시가 실제 클래스와 일치하는지도 갱신한다.
@@ -1,176 +0,0 @@
# 크리에이터 커뮤니티 게시물 본문 번역 PRD
## 문서 정보
| 항목 | 내용 |
|---|---|
| 상태 | 구현 및 로컬 자동 검증 완료 · 테스트 서버 수동 검증 대기 |
| 작성일 / 최종 수정일 | 2026-09-10 |
| 결정권자 | 요청 사용자 |
| 산출물 범위 | 코드·자동 테스트·MySQL DDL 작성. 실제 DDL 적용·배포·Papago/HTTP 검증은 테스트 서버에서 수행한다. |
| API 계약 | 별도 파일을 만들지 않고 이 문서의 API 계약 절에 통합 |
| 기준 템플릿 | `docs/sample/sample-prd.md` |
## 1. 목표와 현재 동작
크리에이터 커뮤니티 게시물의 본문을 한국어·영어·일본어로 제공한다. 작성한 원문은 보존하고,
원문 이외의 지원 언어 번역을 저장한다. 이용자는 요청 언어에 맞는 본문을 상세·목록·미리보기에서 읽는다.
현재 코드에서 확인한 사실:
| 근거 파일 | 확인한 동작 |
|---|---|
| `src/main/kotlin/kr/co/vividnext/sodalive/explorer/profile/creatorCommunity/CreatorCommunity.kt` | 원문 `content`는 있으나 원문 언어와 번역 저장 구조는 없다. |
| `src/main/kotlin/kr/co/vividnext/sodalive/content/AudioContentService.kt` | 상세 조회에서 요청 언어의 번역을 조회한다. 번역이 없으면 해당 언어 작업을 예약하고 원문 응답을 유지한다. 원문 언어가 없는 경우에는 이 예약 분기에 들어가지 않는다. |
| `src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectEvent.kt` | 커밋 후 비동기 언어 감지, 언어 저장, 번역 이벤트 발행 흐름이 있다. |
| `src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/ResourceTranslationJobScheduler.kt` | 리소스의 원문 언어를 제외한 지원 언어 전체 또는 지정한 한 언어의 작업을 예약한다. |
| `src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationJobScheduler.kt` | 원문 언어가 `ko`, `en`, `ja`인 비어 있지 않은 텍스트만 예약한다. 동일 리소스·필드·목표 언어·원문 해시 작업은 중복 생성하지 않는다. |
| `src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationJobWorker.kt` | 저장된 작업을 처리하고 번역 메모리와 조회용 번역을 저장한다. 주기 기본값은 600000ms이며 실제 환경 설정에 따라 달라진다. |
이번 기능은 오디오 상세의 누락 번역 예약 방식을 따른다. 다만 기존 커뮤니티 게시물은 언어 정보 자체가 없으므로,
상세 조회에서 비동기 언어 감지까지 연결해야 한다. 오디오 상세가 현재 언어 미확정 데이터도 감지한다고 가정하지 않는다.
## 2. 포함 범위와 제외 범위
### 포함
- 본문 `content`만 번역하며 무료·유료 게시물에 같은 언어 정책을 적용한다.
- 신규 게시물 저장 후 자동 감지·번역, 실제 본문 변경 후 언어 재감지·번역 갱신.
- 기존 게시물은 상세 조회를 계기로 필요한 언어를 감지하고 요청 언어의 누락 번역을 예약한다.
- 기존 커뮤니티 API와 v2 상세·목록, 채널 홈의 고정/일반 게시물, 홈 추천 인기 커뮤니티, 팔로잉 소식의 본문·미리보기.
- 공유 생성·수정 서비스를 사용하는 AI 캐릭터 관리자 작성 경로도 같은 저장 처리를 적용한다.
이는 별도 관리자 기능 추가가 아니라 동일 게시물의 생성·수정 누락 방지다.
### 제외
- 댓글·답글·첫 댓글, 이미지 내부 문자, 첨부 오디오 음성의 번역.
- 기존 게시물 일괄 번역, 목록·홈·미리보기·댓글 조회에서 언어 감지 또는 번역 작업 예약.
- 번역 수동 편집·언어 선택 입력·원문 보기 토글·번역 상태 API·실시간 완료 알림.
- 푸시 알림 문구·알림 이력의 번역, 정산 화면과 관리자 편집용 원문 응답 변경.
- 공통 언어 지원 범위, 다른 콘텐츠의 수정 정책, 추천 순위/스냅샷 생성 방식의 변경.
## 3. 확정 요구사항
| ID | 요구사항 | 수용 기준 | 연결 Goal |
|---|---|---|---|
| `CCT-001` | 원문을 보존하고 본문만 지원 언어로 번역해 저장한다. | 한국어·영어·일본어 각각을 원문으로 작성하면 다른 두 언어의 본문 번역이 저장되고 원문은 유지된다. 댓글과 첨부 파일은 바뀌지 않는다. | `P1-T1`, `P1-T2`, `P2-T1` |
| `CCT-002` | 원문 언어가 없으면 본문으로 자동 감지한다. | 요청자의 앱 언어를 원문 언어로 추정하지 않는다. 감지 결과를 저장하고 번역으로 이어진다. | `P1-T2` |
| `CCT-003` | 신규 게시물은 저장 성공 후 원문 이외의 지원 언어 번역을 예약한다. | 저장 롤백에는 감지/번역이 실행되지 않는다. 저장 응답이 외부 번역 완료를 기다리지 않는다. | `P2-T1` |
| `CCT-004` | 실제 본문 수정 시 언어를 다시 감지하고 번역을 갱신한다. | 한국어에서 영어로 변경해도 새 언어와 새 본문으로 처리한다. 동일 본문 제출·이미지·고정·댓글 허용 여부만 변경하면 재번역하지 않는다. | `P2-T1` |
| `CCT-005` | 기존 게시물은 상세 조회에서만 누락 번역을 예약한다. | 번역 미완료 상세는 원문을 반환한다. 원문 언어가 없으면 감지 후 해당 상세 요청 언어만 예약한다. 언어가 같으면 번역 작업은 없다. | `P2-T2` |
| `CCT-006` | 상세·목록·미리보기에서 저장된 유효한 번역을 사용한다. | 레거시 목록/최신 목록, v2 커뮤니티 목록, 채널 홈, 홈 추천, 팔로잉 소식에 같은 언어의 저장 번역이 적용된다. 목록 계열만 조회하면 감지/번역 작업은 0건이다. | `P2-T2`, `P3-T1`, `P3-T2` |
| `CCT-007` | 번역이 없거나 실패했거나 현재 본문에 맞지 않으면 현재 원문을 제공한다. | 수정 커밋 후 새로 시작한 요청에서는 수정 전 번역을 반환하지 않는다. 늦게 도착한 이전 감지/번역 결과도 새 본문을 덮어쓰지 않는다. | `P1-T1`, `P1-T2`, `P2-T1`, `P3-GATE` |
| `CCT-008` | 기존 조회 권한과 유료 본문 제한을 번역문에도 적용한다. | 차단·성인·비활성 필터와 구매/소유자 판정은 유지한다. 번역문을 선택한 다음 기존 미리보기 제한을 적용해 미구매자에게 전체 본문이 노출되지 않는다. | `P2-T2`, `P3-T1`, `P3-T2` |
| `CCT-009` | 기존 API 구조와 언어 결정 방식을 유지한다. | `Accept-Language`를 처리하는 `LangContext`를 사용한다. 응답 본문 문자열의 언어만 달라지고 필드·상태 코드·인증·페이지 규칙은 유지한다. | `P2-T2`, `P3-T1`, `P3-T2` |
| `CCT-010` | 기존 감지 캐시·번역 메모리·큐·워커를 재사용한다. | 반복 상세 조회나 이전 본문으로의 복원에서 불필요한 번역 호출을 만들지 않는다. 목록 번역 조회는 게시물별 쿼리 대신 일괄 조회한다. | `P1-T1`, `P1-T2`, `P3-GATE` |
## 4. 처리 흐름
### 4.1 신규 작성과 본문 수정
1. 기존 검증·소유권 확인을 거쳐 원문을 저장한다. 본문 변경 시 이전 언어를 비우고 본문 개정 번호를 증가시킨다.
2. 저장 트랜잭션 커밋 후 해당 본문의 언어를 비동기로 감지한다. 원문 정보가 이미 있으면 감지를 생략한다.
3. 감지 결과가 현재 본문의 결과임을 확인하고 원문 언어를 저장한다.
4. 지원 언어 중 원문을 제외한 언어를 예약한다. 기존 메모리를 재사용할 수 있으면 조회용 번역을 복원한다.
5. 워커가 완료하면 다음 조회부터 번역문을 제공한다. 완료 전에는 현재 원문을 제공한다.
### 4.2 기존 게시물 상세 조회
1. 기존 접근 권한과 노출 정책을 확인한다.
2. 요청 언어의 현재 본문에 대응하는 번역이 있으면 사용한다.
3. 번역이 없으면 원문 응답을 유지하고 누락 처리만 예약한다. 언어 미확정이면 감지 요청에 상세 요청 언어를 전달한다.
4. 감지 후 원문과 요청 언어가 다를 때 해당 언어만 예약한다. 신규 작성의 전체 언어 예약과 구분한다.
5. 외부 감지/번역은 HTTP 응답을 기다리게 하지 않는다. 다음 조회부터 완성된 번역을 사용한다.
### 4.3 목록·홈·미리보기
권한 필터와 페이지 선정 → 페이지 내 게시물의 유효한 번역 일괄 조회 → 번역 또는 현재 원문 선택 →
기존 유료 미리보기·표시 규칙 적용 순서로 처리한다. 이 경로는 언어 감지, 메모리에서 조회 모델 재생성,
번역 작업 예약을 하지 않는다. 저장된 번역이 없는 기존 게시물은 상세 조회 또는 본문 수정 전까지 원문으로 남는다.
## 5. API 계약과 조회 표면
공개 필드는 추가하지 않는다. `content`와 여기서 파생되는 게시물 미리보기 문자열을 요청 언어로 반환한다.
언어는 `LangInterceptor` → `Lang.fromAcceptLanguage` → `LangContext`를 그대로 사용한다.
지원 언어는 `ko`, `en`, `ja`이고 헤더 누락/미지원 언어 처리는 기존 한국어 기본값을 유지한다.
자동 번역문을 원문 `CreatorCommunity.content`에 덮어쓰지 않는다.
| API | 대상 | 누락 처리 예약 |
|---|---|---|
| `POST /creator-community`, `PUT /creator-community` | 신규 작성·실제 본문 수정 후 처리. multipart 계약 유지 | 커밋 후 전체 목표 언어 |
| `GET /creator-community/{id}` | 레거시 상세 `content` | 요청 언어만 |
| `GET /creator-community`, `GET /creator-community/latest` | 레거시 목록·팔로우 최신 목록 `content` | 없음 |
| `GET /api/v2/creator-channels/community-posts/{postId}` | v2 상세 게시물 `content` | 요청 언어만 |
| `GET /api/v2/creator-channels/{creatorId}/community` | 커뮤니티 탭 게시물 `content` | 없음 |
| `GET /api/v2/creator-channels/{creatorId}/home` | 고정/일반 커뮤니티 항목 `content` | 없음 |
| `GET /api/v2/home/recommendations` | 인기 커뮤니티 항목 본문·파생 미리보기 | 없음 |
| `GET /api/v2/home/following` | `recentNews`의 커뮤니티 게시물 본문 | 없음 |
관리자 게시물 조회는 편집 원문을 유지한다. 같은 작성 서비스를 호출하는 관리자 생성·수정은 `CCT-003~004`를 따른다.
댓글 전용 조회와 구매 응답은 번역 예약 진입점으로 추가하지 않는다.
## 6. 데이터·비동기 정합성 설계 기준
다음 기술 설계는 현재 구현과 DDL에 반영됐다. 실제 MySQL 적용 여부는 테스트 서버 수동 검증에서 확인한다.
| 저장 대상 | 계획 |
|---|---|
| `creator_community` | nullable `language_code`, 본문 변경에만 증가하는 `content_revision`을 추가한다. 기존 행은 언어 NULL, 개정 번호 0으로 시작한다. |
| `creator_community_translation` | 게시물 ID, locale, 번역 본문, 번역 기준 개정 번호, 원문 해시·언어를 저장한다. `(creator_community_id, locale)` 유일성을 보장한다. |
| 공통 감지/번역 저장소 | 기존 감지 캐시와 번역 메모리의 정규화·키, `translation_job` 처리 흐름을 유지한다. 커뮤니티 대상 enum과 원문 추출/조회 모델 저장 분기를 추가한다. |
- 감지 이벤트에 본문 개정 번호와 필요한 경우 목표 언어를 전달한다. 본문이 변경되었거나 비활성화되면 이전 결과를 적용하지 않는다.
- 번역문은 현재 본문의 개정 번호·원문 언어가 일치할 때만 조회한다. 오래된 작업의 결과에 현재 개정 번호를 임의로 붙이지 않는다.
- 감지 결과 저장과 번역 upsert의 개정 확인은 DB 갱신과 원자적으로 처리한다. 외부 API 호출 동안 행 잠금을 유지하지 않는다.
- `updatedAt`은 고정·이미지 등 수정에도 변하므로 본문 개정 판단에 사용하지 않는다.
- 원문 A → B → A 복원 시 기존 COMPLETED 작업 때문에 번역이 영구 누락되지 않도록 현재 메모리로 조회 모델을 먼저 복원한다.
- 기존 정규화는 공백·개행을 합친다. 원문 표시의 개행은 원문 그대로 보존하고, 번역 결과는 기존 번역기의 출력 정책을 따른다.
## 7. 예외·권한·성능
| 상황 | 처리 |
|---|---|
| 빈 본문 또는 공백만 있는 본문 | 기존 저장 검증은 바꾸지 않는다. 감지·번역은 생략하고 원문을 반환한다. |
| 감지 실패 또는 지원하지 않는 원문 언어 | 원문 유지. 지원하지 않는 언어의 번역 작업은 기존 scheduler 정책에 따라 생성하지 않는다. 언어 미확정 게시물의 다음 상세에서 감지를 다시 시도할 수 있다. |
| 번역 실패 | 원문 유지. 기존 워커의 재시도/최종 FAILED 정책을 재사용한다. 반복 상세 조회가 최종 실패 작업을 무한 재생성하지 않는다. |
| 번역 도중 본문 변경·비활성화 | 오래된 결과를 현재 게시물의 번역으로 노출하지 않는다. 삭제/비활성 게시물은 기존 조회 정책대로 숨긴다. |
| 유료 게시물 미구매 | 선택된 번역 또는 원문에 기존 코드포인트 기준 제한을 적용한다. 기존 15자 기준·짧은 본문 절반·말줄임 처리는 유지한다. |
| 목록에 여러 게시물 | 페이지 단위 번역 일괄 조회. 기존 정렬·개수·페이지·추천 후보를 변경하지 않고 추가 N+1을 만들지 않는다. |
외부 감지/번역 실패는 작성·조회 성공을 번역 완료 여부에 종속시키지 않는다. 인증 실패나 DB 장애까지 성공으로 숨기지는 않는다.
본문·자격증명·유료 콘텐츠 전문을 새 로그에 남기지 않는다. 기존 감지/번역 저장소의 텍스트 저장 정책은 재사용한다.
번역 완료 시간 SLA나 워커 주기 조정은 이번 요청에 포함하지 않는다.
## 8. 성공 기준과 추적성
| 수용 시나리오 | 완료 증거 |
|---|---|
| 한·영·일 원문으로 신규 작성 후 다른 두 언어 제공 | `P2-GATE`의 생성→감지→작업→저장 통합 검증 |
| 언어 없는 기존 글: 목록은 원문/작업 0건, 상세는 원문/감지 후 요청 언어 예약 | `P2-T2` 통합 테스트와 배포 후 수동 HTTP 검증 |
| 한국어 본문을 영어로 수정하고 이전 비동기 작업을 늦게 완료 | 현재 원문 폴백과 오래된 결과 차단 테스트 |
| 상세 번역 저장 후 목록·채널 홈·추천·팔로잉 모두 요청 언어 제공 | `P3-T1~T2`, `P3-GATE`의 표면별 검증 |
| 미구매자는 번역 미리보기만, 구매자·소유자는 기존 권한에 따른 본문 제공 | 레거시/v2 권한·코드포인트 경계 회귀 검증 |
| 언어 감지/번역 실패, 반복 조회, 본문 복원 | 원문 유지·작업 중복 방지·번역 메모리 재사용 검증 |
구현 완료는 위 자동 검증 증거가 기록된 뒤에 판정했다. 실제 MySQL·Papago·HTTP 검증은 테스트 서버 수동 검증으로 분리한다.
## 9. 인터뷰 결과와 Decision Log
최종 모호성 점수: **0.04**. 차원별 명확성: Goal 1.00, Scope 1.00, Constraints 0.95, Success 0.95, Context 0.85.
이는 누락 확인용 판단 지표이며, 코드 검증이나 구현 완료를 의미하지 않는다.
열린 제품 질문은 없다. 테스트 환경 자격증명과 DDL 적용 절차는 테스트 서버 배포 단계에서 확인할 실행 조건이다.
| ID | 상태 | 결정 | 근거 / 영향 |
|---|---|---|---|
| `DEC-001` | 확정 | 본문만 번역, 댓글 제외 | 사용자 인터뷰 / `CCT-001` |
| `DEC-002` | 확정 | 기존 글은 오디오 상세처럼 누락 번역 예약 | 사용자 제안 및 후속 상세 한정 답변 / `CCT-005` |
| `DEC-003` | 확정 | 목록 본문·미리보기도 저장된 번역 적용 | 사용자 답변 / `CCT-006` |
| `DEC-004` | 확정 | 언어 정보가 없으면 자동 감지 | 사용자 답변 / `CCT-002` |
| `DEC-005` | 확정 | 본문 수정 시 언어 재감지·번역 갱신 | 사용자 yes / `CCT-004` |
| `DEC-006` | 확정 | 목록에서는 예약하지 않고 상세에서만 예약 | 사용자 답변 / `CCT-005~006` |
| `DEC-007` | 확정 | 새 번역 전에는 수정된 원문 표시 | 사용자 yes / `CCT-007` |
| `DEC-008` | 확정 | 채널 홈·홈 추천·팔로잉 소식 포함 | 사용자 yes / `CCT-006` |
| `DEC-009` | 기술 설계 | 기존 API 구조·권한 유지, 언어별 저장 번역을 본문 필드에 적용 | 저장소 규칙 및 최소 변경 원칙 / `CCT-008~009` |
| `DEC-010` | 기술 설계 | 본문 개정 번호와 기존 캐시·큐 재사용 | 수정 직후 원문 표시와 비동기 경합 방지 / `CCT-007`, `CCT-010` |
결정 날짜는 모두 2026-09-10이다. 범위 변경 시 이 결정 기록과 요구사항을 먼저 갱신하고 `plan-task.md`를 동기화한다.
@@ -1,118 +0,0 @@
# P1-T2 리뷰 보고서
## 리뷰 정보
| 항목 | 내용 |
|---|---|
| 리뷰 대상 | Phase 1 / `P1-T2`, `P1-GATE` |
| 기준 working tree | P1-T2 구현 및 실제 Spring regression test 추가 상태 |
| 리뷰 일자 | 2026-09-10 |
| 리뷰어 | automated review |
| 기준 문서 | `prd.md`, `plan-task.md` |
| 리뷰 상태 | 추가 수정 및 회귀 검증 완료 |
## 범위
- 코드: `LanguageDetectEvent.kt`, `CreatorCommunityTranslationService.kt`
- 테스트: `CreatorCommunityLanguageDetectTest.kt`
- 제외: 다른 리소스 감지, 공개 API, Docker·HTTP·실제 Papago·MySQL 수동 검증
## 확정 발견 사항
| ID | 심각도 | 상태 | 제목 | 후속 goal |
|---|---|---|---|---|
| `REV-P1-T2-001` | Blocker | 수정 완료 | 커밋 후 번역 예약이 독립 트랜잭션으로 커밋되지 않는다 | `P1-R1` |
| `REV-P1-T2-002` | High | 수정 완료 | 잠금 조회가 stale managed 게시물 상태를 다시 읽지 않는다 | `P1-R1` |
| `REV-P1-T2-003` | High | 수정 완료 | 이미 언어가 있는 이벤트가 요청 target을 버린다 | `P1-R1` |
| `REV-P1-T2-004` | High | 수정 완료 | 이전 mock 검증은 실제 `translation_job` 저장을 증명하지 않는다 | `P1-R1` |
| `REV-P1-T2-005` | High | 수정 완료 | 동시 언어 미확정 감지의 두 번째 target이 lock 뒤 유실된다 | `P1-R2` |
| `REV-P1-T2-006` | Blocker | 수정 완료 | 동시 missing-memory 예약이 translation job unique key에 경합한다 | `P1-R3` |
## 근거와 판정
### REV-P1-T2-001
- 코드: `CreatorCommunityTranslationService.requestTranslations`는 기본 `@Transactional`이고, listener는 after-commit callback에서 이를 호출한다.
- 재현: `shouldExposeProxiedRequiresNewTranslationRequestEntryPoint`는 `Propagation.REQUIRES_NEW`가 아닌 annotation으로 실패했다.
- 영향: 감지 언어 저장 뒤에도 job 예약이 실제로 커밋되지 않아 번역 흐름이 진행되지 않는다.
- 조치: 공유 서비스의 public 요청 진입점을 `REQUIRES_NEW`로 선언하고 실제 job 저장 test로 검증한다.
### REV-P1-T2-002
- 코드: listener는 `findByIdAndIsActiveTrueForUpdate` 뒤 persistence context의 entity를 refresh하지 않는다.
- 재현: `shouldRejectStalePostAfterBlockedDetection`는 감지 동안 본문을 변경한 뒤에도 이전 언어가 저장되어 실패했다.
- 영향: 오래된 감지 결과가 새 본문 언어로 저장될 수 있다.
- 조치: 잠금 획득 뒤 최신 entity 상태를 refresh하고 revision/content를 재검사한다.
### REV-P1-T2-003
- 코드: listener는 이미 languageCode가 설정된 커뮤니티 이벤트를 감지 전 return한다.
- 재현: `shouldContinueBothRequestedTargetsWhenLanguageIsAlreadyKnown`는 `ja`, `en` target job이 저장되지 않아 실패했다.
- 영향: 상세 요청별 번역 예약 범위가 사라진다.
- 조치: 현재 본문 검증 뒤 known-language 이벤트도 after-commit에서 원 target으로 shared service를 호출한다.
### REV-P1-T2-004
- 코드/테스트: 기존 테스트는 `CreatorCommunityTranslationService` mock의 호출만 검증했다.
- 재현: 실제 Spring listener와 scheduler를 연결한 `CreatorCommunityLanguageDetectTest`에서 저장된 `translation_job` target을 확인하자 job이 없었다.
- 영향: mock interaction만 통과해도 사용자 흐름의 persistence 실패를 놓친다.
- 조치: 감지 provider만 제어하고 scheduler/repository는 실제 bean으로 사용한다.
### REV-P1-T2-005
- 코드: lock과 refresh 뒤 languageCode가 이미 있으면 revision/content 재검증 전에 return한다.
- 재현: 같은 언어 미확정 본문으로 두 감지를 시작해 첫 감지를 먼저 커밋한 뒤 두 번째 감지를 진행하면 두 번째 target job이 없다.
- 영향: 동시 상세 요청이 서로 다른 언어를 요청할 때 한 요청의 번역 예약이 유실된다.
- 조치: 현재 revision/content가 유효하면 이미 저장된 언어를 보존하고, 두 번째 이벤트의 원 target을 after-commit에 등록한다.
### REV-P1-T2-006
- 코드: `requestTranslations`는 post lock 없이 materializer의 missing-memory 반환 뒤 scheduler의 job 존재 조회와 insert를 실행한다.
- 재현: 같은 언어 확정 post와 target으로 두 request transaction을 동시에 시작하면 두 transaction이 missing job을 보고 insert를 시도할 수 있다.
- 영향: job unique key 예외가 호출자 transaction까지 전파돼 상세 예약 흐름이 실패할 수 있다.
- 조치: request transaction 시작에서 active post write lock과 refresh를 수행해 source extraction, memory lookup, job 존재 조회와 insert를 직렬화한다.
## 실행 증거
| 명령 | 결과 | 핵심 증거 |
|---|---|---|
| `./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest'` | 실패 | 초기 test bean 보정 후 7개 중 5개 assertion 실패 |
## 결론
`REV-P1-T2-001~006`은 `plan-task.md`의 `P1-R1~R3` 회귀 수정 goal로 반영했고 모두 수정·검증을 완료했다.
## 수정 후 검증 기록
### 1차 수정 검증 — 2026-09-10
- 무엇을: `REQUIRES_NEW` 번역 요청, stale entity refresh, known-language target continuation과 실제 `translation_job` 검증을 추가했다.
- 어떻게:
- `./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest'` — exit 0, `BUILD SUCCESSFUL`.
- `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.*' --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.*' ktlintCheck bootJar` — exit 0, `BUILD SUCCESSFUL`.
- 남은 항목: 사용자 정책상 Docker, HTTP, 실제 Papago, MySQL 수동 동시성 검증은 실행하지 않았다.
### 2차 수정 검증 — 2026-09-10
- 대상: `REV-P1-T2-005`.
- RED: `./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest'` — exit 1, 8개 중 1개 실패.
두 감지가 언어 NULL에서 시작한 뒤 첫 감지의 `ja` job 저장 후 두 번째 `en` job이 누락됐다.
- GREEN: lock과 refresh 뒤 revision/content가 유효하면 이미 저장된 languageCode를 유지하고,
원 target을 after-commit에 등록하도록 수정했다.
- 검증:
- `./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest'` — exit 0, `BUILD SUCCESSFUL`.
- `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.*' --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.*' ktlintCheck` — exit 0, `BUILD SUCCESSFUL`.
- 남은 항목: Docker, HTTP, 실제 Papago, MySQL 수동 동시성 검증은 사용자 정책상 실행하지 않았다.
### 3차 수정 검증 — 2026-09-10
- 대상: `REV-P1-T2-006`.
- RED: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.CreatorCommunityTranslationServiceTest'`
— exit 1. 실제 `translation_job` insert가 H2 `SQLState 23505`,
`uk_translation_job_resource_field_target_hash` unique index 충돌로 실패했다.
- GREEN: `requestTranslations` transaction 시작에서 active post write lock과 `PESSIMISTIC_WRITE` refresh를 수행하도록 수정했다.
- 검증:
- 같은 focused test — exit 0, `BUILD SUCCESSFUL`; 두 호출 정상 종료와 job 1개 저장을 확인했다.
- P1 직접 영향 회귀와 P1 Gate — exit 0, `BUILD SUCCESSFUL`.
- `./gradlew ktlintCheck` — exit 0, `BUILD SUCCESSFUL`.
- 남은 항목: Docker, HTTP, 실제 Papago, MySQL 수동 동시성 검증은 사용자 정책상 실행하지 않았다.
@@ -1,134 +0,0 @@
# Phase 1 리뷰 보고서
## 1. 리뷰 정보
| 항목 | 내용 |
|---|---|
| 대상 | Phase 1 `P1-T1`, `P1-T2`, `P1-R1~R4`, `P1-GATE` |
| 기준 | HEAD `50409e41c0c469529572f5d77033c3cb23d67d22` + 현재 작업 트리 |
| 작업 트리 지문 | `3bbb1d90869484073c3af681118a13f5f03c3ccecbe84de16f1568338acd66b7` |
| 일자 / 리뷰어 | 2026-09-10 / Codex 및 목표·품질·보안·QA 증거 리뷰어 |
| 기준 문서 | [PRD](../prd.md), [구현 계획](../plan-task.md), `docs/sample/sample-review.md` |
| 상태 | `P1-R4` 수정·자동 회귀·후속 리뷰 완료 · 실제 MySQL/Papago/HTTP 수동 검증 대기 |
## 2. 목적과 범위
§2~7의 정적 근거와 지문은 최초 리뷰 당시 기록이다. 수정 후 코드를 같은 지문으로 검증했다고 보지 않는다.
현재 판정은 §8과 2026-09-10 후속 재판정에 기록하며, 아래 최초 리뷰의 실행 제약은 그대로 보존한다.
원문 언어 감지, 번역 저장·재사용, 본문 개정 정합성, 동시 요청의 목표 언어 보존을 기준 문서와 대조한다.
코드·테스트 소스·기존 검증 기록만 확인한다. 사용자 지시에 따라 테스트/컴파일/서버/HTTP/DB 실행은 하지 않는다.
현재 테스트 통과는 사용자 보고 및 기존 기록으로 구분하며 신규 실행 성공으로 표현하지 않는다.
## 3. 판정 기준
확정 요구사항과 실제 코드 경로가 일치하면 충족으로 판정한다. 결함 후보는 발생 순서·예외 전달·기존 테스트의 경계를
대조한 후 확정/오탐/보류로 분리한다. 이번 확정 항목은 제한된 동시 요청 조건에서 발생하고 재조회로 복구할 수 있어
**Medium**으로 판정한다. 단순 외부 감지 호출 중복 자체는 계획에서 허용한 범위이므로 결함으로 세지 않는다.
## 4. 검토 근거와 충족 항목
아래 source 경로는 `src/main/kotlin/kr/co/vividnext/sodalive/` 기준이다.
| 요구사항 / 경계 | 코드 근거 | 판정 |
|---|---|---|
| `CCT-001` 원문과 번역 분리 | `v2/creator/channel/community/translation/adapter/out/persistence/CreatorCommunityTranslation.kt:17`, `schema.sql` | 충족 |
| `CCT-007` 현재 개정·언어·해시 일치 | `v2/creator/channel/community/translation/application/CreatorCommunityTranslationService.kt:95`, `i18n/translation/TranslationReadModelMaterializer.kt:194` | 충족 |
| 이전 감지 결과 배제 | `content/LanguageDetectEvent.kt:383`, 감지 전 확인 및 잠금/refresh 후 재검사 | 충족 |
| `CCT-010` A→B→A 메모리 복원 | `CreatorCommunityTranslationService.requestTranslations`에서 materialize 후 누락 예약 | 충족 |
| 같은 게시물 작업/번역 행 저장 직렬화 | 요청 진입점의 post lock, materializer의 post/translation lock | 충족 |
| 언어 미확정 상태의 실제 캐시 INSERT 경합 | 최초 근거: `content/LanguageDetectionCacheService.kt:21`, `:29` | 당시 수정 필요, `P1-R4` 자동 검증으로 수정 확인 (§9) |
읽은 테스트에는 `CreatorCommunityTranslationServiceTest`의
`shouldReturnOnlyCurrentTranslationFromBatchedRead`, `shouldFallbackToOriginalWhenTranslationIsMissingOrDoesNotMatchCurrentSource`,
`shouldRematerializeAtoBtoAIntoExistingTranslationRow`, `shouldSerializeConcurrentMissingMemoryTranslationJobScheduling`,
`shouldUpdateExistingTranslationAfterRepeatableReadSnapshotWaitsForFirstWriter`가 포함된다.
기존 P1 리뷰의 수정 사항을 신규 결함으로 중복 등록하지 않았다.
실행한 검증은 `git diff`, `rg`, `sed`, `nl`을 통한 정적 대조와 파일 SHA256 계산이다.
기존 테스트 XML과 리뷰 레인 출처는 [증거 기록](review-evidence.md)에 있다. 새 테스트나 런타임 재현은 실행하지 않았다.
## 5. 발견 사항 요약
| ID | 심각도 | 상태 | 제목 | 소유 Task | 후속 Goal |
|---|---|---|---|---|---|
| `REV-P1-007` | Medium | 수정 완료 · `P1-R4` 자동 증거 (§9), 최초 정적 확정 이력 유지 | 최초 감지 캐시 저장 경합으로 후발 목표 언어의 예약 유실 | `P1-T2`, `P1-R2` | `P1-R4` 완료, 실제 MySQL 수동 확인 |
## 6. REV-P1-007 상세
- 관련 요구사항: `CCT-005`, `CCT-010`, 계획 `P1-R2`의 각 요청 target 보존 목표.
- 관련 계약: PRD §4.2 상세 요청 언어만 예약, §6 기존 감지 캐시 재사용.
- 근거 파일:
- `src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectionCacheService.kt:21`: 캐시를 먼저 조회한다.
- 같은 파일 `:28`, `:29`: 외부 감지 후 같은 키에 무조건 `save`한다.
- `src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectionResult.kt:15`: 해시/provider/version 유일 키.
- `src/main/kotlin/kr/co/vividnext/sodalive/common/BaseEntity.kt:19`: IDENTITY 저장 식별자.
- `src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectEvent.kt:398`: 캐시 예외가 후속 post lock보다 먼저 전파된다.
- 같은 파일 `:411`, `:417`: 목표 언어 후속 예약은 감지 성공 이후에만 등록된다.
### 정적 검증 순서
이 순서는 코드를 따라 확인한 결함 조건이며, 이번 턴에서 실제로 실행한 재현 결과가 아니다.
1. 원문 언어 NULL이고 감지 캐시가 없는 동일 한국어 게시물에 일본어·영어 상세 요청을 보낸다.
2. 두 감지 트랜잭션이 모두 언어 NULL과 캐시 miss를 읽은 뒤 각 detector 호출을 진행한다.
3. 첫 detector가 반환하면 캐시 INSERT → 게시물 언어 저장 → 커밋 → 일본어 작업 예약이 진행된다.
4. 뒤늦게 반환한 detector는 캐시를 다시 읽거나 원자적으로 합류하지 않고 같은 유일 키를 INSERT한다.
5. 중복 키 예외로 두 번째 감지 트랜잭션이 종료되어 영어 목표를 예약하는 콜백에 도달하지 못한다.
기대 결과는 양쪽 목표 언어의 작업 보존이다. 코드 경로상 결과는 후발 목표의 작업 누락이다.
다음 영어 상세 조회로 다시 예약할 수 있으므로 영구적인 데이터 손실이라고 주장하지 않는다.
서로 다른 게시물을 같은 본문으로 동시에 신규 작성할 때도 동일한 전역 캐시 키 경합이 발생할 수 있다.
### 기존 테스트가 통과하는 이유
`src/test/kotlin/kr/co/vividnext/sodalive/content/CreatorCommunityLanguageDetectTest.kt:335`의
`shouldPreserveSecondTargetAfterConcurrentDetectionSetsLanguage`는 `ControlledLanguageDetectionCacheService`를 사용한다.
같은 파일 `:743`의 `detectWithCache` override는 실제 캐시 SELECT/INSERT 없이 제어된 언어를 반환한다.
따라서 이 테스트의 목표 보존 성공은 실제 캐시 유일 키 저장 경합까지 보장하지 않는다.
### 권장 조치와 판정
동일 캐시 키 저장을 원자적으로 처리해 이미 저장한 결과로 수렴시키고, 후발 감지 트랜잭션이 rollback-only가 되지 않게 한다.
이미 실패한 트랜잭션 내부에서 예외만 잡고 계속 진행하는 방식은 사용하지 않는다.
외부 API 호출 동안 게시물 행 잠금을 잡지 않는 현재 기준을 유지한다.
실제 캐시 service/repository를 사용하고 detector만 통제하는 두 cache miss 경합 회귀 테스트를 추가한다.
2026-09-10 — 품질 리뷰, 목표 리뷰, 루트 리뷰에서 위 정적 경로를 교차 확인하여 확정했다.
실행 재현은 사용자 지시에 따라 수행하지 않았으며 `P1-R4`의 RED 단계로 남긴다.
## 7. 계획 전환
`plan-task.md`의 Phase 1에 신규 `P1-R4`를 추가한다. 기존 `P1-R2`와 `P1-GATE` 완료 체크 및 검증 기록은 유지한다.
새 목표: 실제 최초 감지 캐시 경합에서도 두 요청 target을 보존하고 해당 회귀를 방지한다.
상세 검증 명령·파일·RED/GREEN/REFACTOR·재검토 조건은 신규 Task에 기록한다.
## 8. 리뷰 종료 판정
| 항목 | 결과 |
|---|---|
| Phase 범위와 기존 수정 확인 | 충족 |
| 후보 판정 | 확정 1건. afterCommit 후 재잠금 교착 후보는 DB 커밋 후 잠금 해제로 오탐 제외 |
| 확정 항목 계획 반영 | 최초 `P1-R4` 신규 등록, 이후 구현·자동 검증·후속 리뷰 완료 |
| 실행 범위 명시 | 최초 리뷰는 테스트 미실행. 이후 `P1-R4` 로컬 자동 검증 증거를 §9에 별도 누적 |
**최초 결론 기록: 수정 Goal 필요.** 당시 최초 감지 캐시 경합 수정과 수정 후 검증이 필요했다.
**현재 최종 결론: `REV-P1-007`은 `P1-R4` 로컬 자동 검증 범위에서 수정 완료.**
실제 MySQL/Papago/HTTP 검증은 기존 배포 후 체크리스트에서 미완료로 유지한다.
## 9. P1-R4 수정 후 재판정 · 2026-09-10
- RED는 실제 캐시 service/repository와 제어된 provider를 사용했다. 두 provider 진입 후 focused 명령이
exit 1로 실패했고 `ExecutionException → DataIntegrityViolationException → H2 23505` 캐시 유일 키 충돌을 확인했다.
- GREEN은 native MySQL `ON DUPLICATE KEY UPDATE id=id`와 scalar `SELECT ... FOR UPDATE`로 승자 결과에
수렴시킨다. audit 시각을 명시하고 DB 예외를 잡아 같은 트랜잭션에서 계속하는 방식은 사용하지 않는다.
- 같은 게시물 `ja`/`en` 이중 miss 및 다른 게시물의 동일 본문 경합에서 캐시 1행과 각 target 작업 보존을 확인했다.
focused fresh 재실행은 `--rerun-tasks --no-parallel`로 `BUILD SUCCESSFUL` (5분 19초)이었다.
- P1 listener/scheduler/materializer 회귀 (1분 09초), P2 상세/API 회귀 (1분 42초), `ktlintCheck` (44초)는
모두 `BUILD SUCCESSFUL`이다. 정확한 명령은 [후속 증거](review-evidence.md)에 기록한다.
- spec `PASS`: `ses_f7657d350ffe3YUYhEHvHPuikK`. quality `APPROVED`: `ses_f7656994dffeR2odTLswaw6RTo`.
- `REV-P1-007`의 실제 캐시 경합 테스트 공백은 위 자동 증거로 보완됐다. H2 `MODE=MySQL`은 MySQL 8/InnoDB의
실제 격리·잠금·DDL 증거가 아니다. 실제 MySQL의 순서 제어 경합, audit 컬럼, 감지 중 수정 가능 여부와 stale 차단,
실제 Papago/HTTP는 [수동 체크리스트](../plan-task.md)에서 확인해야 한다.
- 전체 `./gradlew test`는 생략했다. 공통 캐시 계약·실제 repository 경합·모든 직접 listener/scheduler/materializer
테스트·P2 상세/API 소비자가 통과했고 별도의 미해결 공통 경계가 없다는 영향 범위 판단에 따른다.
@@ -1,85 +0,0 @@
# Phase 2 리뷰 보고서
## 1. 리뷰 정보
| 항목 | 내용 |
|---|---|
| 대상 | Phase 2 `P2-T1`, `P2-T2`, `P2-R1~R3`, `P2-GATE` |
| 기준 | HEAD `50409e41c0c469529572f5d77033c3cb23d67d22` + 현재 작업 트리 |
| 작업 트리 지문 | `3bbb1d90869484073c3af681118a13f5f03c3ccecbe84de16f1568338acd66b7` |
| 일자 / 리뷰어 | 2026-09-10 / Codex 및 목표·품질·보안·QA 증거 리뷰어 |
| 기준 문서 | [PRD](../prd.md), [구현 계획](../plan-task.md), `docs/sample/sample-review.md` |
| 상태 | 판정 완료 |
## 2. 목적과 범위
생성 커밋 후 번역, 실제 본문 수정 시 재감지, 상세의 요청 언어 예약, 기존 권한/응답 보존을 점검한다.
관리자 공용 mutation 경로와 고정 상태 경합의 기존 수정도 확인한다. 사용자 지시에 따라 테스트/컴파일/HTTP 실행은 하지 않는다.
소스·테스트·과거 검증 기록을 기준으로 판단하며 새로운 기능을 요구하거나 미실행을 결함으로 만들지 않는다.
## 3. 판정 기준과 검토 근거
source 경로는 `src/main/kotlin/kr/co/vividnext/sodalive/`, test 경로는 같은 패키지의 `src/test/kotlin/` 기준이다.
| 기준 | 근거 | 판정 |
|---|---|---|
| `CCT-003` 생성 커밋 후 예약 | `explorer/profile/creatorCommunity/CreatorCommunityService.kt:152`, `:175`, `:192` | 충족. 커밋 후 공유 쓰기 진입점을 호출하고 외부 감지는 비동기 listener에서 실행 |
| `CCT-004` 실제 본문 변경만 재감지 | 같은 파일 `:214`, `:221` | 충족. 소유권 잠금 조회/refresh 후 문자열 비교, 언어 NULL, 개정 증가 |
| 본문 외 고정 상태 변경의 정합성 | 같은 파일 `:264`의 잠금/refresh 및 관리자 공용 경로 | 기존 `P2-R2` 수정 반영 확인 |
| `CCT-005` 상세만 요청 언어 예약 | 같은 파일 `:398`, `v2/creator/channel/community/application/CreatorChannelCommunityQueryService.kt:128` | 충족. 유효 번역이 없을 때 요청 locale만 전달 |
| `CCT-007` 최신 원문 폴백 | 공유 조회 결과를 DTO에 복사하며 유효하지 않은 번역은 사용하지 않음 | 충족 |
| `CCT-008` 권한·유료 미리보기 | 레거시 차단 확인 `CreatorCommunityService.kt:390`, v2 접근 검사 `CreatorChannelCommunityQueryService.kt:121`, 기존 마스킹 `:253` | 충족. 번역 선택 후 마스킹 |
| `CCT-009` API/언어 규칙 | 기존 `LangContext`를 사용하고 공개 DTO에는 `content`만 복사 | 충족 |
관리자 생성/수정은 `v2/api/admin/aicharacter/community/AiCharacterAdminCommunityPostFacade.kt:47`, `:75`에서
기존 공용 서비스를 호출한다. 관리용 조회는 원문을 유지한다. 댓글/답글/구매를 번역 예약 진입점으로 추가하지 않았다.
확인한 테스트:
- `content/CreatorCommunityLanguageDetectTest.kt:192` — `shouldRunDetailTranslationPipelineThroughProxyListenerAndScheduler`.
- 같은 파일 `:433` — `shouldLeaveNoPostOrTranslationArtifactsWhenProxiedCreateRollsBack`.
- 같은 파일 `:461` — `shouldHideStaleTranslationAndScheduleNewTargetsAfterCommittedEnglishModification`.
- `explorer/profile/creatorCommunity/CreatorCommunityServiceTest.kt` — 동일 본문/본문 외 수정의 비예약, 유료·소유자·구매자·차단 조건.
- `v2/api/admin/aicharacter/community/AiCharacterAdminCommunityPostConcurrencyTest.kt` — 관리자 공용 mutation과 최신 본문 보존.
## 4. 실행 및 증거 한계
`git diff`, `rg`, `sed`와 테스트 소스 읽기로 호출·트랜잭션·권한 경계를 확인했다.
기존 XML 성공 기록은 [증거 기록](review-evidence.md)에 분리했다. 테스트/컴파일/서버/외부 호출은 실행하지 않았다.
`shouldRunDetailTranslationPipelineThroughProxyListenerAndScheduler`는 실제 프록시·listener·scheduler를 연결하지만
번역 메모리를 직접 저장한 뒤 materializer를 호출한다. 워커 테스트는 별도의 mock 기반 구성요소 검증이다.
따라서 한·영·일 각각의 신규 작성부터 실제 provider/워커/번역 행 저장까지 하나로 연결한 실환경 검증을 완료했다고 해석하지 않는다.
이는 새 제품 결함으로 확정하지 않고 기존 테스트 서버 수동 체크리스트의 실행 범위로 유지한다.
## 5. 발견 사항 요약
**Phase 2 자체 구현의 추가 확정 발견 사항 없음.**
Phase 1의 `REV-P1-007`은 상세를 통한 최초 언어 감지에도 영향을 준다. 같은 원인을 Phase 2 결함으로 중복 등록하지 않고
[Phase 1 리뷰](phase-1-review.md)의 `P1-R4`에서 수정한다. 이 의존성까지 포함한 전체 번역 흐름을 무조건 PASS로 표현하지 않는다.
## 6. 후보 판정
| 후보 | 판정 / 근거 |
|---|---|
| afterCommit의 REQUIRES_NEW 진입이 이전 post lock과 교착 | 오탐. DB commit 후 콜백이므로 이전 트랜잭션의 DB 잠금은 해제된 상태 |
| 관리자 별도 생성/수정에 번역 연결 누락 | 오탐. 공용 레거시 서비스를 호출하므로 중복 연결 불필요 |
| 테스트 재실행이 없으므로 구현 실패 | 해당 없음. 사용자 지시이며 정적 리뷰의 실행 한계로만 기록 |
## 7. 계획 전환
**전환 항목 없음.** 자체 수정 Task를 억지로 추가하지 않는다. Phase 1 `P1-R4`의 직접 영향 회귀에 상세 파이프라인을 포함한다.
## 8. 리뷰 종료 판정
| 항목 | 결과 |
|---|---|
| Phase 2 자체 요구사항 확인 | 충족 |
| 추가 확정 결함 | 없음 |
| 다른 Phase 의존 결함 기록 | `REV-P1-007` / `P1-R4` |
| 새 수정 Task | 해당 없음 |
| 검증 범위 명시 | 충족. 소스·기존 테스트/기록 대조, 직접 실행 없음 |
**최종 결론: Phase 2 자체 기준 충족, 추가 확정 발견 사항 없음.**
남은 항목은 Phase 1 수정의 영향 재검토와 기존 테스트 서버 수동 확인이다. 이번 리뷰에서 수정한 제품 코드는 없다.
@@ -1,84 +0,0 @@
# Phase 3 리뷰 보고서
## 1. 리뷰 정보
| 항목 | 내용 |
|---|---|
| 대상 | Phase 3 `P3-T1`, `P3-T2`, `P3-R1`, `P3-GATE` |
| 기준 | HEAD `50409e41c0c469529572f5d77033c3cb23d67d22` + 현재 작업 트리 |
| 작업 트리 지문 | `3bbb1d90869484073c3af681118a13f5f03c3ccecbe84de16f1568338acd66b7` |
| 일자 / 리뷰어 | 2026-09-10 / Codex 및 문맥·목표·보안·QA 증거 리뷰어 |
| 기준 문서 | [PRD](../prd.md), [구현 계획](../plan-task.md), `docs/sample/sample-review.md` |
| 상태 | 판정 완료 |
## 2. 목적과 범위
`CCT-006~010`의 목록·미리보기·홈 표면, 저장 번역만 읽는 경계, 권한·페이지·공개 계약 유지를 확인한다.
기존 최종 Gate의 실제 실행 미완료 범위도 대조한다. 사용자 지시에 따라 테스트·컴파일·서버·HTTP는 실행하지 않는다.
## 3. 판정 기준과 코드 대조
아래 경로는 `src/main/kotlin/kr/co/vividnext/sodalive/` 기준이다.
| 표면 / 기준 | 코드 근거 | 판정 |
|---|---|---|
| 레거시 일반·최신 목록 | `explorer/profile/creatorCommunity/CreatorCommunityService.kt:305`, `:359`, `:641`, `:679` | 충족. 표시할 ID를 모아 번역 조회 후 본문만 복사 |
| v2 탭 | `v2/creator/channel/community/application/CreatorChannelCommunityQueryService.kt:74` | 충족. 반환 페이지 확정 후 번역 조회, 다음 페이지 확인용 추가 행 제외 |
| 채널 홈 고정·일반 | `v2/creator/channel/home/application/CreatorChannelHomeQueryService.kt:104`, `:133` → 공용 `findHomeCommunityPosts` | 충족. 두 그룹 모두 같은 읽기 연결 |
| 홈 추천 | `v2/recommendation/application/HomeRecommendationQueryService.kt:158` | 충족. 후보 정렬·중복 제거·limit 이후 최종 ID만 처리 |
| 팔로잉 소식 | `v2/home/following/application/HomeFollowingQueryService.kt:32`, `:60` | 충족. 커뮤니티 유형만 변경하고 다른 소식 유지 |
| 목록 계열 예약 금지 | `v2/creator/channel/community/translation/application/CreatorCommunityTranslationService.kt:33` | 충족. `findDisplayContents`는 읽기 전용이며 감지·예약·materialize 호출 없음 |
| 공개 스키마 | DTO/도메인 `copy(content = ...)` | 충족. 내부 `CreatorCommunityDisplayContent`를 공개 응답으로 추가하지 않음 |
| DDL 타입 정합성 | `schema.sql:11`, `CreatorCommunityTranslation.kt`의 sourceHash 매핑 | 기존 `P3-R1`의 VARCHAR(64) 수정 반영 확인 |
`LiveApiService`와 `ExplorerService`의 간접 목록 호출도 기존 서비스에 연결되어 저장 번역을 사용한다.
팔로잉 본문은 `DefaultHomeFollowingQueryRepository.kt:160`, `:251`에서 현재 게시물 내용을 읽으므로
소식 발행 당시 저장한 미리보기를 번역 원문으로 사용하지 않는다.
## 4. 테스트·기록 대조
test 경로는 `src/test/kotlin/kr/co/vividnext/sodalive/` 기준이다.
| 검증 대상 | 읽은 기존 테스트 |
|---|---|
| 배치 크기 1/4에서 SELECT 2회 유지 | `explorer/profile/creatorCommunity/CreatorCommunityTranslationEndToEndTest.kt:66`, `shouldReadTranslationsWithConstantSelectCountAcrossBatchSizes` |
| 목록 누락 번역의 작업/이벤트 미생성 | 같은 파일 `:98`, `shouldNotPublishOrScheduleWhenLegacyListReadsMissingTranslation` |
| 레거시 필터·마스킹·일괄 조회 | `explorer/profile/creatorCommunity/CreatorCommunityServiceTest.kt:579` 이후 관련 테스트 |
| v2 페이지 추가 행 제외·홈 두 그룹 | `v2/creator/channel/community/application/CreatorChannelCommunityQueryServiceTest.kt:180` 이후 관련 테스트 |
| 채널 홈 저장 번역 | `v2/api/creator/channel/home/CreatorChannelHomeEndToEndTest.kt:89`, `shouldUseStoredTranslationsForPinnedAndNormalHomeCommunityPosts` |
| 추천 최종 배치·팔로잉 커뮤니티 유형만 처리 | `v2/recommendation/application/HomeRecommendationQueryServiceTest.kt:705`, `v2/home/following/application/HomeFollowingQueryServiceTest.kt:123` |
`git diff`, `rg`, `sed`로 호출부와 테스트를 대조했다. 기존 XML과 레인 결과는 [증거 기록](review-evidence.md)에 있다.
이 표는 테스트를 새로 실행했다는 의미가 아니다. 기존 계획의 로컬 성공 기록과 실제 MySQL/Papago/HTTP 미완료 표기는
서로 구분되어 있으며, 후자를 완료한 것으로 평가하지 않는다.
## 5. 발견 사항 요약
**확정 발견 사항 없음.** 목록·채널 홈·추천·팔로잉의 저장 번역 적용은 인터뷰에서 확정한 범위에 부합한다.
## 6. 후보 판정
| 후보 | 판정 / 근거 |
|---|---|
| 추천·팔로잉 본문 복사가 유료 전체 본문을 노출 | 오탐. `DefaultHomeRecommendationQueryRepository.kt:893`, `DefaultHomeFollowingQueryRepository.kt:461`의 기존 무료 조건 유지 |
| 레거시/v2 마스킹 전에 원문 길이를 사용 | 오탐. 번역 본문을 복사한 뒤 `SelectCommunityPostResponse.kt:44`, `CreatorChannelCommunityQueryService.kt:253`의 기존 마스킹 실행 |
| 번역 배치 조회가 작성자별 N+1을 추가 | 오탐. `member` LAZY이며 읽기에서 접근하지 않는다. 서로 다른 작성자의 배치 크기 테스트가 기존에 존재 |
| 목록 번역 누락을 처리하기 위해 자동 작업 예약 | 오탐. 공용 읽기 메서드만 사용하고 예약 진입점을 호출하지 않음 |
## 7. 계획 전환
**전환 항목 없음.** 추가 수정 Task는 만들지 않는다. Phase 1 결함으로 번역이 아직 생성되지 않은 경우에는
이 Phase의 요구대로 원문을 표시한다. 예약 결함은 `P1-R4`에서 처리한다.
## 8. 리뷰 종료 판정
| 항목 | 결과 |
|---|---|
| 모든 합의된 목록·미리보기 표면 확인 | 충족 |
| 확정 결함 | 없음 |
| 후보 판정 완료 | 충족, 위 후보는 오탐 |
| 확정 항목 계획 반영 | 해당 없음 |
| 실행 범위·기존 미완료 검증 구분 | 충족 |
**최종 결론: Phase 3 기준 충족, 확정 발견 사항 없음.**
실제 DDL·MySQL 동시성·HTTP·Papago 확인은 기존 수동 체크리스트대로 남긴다. 이번 리뷰에서 제품 코드를 수정하지 않았다.
@@ -1,121 +0,0 @@
# 2026-09-10 Phase별 정적 리뷰 증거
## 대상과 검증 범위
아래 지문부터 리뷰 산출물 검증까지는 최초 정적 리뷰 당시 기록이다. `P1-R4` 이후 변경에는 이 지문과 PASS를
소급 적용하지 않는다. 현재 최종 판정과 후속 자동 증거는 문서 끝에 별도로 누적한다.
- 기준 HEAD: `50409e41c0c469529572f5d77033c3cb23d67d22`.
- 리뷰 대상은 HEAD 자체가 아닌 현재 수정/미추적 source·test와 `schema.sql` 32개 파일이다.
- 위 파일의 경로순 `경로 + NUL + SHA256 + LF`를 결합한 SHA256:
`3bbb1d90869484073c3af681118a13f5f03c3ccecbe84de16f1568338acd66b7`.
- 사용자 지시: 컴파일·테스트는 이미 통과했으므로 테스트를 직접 실행하지 않는다.
- 이번 판정은 소스·테스트·기존 기록의 정적 대조다. 테스트/컴파일/서버/HTTP/Papago/MySQL 실행 판정이 아니다.
- 이전 리뷰의 PASS를 재사용하지 않고 현재 작업 트리를 다시 읽었다. 아래 PASS는 정적 리뷰 범위에만 적용한다.
## 레인 기록
모든 기록의 기준은 위 전체 HEAD와 작업 트리 지문이다. 소스가 바뀌면 이 결과를 그대로 재사용하지 않는다.
| 레인 | 판정 | 근거 / 결과 출처 |
|---|---|---|
| 보안·권한 `security_review` | PASS | 현재 본문 정합성, 번역 선택 후 유료 마스킹, 추천/팔로잉 무료 필터, 관리자 원문 보존 확인. `/root/security_review` 최종 보고, 2026-09-10. |
| 목표·제약 `goal_review` | 수정 필요 | Phase 1 캐시 경합으로 요청 target 유실을 독립 확인. Phase 2·3 추가 결함 없음. `/root/goal_review` 최종 보고, 2026-09-10. |
| 코드 품질·동시성 `code_review` | 수정 필요 | 감지 캐시 최초 INSERT 경합으로 후발 target 예약 유실. `/root/code_review` 최종 보고, 2026-09-10. Phase 1 보고서에 상세 근거를 기록한다. |
| 기존 QA 증거 `qa_evidence_review` | 정적 증거 확인 완료 | 기존 테스트 소스/XML 성공 기록을 확인했다. 실제 캐시 INSERT 경합과 한·영·일 전체 파이프라인의 직접 통합 증거 한계는 별도로 남긴다. `/root/qa_evidence_review` 최종 보고, 2026-09-10. |
| 문맥·통합 `context_review` | PASS — Phase 3 범위 | 목록/홈 및 간접 소비자, 공개 스키마·무료 필터·읽기 전용 경계 확인. `/root/context_review` 최종 보고, 2026-09-10. Phase 1·2 전체 판정으로 확대하지 않는다. |
동적 QA/debugging 감사는 사용자 지시에 따라 재실행하지 않았다. 이를 PASS나 신규 실패로 분류하지 않는다.
## 기존 실행 증거 표본
아래는 `build/test-results/test/`의 기존 XML을 읽은 결과이며 현재 턴에서 실행한 테스트가 아니다.
| XML 파일명 | 테스트 수 | 실패 / 오류 / skip | 기록 timestamp |
|---|---:|---|---|
| `TEST-kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest.xml` | 12 | 0 / 0 / 0 | 2026-09-10T02:43:16 |
| `TEST-kr.co.vividnext.sodalive.v2.creator.channel.community.translation.CreatorCommunityTranslationServiceTest.xml` | 16 | 0 / 0 / 0 | 2026-09-10T02:50:05 |
| `TEST-kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.CreatorCommunityTranslationEndToEndTest.xml` | 4 | 0 / 0 / 0 | 2026-09-10T02:44:03 |
| `TEST-kr.co.vividnext.sodalive.i18n.translation.TranslationJobWorkerTest.xml` | 7 | 0 / 0 / 0 | 2026-09-10T02:44:03 |
| `TEST-kr.co.vividnext.sodalive.v2.api.creator.channel.community.adapter.in.web.CreatorChannelCommunityEndToEndTest.xml` | 15 | 0 / 0 / 0 | 2026-09-10T02:48:44 |
| `TEST-kr.co.vividnext.sodalive.v2.api.creator.channel.home.CreatorChannelHomeEndToEndTest.xml` | 2 | 0 / 0 / 0 | 2026-09-10T02:49:09 |
XML에 source 지문이 포함되어 있다고 가정하지 않는다. 사용자 보고와 계획의 과거 성공 기록을 보조하는 자료로만 사용한다.
## 최종 정적 판정
- [Phase 1](phase-1-review.md): 확정 수정 사항 1건 → `P1-R4`.
- [Phase 2](phase-2-review.md): 자체 구현 범위 충족, 추가 확정 발견 사항 없음. Phase 1 결함의 상세 예약 영향은 남는다.
- [Phase 3](phase-3-review.md): 저장 번역 표시·목록 비예약 범위 충족, 추가 확정 발견 사항 없음.
- 이번 리뷰는 테스트·제품 코드·DDL을 변경하지 않았다. Phase 1 수정과 실제 실행 검증은 후속 작업이다.
## 리뷰 산출물 검증
- `./gradlew tasks --all` — exit 0, `BUILD SUCCESSFUL`. 저장소 문서 가이드에 따른 task 목록 확인만 수행했다.
이 명령으로 컴파일이나 테스트를 실행하지 않았다.
- `git diff --check` — exit 0. 새 미추적 리뷰 문서는 별도 공백/개행 검사로 확인했다.
- 문서 링크·공백·템플릿 잔여값 검사 — 5개 문서 PASS. `P1-R4`는 Phase 1 안에 한 번만 미완료 Goal로 등록됐다.
- 리뷰 전후 source/test/DDL 32개 파일 SHA256 대조 — 동일 지문으로 PASS. 제품 코드·테스트·DDL 수정 없음.
## P1-R4 수정 후 증거 · 2026-09-10
이 절은 완료된 구현의 RED/GREEN·자동 회귀·리뷰 결과를 전달받아 동기화한 기록이다.
이번 문서 작업에서 제품 테스트를 다시 실행한 결과가 아니며, 위 최초 정적 리뷰의 지문을 새 코드의 지문으로 재사용하지 않는다.
### 구현과 RED/GREEN
- RED: 아래 focused 명령은 두 provider 진입 이후 exit 1로 실패했다.
`ExecutionException → DataIntegrityViolationException → H2 23505`로 감지 캐시 유일 키 충돌을 확인했다.
- GREEN: native MySQL `ON DUPLICATE KEY UPDATE id=id`와 scalar `SELECT ... FOR UPDATE`로 승자 행을
현재 읽기한다. native INSERT에 audit 시각을 명시하며 DB 예외를 잡고 후속 예약을 계속하지 않는다.
- 실제 캐시 service/repository를 통한 같은 게시물 `ja`/`en` 이중 miss와 다른 게시물의 동일 본문 경합을 검증했다.
캐시 1행으로 수렴하고 각 요청의 목표 언어 작업을 보존한다.
### 자동 검증 명령과 결과
RED focused 명령 (exit 1, 위 유일 키 충돌):
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectionCacheConcurrencyTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest'
```
GREEN focused fresh 재실행, `BUILD SUCCESSFUL` (5분 19초):
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectionCacheConcurrencyTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --rerun-tasks --no-parallel
```
P1 listener/scheduler/materializer 영향 회귀, `BUILD SUCCESSFUL` (1분 09초):
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.*' --tests 'kr.co.vividnext.sodalive.i18n.translation.*'
```
P2 상세/API 소비자 회귀, `BUILD SUCCESSFUL` (1분 42초):
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.*' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.community.*'
```
형식 검사, `BUILD SUCCESSFUL` (44초):
```bash
./gradlew ktlintCheck
```
전체 `./gradlew test`는 생략했다. 공통 캐시 계약, 실제 repository 경합, 모든 직접 listener/scheduler/materializer
테스트와 P2 상세/API 소비자가 위 명령으로 통과했고 별도로 미해결된 공통 경계가 없었다.
과거 전체 빌드 성공을 이번 변경의 전체 테스트 실행으로 간주하지 않는다.
### 수정 후 리뷰와 현재 최종 판정
| 리뷰 | 판정 | 출처 |
|---|---|---|
| spec | PASS | `ses_f7657d350ffe3YUYhEHvHPuikK` |
| quality | APPROVED | `ses_f7656994dffeR2odTLswaw6RTo` |
**현재 최종 판정: 기존 Phase 1 결함 `REV-P1-007`은 `P1-R4` 로컬 자동 검증 범위에서 수정 완료다.**
H2 `MODE=MySQL` 결과는 실제 MySQL 8/InnoDB의 유일 키·격리 수준·audit 컬럼·잠금 동작 검증이 아니다.
테스트 서버의 순서 제어 이중 miss, 다른 게시물의 공유 캐시 수렴, provider 차단 중 본문 수정과 stale 결과 차단은
[계획의 수동 체크리스트](../plan-task.md)에 미완료로 남긴다. 실제 MySQL/Papago/live HTTP, Docker, 배포는
검증하지 않았으며 기존 정적 리뷰의 실환경 검증 한계도 유지한다.
@@ -1,19 +0,0 @@
ALTER TABLE creator_community
ADD COLUMN language_code VARCHAR(10) NULL COMMENT '본문 원문 언어 코드',
ADD COLUMN content_revision BIGINT NOT NULL DEFAULT 0 COMMENT '본문 개정 번호';
CREATE TABLE creator_community_translation (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '식별자',
creator_community_id BIGINT NOT NULL COMMENT '크리에이터 커뮤니티 게시물 식별자',
locale VARCHAR(10) NOT NULL COMMENT '표시 대상 언어 코드',
content TEXT NOT NULL COMMENT '번역된 본문',
source_revision BIGINT NOT NULL COMMENT '번역 기준 본문 개정 번호',
source_hash VARCHAR(64) NOT NULL COMMENT '번역 기준 정규화 원문 해시',
source_language VARCHAR(10) NOT NULL COMMENT '번역 기준 원문 언어 코드',
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
PRIMARY KEY (id),
CONSTRAINT uk_creator_community_translation_post_locale UNIQUE (creator_community_id, locale),
CONSTRAINT fk_creator_community_translation_post
FOREIGN KEY (creator_community_id) REFERENCES creator_community (id)
) COMMENT = '크리에이터 커뮤니티 게시물 본문 번역';
@@ -1,144 +0,0 @@
# OCI Blue/Green 배포 검증 endpoint 구현 계획
| 문서 항목 | 내용 |
|---|---|
| 상태 | 구현 완료 |
| 작성일 | 2026-09-14 |
| 요구사항 기준 | `docs/20260914_배포검증readiness및deployment엔드포인트/prd.md` |
| 현재 Phase | Phase 1 배포 검증 endpoint |
| 현재 활성 Goal | 없음 |
## 목표
배포 스크립트가 애플리케이션 포트에서 readiness를, management 포트에서 readiness와 배포 식별자를 확인할 수 있다.
## 현재 상태
| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
|---:|---|---:|---|---|
| 1 | 완료 | `4/4` | 없음 | 없음 |
## 범위
### 포함
- `spring-boot-starter-actuator` 의존성 추가.
- `application.yml`(main/test)의 포트·probe·exposure·deployment property 설정.
- `DeploymentEndpoint` custom Actuator endpoint 구현.
- `SecurityConfig`의 `/readyz` permitAll 최소 변경.
- 위 동작을 검증하는 통합 test.
### 제외
- Kubernetes 의존성·설정.
- 배포 스크립트(`scripts/`, `appspec.yml`) 변경.
- 신규 추상화/라이브러리, 기존 API 변경.
## 기술적 제약
- 기술 스택: Kotlin 1.6.21, Spring Boot 2.7.14, Gradle Kotlin DSL, JUnit 5.
- 배포 식별자는 property placeholder만 사용하고 별도 환경변수 파싱·fallback 코드를 만들지 않는다.
- 응답 필드명은 snake_case 고정(`application_artifact_version`, `config_commit`).
- 검증: 신규 test 우선 실행 후 `./gradlew test` 전체 회귀(공통 보안·설정 변경이므로 전체 회귀 필요).
## Phase 1 배포 검증 endpoint
**Phase 결과:** readiness와 deployment endpoint가 지정된 포트 경계에 맞게 동작한다.
**선행조건:** 없음.
**Phase 완료 조건:** `P1-T1`~`P1-T4` 완료, `./gradlew test`와 `./gradlew bootJar` 성공 기록.
### 구현 항목
#### Task 1.1 Actuator 의존성과 기본 설정
**Goal 실행 `P1-T1`:** Actuator를 추가하고 포트·exposure·deployment property 계약을 설정에 반영한다.
- **시작 조건:** PRD `DEPLOY-001`, `DEPLOY-002`, `DEPLOY-005`.
- **완료 증거:** 설정 파일 diff와 애플리케이션 컨텍스트 기동 test 통과.
- **범위 밖:** endpoint 구현, security 변경.
**Files:**
- Modify: `build.gradle.kts`
- Modify: `src/main/resources/application.yml`
- Modify: `src/test/resources/application.yml`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/deployment/DeploymentEndpointIntegrationTest.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/deployment/DeploymentEndpointInjectedValueIntegrationTest.kt`
- [x] **RED:** `DeploymentEndpointIntegrationTest`에서 management 포트 readiness/deployment 호출 test를 작성했다.
- [x] **RED 확인:** Actuator 부재로 `Could not resolve placeholder 'local.management.port'` 실패를 확인했다.
- [x] **GREEN:** `spring-boot-starter-actuator`와 포트·exposure·deployment 설정을 추가했다.
- [x] **GREEN 확인:** `./gradlew test --tests 'kr.co.vividnext.sodalive.deployment.*'` 통과.
- [x] **REFACTOR:** deprecated `LocalServerPort` import 정리, `./gradlew ktlintCheck` 성공.
#### Task 1.2 readiness 접근 허용
**Goal 실행 `P1-T2`:** `/readyz`와 management readiness가 인증 없이 200을 반환한다.
- **시작 조건:** `P1-T1` 완료.
- **완료 증거:** readiness test 통과.
- **범위 밖:** 기타 endpoint의 security 정책 변경.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/configs/SecurityConfig.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/deployment/DeploymentEndpointIntegrationTest.kt`
- [x] **RED:** `/readyz` 200 기대 test 작성(`DeploymentEndpointIntegrationTest`).
- [x] **RED 확인:** Actuator/보안 미적용 상태 실패 확인.
- [x] **GREEN:** `SecurityConfig`에 `/readyz` permitAll과 `EndpointRequest.toAnyEndpoint()` permitAll 추가.
- [x] **GREEN 확인:** readiness test 2건 통과.
- [x] **REFACTOR:** 추가 변경 없음.
#### Task 1.3 deployment custom Actuator endpoint
**Goal 실행 `P1-T3`:** `/actuator/deployment`가 snake_case 배포 식별자를 반환한다.
- **시작 조건:** `P1-T1` 완료.
- **완료 증거:** 기본값·주입값 test 통과.
- **범위 밖:** 추가 필드.
**Files:**
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/deployment/DeploymentEndpoint.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/deployment/DeploymentEndpointIntegrationTest.kt`
- [x] **RED:** 기본값(`local`, 40자리 zero)과 주입값 검증 test 작성.
- [x] **RED 확인:** endpoint 미구현 실패 확인.
- [x] **GREEN:** `@Endpoint(id = "deployment")` + `@ReadOperation` 구현.
- [x] **GREEN 확인:** 기본값·주입값 test 통과.
- [x] **REFACTOR:** `./gradlew ktlintCheck` 성공.
#### Task 1.4 포트 접근 경계 검증
**Goal 실행 `P1-T4`:** 애플리케이션 포트에서 `/actuator/deployment`가 노출되지 않음을 검증한다.
- **시작 조건:** `P1-T3` 완료.
- **완료 증거:** 애플리케이션 포트 접근 test 통과.
- **범위 밖:** 그 외 경로 노출 정책.
**Files:**
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/deployment/DeploymentEndpointIntegrationTest.kt`
- [x] **RED:** 애플리케이션 포트 접근이 200이 아님을 기대하는 test 작성.
- [x] **RED 확인:** 초기 404 기대 단정이 `401 UNAUTHORIZED`로 실패함을 확인.
- [x] **GREEN:** management 포트 분리로 애플리케이션 포트에서는 endpoint가 매핑되지 않고 401로 차단됨을 확인, 단정을 "200 아님 + 배포 식별자 미포함" 계약으로 정정.
- [x] **GREEN 확인:** 해당 test 통과.
- [x] **REFACTOR:** `./gradlew test` 전체 회귀 성공.
### Phase Gate `P1-GATE`
- [x] `./gradlew test` 성공.
- [x] `./gradlew bootJar` 성공 및 실행 가능한 JAR 생성 확인.
## 검증 기록
- 2026-09-14 `./gradlew test --tests 'kr.co.vividnext.sodalive.deployment.*'` → RED 5 failed → GREEN 5 passed.
- 2026-09-14 `./gradlew ktlintCheck` → BUILD SUCCESSFUL.
- 2026-09-14 `./gradlew test` → BUILD SUCCESSFUL (전체 회귀).
- 2026-09-14 `./gradlew bootJar` → `build/libs/sodalive-0.0.1-SNAPSHOT.jar`(141MB), `Main-Class: org.springframework.boot.loader.JarLauncher` 확인.
- 참고: 기존 test 실행에는 `JWT_SECRET` 환경변수가 필요하며 이는 이번 변경 이전부터 동일한 전제다.
- 참고: 애플리케이션 포트에서 `/actuator/deployment`는 404가 아니라 401로 차단된다. `EndpointRequest` matcher가 management 포트 분리 시 애플리케이션 포트 요청에 매칭되지 않기 때문이며, 노출되지 않는다는 요구는 충족한다.
@@ -1,101 +0,0 @@
# OCI Blue/Green 배포 검증용 readiness 및 deployment endpoint PRD
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | 구현 완료 |
| 작성일 | 2026-09-14 |
| 최종 수정일 | 2026-09-14 |
| 대상 제품 | sodalive server 배포 검증 endpoint |
| 작성자·결정권자 | 요청 사용자 |
| 관련 구현 계획 | `docs/20260914_배포검증readiness및deployment엔드포인트/plan-task.md` |
| 관련 review | 없음 |
## 1. Overview
OCI Blue/Green 배포에서 배포 스크립트가 새로 기동한 인스턴스의 기동 완료 여부와, 실제로 어떤 artifact/config가 올라갔는지를
HTTP로 확인할 수 있어야 한다. 이를 위해 Spring Boot Actuator의 readiness probe와 배포 식별 정보를 반환하는 custom Actuator
endpoint를 제공한다.
## 2. Problem Statement
- 현재 프로젝트에는 Actuator 의존성과 health endpoint가 없어 배포 스크립트가 기동 완료를 판정할 방법이 없다.
- 어떤 artifact 버전과 config commit이 배포되었는지 런타임에서 확인할 수 없다.
- 모든 요청이 Spring Security의 `anyRequest().authenticated()`로 보호되어 있어 인증 없는 probe 호출이 불가능하다.
해결 판단 기준: 배포 스크립트가 인증 없이 `GET :8080/readyz`로 기동을 판정하고, 운영 전용 포트에서
`GET :8082/actuator/deployment`로 배포 식별자를 확인할 수 있다.
## 3. Goals
- 애플리케이션 포트(8080)에서 인증 없이 readiness 확인 가능.
- Management 포트(8082)에서 readiness와 배포 식별 정보 확인 가능.
- 배포 식별자는 환경변수로 주입하고, 환경변수가 없어도 로컬/테스트 기동이 가능해야 한다.
## 4. Non-Goals
- Kubernetes 관련 의존성·설정 추가.
- liveness 기반 자동 재기동 정책, 배포 스크립트 자체 변경.
- health details/components 공개, 신규 추상화 계층 도입.
## 5. 권한
- 인증 주체: 없음(배포 스크립트/로드밸런서).
- `/readyz`: 애플리케이션 포트에서 인증 없이 허용.
- `/actuator/**`: management 포트(8082)에서만 노출. 애플리케이션 포트에서는 노출하지 않는다.
- `/readyz` 응답에는 민감 정보나 배포 식별자를 포함하지 않는다.
## 6. 기능 요구사항
| ID | 상태 | 요구사항 | 수용 기준 | Goal 연결 |
|---|---|---|---|---|
| `DEPLOY-001` | 확정 | `spring-boot-starter-actuator` 의존성을 추가한다(중복 추가 금지). | `build.gradle.kts`에 1회만 존재 | `P1-T1` |
| `DEPLOY-002` | 확정 | 애플리케이션 포트 8080, management 포트 8082로 분리한다. | `application.yml`에 `server.port: 8080`, `management.server.port: 8082` | `P1-T1` |
| `DEPLOY-003` | 확정 | health probes와 additional path를 활성화해 `/readyz`를 제공한다. | `GET :8080/readyz` → 200 | `P1-T2` |
| `DEPLOY-004` | 확정 | management 포트에서 readiness를 제공한다. | `GET :8082/actuator/health/readiness` → 200 | `P1-T2` |
| `DEPLOY-005` | 확정 | web exposure는 `health`, `deployment`만 포함하고 health details/components는 공개하지 않는다. | `management.endpoints.web.exposure.include: health,deployment`, `show-details: never`, `show-components: never` | `P1-T1` |
| `DEPLOY-006` | 확정 | `DEPLOY_ARTIFACT_VERSION`/`DEPLOY_CONFIG_COMMIT`을 property placeholder로 연결한다. | 환경변수 없으면 `local`, 40자리 zero commit | `P1-T3` |
| `DEPLOY-007` | 확정 | `/actuator/deployment`를 custom Actuator endpoint로 구현한다. | REST controller가 아닌 `@Endpoint` 구현체 존재 | `P1-T3` |
| `DEPLOY-008` | 확정 | 응답 필드는 정확히 `application_artifact_version`, `config_commit`이다. | snake_case JSON 검증 test 통과 | `P1-T3` |
| `DEPLOY-009` | 확정 | 애플리케이션 포트에서 `/actuator/deployment`가 노출되지 않는다. | `GET :8080/actuator/deployment` → 200 아님 | `P1-T4` |
| `DEPLOY-010` | 확정 | Security 정책 최소 변경으로 readiness가 401/403/redirect 되지 않는다. | `SecurityConfig`에 `/readyz` permitAll 추가 | `P1-T2` |
## 7. API 계약
### 7.1 `GET :8080/readyz`
- 인증 불필요. 응답 body는 Actuator 기본 health 응답(`{"status":"UP"}`), 세부 정보 비공개.
### 7.2 `GET :8082/actuator/health/readiness`
- 응답: `{"status":"UP"}`.
### 7.3 `GET :8082/actuator/deployment`
```json
{
"application_artifact_version": "local",
"config_commit": "0000000000000000000000000000000000000000"
}
```
## 8. 성공 기준
- [x] `GET :8080/readyz`가 200을 반환한다. (`DEPLOY-003`, `DEPLOY-010`)
- [x] `GET :8082/actuator/health/readiness`가 200을 반환한다. (`DEPLOY-004`)
- [x] `GET :8082/actuator/deployment`가 주입값을 snake_case JSON으로 반환한다. (`DEPLOY-006`~`DEPLOY-008`)
- [x] `GET :8080/actuator/deployment`가 200을 반환하지 않는다(401로 차단). (`DEPLOY-009`)
- [x] `./gradlew test`, `./gradlew bootJar` 성공.
## 9. Open Questions
없음.
## 10. Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항 |
|---|---|---|---|---|---|
| 2026-09-14 | `DEC-001` | 확정 | Kubernetes 의존성 없이 Actuator 기본 probe만 사용 | 사용자 요구사항 범위 제한 | `DEPLOY-003`, `DEPLOY-004` |
| 2026-09-14 | `DEC-002` | 확정 | 배포 식별자는 별도 파싱 코드 없이 Spring property placeholder로만 연결 | 사용자 요구사항, 단순성 유지 | `DEPLOY-006` |
| 2026-09-14 | `DEC-003` | 확정 | `/actuator/deployment`는 `@Endpoint` 기반 custom Actuator endpoint로 구현 | 사용자 요구사항(REST controller 금지) | `DEPLOY-007` |
@@ -1,388 +0,0 @@
# 크리에이터 시작 DM 방 생성 Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` 또는 `superpowers:executing-plans`로 task 단위 구현을 진행한다. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** `POST /api/v2/user-creator-chat/rooms/create`가 기존 리스너 시작 DM 생성과 새 크리에이터 시작 DM 생성을 모두 지원한다.
**Architecture:** 기존 endpoint와 응답 DTO를 유지하고 request DTO만 `recipientId` 중심으로 확장한다. Controller에서 `request.recipientMemberId()`로 단일 상대 회원 ID를 산출하고, 기존 `UserCreatorChatService.createOrGetRoom(member, recipientId)` 흐름과 `validateRecipient` 정책을 재사용한다. 메시지 저장/전달/푸시는 기존 WebSocket 및 메시지 발송 흐름에 맡긴다.
**Tech Stack:** Kotlin, Spring Boot 2.7.14, Java 17, JUnit 5, Mockito, Gradle Wrapper
---
| 문서 항목 | 내용 |
|---|---|
| 상태 | 구현 중 |
| 작성일 | 2026-09-14 |
| 요구사항 기준 | `docs/20260914_크리에이터_리스너_DM방_생성/prd.md` |
| API 기준 | PRD §8 |
| 현재 Phase | Phase 1 |
| 현재 활성 Goal | 없음 |
## 목표
기존 `creatorId` 요청을 깨지 않으면서 신규 `recipientId` 요청으로 발신자 역할과 무관하게 유저-크리에이터 DM 방을 생성/조회할 수 있게 한다.
## 현재 상태
| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
|---:|---|---:|---|---|
| 1 | 진행 중 | `3/3` | `P1-GATE` | 전체 `./gradlew build`가 `:test` 단계에서 timeout 됨 |
## 범위
### 포함
- `POST /api/v2/user-creator-chat/rooms/create` request DTO 확장
- `recipientId` 표준 필드 추가
- 기존 `creatorId` alias 유지
- `recipientId`/`creatorId` 누락·불일치 validation
- 기존 방 재사용 및 새 방 생성 회귀 검증
- `/create`가 메시지를 만들지 않는다는 회귀 검증
### 제외
- 첫 메시지 발송 request 추가
- WebSocket 프로토콜 변경
- FCM 푸시 정책 변경
- DB 스키마 변경
- 새 endpoint 추가
- 기존 `creatorId` alias 제거
## 기술적 제약
- 공개 API 응답 `CreateUserCreatorChatRoomResponse(roomId)`는 변경하지 않는다.
- 신규 클라이언트는 `recipientId`를 사용하지만, 기존 클라이언트의 `creatorId` 요청도 허용한다.
- `recipientId`와 `creatorId`가 모두 있고 값이 다르면 `common.error.invalid_request`로 거부한다.
- 권한/상태 검증은 기존 `UserCreatorChatService.validateRecipient` 정책을 재사용한다.
- 새 공용 abstraction, 새 dependency, DB migration은 만들지 않는다.
- 구현 Task는 RED → GREEN → REFACTOR 순서로 수행한다.
## 파일 구조 계획
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/dto/UserCreatorChatDtos.kt`
- `CreateUserCreatorChatRoomRequest`에 `recipientId` nullable 필드와 기존 `creatorId` nullable alias를 둔다.
- 단일 상대 ID 산출 함수를 DTO 내부에 둔다.
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/controller/UserCreatorChatController.kt`
- `request.recipientMemberId()` 결과를 `service.createOrGetRoom(member, recipientId)`에 전달한다.
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/service/UserCreatorChatService.kt`
- 함수 파라미터명만 의미에 맞게 `recipientId`로 바꾸는 것을 검토한다. 동작은 유지한다.
- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/UserCreatorChatServiceTest.kt`
- 새 방 생성, 기존 방 재사용, 메시지 미생성, validation 회귀를 검증한다.
- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/UserCreatorChatControllerMappingTest.kt`
- request alias 해석 단위 테스트 또는 controller mapping 테스트를 보강한다.
## Phase 1: `/create` request 일반화
**Phase 결과:** 기존 클라이언트와 신규 클라이언트 모두 같은 `/create` endpoint로 DM 방을 생성/조회할 수 있다.
**선행조건:** PRD `DEC-001`~`DEC-003` 확정.
**Phase 완료 조건:** `P1-T1`~`P1-T3`과 `P1-GATE` 완료, 검증 기록 누적.
### 구현 항목
#### Task 1.1 request DTO alias 계약 추가
**Goal 실행 `P1-T1`:** `CreateUserCreatorChatRoomRequest`가 `recipientId`와 기존 `creatorId` alias에서 하나의 상대 회원 ID를 산출한다.
- **시작 조건:** PRD `DMROOM-001~004`, `DEC-003` 확인.
- **완료 증거:** DTO/Controller focused test 통과와 request 계약 문서 일치.
- **범위 밖:** 방 생성 repository 동작 변경, 메시지 발송.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/dto/UserCreatorChatDtos.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/controller/UserCreatorChatController.kt`
- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/UserCreatorChatControllerMappingTest.kt`
**Interfaces:**
- Consumes: request JSON `{ "recipientId": Long? }`, `{ "creatorId": Long? }`
- Produces: `CreateUserCreatorChatRoomRequest.recipientMemberId(): Long`
- [x] **RED:** `UserCreatorChatControllerMappingTest`에 `recipientId`만 보낸 요청이 service에 해당 ID를 전달하는 실패 테스트를 작성한다.
```kotlin
@Test
fun shouldCreateRoomWithRecipientId() {
val service = Mockito.mock(UserCreatorChatService::class.java)
val controller = UserCreatorChatController(service)
val member = Member(email = "creator@test.com", password = "pw", nickname = "creator")
member.id = 10L
Mockito.`when`(service.createOrGetRoom(member, 20L))
.thenReturn(CreateUserCreatorChatRoomResponse(roomId = 30L))
val response = controller.createOrGetRoom(
member,
CreateUserCreatorChatRoomRequest(recipientId = 20L, creatorId = null)
)
Mockito.verify(service).createOrGetRoom(member, 20L)
assertEquals(30L, response.data!!.roomId)
}
```
- [x] **RED:** 기존 `creatorId`만 보낸 요청도 service에 해당 ID를 전달하는 실패 테스트를 작성한다.
```kotlin
@Test
fun shouldCreateRoomWithLegacyCreatorId() {
val request = CreateUserCreatorChatRoomRequest(recipientId = null, creatorId = 20L)
assertEquals(20L, request.recipientMemberId())
}
```
- [x] **RED:** 두 필드가 모두 없거나 서로 다르면 `common.error.invalid_request`가 발생하는 실패 테스트를 작성한다.
```kotlin
@Test
fun shouldRejectMissingOrConflictingRecipientIds() {
val missing = assertThrows(SodaException::class.java) {
CreateUserCreatorChatRoomRequest(recipientId = null, creatorId = null).recipientMemberId()
}
assertEquals("common.error.invalid_request", missing.messageKey)
val conflict = assertThrows(SodaException::class.java) {
CreateUserCreatorChatRoomRequest(recipientId = 20L, creatorId = 21L).recipientMemberId()
}
assertEquals("common.error.invalid_request", conflict.messageKey)
}
```
- [x] **RED 확인:** `./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatControllerMappingTest`를 실행해 `recipientId` 생성자 파라미터 또는 `recipientMemberId()` 부재로 실패하는 것을 확인한다.
- [x] **GREEN:** DTO를 최소 확장한다.
```kotlin
data class CreateUserCreatorChatRoomRequest(
val recipientId: Long? = null,
val creatorId: Long? = null
) {
fun recipientMemberId(): Long {
if (recipientId != null && creatorId != null && recipientId != creatorId) {
throw SodaException(messageKey = "common.error.invalid_request")
}
return recipientId ?: creatorId ?: throw SodaException(messageKey = "common.error.invalid_request")
}
}
```
- [x] **GREEN:** Controller에서 `request.recipientMemberId()`를 service에 전달한다.
```kotlin
ApiResponse.ok(service.createOrGetRoom(member, request.recipientMemberId()))
```
- [x] **GREEN 확인:** 같은 focused test를 다시 실행해 성공을 확인한다.
- [x] **REFACTOR:** 테스트 helper 중 이번 Task가 만든 중복만 정리하고 `./gradlew ktlintCheck` 결과를 Progress에 기록한다.
#### Task 1.2 service 방 생성 정책 회귀 보강
**Goal 실행 `P1-T2`:** 발신자 역할과 무관하게 기존 수신자 검증, 기존 방 재사용, 메시지 미생성 정책을 유지한다.
- **시작 조건:** `P1-T1` 완료.
- **완료 증거:** `UserCreatorChatServiceTest` focused test 통과.
- **범위 밖:** `validateRecipient` 정책 변경, WebSocket 발송 구현.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/service/UserCreatorChatService.kt`
- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/UserCreatorChatServiceTest.kt`
**Interfaces:**
- Consumes: `createOrGetRoom(member: Member, recipientId: Long)`
- Produces: `CreateUserCreatorChatRoomResponse(roomId: Long)`
- [x] **RED:** 크리에이터 역할 회원이 일반 회원에게 방을 생성할 수 있는 실패 테스트를 작성한다.
```kotlin
@Test
fun shouldCreateRoomWhenCreatorStartsDmToUser() {
val creator = member(1L, "creator").apply { role = MemberRole.CREATOR }
val user = member(2L, "user")
Mockito.`when`(memberRepository.findById(2L)).thenReturn(Optional.of(user))
Mockito.`when`(roomRepository.findActiveRoomByParticipantMemberIds(1L, 2L)).thenReturn(null)
Mockito.`when`(roomRepository.save(Mockito.any(UserCreatorChatRoom::class.java))).thenReturn(room(10L))
val response = service.createOrGetRoom(creator, 2L)
assertEquals(10L, response.roomId)
Mockito.verify(participantRepository).save(Mockito.argThat { it.member == creator })
Mockito.verify(participantRepository).save(Mockito.argThat { it.member == user })
Mockito.verifyNoInteractions(messageRepository)
}
```
- [x] **RED:** 기존 활성 방이 있으면 새 방과 메시지를 만들지 않는 회귀 테스트를 작성한다.
```kotlin
@Test
fun shouldReturnExistingRoomWithoutCreatingMessage() {
val creator = member(1L, "creator").apply { role = MemberRole.CREATOR }
val user = member(2L, "user")
val existingRoom = room(10L)
Mockito.`when`(memberRepository.findById(2L)).thenReturn(Optional.of(user))
Mockito.`when`(roomRepository.findActiveRoomByParticipantMemberIds(1L, 2L)).thenReturn(existingRoom)
val response = service.createOrGetRoom(creator, 2L)
assertEquals(10L, response.roomId)
Mockito.verify(roomRepository, Mockito.never()).save(Mockito.any(UserCreatorChatRoom::class.java))
Mockito.verifyNoInteractions(messageRepository)
}
```
- [x] **RED 확인:** `./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceTest`를 실행해 누락된 동작 또는 helper compile 실패를 확인한다.
- [x] **GREEN:** 필요하면 `createOrGetRoom(member, creatorId)` 파라미터명을 `recipientId`로 변경한다. 함수 내부 로직은 기존 `memberRepository.findById`, `validateRecipient`, `findActiveRoomByParticipantMemberIds`, participant 저장 흐름을 유지한다.
```kotlin
@Transactional
fun createOrGetRoom(member: Member, recipientId: Long): CreateUserCreatorChatRoomResponse {
val recipient = memberRepository.findById(recipientId).orElseThrow {
SodaException(messageKey = "message.error.recipient_not_found")
}
validateRecipient(member, recipient)
val existingRoom = roomRepository.findActiveRoomByParticipantMemberIds(member.id!!, recipient.id!!)
if (existingRoom != null) {
return CreateUserCreatorChatRoomResponse(roomId = existingRoom.id!!)
}
val room = roomRepository.save(UserCreatorChatRoom())
participantRepository.save(UserCreatorChatParticipant(room, member))
participantRepository.save(UserCreatorChatParticipant(room, recipient))
return CreateUserCreatorChatRoomResponse(roomId = room.id!!)
}
```
- [x] **GREEN 확인:** 같은 focused test를 다시 실행해 성공을 확인한다.
- [x] **REFACTOR:** 파라미터명 변경으로 테스트/문서와 의미가 맞는지 확인하고 새 abstraction 없이 종료한다.
#### Task 1.3 통합 회귀 검증 보강
**Goal 실행 `P1-T3`:** 기존 리스너 시작 흐름과 신규 크리에이터 시작 흐름이 통합 환경에서 모두 동작한다.
- **시작 조건:** `P1-T1`, `P1-T2` 완료.
- **완료 증거:** 통합 테스트와 focused 회귀 명령 통과.
- **범위 밖:** 전체 메시징 E2E, 푸시 발송 검증.
**Files:**
- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/UserCreatorChatServiceIntegrationTest.kt`
- [x] **RED:** 리스너가 `creatorId` alias로 기존처럼 방을 만들 수 있는 통합 회귀 테스트를 작성한다.
- [x] **RED:** 크리에이터가 일반 회원 ID로 방을 만들 수 있는 통합 테스트를 작성한다.
- [x] **RED 확인:** `./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceIntegrationTest`를 실행해 현재 계약 미지원 실패를 확인한다.
- [x] **GREEN:** `P1-T1`, `P1-T2` 구현만으로 통합 테스트를 통과시킨다. 추가 production 코드를 만들지 않는다.
- [x] **GREEN 확인:** 같은 통합 테스트를 다시 실행해 성공을 확인한다.
- [x] **REFACTOR:** 통합 테스트 fixture 중 이번 Task가 만든 중복만 정리한다.
### 완료 조건
- [x] `P1-T1`, `P1-T2`, `P1-T3`의 체크박스와 완료 증거가 모두 충족됐다.
- [x] PRD `DMROOM-001~007`이 구현 또는 명시적 제외로 추적된다.
- [x] 기존 `creatorId` 요청과 신규 `recipientId` 요청의 차이가 문서와 테스트에 남아 있다.
### 검증 방법
#### Phase 1 Gate
**Goal 실행 `P1-GATE`:** `/create` request 호환성, 방 생성 정책, 메시지 비생성 정책을 최종 판정한다.
- **시작 조건:** Phase 1의 모든 Task goal 완료.
- **완료 증거:** 아래 명령 통과와 Progress 기록.
- **범위 밖:** 실패와 무관한 채팅방 목록, openRoom 응답, WebSocket 기능 수정.
```bash
./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatControllerMappingTest
./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceTest
./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceIntegrationTest
./gradlew ktlintCheck
```
**Expected:** 모든 명령이 `BUILD SUCCESSFUL`이고, `/create` 호출만으로 메시지 저장/전달/푸시가 발생하지 않는 테스트가 통과한다.
## 실행 순서와 의존성
| 순서 | Goal | 선행조건 | 병행 가능 | 차단 시 다음 행동 |
|---:|---|---|---|---|
| 1 | `P1-T1` | PRD 확정 | 아니요 | request 계약 재확인 |
| 2 | `P1-T2` | `P1-T1` | 아니요 | 기존 service 정책 대조 |
| 3 | `P1-T3` | `P1-T1`, `P1-T2` | 아니요 | 통합 fixture 보정 |
| 4 | `P1-GATE` | Phase 1 Task 전체 | 아니요 | 실패 소유 Task로 회귀 수정 |
```text
P1-T1 → P1-T2 → P1-T3 → P1-GATE
```
## 변경 금지 항목
- `/create`에서 메시지를 저장하거나 발송하지 않는다.
- 기존 `creatorId` request를 제거하지 않는다.
- `CreateUserCreatorChatRoomResponse` 필드를 바꾸지 않는다.
- DB schema, WebSocket message type, FCM event 계약을 변경하지 않는다.
- test를 삭제·skip·완화하지 않는다.
- 요청 범위 밖 리팩터링과 공용 abstraction을 추가하지 않는다.
## Progress
기존 기록을 삭제하거나 덮어쓰지 않고 실제 실행 결과를 차수별로 누적한다.
### P1-T1 1차 실행 — 2026-09-14
- 상태: 완료
- 무엇을: `CreateUserCreatorChatRoomRequest`에 `recipientId` 표준 필드와 `creatorId` alias를 추가하고, controller가 `recipientMemberId()` 결과를 service에 전달하도록 구현했다.
- 왜: `DMROOM-001~004`, `DEC-003` 기준으로 신규 클라이언트와 기존 클라이언트 request를 모두 지원하기 위해서다.
- 어떻게:
- `./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatControllerMappingTest` — RED 확인, `recipientId` 생성자 파라미터와 `recipientMemberId()` 부재로 `compileTestKotlin` 실패.
- `./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatControllerMappingTest` — GREEN 확인, `BUILD SUCCESSFUL`.
- 남은 항목: 없음.
- 다음 행동: `P1-T2` 진행.
### P1-T2 1차 실행 — 2026-09-14
- 상태: 완료
- 무엇을: 크리에이터 시작 DM 방 생성, 기존 방 재사용, `/create` 메시지 미생성 정책을 `UserCreatorChatServiceTest`로 고정했다. production service는 파라미터명만 `recipientId`로 정리했다.
- 왜: `DMROOM-005~007`, `DEC-001`, `DEC-002` 기준으로 기존 수신자 검증과 메시지 발송 분리 정책을 유지하기 위해서다.
- 어떻게:
- `./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceTest` — `BUILD SUCCESSFUL`.
- 남은 항목: 없음.
- 다음 행동: `P1-T3` 진행.
### P1-T3 1차 실행 — 2026-09-14
- 상태: 완료
- 무엇을: 리스너 시작 기존 흐름과 크리에이터 시작 신규 흐름을 `UserCreatorChatServiceIntegrationTest`에 추가했다.
- 왜: 실제 JPA 통합 환경에서 양방향 방 생성과 메시지 미생성을 확인하기 위해서다.
- 어떻게:
- `./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceIntegrationTest` — `BUILD SUCCESSFUL`.
- 남은 항목: 없음.
- 다음 행동: `P1-GATE` 진행.
### P1-GATE 1차 실행 — 2026-09-14
- 상태: 차단 감사 중
- 무엇을: Phase 1 focused test와 lint를 검증하고 전체 build를 시도했다.
- 왜: `/create` request 호환성, 방 생성 정책, 메시지 비생성 정책과 공통 품질 기준을 판정하기 위해서다.
- 어떻게:
- `./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatControllerMappingTest --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceTest --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceIntegrationTest` — `BUILD SUCCESSFUL`.
- `./gradlew ktlintCheck` — 최초 import 정렬 오류로 실패 후 수정, 재실행 `BUILD SUCCESSFUL`.
- `./gradlew build` — 120초 timeout, 재시도 600초 timeout. 두 번 모두 `:test` 단계에서 종료되지 않아 전체 build 성공 증거는 확보하지 못했다.
- 남은 항목: 전체 build timeout 원인 분리 또는 별도 승인.
- 다음 행동: 변경 범위 리뷰와 전체 suite hang 원인 보고.
## Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 Goal/문서 |
|---|---|---|---|---|---|
| 2026-09-14 | `DEC-001` | 확정 | `/create`는 방 생성/조회만 처리한다. | 사용자 선택 A | `P1-T2`, PRD `DEC-001` |
| 2026-09-14 | `DEC-002` | 확정 | 수신자는 `MemberRole` 제한 없이 기존 수신자 검증 정책을 따른다. | 사용자 선택 B | `P1-T2`, PRD `DEC-002` |
| 2026-09-14 | `DEC-003` | 확정 | `recipientId`를 표준 필드로 추가하고 `creatorId` alias를 유지한다. | 기존 클라이언트 호환 필요 | `P1-T1`, PRD `DEC-003` |
## 발견된 문제
| ID | 심각도 | 상태 | 발견 내용 | 영향 Goal | 처리 계획 |
|---|---|---|---|---|---|
| 없음 | - | - | - | - | - |
@@ -1,159 +0,0 @@
# PRD: 크리에이터 시작 DM 방 생성
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | 구현 기준 확정 |
| 작성일 | 2026-09-14 |
| 최종 수정일 | 2026-09-14 |
| 대상 제품 | 유저-크리에이터 DM |
| 작성자·결정권자 | 사용자 인터뷰 기준 |
| 관련 구현 계획 | `docs/20260914_크리에이터_리스너_DM방_생성/plan-task.md` |
| 관련 review | 없음 |
## 1. Overview
현재 `POST /api/v2/user-creator-chat/rooms/create`는 일반 유저가 크리에이터에게 DM을 시작할 때 방을 생성하거나 기존 방을 반환한다. 이번 요구사항은 같은 DM 도메인에서 크리에이터도 상대 회원에게 먼저 DM 방을 만들 수 있게 하는 것이다.
첫 메시지 저장, 실시간 전달, 푸시는 이번 API에서 처리하지 않는다. 방 생성 후 메시지는 기존 WebSocket 텍스트 발송 또는 기존 메시지 발송 흐름을 사용한다.
## 2. Problem Statement
- 현재 생성 요청 DTO는 `creatorId`만 받기 때문에 API 의미가 “일반 유저가 크리에이터에게 DM 시작”에 고정되어 있다.
- 크리에이터가 먼저 상대 회원에게 연락하려면 같은 유저-크리에이터 DM 방을 만들 수 있는 서버 계약이 필요하다.
- 기존 클라이언트는 이미 `creatorId`를 보내고 있으므로, 새 필드만 강제하면 기존 리스너 시작 DM 생성 흐름이 깨진다.
문제 해결 여부는 신규 클라이언트가 `recipientId`로 방을 만들 수 있고, 기존 클라이언트가 `creatorId`로 같은 API를 계속 사용할 수 있는지로 판단한다.
## 3. Goals
- `POST /api/v2/user-creator-chat/rooms/create`가 발신자 역할과 무관하게 상대 회원 ID로 DM 방을 생성하거나 기존 방을 반환한다.
- 신규 표준 request 필드는 `recipientId`로 한다.
- 기존 클라이언트 호환을 위해 `creatorId` request 필드는 alias로 유지한다.
- 기존 리스너 → 크리에이터 방 생성 흐름은 계속 동작한다.
- 크리에이터 → 상대 회원 방 생성 흐름도 같은 참여자/중복 방 정책을 따른다.
## 4. Non-Goals
- `/create`에서 첫 텍스트 메시지를 저장하거나 발송하지 않는다.
- `/create`에서 WebSocket 메시지를 대신 보내지 않는다.
- FCM 푸시 발송 정책은 변경하지 않는다.
- DB 스키마를 변경하지 않는다.
- 새 endpoint를 만들지 않는다.
- 기존 `roomId` 응답 구조를 변경하지 않는다.
- `creatorId` alias 제거 시점이나 클라이언트 마이그레이션 일정은 이번 범위에서 정하지 않는다.
## 5. Target Users and Permissions
| 사용자 | 목표 | 주요 작업 | 사용 환경 |
|---|---|---|---|
| 리스너/일반 유저 | 크리에이터에게 먼저 DM 시작 | 상대 회원 지정 후 방 생성 | 모바일 클라이언트 |
| 크리에이터 | 상대 회원에게 먼저 DM 시작 | 상대 회원 지정 후 방 생성 | 모바일 클라이언트 |
권한과 거부 조건:
- 인증 주체: 로그인 `Member`
- 허용 역할: 별도 `MemberRole` 제한 없음
- 수신자 조건: 활성 회원, AI 캐릭터 아님, 자기 자신 아님, 차단 정책 통과
- 미인증: 기존처럼 `common.error.bad_credentials`
- 수신자 없음 또는 AI 캐릭터: 기존 정책에 맞춰 `message.error.recipient_not_found`
- 비활성 수신자: 기존처럼 `message.error.recipient_inactive`
- 자기 자신: 기존처럼 `common.error.invalid_request`
- 상대가 발신자를 차단한 경우: 기존처럼 `message.error.blocked_by_recipient`
## 6. 핵심 사용자 흐름
1. 인증 회원이 DM을 시작할 상대 회원을 선택한다.
2. 클라이언트는 `POST /api/v2/user-creator-chat/rooms/create`에 `recipientId`를 보낸다.
3. 서버는 기존 alias인 `creatorId`만 온 요청도 허용한다.
4. 서버는 발신자와 수신자 사이의 활성 DM 방이 있으면 기존 `roomId`를 반환한다.
5. 활성 DM 방이 없으면 방과 두 참여자를 생성하고 새 `roomId`를 반환한다.
6. 클라이언트는 반환된 `roomId`로 기존 방 입장 및 메시지 발송 흐름을 진행한다.
## 7. 기능 요구사항
| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 |
|---|---|---|---|---|
| `DMROOM-001` | 확정 | `/create`는 `recipientId`를 표준 상대 회원 ID로 받아 방을 생성/조회한다. | `recipientId`만 보낸 요청이 기존 `roomId` 응답을 받는다. | `P1-T1` |
| `DMROOM-002` | 확정 | 기존 클라이언트 호환을 위해 `creatorId`만 보낸 요청도 계속 허용한다. | 기존 `creatorId` request가 깨지지 않고 동일한 서비스 흐름을 탄다. | `P1-T1` |
| `DMROOM-003` | 확정 | `recipientId`와 `creatorId`가 모두 없으면 잘못된 요청으로 거부한다. | `common.error.invalid_request`로 실패한다. | `P1-T1` |
| `DMROOM-004` | 확정 | 두 필드가 모두 있고 값이 다르면 모호한 요청으로 거부한다. | `common.error.invalid_request`로 실패하고 방을 만들지 않는다. | `P1-T1` |
| `DMROOM-005` | 확정 | 수신자 권한/상태 검증은 기존 `validateRecipient` 정책을 재사용한다. | 비활성, AI 캐릭터, 자기 자신, 차단 관계의 기존 오류 key가 유지된다. | `P1-T2` |
| `DMROOM-006` | 확정 | 기존 활성 방이 있으면 새 방을 만들지 않고 기존 `roomId`를 반환한다. | 같은 두 회원으로 두 번 호출해도 활성 방은 1개다. | `P1-T2` |
| `DMROOM-007` | 확정 | `/create`는 첫 메시지 저장/전달/푸시를 수행하지 않는다. | 방 생성 후 `UserCreatorChatMessage`가 생성되지 않는다. | `P1-T2` |
## 8. API 계약
### 8.1 Endpoint
- Method: `POST`
- Path: `/api/v2/user-creator-chat/rooms/create`
- Auth: 로그인 회원 필수
- Success envelope: 기존 `ApiResponse.ok(...)`
### 8.2 Request
```json
{
"recipientId": 200,
"creatorId": 200
}
```
- `recipientId`: 신규 표준 필드. 발신자 반대편 회원 ID다.
- `creatorId`: 기존 클라이언트 호환용 alias. 신규 클라이언트는 `recipientId`를 사용한다.
- 둘 중 하나만 보내는 요청을 허용한다.
- 둘 다 보내는 경우 값이 같으면 허용한다.
- 둘 다 보내는 경우 값이 다르면 `common.error.invalid_request`로 거부한다.
- 둘 다 없으면 `common.error.invalid_request`로 거부한다.
### 8.3 Response
```json
{
"roomId": 123
}
```
- 응답 DTO `CreateUserCreatorChatRoomResponse`의 필드는 변경하지 않는다.
## 9. 보안과 데이터 취급
- 수신자 ID는 요청 본문 외 로그에 별도 기록하지 않는다.
- 차단 정책은 기존 `BlockMemberRepository.isBlocked(blockedMemberId = sender.id, memberId = recipient.id)` 기준을 유지한다.
- AI 캐릭터용 `Member`와의 DM 방은 계속 생성하지 않는다.
- 공개 API 스키마에서 기존 필드 제거는 금지한다.
## 10. 성공 기준
- [x] 신규 `recipientId` 요청으로 크리에이터가 상대 회원과 DM 방을 만들 수 있다.
- [x] 기존 `creatorId` 요청으로 리스너가 크리에이터와 DM 방을 만들 수 있다.
- [x] 같은 두 회원의 중복 요청은 같은 활성 `roomId`를 반환한다.
- [x] `/create` 호출만으로 메시지, WebSocket 전달, FCM 푸시가 발생하지 않는다.
- [x] 오류 key는 기존 정책과 호환된다.
## 11. Open Questions
없음. 인터뷰로 아래 결정을 확정했다.
## 12. 요구사항 추적표
| 요구사항 범위 | 계획 Phase | Goal | 자동 검증 | 수동 검증 |
|---|---:|---|---|---|
| `DMROOM-001~004` | 1 | `P1-T1` | `UserCreatorChatControllerMappingTest`, `UserCreatorChatServiceTest` | request alias 계약 대조 |
| `DMROOM-005~007` | 1 | `P1-T2` | `UserCreatorChatServiceTest`, `UserCreatorChatServiceIntegrationTest` | 기존 메시지 발송 흐름 분리 확인 |
## 13. Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항·계약·Goal |
|---|---|---|---|---|---|
| 2026-09-14 | `DEC-001` | 확정 | `/create`는 방 생성/조회만 처리하고 첫 메시지는 발송하지 않는다. | 사용자 선택 A | `DMROOM-007`, `P1-T2` |
| 2026-09-14 | `DEC-002` | 확정 | 수신자는 `MemberRole`로 제한하지 않고 활성/AI 아님/자기 자신 아님/차단 정책으로 제한한다. | 사용자 선택 B, 기존 `validateRecipient` 정책 | `DMROOM-005`, `P1-T2` |
| 2026-09-14 | `DEC-003` | 확정 | 신규 표준 필드는 `recipientId`로 하고 기존 `creatorId`는 alias로 유지한다. | 기능 의미는 A가 맞지만 기존 클라이언트 동작 보존 필요 | `DMROOM-001~004`, `P1-T1` |
## 14. 변경 관리
- 코드 구현 전 `plan-task.md`의 체크박스와 Goal 단위를 따른다.
- 구현 중 API 계약이 바뀌면 이 PRD의 Decision Log를 먼저 갱신한다.
- 기존 `creatorId` alias를 제거하려면 별도 PRD와 클라이언트 마이그레이션 계획을 작성한다.
@@ -1,357 +0,0 @@
# 라이브 크리에이터 입장 제한 구현 계획
> **For agentic workers:** REQUIRED SUB-SKILL: Use `subagent-driven-development` or `executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
| 문서 항목 | 내용 |
|---|---|
| 상태 | Phase 1~3 구현 및 검증 완료 |
| 작성일 | `2026-09-17` |
| 요구사항 기준 | `docs/20260917_라이브_크리에이터_입장제한/prd.md` |
| API 기준 | 기존 API 응답 스키마 변경 없음 |
| 현재 Phase | 완료 |
| 현재 활성 Goal | 없음 |
| 다음 Goal | 없음 |
## 목표
다른 크리에이터가 `isAvailableJoinCreator = false` 라이브 방을 볼 수도, 직접 입장할 수도 없게 하고, 입장 가능 성별(`genderRestriction`)도 조회와 입장 경계에서 일관되게 적용한다.
## 현재 상태
| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
|---:|---|---:|---|---|
| 1 | 완료 | `2/2` | 없음 | 없음 |
| 2 | 완료 | `1/1` | 없음 | 없음 |
| 3 | 완료 | `2/2` | 없음 | 없음 |
## 범위
### 포함
- `v2` 홈 추천/온에어 라이브 조회의 `isAvailableJoinCreator` 및 `genderRestriction` 필터 누락 보정.
- `v2` 크리에이터 채널 라이브 탭의 조회자 크리에이터 판정 보정.
- `/live/room/enter`에서 다른 크리에이터의 제한 방 직접 입장 차단과 기존 성별 입장 차단 회귀 검증.
- focused test와 직접 영향 회귀 검증.
- 후속 리뷰 `REV-001`: `/live/room/info/{id}`의 토큰 발급 전 크리에이터·성별 제한 적용.
- 후속 리뷰 `REV-002`: 채널 소유자 본인의 제한 방 조회를 repository 회귀 테스트로 고정.
### 제외
- 공개 API DTO 필드 추가/삭제.
- DB schema 변경.
- 기존 성인/성별/차단/강퇴/비공개/결제 정책 재설계.
- 관리자용 라이브 조회 정책 변경.
## 기술적 제약
- 기술 스택: Kotlin, Spring Boot 2.7.14, QueryDSL, Gradle Wrapper.
- 기존 QueryDSL 조건 패턴을 재사용하고 새 abstraction은 만들지 않는다.
- 크리에이터 제한 조건은 `isViewerCreator && memberId != null`일 때만 적용하며, 방 생성자는 `liveRoom.member.id.eq(memberId)`로 예외 처리한다.
- 성별 제한 조건은 기존 조회 경로와 같은 정책을 따른다. `Gender.MALE`은 `ALL`, `MALE_ONLY`, `Gender.FEMALE`은 `ALL`, `FEMALE_ONLY`, `Gender.NONE` 또는 비로그인/null 유효 성별은 필터 없음이다.
- 방 생성자 본인은 성별 제한 조건에서도 `liveRoom.member.id.eq(memberId)`로 예외 처리한다.
- 모든 production 변경 Task는 `RED → GREEN → REFACTOR` 순서로 진행한다.
- 공개 API schema 변경은 금지한다.
## Phase 1: 리스트 노출 제한 보정
**Phase 결과:** 다른 크리에이터가 문제 의심 리스트 경로에서 제한 방을 받지 않고, 성별 제한에 맞지 않는 사용자가 v2 홈 추천/온에어 라이브에서 제한 방을 받지 않는다.
**선행조건:** PRD 확정.
**Phase 완료 조건:** `P1-T1`, `P1-T2`, `P1-GATE` 완료 및 검증 기록 누적.
### 구현 항목
#### Task 1.1 v2 홈 추천/온에어 라이브 필터 적용
**Goal 실행 `P1-T1`:** `findLiveRecommendations()` 계열 호출에서 조회자 크리에이터 여부와 유효 성별을 전달하고 QueryDSL 필터를 적용한다.
- **시작 조건:** `LCR-001` 확정.
- **완료 증거:** 다른 크리에이터가 제한 방을 받지 않고, 성별 제한에 맞지 않는 사용자가 제한 방을 받지 않으며, 방 생성자 본인은 예외인 focused test 통과.
- **범위 밖:** `/live/room/enter` 입장 차단.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/port/out/HomeRecommendationQueryPort.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/application/HomeRecommendationQueryService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacade.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/home/live/application/HomeOnAirLiveFacade.kt`
- Test: repository/service 기존 테스트 위치를 우선 확인하고, 없으면 `src/test/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepositoryTest.kt`
**Interfaces:**
- `findLiveRecommendations(offset, limit, memberId, includeAdultLives, isViewerCreator, effectiveViewerGender)` 형태로 파라미터를 추가한다.
- `isViewerCreator` 기본값은 `false`로 둬 snapshot refresh 등 기존 호출을 보존한다.
- `effectiveViewerGender` 기본값은 `null`로 둬 비로그인/성별 미설정과 snapshot refresh 등 기존 호출을 보존한다.
- `HomeRecommendationFacade`와 `HomeOnAirLiveFacade`는 `member.auth?.gender` 우선, 없으면 `member.gender`로 기존 경로와 같은 유효 성별을 계산해 전달한다.
- [x] **RED:** 크리에이터 조회자에게 `isAvailableJoinCreator = false` 라이브가 제외되는 테스트, 성별 제한에 맞지 않는 조회자에게 `genderRestriction` 제한 라이브가 제외되는 테스트, 방 생성자 본인은 포함되는 테스트를 작성한다.
- [x] **RED 확인:** `./gradlew test --tests '*DefaultHomeRecommendationQueryRepositoryTest'`를 실행해 필터 미구현으로 크리에이터 제한 방 또는 성별 제한 방이 포함되는 assertion 실패를 확인한다.
- [x] **GREEN:** `HomeRecommendationQueryPort`, `HomeRecommendationQueryService`, `DefaultHomeRecommendationQueryRepository`, `HomeRecommendationFacade`, `HomeOnAirLiveFacade`에 `isViewerCreator`, `effectiveViewerGender` 전달과 조건을 최소 추가한다.
- [x] **GREEN 확인:** `./gradlew test --tests '*DefaultHomeRecommendationQueryRepositoryTest'`를 다시 실행해 성공을 확인한다.
- [x] **REFACTOR:** 이번 Task가 만든 중복만 정리하고 `./gradlew ktlintCheck` 및 focused test 결과를 Progress에 기록한다.
#### Task 1.2 v2 크리에이터 채널 라이브 탭 판정 보정
**Goal 실행 `P1-T2`:** 크리에이터 채널 라이브 탭에서 “조회자가 크리에이터인지” 기준으로 제한 방 노출을 막는다.
- **시작 조건:** `LCR-002` 확정.
- **완료 증거:** 다른 크리에이터는 제한 방을 받지 않고 방 생성자 본인은 받을 수 있는 focused test 통과.
- **범위 밖:** 크리에이터 채널 홈은 이미 `viewer.role == MemberRole.CREATOR`를 사용하므로 변경하지 않는다.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/live/application/CreatorChannelLiveQueryService.kt`
- Test: 기존 테스트 위치를 우선 확인하고, 없으면 `src/test/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/live/application/CreatorChannelLiveQueryServiceTest.kt`
**Interfaces:**
- `queryPort.findCurrentLive(..., isViewerCreator = viewer.role == MemberRole.CREATOR, ...)`로 전달한다.
- repository의 기존 `creatorJoinLiveCondition(viewerId, isViewerCreator)`와 본인 예외는 유지한다.
- [x] **RED:** 다른 크리에이터 viewer가 `isAvailableJoinCreator = false` 현재 라이브를 받지 않는 service test를 작성한다.
- [x] **RED 확인:** `./gradlew test --tests '*CreatorChannelLiveQueryServiceTest'`를 실행해 기존 `viewerId == creatorId` 판정 때문에 제한 방이 반환되는 assertion 실패를 확인한다.
- [x] **GREEN:** `CreatorChannelLiveQueryService`의 `isViewerCreator` 계산을 `viewer.role == MemberRole.CREATOR`로 변경한다.
- [x] **GREEN 확인:** 같은 focused test를 다시 실행해 성공을 확인한다.
- [x] **REFACTOR:** 중복 정리 없이 끝낼 수 있으면 그대로 두고 focused test 및 `./gradlew ktlintCheck` 결과를 Progress에 기록한다.
### 검증 방법
#### Phase 1 Gate
**Goal 실행 `P1-GATE`:** 리스트 노출 제한과 성별 제한 경로가 PRD 요구사항과 일치하는지 판정한다.
- **시작 조건:** `P1-T1`, `P1-T2` 완료.
- **완료 증거:** 아래 명령 통과와 수동 대조 기록.
- **범위 밖:** 입장 차단 구현.
```bash
./gradlew test --tests '*DefaultHomeRecommendationQueryRepositoryTest' --tests '*CreatorChannelLiveQueryServiceTest'
./gradlew ktlintCheck
```
**Expected:** focused test와 ktlint가 0 exit code로 종료한다.
수동 대조:
- [x] `HomeFollowingQueryService`와 `CreatorChannelHomeQueryService`의 기존 정상 조건은 변경하지 않았음을 확인한다.
- [x] `HomeRecommendationFacade.getHomeRecommendations`, `HomeRecommendationFacade.getLives`, `HomeOnAirLiveFacade.getOnAirLives`가 모두 조회자 크리에이터 여부와 유효 성별을 전달함을 확인한다.
## Phase 2: 직접 입장 차단
**Phase 결과:** 다른 크리에이터가 제한 방 ID를 알고 있어도 `/live/room/enter`로 입장할 수 없고, 성별 제한에 맞지 않는 사용자의 직접 입장도 기존 정책대로 차단된다.
**선행조건:** `P1-GATE` 완료.
**Phase 완료 조건:** `P2-T1`, `P2-GATE` 완료 및 검증 기록 누적.
### 구현 항목
#### Task 2.1 `/live/room/enter` 크리에이터 제한 차단 및 성별 제한 회귀 검증
**Goal 실행 `P2-T1`:** `LiveRoomService.enterLive()`에서 다른 크리에이터의 제한 방 입장을 결제/roomInfo 변경 전 차단하고, 기존 성별 제한 입장 차단을 회귀 테스트로 고정한다.
- **시작 조건:** `LCR-003` 확정, `P1-GATE` 완료.
- **완료 증거:** 다른 크리에이터는 예외, 성별 제한에 맞지 않는 사용자는 `live.room.gender_restricted` 예외, 방 생성자 본인과 일반 유저는 기존 정책 유지 test 통과.
- **범위 밖:** error envelope schema 변경.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/live/room/LiveRoomService.kt`
- Test: 기존 테스트 위치를 우선 확인하고, 없으면 `src/test/kotlin/kr/co/vividnext/sodalive/live/room/LiveRoomServiceTest.kt`
- Optional Modify: 메시지 key 추가가 필요하다고 확인될 때만 `src/main/resources/messages*.properties` 계열 파일
**Implementation rule:**
`enterLive()`에서 room 조회 후, 결제나 `LiveRoomInfo` 변경 전에 아래 의미의 조건을 추가한다.
```kotlin
if (
member.role == MemberRole.CREATOR &&
room.member!!.id!! != member.id!! &&
!room.isAvailableJoinCreator
) {
throw SodaException(messageKey = "live.room.not_found")
}
```
기존 message key 재사용이 부적절하다고 확인되면 PRD와 plan-task를 먼저 갱신한 뒤 새 message key를 추가한다.
성별 제한은 현재 구현된 아래 의미의 조건을 유지한다. 이 작업에서는 해당 조건을 약화하지 말고 회귀 테스트로 고정한다.
```kotlin
if (room.member!!.id!! != member.id!! && !member.canEnter(room.genderRestriction)) {
throw SodaException(messageKey = "live.room.gender_restricted")
}
```
- [x] **RED:** 다른 크리에이터가 `isAvailableJoinCreator = false` 방에 입장하면 예외가 발생하고 `roomInfoRepository.save`와 `canPaymentService.spendCan`이 호출되지 않는 테스트를 작성한다. 성별 제한에 맞지 않는 사용자가 입장하면 `live.room.gender_restricted` 예외가 발생하는 회귀 테스트도 작성한다.
- [x] **RED 확인:** `./gradlew test --tests '*LiveRoomServiceTest'`를 실행해 기존 구현이 입장을 허용하거나 후속 저장을 호출하는 assertion 실패를 확인한다.
- [x] **GREEN:** `LiveRoomService.enterLive()`에 최소 조건을 추가한다.
- [x] **GREEN 확인:** 같은 focused test를 다시 실행해 성공을 확인한다.
- [x] **REFACTOR:** 방 생성자 본인, 일반 유저, `Gender.NONE` 사용자 회귀 테스트를 함께 실행하고 `./gradlew ktlintCheck` 결과를 Progress에 기록한다.
### 검증 방법
#### Phase 2 Gate
**Goal 실행 `P2-GATE`:** 입장 차단, 리스트 노출 차단, 성별 제한 전체 흐름을 최종 판정한다.
- **시작 조건:** `P2-T1` 완료.
- **완료 증거:** 아래 명령 통과와 계획 문서 Progress 기록.
- **범위 밖:** 실패 test 삭제·완화, 무관한 리팩터링.
```bash
./gradlew test --tests '*DefaultHomeRecommendationQueryRepositoryTest' --tests '*CreatorChannelLiveQueryServiceTest' --tests '*LiveRoomServiceTest'
./gradlew ktlintCheck
./gradlew test
```
**Expected:** focused test, ktlint, 전체 test가 0 exit code로 종료한다. 크리에이터 제한과 성별 제한이 모두 조회/입장 경계에서 검증된다. 전체 test가 환경 문제로 실패하면 실패 원인과 focused/영향 범위 대체 검증을 Progress에 기록한다.
## Phase 3: 후속 리뷰 항목 구현
**근거:** `reviews/현재변경사항-review.md`의 `REV-001`, `REV-002` 및 두 항목을 후속 구현사항으로 추가하라는 사용자 요청.
**Phase 결과:** 제한 사용자는 방 정보 API로 토큰을 발급받지 못하고, 채널 소유자 본인의 제한 방 조회는 실제 repository 테스트로 보장된다.
**선행조건:** Phase 1~2 완료 및 후속 리뷰 확인. 기존 완료 체크박스와 검증 기록은 유지한다.
**Phase 완료 조건:** `P3-T1`, `P3-T2`, `P3-GATE` 완료와 실행 증거 기록.
### Task 3.1 토큰 발급 경계의 입장 제한 보강
- [x] **Task 3.1 완료**
**Goal 실행 `P3-T1`:** `REV-001`에 따라 `getRoomInfo()`에서 토큰 생성 전에 크리에이터·성별 제한을 적용하고 허용 사용자 회귀를 검증한다.
- **시작 조건:** `REV-001`의 제한 검사 누락 확인. 실제 RTC 우회 접속은 아직 재현되지 않았으므로 서버의 토큰 생성 호출 여부부터 검증한다.
- **완료 증거:** 제한 사용자에 대한 실패 테스트 → 최소 수정 후 예외 key 및 RTC/RTM 생성기 무호출 검증 → 소유자·허용 사용자 회귀 통과.
- **범위 밖:** 새로운 입장 완료 여부 검사, 성인/비공개/결제 정책 재설계, 기존 발급 토큰 회수, Agora SDK 변경, API/DB 스키마 변경.
**Files:**
- Modify: `docs/20260917_라이브_크리에이터_입장제한/prd.md` — LCR-003 및 성공 기준에 방 정보 API의 토큰 발급 경계를 명시.
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/live/room/LiveRoomService.kt` — `getRoomInfo()`.
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/live/room/LiveRoomServiceTest.kt`.
- Read: `src/main/kotlin/kr/co/vividnext/sodalive/live/room/LiveRoomController.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/member/Member.kt`.
**구현 기준:** 기존 방/roomInfo 존재 및 상호 차단 검사를 유지하고 첫 토큰 생성 호출 전에 `/enter`와 동일한 조건을 적용한다. 다른 크리에이터의 제한 방 접근은 `live.room.not_found`, 다른 사용자의 성별 불일치는 `live.room.gender_restricted`로 거절한다. 두 제한이 겹치면 크리에이터 제한을 먼저 판정한다. 생성자는 두 제한의 예외이며 성별은 `Member.canEnter()`를 재사용해 인증 성별 우선 및 `Gender.NONE` 허용 정책을 유지한다. RTC, RTM, v2v 토큰 모두 제한 검사를 통과한 뒤에만 생성한다.
- [x] **문서 정합성:** production 수정 전에 기존 PRD의 LCR-003, 관련 흐름·성공 기준에 토큰 발급 제한을 반영하고 후속 검증 항목은 미완료로 둔다.
- [x] **RED:** roomInfo와 room이 존재하고 차단 관계가 없는 fixture에서 다른 크리에이터의 제한 방 접근 및 성별 불일치 접근을 테스트한다. 토큰 생성기는 테스트용 문자열을 반환하도록 준비하고 정상 응답 구성에 필요한 의존성도 설정해, 무관한 null 오류가 아닌 예상 예외 미발생으로 실패하는지 확인한다.
- [x] **GREEN:** 위 조건을 최소 추가하고 예외 key, `rtcTokenBuilder`와 `rtmTokenBuilder`의 무호출을 검증한다. `/enter` 거절 후 `/info/{id}`에 해당하는 서비스 호출도 토큰을 생성하지 않는지 확인한다.
- [x] **회귀:** 소유자는 크리에이터·성별 제한이 모두 걸려도 허용되고, 일반 사용자와 허용 방의 다른 크리에이터는 성별이 맞으면 응답을 받는다. 인증 성별 우선, `Gender.NONE` 허용, 기존 상호 차단 거절을 확인한다.
- [x] **REFACTOR/기록:** 불필요한 추상화 없이 기존 스타일을 유지하고 아래 명령의 결과와 무엇을/왜/어떻게 검증했는지를 이 Task 아래에 누적한다.
```bash
./gradlew test --tests '*LiveRoomServiceTest' --tests '*LiveRoomServiceAdultVisibilityPolicyTest'
```
**Expected:** RED 단계는 제한 검사 누락으로 실패하고, GREEN 이후는 exit 0. 차단 경로에서는 토큰이 생성되지 않는다.
**검증 기록 (2026-09-17):** `LiveRoomServiceTest`에 정상 응답 fixture와 제한·허용 회귀 10건을 추가했다. RED에서 다른 크리에이터, 성별 불일치, 중첩 제한, `/enter` 거절 후 정보 조회 테스트가 모두 예상 `SodaException` 미발생으로 실패했다. `getRoomInfo()`의 기존 상호 차단 검사 뒤와 모든 RTC/RTM/v2v 토큰 생성 앞에 `/enter`와 동일한 크리에이터·성별 조건을 추가한 뒤 `./gradlew test --rerun-tasks --tests '*LiveRoomServiceTest' --tests '*LiveRoomServiceAdultVisibilityPolicyTest'`가 20건 모두 통과하며 `BUILD SUCCESSFUL`로 종료했다. 거절 경로의 token builder 무호출과 소유자·성별 일치 사용자·허용 방 크리에이터·인증 성별 우선·`Gender.NONE`·기존 상호 차단 회귀를 확인했다. 실제 HTTP/RTC 연결은 검증하지 않았다. P3-T1 리뷰 결과 Blocker는 0건이다.
### Task 3.2 채널 소유자 제한 방 조회 회귀 테스트
- [x] **Task 3.2 완료**
**Goal 실행 `P3-T2`:** `REV-002`에 따라 채널 소유자 본인이 `isAvailableJoinCreator = false`인 현재 방을 조회할 수 있음을 H2 repository 테스트로 고정한다.
- **시작 조건:** `REV-002` 확인. 기본 실행 순서는 `P3-T1` 이후이며 파일 변경은 독립적이다.
- **완료 증거:** 실제 repository의 `findCurrentLive()` 결과가 생성한 제한 방 ID와 일치하고 기존 타인 필터 테스트도 통과한다.
- **범위 밖:** production 조회 조건 수정, 채널 API/DTO 변경, 조회 정책 재설계.
**Files:**
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/live/adapter/out/persistence/DefaultCreatorChannelLiveQueryRepositoryTest.kt`.
- Read: `src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/live/adapter/out/persistence/DefaultCreatorChannelLiveQueryRepository.kt`.
**TDD 예외 사유:** 소유자 예외는 이미 구현돼 있고 이번 Task는 누락된 테스트만 추가한다. RED를 만들기 위해 정상 production 코드를 변경하지 않는다. 대체 검증은 실제 H2 조회 결과 assertion과 기존 타인 제외 테스트의 동시 통과다.
- [x] **테스트 추가:** 기존 fixture로 활성·비성인·유효 channelName의 현재 방을 생성하고 `isAvailableJoinCreator = false`로 설정한다. `flushAndClear()` 후 `viewerId == creatorId`, `isViewerCreator = true`, 성별 제한과 일치하는 유효 성별로 조회해 방 ID를 단정한다.
- [x] **GREEN:** 아래 focused test로 소유자 조회와 기존 타인 제외 동작이 함께 통과하는지 확인한다.
- [x] **REFACTOR/기록:** 기존 fixture를 재사용하고 이 Task 아래에 명령과 검증 결과를 누적한다. 예상 밖 실패는 원인을 판정한 뒤 production 수정이 필요하면 먼저 Task 범위를 갱신한다.
```bash
./gradlew test --tests '*DefaultCreatorChannelLiveQueryRepositoryTest' --tests '*CreatorChannelLiveQueryServiceTest'
```
**Expected:** exit 0. 소유자에게 제한 방이 반환되고 다른 크리에이터에게는 기존대로 제외된다.
**검증 기록 (2026-09-17):** production 조건은 변경하지 않고 `DefaultCreatorChannelLiveQueryRepositoryTest.shouldReturnRestrictedCurrentLiveForChannelOwner`를 추가했다. 활성·비성인·유효 channelName·`isAvailableJoinCreator = false`·`MALE_ONLY` 방을 실제 H2에 저장하고 `viewerId == creatorId`, `isViewerCreator = true`, `Gender.MALE`로 조회해 생성한 방 ID를 단정했다. `./gradlew test --rerun-tasks --tests '*DefaultCreatorChannelLiveQueryRepositoryTest' --tests '*CreatorChannelLiveQueryServiceTest'`가 기존 다른 크리에이터 제외 테스트와 함께 `BUILD SUCCESSFUL`로 종료했다. `git diff --check`도 통과했다.
### Phase 3 Gate
**Goal 실행 `P3-GATE`:** 후속 두 항목과 기존 목록·입장 정책의 회귀 검증을 완료한다.
- **시작 조건:** `P3-T1`, `P3-T2` 완료.
- **완료 증거:** 아래 명령 exit 0, 토큰 생성 전 제한 검사 수동 대조, 소유자 조회 assertion 확인, PRD·리뷰·계획의 상태 및 검증 기록 갱신.
- **범위 밖:** 실제 RTC 접속을 검증하지 않고 검증했다고 기록하는 행위, 무관한 리팩터링.
```bash
./gradlew test --tests '*LiveRoomServiceTest' --tests '*LiveRoomServiceAdultVisibilityPolicyTest' --tests '*DefaultCreatorChannelLiveQueryRepositoryTest' --tests '*CreatorChannelLiveQueryServiceTest' --tests '*DefaultHomeRecommendationQueryRepositoryTest'
./gradlew ktlintCheck
./gradlew tasks --all
```
- [x] 위 명령을 실행하고 각 Task의 완료 증거를 대조한다.
- [x] 실제 HTTP/RTC 연결 검증 여부와 환경 한계를 별도로 기록한다. 서비스 테스트 통과를 실제 RTC 접속 검증으로 간주하지 않는다.
- [x] 전체 회귀는 공통 인증·예외·설정까지 변경하거나 focused test로 영향 범위를 판단할 수 없는 경우 또는 사용자 요청 시 실행한다. 생략 시 이유와 위 대체 회귀 명령을 Progress에 남긴다.
- [x] `reviews/현재변경사항-review.md`에 수정 후 검증을 누적하고, PRD의 후속 성공 기준 및 Phase 3 상태를 실제 결과에 맞춰 갱신한다.
## 실행 순서와 의존성
| 순서 | Goal | 선행조건 | 병행 가능 | 차단 시 다음 행동 |
|---:|---|---|---|---|
| 1 | `P1-T1` | PRD 확정 | 아니요 | 호출부/port signature 대조 후 문서 갱신 |
| 2 | `P1-T2` | PRD 확정 | 예, `P1-T1`과 파일 충돌 없음 | service test 작성 방식 확정 |
| 3 | `P1-GATE` | `P1-T1`, `P1-T2` | 아니요 | 실패 소유 Task로 회귀 수정 |
| 4 | `P2-T1` | `P1-GATE` | 아니요 | 오류 message key 결정 후 문서 갱신 |
| 5 | `P2-GATE` | `P2-T1` | 아니요 | 실패 소유 Task로 회귀 수정 |
| 6 | `P3-T1` | `P2-GATE`, `REV-001` | 기본 순차 | 토큰 생성 전 거절 재현과 PRD 정합성 확인 |
| 7 | `P3-T2` | `REV-002` | `P3-T1`과 파일 독립 | 기존 fixture·현재 방 조건 확인 |
| 8 | `P3-GATE` | `P3-T1`, `P3-T2` | 아니요 | 실패 소유 Task로 회귀 수정 |
```text
P1-T1 ─┐
├→ P1-GATE → P2-T1 → P2-GATE
P1-T2 ─┘
P2-GATE → P3-T1 ─┐
P3-T2 ─┴→ P3-GATE
```
## 변경 금지 항목
- 공개 API 응답 DTO를 변경하지 않는다.
- `isAvailableJoinCreator`의 DB schema나 기본값을 변경하지 않는다.
- 기존 성인/성별/차단/강퇴/비공개/결제 조건을 완화하지 않는다.
- 테스트를 삭제·skip·완화하지 않는다.
- `as any`, 타입 억제, 불필요한 새 abstraction을 만들지 않는다.
## Progress
- 2026-09-17: PRD와 계획 문서 작성. 구현은 아직 시작하지 않음.
- 2026-09-17: v2 홈 추천/온에어 라이브의 `genderRestriction` 조회 필터와 `/live/room/enter` 성별 제한 회귀 검증을 PRD/계획에 반영. 구현은 아직 시작하지 않음.
- 2026-09-17: `P1-T1` RED 확인. 신규 인자 추가 전 `compileTestKotlin`에서 `isViewerCreator`/`effectiveViewerGender` 미정의로 실패했고, 시그니처 연결 후 repository focused test 79건 중 크리에이터 제한 1건과 성별 제한 2건이 assertion 실패했다. facade 전달 전 `HomeRecommendationControllerTest.shouldLogHomeRecommendationPageFailure`도 신규 인자 불일치로 실패했다.
- 2026-09-17: `P1-T1` GREEN 확인. `./gradlew test --rerun-tasks --tests '*DefaultHomeRecommendationQueryRepositoryTest' --tests '*HomeRecommendationQueryServiceTest' --tests '*HomeRecommendationFacadeTest' --tests '*HomeOnAirLiveFacadeTest'`가 `BUILD SUCCESSFUL`로 종료했다. 컴파일 경고는 기존 deprecated API 및 기존 테스트 경고이며 신규 실패는 없다.
- 2026-09-17: `P1-T1` REFACTOR 확인. 추가 추상화 없이 기존 QueryDSL 패턴을 재사용했고 `./gradlew ktlintCheck`가 `BUILD SUCCESSFUL`로 종료했다.
- 2026-09-17: `P1-T2` RED 확인. 다른 ID의 `MemberRole.CREATOR` viewer 테스트에서 `currentLiveIsViewerCreator`가 기대값 `true`, 실제값 `false`로 실패했다.
- 2026-09-17: `P1-T2` GREEN 확인. `CreatorChannelLiveQueryService`가 `viewer.role == MemberRole.CREATOR`를 전달하도록 최소 수정한 뒤 `./gradlew test --rerun-tasks --tests '*CreatorChannelLiveQueryServiceTest'`가 `BUILD SUCCESSFUL`로 종료했다.
- 2026-09-17: `P1-T2` REFACTOR 확인. 별도 추상화 없이 기존 역할 enum을 사용했고 `./gradlew ktlintCheck`가 `BUILD SUCCESSFUL`로 종료했다.
- 2026-09-17: `P1-GATE` 자동 검증. `./gradlew test --rerun-tasks --tests '*DefaultHomeRecommendationQueryRepositoryTest' --tests '*HomeRecommendationQueryServiceTest' --tests '*HomeRecommendationFacadeTest' --tests '*HomeOnAirLiveFacadeTest' --tests '*CreatorChannelLiveQueryServiceTest'`와 `./gradlew ktlintCheck`가 모두 `BUILD SUCCESSFUL`로 종료했다. 출력된 deprecated API 및 unchecked cast 경고는 변경 범위 밖의 기존 경고다.
- 2026-09-17: `P1-GATE` 수동 대조. `HomeFollowingQueryService`와 `CreatorChannelHomeQueryService`는 변경하지 않았고, 홈 추천·라이브·온에어 facade 세 경로가 조회자 역할과 유효 성별을 전달함을 확인했다.
- 2026-09-17: `P1-GATE` 리뷰 승인. Phase 1 전체 변경 범위의 PRD/계획 위반과 기존 필터 약화가 없음을 확인했으며 Blocker는 0건이다.
- 2026-09-17: `P2-T1` RED 확인. 다른 크리에이터의 제한 방 입장 테스트가 `SodaException`을 기대했지만 예외가 발생하지 않아 실패했다.
- 2026-09-17: `P2-T1` GREEN 확인. `LiveRoomService.enterLive()`의 결제 및 room-info 접근 전에 역할·방 생성자·`isAvailableJoinCreator` 조건을 추가한 뒤 `./gradlew test --rerun-tasks --tests '*LiveRoomServiceTest'`가 5건 모두 통과하며 `BUILD SUCCESSFUL`로 종료했다.
- 2026-09-17: `P2-T1` REFACTOR 확인. 방 생성자, 일반 사용자, `Gender.NONE`, 성별 불일치 회귀 테스트와 차단 경로의 무부수효과 검증을 유지했고 `./gradlew ktlintCheck`가 `BUILD SUCCESSFUL`로 종료했다.
- 2026-09-17: `P2-GATE` 자동 검증. `./gradlew test --rerun-tasks --tests '*DefaultHomeRecommendationQueryRepositoryTest' --tests '*CreatorChannelLiveQueryServiceTest' --tests '*LiveRoomServiceTest'`, `./gradlew ktlintCheck`, `./gradlew test --rerun-tasks`가 모두 `BUILD SUCCESSFUL`로 종료했다.
- 2026-09-17: `P2-GATE` 최종 리뷰 승인. 구현·테스트·문서의 PRD/계획 일치와 API/스키마 유지 여부를 재검토했으며 Blocker는 0건이다.
- 2026-09-17: 현재 변경사항 후속 리뷰. focused 140건 및 직접 영향 회귀 42건, 총 182건 통과. `./gradlew ktlintCheck tasks --all` 성공(ktlint UP-TO-DATE). 소스 수정 없이 목록·입장 경계 중심의 검토이므로 전체 회귀는 재실행하지 않았다. 명시된 구현 범위는 적합하나, 기존 `/live/room/info/{id}` 토큰 발급 경계의 제한 누락과 채널 소유자 조회 테스트 보완점을 `reviews/현재변경사항-review.md`에 기록했다. 실제 HTTP/RTC 연결은 미검증이며, 제품 전체의 입장 차단 완결성 승인은 보류한다. 기존 완료 기록은 유지한다.
- 2026-09-17: 사용자 요청에 따라 `REV-001`을 토큰 발급 제한 보강 `P3-T1`, `REV-002`를 채널 소유자 조회 테스트 `P3-T2`로 구체화하고 `P3-GATE`를 추가했다. 파일·조건·예외 key·회귀 시나리오·명령·완료 증거를 명시했으며 기존 Phase 1~2 완료 기록은 유지했다. `./gradlew tasks --all`은 exit 0, `BUILD SUCCESSFUL`; `git diff --check`도 통과했다. 이번 변경은 계획 문서만 갱신하므로 코드 테스트는 실행하지 않았다. 후속 구현은 미착수이며 다음 Goal은 `P3-T1`이다.
- 2026-09-17: `P3-T1` 시작 전 문서 정합성 완료. PRD의 관련 review, 문제·목표·사용자 흐름, `LCR-003`, API 계약, 보안 기준과 미완료 성공 기준에 `/live/room/info/{id}` 토큰 발급 경계 및 `REV-002` 회귀 검증을 반영했다.
- 2026-09-17: `P3-GATE` 자동 검증. `./gradlew test --rerun-tasks --tests '*LiveRoomServiceTest' --tests '*LiveRoomServiceAdultVisibilityPolicyTest' --tests '*DefaultCreatorChannelLiveQueryRepositoryTest' --tests '*CreatorChannelLiveQueryServiceTest' --tests '*DefaultHomeRecommendationQueryRepositoryTest'`가 119건, 실패·오류·skip 0으로 `BUILD SUCCESSFUL` 종료했다. `./gradlew ktlintCheck`, `./gradlew tasks --all`, `git diff --check`도 모두 성공했다.
- 2026-09-17: 토큰 발급 경계는 보안 관련 변경이므로 조건부 전체 회귀를 실행했다. `./gradlew test --rerun-tasks`가 `BUILD SUCCESSFUL`로 종료했다. 실제 HTTP 인증/직렬화 및 Agora RTC/RTM 연결은 환경상 실행하지 않았고, 실제 서비스 메서드 호출과 token builder 무호출 assertion 및 H2 repository 조회를 대체 실행 증거로 사용했다.
- 2026-09-17: `P3-GATE` 최종 reviewer gate 승인. Phase 3 구현·테스트·PRD·계획·후속 리뷰 해소 기록을 전체 diff 기준으로 검토했으며 Blocker는 0건이다.
@@ -1,115 +0,0 @@
# 라이브 크리에이터 입장 제한 PRD
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | Phase 1~3 구현 및 검증 완료 |
| 작성일 | `2026-09-17` |
| 최종 수정일 | `2026-09-17` |
| 대상 제품 | 라이브 방 목록 노출 및 입장 제한 |
| 작성자·결정권자 | Sisyphus / 사용자 |
| 관련 API Contract | 기존 API 응답 스키마 변경 없음 |
| 관련 구현 계획 | `docs/20260917_라이브_크리에이터_입장제한/plan-task.md` |
| 관련 review | `reviews/현재변경사항-review.md` (`REV-001`, `REV-002`) |
## 1. Overview
라이브 방 생성자가 `isAvailableJoinCreator = false`로 설정한 방은 다른 크리에이터 계정에게 노출되거나 입장 가능하면 안 된다. 또한 `genderRestriction`으로 입장 가능 성별이 제한된 방은 조회 단계에서도 입장 가능한 사용자에게만 노출돼야 한다. 기존 `/live/room` 계열 조회는 대부분 이 정책을 적용하지만, v2 홈 추천/온에어 라이브와 일부 크리에이터 채널 라이브 경로에서 정책 누락 가능성이 확인됐다. 후속 리뷰에서 `/live/room/info/{id}`가 같은 제한을 확인하지 않고 RTC/RTM 토큰을 발급하는 경로도 확인됐다.
## 2. Problem Statement
- `v2` 홈 추천/온에어 라이브 조회는 `findLiveRecommendations()`에서 조회자의 크리에이터 여부와 유효 성별을 받지 않아 `isAvailableJoinCreator = false`인 방도 크리에이터에게 노출될 수 있고, 성별 제한 방도 입장 불가능한 사용자에게 노출될 수 있다.
- `v2` 크리에이터 채널 라이브 탭은 조회자가 크리에이터인지가 아니라 조회자가 해당 채널 주인인지로만 `isViewerCreator`를 계산해, 다른 크리에이터에게 제한 방이 노출될 수 있다.
- `/live/room/enter`는 성인, 비공개, 차단, 강퇴, 성별, 정원, 결제 조건은 확인하지만 크리에이터 입장 제한을 최종 차단하지 않는다.
- `/live/room/info/{id}`는 방 정보와 상호 차단만 확인한 뒤 RTC/RTM 토큰을 생성하므로 `/enter`에서 거절된 사용자도 토큰 발급을 요청할 수 있다.
문제를 해결했다는 판단은 다른 크리에이터가 `isAvailableJoinCreator = false` 방을 리스트에서 보지 못하고, 성별 제한에 맞지 않는 사용자가 제한 방을 리스트에서 보지 못하며, 직접 `enter` 요청을 보내도 차단되는 것으로 한다.
## 3. Goals
- 다른 크리에이터 계정은 `isAvailableJoinCreator = false` 라이브 방을 문제 의심 경로에서 볼 수 없다.
- 다른 크리에이터 계정은 `isAvailableJoinCreator = false` 라이브 방에 직접 입장할 수 없다.
- 입장 가능 성별이 제한된 라이브 방은 성별이 맞는 사용자 또는 방 생성자 본인에게만 조회된다.
- 입장 가능 성별이 제한된 라이브 방은 성별이 맞는 사용자 또는 방 생성자 본인만 입장할 수 있다.
- 방을 만든 크리에이터 본인은 예외로 계속 조회 및 입장 가능하다.
- 제한 사용자는 `/live/room/info/{id}`에서 RTC/RTM/v2v 토큰을 발급받을 수 없다.
- 기존 응답 DTO와 공개 API 스키마는 변경하지 않는다.
## 4. Non-Goals
- `isAvailableJoinCreator` 필드명, 의미, DB 스키마 변경은 하지 않는다.
- 일반 유저, 관리자, 봇, 에이전트의 기존 노출/입장 정책은 변경하지 않는다.
- 기존 성인/성별/차단/강퇴/비공개/결제 정책은 재설계하지 않는다.
- `Gender.NONE` 사용자의 기존 정책은 변경하지 않는다. 기존 `Member.canEnter()`와 리스트 조건처럼 성별 미설정 사용자는 성별 제한을 통과한다.
- 새 API endpoint나 새 응답 필드는 만들지 않는다.
## 5. Target Users and Permissions
| 사용자 | 목표 | 정책 |
|---|---|---|
| 방 생성 크리에이터 | 본인이 만든 방 조회 및 입장 | `isAvailableJoinCreator = false`여도 허용 |
| 다른 크리에이터 | 크리에이터 입장 제한 방 접근 방지 | `isAvailableJoinCreator = false`면 목록 미노출 및 입장 차단 |
| 일반 유저 | 기존 라이브 조회 및 입장 | `genderRestriction`에 맞으면 허용, `Gender.NONE`은 기존처럼 허용 |
## 6. 핵심 사용자 흐름
1. 일반 유저 또는 방 생성자가 `isAvailableJoinCreator = false` 방을 조회하면 기존 정책에 따라 표시된다.
2. 성별 제한에 맞지 않는 사용자가 `genderRestriction` 제한 방을 v2 홈 추천/온에어 라이브에서 조회하면 표시되지 않는다.
3. 다른 크리에이터가 같은 방을 v2 홈 추천/온에어 라이브 또는 크리에이터 채널 라이브 경로에서 조회하면 표시되지 않는다.
4. 성별 제한에 맞지 않는 사용자가 방 ID를 알고 `/live/room/enter`를 호출하면 입장이 거부된다.
5. 다른 크리에이터가 방 ID를 알고 `/live/room/enter`를 호출하면 입장이 거부된다.
6. 방 생성 크리에이터가 본인 방에 입장하면 기존처럼 허용된다.
7. `/enter`에서 거절되는 다른 크리에이터 또는 성별 불일치 사용자가 `/live/room/info/{id}`를 호출하면 토큰 생성 전에 같은 정책으로 거절된다.
8. 방 생성자, 성별이 맞는 일반 사용자, 크리에이터 입장이 허용된 방의 다른 크리에이터는 기존처럼 방 정보와 토큰을 받는다.
## 7. 기능 요구사항
| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 |
|---|---|---|---|---|
| `LCR-001` | 확정 | v2 홈 추천/온에어 라이브 조회에서 다른 크리에이터에게 `isAvailableJoinCreator = false` 방을 숨기고, 성별 제한에 맞지 않는 사용자에게 `genderRestriction` 제한 방을 숨긴다. | `HomeRecommendationQueryService.findLiveRecommendations()` 호출 경로가 조회자 크리에이터 여부와 유효 성별을 전달한다. repository는 `liveRoom.isAvailableJoinCreator.isTrue.or(liveRoom.member.id.eq(memberId))`와 `Gender.MALE -> ALL/MALE_ONLY`, `Gender.FEMALE -> ALL/FEMALE_ONLY`, `Gender.NONE/null -> 필터 없음` 조건을 적용한다. | `P1-T1` |
| `LCR-002` | 확정 | v2 크리에이터 채널 라이브 탭에서 다른 크리에이터에게 제한 방을 숨긴다. | `CreatorChannelLiveQueryService`가 `viewer.role == MemberRole.CREATOR` 기준으로 조회자 크리에이터 여부를 전달한다. 방 생성자 본인은 예외다. | `P1-T2` |
| `LCR-003` | 확정 | `/live/room/enter`와 `/live/room/info/{id}`에서 다른 크리에이터의 제한 방 입장·토큰 발급과 성별 제한에 맞지 않는 접근을 차단한다. | 다른 크리에이터 제한은 `live.room.not_found`, 성별 제한은 `live.room.gender_restricted`로 결제·입장 상태 변경 또는 RTC/RTM/v2v 토큰 생성 전에 거절한다. 생성자는 예외이며 성별 판정은 `Member.canEnter()`를 재사용한다. | `P2-T1`, `P3-T1` |
| `LCR-004` | 확정 | 기존 정상 경로는 유지한다. | 일반 유저와 방 생성자 본인의 조회/입장 동작은 유지되고 기존 테스트 또는 신규 회귀 테스트로 확인된다. | `P2-GATE` |
## 8. API 계약
- 변경되는 공개 request/response 필드는 없다.
- `/live/room/enter`는 기존 오류 envelope를 사용한다.
- `/live/room/info/{id}`도 기존 오류 envelope와 message key를 재사용하며 응답 필드는 변경하지 않는다.
- 신규 message key 추가 여부는 구현 단계에서 기존 `live.room.gender_restricted`, `common.error.invalid_request`, `live.room.not_found` 패턴을 확인해 결정한다. 새 key가 필요하면 메시지 리소스와 테스트를 함께 갱신한다.
## 9. 보안과 데이터 취급
- 숨김 정책은 클라이언트 표시만으로 끝내지 않고 서버 입장 경계에서 한 번 더 차단한다.
- 제한 방 존재 여부를 다른 크리에이터에게 과도하게 노출하지 않는 오류 메시지를 우선한다.
- 민감정보, 결제 정보, password, token은 로그나 테스트 fixture에 기록하지 않는다.
- 제한 검사는 RTC, RTM, v2v 토큰 생성 호출보다 먼저 수행한다.
## 10. 성공 기준
- [x] 다른 크리에이터는 `isAvailableJoinCreator = false` 방을 v2 홈 추천/온에어 라이브에서 받지 않는다. (`LCR-001`)
- [x] 성별 제한에 맞지 않는 사용자는 `genderRestriction` 제한 방을 v2 홈 추천/온에어 라이브에서 받지 않는다. (`LCR-001`)
- [x] 다른 크리에이터는 `isAvailableJoinCreator = false` 방을 v2 크리에이터 채널 라이브 탭에서 받지 않는다. (`LCR-002`)
- [x] 다른 크리에이터는 `isAvailableJoinCreator = false` 방에 직접 입장할 수 없다. (`LCR-003`)
- [x] 성별 제한에 맞지 않는 사용자는 제한 방에 직접 입장할 수 없다. (`LCR-003`)
- [x] 방 생성 크리에이터 본인은 본인 방을 조회하고 입장할 수 있다. (`LCR-001`~`LCR-003`)
- [x] 공개 API 스키마 변경 없이 focused test와 영향 범위 회귀가 통과한다.
- [x] 다른 크리에이터와 성별 불일치 사용자는 `/live/room/info/{id}`에서 토큰 생성 전에 거절되고 토큰 생성기가 호출되지 않는다. (`LCR-003`)
- [x] 방 생성자, 성별이 맞는 일반 사용자, 크리에이터 입장이 허용된 방의 다른 크리에이터, `Gender.NONE` 사용자는 기존처럼 방 정보와 토큰을 받는다. (`LCR-003`, `LCR-004`)
- [x] 채널 소유자 본인은 `isAvailableJoinCreator = false`인 현재 방을 repository 조회에서 받는다. (`LCR-002`, `LCR-004`)
## 11. Decision Log
| 일시 | 결정 | 근거 |
|---|---|---|
| 2026-09-17 | `isAvailableJoinCreator = false`는 다른 크리에이터만 제한하고 방 생성자 본인은 예외로 둔다. | 기존 QueryDSL 조건들이 `liveRoom.member.id.eq(viewerId)` 예외를 두는 패턴과 사용자 선택 A |
| 2026-09-17 | 이 작업은 문서가 필요한 구현 작업으로 분류한다. | 저장소 `AGENTS.md`와 `docs/agent-guides/작업절차.md`가 모든 구현 작업 전 PRD와 plan-task를 요구 |
| 2026-09-17 | v2 홈 추천/온에어 라이브에도 기존 조회 경로와 같은 `genderRestriction` 필터를 적용한다. | `/live/room`, 팔로잉, 크리에이터 채널 조회 경로가 이미 성별 조건을 조회 단계에서 적용하고 있으며 사용자가 문서 반영을 요청 |
| 2026-09-17 | `/live/room/enter`의 성별 제한은 기존 `Member.canEnter()` 정책을 유지한다. | 현재 `LiveRoomService.enterLive()`가 이미 `room.member.id != member.id && !member.canEnter(room.genderRestriction)`을 차단하고, `Gender.NONE`은 `canEnter()`에서 허용됨 |
| 2026-09-17 | `/live/room/info/{id}`에서도 `/enter`와 같은 크리에이터·성별 제한을 토큰 생성 전에 적용한다. | `REV-001`에서 `/enter` 거절 후에도 RTC/RTM/v2v 토큰 생성 경로가 열려 있음을 코드로 확인 |
| 2026-09-17 | 채널 소유자의 제한 방 조회는 production 변경 없이 H2 repository 회귀 테스트로 고정한다. | `REV-002`와 기존 `creatorJoinLiveCondition()`의 소유자 예외 |
## 12. 열린 질문
- 없음. 구현 중 기존 메시지 key 재사용이 부적절하다고 확인되면 plan-task 범위를 먼저 갱신한다.
@@ -1,114 +0,0 @@
# 라이브 크리에이터 입장 제한 현재 변경사항 리뷰
## 1. 리뷰 정보
- 일자: 2026-09-17
- 기준: `62c834d28f0d142e81f2d303273eb1220cab0611` 위의 현재 staged/working tree 변경사항. commit 자체에 대한 승인이 아니다.
- 소스 diff SHA-256 (`git diff HEAD -- src`): `7b951c79f1575832ac65870a479005909da22e640772c5609a3cbdd983209b98`
- 기준 문서: `../prd.md`, `../plan-task.md`
- 범위: LCR-001~004, 변경 production 7개 파일과 관련 테스트, 기존 조회/입장 정책.
- 상태: 판정 완료. production 및 테스트 코드는 수정하지 않았다.
## 2. 검토 기준 및 근거
- 홈 추천·라이브·온에어의 역할/인증 성별 전달, QueryDSL 필터와 생성자 예외를 대조한다.
- 크리에이터 채널 라이브의 역할 판정과 기존 repository 조건을 대조한다.
- 직접 입장 거부가 결제 및 roomInfo 접근보다 먼저 발생하는지 확인한다.
- 공개 DTO, 일반 사용자, Gender.NONE, 기존 성인/차단/결제 정책의 회귀 여부를 확인한다.
- `docs/sample/sample-review.md` 기준으로 확정 결함과 검증 한계를 구분한다.
## 3. 검토별 증거 기록
| 검토 | 기준 HEAD | 판정 | 근거 |
|---|---|---|---|
| 코드 품질 | `62c834d28f0d142e81f2d303273eb1220cab0611` + 현재 변경 | PASS | `/root/quality`: SQL WHERE 적용 후 페이지네이션, 호출 3곳 인자 전달, 기본값 및 생성자 예외, 부수효과 전 차단 확인. 이전 XML은 이번 실행 증거로 사용하지 않음. |
| 요구사항 | `62c834d28f0d142e81f2d303273eb1220cab0611` + 현재 변경 | PASS | `/root/requirements`: LCR-001~004 구현 일치. 채널 소유자 조회의 직접 회귀 테스트는 보완 여지 있음. |
| 주변 문맥 | `62c834d28f0d142e81f2d303273eb1220cab0611` + 현재 변경 | PASS | `/root/context`: 기존 팔로잉·채널 홈 조건 및 Member.canEnter와 일치. 기존 상세 조회의 제한 미검사는 이번 diff 밖임. |
| 보안 | `62c834d28f0d142e81f2d303273eb1220cab0611` + 현재 변경 | FAIL | `/root/security`: getRoomInfo의 기존 RTC 토큰 발급 경로가 입장 제한을 검사하지 않음. 코드 추적 근거이며 실제 RTC 연결은 미검증. |
| 자동 QA | `62c834d28f0d142e81f2d303273eb1220cab0611` + 현재 변경 | PASS | `/root/qa`: focused 140건 + 인접 회귀 42건 통과. 실제 HTTP/RTC QA는 INCONCLUSIVE. |
| 런타임 감사 | `62c834d28f0d142e81f2d303273eb1220cab0611` + 현재 변경 | INCONCLUSIVE | H2 쿼리 결과, 서비스 거부 예외 및 무부수효과 assertion은 실행 확인. 실제 RTC 토큰을 사용한 연결 우회는 실행하지 않음. |
## 4. 실행 검증
환경: macOS, Java 17, Gradle Wrapper, repository 테스트 H2. 전체 회귀 대신 변경 파일 focused test 및 직접 영향받는 기능 회귀를 실행한다. 공개 DTO·공통 인증·설정 변경은 없으며 이 리뷰에서 소스를 수정하지 않아 전체 테스트를 재실행하지 않았다. 기존 계획의 전체 회귀 성공 기록은 이번 실행 결과로 간주하지 않는다.
```bash
./gradlew test --rerun-tasks --tests '*DefaultHomeRecommendationQueryRepositoryTest' --tests '*CreatorChannelLiveQueryServiceTest' --tests '*LiveRoomServiceTest' --tests '*HomeRecommendationQueryServiceTest' --tests '*HomeRecommendationFacadeTest' --tests '*HomeOnAirLiveFacadeTest'
```
- `/root/qa` 실행: BUILD SUCCESSFUL, 140건, 실패/오류/skip 0, 3분 19초.
- `./gradlew ktlintCheck tasks --all`: BUILD SUCCESSFUL. ktlint 작업은 UP-TO-DATE이며 강제 재실행은 하지 않았다.
- `git diff --check`: exit 0.
- `./gradlew test --tests '*HomeRecommendationControllerTest' --tests '*DefaultCreatorChannelLiveQueryRepositoryTest' --tests '*HomeOnAirLiveControllerTest' --tests '*LiveRoomServiceAdultVisibilityPolicyTest'`: exit 0, 42건, 실패/오류/skip 0, 41초.
- 합계: 182건 통과. 추천 repository 81, 추천 service 35, 추천 facade 6, 온에어 facade 4, 채널 service 9, 입장 service 5, 추천 controller 27, 온에어 controller 2, 채널 repository 8, 기존 성인 정책 5.
- 실제 HTTP/RTC 연결은 미검증. localhost:8080에 실행 중 서버가 없고 운영 데이터·외부 서비스에 연결하지 않았다. 서비스 Mockito 테스트 및 H2 repository 테스트는 입장 거부/조회 필터의 실행 증거이며 실제 RTC 우회 재현 증거는 아니다.
## 5. 발견 사항 및 종료 판정
### REV-001 — 기존 방 정보 API의 토큰 발급 경계에 제한 검사 없음
- 심각도: High. 상태: 제한 검사 누락은 코드로 확정, 실제 RTC 접속 우회는 미검증.
- 관련 목표: PRD §3의 다른 크리에이터·성별 불일치 사용자의 입장 차단.
- 이번 diff가 도입한 결함은 아니며, 계획에 명시된 목록 및 `/enter` 수정 범위 밖의 기존 경로다.
- `LiveRoomController.kt:129`의 `GET /live/room/info/{id}`는 로그인 확인 후 `getRoomInfo()`를 호출한다.
- `LiveRoomService.kt:972`는 roomInfo·room 존재와 상호 차단만 검사한다. 크리에이터 제한, 성별 제한, 호출자의 입장 완료 여부는 확인하지 않는다.
- 같은 파일 `:991`부터 RTC 토큰 생성기를 호출하고 `:1065`부터 채널명과 토큰을 응답에 넣는다. `RtcTokenBuilder.kt:83`은 JoinChannel 권한을 추가한다.
- 확인 시나리오: roomInfo가 존재하는 제한 방에서, 호스트와 차단 관계가 없는 다른 크리에이터가 방 ID로 `/info/{id}`를 요청한다. `/enter`에서 거절됐더라도 이 경로의 토큰 발급 전 제한 검사가 없다.
- 권장 조치: 토큰 발급 경계에도 생성자 예외를 포함한 크리에이터·성별 제한을 적용하고, 제한 사용자는 토큰 생성기가 호출되지 않는 회귀 테스트로 고정한다. 전체 입장 정책 재설계는 별도 범위다.
### REV-002 — 채널 소유자 조회의 직접 회귀 테스트 보완
- 심각도: Low, 비차단 검증 보완점.
- `CreatorChannelLiveQueryServiceTest.kt:67`은 다른 크리에이터의 `isViewerCreator` 전달을 검증한다.
- `DefaultCreatorChannelLiveQueryRepositoryTest.kt:206`은 다른 크리에이터 조회 필터를 검증하지만, 소유자 본인의 제한 방 반환을 직접 검증하지 않는다.
- 소유자 허용 조건 자체는 `DefaultCreatorChannelLiveQueryRepository.kt:353`에 존재하므로 구현 누락으로 판정하지 않는다.
- 권장 조치: viewerId == creatorId이고 isAvailableJoinCreator == false인 현재 방이 반환되는 repository 회귀 테스트 1건으로 P1-T2 완료 증거를 보강한다.
## 6. 후속 처리
코드 수정은 수행하지 않았다. 명시된 구현 범위의 기능 결함은 발견하지 못했으나, 제품 전체의 입장 차단 완료 판정에는 REV-001 확인·보강이 필요하다. 구현을 진행할 경우 기존 계획에 토큰 발급 경계 보강 Task를 추가한 뒤 실패 재현 → 최소 수정 → 회귀 검증 순서로 진행한다. 기존 완료 체크박스와 검증 기록은 유지한다.
**종합 판정:** 명시된 목록·`/enter` 구현 범위는 적합하다. 보안 검토 FAIL 및 실제 API/RTC 검증 한계 때문에 제품 전체의 입장 차단에 대한 무조건 승인은 보류한다. 이번 diff에서 새로 도입된 확정 결함은 발견하지 못했다.
**다음 행동:** REV-001의 토큰 발급 경계를 후속 검증·수정 범위로 반영한다.
## 7. Phase 3 후속 구현 검증
- 일자: 2026-09-17
- 대상: `REV-001`, `REV-002` 후속 구현과 Phase 3 Gate.
- [x] `REV-001` 해소: `LiveRoomService.getRoomInfo()`가 기존 room/roomInfo 존재 및 상호 차단 검사 뒤, RTC/RTM/v2v 토큰 생성 전에 다른 크리에이터와 성별 불일치 사용자를 각각 `live.room.not_found`, `live.room.gender_restricted`로 거절한다.
- [x] `REV-001` 회귀: 제한 경로의 token builder 무호출, `/enter` 거절 후 정보 조회 거절, 소유자·성별 일치 사용자·허용 방 크리에이터·인증 성별 우선·`Gender.NONE` 허용, 기존 상호 차단 거절을 서비스 테스트로 확인했다.
- [x] `REV-002` 해소: 실제 H2 repository 테스트가 채널 소유자에게 `isAvailableJoinCreator = false`인 본인 현재 방 ID를 반환하고, 기존 다른 크리에이터 제외 테스트도 통과했다.
- [x] Phase 3 focused 회귀: 5개 테스트 클래스 119건이 실패·오류·skip 0으로 통과했다.
- [x] 품질 및 명령 검증: `./gradlew ktlintCheck`, `./gradlew tasks --all`, `git diff --check`가 성공했다.
- [x] 전체 회귀: 보안 경계 변경을 반영해 `./gradlew test --rerun-tasks`를 실행했고 `BUILD SUCCESSFUL`로 종료했다.
- [x] 검증 한계 기록: 실제 HTTP 인증/직렬화 및 Agora RTC/RTM 연결은 실행하지 않았으며 서비스 메서드 호출, token builder 무호출 assertion, 실제 H2 조회를 대체 실행 증거로 사용했다.
- [x] 최종 reviewer gate: Phase 3 구현·테스트·문서 정합성을 전체 diff 기준으로 재검토했고 Blocker 0건으로 승인됐다.
**후속 판정:** `REV-001`, `REV-002`는 구현 및 회귀 검증으로 해소됐다. 기존 리뷰의 보안 FAIL은 토큰 발급 전 서버 제한 검사 누락 기준에서 해소됐으며, 실제 RTC 연결 검증을 수행했다는 주장은 하지 않는다.
## 8. Phase 1~3 문서·코드 정적 재대조 — 2026-09-17
- 사용자 요청: 전체 자동 테스트는 이미 수행됐으므로 재실행하지 않고 문서와 실제 코드의 스펙 일치 여부를 확인한다.
- 기준 HEAD: `62c834d28f0d142e81f2d303273eb1220cab0611` 및 현재 staged/working tree 변경.
- 소스 diff SHA-256 (`git diff HEAD -- src`): `4d90f90b2a262d1ee081c8e9fc78085ce6d04199d9c50a3d5a7506ceaeed0fbe`.
- 범위: LCR-001~004, P1~P3, REV-001/002, 호출 경로와 테스트 assertion. 이번 검토에서 테스트·애플리케이션은 실행하지 않는다. 기존 실행 성공 기록과 이번 정적 검토 판정은 구분한다.
| 검토 | 정적 판정 | 근거 |
|---|---|---|
| 요구사항 | PASS | `/root/spec_v3`: 전체 호출 3곳 역할·성별 전달, 목록 필터 및 생성자 예외, 입장/토큰 발급 전 거절, 채널 소유자 repository assertion까지 LCR-001~004 구현 확인. |
| 보안 경계 | PASS | `/root/security_v3`: LiveRoomService.kt:986~995 검사 뒤 :1001/:1009/:1016 토큰 생성. 기존 존재·양방향 차단 검사 및 /enter의 결제 전 차단 유지. |
| 코드 품질 | PASS | `/root/quality_v3`: 모든 호출부 인자 전달, WHERE 필터 후 페이지네이션, 내부 기본값 및 공개 API/DB 스키마 유지. |
| 테스트 소스 | PASS | `/root/tests_v3`: LiveRoomServiceTest.kt:180~326 제한/허용/우선순위/무호출 assertion, :368 세 토큰 응답 및 호출 횟수, 채널 repository 테스트 :244~266 실제 소유자 방 ID assertion 확인. 실행 QA 판정은 아님. |
| 문서·주변 정책 | PASS | `/root/context_v3`: Member.canEnter 및 기존 채널 조건과 일치. 이전 FAIL/미착수는 보존된 이력이며 후속 완료 기록으로 해소됨. |
위 판정은 명시된 HEAD와 소스 diff 조합에 한정한다.
**요구사항 대조:**
- LCR-001: 홈 추천·라이브·온에어의 역할/유효 성별 전달과 조회 필터 일치. 생성자 예외와 NONE/null 정책 유지.
- LCR-002: 채널 조회자의 실제 CREATOR 역할 판정 및 생성자 예외 일치. REV-002의 소유자 H2 테스트 추가 확인.
- LCR-003: /enter는 결제·상태 변경 전, /info는 모든 토큰 생성 전에 동일 제한 검사. 예외 key·우선순위·생성자 예외·Member.canEnter 재사용 일치. REV-001 해소 확인.
- LCR-004: 허용 사용자·생성자·인증 성별 우선·Gender.NONE 회귀 assertion 존재. 공개 DTO/DB 스키마 및 기존 제한 조건 유지.
**최종 정적 판정: PASS.** 문서에 명시된 Phase 1~3 구현 및 후속 두 항목의 누락·스펙 위반은 발견하지 못했다. 새 수정 Task로 전환할 확정 항목은 없다. 코드·테스트는 변경하지 않았으며 이 절만 누적했다. 사용자 요청에 따라 테스트와 Gradle 작업을 재실행하지 않고 문서·소스·diff를 대조했다. 전체 자동 테스트 성공은 사용자 확인 및 기존 문서 기록으로 구분하며, 이번에 HTTP/RTC 실행 또는 과거 RED→GREEN을 재검증했다고 주장하지 않는다.
@@ -1,299 +0,0 @@
# 성인 콘텐츠 노출 정책 Deprecated 함수 제거 구현 계획
| 문서 항목 | 내용 |
|---|---|
| 상태 | Phase 1~3 완료, P3-R1 구현 완료·실행 검증 대기 |
| 작성일 | `2026-09-17` |
| 요구사항 기준 | `docs/20260917_성인콘텐츠노출정책_Deprecated함수_제거/prd.md` |
| API 기준 | 기존 API 응답 스키마 변경 없음 |
| 현재 Phase | Phase 3 후속 실행 검증 대기 |
| 현재 활성 Goal | `P3-R1` 실행 검증 |
| 다음 Goal | 없음 |
## 목표
`MemberContentPreferencePolicy.isAdultVisibleByPolicy(...)` / `resolveCountryCodeByPolicy(...)` Deprecated 경로를 `MemberContentPreferenceService` 정식 경로로 이전하고, Deprecated 함수와 전용 테스트를 제거한다. 사용자가 확정한 JP 강제 매핑의 `2L` 제거를 제외하고 성인 콘텐츠 노출 판정 결과는 유지한다.
## 현재 상태
| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
|---:|---|---:|---|---|
| 1 | 완료 | `1/1` | 없음 | 없음 |
| 2 | 완료 | `4/4` | 없음 | 없음 |
| 3 | 완료 | `1/1` | 없음 | 없음 |
| 3 후속 | 진행 중 | `0/1` | 활성: `P3-R1` 실행 검증 | 회귀 테스트 구현·소스 검토 완료, 자동 실행 대기 |
## 범위
### 포함
- `MemberContentPreferenceService`에 `isAdultVisibleForQuery(member, isAdultContentVisible)` 추가.
- production 12개 파일 27곳의 `isAdultVisibleByPolicy(...)` 호출 치환 및 `MemberContentPreferenceService` 생성자 주입.
- `MemberContentPreferencePolicy.kt`, `MemberContentPreferencePolicyTest.kt` 제거와 고유 검증 이전.
- 영향 범위 focused test 및 ktlint 검증.
### 제외
- `isAdult` 판정 알고리즘 변경 및 JP 강제 매핑의 `2L` 제거 외 국가 강제 매핑 회원 ID 변경.
- 각 서비스 public 메서드 시그니처 변경, 공개 API 스키마 변경.
- `CanController`의 통화 강제 로직.
## 기술적 제약
- 기술 스택: Kotlin, Spring Boot 2.7.14, Gradle Wrapper, ktlint.
- 신규 abstraction을 만들지 않는다. 기존 `MemberContentPreferenceService`의 `resolveCountryCode` + `calculateIsAdultForQuery`를 재사용한다.
- `CountryContext`는 `@RequestScope`이므로 마이그레이션 대상은 웹 요청 경로에서만 호출되는 서비스로 한정한다(`RISK-001`).
- 모든 production 변경 Task는 `RED → GREEN → REFACTOR` 순서로 진행한다.
- 테스트 실행은 변경 범위 focused test를 우선하고, 전체 회귀는 실행하지 않으며 생략 근거를 검증 기록에 남긴다.
## Phase 1: 정식 경로 단일 진입점 확보
**Phase 결과:** `MemberContentPreferenceService.isAdultVisibleForQuery(...)`가 Deprecated 함수와 동일한 판정을 제공한다.
**선행조건:** PRD 확정.
**Phase 완료 조건:** `P1-T1` 완료 및 검증 기록 누적.
### 구현 항목
#### Task 1.1 `isAdultVisibleForQuery` 추가
**Goal 실행 `P1-T1`:** `MemberContentPreferenceService`에 접속 국가 계산과 성인 노출 판정을 묶은 단일 메서드를 추가한다.
- **시작 조건:** `DEPREM-001` 확정.
- **완료 증거:** KR + 미인증 → `false`, KR + 인증 → 전달값, 비KR → 전달값, 강제 매핑 회원은 헤더보다 강제 국가 우선인 focused test 통과.
- **범위 밖:** 호출부 치환.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceService.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceServiceTest.kt`
**Interfaces:**
- `fun isAdultVisibleForQuery(member: Member, isAdultContentVisible: Boolean): Boolean`
- 구현은 `calculateIsAdultForQuery(member, resolveCountryCode(member), isAdultContentVisible)`로 한다. DB 조회를 추가하지 않는다.
- [x] **RED:** `MemberContentPreferenceServiceTest`에 `isAdultVisibleForQuery` 판정 테스트 4건(KR 미인증/KR 인증/비KR/강제 매핑)을 작성한다.
- [x] **RED 확인:** `MemberContentPreferenceServiceTest` 실행 결과 `Unresolved reference: isAdultVisibleForQuery` 컴파일 실패를 확인했다.
- [x] **GREEN:** `MemberContentPreferenceService`에 `isAdultVisibleForQuery`를 추가했다.
- [x] **GREEN 확인:** `MemberContentPreferenceServiceTest` 25/25 통과.
- [x] **REFACTOR:** `resolveCountryCode` + `calculateIsAdultForQuery` 재사용만으로 구현해 중복 계산이 없음을 확인했고 ktlint 통과.
## Phase 2: production 호출부 마이그레이션
**Phase 결과:** production 코드에서 `isAdultVisibleByPolicy(...)` 호출이 0건이 된다.
**선행조건:** Phase 1 완료.
**Phase 완료 조건:** `P2-T1`~`P2-T4`와 `P2-GATE` 완료 및 검증 기록 누적.
### 구현 항목
#### Task 2.1 메인 탭 서비스 7개 치환
**Goal 실행 `P2-T1`:** 콘텐츠 메인 탭 서비스 7개가 `MemberContentPreferenceService`로 성인 노출 여부를 계산한다.
- **시작 조건:** `P1-T1` 완료.
- **완료 증거:** 7개 파일에서 `isAdultVisibleByPolicy` import/호출 0건, 컴파일 및 영향 범위 테스트 통과.
- **범위 밖:** `AudioContentService`, `ContentSeriesService`.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/asmr/AudioContentMainTabAsmrService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/replay/AudioContentMainTabLiveReplayService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/series/AudioContentMainTabSeriesService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/alarm/AudioContentMainTabAlarmService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/content/AudioContentMainTabContentService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/free/AudioContentMainTabFreeService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/home/AudioContentMainTabHomeService.kt`
**Interfaces:**
- 각 서비스 생성자에 `private val memberContentPreferenceService: MemberContentPreferenceService`를 추가한다.
- `isAdultVisibleByPolicy(member, isAdultContentVisible)` → `memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)`.
- `AudioContentMainTabHomeService`의 nullable member 처리(`member?.let { ... } ?: false`)는 유지한다.
- [x] **RED:** 7개 서비스가 각각 대응 `*Controller`에서만 주입됨을 확인해 `RISK-001` 위반 경로가 없음을 검증했다.
- [x] **GREEN:** 7개 파일의 호출부와 생성자를 치환했다.
- [x] **GREEN 확인:** 테스트 컴파일과 `src/test/kotlin/kr/co/vividnext/sodalive/content` 42/42 통과로 확인했다.
- [x] **REFACTOR:** `isAdultVisibleByPolicy` import를 `MemberContentPreferenceService` import로 교체했고 ktlint 통과.
#### Task 2.2 메인/큐레이션/테마 서비스 치환
**Goal 실행 `P2-T2`:** `AudioContentMainService`, `AudioContentCurationService`, `AudioContentThemeService`를 정식 경로로 치환한다.
- **시작 조건:** `P2-T1` 완료.
- **완료 증거:** 3개 파일에서 `isAdultVisibleByPolicy` 0건, 컴파일 및 영향 범위 테스트 통과.
- **범위 밖:** 다른 Task 대상 파일.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/AudioContentMainService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/curation/AudioContentCurationService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/theme/AudioContentThemeService.kt`
**Interfaces:**
- `P2-T1`과 동일한 치환 규칙을 적용한다.
- [x] **RED:** 3개 서비스의 치환 대상이 모두 `member`를 받는 웹 조회 메서드임을 확인했다.
- [x] **GREEN:** 3개 파일을 치환했다.
- [x] **GREEN 확인:** 테스트 컴파일 성공 및 `content` 패키지 회귀 통과.
- [x] **REFACTOR:** import 정리 후 ktlint 통과.
#### Task 2.3 `AudioContentService` 치환
**Goal 실행 `P2-T3`:** `AudioContentService`의 3곳을 정식 경로로 치환한다.
- **시작 조건:** `P2-T2` 완료.
- **완료 증거:** `AudioContentServiceTest`가 갱신된 생성자로 통과한다.
- **범위 밖:** `ContentSeriesService`.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/AudioContentService.kt`
- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/content/AudioContentServiceTest.kt`
**Interfaces:**
- `P2-T1`과 동일한 치환 규칙을 적용하고, 테스트에서는 `MemberContentPreferenceService`를 mock으로 주입한다.
- [x] **RED:** `AudioContentServiceTest.kt:118`에서 `No value passed for parameter 'memberContentPreferenceService'` 컴파일 실패를 확인했다.
- [x] **GREEN:** `getDetail`, `getLatestCreatorAudioContent`, `getAudioContentList` 3곳을 치환하고 테스트에 mock을 주입했다.
- [x] **GREEN 확인:** `AudioContentServiceTest` 16/16 통과.
- [x] **REFACTOR:** import 정리 후 ktlint 통과.
#### Task 2.4 `ContentSeriesService` 치환
**Goal 실행 `P2-T4`:** `ContentSeriesService`의 5곳을 정식 경로로 치환한다.
- **시작 조건:** `P2-T3` 완료.
- **완료 증거:** 시리즈 관련 영향 범위 테스트 통과, `isAdultVisibleByPolicy` 0건.
- **범위 밖:** Deprecated 함수 제거.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/series/ContentSeriesService.kt`
- Test: 필요 시 `src/test/kotlin/kr/co/vividnext/sodalive/content/series/main/SeriesMainControllerTest.kt` 등 영향 테스트 갱신
**Interfaces:**
- `P2-T1`과 동일한 치환 규칙을 적용한다.
- [x] **RED:** 테스트 컴파일을 실행해 `ContentSeriesService`를 직접 생성하는 테스트가 없어 추가 수정이 필요 없음을 확인했다.
- [x] **GREEN:** 5곳(`getSeriesList`, `getSeriesListByGenre`, `getSeriesDetail`, `getSeriesContentList`, `getRecommendSeriesList`)을 치환했다.
- [x] **GREEN 확인:** 테스트 컴파일 성공 및 Spring 컨텍스트 로딩 테스트 통과.
- [x] **REFACTOR:** import 정리 후 ktlint 통과.
### Phase 2 Gate
**Goal 실행 `P2-GATE`:** production에서 Deprecated 호출이 0건임을 확인한다.
- [x] `isAdultVisibleByPolicy|resolveCountryCodeByPolicy` 검색 결과가 `src/main/kotlin`에서 0건이다.
- [x] Phase 2 대상 파일의 영향 범위 테스트가 통과한다(`content` 42/42).
## Phase 3: Deprecated 함수 제거와 테스트 정리
**Phase 결과:** Deprecated 함수와 전용 테스트가 제거되고 고유 검증이 정식 경로 테스트에 남는다.
**선행조건:** Phase 2 완료.
**Phase 완료 조건:** `P3-T1`, `P3-GATE` 완료 및 검증 기록 누적.
### 구현 항목
#### Task 3.1 Deprecated 정의 제거와 검증 이전
**Goal 실행 `P3-T1`:** `MemberContentPreferencePolicy.kt`와 `MemberContentPreferencePolicyTest.kt`를 제거하고 고유 검증을 이전한다.
- **시작 조건:** `P2-GATE` 완료.
- **완료 증거:** 두 파일이 삭제되고 `member/contentpreference` 테스트가 모두 통과한다.
- **범위 밖:** `MemberContentPreferenceCountryResolver.kt` 변경.
**Files:**
- Delete: `src/main/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferencePolicy.kt`
- Delete: `src/test/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferencePolicyTest.kt`
- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceServiceTest.kt`
**Interfaces:**
- 이전 대상 검증: 헤더 공백/소문자 정규화(`" us "` → `US`), 국가 컨텍스트 없음 → `KR` fallback, 비KR에서 저장 `countryCode` 무시.
- 이미 정식 경로 테스트에 존재하는 검증은 중복 추가하지 않는다.
- [x] **RED:** 로그인 회원의 헤더 공백/소문자 정규화와 KR fallback 검증을 `MemberContentPreferenceServiceTest`에 추가했다. 나머지 항목(비로그인 정규화, 저장 `countryCode` 미사용)은 기존 테스트가 이미 커버함을 확인해 중복 추가하지 않았다.
- [x] **GREEN:** `MemberContentPreferencePolicy.kt`와 `MemberContentPreferencePolicyTest.kt`를 삭제했다.
- [x] **GREEN 확인:** `member/contentpreference` 36/36 통과.
- [x] **REFACTOR:** ktlint 통과 및 잔여 참조 0건 확인.
### Phase 3 Gate
**Goal 실행 `P3-GATE`:** 전체 정리 상태를 확인한다.
- [x] `isAdultVisibleByPolicy|resolveCountryCodeByPolicy` 참조가 `src/main/kotlin`, `src/test/kotlin`에서 0건이다.
- [x] `member/contentpreference` 테스트와 Phase 2 영향 범위 테스트가 통과한다.
- [x] `./gradlew ktlintMainSourceSetCheck ktlintTestSourceSetCheck`가 통과한다.
- [x] PRD 성공 기준 체크박스를 갱신했다.
## Phase 3 후속: 리뷰 검증 보강
### Task 3.R1 저장 국가 무시 검증 이전
**Goal 실행 `P3-R1`:** 저장 국가가 KR인 미인증 회원이 US에서 조회할 때 저장 국가를 무시하는 기존 정책을 정식 서비스 테스트로 검증한다.
- **시작 조건:** DEPREM-004 및 `reviews/문서대비구현-review.md`의 REV-002 확정. REV-001은 사용자 확인으로 결함 판정 철회; `2L` 제거 유지.
- **완료 증거:** 아래 테스트 추가 및 조건·assertion 소스 검토, 후속 실행이 허용된 경우 focused test 결과 기록. 실행하지 않았으면 실행 검증 대기로 남기고 완료 처리하지 않는다.
- **범위 밖:** production 정책·resolver·매핑 변경, API 변경, 테스트 helper 리팩터링, 전체 회귀 실행.
- **TDD 예외:** 현재 production은 올바르게 저장 국가를 무시하므로 신규 테스트는 처음부터 통과하는 것이 정상이다. 실패를 만들려고 정상 구현을 변경하지 않는다. 삭제된 테스트와 새 테스트의 입력·assertion 대조로 누락 검증 이전을 확인한다.
- **실행 제약:** 이번 문서 갱신에서는 테스트를 실행하지 않는다. 기존 자동 테스트 미실행 지시가 유지되는 동안 후속 작업도 소스 검토까지만 진행하고 실행 상태를 별도로 남긴다.
**Files:**
- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceServiceTest.kt`
- Update: `docs/20260917_성인콘텐츠노출정책_Deprecated함수_제거/plan-task.md`
- Update: `docs/20260917_성인콘텐츠노출정책_Deprecated함수_제거/reviews/문서대비구현-review.md`
**추가할 테스트:** 기존 `createMember`, `countryContext`, `service`, JUnit import를 재사용한다.
```kotlin
@Test
@DisplayName("비KR 요청에서는 회원의 저장 국가와 무관하게 전달한 성인 노출값을 사용한다")
fun shouldIgnoreStoredCountryCodeWhenRequestCountryIsNotKr() {
val member = createMember(id = 2401L, withAuth = false).apply {
countryCode = "KR"
}
countryContext.setCountryCode("US")
assertEquals("US", service.resolveCountryCode(member))
assertTrue(service.isAdultVisibleForQuery(member, isAdultContentVisible = true))
assertFalse(service.isAdultVisibleForQuery(member, isAdultContentVisible = false))
}
```
- [x] **누락 확인:** 삭제된 정책 테스트와 비교해 저장 KR·요청 US·미인증 조건이 기존 정식 테스트에 없음을 확인했다(TDD 예외 적용).
- [x] **최소 구현:** 위 테스트 1건만 추가했다. 강제 매핑이 없는 ID 2401을 사용하고 production은 변경하지 않았다.
- [x] **소스 검토:** 국가 결과 US 및 노출 전달값 true/false 보존 assertion을 확인했다. 저장 국가 KR을 우선하면 국가 assertion과 `true` 전달값 assertion이 실패한다.
- [ ] **실행 검증:** 자동 테스트 실행이 허용되는 후속 단계에서 아래 focused test와 ktlint를 실행하고 결과를 기록한다. 미실행이면 완료 표시하지 않는다.
- [x] **기록 갱신:** P3-T1의 기존 완료 기록을 유지하고, REV-002 보강 결과와 실행 대기 상태를 본 Task와 리뷰에 누적했다.
**후속 실행용 명령(이번에는 미실행):** 저장소와 호환되는 JDK 환경에서 실행한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceServiceTest'
./gradlew ktlintTestSourceSetCheck
```
기대 결과: 신규 테스트를 포함한 서비스 테스트 및 테스트 소스 ktlint 성공. 테스트 한 파일의 검증 보강이므로 전체 회귀는 생략한다.
## 검증 기록
- 2026-09-17 Phase 3 후속 P3-R1: 삭제된 정책 테스트와 현재 서비스 테스트를 대조해 저장 KR·요청 US·미인증 조건의 누락을 확인하고 `MemberContentPreferenceServiceTest.shouldIgnoreStoredCountryCodeWhenRequestCountryIsNotKr` 1건을 추가했다. 국가 결과 US와 전달값 true/false 보존 assertion을 소스로 검토했다. production은 변경하지 않았으며 기존 자동 테스트 미실행 지시에 따라 focused test와 ktlint는 실행하지 않아 Task 완료 처리는 보류했다.
- 2026-09-17 리뷰 후속 문서 갱신: 사용자가 JP 매핑의 `2L` 제거를 의도한 변경으로 확정했다. REV-002 검증 누락은 `P3-R1`로 추가하고 REV-003 호출 수는 27곳으로 정정했다. 문서와 테스트 소스의 식별자·조건을 대조했으며 사용자 지시에 따라 자동 테스트 및 Gradle 명령은 실행하지 않았다.
- 2026-09-17 Phase 1: `MemberContentPreferenceServiceTest` 실행 → RED에서 `Unresolved reference: isAdultVisibleForQuery` 확인, GREEN 후 25/25 통과. 검증 이유: 신규 판정 메서드가 Deprecated 함수와 동일한 결과를 내는지 확인.
- 2026-09-17 Phase 2: `AudioContentServiceTest.kt:118` 컴파일 실패로 생성자 변경 영향을 확인한 뒤 mock 주입. `src/test/kotlin/kr/co/vividnext/sodalive/content` 42/42 통과, `AudioContentServiceTest` 16/16 통과.
- 2026-09-17 Phase 3: `src/test/kotlin/kr/co/vividnext/sodalive/member/contentpreference` 36/36 통과(Deprecated 테스트 5건 삭제, 신규 3건 추가 반영).
- 2026-09-17 빈 주입 회귀: `SpringBootIntegrationSampleTest` 1/1 통과로 12개 서비스에 추가된 `MemberContentPreferenceService` 주입이 애플리케이션 컨텍스트에서 정상 해석됨을 확인(순환 의존 없음).
- 2026-09-17 스타일: `JAVA_HOME=<Android Studio JBR 21> ./gradlew ktlintMainSourceSetCheck ktlintTestSourceSetCheck` BUILD SUCCESSFUL. JetBrains JBR 25는 Gradle 8.1.1과 비호환이어서 Java 21 JBR을 사용했다.
- 2026-09-17 전체 회귀 생략: `./gradlew test` 전체 회귀는 실행하지 않았다. 근거는 변경이 `isAdult` 계산 위임 경로 치환으로 한정되고 공개 스키마/DB/보안 설정 변경이 없으며, 대신 변경 범위 focused test(`content` 42, `member/contentpreference` 36, `AudioContentServiceTest` 16)와 컨텍스트 로딩 테스트, ktlint 전체 소스셋 검사를 실행했다.
@@ -1,132 +0,0 @@
# 성인 콘텐츠 노출 정책 Deprecated 함수 제거 PRD
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | Phase 1~3 완료, 리뷰 후 고유 검증 보강 대기 |
| 작성일 | `2026-09-17` |
| 최종 수정일 | `2026-09-17` |
| 대상 제품 | 성인 콘텐츠 노출 여부 / 접속 국가 코드 계산 정책 |
| 작성자·결정권자 | Junie / 사용자 |
| 관련 API Contract | 기존 API 응답 스키마 변경 없음 |
| 관련 구현 계획 | `docs/20260917_성인콘텐츠노출정책_Deprecated함수_제거/plan-task.md` |
| 관련 review | `reviews/문서대비구현-review.md` |
## 1. Overview
성인 콘텐츠 노출 여부(`isAdult`)와 접속 국가 코드 계산 정책은 현재 두 경로에 중복 구현되어 있다. 하나는 `@Deprecated`로 표시된 top-level 함수 `MemberContentPreferencePolicy.isAdultVisibleByPolicy(...)` / `resolveCountryCodeByPolicy(...)`이고, 다른 하나는 정식 경로인 `MemberContentPreferenceService`다. Deprecated 경로가 production 12개 파일에서 여전히 27곳 호출되고 있어 정책 변경 시 두 곳을 모두 고쳐야 하는 위험이 남아 있다. 이 작업은 Deprecated 경로 호출부를 `MemberContentPreferenceService`로 이전하고 Deprecated 함수와 그 전용 테스트를 제거한다.
## 2. Problem Statement
- `MemberContentPreferencePolicy.kt`의 두 함수는 `docs/20260623_메인_콘텐츠_추천_탭_API/plan-task.md`에서 `@Deprecated` 처리만 되고 호출부 이전은 완료되지 않았다.
- 접속 국가 판정 기준이 두 경로에서 다르게 조달된다. Deprecated 경로는 `RequestContextHolder`에서 `CloudFront-Viewer-Country` 헤더를 직접 읽고, 정식 경로는 `CountryContext`(요청 스코프)에서 읽는다. 값 출처(같은 헤더, `CountryInterceptor`가 주입)는 같지만 경로가 둘이다.
- Deprecated 함수의 유일한 테스트인 `MemberContentPreferencePolicyTest`의 5개 검증은 `MemberContentPreferenceServiceTest` / `MemberContentPreferenceIntegrationTest`에 이미 동등하게 존재해, 회원 ID 강제 매핑 정책을 변경할 때마다 같은 상수를 3~4개 파일에서 함께 고쳐야 한다.
- 결과적으로 정책 변경(예: 국가 강제 매핑 회원 ID 추가/삭제)이 중복 지점 누락으로 회귀를 만들 수 있다.
문제를 해결했다는 판단은 `isAdultVisibleByPolicy` / `resolveCountryCodeByPolicy` 참조가 `src/main/kotlin`과 `src/test/kotlin`에서 0건이 되고, 기존 legacy 콘텐츠 조회 API의 `isAdult` 계산 결과가 그대로 유지되는 것으로 한다.
## 3. Goals
- 성인 콘텐츠 노출 여부 계산의 단일 진입점을 `MemberContentPreferenceService`로 만든다.
- `MemberContentPreferencePolicy.kt`의 Deprecated 함수 2개와 파일, 전용 테스트를 제거한다.
- 기존 legacy 콘텐츠 조회 API의 `isAdult` / 국가 코드 계산 동작을 유지하되, 사용자가 확정한 JP 강제 매핑의 `2L` 제거는 예외로 반영한다.
- 공개 API request/response 스키마를 변경하지 않는다.
## 4. Non-Goals
- `isAdult` 판정 정책 자체(KR + 본인인증 여부, 해외 전달값 사용)를 변경하지 않는다.
- JP 강제 매핑의 `2L` 제거 외에는 회원 ID 국가 강제 매핑(`FORCED_KR_MEMBER_IDS`, `FORCED_JP_MEMBER_IDS`) 값을 변경하지 않는다.
- `isAdultContentVisible`을 서비스 파라미터에서 제거하거나 저장값 조회로 대체하는 리팩터링은 하지 않는다. 호출부 시그니처는 유지한다.
- `CanController`의 통화(currency) 강제 지정 로직은 국가 강제 매핑과 무관하므로 건드리지 않는다.
- `MemberContentPreferenceCountryResolver.kt`의 강제 매핑 알고리즘은 유지하고, JP 대상에서 `2L`만 제외한다.
## 5. 영향 범위
### 5.1 Deprecated 함수 정의
| 파일 | 대상 |
|---|---|
| `src/main/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferencePolicy.kt` | `resolveCountryCodeByPolicy(member)`, `isAdultVisibleByPolicy(member, isAdultContentVisible)` |
### 5.2 production 호출부
| 파일 | 호출 수 |
|---|---:|
| `content/series/ContentSeriesService.kt` | 5 |
| `content/AudioContentService.kt` | 3 |
| `content/main/AudioContentMainService.kt` | 2 |
| `content/main/curation/AudioContentCurationService.kt` | 2 |
| `content/theme/AudioContentThemeService.kt` | 2 |
| `content/main/tab/free/AudioContentMainTabFreeService.kt` | 4 |
| `content/main/tab/alarm/AudioContentMainTabAlarmService.kt` | 2 |
| `content/main/tab/content/AudioContentMainTabContentService.kt` | 2 |
| `content/main/tab/home/AudioContentMainTabHomeService.kt` | 2 |
| `content/main/tab/asmr/AudioContentMainTabAsmrService.kt` | 1 |
| `content/main/tab/replay/AudioContentMainTabLiveReplayService.kt` | 1 |
| `content/main/tab/series/AudioContentMainTabSeriesService.kt` | 1 |
12개 파일, 총 27곳이다. 어떤 파일도 현재 `MemberContentPreferenceService`를 주입받지 않는다.
### 5.3 테스트 호출부
| 파일 | 처리 |
|---|---|
| `src/test/kotlin/.../member/contentpreference/MemberContentPreferencePolicyTest.kt` | 삭제. 동등 검증이 `MemberContentPreferenceServiceTest`, `MemberContentPreferenceIntegrationTest`에 이미 존재하며, 부족한 항목은 `MemberContentPreferenceServiceTest`로 이전한다. |
## 6. 기능 요구사항
| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 |
|---|---|---|---|---|
| `DEPREM-001` | 확정 | `MemberContentPreferenceService`에 `isAdultVisibleForQuery(member, isAdultContentVisible)`를 추가해 `resolveCountryCode(member)` + `calculateIsAdultForQuery(...)` 조합을 단일 메서드로 제공한다. | KR + `auth == null`이면 `false`, KR + `auth != null`이면 전달값, 비KR이면 전달값. 회원 ID 강제 매핑이 접속 국가 헤더보다 우선한다. | `P1-T1` |
| `DEPREM-002` | 확정 | production 12개 파일의 `isAdultVisibleByPolicy(...)` 27곳을 `memberContentPreferenceService.isAdultVisibleForQuery(...)`로 치환하고 `MemberContentPreferenceService`를 생성자 주입한다. | 각 파일에서 `isAdultVisibleByPolicy` import와 호출이 사라지고, `isAdult` 계산 결과가 기존과 동일하다. | `P2-T1`~`P2-T4` |
| `DEPREM-003` | 확정 | `MemberContentPreferencePolicy.kt`와 `MemberContentPreferencePolicyTest.kt`를 제거한다. | `isAdultVisibleByPolicy|resolveCountryCodeByPolicy` 검색 결과가 `src/main/kotlin`, `src/test/kotlin`에서 0건이다. | `P3-T1` |
| `DEPREM-004` | 확정 | Deprecated 테스트에서 제거되는 검증 항목 중 정식 경로 테스트에 없는 것은 `MemberContentPreferenceServiceTest`로 이전한다. | 헤더 공백/소문자 정규화(`" us "` → `US`), 국가 컨텍스트 없음 → `KR` fallback, 비KR에서 저장 `countryCode` 무시 검증이 정식 경로 테스트에 존재한다. | `P3-T1` |
| `DEPREM-005` | 확정 | 기존 legacy 콘텐츠 조회 동작을 회귀 없이 유지한다. | `AudioContentServiceTest` 등 영향 범위 테스트와 `member/contentpreference` 테스트가 모두 통과하고 ktlint가 통과한다. | `P3-GATE` |
## 7. API 계약
- 변경되는 공개 request/response 필드는 없다.
- 신규 message key, 신규 endpoint는 없다.
- 각 서비스의 public 메서드 시그니처(`isAdultContentVisible` 파라미터 포함)는 유지한다. 변경되는 것은 생성자 의존성뿐이다.
## 8. 보안과 데이터 취급
- 접속 국가 판정은 계속 `CloudFront-Viewer-Country` 헤더를 `CountryInterceptor`가 `CountryContext`에 주입한 값만 사용한다.
- 성인 콘텐츠 노출은 KR에서 본인인증(`member.auth != null`)이 있는 경우에만 허용하는 기존 정책을 유지한다.
- 회원 ID, 이메일 등 개인정보는 로그에 추가하지 않는다.
## 9. 리스크
| ID | 리스크 | 대응 |
|---|---|---|
| `RISK-001` | `CountryContext`는 `@RequestScope`이므로 비웹 스레드에서 호출되면 예외가 발생할 수 있다. Deprecated 함수는 `RequestContextHolder`가 없을 때 `KR`로 fallback했다. | 대상 12개 서비스가 controller 요청 경로에서만 호출되는지 Phase 2에서 파일별로 확인한다. 스케줄러/비동기 호출 경로가 발견되면 해당 Task를 진행하지 않고 계획을 먼저 갱신한다. |
| `RISK-002` | 생성자 파라미터 추가로 기존 서비스 테스트가 컴파일 실패할 수 있다. | 해소됨. `AudioContentServiceTest` 1곳만 영향받아 mock 주입으로 해결했다. |
| `RISK-003` | 순환 의존 발생 가능성. | `MemberContentPreferenceService`는 `MemberContentPreferenceRepository`, `MemberRepository`, `CountryContext`, `CacheManager`만 의존하므로 콘텐츠 서비스와 순환이 발생하지 않음을 확인했다. |
## 10. 성공 기준
- [x] `MemberContentPreferenceService.isAdultVisibleForQuery(...)`가 기존 `isAdultVisibleByPolicy(...)`와 동일한 판정을 한다. (`DEPREM-001`)
- [x] production 12개 파일 27곳이 모두 정식 경로를 호출한다. (`DEPREM-002`)
- [x] `MemberContentPreferencePolicy.kt`, `MemberContentPreferencePolicyTest.kt`가 제거되고 참조가 0건이다. (`DEPREM-003`)
- [x] Deprecated 테스트의 고유 검증이 `MemberContentPreferenceServiceTest`에 남아 있다. (`DEPREM-004`)
- [x] 영향 범위 focused test와 ktlint가 통과한다. (`DEPREM-005`)
## 11. Decision Log
기존 성공 기준 체크박스는 당시 완료 기록으로 유지한다. 후속 리뷰에서 DEPREM-004의 저장 국가 충돌 검증 누락을 확인했으며, `plan-task.md`의 `P3-R1` 완료 전까지 해당 검증 보강은 미완료다.
| 일시 | 결정 | 근거 |
|---|---|---|
| 2026-09-17 | Deprecated 함수 제거를 위해 production 호출부를 모두 마이그레이션하는 방식(선택지 3)을 택한다. | 사용자 선택. 테스트만 정식 경로로 바꾸면 production에서 쓰이는 Deprecated 경로가 커버리지 0이 되므로 부적절 |
| 2026-09-17 | 호출부 1:1 치환을 위해 `MemberContentPreferenceService`에 `isAdultVisibleForQuery(member, isAdultContentVisible)` wrapper를 추가한다. | 호출부마다 `resolveCountryCode(...)` + `calculateIsAdultForQuery(...)` 2단계를 반복하면 중복이 27곳으로 늘어남 |
| 2026-09-17 | `MemberContentPreferencePolicyTest`는 삭제하고 고유 검증만 `MemberContentPreferenceServiceTest`로 이전한다. | 5개 검증 중 대부분이 정식 경로 테스트와 중복이며, 함수 제거 후에는 테스트 대상이 사라짐 |
| 2026-09-17 | Phase를 서비스 묶음 단위로 나눠 진행한다. | 27곳 동시 변경 시 실패 원인 추적이 어려움. 저장소 규칙("작은 단위로 안전하게 수정") 준수 |
| 2026-09-17 | `RISK-001`은 해소로 판정한다. | 치환한 27곳이 모두 controller 진입 조회 경로임을 파일별로 확인했고, 스케줄러(`Recommendation/Ranking/ChargeEvent`)는 이 경로를 호출하지 않음 |
- 2026-09-17 사용자 확정: JP 강제 매핑에서 `2L`을 제거한 것은 의도된 정책 변경이다. REV-001은 결함 판정을 철회하며 `2L`을 복원하지 않는다. 나머지 매핑은 유지한다.
- 2026-09-17 후속 계획: REV-002의 저장 국가 무시 검증을 `P3-R1`로 추가한다. 이번 작업은 문서 갱신이며 테스트 구현·실행은 하지 않는다.
## 12. 열린 질문
- 없음. Phase 2에서 비웹 호출 경로(`RISK-001`)가 발견되면 계획을 먼저 갱신하고 사용자에게 확인한다.
@@ -1,65 +0,0 @@
# 문서 대비 구현 리뷰
## 리뷰 정보와 범위
- 일자: 2026-09-17
- 기준: HEAD `8c87286acd69174f6024d30a267458e838e35cf5` 및 리뷰 시작 시 존재한 미커밋 변경
- 요구사항: `../prd.md`, `../plan-task.md`의 Phase 1~3
- 방법: 문서, production 코드, 테스트 소스, 현재 diff와 호출 경로 정적 대조
- 사용자 지시에 따라 자동 테스트·빌드·ktlint·애플리케이션 실행은 하지 않았다. 기존 실행 성공 기록을 재검증한 것으로 취급하지 않는다.
- 구현 및 기존 PRD/계획은 수정하지 않았다. 아래 판정은 현재 작업 트리에 대한 것이며 변경 작성자나 의도를 추정하지 않는다.
## 발견 사항
### REV-001 — 강제 JP 매핑 값이 변경됨
- 심각도: High / 상태: 확정
- 요구사항: PRD §3 기존 동작 유지, §4 강제 매핑 값 변경 금지; 계획 P3-T1의 resolver 변경 제외
- 근거: `src/main/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceCountryResolver.kt:6`에서 `FORCED_JP_MEMBER_IDS`의 `2L`이 제거됐다.
- 코드 추적: 회원 ID 2, 인증 없음, 요청 국가 KR 또는 헤더 없음, `isAdultContentVisible=true`이면 기존 JP 판정/성인 노출 true에서 KR 판정/false로 바뀐다.
- 관련 테스트도 `MemberContentPreferenceServiceTest.kt:64`, `MemberContentPreferenceIntegrationTest.kt:187`에서 ID 2를 29721로 교체해 기존 매핑 회귀를 검출하지 못한다.
- 권장 조치: 문서대로라면 기존 매핑과 해당 테스트 대상을 복원한다. 별도로 의도한 정책 변경이라면 해당 결정과 범위를 문서에 명시해야 한다.
### REV-002 — 저장 국가 무시 검증이 이전되지 않음
- 심각도: Medium / 상태: 확정
- 요구사항: DEPREM-004, P3-T1
- 근거: 삭제된 PolicyTest는 저장 `member.countryCode="KR"`, 요청 국가 US 조건을 검증했다. 현재 `MemberContentPreferenceServiceTest.kt:469`의 해외 노출 테스트와 `:536`의 회원 생성 함수는 저장 국가를 설정하지 않는다. IntegrationTest에도 이 충돌 조건이 없다.
- 영향: 현재 resolver는 저장 국가를 참조하지 않아 구현 자체는 맞지만, 문서에서 이전하도록 요구한 고유 회귀 검증이 빠졌다. `plan-task.md:224`의 기존 테스트가 이미 커버한다는 기록은 부정확하다.
- 권장 조치: 일반 미인증 회원의 저장 국가를 KR로 설정하고 요청 국가는 US로 두어, 정식 진입점의 국가 US/성인 노출 true를 확인하는 검증을 추가한다.
### REV-003 — 호출부 합계 오기
- 심각도: Low / 상태: 확정
- 근거: PRD §5.2 표의 합계와 실제 치환은 모두 12개 파일 27곳이다. PRD와 계획에는 반복해서 24곳으로 기록돼 있다.
- 영향: 호출 치환 누락은 없으며 문서 수치가 틀렸다.
- 권장 조치: 두 문서의 합계를 27곳으로 정정한다.
## 충족 항목과 한계
| 항목 | 정적 검토 결과 |
|---|---|
| DEPREM-001 단일 진입점 | 기존 resolveCountryCode + calculateIsAdultForQuery 재사용, 추가 DB 조회 없음 |
| DEPREM-002 호출부 이전 | 12개 파일 27곳 이전, 인자 및 홈의 member=null → false 유지 |
| DEPREM-003 정의/참조 제거 | 두 파일 삭제, src/main/kotlin 및 src/test/kotlin의 두 Deprecated 함수 이름 검색 0건 |
| DEPREM-004 고유 검증 이전 | 정규화/null 국가값 fallback은 존재, 저장 국가 충돌 검증 누락 |
| DEPREM-005 실행 검증 | 사용자 요청에 따라 재실행 제외 |
| API 계약 | 기존 공개 메서드 인자와 request/response 스키마 변경 없음 |
| 요청 경로/의존성 | 변경된 조회 메서드의 비웹 호출 및 새 순환 의존 발견 없음 |
국가값 null 검증은 요청 스코프 자체가 없는 상황과 다르다. 새 경로는 요청 스코프와 회원 ID를 요구하므로 모든 입력에서 구 함수와 동등하다고 일반화할 수 없다. 다만 검토한 변경 호출 경로에서 해당 비웹/ID 없는 입력은 확인하지 못해 별도 운영 결함으로 확정하지 않았다.
## 리뷰 종료 판정과 후속 작업
요구사항, 테스트 소스, 코드 품질, 보안, 주변 호출 맥락의 검토 결과를 종합했다. 확정 불일치 3건으로 문서와 완전히 일치하는 구현이라고 판정할 수 없다.
이번 요청은 검토이므로 수정 goal은 실행하지 않았다. 후속 구현 시 기존 완료 기록을 유지하면서 REV-001 매핑 일치, REV-002 고유 검증 이전, REV-003 문서 수치 정정을 별도 회귀 Task로 계획에 추가한다. 자동 검증은 이번 검토에서 수행하지 않았다.
## 후속 판정 정정 — 2026-09-17
위 내용은 최초 검토 당시 기록이며, 사용자 확인 이후 현재 판정은 다음과 같다.
- **REV-001: 결함 판정 철회.** 사용자가 `2L` 제거를 의도한 변경으로 확정했다. PRD·계획에 해당 예외를 반영했으며 매핑과 테스트 대상을 복원하지 않는다.
- **REV-002: 구현 완료 / 실행 검증 대기.** `MemberContentPreferenceServiceTest.shouldIgnoreStoredCountryCodeWhenRequestCountryIsNotKr`를 추가해 저장 KR·요청 US·미인증 회원 조건에서 국가 결과 US와 전달값 true/false 보존을 검증한다. production은 변경하지 않았고, 기존 자동 테스트 미실행 지시에 따라 focused test와 ktlint는 실행하지 않았다.
- **REV-003: 문서 정정 완료.** PRD·계획의 24곳 표기를 실제 합계 27곳으로 정정했다.
- **현재 결론:** `P3-R1` 테스트 구현과 소스 검토는 완료했으며, 남은 항목은 focused test와 ktlint 실행 검증이다.
@@ -1,62 +0,0 @@
# 캔 조회 회원 2 강제 통화 제거 구현 계획
- 상태: 구현 완료
- 작성일: 2026-09-18
- 요구사항: [prd.md](prd.md)
- 현재 Phase: 1 완료
- 활성 Goal: 없음
- 실행 순서: CAN-P1-T1 → CAN-P1-GATE
### Phase 1: 회원 2의 기본 통화 적용과 회귀 확인
- [x] **Task 1.1: 회원 2의 강제 통화 제거** (`CAN-P1-T1`)
- Objective: 회원 2가 다른 일반 회원처럼 요청 국가에 따른 통화의 캔 상품을 조회한다.
- 시작 조건: PRD 확정, 기존 컨트롤러·서비스 및 테스트 확인 완료.
- 완료 증거: RED/GREEN 결과, 실제 컨트롤러·서비스·저장소 통합 테스트와 캔 패키지 회귀 통과.
- 범위 밖: 다른 회원 예외 제거, 국가 결정·API 스키마·서비스 리팩터링.
- 수정: `src/main/kotlin/kr/co/vividnext/sodalive/can/CanController.kt`
- 생성: `src/test/kotlin/kr/co/vividnext/sodalive/can/CanControllerIntegrationTest.kt`
- 확인: `src/main/kotlin/kr/co/vividnext/sodalive/can/CanService.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/can/CanServiceTest.kt`
- [x] **RED:** 회원 2의 KRW/USD, 유지할 예외·일반 회원·비로그인·국가 누락 통합 테스트를 작성한다.
- [x] **RED 확인:** `./gradlew test --tests 'kr.co.vividnext.sodalive.can.CanControllerIntegrationTest'`로 회원 2의 JPY 반환 assertion 실패를 확인한다.
- [x] **GREEN:** 컨트롤러 조건에서 `member.id == 2L ||`만 제거한다.
- [x] **GREEN 확인:** 동일 focused test가 통과하는지 확인한다.
- [x] **REFACTOR:** 불필요한 정리 없이 `./gradlew test --tests 'kr.co.vividnext.sodalive.can.*'` 및 변경 파일 lint로 회귀를 확인한다.
#### Task 검증 기록
- 2026-09-18: 기존 `getCans` 및 `/can` 직접 테스트가 없음을 확인했다. 새 테스트는 `@SpringBootTest`와 H2, 요청 범위의 실제 CountryContext를 사용하고 트랜잭션 롤백으로 상품 데이터를 격리한다.
- 2026-09-18 RED: 테스트 작성 중 `Member.password` 필수 인자 누락을 수정한 뒤 production/test 컴파일이 통과했다. 이후 공통 JWT 기본 키의 길이 부족으로 발생한 컨텍스트 로딩 실패는 테스트 실행에만 임시 키를 제공하여 해결했다. 이 두 실패는 동작 RED에 포함하지 않았다.
- 2026-09-18 RED 확인: 아래 환경 설정 후 `./gradlew test --tests 'kr.co.vividnext.sodalive.can.CanControllerIntegrationTest' --console=plain` 실행. 13개 중 회원 2의 4개만 assertion 실패(exit 1): KR은 KRW, US/JP/국가 누락은 USD 기대였으나 실제 JPY. 나머지 9개 통과.
- 2026-09-18 GREEN 확인: 조건 제거 후 같은 focused 명령으로 13개 전부 통과(exit 0), production/test 컴파일 성공.
- 2026-09-18 회귀 확인: `./gradlew test --tests 'kr.co.vividnext.sodalive.can.*' --console=plain` 성공(exit 0). 신규 13개와 기존 14개, 총 5개 클래스 27개 테스트 통과(실패·오류·skip 0). 기존 테스트를 완화하거나 수정할 필요가 없었다.
- [x] **Phase Gate: 변경 범위와 검증 기록 확인** (`CAN-P1-GATE`)
- Objective: 요구사항과 최소 변경, 검증 증거가 일치함을 확인한다.
- 시작 조건: CAN-P1-T1 완료.
- 완료 증거: 캔 패키지 테스트 통과, 문서 명령·diff 확인 및 PRD 체크박스 완료.
- 범위 밖: 전체 서비스 실행과 관련 없는 기능 수정.
- 확인 파일: 이 문서, `docs/20260918_캔조회_회원2_강제통화제거/prd.md`, 위 Task의 코드·테스트.
- TDD 예외 사유: 구현 없는 최종 검증 단계.
- 대체 검증 방법: `./gradlew tasks --all`, `git diff --check`, 변경 파일 대조.
## 검증 범위
- 단일 루트 프로젝트이며 변경은 컨트롤러의 조건 하나에 한정된다. 전체 회귀 실행 조건(공통 코드·여러 도메인 변경·영향 불명확 실패·사용자 명시 요청)이 발생하지 않으면 전체 테스트는 생략하고 캔 패키지 전체를 실행한다.
- 테스트 실행으로 production/test 컴파일을 함께 확인한다. 새 API나 실행 환경 변경이 없어 별도 애플리케이션 구동은 하지 않는다.
## Progress
- 2026-09-18: 요구사항 및 TDD 계획 작성, CAN-P1-T1 준비.
- 2026-09-18: CAN-P1-T1 RED 확인 완료, 회원 2 조건 제거 진행.
- 2026-09-18: CAN-P1-T1 완료. 조건 한 항만 제거했고 신규 13개 및 기존 14개 테스트가 통과했다.
- 2026-09-18: CAN-P1-GATE 완료. API 스키마·다른 회원 예외가 유지되는 diff와 PRD 수용 기준, 검증 기록을 대조했다. 남은 작업 없음.
## 공통 검증 기록
- 셸에 기본 Java가 없어 기존 Gradle 캐시의 Java 17을 사용했다. 설정 파일은 변경하지 않았다.
- 테스트 JWT 기본값은 디코딩 후 키 길이가 부족하므로 실행 프로세스에만 임시 키를 전달했다. 키 값은 저장·출력하지 않는다. 아래 환경 설정 뒤 문서의 검증 명령을 실행한다.
```bash
export JAVA_HOME=~/.gradle/jdks/eclipse_adoptium-17-x86_64-os_x.2/jdk-17.0.19+10/Contents/Home
export JWT_SECRET="$(openssl rand -base64 64 | tr -d '\n')"
```
- 2026-09-18: `./gradlew tasks --all --console=plain`, `git diff --check` 성공(exit 0). 변경 Kotlin 파일의 IDE 정적 검사에서 오류 없음. 신규 테스트는 경고도 없으며 기존 컨트롤러의 수정하지 않은 인증 SpEL 식에는 변수 해석 경고 8개가 있다.
- 2026-09-18: 전체 테스트·전체 ktlint 및 별도 서버 실행은 생략했다. 변경은 컨트롤러 조건 한 곳이고 다른 도메인·공통 코드·하위 모듈 변경이 없어 focused 통합 테스트, 캔 패키지 전체 회귀, 변경 파일 정적 검사로 검증했다.
@@ -1,27 +0,0 @@
# 캔 조회 회원 2 강제 통화 제거
## 문서 정보
- 상태: 구현 완료
- 작성일: 2026-09-18
- 관련 계획: [plan-task.md](plan-task.md)
## 문제와 목표
`GET /can`의 `getCans`는 회원 2·4·44144에게 JPY를 강제 적용한다.
사용자 요청에 따라 회원 2만 제외하여 기존 국가별 통화 선택을 따르게 한다.
## 확정 요구사항과 수용 기준
| ID | 요구사항 | 수용 기준 | Goal |
|---|---|---|---|
| CAN-CURRENCY-001 | 회원 2의 JPY 강제 조건 제거 | KR 요청은 KRW, 그 외 국가는 USD 상품 반환 | CAN-P1-T1 |
| CAN-CURRENCY-002 | 나머지 동작 유지 | 회원 4·44144는 JPY, 일반 회원·비로그인은 기존 국가별 통화 적용 | CAN-P1-T1 |
| CAN-CURRENCY-003 | 관련 테스트 검증 | 변경 전 실패 재현, 변경 후 캔 패키지 테스트 통과 | CAN-P1-GATE |
## 범위 밖
- 다른 진입점의 회원 ID 조건, 국가 판정 및 성인콘텐츠 정책 변경.
- 서비스의 KR → KRW / 그 외 → USD 정책 변경.
- 공개 API 요청·응답 스키마, 인증 및 상품 판매 상태 필터 변경.
## 성공 기준
- [x] 회원 2에 대한 회귀 테스트가 변경 전 실패하고 변경 후 통과한다.
- [x] 회원 4·44144, 일반 회원, 비로그인 및 국가 누락의 기존 동작이 유지된다.
- [x] 관련 기존 테스트가 통과하고 검증 결과를 계획 문서에 기록한다.
@@ -1,120 +0,0 @@
# 기존 관리자 선물함에 신청 취소 기능 추가 프롬프트
## 목적과 사용 범위
- 이 문서는 이미 존재하는 관리자 선물함에 기능 하나를 추가하기 위한 전달용 프롬프트다.
- 아래 확정된 API Request/Response 계약을 기준으로 타입, API client, 화면 액션과 테스트를 구현한다.
- [기존 전체 페이지 프롬프트](admin-page-prompts.md)는 수정하거나 다시 실행하지 않는다.
- 계약 기준: [PRD 8.14.1 관리자 선물 신청 취소](prd.md#8141-관리자-선물-신청-취소).
## 복사해서 전달할 증분 구현 프롬프트
아래 블록 전체를 기존 프론트엔드 저장소의 구현 담당자에게 전달한다.
````markdown
# 기존 관리자 선물함에 신청 취소 액션만 추가
## 1. 기존 코드 확인
이미 구현된 관리자 선물함 목록/상세에 `신청 취소` 기능만 증분으로 추가해줘.
페이지를 새로 만들거나 기존 전체 페이지 구현 프롬프트를 재실행하지 마.
- 먼저 기존 프론트엔드 코드를 읽고 목록, 상세, 액션 타입, 액션 dispatch 위치를 확인한다.
- API 인증/권한, 공통 API client, 응답 envelope 해제 방식, 확인창, 토스트, 오류 처리를 확인한다.
- 기존 상태 변경 액션의 pending 처리와 목록/상세 재조회 방식을 그대로 사용한다.
- 변경할 실제 파일과 재사용할 기존 패턴을 먼저 짧게 정리한다.
- 아래 API 계약을 기준으로 구현한다. 기존 타입이나 호출부가 계약과 다르면 차이를 보고하고 이 기능의 변경 범위 안에서 맞춘다.
## 2. 유지할 기존 화면과 액션
- 기존 `/gift/list` 라우트, 메뉴, 레이아웃, 테이블 컬럼, 필터, 페이지네이션을 보존한다.
- 기존 상세 모달/패널과 액션 표시·실행 프레임워크를 그대로 확장한다.
- `ARRIVE_MAILBOX`, `COMPLETE_INSPECTION`, `COMPLETE_DELIVERY`, `MARK_UNDELIVERABLE`을 보존한다.
- 기존 전달 불가 사유 입력/검증 및 각 액션의 확인창·성공·실패 동작을 변경하지 않는다.
- `COMPLETE_DELIVERY`의 수취인 필수 정보 조건부 허용을 유지한다.
- 모든 기존 액션도 서버 `availableActions`를 따르며 로컬 상태 매핑으로 대체하지 않는다.
- 받을 주소, 카테고리, 사이즈 설정 화면은 수정하지 않는다.
## 3. 최소 타입/dispatch 확장과 버튼 노출
- 기존 `AdminGiftAction` 타입에 `CANCEL`을 추가하되 기존 값을 삭제하거나 재정의하지 않는다.
- 기존 액션 라벨/핸들러 dispatch에 `CANCEL`과 `신청 취소`만 추가한다.
- 목록 row와 열린 상세 모두 기존 액션 렌더링/실행 경로에 연결한다.
- 각 화면의 서버 응답 `availableActions.includes("CANCEL")`일 때만 취소 버튼을 표시한다.
- API 계약상 `RECEIVED`에서만 `CANCEL`을 제공한다. 다른 상태에서는 제공하지 않는다.
- `status === "RECEIVED"`만으로 취소 권한을 만들거나 버튼을 강제로 추가하지 않는다.
- 목록/상세 중 한쪽의 로컬 값을 다른 쪽의 권한 판단에 대신 사용하지 않는다.
- 권한의 최종 판단은 서버가 하며, 관리자가 발신자 본인일 필요는 없다.
## 4. 확정 API 계약
액션 조회:
- 목록: `GET /api/v2/admin/gifts`, `data.items[].availableActions`를 사용한다.
- 상세: `GET /api/v2/admin/gifts/{applicationNo}`, `data.availableActions`를 사용한다.
- 접수 완료 응답: `status="RECEIVED"`, `statusName="접수 완료"`, `availableActions=["CANCEL"]`.
- 취소 후 응답: `status="CANCELED"`, `statusName="신청 취소"`, `availableActions=[]`.
취소 요청:
- Method: `POST`
- URL: `/api/v2/admin/gifts/{applicationNo}/cancel`
- 권한: `ADMIN` 전용. 기존 관리자 인증/권한 경로를 재사용한다.
- Request body: 없음. `{}`, 취소 사유, 환불액 등을 보내지 않는다.
- 서버 전이: `RECEIVED`에서만 `CANCELED`로 변경한다.
- 환불: 원 발신자에게 사용 캔 전액을 리워드캔으로 환불한다.
- 관리자의 잔액으로 환불하는 기능이 아니다. 프론트에서 환불/잔액 변경을 직접 처리하지 않는다.
- 성공 응답: 공통 envelope의 `success=true`와 아래 `data`이며 기존 client의 envelope 처리 방식에 맞춘다. HTTP 성공 코드만으로 업무 성공을 판단하지 않는다.
```json
{
"applicationNo": "A-1002609300001",
"status": "CANCELED",
"statusName": "신청 취소",
"occurredAt": "2026-09-30T12:00:00Z"
}
```
`occurredAt`은 서버의 `canceledAt`과 같은 UTC ISO `Z` 문자열이다.
기존 `AdminGiftOperationStatusResponse`를 재사용하고 로컬 현재 시각으로 값을 만들지 않는다.
## 5. 확인과 요청 중 처리
- 기존 확인창 컴포넌트를 사용하며 대상 `applicationNo`를 명확히 표시한다.
- 확인 문구 예: `신청번호 {applicationNo}의 선물 신청을 취소하시겠습니까?`
- 환불 안내: `사용한 캔 전액이 발신자에게 리워드캔으로 환불됩니다.`
- 확인창을 닫거나 취소하면 API를 호출하지 않는다. 명시적으로 확정한 경우에만 호출한다.
- 확정한 신청번호로 body 없는 요청을 한 번만 보낸다.
- pending 동안 확인 버튼과 같은 신청의 목록/상세 취소 버튼을 비활성화해 중복 제출을 막는다.
- 기존 client의 mutation 재시도 정책도 확인하고 취소 요청을 무조건 자동 재시도하지 않는다.
- 키보드 포커스/확인창 접근성과 pending 표시는 기존 관리자 패턴을 유지한다.
## 6. 성공과 실패
- 서버 성공 확인 후 기존 성공 토스트를 표시한다. 응답 전에 성공으로 처리하지 않는다.
- 현재 필터와 현재 페이지/페이지 크기를 유지한 채 목록을 다시 조회한다.
- 상세가 열려 있으면 해당 상세도 다시 조회해 서버의 현재 상태와 액션을 반영한다.
- 취소된 항목의 서버 상태는 `CANCELED`, `statusName`은 `신청 취소`, `availableActions`는 `[]`다.
- 현재 필터에 맞지 않아 목록에서 사라져도 필터를 초기화하거나 첫 페이지로 임의 이동하지 않는다.
- 실패는 기존 공통 오류 토스트/알림을 사용하며 별도 오류 스키마나 HTTP 정책을 만들지 않는다.
- 서버가 상태 변경/잘못된 요청을 알리거나 통신 실패로 처리 결과가 불명확하면
기존 패턴에 따라 목록과 열린 상세의 서버 현재 상태를 재조회한다. mutation은 재시도하지 않는다.
- 실패 시 로컬 상태를 가짜 `CANCELED`로 바꾸거나 성공 토스트/환불 완료를 표시하지 않는다.
## 7. 구현 후 집중 검증
확정 계약의 성공·실패 응답 fixture와 기존 API client mock을 테스트 범위에서 사용해 화면 및 요청 동작을 검증한다. 실행 코드에 자동 fallback이나 가짜 성공 처리를 추가하지 않는다. 실제 API 연동 검증 결과는 단위/컴포넌트 테스트 결과와 구분해 보고한다.
- 목록과 상세 각각 `RECEIVED` + 서버 `CANCEL`이면 버튼이 나오고 기존 dispatch로 실행되는지 확인한다.
- `RECEIVED`여도 `CANCEL`이 없으면 버튼이 없고, 다른 모든 상태에는 `CANCEL`이 없는지 확인한다.
- 확인창에 신청번호/발신자 전액 리워드캔 환불이 표시되고 확인을 닫으면 API 호출이 0회인지 확인한다.
- 확정 시 정확한 URL로 body 없이 1회만 요청하며 연속 클릭과 목록/상세 중복 실행이 막히는지 확인한다.
- 성공 후 필터/페이지가 유지되고 목록과 열린 상세가 갱신되며 취소 건의 액션이 없어지는지 확인한다.
- 실패 시 공통 오류를 표시하고 가짜 취소/성공이 없으며 필요한 현재 상태 재조회가 수행되는지 확인한다.
- 기존 운영 액션과 `COMPLETE_DELIVERY`의 수취인 정보 조건부 노출이 그대로인지 회귀 확인한다.
- 기존 프론트엔드 테스트 도구로 위 변경 범위만 검증하고 실행 결과/미검증 항목을 보고한다.
## 8. 범위 밖
취소 사유 필드, 취소 전용 푸시 흐름, 새 페이지/라우트, 새 디자인 시스템은 추가하지 않는다.
백엔드 구현, 사용자 직접 취소/자동취소 변경, 기존 페이지 전면 재작성도 이 작업에 포함하지 않는다.
````
@@ -1,549 +0,0 @@
# 선물 관리자 페이지 구현 프롬프트
이 문서는 관리자 페이지의 선물 관련 4개 화면을 프론트엔드 구현 에이전트에게 전달하기 위한 프롬프트 모음이다.
공통 전제:
- 관리자 메뉴에는 parent 메뉴 `선물함 관리` 아래에 다음 4개 하위 메뉴가 있다.
- `선물함 리스트` → `/gift/list`
- `받을 주소` → `/gift/mailbox`
- `선물 카테고리` → `/gift/category`
- `선물 사이즈` → `/gift/size`
- 모든 API 응답은 기존 공통 envelope를 사용한다. 화면에서는 `response.data`를 실제 payload로 사용한다.
- 인증/권한 처리는 기존 관리자 페이지의 API 클라이언트, 토큰 저장 방식, 에러 처리 방식을 따른다.
- 새 디자인 시스템을 만들지 말고 기존 관리자 페이지의 테이블, 필터, 버튼, 모달, 폼, 토스트, 확인창 패턴을 재사용한다.
- 화면 문구는 한국어로 작성한다.
- API 실패 시 기존 관리자 페이지의 공통 에러 표시 방식을 따른다.
---
## 1. 선물함 리스트 페이지 프롬프트
```text
관리자 선물함 리스트 페이지를 구현해줘.
목표:
- 관리자 메뉴 `선물함 관리 > 선물함 리스트`에서 전체 선물 신청 목록을 조회한다.
- 상태, 신청번호, 닉네임으로 필터링할 수 있다.
- 목록 row에서 선물 상세를 확인하고, 현재 상태에서 가능한 운영 액션을 실행할 수 있다.
- 기존 관리자 페이지의 테이블/필터/페이지네이션/모달/확인창 스타일을 그대로 따른다.
라우트:
- `/gift/list`
필수 화면 구성:
- 상단 제목: `선물함 리스트`
- 필터 영역:
- 상태 select: 전체, 접수 완료, 발송 확인, 사서함 도착, 검수 완료, 전달 완료, 전달 불가, 신청 취소
- 신청번호 검색 input: `applicationNo` 부분 검색
- 닉네임 검색 input: 발송인 또는 수취인 닉네임 부분 검색
- 검색 버튼, 초기화 버튼
- 목록 테이블 컬럼:
- 신청번호 `applicationNo`
- 발송인 닉네임 `senderNickname`
- 수취인 닉네임 `recipientNickname`
- 사이즈 `sizeName` / `sizeCode`
- 카테고리 `categoryName`
- 분류번호 `classificationNumber`
- 택배사 `courierCompanyName`
- 운송장번호 `trackingNumber`
- 상태 `statusName`
- 액션 버튼
- 페이지네이션:
- 서버의 `page`, `size`, `totalCount`, `hasNext` 기준으로 기존 관리자 페이지 패턴에 맞춘다.
목록 조회 API:
- Method: `GET`
- URL: `/api/v2/admin/gifts`
- Query:
- `status?: GiftStatus`
- `applicationNo?: string`
- `nickname?: string`
- `page?: number` 기본 `0`
- `size?: number` 기본 `20`
- 필터 조합:
- 선택 필터는 AND 조건이다.
- `nickname`은 발송인/수취인 닉네임 중 하나에 포함되면 매칭된다.
목록 조회 response `data`:
```ts
type AdminGiftListResponse = {
totalCount: number;
items: AdminGiftListItemResponse[];
page: number;
size: number;
hasNext: boolean;
};
type AdminGiftListItemResponse = {
applicationNo: string;
senderNickname: string;
recipientNickname: string;
sizeCode: string;
sizeName: string;
categoryName: string;
classificationNumber: string;
courierCompanyName: string | null;
trackingNumber: string | null;
status: GiftStatus;
statusName: string;
availableActions: AdminGiftAction[];
};
```
상태 enum:
```ts
type GiftStatus =
| "RECEIVED"
| "TRACKING_REGISTERED"
| "ARRIVED_AT_MAILBOX"
| "INSPECTION_COMPLETED"
| "DELIVERED"
| "UNDELIVERABLE"
| "CANCELED";
```
상태 표시명:
- `RECEIVED`: `접수 완료`
- `TRACKING_REGISTERED`: `발송 확인`
- `ARRIVED_AT_MAILBOX`: `사서함 도착`
- `INSPECTION_COMPLETED`: `검수 완료`
- `DELIVERED`: `전달 완료`
- `UNDELIVERABLE`: `전달 불가`
- `CANCELED`: `신청 취소`
상세 조회 API:
- Method: `GET`
- URL: `/api/v2/admin/gifts/{applicationNo}`
- 용도:
- 목록 row 클릭 또는 `상세` 버튼 클릭 시 상세 모달/상세 패널을 연다.
상세 response `data`:
```ts
type AdminGiftDetailResponse = {
applicationNo: string;
senderInfo: AdminGiftMemberInfoResponse;
recipientInfo: AdminGiftMemberInfoResponse;
productInfo: AdminGiftProductInfoResponse;
inboundDeliveryInfo: AdminGiftInboundDeliveryInfoResponse;
status: GiftStatus;
statusName: string;
availableActions: AdminGiftAction[];
};
type AdminGiftMemberInfoResponse = {
nickname: string;
name: string;
phoneNumber: string;
address: string;
};
type AdminGiftProductInfoResponse = {
sizeCode: string;
sizeName: string;
categoryName: string;
classificationNumber: string;
};
type AdminGiftInboundDeliveryInfoResponse = {
courierCompanyName: string | null;
trackingNumber: string | null;
};
```
상세 표시 요구사항:
- 발송인 정보: 닉네임, 이름, 전화번호, 주소
- 수취인 정보: 닉네임, 이름, 전화번호, 주소
- 상품 정보: 사이즈, 카테고리, 분류번호
- 입고 배송 정보: 택배사, 운송장번호
- 현재 상태와 가능한 액션
- 수취인이 배송지를 아직 입력하지 않은 경우 `recipientInfo.nickname`은 표시하고 `name`, `phoneNumber`, `address`는 빈 문자열로 온다. 화면에서는 `미입력`으로 표시해도 된다.
운영 액션 enum:
```ts
type AdminGiftAction =
| "ARRIVE_MAILBOX"
| "COMPLETE_INSPECTION"
| "COMPLETE_DELIVERY"
| "MARK_UNDELIVERABLE";
```
상태별 `availableActions`:
- `RECEIVED`: 없음
- `TRACKING_REGISTERED`: `ARRIVE_MAILBOX`, `MARK_UNDELIVERABLE`
- `ARRIVED_AT_MAILBOX`: `COMPLETE_INSPECTION`, `MARK_UNDELIVERABLE`
- `INSPECTION_COMPLETED`: `COMPLETE_DELIVERY`, `MARK_UNDELIVERABLE`
- `DELIVERED`: 없음
- `UNDELIVERABLE`: 없음
- `CANCELED`: 없음
액션 버튼 문구:
- `ARRIVE_MAILBOX`: `사서함 도착 처리`
- `COMPLETE_INSPECTION`: `검수 완료 처리`
- `COMPLETE_DELIVERY`: `전달 완료 처리`
- `MARK_UNDELIVERABLE`: `전달 불가 처리`
액션 API:
- 사서함 도착 처리
- Method: `POST`
- URL: `/api/v2/admin/gifts/{applicationNo}/arrive-mailbox`
- Body: 없음
- 검수 완료 처리
- Method: `POST`
- URL: `/api/v2/admin/gifts/{applicationNo}/complete-inspection`
- Body: 없음
- 전달 완료 처리
- Method: `POST`
- URL: `/api/v2/admin/gifts/{applicationNo}/complete-delivery`
- Body: 없음
- 전달 불가 처리
- Method: `POST`
- URL: `/api/v2/admin/gifts/{applicationNo}/mark-undeliverable`
- Body:
```ts
type AdminGiftMarkUndeliverableRequest = {
reason: string;
};
```
액션 response `data`:
```ts
type AdminGiftOperationStatusResponse = {
applicationNo: string;
status: GiftStatus;
statusName: string;
occurredAt: string; // UTC ISO string, e.g. 2026-09-30T12:00:00Z
};
```
액션 UX:
- 모든 상태 변경 액션은 확인창을 띄운다.
- `MARK_UNDELIVERABLE`은 사유 입력 모달을 띄운다.
- 전달 불가 사유는 공백만 입력할 수 없고 255자 이내로 제한한다.
- 액션 성공 후:
- 상세 모달이 열려 있으면 상세를 다시 조회한다.
- 목록도 현재 필터/페이지 기준으로 다시 조회한다.
- 성공 토스트를 표시한다.
- 액션 실패 시 기존 관리자 페이지 에러 토스트/알림 패턴을 따른다.
빈 값 표시:
- `courierCompanyName`, `trackingNumber`가 null이면 `-`로 표시한다.
- 수취인 개인정보가 빈 문자열이면 `미입력`으로 표시한다.
테스트/검증:
- API 클라이언트 함수 단위 테스트 또는 페이지 테스트에서 query parameter가 올바르게 전달되는지 확인한다.
- `availableActions`에 따라 버튼 노출이 달라지는지 확인한다.
- 전달 불가 사유 빈 값 validation을 확인한다.
```
---
## 2. 받을 주소 설정 페이지 프롬프트
```text
관리자 선물 받을 주소 설정 페이지를 구현해줘.
목표:
- 관리자 메뉴 `선물함 관리 > 받을 주소`에서 팬이 선물을 보낼 전역 단일 주소를 조회하고 저장한다.
- 이 주소는 팬의 보낸 선물 상세 API에서 정상 진행 상태 중 전달 완료 전(`RECEIVED`, `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`)일 때 `mailbox`로 노출된다.
- 기존 관리자 페이지의 폼, 저장 버튼, 토스트, 에러 표시 패턴을 그대로 따른다.
라우트:
- `/gift/mailbox`
필수 화면 구성:
- 상단 제목: `받을 주소`
- 설명 문구: `팬이 선물을 발송할 때 확인하는 받을 주소입니다.`
- 입력 폼:
- 받을 사람 이름 `name`
- 연락처 `phoneNumber`
- 우편번호 `zipCode`
- 주소 `address`
- 상세주소 `addressDetail`
- 저장 버튼: `저장`
초기 조회 API:
- Method: `GET`
- URL: `/api/v2/admin/gift-mailbox`
- response `data`:
```ts
type AdminGiftMailboxResponse = {
name: string;
address: string;
phoneNumber: string;
} | null;
```
- `data`가 null이면 빈 폼을 표시한다.
저장 API:
- Method: `PUT`
- URL: `/api/v2/admin/gift-mailbox`
- Request:
```ts
type AdminGiftMailboxRequest = {
name: string;
phoneNumber: string;
zipCode: string;
address: string;
addressDetail: string | null;
};
```
- Response `data`:
```ts
type AdminGiftMailboxResponse = {
name: string;
address: string;
phoneNumber: string;
};
```
Validation:
- `name`, `phoneNumber`, `zipCode`, `address`는 필수다.
- 공백만 입력할 수 없다.
- 저장 실패 시 기존 관리자 페이지의 공통 에러 표시 방식을 따른다.
저장 성공 UX:
- 성공 토스트를 표시한다.
- 저장 API response 기준으로 화면 값을 갱신한다.
- `address`는 서버가 조립한 `(우편번호) 주소, 상세주소` 형식으로 표시해도 되고, 입력 필드는 사용자가 입력한 값을 유지해도 된다.
테스트/검증:
- 초기 조회 시 null이면 빈 폼을 표시하는지 확인한다.
- 저장 시 PUT body가 정확히 전달되는지 확인한다.
- 필수값 공백 validation을 확인한다.
```
---
## 3. 선물 카테고리 CRUD 페이지 프롬프트
```text
관리자 선물 카테고리 CRUD 페이지를 구현해줘.
목표:
- 관리자 메뉴 `선물함 관리 > 선물 카테고리`에서 선물 카테고리를 조회, 등록, 수정, 비활성화한다.
- 기존 관리자 페이지의 CRUD 테이블, 등록/수정 모달, 삭제 확인창, 토스트 패턴을 그대로 따른다.
라우트:
- `/gift/category`
필수 화면 구성:
- 상단 제목: `선물 카테고리`
- 상단 우측 `카테고리 등록` 버튼
- 목록 테이블 컬럼:
- 카테고리 ID `categoryId`
- 분류번호 `classificationNumber`
- 카테고리 코드 `categoryCode`
- 카테고리명 `name`
- 접수 코드 `receiptCode`
- 대표 품목 `representativeItem`
- 파손면책 동의 필요 여부 `requiresDamageWaiver`
- 활성 여부 `isActive`
- 관리 버튼: 수정, 비활성화
- 등록/수정 폼 필드:
- `classificationNumber`
- `categoryCode`
- `name`
- `receiptCode`
- `representativeItem`
- `requiresDamageWaiver`
- `isActive`
목록 조회 API:
- Method: `GET`
- URL: `/api/v2/admin/gift-categories`
- Request: 없음
- Response `data`:
```ts
type AdminGiftCategoryResponse = {
categoryId: number;
classificationNumber: string;
categoryCode: string;
name: string;
receiptCode: string;
representativeItem: string;
requiresDamageWaiver: boolean;
isActive: boolean;
};
```
등록 API:
- Method: `POST`
- URL: `/api/v2/admin/gift-categories`
- Body:
```ts
type AdminGiftCategoryRequest = {
classificationNumber: string;
categoryCode: string;
name: string;
receiptCode: string;
representativeItem: string;
requiresDamageWaiver: boolean;
isActive: boolean;
};
```
- Response `data`: `AdminGiftCategoryResponse`
수정 API:
- Method: `PUT`
- URL: `/api/v2/admin/gift-categories/{categoryId}`
- Body: `AdminGiftCategoryRequest`
- Response `data`: `AdminGiftCategoryResponse`
비활성화 API:
- Method: `DELETE`
- URL: `/api/v2/admin/gift-categories/{categoryId}`
- Body: 없음
- Response `data`: `AdminGiftCategoryResponse`
- 서버는 실제 삭제가 아니라 `isActive=false` 논리 삭제로 처리한다.
폼 validation:
- `classificationNumber`: 필수, 숫자 3자리. 예: `100`
- `categoryCode`: 필수, 50자 이하. 예: `DOLL`
- `name`: 필수, 50자 이하. 예: `인형`
- `receiptCode`: 필수, 영문 대문자 1~9자. 예: `A`
- `representativeItem`: 필수, 100자 이하. 예: `피규어`
- `requiresDamageWaiver`: boolean
- `isActive`: boolean
UX 요구사항:
- 등록 성공 후 목록을 다시 조회하고 모달을 닫는다.
- 수정 성공 후 목록을 다시 조회하고 모달을 닫는다.
- 비활성화 버튼은 확인창을 띄운 뒤 호출한다.
- 이미 비활성화된 row는 비활성화 버튼을 disabled 처리한다.
- boolean 값은 기존 관리자 페이지 표현에 맞춰 `예/아니오`, `활성/비활성` 또는 badge로 표시한다.
- `categoryCode`는 수정 폼에 표시하되 서버 쪽 엔티티는 코드 변경을 실제로 반영하지 않을 수 있으므로, 가능하면 수정 시 읽기 전용으로 두고 나머지 운영 필드만 수정하도록 UX를 구성한다.
테스트/검증:
- 목록 조회가 `GET /api/v2/admin/gift-categories`를 호출하는지 확인한다.
- 등록/수정 body가 `AdminGiftCategoryRequest` 형태와 일치하는지 확인한다.
- validation 실패 시 API를 호출하지 않고 폼 에러를 표시한다.
- 비활성화 성공 후 해당 row의 `isActive=false`가 반영되는지 확인한다.
```
---
## 4. 선물 사이즈 가격 CRUD 페이지 프롬프트
```text
관리자 선물 사이즈 가격 CRUD 페이지를 구현해줘.
목표:
- 관리자 메뉴 `선물함 관리 > 선물 사이즈`에서 선물 사이즈별 기본가/판매가/활성 여부를 조회하고 수정한다.
- 현재 API는 사이즈 가격의 목록 조회와 수정만 제공한다. 신규 생성과 물리 삭제 기능은 만들지 않는다.
- 기존 관리자 페이지의 테이블, 수정 모달, 저장 확인/토스트 패턴을 그대로 따른다.
라우트:
- `/gift/size`
필수 화면 구성:
- 상단 제목: `선물 사이즈`
- 목록 테이블 컬럼:
- 사이즈 코드 `sizeCode`
- 사이즈명 `name`
- 기본가 `basePriceCan`
- 판매가 `salePriceCan`
- 활성 여부 `isActive`
- 관리 버튼: 수정
- 수정 폼 필드:
- `sizeCode`: 읽기 전용
- `name`: 읽기 전용
- `basePriceCan`: number input
- `salePriceCan`: number input
- `isActive`: checkbox/switch
목록 조회 API:
- Method: `GET`
- URL: `/api/v2/admin/gift-size-prices`
- Request: 없음
- Response `data`:
```ts
type AdminGiftSizePriceResponse = {
sizeCode: GiftSize;
name: string;
basePriceCan: number;
salePriceCan: number;
isActive: boolean;
};
```
수정 API:
- Method: `PUT`
- URL: `/api/v2/admin/gift-size-prices/{sizeCode}`
- Body:
```ts
type AdminGiftSizePriceRequest = {
basePriceCan: number;
salePriceCan: number;
isActive: boolean;
};
```
- Response `data`: `AdminGiftSizePriceResponse`
사이즈 enum:
```ts
type GiftSize = "SMALL" | "MEDIUM" | "LARGE";
```
서버 validation:
- `salePriceCan`은 0보다 커야 한다.
- `salePriceCan`은 `basePriceCan`보다 클 수 없다.
프론트 validation:
- `basePriceCan`: 필수, 1 이상 정수
- `salePriceCan`: 필수, 1 이상 정수
- `salePriceCan <= basePriceCan`
- validation 실패 시 API 호출을 막고 필드 에러를 표시한다.
UX 요구사항:
- 가격은 숫자 입력이지만 테이블 표시에서는 기존 관리자 페이지의 숫자 포맷을 따른다.
- 수정 버튼 클릭 시 현재 row 값을 폼 초기값으로 넣는다.
- 저장 전 확인창은 기존 관리자 페이지 패턴이 있으면 따른다.
- 저장 성공 후 목록을 다시 조회하고 모달을 닫는다.
- 신규 생성/삭제 버튼은 만들지 않는다.
테스트/검증:
- 목록 조회가 `GET /api/v2/admin/gift-size-prices`를 호출하는지 확인한다.
- 수정 저장 시 `PUT /api/v2/admin/gift-size-prices/{sizeCode}`와 request body가 정확한지 확인한다.
- `salePriceCan > basePriceCan`일 때 API를 호출하지 않고 validation 메시지를 표시하는지 확인한다.
- 저장 성공 후 목록 refresh가 일어나는지 확인한다.
```
---
## 구현 시 참고할 공통 타입
```ts
type ApiResponse<T> = {
success: boolean;
data: T;
message?: string;
};
type GiftStatus =
| "RECEIVED"
| "TRACKING_REGISTERED"
| "ARRIVED_AT_MAILBOX"
| "INSPECTION_COMPLETED"
| "DELIVERED"
| "UNDELIVERABLE"
| "CANCELED";
type AdminGiftAction =
| "ARRIVE_MAILBOX"
| "COMPLETE_INSPECTION"
| "COMPLETE_DELIVERY"
| "MARK_UNDELIVERABLE";
type GiftSize = "SMALL" | "MEDIUM" | "LARGE";
```
## 구현 순서 추천
1. API client 함수와 TypeScript 타입을 먼저 추가한다.
2. `/gift/list` 선물함 리스트와 상세/상태변경 모달을 구현한다.
3. `/gift/mailbox` 받을 주소 설정 화면을 구현한다.
4. `/gift/category` 카테고리 CRUD를 구현한다.
5. `/gift/size` 사이즈 가격 수정 화면을 구현한다.
6. 기존 관리자 메뉴의 `선물함 관리` 하위 route와 연결되는지 확인한다.
7. 각 페이지별 loading/empty/error/success 상태를 확인한다.
@@ -1,381 +0,0 @@
# 선물하기 클라이언트 API 요약
## 문서 목적
- 이 문서는 클라이언트 구현 프롬프트 작성용 빠른 참조다.
- 상세 request/response 계약은 `prd.md`의 `8. API 계약`을 기준으로 한다.
- 여기서는 사용자 역할별 URI, 역할, 핵심 request/response 필드만 요약한다.
## 문서 분리 결정
PRD에는 상세 API 계약, request/response 예시, 요구사항을 유지한다. 클라이언트 프롬프트용 역할별 인벤토리는 별도 문서로 둔다.
- 이유: PRD에 같은 URI 정보를 역할별로 다시 넣으면 상세 계약과 요약표를 동시에 갱신해야 한다.
- 기준: PRD는 제품 요구사항과 API 계약의 원본, 이 문서는 클라이언트 구현을 위한 탐색용 색인이다.
## 공통/조회 API
| 사용자 | Method | URI | 역할 | Request | Response |
|---|---:|---|---|---|---|
| 비회원/회원 | GET | `/api/v2/gifts/form-options` | 선물 신청 폼에 필요한 활성 카테고리와 사이즈별 가격 옵션을 조회한다. | 없음 | `sizes[]`, `categories[]` |
| 팬/크리에이터 | GET | `/api/v2/gifts?type=ALL&page=0&size=20` | 내 선물함 목록을 조회하고 `type=ALL|SENT|RECEIVED`로 전체/보낸/받은 선물을 필터링한다. | query: `type`, `page`, `size` | `items[]`, `page`, `size`, `hasNext` |
| 팬/크리에이터 | GET | `/api/v2/gifts/{applicationNo}` | 선물 상세를 조회하며 로그인 회원이 팬인지 크리에이터인지에 따라 노출 정보와 CTA flag가 달라진다. | path: `applicationNo` | `applicationNo`, `direction`, `status`, `statusName`, `giftInfo`, `senderInfo`, `recipientAddress`, `mailbox`, `trackingRequired`, `recipientAddressRequired`, `delivery`, `statusTimeline`, `review` |
## 팬 API
| 사용자 | Method | URI | 역할 | Request | Response |
|---|---:|---|---|---|---|
| 팬 | POST | `/api/v2/gifts` | 크리에이터에게 선물을 신청하고 최종 결제 금액만큼 캔을 차감한다. | body: `recipientMemberId`, `senderName`, `senderPhoneNumber`, `senderZipCode`, `senderAddress`, `senderAddressDetail`, `sizeCode`, `categoryId`, `senderTermsAgreed`, `senderPrivacyAgreed`, `damageWaiverAgreed` | `applicationNo`, `status`, `statusName`, `priceCan`, `trackingDeadlineAt` |
| 팬 | POST | `/api/v2/gifts/{applicationNo}/cancel` | 운송장 등록 전 선물 신청을 취소하고 전액 환불한다. | path: `applicationNo` | `applicationNo`, `status`, `statusName`, `priceCan`, `canceledAt` |
| 팬 | POST | `/api/v2/gifts/{applicationNo}/tracking` | 발송 후 택배사와 운송장 번호를 등록한다. | path: `applicationNo`, body: `courierCompanyName`, `trackingNumber` | `applicationNo`, `status`, `statusName`, `courierCompanyName`, `trackingNumber`, `trackingRegisteredAt`, `recipientAddressDeadlineAt` |
| 팬 | POST | `/api/v2/gifts/{applicationNo}/review` | 전달 완료된 선물에 리뷰를 작성한다. | path: `applicationNo`, body: `rating`, `keywords`, `comment` | `reviewId`, `applicationNo`, `rating`, `keywords`, `comment`, `createdAt` |
## 크리에이터 API
| 사용자 | Method | URI | 역할 | Request | Response |
|---|---:|---|---|---|---|
| 크리에이터 | POST | `/api/v2/gifts/{applicationNo}/recipient-address` | 운송장 등록 이후 배송지와 수령 약관 동의를 등록한다. | path: `applicationNo`, body: `recipientName`, `recipientPhoneNumber`, `recipientZipCode`, `recipientAddress`, `recipientAddressDetail`, `recipientTermsAgreed`, `recipientPrivacyAgreed` | `applicationNo`, `status`, `statusName`, `recipientAddressRegisteredAt` |
| 크리에이터 | POST | `/api/v2/gifts/{applicationNo}/delivery-complete` | 검수 완료된 선물을 직접 수령 완료 처리한다. | path: `applicationNo` | `applicationNo`, `status`, `statusName`, `deliveredAt` |
## 관리자 API
| 사용자 | Method | URI | 역할 | Request | Response |
|---|---:|---|---|---|---|
| 관리자 | GET | `/api/v2/admin/gift-categories` | 선물 카테고리 목록을 조회한다. | 없음 | `AdminGiftCategoryResponse[]` |
| 관리자 | GET | `/api/v2/admin/gifts` | 전체 선물함 목록을 조회하고 상태/신청번호/닉네임으로 검색한다. | query: `status`, `applicationNo`, `nickname`, `page`, `size` | `totalCount`, `items[]`, `page`, `size`, `hasNext` |
| 관리자 | GET | `/api/v2/admin/gifts/{applicationNo}` | 선물 상세와 발송인/수취인 개인정보, 상품/배송/상태 정보를 조회한다. | path: `applicationNo` | `applicationNo`, `senderInfo`, `recipientInfo`, `productInfo`, `inboundDeliveryInfo`, `status`, `statusName`, `availableActions` |
| 관리자 | POST | `/api/v2/admin/gifts/{applicationNo}/cancel` | 운송장 등록 전 `RECEIVED` 선물을 취소하고 발신자에게 전액 리워드캔을 환불한다. | path: `applicationNo`, body 없음 | `AdminGiftOperationStatusResponse`: `applicationNo`, `status`, `statusName`, `occurredAt` (`canceledAt` UTC ISO `Z`) |
| 관리자 | POST | `/api/v2/admin/gift-categories` | 선물 카테고리를 등록한다. | body: `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive` | `categoryId`, `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive` |
| 관리자 | PUT | `/api/v2/admin/gift-categories/{categoryId}` | 선물 카테고리를 수정한다. | path: `categoryId`, body: `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive` | `categoryId`, `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive` |
| 관리자 | DELETE | `/api/v2/admin/gift-categories/{categoryId}` | 선물 카테고리를 비활성화한다. | path: `categoryId` | `categoryId`, `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive=false` |
| 관리자 | GET | `/api/v2/admin/gift-size-prices` | 사이즈별 기본가와 판매가를 조회한다. | 없음 | `AdminGiftSizePriceResponse[]` |
| 관리자 | PUT | `/api/v2/admin/gift-size-prices/{sizeCode}` | 사이즈별 기본가와 판매가를 수정한다. | path: `sizeCode`, body: `basePriceCan`, `salePriceCan`, `isActive` | `sizeCode`, `name`, `basePriceCan`, `salePriceCan`, `isActive` |
| 관리자 | POST | `/api/v2/admin/gifts/{applicationNo}/arrive-mailbox` | 발송 확인 선물을 사서함 도착 처리한다. | path: `applicationNo` | `applicationNo`, `status`, `statusName`, `occurredAt` |
| 관리자 | POST | `/api/v2/admin/gifts/{applicationNo}/complete-inspection` | 사서함 도착 선물을 검수 완료 처리한다. | path: `applicationNo` | `applicationNo`, `status`, `statusName`, `occurredAt` |
| 관리자 | POST | `/api/v2/admin/gifts/{applicationNo}/mark-undeliverable` | 진행 중 선물을 전달 불가 처리하고 사유를 저장한다. | path: `applicationNo`, body: `reason` | `applicationNo`, `status`, `statusName`, `occurredAt` |
| 관리자 | POST | `/api/v2/admin/gifts/{applicationNo}/complete-delivery` | 검수 완료 선물을 운영자가 전달 완료 처리한다. | path: `applicationNo` | `applicationNo`, `status`, `statusName`, `occurredAt` |
관리자 응답 DTO 요약:
- `AdminGiftCategoryResponse`: `categoryId`, `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive`
- `AdminGiftListResponse`: `totalCount`, `items`, `page`, `size`, `hasNext`
- `AdminGiftListItemResponse`: `applicationNo`, `senderNickname`, `recipientNickname`, `sizeCode`, `sizeName`, `categoryName`, `classificationNumber`, `courierCompanyName`, `trackingNumber`, `status`, `statusName`, `availableActions`
- `AdminGiftDetailResponse`: `applicationNo`, `senderInfo`, `recipientInfo`, `productInfo`, `inboundDeliveryInfo`, `status`, `statusName`, `availableActions`
- `AdminGiftSizePriceResponse`: `sizeCode`, `name`, `basePriceCan`, `salePriceCan`, `isActive`
- `AdminGiftOperationStatusResponse`: `applicationNo`, `status`, `statusName`, `occurredAt`
관리자 취소는 기존 `hasRole('ADMIN')` 권한을 따르며 관리자가 발신자가 아니어도 `RECEIVED`에서 취소할 수 있다. 같은 트랜잭션에서 `GiftDelivery.canceledAt`을 기록하고 기존 `refundGiftCan`으로 발신자에게 원 결제액 전액을 리워드캔으로 환불한다. 존재하지 않는 신청번호나 다른 상태는 기존 공통 invalid request이며 기존 `ApiResponse` envelope를 사용한다. 기존 사용자 취소 응답은 별도 계약이며 바뀌지 않는다. HTTP 성공 코드만으로 업무 성공을 판단하지 않고 envelope의 `success`를 확인한다.
관리자 선물함의 action: `RECEIVED`는 목록과 상세 모두 `availableActions=["CANCEL"]`; 그 외 상태는 기존 매핑을 유지한다. 특히 `INSPECTION_COMPLETED`의 `COMPLETE_DELIVERY`는 수취인 정보 완비 조건부 노출이다.
기존 관리자 화면에 취소 기능만 추가하는 작업은 [관리자 취소 기능 추가 프롬프트](admin-gift-cancel-addition-prompt.md)를 사용한다. 전체 화면 구현용 `admin-page-prompts.md`는 변경하지 않는다.
## Kotlin DTO 형태
아래는 JSON으로 변환되기 직전의 API request/response `data class` 형태다. `companion object` 변환 함수는 클라이언트 입력/출력 형태와 직접 관련이 없어 생략했다. 응답 시각 필드는 UTC ISO 문자열이다. 예: `2026-09-30T12:00:00Z`.
### 사용자 Request DTO
```kotlin
data class GiftApplicationRequest(
val recipientMemberId: Long,
val senderName: String,
val senderPhoneNumber: String,
val senderZipCode: String,
val senderAddress: String,
val senderAddressDetail: String?,
val sizeCode: GiftSize,
val categoryId: Long,
val senderTermsAgreed: Boolean,
val senderPrivacyAgreed: Boolean,
val damageWaiverAgreed: Boolean
)
data class GiftTrackingRegistrationRequest(
val courierCompanyName: String,
val trackingNumber: String
)
data class GiftRecipientAddressRegistrationRequest(
val recipientName: String,
val recipientPhoneNumber: String,
val recipientZipCode: String,
val recipientAddress: String,
val recipientAddressDetail: String?,
val recipientTermsAgreed: Boolean,
val recipientPrivacyAgreed: Boolean
)
data class GiftReviewRequest(
val rating: Int,
val keywords: List<String>,
val comment: String?
)
```
### 사용자 Response DTO
```kotlin
data class GiftFormOptionsResponse(
val sizes: List<GiftSizeOptionResponse>,
val categories: List<GiftCategoryOptionResponse>
)
data class GiftSizeOptionResponse(
val sizeCode: String,
val name: String,
val basePriceCan: Int,
val salePriceCan: Int
)
data class GiftCategoryOptionResponse(
val categoryId: Long,
val name: String,
val requiresDamageWaiver: Boolean
)
// name은 사용자 폼 옵션에서만 "분류명/대표품목" 형태로 조합된다.
data class GiftListResponse(
val totalCount: Long,
val items: List<GiftListItemResponse>,
val page: Int,
val size: Int,
val hasNext: Boolean
)
data class GiftListItemResponse(
val applicationNo: String,
val direction: String,
val status: String,
val statusName: String,
val priceCan: Int,
val categoryName: String,
val sizeName: String,
val counterpartMemberId: Long,
val counterpartNickname: String,
val counterpartProfileImageUrl: String,
val recipientAddressRegistered: Boolean,
val recipientAddressDeadlineAt: String?,
val canceledAt: String?,
val createdAt: String?
)
data class GiftDetailResponse(
val applicationNo: String,
val direction: String,
val status: String,
val statusName: String,
val giftInfo: GiftDetailInfoResponse,
val senderInfo: GiftAddressResponse?,
val recipientAddress: GiftAddressResponse?,
val mailbox: GiftMailboxResponse?,
val trackingRequired: Boolean,
val recipientAddressRequired: Boolean,
val recipientAddressDeadlineAt: String?,
val delivery: GiftDeliveryInfoResponse,
val statusTimeline: List<GiftStatusTimelineResponse>
)
data class GiftDetailInfoResponse(
val recipientCreatorNickname: String?,
val senderNickname: String?,
val sizeName: String,
val categoryName: String,
val applicationNo: String?,
val paidCan: Int?,
val tracking: String?,
val shippingRequestedAt: String?
)
data class GiftAddressResponse(
val name: String,
val phoneNumber: String,
val address: String
)
data class GiftMailboxResponse(
val name: String,
val address: String,
val phoneNumber: String
)
// mailbox는 direction=SENT이고 status가 RECEIVED, TRACKING_REGISTERED,
// ARRIVED_AT_MAILBOX, INSPECTION_COMPLETED일 때만 값이 있다.
// DELIVERED, UNDELIVERABLE, CANCELED 또는 direction=RECEIVED이면 null이다.
data class GiftDeliveryInfoResponse(
val canceledAt: String?,
val undeliverableAt: String?,
val undeliverableReason: String?
)
data class GiftStatusTimelineResponse(
val status: String,
val statusName: String,
val occurredAt: String?
)
data class GiftApplicationResponse(
val applicationNo: String,
val status: String,
val statusName: String,
val priceCan: Int,
val trackingDeadlineAt: String
)
data class GiftCancellationResponse(
val applicationNo: String,
val status: String,
val statusName: String,
val priceCan: Int,
val canceledAt: String
)
data class GiftTrackingRegistrationResponse(
val applicationNo: String,
val status: String,
val statusName: String,
val courierCompanyName: String,
val trackingNumber: String,
val trackingRegisteredAt: String,
val recipientAddressDeadlineAt: String
)
data class GiftRecipientAddressRegistrationResponse(
val applicationNo: String,
val status: String,
val statusName: String,
val recipientAddressRegisteredAt: String
)
data class GiftDeliveryConfirmationResponse(
val applicationNo: String,
val status: String,
val statusName: String,
val deliveredAt: String
)
data class GiftReviewResponse(
val reviewId: Long,
val applicationNo: String,
val rating: Int,
val keywords: List<String>,
val comment: String?,
val createdAt: String?
)
```
### 관리자 Request DTO
```kotlin
data class AdminGiftCategoryRequest(
val classificationNumber: String,
val categoryCode: String,
val name: String,
val receiptCode: String,
val representativeItem: String,
val requiresDamageWaiver: Boolean,
val isActive: Boolean
)
data class AdminGiftSizePriceRequest(
val basePriceCan: Int,
val salePriceCan: Int,
val isActive: Boolean
)
data class AdminGiftMarkUndeliverableRequest(
val reason: String
)
```
### 관리자 Response DTO
```kotlin
data class AdminGiftCategoryResponse(
val categoryId: Long,
val classificationNumber: String,
val categoryCode: String,
val name: String,
val receiptCode: String,
val representativeItem: String,
val requiresDamageWaiver: Boolean,
val isActive: Boolean
)
data class AdminGiftListResponse(
val totalCount: Long,
val items: List<AdminGiftListItemResponse>,
val page: Int,
val size: Int,
val hasNext: Boolean
)
data class AdminGiftListItemResponse(
val applicationNo: String,
val senderNickname: String,
val recipientNickname: String,
val sizeCode: String,
val sizeName: String,
val categoryName: String,
val classificationNumber: String,
val courierCompanyName: String?,
val trackingNumber: String?,
val status: String,
val statusName: String,
val availableActions: List<String>
)
data class AdminGiftDetailResponse(
val applicationNo: String,
val senderInfo: AdminGiftMemberInfoResponse,
val recipientInfo: AdminGiftMemberInfoResponse,
val productInfo: AdminGiftProductInfoResponse,
val inboundDeliveryInfo: AdminGiftInboundDeliveryInfoResponse,
val status: String,
val statusName: String,
val availableActions: List<String>
)
data class AdminGiftMemberInfoResponse(
val nickname: String,
val name: String,
val phoneNumber: String,
val address: String
)
data class AdminGiftProductInfoResponse(
val sizeCode: String,
val sizeName: String,
val categoryName: String,
val classificationNumber: String
)
data class AdminGiftInboundDeliveryInfoResponse(
val courierCompanyName: String?,
val trackingNumber: String?
)
data class AdminGiftSizePriceResponse(
val sizeCode: String,
val name: String,
val basePriceCan: Int,
val salePriceCan: Int,
val isActive: Boolean
)
data class AdminGiftOperationStatusResponse(
val applicationNo: String,
val status: GiftStatus,
val statusName: String,
val occurredAt: String
)
```
## 클라이언트 구현 참고
- 선물 푸시 딥링크는 `deepLinkValue=GIFT_DETAIL`, `deepLinkId=applicationNo`를 사용한다.
- 딥링크 진입 후에는 `GET /api/v2/gifts/{applicationNo}`로 상세를 조회해 `direction`, `trackingRequired`, `recipientAddressRequired`를 기준으로 화면과 CTA를 결정한다.
- 운송장 미등록 자동취소는 서버 스케줄러가 처리하며, 팬 클라이언트는 상세 조회의 `status=CANCELED`와 푸시를 기준으로 표시한다.
- 모든 응답은 기존 `ApiResponse.ok(...)` envelope 안의 `data`로 내려간다.
@@ -1,433 +0,0 @@
# 보낸 선물 상세 및 운송장 등록 페이지 생성 프롬프트
이 문서는 Android/iOS 앱의 `선물함` 리스트에서 보낸 선물 상세 페이지와 운송장 등록 페이지를 생성할 때 사용하는 프롬프트다.
참고 Figma:
- 선물 보내기 신청 상세 운송장 등록 전 UI: `2481:19011`
- 선물 보내기 신청 상세 운송장 등록 후 UI: `2481:19152`
- 선물 보내기 신청 상세 전달 완료 UI: `2481:19320`
- 전달 불가 UI: `2481:19456`
- 취소 버튼 다이얼로그 UI: `2481:19500`
- 취소 완료 페이지 UI: `2481:19521`
- 운송장 등록 UI: `2481:19066`
- 운송장 정보를 채우고 난 후 UI: `2481:19109`
전제:
- 선물함 리스트 item 탭 시 `applicationNo`를 전달받아 상세 페이지로 이동한다.
- 새 디자인 시스템을 만들지 말고 Android/iOS 각각의 기존 디자인 시스템, 컴포넌트, API client, 상태 관리, toast/dialog, navigation 패턴을 재사용한다.
- 모든 API 응답은 공통 envelope를 사용하며 실제 payload는 `response.data`다.
- Figma의 진행 상태는 4단계처럼 보이지만 실제 구현은 서버의 `statusTimeline` 5개 상태를 모두 사용한다.
- 운송장 등록의 택배사 선택지는 서버 API가 없으므로 앱 로컬 상수로 관리한다.
- 취소 확인 팝업은 앱의 `v2 dialog` 컴포넌트를 기본으로 사용한다.
---
## 모바일 앱 구현 프롬프트
```text
Android/iOS 앱의 선물 상세 페이지와 운송장 등록 페이지를 Figma 기준으로 생성하고 API 연동을 구현해줘.
범위:
- 선물함 리스트에서 `applicationNo`를 받아 선물 상세 페이지로 이동한다.
- 상세 페이지는 `GET /api/v2/gifts/{applicationNo}` 응답으로 렌더링한다.
- `trackingRequired=true`인 보낸 선물 상세에서는 운송장 등록 CTA를 표시하고 운송장 등록 페이지로 이동한다.
- 운송장 등록 페이지는 같은 상세 API를 조회해 신청 요약과 보낼 주소를 표시한 뒤 `POST /api/v2/gifts/{applicationNo}/tracking`으로 운송장 정보를 등록한다.
중요 전제:
- Figma의 visual structure와 문구를 우선 따르되, 상태 개수와 데이터 노출은 API 계약을 우선한다.
- 상세 진행 단계는 Figma처럼 4단계로 고정하지 말고 API `statusTimeline`의 5개 정상 진행 상태를 모두 렌더링한다.
- 택배사 목록은 API로 조회하지 않는다. 앱 로컬 상수로 관리하고 선택한 한글 표시명을 `courierCompanyName`으로 전송한다.
- 운송장 등록 완료 후 수정 기능은 만들지 않는다.
상세 페이지 진입:
- 선물함 리스트 item에서 받은 `applicationNo`로 진입한다.
- 화면 진입 시 `GET /api/v2/gifts/{applicationNo}`를 호출한다.
- 조회 결과 `status=CANCELED`이면 일반 신청 상세 화면을 렌더링하지 말고 취소 완료 페이지 UI를 보여준다.
- 로딩 중에는 기존 앱 상세 화면 로딩/스켈레톤 패턴을 사용한다.
- 실패 시 기존 앱 toast/dialog와 재시도 패턴을 사용한다.
상세 페이지 공통 레이아웃:
1. 상단 고정 내비게이션
- 타이틀: `신청 상세`
- 뒤로가기 버튼은 기존 앱 패턴을 사용한다.
2. 스크롤 콘텐츠
- 배송 상태 hero
- 진행 상태 progress
- 상태별 action button 영역
- 선물 정보
- 필요한 경우 보내는 사람, 받는 사서함, 사유 섹션
3. 하단 safe area
- 기존 앱 패턴을 따른다.
상태별 hero 문구:
| status | chip | title | body |
|---|---|---|---|
| `RECEIVED` | 없음 또는 `접수 완료` | `선물 신청 완료!` | `선물이 정상적으로 접수되었어요!` |
| `TRACKING_REGISTERED` | `발송 확인` | `사서함으로 이동 중이에요` | 없음 |
| `ARRIVED_AT_MAILBOX` | `사서함 도착` | `선물이 사서함에 도착했어요` | 없음 |
| `INSPECTION_COMPLETED` | `검수 완료` | `선물 검수를 완료했어요` | 없음 |
| `DELIVERED` | `전달 완료` | `크리에이터에게 선물을 전달했어요` | 없음 |
| `UNDELIVERABLE` | `전달 불가` | `전달할 수 없는 품목입니다` | `보내주신 선물은 SODALIVE 선물 정책에 따라 크리에이터에게 전달할 수 없는 품목으로 확인되었습니다.` |
| `CANCELED` | `신청 취소` | `선물 신청이 취소되었어요` | `사용한 캔은 환불 처리됩니다.` |
진행 상태 progress:
- `statusTimeline` 배열을 그대로 사용한다.
- 항상 아래 5개 단계를 이 순서로 표시한다.
1. `RECEIVED`: `신청 접수`
2. `TRACKING_REGISTERED`: `발송 확인`
3. `ARRIVED_AT_MAILBOX`: `사서함 도착`
4. `INSPECTION_COMPLETED`: `검수 완료`
5. `DELIVERED`: `전달 완료`
- `occurredAt`이 있으면 해당 단계는 완료 색상으로 표시하고 `MM.DD`를 표시한다.
- `occurredAt`이 null이면 비활성 색상으로 표시하고 날짜는 표시하지 않는다.
- `UNDELIVERABLE`, `CANCELED`는 정상 진행 단계가 아니므로 progress step으로 추가하지 않는다.
- 종료 상태에서도 `statusTimeline`에 있는 정상 진행 이력은 그대로 표시한다.
상세 페이지 섹션 표시 규칙:
- `선물 정보`는 항상 표시한다.
- `direction=SENT`이면 크리에이터명은 `giftInfo.recipientCreatorNickname`을 사용한다.
- `direction=RECEIVED`이면 보낸 팬명은 `giftInfo.senderNickname`을 사용한다.
- `senderInfo`가 있으면 `보내는 사람` 섹션을 표시한다.
- `mailbox`가 있으면 `받는 사서함` 또는 `보내실 주소` 섹션을 표시한다.
- `recipientAddress`가 있으면 `받는 사람` 또는 `배송지` 섹션을 표시한다.
- `delivery.undeliverableReason`이 있으면 `사유` 섹션을 표시한다.
선물 정보 표시 필드:
- 크리에이터 또는 보낸 팬 닉네임
- 선물 사이즈: `giftInfo.sizeName`
- 카테고리: `giftInfo.categoryName`
- 신청번호: `applicationNo` 또는 `giftInfo.applicationNo`
- 캔: `giftInfo.paidCan`이 null이 아닐 때만 표시
- 운송장 번호: `giftInfo.tracking`이 null이 아닐 때 표시
- 검수일: `statusTimeline`에서 `INSPECTION_COMPLETED.occurredAt`이 있으면 표시
- 전달 완료일: `statusTimeline`에서 `DELIVERED.occurredAt`이 있으면 표시
- 취소일: `delivery.canceledAt`이 있으면 표시
받는 사서함/보내실 주소 표시:
- `mailbox.name`을 사서함/받는 분으로 표시한다.
- `mailbox.address`를 주소로 표시한다.
- `mailbox.phoneNumber`를 연락처로 표시한다.
- `mailbox`는 관리자가 등록한 전역 단일 주소다. 상대방 주소가 아니다.
- `mailbox`는 `direction=SENT`이고 `status`가 `RECEIVED`, `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`일 때 내려온다.
- `DELIVERED`, `UNDELIVERABLE`, `CANCELED` 또는 `direction=RECEIVED`에서는 `mailbox=null`이다.
- `mailbox=null`이면 해당 섹션을 표시하지 않는다.
보내는 사람 표시:
- `senderInfo.name`
- `senderInfo.phoneNumber`
- `senderInfo.address`
- 이 정보는 보낸 팬 본인이 신청 시 입력한 정보다.
전달 불가 표시:
- `status=UNDELIVERABLE`이면 Figma `2481:19456` 패턴을 따른다.
- 사유 섹션의 제목은 `delivery.undeliverableReason`을 사용한다.
- `delivery.undeliverableReason`이 null이면 사유 섹션 제목은 `전달 불가`로 표시한다.
- 안내 문구는 `해당 선물은 정책에 따라 폐기되며 반송되지 않습니다.`를 사용한다.
상세 페이지 action:
- `trackingRequired=true`이면 하단 주요 CTA `운송장 작성하기`를 표시하고 운송장 등록 페이지로 이동한다.
- `direction=SENT && status=RECEIVED`이면 보조 action `신청 취소`를 표시할 수 있다.
- 신청 취소 버튼을 누르면 즉시 API를 호출하지 말고 `v2 dialog` 확인 팝업을 먼저 표시한다.
- `status=DELIVERED && direction=SENT`이면 `리뷰 남기기` 버튼을 표시하고 기존 리뷰 작성 화면/플로우로 이동한다.
- `문의하기`, `선물 정책 확인` 버튼은 기존 앱에 해당 이동 경로가 있으면 연결하고, 없으면 기존 정책에 맞춰 숨기거나 비활성 처리한다.
신청 취소 확인 다이얼로그:
- Figma `2481:19500`을 참고한다.
- 앱의 기본 `v2 dialog` 컴포넌트를 사용한다. 새 dialog 컴포넌트를 만들지 않는다.
- 제목: `신청 취소`
- 본문:
- `{크리에이터}에게 보내는 선물을 취소할까요?`
- `선물 보내기 규정에 따라 선물 취소 및 사용한 캔이 모두 환불됩니다.`
- 왼쪽 action: `나가기`
- dialog만 닫고 상세/운송장 등록 화면 상태를 유지한다.
- 오른쪽 destructive action: `취소하기`
- `POST /api/v2/gifts/{applicationNo}/cancel`을 호출한다.
- 호출 중에는 중복 탭을 막고 loading 상태를 표시한다.
- 실패 시 dialog를 닫지 말고 기존 앱 에러 toast/dialog 패턴으로 안내한다.
- 성공 시 취소 완료 페이지로 replace navigation 한다.
취소 완료 페이지:
- Figma `2481:19521`을 참고한다.
- 취소 API 성공 직후뿐 아니라 상세 페이지 접근 시 `GET /api/v2/gifts/{applicationNo}` 응답이 `status=CANCELED`인 경우에도 이 화면을 보여준다.
- 상단 타이틀: `취소 완료`
- hero chip: `취소 완료`
- hero title: `선물 신청이 취소되었어요`
- hero body: `{크리에이터}에게 보내는 선물 신청({applicationNo})이 취소되었습니다. 취소한 신청은 되돌릴 수 없으며, 다시 보내려면 새로 신청해 주세요.`
- 섹션 제목: `취소 상세`
- 취소 상세 카드 표시 필드:
- 크리에이터: `giftInfo.recipientCreatorNickname`
- 선물 사이즈: `giftInfo.sizeName`
- 카테고리: `giftInfo.categoryName`
- 신청번호: `applicationNo`
- 신청일: `statusTimeline`의 `RECEIVED.occurredAt`
- 취소일: 취소 API response의 `canceledAt` 또는 상세 API 조회 시 `delivery.canceledAt`
- 환불 캔: 취소 API response의 `priceCan` 또는 상세 API의 `giftInfo.paidCan`
- 하단 또는 카드 아래에 `문의하기` 버튼을 표시한다.
- 뒤로가기 동작은 취소 전 상세/운송장 등록 화면으로 돌아가지 않게 한다. 기존 앱 navigation 정책에 맞춰 선물함 리스트 또는 이전 안전 화면으로 이동한다.
운송장 등록 페이지 진입:
- 상세 페이지에서 `trackingRequired=true`일 때만 진입시킨다.
- 진입 시 `GET /api/v2/gifts/{applicationNo}`를 다시 조회한다.
- 조회 결과에서 `trackingRequired=false`이면 이미 등록 불가 상태이므로 기존 오류 처리 후 상세 페이지로 돌아간다.
운송장 등록 페이지 레이아웃:
1. 상단 고정 내비게이션
- 타이틀: `운송장 등록`
2. 신청 건 요약 카드
- `applicationNo`
- 크리에이터 닉네임: `giftInfo.recipientCreatorNickname`
- `giftInfo.sizeName · giftInfo.categoryName · 신청일`
- 신청일은 `statusTimeline`의 `RECEIVED.occurredAt`을 `YYYY.MM.DD`로 표시한다.
3. 보내실 주소
- `mailbox`를 사용한다.
- `mailbox=null`이면 운송장 등록을 막고 `받을 주소가 등록되어 있지 않습니다.` 오류를 표시한다.
4. 운송장 정보
- 택배사 select
- 운송장 번호 input
5. 등록 안내
- Figma의 안내 문구를 유지한다.
6. 하단 action bar
- 왼쪽: `신청 취소`
- 오른쪽: `등록 완료`
택배사 로컬 상수:
- 서버에서 택배사 옵션을 조회하지 않는다.
- 앱에 아래 로컬 옵션을 둔다. 이미 앱 공통 택배사 상수가 있으면 그것을 우선 사용한다.
```ts
const giftCourierCompanyNames = [
"CJ대한통운",
"우체국택배",
"GS25 편의점택배",
"CU 편의점택배",
"한진택배",
"롯데택배",
"로젠택배",
"경동택배",
"대신택배",
"일양로지스",
"천일택배",
"합동택배",
"건영택배",
"농협택배"
];
```
- 선택 UI는 기존 앱의 bottom sheet, picker, dialog 중 이미 쓰는 방식을 사용한다.
- API에는 선택된 한글 표시명을 그대로 `courierCompanyName`으로 보낸다.
운송장 등록 CTA 활성 조건:
- 택배사를 선택했다.
- 운송장 번호를 입력했다.
- 운송장 번호는 공백만 입력할 수 없다.
- submit 중에는 중복 탭을 막고 loading 상태를 표시한다.
- 비활성 상태는 Figma `2481:19066`, 활성 상태는 Figma `2481:19109`를 따른다.
운송장 등록 성공 처리:
- `POST /api/v2/gifts/{applicationNo}/tracking` 성공 후 성공 toast를 표시한다.
- 상세 페이지로 돌아가거나 replace navigation으로 상세 페이지를 다시 연다.
- 상세 페이지는 `GET /api/v2/gifts/{applicationNo}`를 다시 호출해 `TRACKING_REGISTERED` 상태를 표시한다.
API 명세:
선물 상세 조회:
- Method: `GET`
- URL: `/api/v2/gifts/{applicationNo}`
- 인증: 로그인 필요
- Response envelope 예시:
```json
{
"success": true,
"data": {
"applicationNo": "A-1002609300001",
"direction": "SENT",
"status": "RECEIVED",
"statusName": "접수 완료",
"giftInfo": {
"recipientCreatorNickname": "달빛수집가",
"senderNickname": null,
"sizeName": "소형",
"categoryName": "잡화",
"applicationNo": "A-1002609300001",
"paidCan": 100,
"tracking": null,
"shippingRequestedAt": null
},
"senderInfo": {
"name": "김소다",
"phoneNumber": "01012345678",
"address": "(04030) 서울특별시 마포구 양화로 000, 3층"
},
"recipientAddress": null,
"mailbox": {
"name": "소다라이브 사서함",
"address": "(06174) 서울특별시 강남구 테헤란로108길 8, 유민빌딩 4층",
"phoneNumber": "02-2055-1477"
},
"trackingRequired": true,
"recipientAddressRequired": false,
"recipientAddressDeadlineAt": null,
"delivery": {
"canceledAt": null,
"undeliverableAt": null,
"undeliverableReason": null
},
"statusTimeline": [
{
"status": "RECEIVED",
"statusName": "접수 완료",
"occurredAt": "2026-09-18T03:00:00Z"
},
{
"status": "TRACKING_REGISTERED",
"statusName": "발송 확인",
"occurredAt": null
},
{
"status": "ARRIVED_AT_MAILBOX",
"statusName": "사서함 도착",
"occurredAt": null
},
{
"status": "INSPECTION_COMPLETED",
"statusName": "검수완료",
"occurredAt": null
},
{
"status": "DELIVERED",
"statusName": "전달완료",
"occurredAt": null
}
]
},
"message": ""
}
```
Response `data` 필드:
| 필드 | 타입 | 설명 |
|---|---|---|
| `applicationNo` | string | 선물 신청번호 |
| `direction` | string | `SENT` 또는 `RECEIVED` |
| `status` | string | 선물 상태 코드 |
| `statusName` | string | 서버 상태 표시명 |
| `giftInfo` | object | 선물 기본 정보 |
| `giftInfo.recipientCreatorNickname` | string 또는 null | 보낸 선물 관점에서 받는 크리에이터 닉네임 |
| `giftInfo.senderNickname` | string 또는 null | 받은 선물 관점에서 보낸 팬 닉네임 |
| `giftInfo.sizeName` | string | 선물 사이즈명 |
| `giftInfo.categoryName` | string | 카테고리명 |
| `giftInfo.applicationNo` | string 또는 null | 보낸 선물 관점 신청번호 |
| `giftInfo.paidCan` | number 또는 null | 보낸 선물 관점 사용 캔 |
| `giftInfo.tracking` | string 또는 null | 운송장 표시 문자열. 예: `한진택배_123456789012` |
| `giftInfo.shippingRequestedAt` | string 또는 null | 받은 선물 관점 배송신청일. UTC ISO 문자열 |
| `senderInfo` | object 또는 null | 보낸 팬 본인이 신청 시 입력한 보내는 사람 정보 |
| `senderInfo.name` | string | 이름 |
| `senderInfo.phoneNumber` | string | 휴대폰 번호 |
| `senderInfo.address` | string | `(우편번호) 주소, 상세주소` 형식 주소 |
| `recipientAddress` | object 또는 null | 받는 크리에이터 본인이 입력한 배송지 |
| `mailbox` | object 또는 null | 관리자가 등록한 전역 선물 받을 주소. 보낸 선물의 `DELIVERED` 전 정상 진행 상태에서만 값이 있다 |
| `mailbox.name` | string | 사서함/받는 분 이름 |
| `mailbox.address` | string | `(우편번호) 주소, 상세주소` 형식 주소 |
| `mailbox.phoneNumber` | string | 연락처 |
| `trackingRequired` | boolean | 보낸 팬이 운송장 등록을 해야 하는 상태인지 여부 |
| `recipientAddressRequired` | boolean | 받는 크리에이터가 배송지를 입력해야 하는 상태인지 여부 |
| `recipientAddressDeadlineAt` | string 또는 null | 배송지 입력 마감일. UTC ISO 문자열 |
| `delivery.canceledAt` | string 또는 null | 취소일. UTC ISO 문자열 |
| `delivery.undeliverableAt` | string 또는 null | 전달 불가 처리일. UTC ISO 문자열 |
| `delivery.undeliverableReason` | string 또는 null | 전달 불가 사유 |
| `statusTimeline` | array | 정상 진행 5단계 타임라인 |
| `statusTimeline[].status` | string | 단계 상태 코드 |
| `statusTimeline[].statusName` | string | 단계 표시명 |
| `statusTimeline[].occurredAt` | string 또는 null | 해당 단계 도달 시각. UTC ISO 문자열 |
운송장 등록:
- Method: `POST`
- URL: `/api/v2/gifts/{applicationNo}/tracking`
- 인증: 로그인 필요
- Request:
```json
{
"courierCompanyName": "한진택배",
"trackingNumber": "123456789012"
}
```
- Response envelope 예시:
```json
{
"success": true,
"data": {
"applicationNo": "A-1002609300001",
"status": "TRACKING_REGISTERED",
"statusName": "발송 확인",
"courierCompanyName": "한진택배",
"trackingNumber": "123456789012",
"trackingRegisteredAt": "2026-09-19T03:00:00Z",
"recipientAddressDeadlineAt": "2026-09-26T03:00:00Z"
},
"message": ""
}
```
운송장 등록 response `data` 필드:
| 필드 | 타입 | 설명 |
|---|---|---|
| `applicationNo` | string | 선물 신청번호 |
| `status` | string | 등록 후 상태. `TRACKING_REGISTERED` |
| `statusName` | string | 서버 상태 표시명 |
| `courierCompanyName` | string | 선택한 택배사 한글명 |
| `trackingNumber` | string | 운송장 번호 |
| `trackingRegisteredAt` | string | 운송장 등록일. UTC ISO 문자열 |
| `recipientAddressDeadlineAt` | string | 크리에이터 배송지 입력 마감일. UTC ISO 문자열 |
선물 보내기 취소:
- Method: `POST`
- URL: `/api/v2/gifts/{applicationNo}/cancel`
- Request: 없음
- 용도: `direction=SENT && status=RECEIVED`에서만 `신청 취소` action에 사용한다.
- Response envelope 예시:
```json
{
"success": true,
"data": {
"applicationNo": "A-1002609300001",
"status": "CANCELED",
"statusName": "신청 취소",
"priceCan": 100,
"canceledAt": "2026-09-18T04:00:00Z"
},
"message": ""
}
```
선물 보내기 취소 response `data` 필드:
| 필드 | 타입 | 설명 |
|---|---|---|
| `applicationNo` | string | 선물 신청번호 |
| `status` | string | 취소 후 상태. `CANCELED` |
| `statusName` | string | 서버 상태 표시명 |
| `priceCan` | number | 환불되는 캔 수량 |
| `canceledAt` | string | 취소일. UTC ISO 문자열 |
테스트/검증:
- 리스트 item 탭 시 `applicationNo`로 상세 페이지가 열리는지 확인한다.
- 상세 진입 시 `GET /api/v2/gifts/{applicationNo}`가 호출되는지 확인한다.
- 상세 조회 결과 `status=CANCELED`이면 일반 상세가 아니라 취소 완료 페이지가 표시되는지 확인한다.
- `statusTimeline` 5개 단계가 모두 표시되는지 확인한다.
- Figma처럼 4단계로 하드코딩하지 않았는지 확인한다.
- `trackingRequired=true`이면 `운송장 작성하기`가 표시되는지 확인한다.
- 신청 취소 버튼 탭 시 `v2 dialog` 확인 팝업이 뜨고 즉시 API를 호출하지 않는지 확인한다.
- 취소 확인 dialog에서 `나가기`를 누르면 dialog만 닫히는지 확인한다.
- 취소 확인 dialog에서 `취소하기`를 누르면 `POST /api/v2/gifts/{applicationNo}/cancel`을 호출하는지 확인한다.
- 취소 성공 후 취소 완료 페이지가 표시되고 취소 전 상세/등록 화면으로 돌아가지 않는지 확인한다.
- `mailbox`가 있을 때만 사서함 주소 섹션이 표시되는지 확인한다.
- `direction=SENT`의 `RECEIVED`, `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED` 상태에서 `mailbox`가 표시되는지 확인한다.
- `DELIVERED`, `UNDELIVERABLE`, `CANCELED`, `direction=RECEIVED`에서는 `mailbox`가 표시되지 않는지 확인한다.
- `UNDELIVERABLE`이면 전달 불가 hero와 사유 섹션이 표시되는지 확인한다.
- 운송장 등록 페이지에서 택배사/운송장 번호 누락 시 API를 호출하지 않는지 확인한다.
- 운송장 등록 시 선택한 택배사 한글명과 운송장 번호가 request body로 전송되는지 확인한다.
- 운송장 등록 성공 후 상세 페이지가 재조회되어 `TRACKING_REGISTERED` 상태로 보이는지 확인한다.
- 모든 날짜는 UTC ISO 문자열을 앱 표시 형식으로 변환해 표시하는지 확인한다.
```
@@ -1,270 +0,0 @@
# 선물함 리스트 페이지 생성 프롬프트
이 문서는 Android/iOS 앱의 `선물함` 리스트 페이지를 생성할 때 사용하는 프롬프트다.
참고 Figma:
- 팬 모드, 신청한 내역이 있을 때: `2481:19382`
- 팬 모드, 신청한 내역이 없을 때: `2520:35587`
- 크리에이터 모드, 받은 선물 내역이 없을 때: `2531:36283`
- 크리에이터 모드, 받은 선물 내역이 있을 때: `2531:36194`
- 크리에이터 모드, 받은 선물 상태별 카드 표시: `2531:36237`
전제:
- Android/iOS 각각의 기존 디자인 시스템, 컴포넌트, API client, 상태 관리, toast/dialog, navigation 패턴을 재사용한다.
- Figma의 visual structure를 기준으로 구현하되, 아래 사용자 요구사항을 Figma보다 우선한다.
- 상단 뒤로가기 내비게이션 영역은 고정한다.
- 상단 뒤로가기 내비게이션 영역을 제외한 전체 콘텐츠 영역은 스크롤되어야 한다.
- `신청 내역`, `선물 내역` 섹션 타이틀은 표시하지 않는다.
- 리스트는 신청일/취소일 최신순으로 보여야 한다.
- request/response 설명은 모바일 공통 JSON 기준이다.
---
## 모바일 앱 구현 프롬프트
```text
Android/iOS 앱의 선물함 리스트 페이지를 Figma 기준으로 생성하고 API 연동을 구현해줘.
Figma는 두 관점의 상태를 보여준다.
- 보낸 선물 관점: 사용자가 본인이 신청한 선물 내역을 확인하는 상태다. Figma `2481:19382`, `2520:35587`를 기준으로 한다.
- 받은 선물 관점: 사용자가 본인이 받을 선물 내역을 확인하는 상태다. Figma `2531:36283`, `2531:36194`, `2531:36237`를 기준으로 한다.
- 실제 선물함 API는 두 관점을 나누어 호출하지 않고 `type=ALL`로 한 번 호출한다.
- 응답 item의 `direction` 값이 `SENT`이면 보낸 선물 카드로, `RECEIVED`이면 받은 선물 카드로 렌더링한다.
- 각 카드에는 상대방 프로필 이미지와 닉네임을 표시한다.
- `direction=SENT`: 상대방은 선물을 받는 크리에이터다.
- `direction=RECEIVED`: 상대방은 선물을 보낸 팬이다.
중요 요구사항:
- 상단 뒤로가기 내비게이션은 고정한다.
- 상단 내비게이션 아래의 전체 콘텐츠만 스크롤되게 한다.
- Figma에 보이는 `신청 내역`, `선물 내역` 섹션 타이틀은 실제 구현에서 표시하지 않는다.
- 선물함 리스트는 신청일/취소일 최신순으로 정렬한다.
- 현재 API 응답만으로 취소일 기준 정렬/표시는 완전하지 않으므로, API가 취소일을 내려주지 않으면 서버 응답 순서를 우선 사용하고 취소 건 날짜 라벨은 `createdAt` 기준으로 표시한다. 취소일 표시가 필수이면 API 보강이 필요하다.
API 호출:
- 선물함 리스트는 항상 `GET /api/v2/gifts?type=ALL&page=0&size=20`로 조회한다.
- `SENT`, `RECEIVED`로 따로 호출하지 않는다.
- `items[].direction`으로 보낸 선물/받은 선물 UI를 결정한다.
- 페이지 진입 시 첫 페이지를 조회한다.
- `hasNext=true`이면 스크롤 하단에서 다음 page를 추가 조회한다.
- pull-to-refresh가 기존 앱에 있으면 page를 0으로 초기화하고 다시 조회한다.
공통 레이아웃:
1. 상단 고정 내비게이션
- 타이틀: `선물함`
- 뒤로가기 버튼은 기존 앱 패턴을 사용한다.
- 이 영역은 스크롤되지 않는다.
2. 스크롤 콘텐츠
- nav 아래부터 시작한다.
- 안내 배너, 빈 상태, 리스트, 하단 여백 또는 하단 문의 버튼까지 스크롤 영역에 포함한다.
- iOS safe area와 Android navigation bar 여백은 기존 앱 패턴을 따른다.
보낸 선물 UI:
- `direction=SENT`인 item에 적용한다.
- 사용자가 신청한 선물 내역을 보여준다.
- 보낸 선물만 있는 상태는 Figma `2481:19382`를 따른다.
- 상단 안내 배너를 표시한다.
- 제목: `사서함을 통해 안전하게 전달됩니다`
- 본문: `크리에이터 및 팬의 주소는 공개되지 않습니다. 선물은 소다라이브 사서함에 도착한 뒤 크리에이터에게 전달됩니다.`
- `신청 내역` 섹션 타이틀은 표시하지 않는다.
- 카드 구성:
- 상단 왼쪽: `statusName`
- 상단 오른쪽: 날짜 라벨
- 기본: `{createdAt} 신청`
- 상태가 `CANCELED`이고 취소일 필드가 있으면 `{canceledAt} 취소`
- 현재 리스트 API에는 `canceledAt`이 없으므로 기존 API만 사용할 때는 `{createdAt} 취소` 또는 `{createdAt} 신청` 중 제품 정책에 맞춰 하나로 통일한다.
- 프로필 row 내부: `counterpartProfileImageUrl`, `counterpartNickname`을 사용해 받는 크리에이터 프로필을 표시한다.
- 프로필 row 아래 보조 문구: `sizeName · categoryName`
- 프로필 이미지가 없으면 기존 앱의 기본 프로필 이미지를 표시한다.
- 우측 chevron
- 탭 시 선물 상세 페이지로 이동하며 `applicationNo`를 전달한다.
- 리스트가 비어 있고 보낸 선물 관점으로 진입한 화면이면 Figma `2520:35587`를 따른다.
- 상단 안내 배너만 표시한다.
- 별도 empty title/body를 추가하지 않는다.
받은 선물 UI:
- `direction=RECEIVED`인 item에 적용한다.
- 사용자가 받을 선물 내역을 보여준다.
- 리스트가 비어 있고 받은 선물 관점으로 진입한 화면이면 Figma `2531:36283`를 따른다.
- 가운데 empty title: `전달 예정인 선물이 없어요`
- empty body: `베타 기간에는 팬이 선물을 보내는 기능만 제공돼요. 더 다양해진 선물 기능으로 곧 다시 만나요!`
- 버튼: `의견 남기기`
- 의견 남기기 동작은 기존 앱의 문의/피드백 이동 패턴을 사용한다.
- 받은 선물이 있는 상태는 Figma `2531:36194`, `2531:36237`를 따른다.
- 상단 안내 배너를 표시한다.
- 제목: `배송지 입력 기간 안내`
- 본문: `알림을 받은 날부터 7일 이내에 배송지를 입력해 주세요. 기한 내 입력하지 않으면 선물이 반송됩니다.`
- `선물 내역` 섹션 타이틀은 표시하지 않는다.
- 배송지 입력이 필요한 선물이 있으면 파란 안내 배너를 리스트 상단에 표시한다.
- 제목: `팬이 보낸 선물이 있어요!`
- 본문: `선물이 늦지 않게 전달될 수 있도록 배송지를 입력해 주세요.`
- 보조 문구: `*n일 이내로 입력하지 않으면 선물이 사라져요.`
- 현재 리스트 API에는 배송지 입력 마감일이 없으므로 정확한 n일 계산이 필요하면 API 보강이 필요하다.
- 배너 탭 시 배송지 입력이 필요한 첫 번째 선물 상세로 이동한다.
- 카드 구성:
- 상단 왼쪽 프로필 row 내부: `counterpartProfileImageUrl`, `counterpartNickname`을 사용해 보낸 팬 프로필을 표시한다.
- 상단 오른쪽: `{createdAt} 신청`
- 본문 메인: 상태 표시 문구
- 본문 서브: 상태 보조 문구가 필요한 경우만 표시
- 우측 chevron
- 탭 시 선물 상세 페이지로 이동하며 `applicationNo`를 전달한다.
- 리스트 하단에는 Figma처럼 `문의하기` 하단 버튼을 둘 수 있다. 기존 앱 정책상 고정 버튼이면 하단 safe area를 포함하고, 스크롤 콘텐츠 내부 버튼이면 콘텐츠 하단에 둔다.
상태 표시 매핑:
보낸 선물 카드:
| API status | 표시 문구 |
|---|---|
| `RECEIVED` | `운송장 등록 필요` |
| `TRACKING_REGISTERED` | `발송 확인` |
| `ARRIVED_AT_MAILBOX` | `사서함 도착` |
| `INSPECTION_COMPLETED` | `선물 검수 완료` |
| `DELIVERED` | `전달 완료` |
| `UNDELIVERABLE` | `전달 불가` |
| `CANCELED` | `신청 취소` |
받은 선물 카드:
| API status | 메인 문구 | 서브 문구 |
|---|---|---|
| `TRACKING_REGISTERED` | `배송지 입력 필요` | `전달 예정` |
| `ARRIVED_AT_MAILBOX` | `선물 검수` | `선물 확인 중` |
| `INSPECTION_COMPLETED` | `선물 검수 완료` | `배송 중` |
| `DELIVERED` | `전달 완료` | 없음 |
| `UNDELIVERABLE` | `전달 불가` | 없음 |
API 명세:
선물함 리스트 조회 API:
- Method: `GET`
- URL: `/api/v2/gifts`
- 인증: 로그인 필요
- Query:
- `type`: `ALL`, `SENT`, `RECEIVED`
- `page`: 0부터 시작
- `size`: 페이지 크기. 기본 20
- 이 페이지에서는 `type=ALL`만 사용한다.
- Response envelope 예시:
```json
{
"success": true,
"data": {
"totalCount": 1,
"items": [],
"page": 0,
"size": 20,
"hasNext": false
},
"message": ""
}
```
Response `data` 예시:
```json
{
"totalCount": 2,
"items": [
{
"applicationNo": "A-1002609300001",
"direction": "SENT",
"status": "RECEIVED",
"statusName": "접수 완료",
"priceCan": 80,
"categoryName": "아크릴/스탠드",
"sizeName": "소형",
"counterpartMemberId": 200,
"counterpartNickname": "달빛수집가",
"counterpartProfileImageUrl": "https://example.com/profile.png",
"recipientAddressRegistered": false,
"recipientAddressDeadlineAt": null,
"canceledAt": null,
"createdAt": "2026-09-18T03:00:00Z"
}
],
"page": 0,
"size": 20,
"hasNext": false
}
```
Response `data` 필드:
| 필드 | 타입 | 설명 |
|---|---|---|
| `totalCount` | number | 전체 개수 |
| `items` | array | 선물함 리스트 |
| `items[].applicationNo` | string | 선물 신청번호. 상세 이동 ID |
| `items[].direction` | string | `SENT` 또는 `RECEIVED` |
| `items[].status` | string | 선물 상태 코드 |
| `items[].statusName` | string | 서버 상태 표시명 |
| `items[].priceCan` | number | 사용된 캔 |
| `items[].categoryName` | string | 카테고리명 |
| `items[].sizeName` | string | 사이즈명 |
| `items[].counterpartMemberId` | number | 상대방 회원 ID. `SENT`에서는 받는 크리에이터, `RECEIVED`에서는 보낸 팬 |
| `items[].counterpartNickname` | string | 상대방 닉네임 |
| `items[].counterpartProfileImageUrl` | string 또는 null | 상대방 프로필 이미지 URL. 없으면 기본 프로필 이미지 표시 |
| `items[].recipientAddressRegistered` | boolean | 크리에이터 배송지 필수 정보가 모두 입력되었는지 여부 |
| `items[].recipientAddressDeadlineAt` | string 또는 null | `direction=RECEIVED`이고 배송지가 아직 입력되지 않은 경우의 배송지 입력 기한. 배송지 입력 완료 후에는 null |
| `items[].canceledAt` | string 또는 null | 취소 상태의 취소일. 취소되지 않은 선물은 null |
| `items[].createdAt` | string 또는 null | 신청일. UTC ISO 문자열 |
| `page` | number | 현재 페이지 |
| `size` | number | 페이지 크기 |
| `hasNext` | boolean | 다음 페이지 존재 여부 |
정렬:
- 현재 서버 API는 `createdAt desc, id desc`로 정렬한다.
- 요구사항은 신청일/취소일 최신순이다.
- 취소일 최신순까지 정확히 맞추려면 리스트 API가 `canceledAt` 또는 `displayedAt` 같은 정렬 기준 시각을 내려주고 그 기준으로 정렬해야 한다.
- API 보강 전에는 서버 응답 순서를 그대로 사용하고, 클라이언트에서 임의 재정렬하지 않는다.
상대방 프로필 표시 규칙:
- `counterpartNickname`은 카드의 프로필 row 이름으로 표시한다.
- `counterpartProfileImageUrl`이 있으면 해당 이미지를 원형 프로필 이미지로 표시한다.
- `counterpartProfileImageUrl`이 `null`이거나 빈 값이면 기존 앱의 기본 프로필 이미지를 표시한다.
- `direction=SENT`에서는 받는 크리에이터 정보로 해석한다.
- `direction=RECEIVED`에서는 보낸 팬 정보로 해석한다.
배송지/취소 표시 규칙:
- 배송지 입력 완료 여부는 `recipientAddressRegistered`로 판단한다.
- 배송지 입력 남은 기간은 `recipientAddressDeadlineAt` 기준으로 앱에서 계산한다.
- 배송지가 이미 입력되었으면 `recipientAddressDeadlineAt`은 null이다.
- 취소 상태의 날짜 라벨은 `canceledAt`이 있으면 `{canceledAt} 취소`로 표시하고, 그 외에는 `{createdAt} 신청`으로 표시한다.
로딩/에러/빈 상태:
- 최초 로딩 중에는 기존 앱 리스트 스켈레톤 또는 loading 패턴을 사용한다.
- 실패 시 기존 앱 toast/dialog와 재시도 버튼을 사용한다.
- 빈 상태는 진입 관점에 따라 다르게 표시한다.
- 보낸 선물 관점으로 진입한 화면이면 안내 배너만 남긴다.
- 받은 선물 관점으로 진입한 화면이면 중앙 empty UI와 `의견 남기기` 버튼을 표시한다.
테스트/검증:
- 선물함 진입 시 `type=ALL`로 API를 한 번 호출하는지 확인한다.
- `direction=SENT` item은 보낸 선물 카드 UI로 표시되는지 확인한다.
- `direction=RECEIVED` item은 받은 선물 카드 UI로 표시되는지 확인한다.
- 각 item의 `counterpartNickname`, `counterpartProfileImageUrl`이 프로필 row에 표시되는지 확인한다.
- `counterpartProfileImageUrl=null`이면 기본 프로필 이미지가 표시되는지 확인한다.
- 상단 내비게이션은 고정되고 아래 콘텐츠만 스크롤되는지 확인한다.
- `신청 내역`, `선물 내역` 텍스트가 실제 화면에 노출되지 않는지 확인한다.
- 리스트 item 탭 시 `applicationNo`로 상세 화면 이동이 되는지 확인한다.
- 빈 상태가 진입 관점에 맞는 Figma 기준으로 표시되는지 확인한다.
- `hasNext=true`일 때 다음 page를 추가 조회하는지 확인한다.
- API 실패 시 입력/스크롤 상태를 깨지 않고 오류와 재시도를 제공하는지 확인한다.
```
---
## API 요약
| 목적 | Method | URL | Query | Response data |
|---|---|---|---|---|
| 선물함 리스트 조회 | GET | `/api/v2/gifts` | `type=ALL`, `page`, `size` | 선물 리스트, 페이지 정보 |
## Figma 반영 메모
- 보낸 선물 리스트 있음: 안내 배너 + 카드 리스트. 단, 실제 구현에서는 `신청 내역` 타이틀을 제거한다.
- 보낸 선물 관점 empty: 안내 배너만 표시한다.
- 받은 선물 관점 empty: 중앙 empty UI와 `의견 남기기` 버튼을 표시한다.
- 받은 선물 리스트 있음: 안내 배너 + 배송지 입력 CTA 배너 + 카드 리스트. 단, 실제 구현에서는 `선물 내역` 타이틀을 제거한다.
- 받은 선물 상태별 카드는 `배송지 입력 완료/전달 예정`, `전달 완료`, `전달 불가`, `선물 검수/선물 확인 중`, `선물 검수 완료/배송 중` 패턴을 사용한다.
@@ -1,114 +0,0 @@
# 선물 받을 주소 관리자 페이지 구현 프롬프트
이 문서는 관리자 페이지에서 전역 선물 받을 주소를 등록/수정하는 화면을 구현할 때 사용하는 프롬프트다.
## 전제
- 여기서 말하는 `선물 받을 주소`는 선물 상대방 주소가 아니다.
- 관리자가 등록하는 전역 단일 주소다.
- 팬이 보낸 선물 상세를 정상 진행 상태 중 전달 완료 전(`RECEIVED`, `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`)에 조회할 때, 이 주소가 `mailbox`로 노출된다.
- 새 디자인 시스템을 만들지 말고 기존 관리자 페이지의 폼, 버튼, 토스트, 에러 표시 패턴을 재사용한다.
## 구현 프롬프트
```text
관리자 선물 받을 주소 설정 페이지를 구현해줘.
목표:
- 관리자 메뉴 `선물함 관리 > 받을 주소`에서 팬이 선물을 보낼 전역 단일 주소를 조회하고 저장한다.
- 이 주소는 상대방 주소가 아니라 관리자가 등록하는 운영 주소다.
- 팬의 선물 상세 API에서는 `direction=SENT`이고 `status`가 `RECEIVED`, `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`일 때 이 주소가 `mailbox`로 노출된다.
- 기존 관리자 페이지의 폼, 저장 버튼, 토스트, 에러 표시 패턴을 그대로 따른다.
라우트:
- `/gift/mailbox`
메뉴:
- parent: `선물함 관리`
- label: `받을 주소`
- path: `/gift/mailbox`
필수 화면 구성:
- 상단 제목: `받을 주소`
- 설명 문구: `팬이 선물을 발송할 때 확인하는 받을 주소입니다.`
- 입력 폼:
- 받을 사람 이름 `name`
- 연락처 `phoneNumber`
- 우편번호 `zipCode`
- 주소 `address`
- 상세주소 `addressDetail`
- 저장 버튼: `저장`
초기 조회 API:
- Method: `GET`
- URL: `/api/v2/admin/gift-mailbox`
- 모든 API 응답은 기존 공통 envelope를 사용한다.
- 화면에서는 `response.data`를 실제 payload로 사용한다.
- response `data`:
```ts
type AdminGiftMailboxResponse = {
name: string;
address: string;
phoneNumber: string;
} | null;
```
- `data`가 null이면 아직 등록된 받을 주소가 없는 상태다.
- null이면 빈 폼을 표시한다.
저장 API:
- Method: `PUT`
- URL: `/api/v2/admin/gift-mailbox`
- Request:
```ts
type AdminGiftMailboxRequest = {
name: string;
phoneNumber: string;
zipCode: string;
address: string;
addressDetail: string | null;
};
```
- Response `data`:
```ts
type AdminGiftMailboxResponse = {
name: string;
address: string;
phoneNumber: string;
};
```
동작 규칙:
- 받을 주소는 전역 단일 설정이다.
- 등록과 수정은 같은 `PUT /api/v2/admin/gift-mailbox` API를 사용한다.
- 최초 저장이면 생성처럼 동작한다.
- 이미 저장된 값이 있으면 기존 주소를 수정한다.
- 별도 ID, 목록, 삭제 기능은 만들지 않는다.
폼 validation:
- `name`, `phoneNumber`, `zipCode`, `address`는 필수다.
- 필수값은 공백만 입력할 수 없다.
- `addressDetail`은 선택이다.
- validation 실패 시 API를 호출하지 않고 기존 관리자 페이지의 필드 에러 표시 방식을 따른다.
저장 성공 UX:
- 성공 토스트를 표시한다.
- 저장 API response 기준으로 화면 값을 갱신한다.
- response의 `address`는 서버가 조립한 `(우편번호) 주소, 상세주소` 형식이다.
- 입력 필드는 사용자가 입력한 `zipCode`, `address`, `addressDetail` 값을 유지해도 된다.
빈 상태 UX:
- 조회 결과 `data=null`이면 빈 폼을 보여준다.
- 필요하면 안내 문구 `등록된 받을 주소가 없습니다. 주소를 입력하고 저장해주세요.`를 표시한다.
에러 처리:
- API 실패 시 기존 관리자 페이지의 공통 에러 토스트/알림 패턴을 따른다.
- 인증/권한 처리는 기존 관리자 API client와 토큰 처리 방식을 따른다.
테스트/검증:
- `/gift/mailbox` route가 선물함 관리 메뉴에서 접근되는지 확인한다.
- 초기 조회 시 `GET /api/v2/admin/gift-mailbox`를 호출하는지 확인한다.
- 조회 결과가 null이면 빈 폼을 표시하는지 확인한다.
- 저장 시 `PUT /api/v2/admin/gift-mailbox`와 request body가 정확한지 확인한다.
- 필수값 공백 validation 시 API를 호출하지 않는지 확인한다.
- 저장 성공 후 성공 토스트와 화면 갱신이 일어나는지 확인한다.
```
@@ -1,421 +0,0 @@
# 받은 선물 상세 및 배송지 입력 페이지 생성 프롬프트
이 문서는 Android/iOS 앱의 `선물함` 리스트에서 받은 선물 상세 페이지와 배송지 입력 UI를 생성할 때 사용하는 프롬프트다.
참고 Figma:
- 배송지 입력 전 상세 UI: `2531:36290`
- 배송지 입력 완료 후 상세 UI: `2531:36399`
- 선물 전달 완료시 상세 UI: `2531:36330`
- 선물 전달 불가시 상세 UI: `2531:36422`
전제:
- 선물함 리스트 item 탭 시 `applicationNo`를 전달받아 상세 페이지로 이동한다.
- 새 디자인 시스템을 만들지 말고 Android/iOS 각각의 기존 디자인 시스템, 컴포넌트, API client, 상태 관리, toast/dialog, navigation 패턴을 재사용한다.
- 모든 API 응답은 공통 envelope를 사용하며 실제 payload는 `response.data`다.
- 이 프롬프트는 받는 크리에이터 관점(`direction=RECEIVED`)만 다룬다.
- API 예시는 TypeScript 타입이 아니라 JSON으로 작성한다.
---
## 모바일 앱 구현 프롬프트
```text
Android/iOS 앱의 받은 선물 상세 페이지와 배송지 입력 UI를 Figma 기준으로 생성하고 API 연동을 구현해줘.
범위:
- 선물함 리스트에서 `applicationNo`를 받아 받은 선물 상세 페이지로 이동한다.
- 상세 페이지는 `GET /api/v2/gifts/{applicationNo}` 응답으로 렌더링한다.
- `direction=RECEIVED && recipientAddressRequired=true`이면 배송지 입력 UI를 표시한다.
- 배송지 입력은 `POST /api/v2/gifts/{applicationNo}/recipient-address`로 연결한다.
- 배송지 입력 완료 후에는 상세를 다시 조회해 배송지 입력 완료 상태 UI를 표시한다.
중요 전제:
- Figma의 visual structure와 문구를 우선 따르되, 데이터 노출과 CTA 조건은 API 계약을 우선한다.
- `direction=RECEIVED` 화면에서 `senderInfo`, `mailbox`, `giftInfo.applicationNo`, `giftInfo.paidCan`, `giftInfo.tracking`은 표시하지 않는다.
- `recipientAddress`가 null이면 받는 주소 섹션 자체를 표시하지 않는다. 전달 완료 후 배송지 정보가 삭제될 예정이므로 빈 섹션, skeleton, `-` 값도 표시하지 않는다.
- 전달 불가 화면의 `문의하기`는 기존 앱의 카카오 채널 문의 연결과 동일하게 연결한다.
- 전달 불가 화면의 `선물 정책 확인`은 버튼/action만 만들어두고 실제 외부 페이지 연결은 하지 않는다. 임의 URL을 연결하지 않는다.
상세 페이지 진입:
- 화면 진입 시 `GET /api/v2/gifts/{applicationNo}`를 호출한다.
- 조회 결과 `direction`이 `RECEIVED`가 아니면 이 화면을 렌더링하지 말고 기존 앱의 잘못된 접근/상세 재라우팅 정책을 따른다.
- 로딩 중에는 기존 앱 상세 화면 로딩/스켈레톤 패턴을 사용한다.
- 실패 시 기존 앱 toast/dialog와 재시도 패턴을 사용한다.
배송지 입력 전 UI:
- 적용 조건: `direction=RECEIVED && recipientAddressRequired=true`.
- Figma `2531:36290`을 따른다.
- 상단 타이틀: `선물 받기`.
- 개인정보 이용 안내 배너를 표시한다.
- 제목: `개인정보 이용 안내`
- 본문: `크리에이터 및 팬의 주소는 공개되지 않습니다. 입력한 배송지는 선물 전달 및 필요한 사고 처리에서 사용되며, 전달 완료 후 파기됩니다.`
- `전달 예정 선물` 섹션을 표시한다.
- 발송인: `giftInfo.senderNickname`
- 사이즈: `giftInfo.sizeName`
- 카테고리: `giftInfo.categoryName`
- `배송지 입력` 섹션을 표시한다.
- 이름 input: `recipientName`
- 휴대폰 번호 input: `recipientPhoneNumber`
- 우편번호 input: `recipientZipCode`
- 우편번호 검색 버튼: 기존 페이지와 동일하게 Kakao 우편번호 서비스를 사용한다.
- 주소 input: `recipientAddress`
- 상세 주소 input: `recipientAddressDetail`
- `이용 약관 동의` 섹션을 표시한다.
- `소다라이브 크리에이터 상품 전달 이용약관 및 전달 가능 제한 품목을 확인하고 동의합니다.(필수)`
- `상품 전달을 위해 수령인 성명·연락처·주소 등 필요한 개인정보를 일시적으로 수집·이용하는 것에 동의합니다.(필수)`
- 두 항목 모두 체크해야 제출 가능하다.
- 약관 상세 링크는 앱에 기존 약관/webview 경로가 있으면 연결하고, 없으면 새 페이지를 만들지 않는다.
- 하단 주요 CTA: `선물 받기`.
- CTA 활성 조건:
- 이름, 휴대폰 번호, 우편번호, 주소가 공백이 아니다.
- 상세 주소는 선택 입력이다.
- 약관 2개가 모두 체크됐다.
- submit 중에는 중복 탭을 막고 loading 상태를 표시한다.
배송지 입력 API 연결:
- CTA 탭 시 `POST /api/v2/gifts/{applicationNo}/recipient-address`를 호출한다.
- request body에는 화면 입력값과 약관 동의 boolean을 그대로 전송한다.
- 성공 시 성공 toast를 표시하고 상세 페이지를 다시 조회하거나 replace navigation으로 상세를 다시 연다.
- 실패 시 기존 앱 form error/toast/dialog 패턴을 따른다. 실패 상태에서 입력값은 유지한다.
주소 검색 구현:
- 기존 앱/페이지에 Kakao 우편번호 서비스 래퍼가 있으면 반드시 재사용한다.
- 신규 연결이 필요하면 Kakao 우편번호 서비스 공식 가이드 `https://postcode.map.kakao.com/guide`를 따른다.
- SDK script는 공식 가이드의 `//t1.kakaocdn.net/mapjsapi/bundle/postcode/prod/postcode.v2.js`를 사용한다. 임의 수정본이나 별도 주소 검색 API를 만들지 않는다.
- Android/iOS WebView 또는 모바일웹 환경에서는 `window.open` 팝업이 막힐 수 있으므로, 기존 페이지와 같은 방식이 없다면 Kakao 가이드의 `embed()` 기반 레이어/페이지 삽입 방식을 우선 검토한다.
- 검색 결과 선택 시:
- `data.zonecode`를 `recipientZipCode`에 넣는다.
- `data.userSelectedType === "R"`이면 `data.roadAddress`를, 그 외에는 `data.jibunAddress`를 `recipientAddress`에 넣는다.
- 주소 선택 후 `recipientAddressDetail` 입력으로 포커스를 이동한다.
- 상세 주소는 Kakao 결과에서 채우지 않고 사용자가 직접 입력하게 한다.
- 주소 검색 실패/취소 시 입력 중이던 이름, 휴대폰 번호, 약관 체크 상태를 초기화하지 않는다.
배송지 입력 완료 후 상세 UI:
- 적용 조건: `direction=RECEIVED && recipientAddressRequired=false && status`가 `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED` 중 하나이며 `recipientAddress`가 있다.
- Figma `2531:36399`를 따른다.
- 상단 타이틀: `선물 상세`.
- hero title: `배송지 입력 완료!`
- hero body: `빠른 시일 내로 선물을 전달 드릴게요.`
- `문의하기` 버튼을 표시하고 기존 카카오 채널 문의로 연결한다.
- `선물 정보` 섹션을 표시한다.
- 발송인: `giftInfo.senderNickname`
- 사이즈: `giftInfo.sizeName`
- 카테고리: `giftInfo.categoryName`
- 배송 신청일: `giftInfo.shippingRequestedAt`
- `받는 주소` 섹션은 `recipientAddress`가 있을 때만 표시한다.
- 이름: `recipientAddress.name`
- 휴대폰 번호: `recipientAddress.phoneNumber`
- 주소: `recipientAddress.address`
선물 전달 완료 상세 UI:
- 적용 조건: `direction=RECEIVED && status=DELIVERED`.
- Figma `2531:36330`을 따른다.
- 상단 타이틀: `선물 상세`.
- hero title: `선물 전달 완료!`
- hero body: `팬이 보낸 선물이 도착했어요. 선물이 도착하지 않은 경우, 문의해 주세요.`
- `문의하기` 버튼을 표시하고 기존 카카오 채널 문의로 연결한다.
- `선물 정보` 섹션을 표시한다.
- 발송인: `giftInfo.senderNickname`
- 사이즈: `giftInfo.sizeName`
- 카테고리: `giftInfo.categoryName`
- 배송 신청일: `giftInfo.shippingRequestedAt`
- 배송 완료일: `statusTimeline`에서 `DELIVERED.occurredAt`
- `받는 주소` 섹션은 `recipientAddress`가 있을 때만 표시한다.
- 섹션 보조 문구: `배송 완료 3일 후 해당 정보는 사라져요`
- 이름: `recipientAddress.name`
- 휴대폰 번호: `recipientAddress.phoneNumber`
- 주소: `recipientAddress.address`
- `recipientAddress=null`이면 `받는 주소` 섹션 전체를 숨긴다.
선물 전달 불가 상세 UI:
- 적용 조건: `direction=RECEIVED && status=UNDELIVERABLE`.
- Figma `2531:36422`를 따른다.
- 상단 타이틀: `선물 상세`.
- chip: `전달 불가`
- hero title: `전달할 수 없는 품목입니다`
- hero body: `해당 선물은 SODALIVE 선물 정책에 따라 크리에이터에게 전달할 수 없는 품목으로 확인되었습니다.`
- action button:
- `문의하기`: 기존 카카오 채널 문의로 연결한다.
- `선물 정책 확인`: action handler만 연결하고 실제 외부 페이지/URL은 연결하지 않는다. 기존 앱 정책상 no-op이 금지되어 있으면 `준비 중입니다.` toast만 표시한다.
- `사유` 섹션을 표시한다.
- 사유 제목: `delivery.undeliverableReason`이 있으면 그 값을 사용한다.
- `delivery.undeliverableReason`이 null이면 `전달 불가`로 표시한다.
- 안내 문구: `해당 선물은 정책에 따라 폐기되며 반송되지 않습니다.`
- 전달 불가 상태에서는 배송지 입력 UI를 표시하지 않는다.
- `recipientAddress`가 응답에 있더라도 전달 불가 Figma에는 받는 주소 섹션이 없으므로 표시하지 않는다.
날짜 표시:
- API의 모든 날짜는 UTC ISO 문자열이다.
- 앱 공통 날짜 formatter가 있으면 재사용한다.
- Figma처럼 상세 필드 날짜는 `YYYY.MM.DD`로 표시한다.
- 값이 null이면 해당 row를 숨긴다.
API 명세:
선물 상세 조회:
- Method: `GET`
- URL: `/api/v2/gifts/{applicationNo}`
- 인증: 로그인 필요
- Response envelope 예시 - 배송지 입력 전:
```json
{
"success": true,
"data": {
"applicationNo": "A-1002609300001",
"direction": "RECEIVED",
"status": "TRACKING_REGISTERED",
"statusName": "발송 확인",
"giftInfo": {
"recipientCreatorNickname": null,
"senderNickname": "팬닉네임이들어가는부분",
"sizeName": "소형",
"categoryName": "신규 전자굿즈",
"applicationNo": null,
"paidCan": null,
"tracking": null,
"shippingRequestedAt": "2026-10-12T03:00:00Z"
},
"senderInfo": null,
"recipientAddress": null,
"mailbox": null,
"trackingRequired": false,
"recipientAddressRequired": true,
"recipientAddressDeadlineAt": "2026-10-19T03:00:00Z",
"delivery": {
"canceledAt": null,
"undeliverableAt": null,
"undeliverableReason": null
},
"statusTimeline": [
{
"status": "RECEIVED",
"statusName": "접수 완료",
"occurredAt": "2026-10-11T03:00:00Z"
},
{
"status": "TRACKING_REGISTERED",
"statusName": "발송 확인",
"occurredAt": "2026-10-12T03:00:00Z"
},
{
"status": "ARRIVED_AT_MAILBOX",
"statusName": "사서함 도착",
"occurredAt": null
},
{
"status": "INSPECTION_COMPLETED",
"statusName": "검수완료",
"occurredAt": null
},
{
"status": "DELIVERED",
"statusName": "전달완료",
"occurredAt": null
}
]
},
"message": ""
}
```
Response envelope 예시 - 배송지 입력 완료/전달 완료:
```json
{
"success": true,
"data": {
"applicationNo": "A-1002609300001",
"direction": "RECEIVED",
"status": "DELIVERED",
"statusName": "전달완료",
"giftInfo": {
"recipientCreatorNickname": null,
"senderNickname": "팬닉네임이들어가는부분",
"sizeName": "소형",
"categoryName": "신규 전자굿즈",
"applicationNo": null,
"paidCan": null,
"tracking": null,
"shippingRequestedAt": "2026-10-12T03:00:00Z"
},
"senderInfo": null,
"recipientAddress": {
"name": "크리에이터이름",
"phoneNumber": "01012345678",
"address": "(04030) 서울특별시 마포구 양화로 000, 3층"
},
"mailbox": null,
"trackingRequired": false,
"recipientAddressRequired": false,
"recipientAddressDeadlineAt": "2026-10-19T03:00:00Z",
"delivery": {
"canceledAt": null,
"undeliverableAt": null,
"undeliverableReason": null
},
"statusTimeline": [
{
"status": "RECEIVED",
"statusName": "접수 완료",
"occurredAt": "2026-10-11T03:00:00Z"
},
{
"status": "TRACKING_REGISTERED",
"statusName": "발송 확인",
"occurredAt": "2026-10-12T03:00:00Z"
},
{
"status": "ARRIVED_AT_MAILBOX",
"statusName": "사서함 도착",
"occurredAt": "2026-10-14T03:00:00Z"
},
{
"status": "INSPECTION_COMPLETED",
"statusName": "검수완료",
"occurredAt": "2026-10-16T03:00:00Z"
},
{
"status": "DELIVERED",
"statusName": "전달완료",
"occurredAt": "2026-10-22T03:00:00Z"
}
]
},
"message": ""
}
```
Response envelope 예시 - 전달 불가:
```json
{
"success": true,
"data": {
"applicationNo": "A-1002609300001",
"direction": "RECEIVED",
"status": "UNDELIVERABLE",
"statusName": "전달불가",
"giftInfo": {
"recipientCreatorNickname": null,
"senderNickname": "팬닉네임이들어가는부분",
"sizeName": "소형",
"categoryName": "신규 전자굿즈",
"applicationNo": null,
"paidCan": null,
"tracking": null,
"shippingRequestedAt": "2026-10-12T03:00:00Z"
},
"senderInfo": null,
"recipientAddress": null,
"mailbox": null,
"trackingRequired": false,
"recipientAddressRequired": false,
"recipientAddressDeadlineAt": "2026-10-19T03:00:00Z",
"delivery": {
"canceledAt": null,
"undeliverableAt": "2026-10-16T03:00:00Z",
"undeliverableReason": "음식물 또는 보관이 어려운 품목"
},
"statusTimeline": [
{
"status": "RECEIVED",
"statusName": "접수 완료",
"occurredAt": "2026-10-11T03:00:00Z"
},
{
"status": "TRACKING_REGISTERED",
"statusName": "발송 확인",
"occurredAt": "2026-10-12T03:00:00Z"
},
{
"status": "ARRIVED_AT_MAILBOX",
"statusName": "사서함 도착",
"occurredAt": "2026-10-14T03:00:00Z"
},
{
"status": "INSPECTION_COMPLETED",
"statusName": "검수완료",
"occurredAt": null
},
{
"status": "DELIVERED",
"statusName": "전달완료",
"occurredAt": null
}
]
},
"message": ""
}
```
선물 상세 response `data` 필드:
| 필드 | 설명 |
|---|---|
| `applicationNo` | 선물 신청번호. 화면 진입 key로 사용한다. |
| `direction` | 이 프롬프트에서는 `RECEIVED`만 렌더링한다. |
| `status` | `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`, `DELIVERED`, `UNDELIVERABLE` 등을 상태별 UI 분기에 사용한다. |
| `giftInfo.senderNickname` | 받은 선물 관점의 발송인 팬 닉네임. |
| `giftInfo.sizeName` | 선물 사이즈명. |
| `giftInfo.categoryName` | 카테고리명. |
| `giftInfo.shippingRequestedAt` | 배송 신청일. UTC ISO 문자열. |
| `recipientAddress` | 크리에이터 본인이 입력한 배송지. null이면 받는 주소 섹션을 숨긴다. |
| `recipientAddressRequired` | 배송지 입력 UI 표시 여부. |
| `recipientAddressDeadlineAt` | 배송지 입력 마감일. 필요하면 안내 문구에 사용한다. |
| `delivery.undeliverableReason` | 전달 불가 사유. |
| `statusTimeline` | 배송 완료일 등 상태별 날짜를 찾는 데 사용한다. |
배송지 입력:
- Method: `POST`
- URL: `/api/v2/gifts/{applicationNo}/recipient-address`
- 인증: 로그인 필요
- Request:
```json
{
"recipientName": "크리에이터이름",
"recipientPhoneNumber": "01012345678",
"recipientZipCode": "04030",
"recipientAddress": "서울특별시 마포구 양화로 000",
"recipientAddressDetail": "3층",
"recipientTermsAgreed": true,
"recipientPrivacyAgreed": true
}
```
- Response envelope 예시:
```json
{
"success": true,
"data": {
"applicationNo": "A-1002609300001",
"status": "TRACKING_REGISTERED",
"statusName": "발송 확인",
"recipientAddressRegisteredAt": "2026-10-13T03:00:00Z"
},
"message": ""
}
```
배송지 입력 response `data` 필드:
| 필드 | 설명 |
|---|---|
| `applicationNo` | 선물 신청번호 |
| `status` | 등록 후 상태. 일반적으로 기존 진행 상태 유지 |
| `statusName` | 서버 상태 표시명 |
| `recipientAddressRegisteredAt` | 배송지 입력 완료 시각. UTC ISO 문자열 |
테스트/검증:
- 리스트 item 탭 시 `applicationNo`로 받은 선물 상세 페이지가 열리는지 확인한다.
- 상세 진입 시 `GET /api/v2/gifts/{applicationNo}`가 호출되는지 확인한다.
- `direction=RECEIVED && recipientAddressRequired=true`이면 배송지 입력 UI가 표시되는지 확인한다.
- 배송지 입력 필수값 또는 약관 동의가 누락되면 `POST /recipient-address`를 호출하지 않는지 확인한다.
- 배송지 입력 submit 시 request body가 API 명세와 일치하는지 확인한다.
- 배송지 입력 성공 후 상세가 재조회되고 배송지 입력 완료 UI가 표시되는지 확인한다.
- 배송지 입력 완료/전달 완료 상태에서 `recipientAddress`가 있으면 받는 주소 섹션이 표시되는지 확인한다.
- `recipientAddress=null`이면 받는 주소 섹션 자체가 표시되지 않는지 확인한다.
- `status=DELIVERED`이면 전달 완료 UI와 배송 완료일이 표시되는지 확인한다.
- `status=UNDELIVERABLE`이면 전달 불가 UI, 사유, 폐기/반송 불가 안내가 표시되는지 확인한다.
- 전달 불가 화면의 `문의하기`는 기존 카카오 채널 문의로 연결되는지 확인한다.
- 전달 불가 화면의 `선물 정책 확인`은 버튼 action만 있고 실제 외부 URL을 열지 않는지 확인한다.
- 모든 날짜는 UTC ISO 문자열을 앱 표시 형식으로 변환해 표시하는지 확인한다.
```
@@ -1,138 +0,0 @@
CREATE TABLE gift_category (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '내부 기본키',
classification_number VARCHAR(3) NOT NULL COMMENT '신청번호에 사용하는 3자리 분류번호',
category_code VARCHAR(50) NOT NULL COMMENT '내부 범용코드',
name VARCHAR(50) NOT NULL COMMENT '분류명',
receipt_code VARCHAR(9) NOT NULL COMMENT '신청번호에 사용하는 접수코드',
representative_item VARCHAR(100) NOT NULL COMMENT '대표품목',
requires_damage_waiver TINYINT(1) NOT NULL COMMENT '파손면책 동의 필요 여부',
is_active TINYINT(1) NOT NULL COMMENT '활성 여부',
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
PRIMARY KEY (id),
UNIQUE KEY uk_gift_category_classification_number (classification_number),
UNIQUE KEY uk_gift_category_code (category_code),
UNIQUE KEY uk_gift_category_receipt_code (receipt_code)
) COMMENT='선물 카테고리';
CREATE TABLE gift_mailbox (
id BIGINT NOT NULL COMMENT '전역 단일 설정 ID. 항상 1',
name VARCHAR(50) NOT NULL COMMENT '받을 사람 이름',
phone_number VARCHAR(30) NOT NULL COMMENT '받을 연락처',
zip_code VARCHAR(20) NOT NULL COMMENT '받을 우편번호',
address VARCHAR(255) NOT NULL COMMENT '받을 주소',
address_detail VARCHAR(255) NULL COMMENT '받을 상세주소',
PRIMARY KEY (id)
) COMMENT='선물 받을 주소 전역 설정';
CREATE TABLE gift (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '내부 기본키',
application_no VARCHAR(40) NOT NULL COMMENT '신청번호',
sender_member_id BIGINT NOT NULL COMMENT '보내는 팬 회원번호',
recipient_member_id BIGINT NOT NULL COMMENT '받는 크리에이터 회원번호',
status VARCHAR(30) NOT NULL COMMENT '선물 상태',
size_code VARCHAR(20) NOT NULL COMMENT '선물 사이즈 코드',
category_id BIGINT NOT NULL COMMENT '신청 시 카테고리 ID',
category_name_snapshot VARCHAR(50) NOT NULL COMMENT '신청 시 카테고리명 스냅샷',
sale_price_can INT NOT NULL COMMENT '신청 시 결제 금액 스냅샷',
can_usage_id BIGINT NOT NULL COMMENT '캔 사용내역 ID',
sender_terms_agreed TINYINT(1) NOT NULL COMMENT '팬 이용약관 동의 여부',
sender_privacy_agreed TINYINT(1) NOT NULL COMMENT '팬 개인정보 동의 여부',
sender_terms_agreed_at TIMESTAMP NOT NULL COMMENT '팬 이용약관 동의 시각',
sender_privacy_agreed_at TIMESTAMP NOT NULL COMMENT '팬 개인정보 동의 시각',
recipient_terms_agreed TINYINT(1) NOT NULL COMMENT '크리에이터 이용약관 동의 여부',
recipient_privacy_agreed TINYINT(1) NOT NULL COMMENT '크리에이터 개인정보 동의 여부',
recipient_terms_agreed_at TIMESTAMP NULL COMMENT '크리에이터 이용약관 동의 시각',
recipient_privacy_agreed_at TIMESTAMP NULL COMMENT '크리에이터 개인정보 동의 시각',
damage_waiver_agreed TINYINT(1) NOT NULL COMMENT '파손면책 동의 여부',
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
PRIMARY KEY (id),
UNIQUE KEY uk_gift_application_no (application_no),
CONSTRAINT fk_gift_sender_member FOREIGN KEY (sender_member_id) REFERENCES member (id),
CONSTRAINT fk_gift_recipient_member FOREIGN KEY (recipient_member_id) REFERENCES member (id),
CONSTRAINT fk_gift_category FOREIGN KEY (category_id) REFERENCES gift_category (id),
CONSTRAINT fk_gift_can_usage FOREIGN KEY (can_usage_id) REFERENCES use_can (id)
) COMMENT='선물 신청';
CREATE TABLE gift_delivery (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '내부 기본키',
gift_id BIGINT NOT NULL COMMENT '선물 ID',
sender_name VARCHAR(50) NOT NULL COMMENT '발신자 이름',
sender_phone_number VARCHAR(30) NOT NULL COMMENT '발신자 휴대폰 번호',
sender_zip_code VARCHAR(20) NOT NULL COMMENT '발신자 우편번호',
sender_address VARCHAR(255) NOT NULL COMMENT '발신자 주소',
sender_address_detail VARCHAR(255) NULL COMMENT '발신자 상세주소',
recipient_name VARCHAR(50) NULL COMMENT '수신자 이름',
recipient_phone_number VARCHAR(30) NULL COMMENT '수신자 휴대폰 번호',
recipient_zip_code VARCHAR(20) NULL COMMENT '수신자 우편번호',
recipient_address VARCHAR(255) NULL COMMENT '수신자 주소',
recipient_address_detail VARCHAR(255) NULL COMMENT '수신자 상세주소',
courier_company_name VARCHAR(50) NULL COMMENT '택배사 한글 표시명',
tracking_number VARCHAR(100) NULL COMMENT '운송장 번호',
tracking_deadline_at TIMESTAMP NOT NULL COMMENT '운송장 등록 기한',
recipient_address_deadline_at TIMESTAMP NULL COMMENT '수신자 배송지 입력 기한',
tracking_deadline_reminder_sent_at TIMESTAMP NULL COMMENT '운송장 등록 기한 안내 발송 시각',
recipient_address_deadline_reminder_sent_at TIMESTAMP NULL COMMENT '수신자 배송지 입력 기한 안내 발송 시각',
tracking_registered_at TIMESTAMP NULL COMMENT '운송장 등록 시각',
arrived_at_mailbox_at TIMESTAMP NULL COMMENT '사서함 도착 시각',
inspection_completed_at TIMESTAMP NULL COMMENT '검수완료 시각',
delivered_at TIMESTAMP NULL COMMENT '전달완료 시각',
canceled_at TIMESTAMP NULL COMMENT '취소 시각',
undeliverable_at TIMESTAMP NULL COMMENT '전달불가 시각',
undeliverable_reason VARCHAR(255) NULL COMMENT '전달불가 사유',
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
PRIMARY KEY (id),
UNIQUE KEY uk_gift_delivery_gift_id (gift_id),
CONSTRAINT fk_gift_delivery_gift FOREIGN KEY (gift_id) REFERENCES gift (id)
) COMMENT='선물 배송 정보';
CREATE TABLE gift_size_price (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '내부 기본키',
size_code VARCHAR(20) NOT NULL COMMENT '선물 사이즈 코드',
base_price_can INT NOT NULL COMMENT '기본 금액',
sale_price_can INT NOT NULL COMMENT '결제 금액',
is_active TINYINT(1) NOT NULL COMMENT '활성 여부',
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
PRIMARY KEY (id),
UNIQUE KEY uk_gift_size_price_size_code (size_code)
) COMMENT='선물 사이즈별 가격';
CREATE TABLE gift_review (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '내부 기본키',
gift_id BIGINT NOT NULL COMMENT '선물 ID',
sender_member_id BIGINT NOT NULL COMMENT '리뷰 작성 팬 회원번호',
rating INT NOT NULL COMMENT '별점',
keywords TEXT NULL COMMENT '리뷰 키워드 목록',
comment VARCHAR(255) NULL COMMENT '추가의견',
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
PRIMARY KEY (id),
UNIQUE KEY uk_gift_review_gift_id (gift_id),
CONSTRAINT fk_gift_review_gift FOREIGN KEY (gift_id) REFERENCES gift (id),
CONSTRAINT fk_gift_review_sender_member FOREIGN KEY (sender_member_id) REFERENCES member (id)
) COMMENT='선물 리뷰';
CREATE TABLE gift_application_no_sequence (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '내부 기본키',
category_id BIGINT NOT NULL COMMENT '채번 기준 카테고리 ID',
sequence_date VARCHAR(6) NOT NULL COMMENT '채번 기준일 yyMMdd',
last_sequence INT NOT NULL COMMENT '마지막 일련번호',
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
PRIMARY KEY (id),
UNIQUE KEY uk_gift_application_no_sequence_category_date (category_id, sequence_date),
CONSTRAINT fk_gift_application_no_sequence_category FOREIGN KEY (category_id) REFERENCES gift_category (id)
) COMMENT='선물 신청번호 날짜별 채번';
ALTER TABLE gift_category DROP INDEX uk_gift_category_receipt_code;
-- 2026-10-23: 전달 완료 후 배송정보 삭제를 위한 발신자 컬럼 NULL 허용.
-- 기존 DB에는 아래 ALTER TABLE 문만 적용하며, 이 파일 전체를 재실행하지 않는다.
ALTER TABLE gift_delivery
MODIFY COLUMN sender_name VARCHAR(50) NULL COMMENT '발신자 이름',
MODIFY COLUMN sender_phone_number VARCHAR(30) NULL COMMENT '발신자 휴대폰 번호',
MODIFY COLUMN sender_zip_code VARCHAR(20) NULL COMMENT '발신자 우편번호',
MODIFY COLUMN sender_address VARCHAR(255) NULL COMMENT '발신자 주소';
@@ -1,263 +0,0 @@
# 선물 보내기 페이지 생성 프롬프트
이 문서는 Android/iOS 앱의 `선물 보내기` 페이지를 생성하거나 기존 생성 UI에 API 연동을 붙일 때 사용하는 프롬프트다.
참고 Figma:
- 빈 입력 상태: `2481:18904`
- 입력 완료 및 CTA 활성화 상태: `2481:18957`
전제:
- 크리에이터 닉네임과 `memberId`를 받아 `선물 보내기` 화면으로 이동하는 흐름은 이미 생성되어 있다.
- 새 진입 흐름을 만들지 않는다.
- Figma에 있는 UI 구조와 문구를 유지한다.
- Android/iOS 각각의 기존 디자인 시스템, 컴포넌트, API client, 상태 관리, toast/dialog, navigation 패턴을 재사용한다.
- 모든 API 응답은 공통 envelope를 사용하며 실제 payload는 `data`에 있다.
- request/response 설명은 모바일 공통 JSON 기준이다.
---
## 모바일 앱 구현 프롬프트
```text
Android/iOS 앱의 선물 보내기 페이지를 Figma 기준으로 생성하고 API 연동을 구현해줘.
중요 전제:
- 크리에이터 닉네임과 memberId를 받아 이 화면으로 이동하는 기능은 이미 구현되어 있다.
- 이 작업에서는 이동 경로를 새로 만들지 말고, 전달받은 값만 화면과 API request에 연결한다.
- 전달받은 크리에이터 닉네임은 `받는 크리에이터` 영역에 표시한다.
- 전달받은 memberId는 선물 신청 API의 `recipientMemberId`로 보낸다.
Figma 참고 상태:
- 빈 입력 상태: node `2481:18904`
- 입력 완료 및 최하단 CTA 활성화 상태: node `2481:18957`
화면 구조:
1. 상단
- 타이틀: `선물 보내기`
- 뒤로가기 버튼은 기존 앱 패턴을 사용한다.
2. 안내 배너
- 제목: `선물 보내기 베타 서비스 안내`
- 본문: `베타 기간 동안은 일부 기능만 제공됩니다. 크리에이터에게 마음을 잘 전할 수 있도록 더 넓어진 선물 보내기로 곧 다시 만나요!`
3. 받는 크리에이터
- 이전 화면에서 전달받은 크리에이터 닉네임을 표시한다.
- Figma의 프로필 row 형태를 유지한다.
- memberId는 화면 표시용이 아니라 API request용으로만 사용한다.
4. 선물 사이즈
- 화면 진입 시 `GET /api/v2/gifts/form-options`를 호출해 `sizes`를 가져온다.
- 조회된 `sizes`를 사이즈 카드 목록에 바인딩한다.
- 카드에는 `name`, 사이즈 설명, 캔 가격을 표시한다.
- 서버 응답에는 사이즈 설명 필드가 없으므로 설명 문구는 앱에서 코드별로 매핑한다.
- `SMALL`: `세 변의 합 100cm 이하 · 5kg 이하`
- `MEDIUM`, `LARGE`: 정책 문구가 앱에 이미 있으면 기존 문구를 사용하고, 없으면 이름과 가격만 표시한다.
- 가격은 `salePriceCan`을 표시하고 submit 금액도 `salePriceCan`을 사용한다.
- `basePriceCan`과 `salePriceCan`이 다르면 기존 앱 할인/정가 표시 패턴이 있을 때만 정가를 함께 보여준다.
- 기본 선택은 서버가 내려준 첫 번째 사이즈로 둔다.
5. 카테고리
- 화면 진입 시 같은 `GET /api/v2/gifts/form-options` 응답의 `categories`를 사용한다.
- Figma의 select field를 유지한다.
- 빈 상태 문구: `카테고리 선택`
- 선택 후에는 선택한 카테고리 `name`을 표시한다.
- 카테고리 선택 UI는 기존 Android/iOS 앱 패턴에 맞는 bottom sheet, picker, dialog 중 이미 쓰는 방식을 사용한다.
- `requiresDamageWaiver=true`인 카테고리를 선택한 경우에만 카테고리 아래에 파손 면책 동의 row를 표시한다.
- 파손 면책 동의 문구: `파손 및 분실 면책 사항에 동의합니다. (필수)`
- `requiresDamageWaiver=false` 카테고리를 선택하면 파손 면책 동의 row를 숨기고 `damageWaiverAgreed=false`로 초기화한다.
6. 보내는 사람
- 이름 input → `senderName`
- 휴대폰 번호 input → `senderPhoneNumber`
- 우편번호 input → `senderZipCode`
- 주소 input → `senderAddress`
- 상세 주소 input → `senderAddressDetail`
- `우편번호 검색` 버튼은 기존 주소 검색 기능과 연결한다.
- 주소 검색 결과로 우편번호와 기본 주소를 채운다.
- 기본 주소는 사용자가 직접 수정하지 못하게 하는 기존 패턴이 있으면 그 패턴을 따른다.
7. 이용 약관 동의
- Figma의 발송 규정 요약 박스와 체크박스 2개를 유지한다.
- `소다라이브 크리에이터 상품 전달 이용약관에 동의합니다. (필수)` → `senderTermsAgreed`
- `상품 전달을 위한 개인정보 수집·이용에 동의합니다. (필수)` → `senderPrivacyAgreed`
8. 하단 CTA
- 빈 상태 또는 필수값 누락 상태는 Figma 빈 상태처럼 비활성 버튼을 표시한다.
- 활성 조건을 모두 만족하면 Figma 활성 상태처럼 soda 색상 CTA로 바꾼다.
- 활성 CTA 문구는 선택된 사이즈의 `salePriceCan`을 사용해 `{salePriceCan}캔으로 선물 보내기`로 표시한다.
- submit 중에는 중복 탭을 막고 loading 상태를 표시한다.
화면 진입 시 처리:
- 이미 전달받은 `creatorNickname`과 `memberId`를 읽는다.
- 둘 중 하나라도 없으면 기존 앱의 오류 처리 또는 뒤로가기 패턴을 따른다.
- 즉시 `GET /api/v2/gifts/form-options`를 호출한다.
- 로딩 중에는 기존 화면 스켈레톤/로딩 패턴을 사용한다.
- 조회 실패 시 toast/dialog와 재시도 동작을 기존 패턴으로 제공한다.
- `sizes` 또는 `categories`가 비어 있으면 선물 신청을 막고 CTA를 비활성화한다.
CTA 활성 조건:
- `memberId`가 있다.
- 사이즈가 선택되어 있다.
- 카테고리가 선택되어 있다.
- 이름이 입력되어 있다.
- 휴대폰 번호가 입력되어 있다.
- 우편번호가 입력되어 있다.
- 주소가 입력되어 있다.
- 이용약관 동의가 true다.
- 개인정보 수집·이용 동의가 true다.
- 선택한 카테고리의 `requiresDamageWaiver=true`이면 파손 면책 동의가 true다.
검증 실패 처리:
- CTA는 기본적으로 위 조건을 만족할 때만 활성화한다.
- 그래도 submit 시점에 한 번 더 validation 한다.
- 누락된 필드는 기존 앱의 input error, toast, dialog 중 현재 화면 패턴에 맞춰 안내한다.
- validation 실패 시 `POST /api/v2/gifts`를 호출하지 않는다.
폼 옵션 조회 API:
- Method: `GET`
- URL: `/api/v2/gifts/form-options`
- Request: 없음
- Response envelope 예시:
```json
{
"success": true,
"data": {
"sizes": [],
"categories": []
},
"message": ""
}
```
- Response `data` 예시:
```json
{
"sizes": [
{
"sizeCode": "SMALL",
"name": "소형",
"basePriceCan": 100,
"salePriceCan": 80
}
],
"categories": [
{
"categoryId": 1,
"name": "아크릴",
"requiresDamageWaiver": true
}
]
}
```
폼 옵션 필드:
| 필드 | 타입 | 설명 |
|---|---|---|
| `sizes` | array | 선택 가능한 선물 사이즈 목록 |
| `sizes[].sizeCode` | string | 사이즈 코드. `SMALL`, `MEDIUM`, `LARGE` |
| `sizes[].name` | string | 사이즈 표시명 |
| `sizes[].basePriceCan` | number | 기본 가격, 단위는 캔 |
| `sizes[].salePriceCan` | number | 실제 결제 가격, 단위는 캔 |
| `categories` | array | 선택 가능한 활성 카테고리 목록 |
| `categories[].categoryId` | number | 카테고리 ID |
| `categories[].name` | string | 카테고리 표시명 |
| `categories[].requiresDamageWaiver` | boolean | 파손 면책 동의 필요 여부 |
선물 신청 접수 API:
- Method: `POST`
- URL: `/api/v2/gifts`
- 인증: 로그인 회원 필요. 기존 앱 인증 토큰/세션 처리 방식을 사용한다.
- Request body 예시:
```json
{
"recipientMemberId": 100,
"senderName": "김소다",
"senderPhoneNumber": "01000000000",
"senderZipCode": "12345",
"senderAddress": "서울시 강남구 ...",
"senderAddressDetail": "123동 456호",
"sizeCode": "SMALL",
"categoryId": 1,
"senderTermsAgreed": true,
"senderPrivacyAgreed": true,
"damageWaiverAgreed": true
}
```
Request body 필드:
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| `recipientMemberId` | number | Y | 화면 진입 시 전달받은 memberId |
| `senderName` | string | Y | 보내는 사람 이름 |
| `senderPhoneNumber` | string | Y | 보내는 사람 휴대폰 번호 |
| `senderZipCode` | string | Y | 보내는 사람 우편번호 |
| `senderAddress` | string | Y | 보내는 사람 기본 주소 |
| `senderAddressDetail` | string 또는 null | N | 보내는 사람 상세 주소 |
| `sizeCode` | string | Y | 선택한 사이즈 코드 |
| `categoryId` | number | Y | 선택한 카테고리 ID |
| `senderTermsAgreed` | boolean | Y | 이용약관 동의 여부. 반드시 `true` |
| `senderPrivacyAgreed` | boolean | Y | 개인정보 수집·이용 동의 여부. 반드시 `true` |
| `damageWaiverAgreed` | boolean | Y | 파손 면책 동의 여부. 필요한 카테고리에서는 `true`, 필요 없는 카테고리에서는 `false` |
- Response `data` 예시:
```json
{
"applicationNo": "A-1002609300001",
"status": "RECEIVED",
"statusName": "접수 완료",
"priceCan": 80,
"trackingDeadlineAt": "2026-10-02T03:00:00Z"
}
```
Response `data` 필드:
| 필드 | 타입 | 설명 |
|---|---|---|
| `applicationNo` | string | 선물 신청번호 |
| `status` | string | 신청 상태 코드 |
| `statusName` | string | 신청 상태 표시명 |
| `priceCan` | number | 실제 차감된 캔 금액 |
| `trackingDeadlineAt` | string | 운송장 등록 기한. UTC ISO 문자열 |
성공 처리:
- 신청 성공 시 기존 앱의 완료 dialog 또는 완료 화면 패턴을 사용한다.
- 최소 표시값은 `applicationNo`, `statusName`, `priceCan`, `trackingDeadlineAt`이다.
- 성공 이후 이동 CTA가 필요하면 기존 선물함 또는 선물 상세 이동 패턴을 사용한다.
실패 처리:
- 서버 오류 메시지가 있으면 기존 앱 에러 노출 방식으로 표시한다.
- 잔액 부족, 유효하지 않은 카테고리, 파손 면책 미동의, 약관 미동의 등의 오류는 서버 메시지를 우선 사용한다.
- 실패 시 입력값은 유지한다.
테스트/검증:
- 화면 진입 시 `GET /api/v2/gifts/form-options`가 호출되는지 확인한다.
- 전달받은 크리에이터 닉네임이 받는 크리에이터 영역에 표시되는지 확인한다.
- 전달받은 memberId가 `POST /api/v2/gifts`의 `recipientMemberId`로 들어가는지 확인한다.
- 빈 상태에서는 CTA가 비활성화되는지 확인한다.
- 필수 입력과 필수 동의를 모두 완료하면 CTA가 활성화되고 `{salePriceCan}캔으로 선물 보내기`가 표시되는지 확인한다.
- `requiresDamageWaiver=true` 카테고리 선택 시 파손 면책 동의 row가 표시되고 동의 전에는 CTA가 비활성인지 확인한다.
- `requiresDamageWaiver=false` 카테고리 선택 시 파손 면책 동의 row가 숨겨지고 request의 `damageWaiverAgreed`가 false인지 확인한다.
- submit 성공 시 요청 body와 성공 처리 값을 확인한다.
- submit 실패 시 입력값이 유지되고 기존 앱 방식으로 오류가 표시되는지 확인한다.
```
---
## API 요약
| 목적 | Method | URL | Request | Response data |
|---|---|---|---|---|
| 폼 옵션 조회 | GET | `/api/v2/gifts/form-options` | 없음 | 사이즈 목록, 카테고리 목록 |
| 선물 신청 접수 | POST | `/api/v2/gifts` | 선물 신청 JSON body | 신청번호, 상태, 차감 금액, 운송장 등록 기한 |
## Figma 반영 메모
- 빈 상태 Figma는 카테고리 미선택, 보내는 사람 정보 미입력, 약관 미동의, 하단 CTA 비활성 상태다.
- 활성 상태 Figma는 크리에이터 닉네임 표시, 카테고리 선택, 파손 면책 동의 노출, 보내는 사람 정보 입력, 약관 동의, 하단 CTA 활성 상태다.
- Figma의 하단 버튼 텍스트는 캔 금액이 포함된 형태이므로 API의 `salePriceCan`으로 동적으로 표시한다.
- Figma의 select, checkbox, radio, bottom action bar, safe area는 각 플랫폼의 기존 컴포넌트로 대응한다.
@@ -1,596 +0,0 @@
# iOS 선물하기 전체 기능 단일 구현 프롬프트
이 문서는 iOS 앱에서 크리에이터 선물하기 사용자 기능을 한 번에 구현할 때 사용하는 단일 프롬프트다. 기존 분할 문서의 사용자 화면 범위를 합치고, Figma UI 확인 결과와 신청 완료 후 상세 이동 정책을 반영했다.
관리자 화면은 iOS 앱 범위가 아니므로 제외한다.
## 참고 문서
- `docs/20260929_크리에이터_선물하기/prd.md`
- `docs/20260929_크리에이터_선물하기/client-api-summary.md`
- `docs/20260929_크리에이터_선물하기/gift-send-page-prompt.md`
- `docs/20260929_크리에이터_선물하기/gift-list-page-prompt.md`
- `docs/20260929_크리에이터_선물하기/gift-detail-tracking-page-prompt.md`
- `docs/20260929_크리에이터_선물하기/gift-received-detail-page-prompt.md`
## Figma 확인 노드
- 선물 보내기: 빈 입력 `2481:18904`, 입력 완료/CTA 활성 `2481:18957`
- 선물함 리스트: 보낸 내역 있음 `2481:19382`, 보낸 내역 없음 `2520:35587`, 받은 내역 없음 `2531:36283`, 받은 내역 있음 `2531:36194`, 받은 상태별 카드 `2531:36237`
- 보낸 선물 상세/운송장: 등록 전 `2481:19011`, 등록 후 `2481:19152`, 전달 완료 `2481:19320`, 전달 불가 `2481:19456`, 취소 다이얼로그 `2481:19500`, 취소 완료 `2481:19521`, 운송장 입력 전 `2481:19066`, 운송장 입력 완료 `2481:19109`
- 받은 선물 상세/배송지: 배송지 입력 전 `2531:36290`, 배송지 입력 완료 `2531:36399`, 전달 완료 `2531:36330`, 전달 불가 `2531:36422`
Figma 재확인 메모:
- 모든 화면은 iPhone 13 기준 402px 폭, black/dark surface 기반이다.
- 상단 status bar와 nav/top 영역은 고정하고, 본문은 `scroll area`로 분리한다.
- 주요 섹션은 14pt 좌우 여백, 카드/입력/배너는 rounded dark surface, 섹션 사이 divider를 사용한다.
- 선물 보내기 화면은 안내 배너, 받는 크리에이터, 선물 사이즈, 카테고리, 보내는 사람, 약관 동의, 하단 single CTA 구조다.
- 선물함 리스트는 안내 배너와 104pt 높이 카드 리스트 구조다. 실제 구현에서는 Figma에 있는 `신청 내역`, `선물 내역` 섹션 타이틀을 표시하지 않는다.
- 보낸 상세는 상태 hero, 사서함/등록 안내, 선물 정보, 하단 action bar를 중심으로 한다.
- 받은 상세는 상태 hero와 문의 버튼, 선물 정보, 받는 주소 카드 구조를 상태별로 바꾼다.
---
## iOS 구현 프롬프트
```text
iOS 앱의 크리에이터 선물하기 사용자 기능 전체를 Figma와 API 계약 기준으로 구현해줘.
범위:
- 선물 보내기 신청 화면
- 선물함 리스트 화면
- 선물 상세 화면
- 보낸 선물의 운송장 등록 화면
- 보낸 선물의 신청 취소 확인/취소 완료 화면
- 받은 선물의 배송지 입력 UI
- 받은 선물의 배송지 입력 완료/전달 완료/전달 불가 상세 UI
- 푸시/딥링크 진입 시 선물 상세 이동
범위 밖:
- 관리자 화면
- 새 디자인 시스템 생성
- 외부 택배 조회/운송장 실시간 검증
- 약관 본문 제공 API 신규 구현
- 선물 이미지, 첨부파일, 메시지 카드
- 임의 URL 연결
공통 전제:
- iOS 기존 디자인 시스템, 컴포넌트, API client, 인증, 상태 관리, toast/dialog, navigation, loading/error 패턴을 재사용한다.
- Figma visual structure와 문구를 우선 따르되, 데이터 노출과 CTA 조건은 API 계약을 우선한다.
- 모든 API 응답은 공통 envelope를 사용하며 실제 payload는 `response.data` 또는 기존 iOS API client의 data unwrap 결과다.
- 모든 날짜는 UTC ISO 문자열이다. 앱 공통 formatter가 있으면 재사용하고, 상세 필드 날짜는 Figma처럼 `YYYY.MM.DD`로 표시한다.
- 개인정보 노출 경계를 반드시 지킨다. 로그인 회원이 알아야 하는 본인 정보만 표시하고, 상대방의 이름/휴대폰/주소는 표시하지 않는다.
- Figma 기준으로 상단 navigation은 고정하고, navigation 아래 본문만 스크롤한다.
- iOS safe area, keyboard avoidance, bottom action bar는 기존 앱 패턴을 따른다.
- 새 route/deep link가 필요하면 기존 navigation/deep link 등록 방식에 맞춘다.
가장 중요한 이동 정책:
- 선물 보내기 신청 `POST /api/v2/gifts` 성공 시 완료 dialog에서 멈추지 말고, 성공 응답의 `applicationNo`로 선물 상세 페이지로 이동한다.
- 신청 완료 직후 이동 대상은 `GET /api/v2/gifts/{applicationNo}` 기반 상세 페이지다.
- 신청 성공 후 뒤로가기로 입력 폼에 다시 돌아와 중복 신청하지 않도록 기존 iOS navigation 정책에 맞춰 replace 또는 stack 정리를 적용한다.
- 선물함 리스트 item 탭, 푸시 딥링크, 신청 완료 후 이동은 모두 같은 상세 화면으로 들어가고, 상세 API의 `direction`, `trackingRequired`, `recipientAddressRequired`, `status`로 UI를 분기한다.
보낸 사람/받는 사람 상세 차이:
- 같은 `GET /api/v2/gifts/{applicationNo}` 상세 API를 사용하지만 `direction`에 따라 상세 페이지를 다르게 표시한다.
- `direction=SENT`는 보낸 팬 관점이다.
- 받는 크리에이터 닉네임은 `giftInfo.recipientCreatorNickname`으로 표시한다.
- 팬 본인이 신청 시 입력한 발신자 정보 `senderInfo`를 표시할 수 있다.
- 관리자 전역 사서함 `mailbox`가 있으면 `보내실 주소` 또는 `받는 사서함` 섹션에 표시한다.
- 크리에이터가 입력한 배송지 `recipientAddress`는 표시하지 않는다.
- `trackingRequired=true`이면 운송장 등록 CTA를 표시한다.
- `status=RECEIVED`이면 신청 취소 action을 제공할 수 있다.
- `direction=RECEIVED`는 받는 크리에이터 관점이다.
- 보낸 팬 닉네임은 `giftInfo.senderNickname`으로 표시한다.
- 팬이 신청 시 입력한 이름/휴대폰/주소 `senderInfo`는 표시하지 않는다.
- `mailbox`, `giftInfo.applicationNo`, `giftInfo.paidCan`, `giftInfo.tracking`은 표시하지 않는다.
- 크리에이터 본인이 입력한 배송지 `recipientAddress`가 있을 때만 받는 주소 섹션을 표시한다.
- `recipientAddressRequired=true`이면 배송지 입력 UI를 표시한다.
1. 선물 보내기 화면
Figma:
- 빈 입력 상태: `2481:18904`
- 입력 완료/CTA 활성 상태: `2481:18957`
진입 전제:
- 크리에이터 닉네임과 `memberId`를 받아 이 화면으로 이동하는 기존 흐름은 이미 있다.
- 이 작업에서 새 진입 흐름을 만들지 않는다.
- 전달받은 크리에이터 닉네임은 `받는 크리에이터` 영역에 표시한다.
- 전달받은 `memberId`는 `POST /api/v2/gifts`의 `recipientMemberId`로 보낸다.
- 둘 중 하나라도 없으면 기존 앱의 오류 처리 또는 안전한 뒤로가기 패턴을 따른다.
화면 구조:
- 상단 타이틀: `선물 보내기`
- 안내 배너
- 제목: `선물 보내기 베타 서비스 안내`
- 본문: `베타 기간 동안은 일부 기능만 제공됩니다. 크리에이터에게 마음을 잘 전할 수 있도록 더 넓어진 선물 보내기로 곧 다시 만나요!`
- 받는 크리에이터: Figma 프로필 row 형태로 전달받은 닉네임 표시
- 선물 사이즈: `GET /api/v2/gifts/form-options`의 `sizes` 바인딩
- 카테고리: 같은 응답의 `categories` 바인딩
- 보내는 사람 입력: 이름, 휴대폰 번호, 우편번호, 주소, 상세 주소
- 이용 약관 동의: 발송 규정 요약 박스와 체크박스 2개
- 하단 CTA: `{salePriceCan}캔으로 선물 보내기`
폼 옵션 조회:
- 화면 진입 시 `GET /api/v2/gifts/form-options` 호출
- `sizes` 기본 선택은 서버가 내려준 첫 번째 항목
- 가격 표시는 `salePriceCan`을 사용하고 신청 금액도 `salePriceCan`을 사용
- `basePriceCan != salePriceCan`이면 기존 앱 할인/정가 표시 패턴이 있을 때만 정가를 함께 표시
- 사이즈 설명은 API에 없으므로 앱 로컬 매핑 사용
- `SMALL`: `세 변의 합 100cm 이하 · 5kg 이하`
- `MEDIUM`: `세 변의 합 120cm 이하 · 15kg 이하`
- `LARGE`: `세 변의 합 160cm 이하 · 20kg 이하`
- 카테고리 select는 기존 iOS picker/bottom sheet/dialog 패턴 중 앱에서 이미 쓰는 방식을 사용
- `requiresDamageWaiver=true` 카테고리 선택 시에만 파손 면책 동의 row 표시
- `requiresDamageWaiver=false` 선택 시 파손 면책 동의 row를 숨기고 `damageWaiverAgreed=false`로 초기화
입력 필드 매핑:
- 이름 input -> `senderName`
- 휴대폰 번호 input -> `senderPhoneNumber`
- 우편번호 input -> `senderZipCode`
- 주소 input -> `senderAddress`
- 상세 주소 input -> `senderAddressDetail`
- 우편번호 검색은 기존 주소 검색 기능을 재사용한다.
동의 필드:
- `소다라이브 크리에이터 상품 전달 이용약관에 동의합니다. (필수)` -> `senderTermsAgreed`
- `상품 전달을 위한 개인정보 수집·이용에 동의합니다. (필수)` -> `senderPrivacyAgreed`
- `파손 및 분실 면책 사항에 동의합니다. (필수)` -> `damageWaiverAgreed`, 필요한 카테고리에서만 표시/필수
- 각 약관 문구의 `(필수)` 부분은 터치 가능한 링크로 처리한다.
- `(필수)` 터치 시 약관 Notion 웹페이지로 이동한다.
- sender 약관 2개와 recipient 약관 2개는 모두 같은 Notion 페이지로 이동하면 된다.
- Notion 페이지 URL은 실제 구현 시 입력받도록 처리하고, 이 프롬프트에서 임의 URL을 하드코딩하지 않는다.
CTA 활성 조건:
- `memberId` 있음
- 사이즈 선택됨
- 카테고리 선택됨
- 이름, 휴대폰 번호, 우편번호, 주소 입력됨
- 이용약관 동의 true
- 개인정보 동의 true
- 선택 카테고리의 `requiresDamageWaiver=true`이면 파손 면책 동의 true
- submit 중에는 중복 탭 방지와 loading 표시
- validation 실패 시 `POST /api/v2/gifts`를 호출하지 않는다.
선물 신청 API:
- Method: `POST`
- URL: `/api/v2/gifts`
- Request:
```json
{
"recipientMemberId": 100,
"senderName": "김소다",
"senderPhoneNumber": "01000000000",
"senderZipCode": "12345",
"senderAddress": "서울시 강남구 ...",
"senderAddressDetail": "123동 456호",
"sizeCode": "SMALL",
"categoryId": 1,
"senderTermsAgreed": true,
"senderPrivacyAgreed": true,
"damageWaiverAgreed": true
}
```
- Response data:
```json
{
"applicationNo": "A-1002609300001",
"status": "RECEIVED",
"statusName": "접수 완료",
"priceCan": 80,
"trackingDeadlineAt": "2026-10-02T03:00:00Z"
}
```
- 성공 시 `applicationNo`로 선물 상세 페이지로 이동한다.
- 실패 시 서버 메시지를 기존 앱 오류 노출 방식으로 표시하고 입력값은 유지한다.
2. 선물함 리스트 화면
Figma:
- 보낸 내역 있음: `2481:19382`
- 보낸 내역 없음: `2520:35587`
- 받은 내역 없음: `2531:36283`
- 받은 내역 있음: `2531:36194`
- 받은 상태별 카드: `2531:36237`
공통 요구사항:
- 상단 타이틀: `선물함`
- 상단 뒤로가기 navigation은 고정
- navigation 아래 콘텐츠만 스크롤
- Figma에 보이는 `신청 내역`, `선물 내역` 섹션 타이틀은 표시하지 않는다.
- 리스트는 서버 응답 순서를 우선 사용한다. 현재 API만으로 취소일 기준 재정렬을 임의 구현하지 않는다.
- item 탭 시 `applicationNo`를 전달해 선물 상세 페이지로 이동한다.
API:
- Method: `GET`
- URL: `/api/v2/gifts?type=ALL&page=0&size=20`
- 이 화면에서는 `SENT`, `RECEIVED`를 따로 호출하지 않고 `type=ALL`을 사용한다.
- `items[].direction`으로 보낸/받은 카드 UI를 결정한다.
- `hasNext=true`이면 스크롤 하단에서 다음 page를 추가 조회한다.
- 기존 앱에 pull-to-refresh가 있으면 page 0부터 다시 조회한다.
Response data 예시:
```json
{
"totalCount": 2,
"items": [
{
"applicationNo": "A-1002609300001",
"direction": "SENT",
"status": "RECEIVED",
"statusName": "접수 완료",
"priceCan": 80,
"categoryName": "아크릴/스탠드",
"sizeName": "소형",
"counterpartMemberId": 200,
"counterpartNickname": "달빛수집가",
"counterpartProfileImageUrl": "https://example.com/profile.png",
"recipientAddressRegistered": false,
"recipientAddressDeadlineAt": null,
"canceledAt": null,
"createdAt": "2026-09-18T03:00:00Z"
}
],
"page": 0,
"size": 20,
"hasNext": false
}
```
보낸 선물 카드 (`direction=SENT`):
- 상대방은 선물을 받는 크리에이터다.
- 상단 안내 배너 표시
- 제목: `사서함을 통해 안전하게 전달됩니다`
- 본문: `크리에이터 및 팬의 주소는 공개되지 않습니다. 선물은 소다라이브 사서함에 도착한 뒤 크리에이터에게 전달됩니다.`
- 카드에는 `statusName`, 날짜 라벨, 크리에이터 프로필/닉네임, `sizeName · categoryName`, chevron 표시
- 날짜 라벨은 기본 `{createdAt} 신청`; 취소일 필드가 없으면 임의 취소일 계산 금지
- `status=CANCELED`이고 `canceledAt`이 있으면 날짜 라벨은 `{canceledAt} 취소`로 표시한다.
- 보낸 선물 empty는 안내 배너만 표시하고 별도 empty title/body를 추가하지 않는다.
받은 선물 카드 (`direction=RECEIVED`):
- 상대방은 선물을 보낸 팬이다.
- 받은 선물 empty
- 제목: `전달 예정인 선물이 없어요`
- 본문: `베타 기간에는 팬이 선물을 보내는 기능만 제공돼요. 더 다양해진 선물 기능으로 곧 다시 만나요!`
- 버튼: `의견 남기기`, 기존 문의/피드백 이동 패턴 사용
- 받은 선물 있음 상단 안내 배너
- 제목: `배송지 입력 기간 안내`
- 본문: `알림을 받은 날부터 7일 이내에 배송지를 입력해 주세요. 기한 내 입력하지 않으면 선물이 반송됩니다.`
- 배송지 입력이 필요한 선물이 있으면 리스트 상단에 파란 안내 배너 표시
- 제목: `팬이 보낸 선물이 있어요!`
- 본문: `선물이 늦지 않게 전달될 수 있도록 배송지를 입력해 주세요.`
- 보조 문구는 `recipientAddressRegistered=false`이고 `recipientAddressDeadlineAt`이 있으면 남은 일수로 표시한다.
- 배송지가 이미 입력되어 `recipientAddressRegistered=true`이면 `recipientAddressDeadlineAt`은 null로 온다.
- 배너 탭 시 배송지 입력이 필요한 첫 번째 선물 상세로 이동
- 카드에는 팬 프로필/닉네임, `{createdAt} 신청`, 상태 메인/서브 문구, chevron 표시
- 하단 `문의하기` 버튼은 기존 앱 정책에 맞춰 고정 또는 스크롤 내부 버튼으로 둔다.
상태 표시 매핑:
- 보낸 선물 카드
- `RECEIVED`: `운송장 등록 필요`
- `TRACKING_REGISTERED`: `발송 확인`
- `ARRIVED_AT_MAILBOX`: `사서함 도착`
- `INSPECTION_COMPLETED`: `선물 검수 완료`
- `DELIVERED`: `전달 완료`
- `UNDELIVERABLE`: `전달 불가`
- `CANCELED`: `신청 취소`
- 받은 선물 카드
- `TRACKING_REGISTERED`: main `배송지 입력 필요`, sub `전달 예정`
- `ARRIVED_AT_MAILBOX`: main `선물 검수`, sub `선물 확인 중`
- `INSPECTION_COMPLETED`: main `선물 검수 완료`, sub `배송 중`
- `DELIVERED`: main `전달 완료`, sub 없음
- `UNDELIVERABLE`: main `전달 불가`, sub 없음
3. 공통 선물 상세 화면
API:
- Method: `GET`
- URL: `/api/v2/gifts/{applicationNo}`
- 리스트 item 탭, 신청 완료 후 이동, 푸시 딥링크 진입 모두 이 API로 상세를 조회한다.
Response data 핵심 필드:
```json
{
"applicationNo": "A-1002609300001",
"direction": "SENT",
"status": "RECEIVED",
"statusName": "접수 완료",
"giftInfo": {
"recipientCreatorNickname": "달빛수집가",
"senderNickname": null,
"sizeName": "소형",
"categoryName": "잡화",
"applicationNo": "A-1002609300001",
"paidCan": 100,
"tracking": null,
"shippingRequestedAt": null
},
"senderInfo": {
"name": "김소다",
"phoneNumber": "01012345678",
"address": "(04030) 서울특별시 마포구 양화로 000, 3층"
},
"recipientAddress": null,
"mailbox": {
"name": "소다라이브 사서함",
"address": "(06174) 서울특별시 강남구 테헤란로108길 8, 유민빌딩 4층",
"phoneNumber": "02-2055-1477"
},
"trackingRequired": true,
"recipientAddressRequired": false,
"recipientAddressDeadlineAt": null,
"delivery": {
"canceledAt": null,
"undeliverableAt": null,
"undeliverableReason": null
},
"statusTimeline": []
}
```
진입 처리:
- 화면 진입 시 상세 API 호출
- 로딩 중에는 기존 상세 로딩/스켈레톤 패턴 사용
- 실패 시 기존 toast/dialog와 재시도 패턴 사용
- `direction`이 현재 화면 분기와 맞지 않아도 별도 화면을 만들지 말고 같은 상세 화면 안에서 `direction` 기준으로 렌더링한다.
진행 상태 progress:
- Figma의 진행 단계가 4단계처럼 보여도 4단계로 하드코딩하지 않는다.
- API `statusTimeline`의 정상 진행 5개 상태를 이 순서로 표시한다.
1. `RECEIVED`: `신청 접수`
2. `TRACKING_REGISTERED`: `발송 확인`
3. `ARRIVED_AT_MAILBOX`: `사서함 도착`
4. `INSPECTION_COMPLETED`: `검수 완료`
5. `DELIVERED`: `전달 완료`
- `occurredAt`이 있으면 완료 색상과 `MM.DD` 표시
- `occurredAt=null`이면 비활성 색상, 날짜 미표시
- `UNDELIVERABLE`, `CANCELED`는 progress step으로 추가하지 않는다.
4. 보낸 선물 상세와 운송장 등록
Figma:
- 상세 운송장 등록 전 `2481:19011`
- 상세 운송장 등록 후 `2481:19152`
- 상세 전달 완료 `2481:19320`
- 전달 불가 `2481:19456`
- 취소 다이얼로그 `2481:19500`
- 취소 완료 `2481:19521`
- 운송장 등록 입력 전 `2481:19066`
- 운송장 등록 입력 완료 `2481:19109`
적용 조건:
- `direction=SENT`
상단 타이틀:
- 일반 상세: `신청 상세`
- 취소 완료 페이지: `취소 완료`
- 운송장 등록: `운송장 등록`
보낸 상세 hero 문구:
- `RECEIVED`: title `선물 신청 완료!`, body `선물이 정상적으로 접수되었어요!`
- `TRACKING_REGISTERED`: chip `발송 확인`, title `사서함으로 이동 중이에요`
- `ARRIVED_AT_MAILBOX`: chip `사서함 도착`, title `선물이 사서함에 도착했어요`
- `INSPECTION_COMPLETED`: chip `검수 완료`, title `선물 검수를 완료했어요`
- `DELIVERED`: chip `전달 완료`, title `크리에이터에게 선물을 전달했어요`
- `UNDELIVERABLE`: chip `전달 불가`, title `전달할 수 없는 품목입니다`, body `보내주신 선물은 SODALIVE 선물 정책에 따라 크리에이터에게 전달할 수 없는 품목으로 확인되었습니다.`
- `CANCELED`: 일반 상세 대신 취소 완료 UI 표시
보낸 상세 섹션:
- 선물 정보는 항상 표시
- 크리에이터: `giftInfo.recipientCreatorNickname`
- 사이즈: `giftInfo.sizeName`
- 카테고리: `giftInfo.categoryName`
- 신청번호: `applicationNo` 또는 `giftInfo.applicationNo`
- 캔: `giftInfo.paidCan`이 null이 아닐 때 표시
- 운송장: `giftInfo.tracking`이 null이 아닐 때 표시
- 검수일/전달 완료일은 `statusTimeline`에서 찾는다.
- `senderInfo`가 있으면 보내는 사람 섹션 표시
- `mailbox`가 있으면 보내실 주소/받는 사서함 섹션 표시
- `delivery.undeliverableReason`이 있으면 사유 섹션 표시
- `recipientAddress`는 보낸 팬 상세에 표시하지 않는다.
보낸 상세 action:
- `trackingRequired=true`이면 주요 CTA `운송장 작성하기` 표시, 운송장 등록 화면으로 이동
- `direction=SENT && status=RECEIVED`이면 보조 action `신청 취소` 표시 가능
- `status=DELIVERED && direction=SENT`이면 기존 리뷰 작성 화면/플로우가 있으면 `리뷰 남기기` 연결
- `문의하기`, `선물 정책 확인`은 기존 이동 경로가 있으면 연결하고, 없으면 숨기거나 기존 앱 정책에 맞춰 처리
신청 취소:
- `신청 취소` 탭 시 즉시 API 호출 금지, 기존 `v2 dialog` 확인 팝업 표시
- 제목: `신청 취소`
- 본문:
- `{크리에이터}에게 보내는 선물을 취소할까요?`
- `선물 보내기 규정에 따라 선물 취소 및 사용한 캔이 모두 환불됩니다.`
- 왼쪽 action: `나가기`, dialog만 닫음
- 오른쪽 destructive action: `취소하기`, `POST /api/v2/gifts/{applicationNo}/cancel` 호출
- 실패 시 dialog를 닫지 말고 기존 에러 패턴 표시
- 성공 시 취소 완료 페이지로 replace navigation
취소 완료 페이지:
- 상세 API 응답이 `status=CANCELED`인 경우에도 표시
- hero title: `선물 신청이 취소되었어요`
- hero body: `{크리에이터}에게 보내는 선물 신청({applicationNo})이 취소되었습니다. 취소한 신청은 되돌릴 수 없으며, 다시 보내려면 새로 신청해 주세요.`
- 취소 상세: 크리에이터, 사이즈, 카테고리, 신청번호, 신청일, 취소일, 환불 캔
- 뒤로가기는 취소 전 상세/등록 화면으로 돌아가지 않게 한다.
운송장 등록 화면:
- 상세에서 `trackingRequired=true`일 때만 진입
- 진입 시 상세 API를 다시 조회
- 조회 결과 `trackingRequired=false`이면 기존 오류 처리 후 상세로 복귀
- 신청 건 요약 카드: `applicationNo`, 크리에이터 닉네임, `sizeName · categoryName · 신청일`
- 보내실 주소: `mailbox` 사용. `mailbox=null`이면 등록을 막고 `받을 주소가 등록되어 있지 않습니다.` 오류 표시
- 운송장 정보: 택배사 select, 운송장 번호 input
- 등록 안내: Figma 안내 문구 유지
- 하단 action bar: 왼쪽 `신청 취소`, 오른쪽 `등록 완료`
택배사 로컬 상수:
```swift
let giftCourierCompanyNames = [
"CJ대한통운",
"우체국택배",
"GS25 편의점택배",
"CU 편의점택배",
"한진택배",
"롯데택배",
"로젠택배",
"경동택배",
"대신택배",
"일양로지스",
"천일택배",
"합동택배",
"건영택배",
"농협택배"
]
```
- 이미 앱 공통 택배사 상수가 있으면 그것을 우선 사용
- API에는 선택한 한글 표시명을 그대로 `courierCompanyName`으로 보낸다.
운송장 등록 CTA 활성 조건:
- 택배사 선택됨
- 운송장 번호가 공백이 아님
- submit 중 중복 탭 방지
운송장 등록 API:
- Method: `POST`
- URL: `/api/v2/gifts/{applicationNo}/tracking`
- Request:
```json
{
"courierCompanyName": "한진택배",
"trackingNumber": "123456789012"
}
```
- 성공 시 성공 toast 표시 후 상세 페이지로 돌아가거나 replace navigation으로 상세를 다시 열고, 상세 API를 재조회해 `TRACKING_REGISTERED` 상태를 표시한다.
5. 받은 선물 상세와 배송지 입력
Figma:
- 배송지 입력 전 `2531:36290`
- 배송지 입력 완료 `2531:36399`
- 전달 완료 `2531:36330`
- 전달 불가 `2531:36422`
적용 조건:
- `direction=RECEIVED`
받은 상세 개인정보 규칙:
- `senderInfo`, `mailbox`, `giftInfo.applicationNo`, `giftInfo.paidCan`, `giftInfo.tracking`은 표시하지 않는다.
- `recipientAddress=null`이면 받는 주소 섹션 전체를 숨긴다. 빈 섹션, skeleton, `-` 값도 표시하지 않는다.
- 전달 불가 화면에서는 `recipientAddress`가 응답에 있어도 받는 주소 섹션을 표시하지 않는다.
배송지 입력 전 UI:
- 적용 조건: `direction=RECEIVED && recipientAddressRequired=true`
- 상단 타이틀: `선물 받기`
- 개인정보 이용 안내 배너
- 제목: `개인정보 이용 안내`
- 본문: `크리에이터 및 팬의 주소는 공개되지 않습니다. 입력한 배송지는 선물 전달 및 필요한 사고 처리에서 사용되며, 전달 완료 후 파기됩니다.`
- 전달 예정 선물 섹션
- 발송인: `giftInfo.senderNickname`
- 사이즈: `giftInfo.sizeName`
- 카테고리: `giftInfo.categoryName`
- 배송지 입력 섹션
- 이름 `recipientName`
- 휴대폰 번호 `recipientPhoneNumber`
- 우편번호 `recipientZipCode`
- 주소 `recipientAddress`
- 상세 주소 `recipientAddressDetail`
- 우편번호 검색은 기존 앱 주소 검색/Kakao 우편번호 래퍼를 재사용
- 이용 약관 동의
- `소다라이브 크리에이터 상품 전달 이용약관 및 전달 가능 제한 품목을 확인하고 동의합니다.(필수)` -> `recipientTermsAgreed`
- `상품 전달을 위해 수령인 성명·연락처·주소 등 필요한 개인정보를 일시적으로 수집·이용하는 것에 동의합니다.(필수)` -> `recipientPrivacyAgreed`
- 각 약관 문구의 `(필수)` 부분은 터치 가능한 링크로 처리한다.
- `(필수)` 터치 시 약관 Notion 웹페이지로 이동한다.
- sender 약관 2개와 recipient 약관 2개는 모두 같은 Notion 페이지로 이동하면 된다.
- Notion 페이지 URL은 실제 구현 시 입력받도록 처리하고, 이 프롬프트에서 임의 URL을 하드코딩하지 않는다.
- 하단 CTA: `선물 받기`
- CTA 활성 조건: 이름, 휴대폰, 우편번호, 주소 입력됨 + 약관 2개 동의됨
배송지 입력 API:
- Method: `POST`
- URL: `/api/v2/gifts/{applicationNo}/recipient-address`
- Request:
```json
{
"recipientName": "크리에이터이름",
"recipientPhoneNumber": "01012345678",
"recipientZipCode": "04030",
"recipientAddress": "서울특별시 마포구 양화로 000",
"recipientAddressDetail": "3층",
"recipientTermsAgreed": true,
"recipientPrivacyAgreed": true
}
```
- 성공 시 성공 toast 표시 후 상세 API를 다시 조회하거나 replace navigation으로 상세를 다시 열어 배송지 입력 완료 UI를 표시한다.
- 실패 시 기존 form error/toast/dialog 패턴을 따르고 입력값은 유지한다.
배송지 입력 완료 상세:
- 적용 조건: `direction=RECEIVED && recipientAddressRequired=false && status`가 `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED` 중 하나이며 `recipientAddress`가 있음
- 상단 타이틀: `선물 상세`
- hero title: `배송지 입력 완료!`
- hero body: `빠른 시일 내로 선물을 전달 드릴게요.`
- `문의하기` 버튼은 기존 카카오 채널 문의로 연결
- 선물 정보: 발송인, 사이즈, 카테고리, 배송 신청일
- 받는 주소: `recipientAddress.name`, `recipientAddress.phoneNumber`, `recipientAddress.address`
전달 완료 상세:
- 적용 조건: `direction=RECEIVED && status=DELIVERED`
- hero title: `선물 전달 완료!`
- hero body: `팬이 보낸 선물이 도착했어요. 선물이 도착하지 않은 경우, 문의해 주세요.`
- 선물 정보: 발송인, 사이즈, 카테고리, 배송 신청일, 배송 완료일
- 받는 주소가 있으면 표시하고 보조 문구 `배송 완료 3일 후 해당 정보는 사라져요` 표시
전달 불가 상세:
- 적용 조건: `direction=RECEIVED && status=UNDELIVERABLE`
- chip: `전달 불가`
- hero title: `전달할 수 없는 품목입니다`
- hero body: `해당 선물은 SODALIVE 선물 정책에 따라 크리에이터에게 전달할 수 없는 품목으로 확인되었습니다.`
- `문의하기`: 기존 카카오 채널 문의로 연결
- `선물 정책 확인`: 실제 외부 URL을 임의 연결하지 않는다. 기존 앱 정책상 no-op 금지이면 `준비 중입니다.` toast만 표시
- 사유 섹션
- 제목: `delivery.undeliverableReason`이 있으면 그 값, 없으면 `전달 불가`
- 안내 문구: `해당 선물은 정책에 따라 폐기되며 반송되지 않습니다.`
- 배송지 입력 UI는 표시하지 않는다.
6. 푸시/딥링크
- 선물 푸시 딥링크는 `deepLinkValue=GIFT_DETAIL`, `deepLinkId=applicationNo`를 사용한다.
- 딥링크 진입 시 바로 특정 보낸/받은 화면을 결정하지 말고, `GET /api/v2/gifts/{applicationNo}`를 호출한 뒤 응답의 `direction`, `trackingRequired`, `recipientAddressRequired`, `status`로 상세 UI를 결정한다.
- 권한 오류 또는 미존재 오류는 기존 앱 딥링크 오류 처리 패턴을 따른다.
7. API 요약
- `GET /api/v2/gifts/form-options`: 선물 신청 폼 옵션 조회
- `POST /api/v2/gifts`: 선물 신청 접수
- `GET /api/v2/gifts?type=ALL&page=0&size=20`: 선물함 리스트 조회
- `GET /api/v2/gifts/{applicationNo}`: 선물 상세 조회
- `POST /api/v2/gifts/{applicationNo}/cancel`: 보낸 선물 신청 취소
- `POST /api/v2/gifts/{applicationNo}/tracking`: 보낸 선물 운송장 등록
- `POST /api/v2/gifts/{applicationNo}/recipient-address`: 받은 선물 배송지 입력
- `POST /api/v2/gifts/{applicationNo}/review`: 전달 완료 후 팬 리뷰 작성, 기존 리뷰 플로우가 있을 때 연결
8. 검증 체크리스트
- 선물 보내기 진입 시 전달받은 크리에이터 닉네임과 `memberId`가 각각 화면/API에 연결되는지 확인한다.
- 화면 진입 시 `GET /api/v2/gifts/form-options`가 호출되는지 확인한다.
- 필수 입력/동의가 누락되면 신청 API를 호출하지 않는지 확인한다.
- `requiresDamageWaiver=true` 카테고리에서만 파손 면책 동의가 표시되고 필수인지 확인한다.
- 선물 신청 성공 후 `applicationNo`로 상세 페이지로 이동하는지 확인한다.
- 신청 완료 후 뒤로가기로 입력 폼에 돌아와 중복 신청하지 않는지 확인한다.
- 선물함 리스트는 `type=ALL`로 한 번 조회하고 `direction`으로 카드 UI를 나누는지 확인한다.
- Figma의 `신청 내역`, `선물 내역` 섹션 타이틀이 실제 화면에 노출되지 않는지 확인한다.
- 리스트 item 탭, 푸시 딥링크, 신청 완료 이동이 모두 같은 상세 조회 플로우를 사용하는지 확인한다.
- `direction=SENT` 상세에서 팬 본인 발신자 정보와 사서함만 표시하고, 크리에이터 배송지는 표시하지 않는지 확인한다.
- `direction=RECEIVED` 상세에서 팬 닉네임만 표시하고 팬의 이름/휴대폰/주소는 표시하지 않는지 확인한다.
- `direction=RECEIVED` 상세에서 `mailbox`, `giftInfo.paidCan`, `giftInfo.tracking`이 표시되지 않는지 확인한다.
- 상세 progress가 `statusTimeline` 5단계를 사용하고 Figma처럼 4단계로 하드코딩되지 않았는지 확인한다.
- `trackingRequired=true`일 때만 운송장 등록 CTA가 표시되는지 확인한다.
- 운송장 등록 성공 후 상세를 재조회해 `TRACKING_REGISTERED` 상태를 표시하는지 확인한다.
- 신청 취소는 확인 dialog 이후에만 API를 호출하고, 성공 시 취소 완료 페이지로 replace 되는지 확인한다.
- `recipientAddressRequired=true`일 때 받은 선물 배송지 입력 UI가 표시되는지 확인한다.
- 배송지 입력 성공 후 상세를 재조회해 배송지 입력 완료 UI가 표시되는지 확인한다.
- `recipientAddress=null`이면 받는 주소 섹션을 통째로 숨기는지 확인한다.
- `status=UNDELIVERABLE`이면 전달 불가 UI와 사유/폐기 안내를 표시하고 배송지 입력 UI를 숨기는지 확인한다.
- 모든 날짜는 UTC ISO 문자열을 앱 표시 형식으로 변환하는지 확인한다.
- API 실패 시 기존 앱 오류 표시 방식을 사용하고 입력값/스크롤 상태를 불필요하게 초기화하지 않는지 확인한다.
```
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
@@ -1,32 +0,0 @@
# Phase 17 통합 배송 개인정보 정리 리뷰
## 리뷰 정보
- 일자: 2026-11-01
- 대상: 승인된 Phase 17 working tree. 문서 2개, 운영 코드 2개, 테스트 5개.
- 기준: PRD `GIFT-018`, `GIFT-020`, `DEC-023`, 계획 `P17-T1`/`P17-GATE`.
- 방법: 구현 담당과 별개의 단일 read-only reviewer가 전체 diff와 연결된 repository, entity, query, DTO, controller, 인증 및 상태 전이 경로를 검토했다.
- 판정: **APPROVE. 확정 발견 사항 및 수정 차단 사항 없음.**
## 기준별 판정
| 기준 | 결과 |
|---|---|
| 상태와 기준 시각 pairing | DELIVERED/deliveredAt 및 UNDELIVERABLE/undeliverableAt의 non-null 시각만 7일 inclusive cutoff로 판정. fallback·CANCELED 제외 |
| 삭제·보존 범위 | 기존 12개 필드 null 처리 본문 유지. 상태·전달불가 사유·업무 시각·회원·결제·동의·리뷰 보존 |
| 예약·잠금 | 매시 :20 Asia/Seoul, Redis literal, transaction/unlock 불변. 자동취소는 미변경 |
| 경계·반복 | 정확한 경계·과거 이력 포함, 1초 미경과·짝인 null 시각·비대상 상태 제외. 부분 삭제·재실행 0건 검증 |
| 조회 회귀 | 두 상태의 실제 JWT HTTP 사용자/관리자 상세·목록, 빈 문자열/null, 권한·액션·flags·시각·사유 보존 |
| 변경 최소성 | 새 스케줄·DDL·API·dependency 없음. 기존 assertion을 재사용한 parameterization, 내부 이름과 호출자 일치 |
## 검증 근거
- reviewer는 RED의 UNDELIVERABLE `expected 1 / actual 0`, 구현 담당의 focused 165개 통과 기록을 대조했다.
- lead 재실행의 scheduler 59개와 실제 HTTP 2개 XML을 reviewer가 직접 확인했다. 실패·오류·skip 0, 두 상태의 DB `erased=1`, `repeated=0`, `persistedNulls=12`와 보존 assertion 통과.
- 리뷰 당시 전체 실행은 진행 중이었다. 이후 lead가 별도 verifier 결과 및 XML 합계를 확인했다: 전체 2,904개, 실패·오류·skip 0, build·ktlintCheck 통과. 상세 명령과 결과는 기존 `plan-task.md`의 Phase 17 최종 Gate에 기록했다.
## 운영 경계
- 기존 nullable schema/reader 호환이 선행조건이다. 배포 후 오래된 전달불가 개인정보도 비가역적으로 삭제된다. 혼합 버전에서 구버전이 같은 락을 획득한 회차는 전달완료만 처리할 수 있다.
- 기존 전건 조회·건별 delivery 조회·단일 트랜잭션 구조는 유지된다. 운영 누적 건수/실행계획 정보 없이 부하 안전성을 단정하지 않으며 이번 범위에서 batching/index를 추가하지 않는다.
- 운영 MySQL·실제 Redis 다중 인스턴스·배포·FCM·백업/로그/캐시 삭제는 미검증 또는 범위 밖이다. LSP는 제공되지 않아 Kotlin compile/ktlint로 대체했다.
@@ -1,324 +0,0 @@
# P3 이름 전달 경로 인벤토리와 GREEN 검증 인계
## COR022 최신 범위
- 레거시 MessageService/Repository는 이번이름변경을 HEAD로 되돌리고 MessageListRow 및 MessageServiceLocalizedNameTest3건을 제거한다. 목록6개와차단오류의이름치환·이벤트nameArgumentMemberIds2곳만 원래형태로돌아가며 API/발송/보관/삭제업무는유지한다.
- 공통FCM/v2 DM/WS는유지한다. 레거시발송 본문args는원본이지만 기존senderMemberId로 공통알림senderNicknameSnapshot이현지화될수있는경계를그대로둔다. 아래T-MESSAGE·JOIN목록은이전이력이며최신검증은 plan-task.md MESSAGE-NAME-TRIM-T1을 따른다.
- 적용완료: 두운영파일HEAD일치·전용2파일삭제, 실제HTTP23요청/발송이벤트2건 및전체2267건/lint통과를확인했다. 임시검증소스·클래스·서버·Redis는정리했고영구테스트3건만제거됐다.
## 상태와 경계
- 기준: `prd.md` NAME002/003/005/006, COR012, `plan-task.md` P3-T1/P3-T2. 이 파일은 부모 에이전트의 실행 인계이며 원 PRD/계획은 수정하지 않았다.
- 1차 인계에서는 대표 RED 테스트 4개 파일과 이 인벤토리만 작성했다. 이어진 부모의 GREEN 위임으로 아래 소유 서버 경로를 구현하고 실제 fixture 회귀를 보강했다. core Member/Lang/creatorname 모듈, 설정 파일, DDL, 외부 저장소는 수정하지 않았다. 커밋/푸시/Gradle 실행은 하지 않았다.
- 부모의 `/var/folders/yh/8xsbvpsj5wg2qnxzxdp11_gm0000gn/T/opencode/creatorname-consumer-red.log`는 104개 중 35개 실패를 기록한다. FCM/WS/message/live의 이름 및 handshake assertion RED를 읽어 확인했다. live 상세 1건은 아래 fixture 보정 대상이다. 이 작업의 GREEN 실행 결과는 아직 없으며 부모가 직렬 검증한다.
- 아래 1차 조사/설계 표는 경로 추적 이력이다. 최종 구현 상태와 변경 파일 및 실행 대기는 문서 끝의 **GREEN 구현 상태**가 우선한다. 테이블 부재/컴파일/컨텍스트 오류를 RED 성공으로 간주하지 않는다.
- 기반 계약: `kr.co.vividnext.sodalive.v2.creatorname.application.CreatorLocalizedNameService.findLocalizedNames(Collection<Long>, Lang): Map<Long, String>`. JA + 활성 + 실제 `Member.role=CREATOR`만 반환하고 다른 언어/미등록/비활성/USER는 원본 fallback한다. HTTP 경계 외 `LangContext` 접근, 행별 조회, 전역 JSON 변환은 금지한다.
- 테스트는 `MemberRepository.saveAndFlush` 후 승인된 `creator_localized_name` 테이블에 JDBC로 실제 JA 행을 넣는다. 이름 resolver/repository/서비스는 mock하지 않는다. USER alias 행은 read-side role 필터를 검증하기 위한 의도적인 fixture이며 관리 API 허용 사례가 아니다.
- 새 통합 테스트의 mock은 외부 전송 경계인 `FcmService`, `S3Uploader`만 쓴다. 기존 Mockito 단위 테스트 및 Redis-only 컨텍스트는 새 필수 생성자 의존성을 명시적으로 제공하도록 조정했다. Redis는 각 클래스의 `EmbeddedRedisInitializer` opt-in으로 제한한다. 테스트 JWT는 공개된 테스트용 64-byte secret을 클래스 속성으로 지정한다. 라이브 토큰은 더미 자격증명으로 로컬 서명만 수행하며 실제 RTC 연결은 하지 않는다.
## 1차 테스트와 예상 RED 이력
모든 경로는 저장소 루트 기준이다. T-FCM/T-WS/T-LIVE/T-MESSAGE는 아래 **정확한 테스트 파일**을 뜻한다.
| 식별자 | 테스트 파일 | 실제 실행 경로와 단언 | 기존 동작의 예상 RED |
|---|---|---|---|
| T-FCM | `src/test/kotlin/kr/co/vividnext/sodalive/fcm/FcmSendListenerLocalizedNameTest.kt` | 실제 `UserCreatorChatService.sendTextMessageByWebSocket`가 발행한 DM 이벤트, 실제 `LiveRoomService.cancelLive`가 발행한 취소 이벤트를 `@RecordApplicationEvents`로 수집. 실제 listener target을 동일 테스트 트랜잭션에서 호출하고 outbound 경계만 관찰. JA/KO 토큰 그룹별 title/body/새 notification snapshot, 255 code point 별칭 저장·재조회, 원본 이벤트 args/title 불변. 이름과 같은 `creator.*$` 방 제목을 본문 인자로 유지. 이름 변경 뒤 새 알림을 생산해도 과거 저장 행이 불변인지 재조회 | JA DM 본문과 snapshot이 `dm-creator`, JA 라이브 제목과 snapshot이 `creator.*$`로 남음. KO/문구 번역/과거 행 보존은 통과해야 함 |
| T-WS | `src/test/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/websocket/UserCreatorChatLocalizedNameIntegrationTest.kt` | 실제 JWT/Redis 인증으로 handshake JA/KO/EN/미지원/누락 헤더 속성. `RANDOM_PORT` + `StandardWebSocketClient`로 localhost 연결, JOIN 후 실제 DB 저장과 Redis pubsub를 거쳐 같은 회원의 KO/JA 두 세션 비교. 별도 테스트로 JA 발신자의 SEND_ACK와 KO 수신 MESSAGE 비교. 실제 HTTP open/messages 언어별 이름도 확인 | handshake의 `attributes["lang"]` 없음. JA MESSAGE/ACK/open/messages 이름이 `original-creator`로 남음. ID/body/mine/requestId는 보존되어야 함 |
| T-LIVE | `src/test/kotlin/kr/co/vividnext/sodalive/live/room/LiveRoomLocalizedNameIntegrationTest.kt` | 실제 JPA/Redis membership을 사용한 getRoomInfo, getRoomDetail, getUserProfile. speaker/manager CREATOR 별칭, USER/비활성 fallback, membership role 보존. donation/roulette 메시지의 UUID/본문/secret 필터, JA→KO 응답 독립성과 공유 Redis 원본 불변. 최근 종료 라이브 KO→JA 캐시 읽기 | JA host/manager/현재 후원·룰렛 표시 이름 및 최근 종료 라이브가 원본으로 남음. KO/USER/비활성/secret 필터/Redis 원본 단언은 통과해야 함 |
| T-MESSAGE | `src/test/kotlin/kr/co/vividnext/sodalive/message/MessageServiceLocalizedNameTest.kt` | 실제 Message sender/recipient 관계 저장 후 문자/음성 sent/received/keep 6개 읽기. CREATOR 발신자/수신자 양쪽, USER 이름 보존, JA/KO/EN, 원본 본문/ID/voice URL 보존 | JA senderNickname/recipientNickname가 원본으로 남음 |
1차 작성 수는 FCM 3개, WS 8개 실행 사례(언어 parameterized 4개 포함), live 4개, legacy message 2개로 총 17개였다. GREEN 위임 후 현재 수는 FCM 6개, WS 9개, live 8개, legacy message 2개로 총 25개다. 추가 사례는 실제 오디오 답글 생산자의 title owner/actor 분리(CREATOR/USER), 실제 기프트 자유 문구, 음성 REST/WS 언어 독립, 중립 feed/current fallback, 예약/방문/추천/후원/하트 현재 이름이다. 전체 P3 외부 수용 기준의 완료를 뜻하지 않는다.
부모 전용 실행 명령(이번 작업에서 미실행):
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.fcm.FcmSendListenerLocalizedNameTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.usercreatorchat.websocket.UserCreatorChatLocalizedNameIntegrationTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.live.room.LiveRoomLocalizedNameIntegrationTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.message.MessageServiceLocalizedNameTest'
```
테스트 listener 호출은 `@Async`/REQUIRES_NEW proxy를 의도적으로 우회한다. rollback 예정인 fixture를 다른 트랜잭션에서 읽는 오류 없이 실제 언어 그룹화/문구 렌더링/DB 저장을 검증한다. async after-commit 스케줄링 자체는 이 테스트의 검증 대상이 아니다. 반면 WS 테스트는 fixture를 commit한 뒤 실제 네트워크/Redis/handler/service/broker 전체를 사용한다. 기존 localhost `StandardWebSocketClient` 선례는 검색되지 않았으며 기존 `UserCreatorChatWebSocketHandshakeIntegrationTest`의 endpoint/인증 계약과 `UserCreatorChatRedisIntegrationTest`의 실제 pubsub 선례를 결합했다.
## 1차 FCM 경계와 메타데이터 설계
기존 구현은 `src/main/kotlin/kr/co/vividnext/sodalive/fcm/FcmEvent.kt` 한 파일의 `FcmEvent`/`FcmSendListener`다. 별도의 FcmSendEvent/FcmSendListEvent 타입은 없다. 1차 조사 시 `sendPush`는 `PushTokenInfo.languageCode`로 그룹화하고 `Lang.fromAcceptLanguage`를 적용하지만 원본 `args`와 `title`을 그대로 사용했다. titleKey와 messageKey는 같은 args 배열을 사용한다. 이제 아래 명시 metadata로 그룹별 새 렌더링을 수행한다.
GREEN에서 부모와 호출부 소유자가 합의하여 적용한 명시 정보:
- 기존 `senderMemberId`는 **알림 행의 발신자 snapshot 주체**로 유지한다. 이미 이름을 전달하는 모든 호출부에 있다. `creatorId`, 수신자 ID, resource ID를 sender ID로 추정하지 않는다.
- 확정 필드 `titleMemberId: Long? = null`: raw title 전체가 회원 이름인 경우 그 회원 ID. 보통 senderMemberId와 같지만 오디오 답글은 다르다.
- 확정 필드 `nameArgumentMemberIds: Map<Int, Long> = emptyMap()`: 0-based args 위치→실제 이름 소유 회원 ID. 현재 대상은 legacy 문자/음성, v2 DM/voice의 `[0]`뿐이다. 문자열 종류/값 일치/정규식/messageKey 추론으로 이름을 찾지 않는다.
- language group마다 sender/title/arg ID의 합집합을 batch 조회하고 별도 args/title/body/senderNicknameSnapshot을 만든다. 원본 이벤트/공유 DTO/저장한 과거 알림을 mutate하지 않는다. 실제 생산자에서 발행한 이벤트를 테스트하므로 metadata가 추가되면 테스트 fixture에 가짜 필드를 붙일 필요 없이 실제 호출부 수정이 검증된다.
- `PushNotificationService.saveNotification`은 language group에서 렌더링한 sender snapshot을 저장하도록 연결한다. `resolveSenderSnapshot`의 기존 명시 snapshot/profile/fallback 의미를 보존한다. `PushNotificationList`에는 senderMemberId가 없으므로 과거 목록 조회 때 현재 회원과 다시 연결하지 않는다.
### 전 FcmEvent 발행 지점 22곳
아래 경로의 공통 prefix는 `src/main/kotlin/kr/co/vividnext/sodalive/`다. 파일 경로와 메서드를 모두 명시했다. 행 번호는 1차 조사 기준이며 이후 수정으로 이동할 수 있다. `titleId`/`argIds`는 위 확정 metadata 값이다. `[외부 소유]`는 이 작업의 소유 범위 밖이지만 서버 내부 파일이라는 뜻이다. 각 행의 최종 처리 상태는 끝의 상태 표에 연결했다.
| # | 생산 파일:행 / 메서드 | 이벤트·현재 이름 위치·이름 아닌 값 | GREEN titleId / argIds / sender snapshot 주체 | 소유/검증 |
|---|---|---|---|---|
| 1 | `fcm/FcmController.kt:23` send 개별 | INDIVIDUAL; 운영자 자유 title/message, 이름 슬롯 없음 | null / empty / 기존 없음 | P3; 임의 텍스트 불변 |
| 2 | `fcm/FcmController.kt:34` send 전체 | ALL; 운영자 자유 title/message, 이름 슬롯 없음 | null / empty / 기존 없음 | P3; 임의 텍스트 불변 |
| 3 | `message/MessageService.kt:74` sendTextMessage | SEND_MESSAGE; titleKey=message.fcm.title, args[0]=sender.nickname, messageKey=text_received | null / `{0: sender.id}` / sender.id | P3; T-MESSAGE + 기존 FCM 문구 |
| 4 | `message/MessageService.kt:149` sendVoiceMessage | SEND_MESSAGE; args[0]=sender.nickname, messageKey=voice_received | null / `{0: sender.id}` / sender.id | P3; T-MESSAGE + 기존 FCM 문구 |
| 5 | `v2/usercreatorchat/service/UserCreatorChatService.kt:235` publishMessagePush | INDIVIDUAL; text/voice 공통 발행. args[0]=sender.nickname, titleKey=dm_title 또는 title, room.id는 deepLinkId | null / `{0: sender.id}` / sender.id | P3; T-FCM 실제 DM 생산자 |
| 6 | `live/room/LiveRoomService.kt:503` createLiveRoom | CREATE_LIVE; raw title=createdRoom.member.nickname; args[0]=createdRoom.title(방 제목) | createdRoom.member.id / empty / 기존 같은 ID | P3; T-FCM 취소와 같은 title 패턴 |
| 7 | `live/room/LiveRoomService.kt:685` startLive | START_LIVE; raw title=room.member.nickname; args[0]=room.title(방 제목) | room.member.id / empty / 기존 같은 ID | P3; 기존 live regression |
| 8 | `live/room/LiveRoomService.kt:760` cancelLive | CANCEL_LIVE; raw title=room.member.nickname; args[0]=room.title, 예약 취소 전 수집한 pushTokens 사용 | room.member.id / empty / 기존 같은 ID | P3; T-FCM 실제 취소 생산자 |
| 9 | `explorer/ExplorerService.kt:683` saveNotice | CHANGE_NOTICE; title=member.nickname, 고정 notice messageKey, args 없음 | member.id / empty / 기존 member.id | [외부 소유: legacy worker] |
| 10 | `explorer/profile/creatorCommunity/CreatorCommunityService.kt:139` createCommunityPost | CHANGE_NOTICE; title=member.nickname, new_post messageKey | member.id / empty / 기존 member.id | [외부 소유: legacy worker] |
| 11 | `explorer/profile/creatorCommunity/CreatorCommunityService.kt:532` createCommunityPostComment | INDIVIDUAL; title=댓글 작성 member.nickname. 수신 creatorId와 작성자 다름 | member.id / empty / 기존 member.id | [외부 소유: legacy worker] |
| 12 | `content/comment/AudioContentCommentService.kt:81` registerComment | CREATE_CONTENT_COMMENT; title은 답글이면 parent.member.nickname, 일반 댓글이면 member.nickname. args[0]=audioContent.title | `parent?.member?.id ?: member.id` / empty / **senderMemberId=member.id 유지** | [외부 소유: legacy worker]; 부모 댓글 작성자와 행위자 각각 CREATOR/USER 조합 회귀 필요 |
| 13 | `content/AudioContentService.kt:492` uploadComplete 완료 안내 | INDIVIDUAL; titleKey=upload_complete_title, message=audioContent.title. 본문은 이름 아님 | null / empty / 기존 audioContent.member.id | [외부 소유: legacy worker]; 생산자 추가 metadata 불필요, 새 sender snapshot만 언어별 |
| 14 | `content/AudioContentService.kt:511` uploadComplete 즉시 공개 | UPLOAD_CONTENT; title=audioContent.member.nickname; args[0]=콘텐츠 제목 | audioContent.member.id / empty / 기존 같은 ID | [외부 소유: legacy worker] |
| 15 | `content/AudioContentService.kt:541` releaseContent | UPLOAD_CONTENT; title=audioContent.member.nickname; args[0]=콘텐츠 제목 | audioContent.member.id / empty / 기존 같은 ID | [외부 소유: legacy worker] |
| 16 | `admin/live/AdminLiveService.kt:341` cancelNotStartedLive4hoursPassed | CANCEL_LIVE; title=room.member.nickname; args[0]=방 제목 | room.member.id / empty / 기존 같은 ID | 부모의 후속 권한 부여로 titleMemberId 한 줄만 이 작업에서 연결 |
| 17 | `can/charge/event/ChargeEventService.kt:80` applyOtherEvent | INDIVIDUAL SYSTEM; title=chargeEvent.title(이벤트 제목), args[0]=additionalCan(숫자) | null / empty / 없음 | [외부 소유: legacy]; 수정 불필요 |
| 18 | `can/charge/event/ChargeEventService.kt:104` applyFirstChargeEvent | INDIVIDUAL SYSTEM; 고정 titleKey, args[0]=additionalCan | null / empty / 없음 | [외부 소유: legacy]; 수정 불필요 |
| 19 | `v2/can/charge/event/ChargeEventJobService.kt:187` publishPaidNotification FIRST_CHARGE | INDIVIDUAL SYSTEM; 고정 titleKey, args[0]=job.additionalCan | null / empty / 없음 | [외부 소유: v2]; 수정 불필요 |
| 20 | `v2/can/charge/event/ChargeEventJobService.kt:200` publishPaidNotification 기타 | INDIVIDUAL SYSTEM; title=job.methodSnapshot, args[0]=job.additionalCan | null / empty / 없음 | [외부 소유: v2]; 수정 불필요 |
| 21 | `admin/audition/AdminAuditionService.kt:94` updateAudition | IN_PROGRESS_AUDITION; 고정 titleKey, args[0]=audition.title(오디션 제목) | null / empty / 없음 | [외부 소유: parent/admin]; 수정 불필요 |
| 22 | `v2/gift/application/GiftPushService.kt:115` publishGiftPush | INDIVIDUAL GIFT; 11개 공개 알림 메서드가 고정 title/message로 위임. memberId는 수신자, applicationNo는 deepLinkId | null / empty / 없음 | [외부 소유: v2]; 회원 표시 이름이 없으므로 수정 불필요 |
기프트의 11개 입구는 sendTrackingDeadlineReminder, sendRecipientAddressDeadlineReminder, sendAutoCanceledToSender, sendTrackingRegisteredToRecipient, sendArrivedAtMailboxToSender, sendArrivedAtMailboxToRecipient, sendInspectionCompleted, sendUndeliverableToSender, sendUndeliverableToRecipient, sendDeliveredToSender, sendDeliveredToRecipient다. 모두 공통 22번 발행으로 수렴하며 수신자 ID를 발신자로 복사하면 안 된다.
### FCM 저장·외부 capacity 분류
| 생산/읽기 파일 | 유형 | 결정/증거 | 테스트/남은 검증 |
|---|---|---|---|
| `src/main/kotlin/kr/co/vividnext/sodalive/fcm/FcmEvent.kt` sendPush → `fcm/notification/PushNotificationService.kt` saveNotification | 신규 recipient-language payload 및 언어별 immutable snapshot 생산 | token language를 정규화한 Lang을 명시 전달. render 후 저장해야 함 | T-FCM |
| `src/main/kotlin/kr/co/vividnext/sodalive/fcm/notification/PushNotificationList.kt` | 기존 역사 snapshot | senderNicknameSnapshot은 `@Column(nullable=false)` 기본 길이 255, message는 TEXT, languageCode 길이 8. sender ID 필드 없음. 기존 entity/DDL 확장 금지 | T-FCM 255자 신규 저장/과거 행 보존; 실제 MySQL charset/collation/컬럼 사양은 미확인 |
| `src/main/kotlin/kr/co/vividnext/sodalive/fcm/notification/PushNotificationListRepository.kt` getNotificationList → `PushNotificationService.getNotificationList` | 역사 snapshot 읽기 | senderNicknameSnapshot을 직접 projection, locale 필터는 LangContext, 회원 join 없음. 현재 alias로 재조회하지 않음 | 저장 행은 T-FCM historical 대조군. 목록 query는 read-only 근거와 기존 `src/test/kotlin/kr/co/vividnext/sodalive/fcm/notification/PushNotificationServiceTest.kt`; H2에 JSON_CONTAINS 지원 fixture가 없어 새 실제 목록 SQL 테스트는 미포함 |
| `src/main/kotlin/kr/co/vividnext/sodalive/fcm/FcmService.kt` send | 외부 provider 전달 | title/body를 Firebase Notification에 그대로 넣으며 truncate 없음. 이번 test는 mock 경계까지이고 provider 전송하지 않음 | [blocked] provider의 byte/payload 제한과 255 Unicode 별칭 호환성, 실제 모바일 수신 증거는 메시징 소유자 필요 |
## WS/HTTP chat 생산·읽기 지도
공통 prefix는 `src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/`다. 모든 신규 payload의 sender ID는 message.participant.member.id이며 roomId/opponentId로 이름 조회하지 않는다.
| 파일/메서드 | 유형·생산 → 읽기 | GREEN 경계 | 검증 |
|---|---|---|---|
| `websocket/UserCreatorChatWebSocketAuthInterceptor.kt` beforeHandshake | 실제 JWT MemberAdapter → session.attributes | `Accept-Language`를 `Lang.fromAcceptLanguage`로 읽어 `lang: Lang` 저장. 제안 상수 `LANG_ATTRIBUTE="lang"`. 누락/미지원은 KO. authentication/memberId는 그대로 | T-WS handshake |
| `websocket/UserCreatorChatWebSocketHandler.kt` handleSendText | request text → service 저장 → SEND_ACK 직렬화 | 세션 Lang을 service에 명시 전달하거나 ACK 경계에서 batch 렌더링. request scope를 WS callback에서 조회하지 않음. ACK `mine=true`, requestId 보존 | T-WS sender ACK |
| `service/UserCreatorChatService.kt` sendTextMessageByWebSocket/deliverRealtime/websocketMessagePayload | 현재 DTO를 먼저 JSON 문자열로 만들어 broker.publish(roomId, opponentId, payload)에 전달 | 중립 senderId와 원본 DTO/본문을 보존해 publish. recipient 세션 언어를 이 단계에서 결정하지 않음. 현재 broker의 기존 4개 생성자 의존성으로 테스트 가능하며 미구현 생성자를 테스트에서 호출하지 않음 | T-WS 실제 송수신 |
| `websocket/UserCreatorChatRoomMessageBroker.kt` publish/onMessage | Redis channel `v2:user-creator-chat:ws:room` → sessionRegistry.findSessions(roomId, memberId) → 같은 pre-serialized 문자열을 모두 전송 | 최소 변경은 기존 envelope의 payload가 가진 senderId/원본 값을 neutral source로 유지하고 onMessage에서 해석한 뒤 세션별 새 DTO/envelope 직렬화. KO/JA Lang별 batch map 조회. 공유 객체 변이/본문 치환 금지. 중립 메시지에 요청 언어 이름을 미리 굳히지 않음 | T-WS same-member 2-session. 기존 `src/test/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/websocket/UserCreatorChatRoomMessageBrokerTest.kt`, `UserCreatorChatRedisIntegrationTest.kt` 회귀도 부모에서 실행 |
| `service/UserCreatorChatService.kt` openRoom/getMessages/toMessageItemDto | DB 현재 opponent.nickname/sender.nickname → HTTP 응답 | HTTP 요청 경계 Lang으로 opponentId/조회 page senderIds batch. sendVoiceMessage/deliverRestMessage의 HTTP message도 별도 request Lang, broker neutral DTO와 독립 | T-WS HTTP open/messages; voice HTTP/S3 경계는 후속 GREEN 회귀 필요 |
| `websocket/UserCreatorChatWebSocketSessionRegistry.kt` | roomId+memberId → 복수 세션 | 이미 복수 세션 지원. 회원 하나의 locale을 전역 저장하지 않음. registry 자체 변경 불필요 | 기존 `src/test/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/websocket/UserCreatorChatWebSocketSessionRegistryTest.kt` |
| `repository/UserCreatorChatRoomRepository.kt` findDmChatListRooms | opponent.member.nickname → 외부 소유 `v2/chat/dto/ChatRoomListQueryDto`의 targetName | 내부 projection에 실제 opponent memberId가 없음. roomId를 alias key로 사용 금지. 아래 cross-owner 조정 필요 | 기존 `src/test/kotlin/kr/co/vividnext/sodalive/v2/chat/ChatRoomListServiceTest.kt`, HomeFollowing 관련 회귀 |
WS 외부 client locale 변경은 reconnect로 새 handshake를 하도록 계약해야 한다. 기존 연결의 locale 자동 변경/메시지 타입 추가는 이번 내부 테스트만으로 승인하거나 구현하지 않는다.
## live 생산·읽기와 캐시 분류
공통 prefix는 `src/main/kotlin/kr/co/vividnext/sodalive/`다. 이 표의 member ID는 표시 이름의 실제 소유자이며 resource ID가 아니다.
| 생산 파일/메서드 → 소비 파일/메서드 | 유형·ID/Lang 출처 | 최소 GREEN 적용 또는 보존 결정 | 검증/첫 단계 미포함 |
|---|---|---|---|
| `live/room/LiveRoomService.kt` enterLive/setSpeaker/setListener/setManager → `live/room/info/LiveRoomInfo.kt` → `LiveRoomMember.kt` | Redis 언어 중립 membership. 인증 Member 또는 request.memberId로 재조회한 Member의 원본 nickname/id | writer 원본 유지. `LiveRoomInfo`/`LiveRoomMember` 저장 객체를 request locale로 덮어쓰지 않음 | T-LIVE actual Redis |
| 위 membership → `live/room/LiveRoomService.kt` getRoomInfo | current live render; host Member.id + 각 member.id, HTTP LangContext 경계 | speaker/listener/manager를 **새 복사본**으로 렌더링. `LiveRoomMember.copy`는 생성자 밖 var role을 자동 복사하지 않으므로 role을 보존해야 함. 저장 권한/equality 흐름에 localized nickname을 집어넣지 않음 | T-LIVE info, role/Redis 원본 |
| 위 membership 또는 reservation Member 관계 → `live/room/LiveRoomService.kt` getRoomDetail/getUserProfile | current-name DTO. detail manager=room.member.id, users=각 id, profile=user.id | 한 요청의 IDs로 batch 조회 후 DTO names만 대체. USER/비활성 fallback. 내부 membership 권한 검사는 원본 객체로 유지 | T-LIVE detail/profile |
| `live/room/LiveRoomService.kt` donation/donationV2, `live/roulette/v2/RouletteService.kt` spinRoulette → `LiveRoomInfo.addDonationMessage/addRouletteMessage` → `getDonationMessageList` | Redis 언어 중립 live feed. memberId/nickname을 원본으로 저장, 본문/UUID/isSecret 별도 | current live read의 복사본 nickname만 batch override, secret 필터 유지. writer의 nickname/본문/canMessage/UUID를 재작성하지 않음. 이미 client에 전달한 payload도 불변 | T-LIVE donation+roulette; 실제 결제/roulette spin 자체는 미실행 |
| `live/room/LiveRoomRepository.kt` getLiveRoomListNow/ReservationWithDate/WithoutDate → `LiveRoomService.getRoomList` | 현재 DB Member 관계; creatorId 이미 있음. HTTP LangContext | 목록 전체 creatorIds batch 후 creatorNickname만 대체 | 후속 focused `src/test/kotlin/kr/co/vividnext/sodalive/live/room/LiveRoomServiceAdultVisibilityPolicyTest.kt`; 소유 범위 밖 api/home/HomeService, api/live/LiveApiService가 호출하므로 공유 서비스에서 해결 |
| `live/room/LiveRoomRepository.kt` getDonationList → `LiveRoomService.getDonationStatus` | 금액 집계 materialization 아닌 요청 시 현재 member.nickname/ID projection | donationList memberId로 batch, 금액/secret 집계/정렬 불변. 역사 닉네임 스냅샷 아님 | T-LIVE 후속 DB 금액 fixture 필요 |
| `live/room/LiveRoomRepository.kt` getHeartList → `LiveRoomService.getHeartList` | 요청 시 현재 member.nickname, 반환 projection에 memberId 없음 | 내부 donor memberId 추가 필요. 공개 DTO field 추가 없이 내부 projection/경계 연결 | T-LIVE 후속 DB 금액 fixture 필요 |
| `live/reservation/LiveReservationService.kt` makeReservation/getReservationList/getReservation | 예약은 member 관계만 저장. nickname/masterNickname는 매번 room.member.nickname | 현재 이름 조회로 분류. room.member.id와 HTTP LangContext batch. 예약 시각/가격/취소 규칙 불변 | 기존 `src/test/kotlin/kr/co/vividnext/sodalive/live/reservation/LiveReservationServiceIntegrationTest.kt` 후속 이름 회귀 |
| `live/room/visit/LiveRoomVisitService.kt` roomVisit → getRecentVisitRoomUsers | 방문 기록은 member 관계/시각, 이름은 현재 Member→GetRoomDetailUser | 현재 이름 조회. 반환 members IDs batch + 명시 요청 Lang. 사용자/역할 필터 불변 | 새 테스트 경로 필요 시 GREEN 전 부모 계획에 추가; 첫 단계 테스트 없음 |
| `live/recommend/LiveRecommendController.kt` → `LiveRecommendService.getRecommendLive` → `LiveRecommendCacheService.getRecommendLive` → `LiveRecommendRepository.getRecommendLive` | banner read-through cache, key=`getRecommendLive:{memberId or guest}:{isAdult}:{lang.name()}`, cache_ttl_3_hours. `configs/RedisConfig.kt` TTL 3시간 | **실제 payload는 GetRecommendLiveResponse(imageUrl, creatorId)뿐이며 nickname 없음.** 이름 캐시가 아니므로 alias 적용 불필요. 이미지 안 텍스트는 서버 alias 치환 대상 아님 | `src/test/kotlin/kr/co/vividnext/sodalive/live/recommend/LiveRecommendRepositoryTest.kt`, `LiveRecommendServiceTest.kt` 기존 선례. 분류는 read-only 증거, 새 RED 없음 |
| `live/recommend/LiveRecommendRepository.kt` getOnAirRecommendChannelList/getRecommendChannelList/getOnAirFollowingChannelList/getFollowingChannelList/getCreatorFollowingAllList → `LiveRecommendService` 같은 public read 메서드들 | 캐시 밖 현재 nickname+creatorId 목록. HTTP 경계 언어를 아직 안 받는 메서드 있음 | controller에서 LangContext 선택 후 service에 명시 Lang 전달하고 반환 IDs batch. count/필터/합치기/정렬은 변경하지 않음 | 기존 위 두 recommend 테스트에 후속 이름 회귀 필요 |
| `live/room/LiveRoomRepository.kt` getLatestFinishedLive → `LiveRoomService.getLatestFinishedLive` → LiveRoomController 및 외부 소유 `api/live/LiveApiService.kt` | 현재 Member.nickname을 포함한 read-through cache, key=`getLatestFinishedLive:{memberId or guest}`, cache_ttl_10_minutes/TTL 10분. **Lang 없음** | 종료된 라이브여도 nickname 역사 snapshot이 아님. 중립 캐시 밖 request-time batch 렌더링 또는 Lang별 key 분리가 필요. 단순히 cache 내부 이름만 현지화하면 다른 요청 언어로 샘 | T-LIVE KO→JA 최근 종료 라이브. 테스트는 현행 cache key를 정리함; GREEN에서 key를 바꾸면 정리 key도 맞춰야 함 |
| `live/room/LiveRoomService.kt` enterLive의 blocked-by-host 오류 / `message/MessageService.kt` blocked-by-recipient 오류 | 현재 회원 이름이 삽입되는 사용자 메시지 | ID 기반 현재 이름을 해당 HTTP 요청 언어로 렌더링. 원본 인증 Member는 수정하지 않음 | 후속 예외 회귀 필요 |
`GetRecentRoomInfoResponse`는 title/notice/cover/인원/genderRestriction뿐이라 회원 이름 적용 대상이 아니다. live signature/menu/roulette의 상품명·메뉴·결과 문구를 회원 별칭으로 치환하지 않는다. v2 roulette은 shared feed의 이름 writer인 것만 확인했고 원본 writer 변경을 요구하지 않는다.
## legacy message 분류
| 생산 → 읽기 | 유형/필요 ID | GREEN | 검증 |
|---|---|---|---|
| `src/main/kotlin/kr/co/vividnext/sodalive/message/MessageService.kt` sendTextMessage/sendVoiceMessage → `message/Message.kt` | DB는 sender/recipient Member 관계와 본문/voice path만 저장, nickname snapshot 없음 | 저장/원본 Member 보존. FCM name metadata는 위 #3/#4 | T-MESSAGE 실제 관계 저장 |
| `message/MessageRepository.kt` sent/received/keep text/voice → `MessageService.getTextMessageResponse/getVoiceMessageResponse` | 현재 이름 조회. 각 sender.id와 recipient.id 모두 필요 | 한 페이지 양쪽 memberIds 합집합 batch, request Lang으로 DTO만 대체. 본문/voice URL/시간/keep/delete/count 불변 | T-MESSAGE 6개 public read 메서드 |
## 부모와 다른 소유자에게 필요한 정확한 수정 목록
- **P3 후속 구현의 직접 파일:** `src/main/kotlin/kr/co/vividnext/sodalive/fcm/FcmEvent.kt`(metadata + recipient group render), `fcm/notification/PushNotificationService.kt`(이미 렌더링한 새 sender snapshot 저장), `v2/usercreatorchat/websocket/UserCreatorChatWebSocketAuthInterceptor.kt`(세션 Lang), `UserCreatorChatWebSocketHandler.kt`(ACK), `UserCreatorChatRoomMessageBroker.kt`(session별 render), `v2/usercreatorchat/service/UserCreatorChatService.kt`(중립 publish/HTTP names/FCM args metadata), `message/MessageService.kt`(현재 이름·FCM metadata), `live/room/LiveRoomService.kt`(live current reads/copy/FCM title metadata/종료 라이브 캐시 경계), `live/recommend/LiveRecommendController.kt` 및 `LiveRecommendService.kt`(명시 Lang/current names), `live/reservation/LiveReservationService.kt`, `live/room/visit/LiveRoomVisitService.kt`. full prefix는 모두 `src/main/kotlin/kr/co/vividnext/sodalive/`다.
- **필요한 내부 projection만 추가:** `live/room/LiveRoomRepository.kt` getHeartList의 실제 donor memberId. `live/room/like/GetLiveRoomHeartListResponse.kt` 공개 스키마를 늘리지 말고 내부 projection 경계를 마련한다. `GetRoomInfoResponse`, `LiveRoomDonationMessage`는 이미 ID가 있어 공개 필드 추가 불필요. `LiveRoomMember`/`LiveRoomInfo`/roulette writer 저장 locale 변경 불필요.
- **legacy worker에 넘길 FCM 변경:** `src/main/kotlin/kr/co/vividnext/sodalive/explorer/ExplorerService.kt` saveNotice(#9), `explorer/profile/creatorCommunity/CreatorCommunityService.kt` createCommunityPost/createCommunityPostComment(#10/#11), `content/AudioContentService.kt` uploadComplete/releaseContent(#14/#15), `content/comment/AudioContentCommentService.kt` registerComment(#12)에 위 titleMemberId만 명시. 기존 args는 그대로 보존하고, 이름 인자가 아니므로 새 nameArgumentMemberIds만 empty로 둔다. 특히 #12의 senderMemberId를 parent ID로 바꾸면 sender snapshot의 행위자 의미가 깨진다.
- **부모/admin 소유자에게 넘길 FCM 변경:** `src/main/kotlin/kr/co/vividnext/sodalive/admin/live/AdminLiveService.kt` cancelNotStartedLive4hoursPassed(#16)에 room.member.id의 title metadata. admin/audition은 이름 슬롯이 없어 수정하지 않는다.
- **v2 worker와 동시에 합의해야 할 공유 projection:** `src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/repository/UserCreatorChatRoomRepository.kt` findDmChatListRooms가 쓰는 외부 소유 `v2/chat/dto/ChatRoomListQueryDto`에 실제 opponentMemberId를 내부 필드로 추가해야 한다. 소비자 `v2/chat/service/ChatRoomListService.kt` getRooms/toResponse 및 `v2/api/home/following/application/HomeFollowingFacade.kt` 경유 이름을 request Lang으로 렌더링하도록 v2 worker가 조정한다. AI row producer `src/main/kotlin/kr/co/vividnext/sodalive/chat/room/repository/ChatRoomRepository.kt` findAiChatListRooms도 같은 생성자를 쓰므로 대응 필요. public targetName/roomId 타입은 그대로다. 이 첫 단계에서 해당 파일은 수정하지 않았다.
- **기반 담당자:** creatorname 서비스/테이블 매핑은 기반 작업자가 제공한다. 이 작업은 core Member/Lang/serializer/config/DDL을 변경하지 않는다. 기반 없이 테이블 부재로 실패한 실행은 의미 있는 RED 증거가 아니다.
## 외부 계약 차단
| 의존 | 소유자/경로 | 내부 확인과 차단 해제 증거 |
|---|---|---|
| EXT001 앱 전체 표시·원본 편집·client cache | [blocked: 모바일 저장소/파일/담당자 미확인] | 서버 DTO 스키마를 유지하더라도 원본 편집기에 localized 이름이 저장되지 않는다는 앱 증거 필요. 이름 cache invalidation/수명/표면 목록 확인 필요 |
| EXT002 운영 UI | [blocked: 운영 UI 저장소/경로/인증 주체 미확인] | 이번 전달 계층 테스트로 관리자 UI 저장 흐름을 완료 처리하지 않음 |
| EXT003 WS session locale | [blocked: client/messaging 저장소·담당자 미확인] | handshake Accept-Language 지원, 언어 변경 시 reconnect, 같은 회원 KO/JA 다중 세션의 실제 앱 검증. 서버 localhost 테스트는 모바일 계약 확인을 대신하지 않음 |
| EXT003 RTC/live 표시 소비 | [blocked: RTC/client 표시 경로 미확인] | 서버 RTC UID/RTM account는 member.id 문자열 및 worker UID이고 이름을 RTC에 등록하는 코드 없음. live HTTP names와 클라이언트/RTM display cache의 매핑/갱신 시점 확인 필요 |
| push provider / 운영 DB capacity | [blocked: 메시징/DB 담당자의 실제 설정 및 증거 필요] | 기존 push snapshot mapping 255와 test H2 저장만 확인 가능. 운영 MySQL charset/column, FCM payload byte 제한, 255 code point/다중 code unit 별칭의 실제 모바일 전송 호환성은 별도 확인. truncate/과거 행 rewrite/column 확장으로 우회하지 않음 |
## 이번 정적 점검과 인계 한계
- `rg -n 'FcmEvent\(' src/main/kotlin`로 선언 1개와 실제 생산 22곳을 대조하고 각 호출부의 title/args/sender ID를 열어 확인했다. 실제 FcmService send는 listener 단일 진입이며 기프트도 위 단일 이벤트 발행이다.
- 기존 생성자/DTO/서비스 메서드, JPA/Redis 저장과 조회, HTTP endpoint, JWT 생성/검증, request-scoped LangContext, 테스트 초기화 선례를 읽어 테스트를 작성했다. 테스트 안에 미구현 service constructor 호출/placeholder/Disabled/실제 Firebase·S3 전송은 없다.
- `rg`로 신규 테스트의 130자 초과 줄/후행 공백/TODO/FIXME/Disabled/mock 직접 생성 패턴이 없음을 확인했다. mock bean은 FcmService/S3Uploader뿐이다. 이 작업에 `lsp_diagnostics` 도구는 제공되지 않았다. Gradle/test/build/lint/실제 localhost QA는 사용자 지시에 따라 **미실행**이며 부모가 직렬 실행한다.
- 외부 앱/RTC 계약과 실제 MySQL/FCM capacity는 내부 구현으로 해제되지 않는다. 아래 추가 통합 사례도 부모의 직렬 GREEN 실행 전까지 통과를 주장하지 않는다.
## GREEN 구현 상태
이 절은 후속 GREEN 위임의 현재 상태다. 모든 `구현/대기`는 코드 연결과 정적 대조 완료, **부모 runtime 검증 대기**를 의미한다. 원 PRD/plan이나 제품 Gate를 완료 처리하지 않았다.
| inventory 행/표면 | 처리 상태 | 구현 및 불변 조건 | 연결 테스트 |
|---|---|---|---|
| FCM #3/#4/#5 | 구현/대기 | legacy text/voice 및 v2 DM/voice가 `nameArgumentMemberIds=mapOf(0 to sender.id)` 명시. event의 원본 args는 유지 | T-FCM, T-MESSAGE, UserCreatorChatServiceTest |
| FCM #6/#7/#8/#16 | 구현/대기 | live 생성/시작/취소 및 admin 자동 취소에 `titleMemberId` 명시. 방 제목 args는 이름 metadata 없음. admin 파일은 허용된 한 줄만 수정 | T-FCM 실제 live 취소, 기존 live 회귀 |
| FCM #9/#10/#11/#12/#14/#15 | 타 소유자 연결 정적 확인/대기 | legacy worker가 실제 파일에 `titleMemberId` 추가한 것을 확인. #12는 `parent?.member?.id ?: member.id`, senderMemberId는 행위자 그대로. 이 작업은 해당 생산 파일을 수정하지 않음 | T-FCM 실제 registerComment 생산자, CREATOR/USER actor 각 1개 |
| FCM #1/#2/#17/#18/#19/#20/#21/#22 | 의도적 보존/대기 | 자유 제목/본문, 이벤트·오디션·콘텐츠 제목, 숫자 args를 이름으로 추측하지 않음. sender ID 없는 기존 fallback 의미 유지 | T-FCM 실제 GiftPushService 생산자; 기존 FcmService/PushNotificationService 회귀 |
| FCM #13 및 새 sender snapshot | 구현/대기 | sender/title/name-args ID 합집합을 정규화한 token Lang 그룹마다 batch 조회. title/body/args는 그룹별 새 값, 새 notification nickname만 sparse alias로 override. 기존 profile/명시 snapshot/default fallback은 기존 resolver 그대로 | T-FCM 255자, 역사 행 불변, 기존 PushNotificationServiceTest |
| 역사 notification 읽기/용량 | 의도적 보존/외부 blocked | sender ID 없는 기존 rows와 목록 projection, JPA/DDL 길이를 변경하지 않음. provider/운영 DB capacity는 계속 blocked | T-FCM historical 대조군; 실제 목록 JSON_CONTAINS SQL 미검증 |
| WS handshake / ACK | 구현/대기 | `LANG_ATTRIBUTE="lang"`에 Lang 저장, 누락/미지원 KO. handler가 `sendTextMessageByWebSocket(..., lang: Lang)`에 필수 명시. WS callback에는 LangContext 접근 없음 | T-WS 실제 JWT/localhost, 기존 handler/auth tests |
| WS pubsub / 복수 세션 | 구현/대기 | 기존 `UserCreatorChatRoomPublishedMessage(roomId, memberId, payload: String)` wire 유지. 원본 senderId/name/body가 포함된 중립 payload를 publish. broker가 세션 Lang별 batch 조회 후 각 세션에 새 ObjectNode copy. MESSAGE 내 senderNickname 필드만 변경 | T-WS 같은 회원 KO/JA 동시 세션, 기존 broker/Redis integration |
| chat HTTP open/messages/voice | 구현/대기 | HTTP 요청 Lang으로 현재 opponent/page sender 이름을 batch 렌더링. voice HTTP DTO와 WS neutral DTO는 독립. body/mine/requestId/ID/voice URL 유지 | T-WS HTTP 및 새 voice REST/WS 사례 |
| chat 목록 공유 projection | 계약 연결 정적 확인/대기 | `UserCreatorChatRoomRepository.findDmChatListRooms` constructor 끝에 `opponent.member.id` 추가. v2 worker의 `ChatRoomListQueryDto` 마지막 `opponentMemberId: Long?`와 소비 batch lookup을 실제 파일에서 확인. 이 작업은 v2/chat/AI repository를 수정하지 않음 | 기존 v2 ChatRoomListService/Controller 및 HomeFollowing tests를 부모가 실행 |
| live Redis membership / donation / roulette writer | 의도적 원본 보존/대기 | `LiveRoomInfo`, `LiveRoomMember`, donation/roulette writer 저장 구조와 이름은 바꾸지 않음. 응답에서만 copy. role은 copy 후 명시 복원, secret 필터와 UUID/본문 유지 | T-LIVE role/secret/Redis 원본 |
| live info/detail/profile/list | 구현/대기 | 실제 memberIds로 current Member batch와 활성 JA alias를 결합. 목록과 shared Redis base 이름도 현재 원본 fallback. 권한 검사에 localized 객체를 넣지 않음 | T-LIVE info/detail/profile/fallback, 기존 AdultVisibilityPolicyTest |
| live donation/heart 집계 | 구현/대기 | donation `userId` 활용. heart는 내부 `LiveRoomHeartListRow(memberId, ...)` projection 추가 후 기존 공개 3-field DTO로 변환. 금액/순서/secret 합계 불변 | T-LIVE 실제 UseCan fixture |
| live 예약 / 최근 방문 | 구현/대기 | reservation owner IDs 및 visitor IDs batch. 예약 read transaction과 room/owner fetch join으로 OSIV off 및 owner N+1 방지. 일반 사용자/역할/예약 정책 필터 유지 | T-LIVE 예약 생성·목록·상세 및 방문자, 기존 LiveReservationServiceIntegrationTest |
| live 추천 / 팔로잉 | 구현/대기 | `LiveRecommendService`의 HTTP 호출 경계 LangContext를 사용해 기존 api/live caller signature를 유지. on-air early return과 off-air 결합 모두 한 batch 렌더링. 이름 없는 3시간 banner cache는 수정하지 않음 | T-LIVE 실제 추천/팔로잉, 기존 LiveRecommendService/Repository tests |
| 최근 종료 live 10분 cache | 구현/대기 | 같은 기존 key/TTL의 `@Cacheable`을 repository query 경계로 이동해 **중립 DTO만 캐시**. 서비스는 캐시 밖에서 현재 Member 이름+alias batch로 새 응답. 원본 변경/별칭 해제도 cached nickname로 fallback하지 않음 | T-LIVE KO→JA→별칭 해제/현재 원본 변경, 기존 key 정리 유지 |
| legacy message 현재 이름 / 오류 문구 | 구현/대기 | text/voice sent/received/keep의 sender+recipient 합집합 Member 및 alias batch. 기존 Message/Member 저장 불변. blocked recipient/host 오류의 표시 이름도 현재 요청 언어로 렌더링 | T-MESSAGE 및 기존 live 정책 tests |
### fixture 및 기존 테스트 정합성
- 부모 RED XML의 live 상세 예외는 `MemberContentPreferenceService.initializeDefaultPreference:61` → `getStoredPreference(REQUIRES_NEW)` → `LiveRoomService.getRoomDetail:538`이다. 미커밋 test Member를 새 트랜잭션이 못 보는 fixture 문제라 해당 상세 테스트만 `Propagation.NOT_SUPPORTED`로 저장을 commit하고 method `DirtiesContext`로 DB fixture를 격리했다. 원래 policy assertion은 삭제/완화하지 않았다. 같은 실제 preference 경계를 타는 새 추천 테스트에도 동일 격리를 사용한다.
- 기존 UserCreatorChatService/LiveRoomService/LiveRecommendService Mockito constructor는 새 필수 resolver와 HTTP LangContext를 명시한다. Redis-only broker integration은 필수 resolver를 `@MockBean`으로 공급한다. 실제 새 이름 통합 테스트는 계속 실제 JPA 이름 resolver를 사용한다.
- voice 추가 사례는 실제 JPA 전송 서비스를 HTTP request context에서 직접 호출하고 실제 localhost WS 수신과 비교한다. S3만 mock한다. multipart HTTP POST 자체의 네트워크 E2E를 실행한 증거는 아니며, open/messages GET은 기존 테스트가 실제 HTTP로 호출한다.
- WebSocket send의 필수 Lang 인자를 모든 기존 test call/stub/verify에 추가했다. PushNotificationService의 필수 `localizedSenderNickname` 인자를 기존 fallback tests에는 null로 명시해 원래 동작 검증을 유지한다. nullable/optional resolver constructor로 우회하지 않았다.
- 제공된 `creatorname-foundation-final-lint.log`의 11개 진단은 content/explorer/member/search 테스트에만 있으며 이 작업 소유 파일은 없었다. 그 파일은 병렬 legacy 소유자에게 남기고, 이 작업 변경 파일의 import/인자 줄바꿈/130자/후행 공백은 정적으로 점검했다. ktlint를 실행했다고 주장하지 않는다.
### 이 GREEN 위임에서 변경한 정확한 파일
공통 main prefix: `src/main/kotlin/kr/co/vividnext/sodalive/`.
- `fcm/FcmEvent.kt`
- `fcm/notification/PushNotificationService.kt`
- `v2/usercreatorchat/websocket/UserCreatorChatWebSocketAuthInterceptor.kt`
- `v2/usercreatorchat/websocket/UserCreatorChatWebSocketHandler.kt`
- `v2/usercreatorchat/websocket/UserCreatorChatRoomMessageBroker.kt`
- `v2/usercreatorchat/service/UserCreatorChatService.kt`
- `v2/usercreatorchat/repository/UserCreatorChatRoomRepository.kt`
- `message/MessageService.kt`
- `live/room/LiveRoomService.kt`
- `live/room/LiveRoomRepository.kt`
- `live/room/like/GetLiveRoomHeartListResponse.kt`
- `live/recommend/LiveRecommendService.kt`
- `live/reservation/LiveReservationService.kt`
- `live/reservation/LiveReservationRepository.kt`
- `live/room/visit/LiveRoomVisitService.kt`
- `admin/live/AdminLiveService.kt` (titleMemberId metadata 한 줄만)
공통 test prefix: `src/test/kotlin/kr/co/vividnext/sodalive/`.
- `fcm/FcmSendListenerLocalizedNameTest.kt`
- `fcm/notification/PushNotificationServiceTest.kt`
- `v2/usercreatorchat/UserCreatorChatServiceTest.kt`
- `v2/usercreatorchat/UserCreatorChatServiceIntegrationTest.kt`
- `v2/usercreatorchat/websocket/UserCreatorChatLocalizedNameIntegrationTest.kt`
- `v2/usercreatorchat/websocket/UserCreatorChatRoomMessageBrokerTest.kt`
- `v2/usercreatorchat/websocket/UserCreatorChatRedisIntegrationTest.kt`
- `v2/usercreatorchat/websocket/UserCreatorChatWebSocketHandlerTest.kt`
- `live/room/LiveRoomLocalizedNameIntegrationTest.kt`
- `live/room/LiveRoomServiceTest.kt`
- `live/room/LiveRoomServiceAdultVisibilityPolicyTest.kt`
- `live/recommend/LiveRecommendServiceTest.kt`
문서는 이 `delivery-name-inventory.md`만 갱신했다. T-MESSAGE 신규 통합 테스트는 1차 작성본을 그대로 사용한다. main PRD/plan-task, foundation/Member/Lang, legacy worker 소유 생산 파일, v2/chat 및 AI repository는 이 작업에서 수정하지 않았다.
### 부모의 직렬 GREEN 검증 명령
아래는 **미실행** 명령이다. 병렬 쓰기가 끝난 뒤 부모가 실행하고, assertion/compile/lint 결과를 별도 기록한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.fcm.FcmSendListenerLocalizedNameTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.usercreatorchat.websocket.UserCreatorChatLocalizedNameIntegrationTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.live.room.LiveRoomLocalizedNameIntegrationTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.message.MessageServiceLocalizedNameTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.fcm.notification.PushNotificationServiceTest' --tests 'kr.co.vividnext.sodalive.fcm.FcmServiceTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceTest' --tests 'kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceIntegrationTest' --tests 'kr.co.vividnext.sodalive.v2.usercreatorchat.websocket.*'
./gradlew test --tests 'kr.co.vividnext.sodalive.live.room.LiveRoomServiceTest' --tests 'kr.co.vividnext.sodalive.live.room.LiveRoomServiceAdultVisibilityPolicyTest' --tests 'kr.co.vividnext.sodalive.live.reservation.LiveReservationServiceIntegrationTest' --tests 'kr.co.vividnext.sodalive.live.recommend.LiveRecommendServiceTest' --tests 'kr.co.vividnext.sodalive.live.recommend.LiveRecommendRepositoryTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.chat.ChatRoomListServiceTest' --tests 'kr.co.vividnext.sodalive.v2.chat.ChatRoomListControllerTest'
./gradlew ktlintCheck
./gradlew assemble
```
동일 localhost/Redis surface 테스트가 부모의 GREEN 및 수동 사용 근거를 제공할 때까지 서버 runtime 완료를 주장하지 않는다. 외부 앱·RTC reconnect·provider/운영 DB capacity blocked 항목은 그대로 유지한다. 새 SDK 기능, DB 적용, historical row rewrite, truncate, 커밋/푸시는 하지 않았다.
## COR013 Delivery JOIN 전환 인계, 2026-10-15
이 절은 앞의 batch 기반 구현 이력보다 우선하는 현재 전환 manifest다. PRD 10절과 계획의 JOIN-T1~T3를 읽고 delivery 소유 코드만 수정했다. main PRD/plan-task, core creatorname/Member/Lang, 다른 legacy/v2 도메인, 검색 JA 및 관리자 /ja 쓰기 정책은 수정하지 않았다. 부모가 제공한 core 43개 통과와 이전 전체 2249개 통과는 **이번 변경 후 실행 결과가 아니다**.
부모 RED 로그 `creatorname-join-consumer-red.log`에서 `LiveRoomLocalizedNameIntegrationTest`의 추천/팔로잉 테스트가 이름 출력이 아닌 별칭 후속 SELECT 단언으로 실패한 것을 확인했다. 이번 작업은 `read`/`rg`/`apply_patch`만 사용했다. Gradle, 테스트, 빌드, lint, HTTP/WS 실행, 에이전트, git/커밋/푸시, 운영 DB 접근은 하지 않았다. 아래 상태는 **부모 직렬 GREEN 실행 준비**, PASS 판정이 아니다.
### 전환 Manifest
아래 main 경로의 공통 prefix는 `src/main/kotlin/kr/co/vividnext/sodalive/`다. 모든 직접 DB 표시 query는 요청 `Lang`의 명시 LEFT JOIN과 `COALESCE`를 사용한다. member ID·Lang·active·CREATOR는 ON 조건이며 기존 업무 WHERE/count/페이지/금액 조건과 공개 JSON 필드는 유지한다.
| 정확한 파일 | 전환 내용 |
|---|---|
| `live/recommend/LiveRecommendRepository.kt`; `live/recommend/LiveRecommendService.kt` | on-air/off-air 추천·팔로잉 및 전체 팔로잉 5개 projection에서 `CreatorNameJoin` 사용. 서비스 이름 map/copy와 resolver 주입 제거. 20개 early return도 이미 조인된 결과를 반환. count에는 이름 조인을 추가하지 않음 |
| `live/room/LiveRoomRepository.kt`; `live/room/LiveRoomListRow.kt`; `live/room/LiveRoomService.kt` | NOW/날짜별 예약/예정 목록은 원본 room과 조인된 이름을 함께 반환. 태그·예약·권한에 필요한 원본 room/member를 변이하지 않으며 이름 후속 조회는 제거. 상세 host도 별도 read query에서 이름을 함께 선택. 금융/쓰기에서 사용하는 기존 `getLiveRoom`/`getLiveRoomAndAccountId`는 원본 entity 그대로 |
| `live/room/GetLiveRoomUserProfileResponse.kt`; `live/room/detail/GetRoomDetailResponse.kt` | 프로필은 원본 Member와 조인된 이름을 반환하여 Redis membership/권한 비교는 원본으로 하고 공개 nickname만 resolved 값 사용. 상세 manager 생성자도 query의 resolved 이름을 받음. 공개 응답 field/type은 불변 |
| `live/room/like/GetLiveRoomHeartListResponse.kt` | 내부 donor-ID batch 전용 `LiveRoomHeartListRow` 제거. 하트 query가 기존 공개 3-field item을 직접 반환. 후원/하트 합계·secret 노출·정렬은 원래 수식 유지 |
| `live/reservation/LiveReservationRepository.kt`; `live/reservation/LiveReservationListRow.kt`; `live/reservation/LiveReservationService.kt` | 예약 목록/단건을 scalar projection으로 전환. 예약 전 live 상세의 booker 목록도 이름 조인된 `GetRoomDetailUser` 반환. 생성·취소·가격·환불 원본 객체와 시간/cover fallback은 유지. 생성 응답만 기존 쓰기 경계 sparse batch 유지 |
| `live/room/visit/LiveRoomVisitRepository.kt`; `live/room/visit/LiveRoomVisitService.kt` | 최근 방문자 query가 resolved 이름과 profile URL을 직접 projection. 기존 사용자/역할 필터 보존, 이름 map/copy와 서비스 resolver/host 주입 제거 |
| `message/MessageRepository.kt`; `message/MessageListRow.kt`; `message/MessageService.kt` | text/voice sent/received/keep 6개 목록의 sender/recipient를 서로 다른 QMember/이름 alias로 조인한 scalar row로 반환. `findMessageNames` 및 원본+별칭 2-query 결합 제거. write/keep/delete/FCM 원본 metadata와 기존 text `isKept=false` 동작 보존 |
| `v2/usercreatorchat/repository/UserCreatorChatMessageRepository.kt`; `v2/usercreatorchat/dto/UserCreatorChatMessageRow.kt`; `v2/usercreatorchat/service/UserCreatorChatService.kt` | HTTP history는 sender 이름을 조인한 scalar row 반환. cursor/active/id-desc query와 createdAt 응답 정렬·mine·본문·URL·시간 의미 보존. 신규 전송의 neutral publisher/ACK/voice 응답 경계는 별도로 유지 |
| `v2/usercreatorchat/repository/UserCreatorChatParticipantRepository.kt` | HTTP open 상대 프로필만 `findActiveOpponentProfile(roomId, memberId, lang)` JOIN projection 사용. 송신 검증에서 필요한 원본 `findActiveOpponent`는 유지 |
| `v2/usercreatorchat/repository/UserCreatorChatRoomRepository.kt`; `v2/chat/service/ChatRoomListService.kt` | DM opponent 목록이 요청 Lang 이름을 직접 조인. 통합 목록 서비스의 이름-only batch/copy와 resolver 주입 제거. 활성 참여자·최신 메시지·팔로우·cursor·AI/DM 병합 순서 유지 |
| `v2/chat/dto/ChatRoomListDtos.kt`; `chat/room/repository/ChatRoomRepository.kt` | batch 전용 내부 `opponentMemberId` 제거, 공유 query DTO는 7필드. AI select-new도 동일 생성자로 맞추고 `pc.character.name` 그대로 선택. AI creator alias는 캐릭터 이름으로 사용하지 않음 |
### Cross-Owner 및 내부 계약
- 기반은 제공된 `CreatorNameJoin(owner: QMember, lang: Lang, alias: String)`의 `name/condition/displayName`과 `CreatorLocalizedNameService.findCurrentNames(ids, lang)`를 사용한다. 기반 파일은 수정하지 않았다. `LiveRoomService.findCurrentNames`는 이제 core의 단일 JOIN SELECT에 위임한다.
- Live recommendation/list/donation/heart/reservation/visitor repository의 표시 query에는 필수 `Lang`을 전달한다. 기존 HTTP 서비스 경계의 `LangContext`가 선택하며 외부 `api/live`, `api/home` 호출 signature는 유지한다.
- `ChatRoomListService.getRooms(member, lang, filter, cursor, limit, followedCreatorsOnly)`는 그대로다. v2 writer 소유 `HomeFollowingFacade`의 기존 명시 Lang 호출은 수정할 필요가 없다. 공유 AI repository에서는 위 7-field query DTO 생성자만 조정했다.
- DM repository의 `findDmChatListRooms`는 `followedCreatorsOnly` 다음, `pageable` 앞에 필수 `lang: Lang`을 받는다. history는 `findMessageHistory(chatRoom, cursor: Long?, lang: Lang, pageable)`로 통합했다. JPQL `:lang`에는 enum 객체를 전달하고 CREATOR role은 실제 `MemberRole.CREATOR` enum literal로 ON에 둔다. 문자열 `"EN"`/`"CREATOR"`로 Hibernate enum 인자를 우회하지 않는다.
- 중립 종료-live repository cache에는 Lang 인자를 추가하지 않았다. 기존 `getLatestFinishedLive:{memberId or guest}` key/10분 TTL과 raw DTO entry는 유지하며, miss/hit 모두 서비스에서 현재 이름을 렌더링한다.
### 잔여 Batch 전수 목록
현재 소유 소스의 `findLocalizedNames` 직접 호출은 아래 **9곳**, 현재 원본까지 필요한 호출은 `LiveRoomService.findCurrentNames`의 core 위임 **1곳**으로 수렴한다. 단순 DB 목록을 이미 materialized됐다는 이유로 남긴 예외는 없다.
| 경계 | 정확한 호출 위치 | 남기는 이유/보존 의미 |
|---|---|---|
| 중립 live membership | `live/room/LiveRoomService.kt#getRoomInfo` → `findCurrentNames` | Redis speaker/listener/manager와 host ID를 한 번에 현재 이름으로 렌더링. 복사본의 role, 원본 membership 및 금융/권한 객체 보존 |
| 중립 live 상세 참가자 | 같은 파일 `getRoomDetail`의 on-air Redis branch → `findCurrentNames` | Redis 참가자만 한 번 렌더링. host와 예약 전 DB booker branch는 JOIN으로 전환되어 이 batch에 포함되지 않음 |
| 중립 live feed | 같은 파일 `getDonationMessageList` → `findCurrentNames` | donation/roulette Redis feed를 기존 secret 필터 후 복사. UUID/본문/공유 원본 보존 |
| 중립 read-through cache | 같은 파일 `getLatestFinishedLive` → `findCurrentNames` | raw 캐시 재사용 후 한 JOIN SELECT로 현재 원본+해당 언어 이름 조회. 원본 변경/별칭 해제도 캐시의 옛 이름으로 fallback하지 않음 |
| 이미 검증에 필요한 원본 entity | 같은 파일 `enterLive`의 차단/참여제한 오류 2곳 → `findLocalizedNames` | 원본 room/host로 입장 검증 후 오류 문구만 sparse override. principal/host 원본은 불변 |
| 쓰기 반환 | `live/reservation/LiveReservationService.kt#makeReservation` → `findLocalizedNames` | 가격/결제/예약에 이미 필요한 room/owner 원본을 보존하고 생성 응답 이름만 렌더링 |
| 쓰기 검증 오류 | `message/MessageService.kt#sendTextMessage`, `sendVoiceMessage` → `findLocalizedNames` | 이미 검증한 recipient를 변경하지 않고 blocked 오류 문구만 렌더링. DB history는 batch 없음 |
| ACK/쓰기 반환 | `v2/usercreatorchat/service/UserCreatorChatService.kt#sendTextMessageByWebSocket`, `deliverRestMessage` → `findLocalizedNames` | 명시 sender-session Lang/HTTP Lang별 응답만 sparse 렌더링. 원본 신규 메시지와 neutral pubsub/FCM snapshot은 별도 유지 |
| 수신자별 전달 | `fcm/FcmEvent.kt#FcmSendListener.sendPush` → `findLocalizedNames` | recipient Lang 그룹마다 sender/title/name-args ID 합집합의 sparse map 사용. 명시 snapshot/profile/raw/default fallback을 유지하며 current-name 조회로 바꾸지 않음 |
| 세션별 전달 | `v2/usercreatorchat/websocket/UserCreatorChatRoomMessageBroker.kt#onMessage` → `findLocalizedNames` | 같은 수신자의 복수 세션 Lang별 독립 payload. publisher payload가 이미 있으므로 DB JOIN 강제 없음 |
`PushNotificationListRepository`/`PushNotificationService`의 이미 렌더된 과거 `senderNicknameSnapshot` 목록은 변경하지 않았다. FCM title owner/name-argument metadata도 그대로다. `LiveRecommendCacheService`의 3시간 banner payload에는 이름이 없으며 변경하지 않았다. 예약 booker의 raw `Member` 조회는 취소/환불 등 기존 업무용이고 표시 이름 batch 호출이 아니다.
### 테스트 변경과 직렬 실행 인계
아래 test 경로의 공통 prefix는 `src/test/kotlin/kr/co/vividnext/sodalive/`다. 새 테스트 및 단언은 아직 실행하지 않았다.
- `live/room/LiveRoomLocalizedNameIntegrationTest.kt`: 기존 추천 RED 단언 유지. 추천·팔로잉 전체에서 standalone name SELECT 금지, 활성 EN 읽기, NOW/날짜 예약/예정 목록 및 예약 booker/list/detail의 USER/미등록/비활성 행 보존과 query count 보강. 예약 read 2회/방문 read 2회/후원+하트 3회 단언. 실제 종료 cache의 raw entry와 room query 1회 재사용을 유지하고 KO/JA/EN current-name 조회는 매 호출 1회 단언.
- `message/MessageServiceLocalizedNameTest.kt`: 기존 JA/KO/EN·본문·USER·voice 검증 보존. 6개 목록의 활성 EN 및 USER alias 무시, 비활성 fallback, count+list 합계 12회와 entity load 0 단언 추가.
- 신규 `v2/usercreatorchat/UserCreatorChatNameJoinRepositoryTest.kt`: 실제 JPQL/DB로 모든 Lang의 DM 목록/history/opponent-profile 이름·USER/미등록/비활성 fallback, 한 query/entity load 0, inactive 메시지 제외와 history cursor 검증. 실제 AI/DM 통합 service+repositories로 AI 이름 불변·EN DM·팔로우·페이지 cursor 및 두 페이지 총 query 4회 검증. Redis가 불필요한 `@DataJpaTest`이며 새 mock 없음.
- `live/recommend/LiveRecommendRepositoryTest.kt`; `live/recommend/LiveRecommendServiceTest.kt`; `live/room/LiveRoomServiceAdultVisibilityPolicyTest.kt`; `v2/usercreatorchat/UserCreatorChatServiceTest.kt`; `v2/chat/ChatRoomListServiceTest.kt`: 변경된 필수 Lang/projection/생성자 계약에 적응. 제거된 이름 서비스에 빈 optional stub/호환 생성자를 추가하지 않았다.
- 기존 실제 localhost HTTP/WS/Redis 통합 테스트, FCM outbound/S3 mock 테스트 및 관리자 쓰기 정책 테스트는 삭제·완화하지 않았다.
부모 전용 명령이며 병렬 작업이 모두 끝난 뒤 **한 Gradle runner에서 직렬 실행**한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.live.room.LiveRoomLocalizedNameIntegrationTest' --tests 'kr.co.vividnext.sodalive.message.MessageServiceLocalizedNameTest' --tests 'kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatNameJoinRepositoryTest' --offline --console=plain
./gradlew test --tests 'kr.co.vividnext.sodalive.live.*' --tests 'kr.co.vividnext.sodalive.message.*' --tests 'kr.co.vividnext.sodalive.fcm.*' --tests 'kr.co.vividnext.sodalive.v2.usercreatorchat.*' --tests 'kr.co.vividnext.sodalive.v2.chat.*' --tests 'kr.co.vividnext.sodalive.v2.api.home.following.*' --offline --console=plain
./gradlew test build ktlintCheck --continue --offline --console=plain
```
정적 확인: 변경 메서드의 전체 호출부와 direct mock 생성자를 `rg`로 대조했다. 소유 코드에서 `findNicknamesByIds`, `findMessageNames`, `localizeChannels`, `opponentMemberId`, `LiveRoomHeartListRow` 참조는 제거됐다. 변경 파일의 130자 초과/후행 공백을 점검했다. LSP 도구는 제공되지 않았으며 compile/JPQL 실행/테스트 통과 및 실제 HTTP/WS 동작은 부모 직렬 검증 전까지 주장하지 않는다. 외부 앱/RTC/provider/운영 DB blocker는 그대로다.
@@ -1,480 +0,0 @@
# Legacy HTTP·검색 크리에이터 이름 적용 목록
## COR021 최신 범위
- ContentSeriesRepository의 목록 이름JOIN5곳과 ContentSeriesService 상세이름batch1곳을 HEAD로 되돌린다. 이 레거시 서비스 재사용자인 Home/Explorer의 시리즈 작성자 이름도 원본으로 돌아가며 기존 제목/장르/요일 번역은 유지한다.
- 공통 이름 기반과 별도v2·관리자 조회는 유지한다. 직접 관련된 AudioContentRepositoryLocalizedNameTest의 시리즈case는 이름단언만 정리하고 제목 번역/fallback을 보존한다. 최신 검증은 plan-task.md SERIES-NAME-TRIM-T1을 따른다.
- 적용 완료: 운영2파일HEAD일치, 제목검증case유지, 실제 시리즈·Home HTTP 및 전체2270건/lint통과를 확인했다. 영구테스트수증감은 없고 임시검증코드는 제거했다.
## COR020 최신 범위
- L42 CharacterCommentService/Repository 이름 변경을 HEAD로 되돌리고 해당 이름 대체 통합테스트1개만 제거한다. 댓글 작성·삭제·신고·권한·커서·건수·언어 감지와 다른 테스트는 유지한다.
- 실제 제거 대상은 LegacyCurrentNameReadIntegrationTest의 shouldLocalizeCharacterCommentWritersWithoutChangingCharacterNameOrUserReplies이며 T20 신규 예정 별도 파일은 생성되지 않았다. 아래 이력과 구분하고 최신 검증은 plan-task.md CHARACTER-COMMENT-TRIM-T1을 따른다.
- 적용 완료: 운영2파일HEAD일치, 전용test1건 제거 후 전체2270건/lint통과. 실제 댓글·답글·상세HTTP10요청도 확인했고 임시 검증 코드는 제거했다.
## COR019 최신 범위
- AudioContentMainController/Service의 이름 변경을 롤백하고 두 파일의 HEAD diff를 제거한다. L24의 전용 findByThemeFor2Weeks/findAudioContentByCurationId 이름 추가분과 L25·메인 큐레이션의 controller cache-hit 후 이름 batch를 제거한다.
- shared findByTheme는 AudioContentThemeService가 계속 사용하므로 유지한다. 전용 Main 테스트는 현재 없으며 T09는 계획 이력이다. 다른 실제 조회의 테스트는 삭제하지 않는다. 자세한 검증은 plan-task.md LEGACY-MAIN-T1을 따른다.
- 적용 완료: 두 메인 파일 HEAD와 동일, repository 전용2메서드 롤백. 임시 실제 HTTP5요청 통과 후 검증 코드는 제거했고 기존 전체2271건 및 lint 통과를 확인했다. 영구 테스트 증감은 없다.
## COR017 최신 범위
- AudioContentMainTab*은 사용자 확인상 미사용이다. 해당 7개 서비스 파일은 HEAD와 같은 상태로 되돌리고 이름 원본 보장을 위한 null 인자·공유 raw 모드·전용 검증을 제거한다. 공유 조회 변경의 미사용 탭 간접 영향은 허용한다.
- 실제 사용 중인 Main/Theme/Home 조회의 언어별 이름과 제목 번역은 유지한다. AudioContentCuration 및 레거시 커뮤니티·팬톡 등 나머지 COR015 범위는 바꾸지 않는다.
- 아래 COR015의 탭 raw 보장 규칙은 당시 이력이며 이 절로 대체한다. 구체 파일·검증은 plan-task.md UNUSED-TAB-T1을 따른다.
## COR015 현재 범위 보정
- 아래 COR012/COR013 표와 실행 기록은 과거 이력이다. 현재 범위는 PRD COR015가 우선한다. 이번 후속 변경은 코드·테스트 정리 및 정적 검토만 하며 실행 검증은 금지되어 있다.
- L13/L14 레거시 팬톡, L26~L30 큐레이션·탭, L37~L39 레거시 커뮤니티의 이름 표시 적용을 제거한다. API·기존 번역·권한·저장·알림 업무는 유지한다.
- L17/L18/L24/L31의 공유 조회는 호출자별로 구분한다. 제외된 탭/큐레이션은 원본 이름을 받고, 다른 API의 언어별 이름과 제목·본문 번역은 유지한다. 원본 경계는 KO 언어를 의미하지 않는다.
- `LegacyCreatorNameRenderer`는 제거하고 필요한 소비자는 `CreatorLocalizedNameService`를 직접 주입한다. T22 래퍼 전용 테스트는 제거하되 실제 core batch의 SQL 수·빈 입력·역할·현재 원본 fallback 회귀는 core 테스트에 보존한다.
- T04/T17의 레거시 별칭 기대값은 원본 경계에 맞춰 최소 보정한다. 검색·프로필·후원·기타 유지 대상의 별칭 테스트, characterization·번역·권한 테스트, v2 테스트는 삭제하지 않는다. 불필요한 테스트 설정 import와 제거된 생성자 인자만 정리한다.
## 단계와 계약
- 기준: 같은 디렉터리 `prd.md`의 NAME002~006 및 COR012, `plan-task.md`의 P2-T1/P2-T2.
- 현재 단계는 **legacy GREEN 소스 연결 및 정적 계약 감사, 부모 직렬 검증 대기**다. 아래 첫 테스트 단계 기록은 보존하며 구현 연결 결과는 마지막 절에 누적한다. runtime PASS나 제품 완료 기록이 아니다.
- 첫 단계에서는 `src/main`을 수정하지 않았다. 후속 부모 지시로 이번에는 legacy 소스·constructor fixture·추가 회귀를 작성했다. main PRD/plan, foundation/v2/async 소스, 운영 DDL은 수정하지 않았고 Gradle·커밋·푸시도 수행하지 않았다.
- 범위: non-v2 현재 앱 HTTP 표시·검색. `content/main/tab/replay`는 라이브 오디오 콘텐츠 탭이므로 포함한다.
- 별도 slice: `fcm/*`, `live/*`, `message/*`와 비동기 발송. `admin/*`, `creator/admin/*`, `partner/*`, auth/login 원본 이름은 수정 제외한다. 공유 `Series` 엔티티를 읽는 앱 서비스는 포함하되 creator-admin 응답은 바꾸지 않는다.
- 공통 구현은 `kr.co.vividnext.sodalive.v2.creatorname.application.CreatorLocalizedNameService.findLocalizedNames(Collection<Long>, Lang): Map<Long, String>`이다. JA 활성 CREATOR만 이름 map에 포함하고 나머지는 기존 원본을 사용한다.
- 응답 조립 직전 실제 owner member IDs를 모아 batch 조회한다. `LangContext`는 HTTP 경계에서만 읽고 내부 호출에는 명시 `Lang`을 전달한다. 행별 이름 조회, `Member.nickname` 변이, principal 변이, 공통 entity getter, 전역 Jackson 변환은 금지한다.
- 공개 DTO field 이름·타입은 보존한다. content/series/cheers/post/order/receipt/character ID를 이름 map key로 쓰지 않는다. owner ID가 없는 projection은 내부 record로 보충하고 HTTP에는 새 필드를 노출하지 않는다.
- 검색은 요청 언어와 무관하게 기존 nickname 조건 **OR 활성 JA alias EXISTS**다. alias는 owner `member_id`, `lang=JA`, `is_active=true`, owner `role=CREATOR`로 상관시킨다. 제목·소개·본문·태그·장르 조건과 기존 visibility/block/requester/count/page 조건은 바꾸지 않는다.
## 이번에 작성한 테스트와 RED 인계
아래 경로는 저장소 루트 기준이다. 모두 기존 실제 API/repository를 호출하며 미래 production helper나 reflection 없이 동작한다. 별칭 fixture는 회원을 flush한 뒤 `JdbcTemplate`으로 `creator_localized_name(member_id, lang, display_name, is_active, created_at, updated_at)`에 넣는다. foundation의 entity 매핑으로 생성되는 테스트 테이블을 사용하며 수동 CREATE TABLE을 하지 않는다. USER/EN 행은 관리 API로 생성할 수 없는 오염 데이터까지 읽기 경계가 방어하는지 검사하는 fixture다.
| Owner | 실제 테스트 파일 | 사례 수 | 보호하는 동작 / 의도된 RED |
|---|---|---:|---|
| T01 | `src/test/kotlin/kr/co/vividnext/sodalive/search/SearchRepositoryLocalizedNameTest.kt` | 5 | original OR JA alias, containsIgnoreCase, 동일 회원 양쪽 매칭 중복 없음, 중복 별칭 owner 분리, list/count/page 일치, soft clear 및 동일 행 재활성화. creator 활성/role/태그 활성/양방향 차단, content 성인/활성/duration/limited/차단, series 성인/episode 성인/활성/duration/차단/조인 중복 유지. content/series title 불변 및 series owner와 episode owner 구분. 미구현 alias list/count assertion에서 실패해야 한다. |
| T02 | `src/test/kotlin/kr/co/vividnext/sodalive/explorer/ExplorerQueryRepositoryLocalizedNameTest.kt` | 2 | KO 채널 검색에서도 JA alias, 원본 유지, CREATOR/self/isActive 필터 및 중복 없음, soft clear/EN 제외와 재활성화. 미구현 alias-only hit에서 실패해야 한다. |
| T03 | `src/test/kotlin/kr/co/vividnext/sodalive/member/MemberRepositoryLocalizedNameTest.kt` | 3 | CREATOR requester의 USER 원본 매칭 유지, USER requester의 USER 제외, ADMIN/AGENT/BOT/self 제외, USER+AI_CHARACTER 별칭 제외, soft clear/EN 제외 및 원본 변경 후 재활성화. CREATOR alias hit 누락에서 실패해야 한다. 해당 repository에는 현재 count API가 없으므로 가상의 count API를 만들지 않는다. |
| T04 | `src/test/kotlin/kr/co/vividnext/sodalive/explorer/ExplorerLocalizedNameEndToEndTest.kt` | 3 | 실제 MockMvc HTTP: JA profile/detail 이름, CREATOR 팬톡 부모/답글과 USER 작성자 혼합, KO/EN 원본, 원본 변경 뒤 별칭 유지 및 clear/missing fallback. `/search` creator `title`+`nickname` JA, content/series 제목 불변·실제 owner 이름 JA, KO `/search/creators` alias hit. 기존 원본 vs 별칭 응답 assertion에서 실패해야 한다. |
| T05 | `src/test/kotlin/kr/co/vividnext/sodalive/content/AudioContentRepositoryLocalizedNameTest.kt` | 2 | 실제 `getLatestContentByTheme(locale=ja)`가 content ID와 다른 owner ID로 JA creatorNickname을 반환, USER 유지, KO/EN 원본, 제목 불변. 공개/미래/성인/활성/duration/차단 필터 유지와 원본 변경 후 soft clear fallback. 현재 원본 vs 별칭 ownername assertion에서 실패해야 한다. |
### 부모 실행 명령
아래 명령은 **아직 실행하지 않았다**. foundation 파일 저장 및 foundation 검증이 끝난 뒤 부모가 순서대로 실행한다. RED는 compile/context/fixture 오류가 아니라 위 요구 동작 assertion 실패여야 한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.search.SearchRepositoryLocalizedNameTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.ExplorerQueryRepositoryLocalizedNameTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.member.MemberRepositoryLocalizedNameTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.content.AudioContentRepositoryLocalizedNameTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.ExplorerLocalizedNameEndToEndTest'
```
T01/T02는 기존 constructor로 QueryDSL repository를 직접 만든다. GREEN에서 dependency가 추가되면 테스트 constructor도 명시적으로 맞춘다. T03/T05는 JPA slice다. GREEN에서 공통 service/adapter dependency를 주입할 경우 해당 slice의 `@Import`를 명시적으로 보완한다. T04는 `@SpringBootTest`+MockMvc이며 기존 `EmbeddedRedisInitializer` opt-in, rollback 트랜잭션과 독립 H2 DB를 사용한다. T05도 독립 H2 DB로 owner/resource ID fixture 충돌을 피한다.
## 전체 source edit map
아래 모든 소스 경로의 공통 prefix는 `src/main/kotlin/kr/co/vividnext/sodalive/`다. 각 셀은 그 prefix 아래 **정확한 경로**이며 wildcard 변경 지시가 아니다. `CURRENT`는 요청 시 현재 이름 조회, `NEUTRAL-CACHE`는 언어 중립 응답 캐시, `RAW`는 원본 편집·인증 경계, `IMMUTABLE`은 기존 역사 값/발송물을 뜻한다. Test owner T01~T05는 이번에 작성했고 T06 이후는 후속 GREEN 전에 추가할 명시적 테스트 소유자다.
### 검색·회원·탐색
| ID | 실제 경로와 심볼 / caller | 응답 타입·이름 및 실제 owner | 유형·언어 / 최소 수정 경계 | Test owner |
|---|---|---|---|---|
| L01 | `search/SearchRepository.kt`: `searchCreatorList`, `searchCreatorTotalCount`; `search/SearchService.kt`: `searchUnified`, `searchCreatorList`; `search/SearchController.kt` | `SearchResponseItem.id=member.id`; **creator branch의 `title`와 `nickname` 모두 이름** | CURRENT. list/count에 같은 alias EXISTS. service 응답 조립에서 Lang별 batch map으로 두 이름 field만 대체. | T01, T04; 기존 `search/SearchServiceTest.kt` constructor 회귀 |
| L02 | 같은 `search/SearchRepository.kt`: `searchContentList`, `searchContentTotalCount`; `search/SearchService.kt`: `searchContentList`, `searchUnified` | `SearchResponseItem.id=audioContent.id`; `nickname=audioContent.member.nickname`. **owner ID projection 없음** | CURRENT. 원본 nickname branch만 OR alias로 확장. 내부 owner ID projection 추가; content title/detail/theme/hashTag predicates·adult/gender/duration/limited/block/count/group/page 유지. | T01, T04 |
| L03 | 같은 `search/SearchRepository.kt`: `searchSeriesList`, `searchSeriesTotalCount`; `search/SearchService.kt`: `searchSeriesList`, `searchUnified` | `id=series.id`; `nickname=series.member.nickname`. **owner ID projection 없음**, episode owner와 series owner는 다를 수 있음 | CURRENT. series owner 상관 alias; episode content visibility/gender 조건과 title/introduction/genre/keyword/group/count/page 유지. 내부 owner ID 필요. | T01, T04 |
| L04 | `explorer/ExplorerQueryRepository.kt`: `getSearchChannel`; `explorer/ExplorerService.kt`: `getSearchChannel`; `explorer/ExplorerController.kt` | `GetRoomDetailUser.nickname`, 반환 Member의 `id` | CURRENT. query original OR alias, 활성 CREATOR/self 제외 유지; service의 양방향 차단 후 응답 mapping에서 batch. DTO 파일이 `live/room/detail`에 있어도 전역 constructor는 변경하지 않는다. | T02, T04 후속 channel HTTP 사례 |
| L05 | `member/MemberRepository.kt`: `MemberQueryRepositoryImpl.findByNicknameAndOtherCondition`; `member/MemberService.kt`: `searchMember`; `member/MemberController.kt` | 혼합 `GetRoomDetailUser.nickname`, 결과 Member `id` | CURRENT. creator alias만 OR, ADMIN/AGENT/BOT/self 제외 및 requester USER의 USER 제외 유지. 현재 query에 isActive/count 조건은 없으므로 이번 작업에서 임의 추가하지 않음. service 양방향 block 유지·배치 표시. | T03, T06 |
| L06 | `member/MemberRepository.kt`: `getMemberProfile`; `member/MemberService.kt`: `getMemberProfile` | `GetMemberProfileResponse.nickname`; 대상 `memberId`가 owner, `myMemberId`는 차단 조건 | CURRENT. 기존 대상 ID로 batch하여 응답 대체. | T06 |
| L07 | `member/MemberService.kt`: `getMyPage`; `member/myPage/MyPageResponse.kt` | `MyPageResponse.nickname`, 인증 Member `id` | CURRENT display. principal을 바꾸지 말고 DTO에서만 alias 적용. raw editor의 `ProfileResponse`와 구분. | T06 |
| L08 | `member/block/BlockMemberRepository.kt`: `getBlockedMemberList`; `member/MemberService.kt`: `getBlockedMemberList` | `GetBlockedMemberListItem.nickname`, blockedMember `id` | CURRENT 혼합 목록. blocked member owner IDs로 batch, 기존 block 활성·member 활성/count 유지. | T06 |
| L09 | `explorer/ExplorerService.kt`: `getExplorer`, `getCreatorRank`; `explorer/ExplorerQueryRepository.kt`: `getCreatorRankings`, `getNewCreators`, `findCreatorByGender` | `GetExplorerSectionCreatorResponse.nickname`, 해당 Member `id` | CURRENT. `CreatorRanking`은 순위/member 참조만 저장하며 nickname snapshot 아님. 기존 `Member.toExplorerSectionCreator` 전역 변경 대신 service 조립 DTO에서 batch. | T04 후속 섹션 사례; 기존 `explorer/ExplorerServiceTest.kt` |
| L10 | `explorer/ExplorerService.kt`: `getCreatorProfile`, `getCreatorDetail` | `CreatorResponse.nickname`, `GetCreatorDetailResponse.nickname`, `creatorAccount.id` | CURRENT. 기존 `langContext.lang`을 명시 Lang로 공통 service에 전달. profile creator와 중첩 하위 service 결과를 각각 실제 owner로 처리. 이름을 넣는 blocked-access 메시지도 같은 creator 표시 계약 대상, auth 식별값 아님. | T04 |
| L11 | `explorer/ExplorerQueryRepository.kt`: `getSimilarCreatorList`, `getRandomCreatorList`; `explorer/ExplorerService.kt`: `getCreatorProfile` | `SimilarCreatorResponse.nickname`, `userId=후보 creator member.id` | CURRENT. 이미 owner ID 보유. profile assembly에서 batch; random/order/tag/fallback query 로직 변경 없음. | T04 후속 similar creator 사례 |
| L12 | `explorer/ExplorerQueryRepository.kt`: `getFollowerList`; `explorer/ExplorerService.kt`: `getFollowerList` | `GetFollowerListDto` / `GetFollowerListResponseItem.nickname`; `userId=팔로워 member.id`, creatorId 아님 | CURRENT 혼합 목록. role/ID 보유; follower DTO 조립에서 batch. count·block·follow/notify 의미 유지. | T04 후속 follower 사례 |
| L13 | `explorer/ExplorerQueryRepository.kt`: `getCheersList`; `explorer/ExplorerService.kt`: `getCreatorProfileCheers`, `getCreatorProfile` | `GetCheersResponseItem.nickname`, 부모·답글 각각 `memberId=writer.id`; `cheersId/creatorId` 아님 | CURRENT 혼합 작성자. 부모·답글 ID를 한 번에 모아 batch, `removeDeletedNicknamePrefix()` 원본 fallback 유지. 날짜·parent·block·count·pagination 유지. | T04 |
| L14 | `explorer/ExplorerService.kt`: `writeCheers`, `modifyCheers` | HTTP `CreatorChannelFanTalkResponse.writerNickname`, `creatorReplies[].writerNickname`; 각각 writer member ID | CURRENT HTTP 쓰기 응답. 공유 v2 `from` factory 전역 수정하지 말고 legacy caller에서 응답 대체; async event는 후속 slice. | T04 후속 쓰기 응답 사례; 기존 `explorer/ExplorerServiceTest.kt`, `explorer/ExplorerControllerTest.kt` |
### 홈·랭킹·추천·캐시
| ID | 실제 경로와 심볼 / caller | 응답 타입·이름 및 실제 owner | 유형·언어 / 최소 수정 경계 | Test owner |
|---|---|---|---|---|
| L15 | `api/home/HomeService.kt`: `fetchData`; `rank/RankingRepository.kt`: `getCreatorRankings` | `GetHomeResponse.creatorRanking[].nickname`, 순위 Member `id` | CURRENT. HomeService에 이미 `LangContext` 있음. follow state 유지, home의 creator DTO만 batch. | T07 |
| L16 | `rank/RankingService.kt`: `getCreatorRanking`, `fetchCreatorBySellContentCountRankTop20`, `fetchCreatorBySeriesRevenueRankTop20`; `rank/RankingRepository.kt`: 같은 이름의 query | explorer creator DTO 또는 `ContentCreatorResponse.creatorNickname`, `creatorId=member.id` | CURRENT 순위 materialization/집계의 **현재 이름**. 순위 데이터가 과거 기간 기준이어도 query가 현재 member를 join하므로 이름은 역사 snapshot 아님. service에서 batch. | T08 |
| L17 | `rank/RankingRepository.kt`: `getAudioContentRanking`, `fetchCreatorContentBySalesCountTop4`, `fetchCreatorContentByLikeCountTop4`, `fetchFreeContentByCreatorIdTop4`; `rank/RankingService.kt`: 대응 메서드 | `GetAudioContentRankingItem.creatorNickname`, `creatorId=member.id`; `contentId`는 별도 | CURRENT. repository에서 title 번역만 기존 locale로 처리, service에서 owner 이름 batch. `api/home/HomeService.getContentRankingBySort`와 모든 content tab caller까지 도달. | T08, T07, T09 |
| L18 | `rank/RankingService.kt`: `getSeriesRanking`, `getSeriesAllRankingByGenre`, `getCompleteSeriesRanking`, `fetchCreatorSeriesBySales`, `seriesToSeriesListItem`; `rank/RankingRepository.kt`: 대응 query | `GetSeriesListResponse.SeriesListItem.creator.nickname`, `series.member.id`, `seriesId` 아님 | CURRENT. 공통 series response assembly에서 batch, creator-admin Series entity·writer/studio 변경 없음. | T08, T09 |
| L19 | `query/recommend/RecommendChannelQueryRepository.kt`: `getRecommendChannelList`; `query/recommend/RecommendChannelQueryService.kt`: `getRecommendChannel`; `api/home/HomeService.kt`: `fetchData` | `RecommendChannelResponse.creatorNickname`, `channelId=member.id`; contentList resource ID와 별도 | NEUTRAL-CACHE. `@Cacheable(default)` key는 `recommendChannel:{memberId 또는 guest}:{isAdult}:{contentType}`로 Lang 없음. cached raw response는 공유 DTO 변이 없이 **cache hit 이후 caller에서 copy+batch**하여 현재 이름 적용. 캐시 안에 JA를 저장하거나 cached DTO를 mutate하면 KO/JA 오염. 이미 존재하는 content title locale cache 문제와 이름 변경을 혼동하지 않음. | T07, T10 |
| L20 | `explorer/profile/CreatorDonationRankingQueryRepository.kt`: `getMemberDonationRanking`; `explorer/profile/CreatorDonationRankingService.kt`: `getMemberDonationRanking`; `explorer/ExplorerService.kt`: profile/donation ranking | `MemberDonationRankingResponse.nickname`, **donor 응답 `userId`**(query record는 `memberId`), 순위 대상 creatorId 아님 | NEUTRAL-CACHE. query→response→Redis list write→cache hit 반환 양쪽 확인. key `creator_donation_ranking_v2:{creatorId}:{period}:{offset}:{limit}:{withDonationCan}`, TTL 다음 월요일, Lang 없음. legacy 응답 조립에서 hit/miss 모두 donor IDs로 copy+batch. count 캐시는 숫자뿐이므로 이름 변경 없음. v2 adapter consumer는 별도 slice. | T11, T04 후속 donor 사례 |
| L21 | `explorer/ExplorerQueryRepository.kt`: `getMemberDonationRanking` | `MemberDonationRankingResponse.nickname`, donor `account.id` | CURRENT. 현재 ExplorerService는 L20의 service를 호출하므로 이 메서드는 legacy direct query 경로의 남은 raw projection이다. 실제 앱 caller가 추가되지 않으면 불필요한 독립 수정은 하지 않음. | T11, source caller 확인 |
L19/L20의 cache hit에서는 alias map에 값이 없을 때 cached nickname을 곧바로 **현재 원본**이라고 간주하면 안 된다. 원본 변경 후 soft clear가 일어나면 cached 원본도 stale할 수 있다. 후속 구현은 cache hit 이후 owner IDs로 현재 Member 원본을 batch 재조회하는 경계(`member/MemberRepository.kt`의 scalar `findNicknamesByIds`)를 두고 현재 원본 fallback과 alias map을 함께 응답에 적용한다. 캐시 entry/과거 record를 재작성하지 않는다. T10/T11에 원본 변경→alias clear→같은 cache hit의 current fallback 사례를 포함한다.
### 오디오·시리즈·메인 탭·주문·플레이리스트
| ID | 실제 경로와 심볼 / caller | 응답 타입·이름 및 실제 owner | 유형·언어 / 최소 수정 경계 | Test owner |
|---|---|---|---|---|
| L22 | `content/AudioContentService.kt`: `getDetail`; `content/AudioContentRepository.kt`: `findByIdAndActive`; `explorer/ExplorerQueryRepository.kt`: `getMember` | `GetAudioContentDetailResponse.creator.nickname` / `AudioContentCreator`, `audioContent.member.id` | CURRENT. 상세 조립에서 creator owner batch, 기존 title/detail/theme 번역과 접근/구매/visibility 유지. | T12; 기존 `content/AudioContentServiceTest.kt` |
| L23 | `content/AudioContentRepository.kt`: `getLatestContentByTheme`; `content/AudioContentService.kt`: `getLatestContentByTheme`; `api/home/HomeService.kt`: latest/free/point/recommend buckets | `AudioContentMainItem.creatorNickname`, `creatorId=member.id`, contentId와 별도 | CURRENT. query method가 `locale`를 이미 받으며 translated-title tuple와 locale-null projection 두 경로 모두 이름 대응 필요. tuple 응답 조립에 명시 Lang의 batch map 사용; service/홈 caller는 현재 locale 전달 유지. title 번역과 owner name 분리. | T05, T07 |
| L24 | `content/AudioContentRepository.kt`: `findByTheme`, `findAlarmContentByTheme`, `findByThemeFor2Weeks`, `findAudioContentByCurationId`, `findAudioContentByCurationIdV2`, `findContentByCurationId`, `getAudioContentRanking`; `content/main/AudioContentMainService.kt`: `getNewContentByTheme`, `getNewContentFor2WeeksByTheme`, `getAudioContentMainBannerList`, `getAudioContentCurationListWithPaging`; `content/AudioContentService.kt`: `getAudioContentRanking` | `GetAudioContentMainItem.creatorNickname` / `GetAudioContentRankingItem.creatorNickname`, `creatorId=member.id` | CURRENT. 각 owner ID는 기존 projection 보유. 해당 service assembly에서 batch 또는 명시 Lang를 query 응답 조립까지 전달. 필터/count/정렬 변경 금지. | T09, T12; T05는 대표 query이고 이 행 전체 검증을 대체하지 않음 |
| L25 | `content/AudioContentRepository.kt`: `getNewContentUploadCreatorList`; `content/main/AudioContentMainService.kt`: `getNewContentUploadCreatorList` | `ContentCreatorResponse.creatorNickname`, `creatorId=member.id` | CURRENT. service에서 batch, creator별 contentList 기존 로직 유지. | T09 |
| L26 | `content/main/curation/AudioContentCurationQueryRepository.kt`: `findByCurationId`; `content/main/curation/AudioContentCurationService.kt`: `getCurationContent`, `getContentCurationList` | `GetAudioContentMainItem.creatorNickname`, `creatorId=member.id` | CURRENT. curation ID를 owner로 쓰지 않음. service에서 batch; active/genre/adult/block/count 유지. | T09 |
| L27 | `content/main/tab/content/ContentMainTabTagCurationRepository.kt`: `getTagCurationContentList`; `content/main/tab/content/ContentMainTabTagCurationService.kt`: `getTagCurationContentList` | `GetAudioContentMainItem.creatorNickname`, `creatorId=member.id` | CURRENT. tag curation content query caller에서 명시 Lang+batch. | T09 |
| L28 | `content/main/tab/AudioContentMainTabRepository.kt`: `findCreatorByThemeContent`, `findCreatorWithHasFreeContent` | `ContentCreatorResponse.creatorNickname`, `creatorId=member.id` | CURRENT. caller는 `content/main/tab/asmr/AudioContentMainTabAsmrService.kt`, `content/main/tab/replay/AudioContentMainTabLiveReplayService.kt`, `content/main/tab/free/AudioContentMainTabFreeService.kt`의 `fetchData`. 배치 표시 후 creator별 인기 콘텐츠는 L17을 재사용. | T09 |
| L29 | `content/main/tab/RecommendSeriesRepository.kt`: `getNewSeriesList`, `getRecommendSeriesList`; `content/main/tab/free/AudioContentMainTabFreeService.kt`, `content/main/tab/series/AudioContentMainTabSeriesService.kt`: `fetchData` | `GetRecommendSeriesListResponse.creatorNickname`, `creatorId=series.member.id` | CURRENT. 추천 row의 ID/seriesId가 아닌 creatorId로 service batch. | T09 |
| L30 | `content/main/tab/home/AudioContentMainTabHomeService.kt`, `content/main/tab/content/AudioContentMainTabContentService.kt`, `content/main/tab/alarm/AudioContentMainTabAlarmService.kt`, `content/main/tab/series/AudioContentMainTabSeriesService.kt` 및 L28의 세 service: `fetchData`와 개별 content/rank/creator/series 조회 메서드 | 중첩 content creatorNickname / series.creator.nickname / ContentCreatorResponse.creatorNickname | CURRENT. 각 nested producer L17/L18/L24~29/L31 적용 누락 확인. 기존 반환된 공통 DTO를 재로컬라이즈하거나 parent/tab ID로 lookup하지 않음. 별도 wildcard 리팩터링 없음. | T09 |
| L31 | `content/series/ContentSeriesRepository.kt`: `getSeriesListV2`, `getSeriesByGenreListV2`, `getRecommendSeriesListV2`, `getOriginalAudioDramaList`, `findByCurationIdV2`, `getDayOfWeekSeriesListV2`; `content/series/ContentSeriesService.kt`: `getSeriesList`, `getSeriesListByGenre`, `getRecommendSeriesList`, `getOriginalAudioDramaList`, `fetchSeriesByCurationId`, `getDayOfWeekSeriesList` | `GetSeriesListResponse.SeriesListItem.creator.nickname`, `creatorId=series.member.id`; seriesId는 resource | CURRENT. **V2라는 메서드 이름이어도 non-v2 파일의 레거시 caller이므로 포함**. 기존 locale은 series title 번역용. 각 반환 목록 조립에서 owner batch; title/genre/price/adult/block/count/요일/정렬 유지. | T13, T07, T09; 기존 `content/series/main/SeriesMainControllerTest.kt` |
| L32 | `content/series/ContentSeriesService.kt`: `getSeriesDetail`; `content/series/ContentSeriesRepository.kt`: `getSeriesDetail` | `GetSeriesDetailResponse.creator.nickname`, `series.member.id` | CURRENT. 상세 DTO 조립에서 batch. `Series.writer`, `studio`, title/introduction/keyword는 creator nickname 아님. | T13 |
| L33 | `content/comment/AudioContentCommentRepository.kt`: `findByContentId`, `getAudioContentCommentReplyList`; `content/comment/AudioContentCommentService.kt`: `getCommentList`, `getCommentReplyList`; `content/AudioContentService.kt`: `getDetail` | `GetAudioContentCommentListItem.nickname`, `writerId=comment.member.id` | CURRENT 혼합 작성자. parent/child 각 writer ID batch; 상세의 commentList도 포함. deleted-prefix fallback, active/block/secret/count/page 유지. blocked-by-creator HTTP 에러의 이름도 creator owner로 표시, FCM args는 제외. | T14, T12 |
| L34 | `content/order/OrderRepository.kt`: `getAudioContentOrderList`, `getAudioContentMainOrderList`; `content/order/OrderService.kt`: 대응 메서드 | `GetAudioContentOrderListItem.creatorNickname` / `GetAudioContentMainItem.creatorNickname`, audioContent owner `creatorId` | CURRENT. 주문 날짜는 역사지만 이름은 query가 현재 Member를 join함. service 응답 batch, KEEP/RENTAL/expiry/isActive/count/page 유지. | T15 |
| L35 | `content/order/OrderRepository.kt`: `findBuyerListByContentId`; `content/AudioContentService.kt`: `getDetail`; `content/GetAudioContentDetailResponse.kt`: `ContentBuyer` | `ContentBuyer.nickname`, **order.member.id가 buyer owner**, 현재 projection은 nickname/profile만 있음 | CURRENT 혼합 구매자. content creator ID로 조회하면 오동작. 내부 buyer member ID record를 추가하고 상세 assembly batch, 공개 ContentBuyer 타입 보존. | T12, T15 |
| L36 | `content/AudioContentRepository.kt`: `fetchContentForPlaylist`; `content/playlist/AudioContentPlaylistService.kt`: `getPlaylistDetail`; `content/playlist/AudioContentPlaylist.kt`: `AudioContentPlaylistContent` | `AudioContentPlaylistContent.creatorNickname`, **projection owner ID 없음**; `id=content.id` | CURRENT. Redis playlist는 content IDs/order/endDate만 저장. getPlaylistDetail에서 SQL 현재 이름 재조회하므로 historical name snapshot 아님. 내부 memberId 추가하여 query→service batch. Redis 저장 record 이름 rewrite/새 필드 없음. | T16 |
### 커뮤니티·후원·사용 내역·캐릭터 작성자·오디션
| ID | 실제 경로와 심볼 / caller | 응답 타입·이름 및 실제 owner | 유형·언어 / 최소 수정 경계 | Test owner |
|---|---|---|---|---|
| L37 | `explorer/profile/creatorCommunity/CreatorCommunityRepository.kt`: `getCommunityPostList`, `getCommunityPost`, `getLatestPostListFromCreatorsYouFollow`; `explorer/profile/creatorCommunity/CreatorCommunityService.kt`: `getCommunityPostList`, `getCommunityPostDetail`, `getLatestPostListFromCreatorsYouFollow`; `explorer/profile/creatorCommunity/SelectCommunityPostResponse.kt`: `toCommunityPostListResponse` | `GetCommunityPostListResponse.creatorNickname` / `SelectCommunityPostResponse.creatorNickname`, post owner `creatorId` | CURRENT. 본문 번역과 별개로 이름 batch. postId/firstComment writer를 owner와 혼동하지 않음. paid mask/adult/pin/block/count 유지. 상세·구매 시 blocked message의 creator 이름도 HTTP current-display. | T17 |
| L38 | `explorer/profile/creatorCommunity/CreatorCommunity.kt`: `toCommunityPostListResponse`; `explorer/profile/creatorCommunity/CreatorCommunityService.kt`: `purchasePost` | 같은 `GetCommunityPostListResponse.creatorNickname`, entity `member.id` | CURRENT 구매 HTTP 응답. entity builder의 모든 호출을 전역 변경하지 말고 legacy service의 반환 DTO에서 override. v2/admin consumers는 별도 scope. | T17 |
| L39 | `explorer/profile/creatorCommunity/comment/CreatorCommunityCommentRepository.kt`: `findByPostId`, `getCommunityCommentReplyList`; `explorer/profile/creatorCommunity/CreatorCommunityService.kt`: `getCommunityPostCommentList`, `getCommentReplyList` 및 post list/detail의 firstComment | `GetCommunityPostCommentListItem.nickname`, `writerId=comment.member.id` | CURRENT mixed writer. 부모·reply·firstComment 각각 writer IDs batch, deleted-prefix/secret/block/count/page 유지. | T17 |
| L40 | `explorer/profile/channelDonation/ChannelDonationMessageRepository.kt`: `getChannelDonationMessageList`; `explorer/profile/channelDonation/ChannelDonationService.kt`: `getChannelDonationList`, `getChannelDonationListForProfile` | `GetChannelDonationListItem.nickname`, **donor `memberId`**, creatorId는 목록 filter | CURRENT mixed donor. 기존 secret/default message/삭제 prefix/adult/visibility/cursor 유지, donor member IDs batch. HTTP recipient render이며 FCM 전달은 제외. | T18 |
| L41 | `can/CanRepository.kt`: `CanQueryRepositoryImpl.getCanUseStatus`; `can/UseCanQueryDto.kt`; `can/CanService.kt`: `getCanUseStatus` | `GetCanUseStatusResponseItem.title` 안 room/audio/community/recipient creator name. `UseCanQueryDto.id=useCan.id`; **각 owner ID 없음** | CURRENT receipt: 현재 member를 join하며 이름 snapshot column 없음. `qRoomMember.id`, `qAudioContentMember.id`, `qCommunityPostMember.id`, `qRecipientMember.id` 내부 projection을 추가하고 service가 title를 만들기 전에 한 번 batch. payment gateway/refund/amount/distinct/page·resource title 우선 fallback 유지. live 이름도 이 HTTP receipt의 조회는 포함하되 `live/*` production 수정은 하지 않음. | T19 |
| L42 | `chat/character/comment/CharacterCommentService.kt`: `listComments`, `getReplies`, `getLatestComment`, `toCommentResponse`, `toReplyResponse`; `chat/character/comment/CharacterCommentDto.kt` | `CharacterCommentResponse.memberNickname`, `CharacterReplyResponse.memberNickname`, entity writer `member.id` | CURRENT mixed writer. characterId는 owner 아님. 부모·답글 목록+original 및 latest에서 writer IDs batch하고 Lang 명시 전달. 캐릭터 자체 `name`/본문 번역은 변경 없음. | T20 |
| L43 | `audition/applicant/AuditionApplicantRepository.kt`: `getAuditionApplicantList`; `audition/applicant/AuditionApplicantService.kt`: `getAuditionApplicantList`; `audition/applicant/AuditionApplicantController.kt` | `GetAuditionRoleApplicantItem.nickname`, **applicant memberId**, applicantId는 resource | CURRENT mixed applicant. service assembly batch, applicant/member 활성·role filter·vote count·sort/page 유지. admin audition은 제외. | T21 |
## 원본·불변·비이름 경계
| 경로와 심볼 | 분류와 결정 | 보존 검증 owner |
|---|---|---|
| `member/Member.kt`: `nickname`, `toExplorerSectionCreator`; `member/MemberAdapter.kt`; `member/MemberService.kt`: `loadUserByUsername` | RAW. entity/principal 원본 불변. `toExplorerSectionCreator`는 앱/관리/기타 공용이므로 이름 getter/global mapper를 변형하지 않고 앱 caller의 DTO를 변경한다. | T04, T06; 기존 Member 서비스·보안 테스트 |
| `member/MemberController.kt`: `getMember` (`GET /member`), `changeNickname`, profile PUT; `member/MemberService.kt`: `getMember`, `updateNickname`, `profileUpdate`; `member/ProfileResponse.kt`, `member/ProfileUpdateRequest.kt` | RAW EDITOR 경계. GET·PUT가 동일 ProfileResponse를 쓰고 nickname editing input을 제공한다. 기존 raw 응답/입력을 임의 로컬라이즈하지 않는다. 외부 client가 GET을 표시에도 쓰는지는 EXT001 확인 전 blocked이며 서버 구현 완료로 raw editor 안전을 증명하지 않는다. 별도 current display는 L06/L07. | T06; 외부 EXT001 |
| `member/MemberRepository.kt`: `findByNickname`, `existsByNickname`, `findNicknamesWithPrefix`; `member/MemberService.kt`: `duplicateCheckNickname`, `validateNickname`; `member/nickname/NicknameGenerateService.kt` | RAW 식별·중복·생성. alias search 대상은 `findByNicknameAndOtherCondition`만, raw unique 검사나 자동 닉네임 생성은 변경 없음. | T06 |
| `member/nickname/NicknameChangeLog.kt`: `prevNickname`; `member/MemberService.kt`: `updateNickname` | IMMUTABLE 변경 전 이름 기록. 기존 row rewrite 없음. 별칭 해제 시 과거 이름이 아니라 현재 Member.nickname으로 fallback. | T03, T04 |
| `member/login/LoginResponse.kt`; `member/MemberService.kt`: login/signup/findOrRegister; `member/auth/*`, `member/social/*`, `admin/*`, `creator/admin/*`, `partner/*` | RAW/제외. login·인증·원본 식별·관리/파트너 계약을 바꾸지 않는다. role+AI_CHARACTER인 CREATOR 표시는 포함, AI_CHARACTER kind만인 USER는 불변. | T03; 기존 auth/admin 테스트 |
| `chat/character/service/ChatCharacterCreatorMemberService.kt`: `ensureAiCharacterCreatorMember`, `syncAiCharacterCreatorMemberDisplayFields`, `syncDisplayFields` | RAW 동기화. ChatCharacter.name에서 원본 Member.nickname을 만든다. 별칭은 별도 테이블이므로 이 producer를 로컬라이즈하거나 원본 sync를 중단하지 않음. | 기존 `chat/character/service/ChatCharacterCreatorMemberServiceTest.kt`, `ChatCharacterCreatorMemberServiceIntegrationTest.kt` |
| `content/AudioContentService.kt`: `publishContentUploadedAfterCommit`; `explorer/profile/creatorCommunity/CreatorCommunityService.kt`: `publishCommunityPostCreatedAfterCommit` | 신규 v2 following event producer. 과거 following rows는 rewrite하지 않는다. v2 producer/consumer inventory slice의 책임이며 이 단계에서 원본 args를 변형하지 않음. | v2 following slice |
| `content/AudioContentService.kt`: uploadComplete/releaseContent; `explorer/ExplorerService.kt`: saveNotice; community/comment FcmEvent args | 새 async recipient payload는 이후 P3 slice. HTTP 이름 변경을 FCM title/args 변경으로 확대하지 않음. | async slice |
| `content/AudioContentRepository.kt`: `findByCreatorId`, other/previous/next-content; `content/series/content/ContentSeriesContentRepository.kt`; content/series banner, theme/category/tag/genre title | 비이름 field. `GetAudioContentListItem`, `OtherContentResponse`, series-content item에는 creator nickname 없음. existing content title/본문/character.name·Series.writer/studio는 creator localized-name으로 대체하지 않음. | T01, T04, T05, T12, T13 |
| L19/L20 cached nickname, Redis playlist detail | NEUTRAL-CACHE/current lookup, **과거 이름 snapshot 면제 아님**. cache hit 뒤 표시 대체하고 shared cache DTO 원본 유지. playlist 이름은 SQL current 조회. | T10, T11, T16 |
## 후속 테스트 소유자
아래 경로의 공통 prefix는 `src/test/kotlin/kr/co/vividnext/sodalive/`다. `신규 예정` 파일은 **아직 생성하지 않았다**. 이번 대표 15개 사례가 inventory 전체 GREEN 검증을 대신하지 않으며 해당 표면을 구현하기 전에 이 소유자의 RED 사례를 보강한다.
| Owner | 정확한 테스트 경로 | 상태·핵심 사례 |
|---|---|---|
| T06 | `member/MemberServiceTest.kt`, `member/MemberControllerTest.kt`; 신규 예정 `member/MemberLocalizedNameEndToEndTest.kt` | 기존 두 파일 있음. profile/myPage/search/block mixed USER, raw ProfileResponse·nickname edit·auth 불변. |
| T07 | `api/home/HomeServiceTest.kt`; 신규 예정 `api/home/HomeLocalizedNameEndToEndTest.kt` | 기존 있음. creator ranking·중첩 content/series/recommend/current names, guest KO/JA. |
| T08 | 신규 예정 `rank/RankingLocalizedNameEndToEndTest.kt` | creator/content/series/current owner 및 period 결과·title 불변. |
| T09 | 신규 예정 `content/main/LegacyContentMainLocalizedNameEndToEndTest.kt` | main/curation/tag/free/content/home/alarm/asmr/replay/series 탭의 creator와 ownernames. |
| T10 | 신규 예정 `query/recommend/RecommendChannelLocalizedNameCacheTest.kt` | 같은 member KO→JA→KO cache hit, alias update 후 current name, 원본 변경+clear 후 현재 원본 fallback, cached raw DTO 불변. |
| T11 | 신규 예정 `explorer/profile/CreatorDonationRankingLocalizedNameCacheTest.kt` | donor CREATOR/USER 혼합, cache hit/miss와 Lang 순서·current alias 갱신·원본 변경+clear fallback, count cache 불변. |
| T12 | `content/AudioContentServiceTest.kt`; 신규 예정 `content/AudioContentLocalizedNameEndToEndTest.kt` | 기존 있음. 상세 creator·mixed buyers·comments, owner ID와 contentId 구분, 원본/번역 title 유지. |
| T13 | 신규 예정 `content/series/ContentSeriesLocalizedNameEndToEndTest.kt`; 기존 `content/series/main/SeriesMainControllerTest.kt` | 목록/genre/recommend/original/curation/dayOfWeek/detail ownernames, writer/studio/title 불변. |
| T14 | 신규 예정 `content/comment/AudioContentCommentLocalizedNameEndToEndTest.kt` | mixed 부모/답글 및 상세 nested 목록, deleted original fallback/secret/block/page. |
| T15 | 신규 예정 `content/order/OrderLocalizedNameEndToEndTest.kt` | 주문 목록 현재 creator와 상세 mixed buyer, rental/expiry/count/public schema. |
| T16 | 신규 예정 `content/playlist/AudioContentPlaylistLocalizedNameEndToEndTest.kt` | Redis metadata는 그대로, detail SQL 이름만 current owner alias·원본 fallback·순서. |
| T17 | `explorer/profile/creatorCommunity/CreatorCommunityServiceTest.kt`, `CreatorCommunityTranslationEndToEndTest.kt`; 신규 예정 `explorer/profile/creatorCommunity/CreatorCommunityLocalizedNameEndToEndTest.kt` | 기존 두 파일 있음. post/detail/following/firstComment/comment/reply mixed owners·본문 번역 유지. |
| T18 | `explorer/profile/channelDonation/ChannelDonationServiceTest.kt`, `ChannelDonationMessageRepositoryTest.kt`; 신규 예정 `explorer/profile/channelDonation/ChannelDonationLocalizedNameEndToEndTest.kt` | 기존 두 파일 있음. donor aliases는 channel creator와 독립; USER·secret/default text 불변. |
| T19 | `can/CanServiceTest.kt`, `can/CanControllerIntegrationTest.kt`; 신규 예정 `can/CanReceiptLocalizedNameEndToEndTest.kt` | 기존 두 파일 있음. recipient/audio/community/room owner ID 구분, title 우선순위와 원본 resource title·receipt 금액 유지. |
| T20 | 신규 예정 `chat/character/comment/CharacterCommentLocalizedNameEndToEndTest.kt` | mixed comment/reply/latest/original, character name과 writer creator name 구분. |
| T21 | 신규 예정 `audition/applicant/AuditionApplicantLocalizedNameEndToEndTest.kt` | CREATOR/USER applicant owner, applicantId≠memberId, likes/count/order 유지. |
## 정적 확인과 남은 검증
- `rg`로 non-v2 nickname/projection 사용을 전체 검색하고 실제 caller/service/DTO를 읽어 목록에 연결했다. 추가 발견은 blocked member, audition applicant, buyerList, recommend series, receipt의 owner ID 누락이다.
- foundation `CreatorLocalizedNameEntity.kt`의 실제 table/column names와 fixture SQL을 대조했다. `JA` enum NAME·member FK·timestamp 값을 일치시켰다.
- 신규 테스트의 130자 초과/trailing whitespace 검색 결과 0건. production helper, reflection, 강제 실패 placeholder는 추가하지 않았다.
- Gradle/test/build/lint와 실제 HTTP 실행은 의도적으로 미실행이다. 부모의 serialized RED가 다음 검증 단계이며 이 문서는 RED 성공 또는 GREEN 완료를 주장하지 않는다.
- 현재 도구 목록에 `lsp_diagnostics`가 없어 Kotlin LSP 진단을 수행하지 못했다. 컴파일/context 오류가 보이면 부모 RED에서 먼저 수정하고 요구 동작 assertion 실패를 별도로 기록해야 한다.
- 외부 EXT001 raw editor/client display/cache 계약과 운영 DDL/MySQL collation은 이 테스트 단계에서 검증하지 않았다. 기존 문서의 승인 이전 문구를 덮어쓰지 않고 COR012를 기준으로 삼았다.
## 후속 GREEN 구현 연결 기록
### 실행 근거와 상태
- 부모 제공 RED: `/var/folders/yh/8xsbvpsj5wg2qnxzxdp11_gm0000gn/T/opencode/creatorname-consumer-red.log`. foundation 이후 기존 consumer 테스트가 실행됐고 별칭 hit/표시 assertion 실패를 확인했다. 이 worker는 Gradle을 실행하지 않았다.
- HTTP fixture 오류도 별도로 확인했다. `build/test-results/test/TEST-kr.co.vividnext.sodalive.explorer.ExplorerLocalizedNameEndToEndTest.xml`의 profile와 unified 요청은 `success=false`, 로그인 오류와 `data=null`이다. stack은 `MemberContentPreferenceService.initializeDefaultPreference`→`resolveForQuery(REQUIRES_NEW)`다. 미커밋 viewer가 별도 트랜잭션에서 보이지 않았으며 JSON field명이 잘못된 것이 아니다. `TestTransaction`으로 fixture를 먼저 커밋하고 다음 검증 트랜잭션을 시작하도록 수정했다. 별칭/원본/title/owner ID 기대값을 완화하지 않았다.
- 부모 lint 로그 `creatorname-foundation-final-lint.log`에 나온 5개 신규 테스트의 JDBC 인자를 각각 별도 줄로 수정했다. main 새 import 순서와 130자 길이도 정적으로 대조했다.
- `v2/creatorname/application/LegacyCreatorNameRenderer.kt`는 명시 Lang의 페이지 batch/copy와 중립 캐시의 현재 원본+별칭 map을 제공한다. 내부에서 foundation의 정확한 `findLocalizedNames(Collection<Long>, Lang)`를 호출한다. 요청 컨텍스트/기본-null service/전역 serializer/Member 변이는 없다.
- `v2/creatorname/adapter/out/persistence/CreatorNamePredicates.kt`의 owner 상관 `EXISTS`를 SearchRepository 6개 list/count 조건, Explorer channel, MemberQuery 검색에 적용했다. 원본 containsIgnoreCase 및 기존 다른 검색 조건·필터·group/count/page는 유지했다.
### L01~L43 연결 결과
| Inventory | 구현 경계 / 정적 판단 | runtime 상태 |
|---|---|---|
| L01~L03 | SearchService가 Lang을 명시 전달. creator title+nickname 대체. `search/SearchResponse.kt`의 `SearchNameRow`에 content/series 실제 ownerId를 내부 projection으로 추가하고 공개 SearchResponseItem으로 변환. | 부모 GREEN 대기 |
| L04~L08 | Explorer/Member 검색·타 회원 profile·myPage·blocked list의 response assembly에 batch/copy 적용. 원본 편집 GET/PUT·login·nickname 식별/변경은 기존 raw 그대로. | 부모 GREEN 대기 |
| L09~L14 | 탐색 섹션, profile/detail/blocked error, similar creator, follower, 부모/답글 cheers, fanTalk 쓰기 응답을 owner별 batch/copy로 연결. profile 내 live manager는 같은 profile creator의 이름을 복사하되 live 소스/저장 객체는 수정하지 않음. | 부모 GREEN 대기 |
| L15~L18 | Home creator ranking, RankingService의 creator/content/series 공통 assembly와 각각의 Top4/Top20 소비자를 연결. 순위/가격/수량/소유/요일/title fields는 그대로. | 부모 GREEN 대기 |
| L19~L20 | HomeService와 ExplorerService에서 neutral cache hit 뒤 현재 Member 원본을 batch 재조회하고 alias를 합쳐 새 DTO로 반환. recommend/donation cache producer·key·TTL·저장 entry는 그대로. | 부모 GREEN 대기 |
| L21 | `ExplorerQueryRepository.getMemberDonationRanking`의 실제 앱 caller가 없음을 `rg`로 다시 확인. 현재 앱은 cached CreatorDonationRankingService를 사용하므로 사용되지 않는 query를 별도로 수정하지 않음. | 연결 제외: 사용되지 않는 projection |
| L22~L23 | Audio 상세 creator/comment/buyer IDs 합집합, latest-content locale query의 owner IDs로 batch. title/detail/theme 번역은 기존 로직. `ContentBuyerRow`는 내부 projection이며 공개 ContentBuyer에는 ID를 추가하지 않음. | 부모 GREEN 대기 |
| L24~L30 | main/theme/curation/tag 및 alarm/content/free/asmr/replay/series 탭에 전체 응답 owner IDs batch 적용. Home tab은 이미 수정된 RankingService를 재사용하여 별도 중복 렌더링하지 않음. cached main 목록은 controller에서 cache hit 뒤 처리한다. | 부모 GREEN 대기 |
| L31~L32 | ContentSeriesService의 모든 목록·genre/recommend/original/curation/dayOfWeek/detail 경계를 연결. 공유 repository/Series entity/admin output을 전역 변경하지 않음. | 부모 GREEN 대기 |
| L33 | Audio 댓글/답글은 명시 Lang 인자를 추가. 앱 AudioContentCommentController만 요청 Lang을 전달하고 기존 shared ADMIN 호출은 기본 KO로 raw 이름 보존. 상세 nested comments도 포함. | 부모 GREEN 대기 |
| L34~L36 | Order response assembly, 내부 ContentBuyerRow, 내부 PlaylistContentRow로 실제 owner IDs 확보. Redis playlist metadata 및 공개 playlist/buyer DTO는 그대로. | 부모 GREEN 대기 |
| L37~L39 | Community 목록/detail/following/purchase, firstComment, 댓글/답글을 연결. 댓글 shared ADMIN consumer가 있어 기본 KO/앱 controller 명시 Lang 경계를 분리. entity/v2 DTO factory 및 번역/paid mask는 그대로. | 부모 GREEN 대기 |
| L40~L43 | donor 목록, Can internal DTO의 room/audio/community/recipient IDs, character comment/reply/latest writers, audition applicant memberIds를 batch로 연결. receipt title 우선순위·금액·resource 제목, USER 이름, count/page/filter는 그대로. | 부모 GREEN 대기 |
### GREEN 감사에서 추가 확인한 캐시·공유 경계
- L24/L25의 `content/main/AudioContentMainService.kt`는 `newContentUploadCreatorList`와 `getAudioContentCurationListWithPaging`의 raw creator 이름 포함 결과를 `default` cache에 저장한다. `content/main/AudioContentMainController.kt`에서 cache hit 뒤 전체 owner IDs의 현재 이름을 조회해 복사했다.
- `content/AudioContentService.kt.getAudioContentRanking`은 Lang 없는 `contentRanking` key와 `cache_ttl_3_days`에 이름 포함 결과를 저장한다. `content/AudioContentController.kt`에서 cache hit 뒤 현재 이름을 batch/copy 처리했다.
- L24에서 사용하는 `content/theme/AudioContentThemeService.kt.getContentByTheme`에도 이름 포함 item이 있어 연결했다. theme/title 자체의 번역 계약은 변경하지 않았다.
- v2 ADMIN `AiCharacterAdminCommunityPostFacade.comments/commentReplies`, `AiCharacterAdminAudioContentFacade.comments/commentReplies`가 legacy comment 서비스를 실제 재사용한다. 이 service 읽기의 기본 Lang은 KO이고 앱 controller만 요청 Lang을 명시한다. v2 ADMIN 파일을 수정하거나 route/principal로 언어를 추론하지 않았다.
- 기존 neutral cache의 콘텐츠 제목/날짜 locale 문제나 visibility 수명은 이번 이름 변경으로 확장 수정하지 않았다. aliases와 현재 원본의 표시만 cache 밖에서 갱신한다.
### 소유한 FCM 호출 metadata
`delivery-name-inventory.md` #9/#10/#11/#12/#14/#15의 6곳에 `titleMemberId`를 명시했다. Explorer notice/community post/comment는 실제 작성 member ID, audio upload/release는 audio owner ID, audio reply는 `parent?.member?.id ?: member.id`다. 기존 title/args/content 제목·deepLink·senderMemberId는 그대로다. 특히 reply snapshot의 sender는 실제 commenter이며 title owner와 다를 수 있다. 중앙 FcmEvent/async/live/message/v2 소스는 수정하지 않았다.
### 추가 회귀와 constructor fixture
추가 테스트는 **아직 실행하지 않았다**. 이번 원래 15개와 아래 13개를 합쳐 대상 이름 회귀는 28개 실행 사례다. 새 회귀의 RED/GREEN을 관찰했다고 주장하지 않으며 부모가 별도 검증 기록을 남긴다.
| Owner | 정확한 테스트 파일 | 사례 / 보호 경계 |
|---|---|---|
| T22 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/creatorname/application/LegacyCreatorNameRendererTest.kt` | 기존 2 + 리뷰 회귀 4: 실제 foundation/JPA batch의 1 select(작은/중복 큰 페이지), KO 0 alias select, USER/missing/원본 DTO 보존; neutral cache의 원본 변경+clear 현재 fallback. 현재 이름 경로는 서로 다른 1/4명에서 JA 2 SQL, KO/EN 1 SQL, entityLoadCount 0 및 빈 입력 0 SQL. |
| T23 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/creatorname/application/LegacyCurrentNameReadIntegrationTest.kt` | 9: profile/myPage/blocked/raw editor, 주문+Redis playlist, mixed buyer 상세, community post/firstComment/reply+shared raw default, donor, receipt 실제 projection, character writers, applicant memberId, donor neutral Redis cache hit/원본 변경+clear/과거 DTO·cache entry 불변. |
| T24 | `src/test/kotlin/kr/co/vividnext/sodalive/content/comment/AudioContentCommentNameMetadataTest.kt` | 2 parameterized: parent CREATOR/commenter USER와 반대 조합. 실제 JPA/댓글 service를 호출하고 outbound event publisher만 capture하여 title owner≠snapshot sender, 원본 title 및 content title args/empty name slots 유지. |
기존 직접 constructor fixture는 새 dependency를 명시적으로 추가했다. legacy JPA slice에는 `src/test/kotlin/kr/co/vividnext/sodalive/support/LegacyCreatorNameTestConfiguration.kt`를 import했다. 이 configuration은 renderer, foundation service, adapter를 제공한다. 기존 isolated unit fixture의 `originalLegacyNameRenderer()`는 실제 renderer와 이름 없는 dependency doubles를 사용하며 production default-null 호환성 경로가 아니다.
소유 범위 밖의 v2/foundation/admin/partner/async JPA slice도 AudioContent custom repository를 스캔한다면 위 test configuration import가 필요하다. 해당 파일은 직접 수정하지 않았다. 직접 constructor가 있는 `v2/api/admin/aicharacter/community/LegacyCommunityPostCharacterizationTest.kt`와 `v2/api/admin/aicharacter/fantalk/LegacyFanTalkReplyCharacterizationTest.kt`도 소유자가 `nameRenderer` 인자를 명시해야 한다. 이 항목은 부모에 전달했으며 해당 소유자 수정 여부는 부모의 최종 compile에서 확인한다.
### 정확한 변경 소스 manifest
아래 공통 prefix는 `src/main/kotlin/kr/co/vividnext/sodalive/`다. 기존 row의 query producer는 current/raw 데이터를 유지하고 실제 response assembly만 수정한 경우도 포함해 연결 경계를 표시했다.
```text
v2/creatorname/application/LegacyCreatorNameRenderer.kt
v2/creatorname/adapter/out/persistence/CreatorNamePredicates.kt
search/SearchRepository.kt
search/SearchResponse.kt
search/SearchService.kt
member/MemberRepository.kt
member/MemberService.kt
explorer/ExplorerQueryRepository.kt
explorer/ExplorerService.kt
explorer/profile/creatorCommunity/CreatorCommunityService.kt
explorer/profile/creatorCommunity/CreatorCommunityController.kt
explorer/profile/channelDonation/ChannelDonationService.kt
api/home/HomeService.kt
rank/RankingService.kt
content/AudioContentRepository.kt
content/AudioContentService.kt
content/AudioContentController.kt
content/GetAudioContentDetailResponse.kt
content/series/ContentSeriesService.kt
content/comment/AudioContentCommentService.kt
content/comment/AudioContentCommentController.kt
content/order/OrderRepository.kt
content/order/OrderService.kt
content/playlist/AudioContentPlaylist.kt
content/playlist/AudioContentPlaylistService.kt
content/main/AudioContentMainService.kt
content/main/AudioContentMainController.kt
content/main/curation/AudioContentCurationService.kt
content/main/tab/content/ContentMainTabTagCurationService.kt
content/main/tab/content/AudioContentMainTabContentService.kt
content/main/tab/free/AudioContentMainTabFreeService.kt
content/main/tab/alarm/AudioContentMainTabAlarmService.kt
content/main/tab/asmr/AudioContentMainTabAsmrService.kt
content/main/tab/replay/AudioContentMainTabLiveReplayService.kt
content/main/tab/series/AudioContentMainTabSeriesService.kt
content/theme/AudioContentThemeService.kt
can/CanRepository.kt
can/CanService.kt
can/UseCanQueryDto.kt
chat/character/comment/CharacterCommentService.kt
audition/applicant/AuditionApplicantService.kt
```
변경 테스트 manifest의 공통 prefix는 `src/test/kotlin/kr/co/vividnext/sodalive/`다. 기존 JPA 파일의 변경은 필요한 test configuration import만이며 본래 테스트 로직을 정리하거나 완화하지 않았다.
```text
support/LegacyCreatorNameTestConfiguration.kt
v2/creatorname/application/LegacyCreatorNameRendererTest.kt
v2/creatorname/application/LegacyCurrentNameReadIntegrationTest.kt
content/comment/AudioContentCommentNameMetadataTest.kt
search/SearchRepositoryLocalizedNameTest.kt
search/SearchServiceTest.kt
explorer/ExplorerQueryRepositoryLocalizedNameTest.kt
explorer/ExplorerLocalizedNameEndToEndTest.kt
explorer/ExplorerServiceTest.kt
member/MemberRepositoryLocalizedNameTest.kt
member/MemberServiceContentPreferenceTest.kt
member/MemberServiceCacheEvictionTest.kt
content/AudioContentRepositoryLocalizedNameTest.kt
content/AudioContentServiceTest.kt
api/home/HomeServiceTest.kt
can/CanServiceTest.kt
explorer/profile/creatorCommunity/CreatorCommunityServiceTest.kt
explorer/profile/creatorCommunity/CreatorCommunityTranslationEndToEndTest.kt
explorer/profile/channelDonation/ChannelDonationServiceTest.kt
explorer/profile/channelDonation/ChannelDonationMessageRepositoryTest.kt
content/CreatorCommunityLanguageDetectTest.kt
content/CreatorCommunityLanguageDetectionCacheConcurrencyTest.kt
content/main/banner/AudioContentBannerRepositoryTest.kt
event/EventRepositoryTest.kt
member/contentpreference/MemberContentPreferenceIntegrationTest.kt
osiv/OsivLazyLoadingRegressionTest.kt
```
### 부모 전용 GREEN 명령과 검증 한계
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.search.SearchRepositoryLocalizedNameTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.ExplorerQueryRepositoryLocalizedNameTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.member.MemberRepositoryLocalizedNameTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.content.AudioContentRepositoryLocalizedNameTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.ExplorerLocalizedNameEndToEndTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creatorname.application.LegacyCreatorNameRendererTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creatorname.application.LegacyCurrentNameReadIntegrationTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.content.comment.AudioContentCommentNameMetadataTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.search.SearchServiceTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.content.AudioContentServiceTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.ExplorerServiceTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.CreatorCommunityServiceTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.CreatorCommunityTranslationEndToEndTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.profile.channelDonation.ChannelDonationServiceTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.api.home.HomeServiceTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.member.MemberServiceContentPreferenceTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.member.MemberServiceCacheEvictionTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.can.CanServiceTest'
./gradlew ktlintCheck
./gradlew assemble
```
- 현재 확인은 source caller/constructor/DTO/owner ID/Lang 및 cache producer/consumer 대조다. public response field 이름·타입과 Member/principal/original editor 불변을 소스에서 점검했다.
- 변경 코드의 길이/후행 공백과 신규 테스트의 placeholder/Disabled/reflection을 `rg`로 점검했다. lint 로그의 인자 줄바꿈 수정은 실제 ktlint 재실행 PASS를 뜻하지 않는다.
- kapt가 생성할 `QSearchNameRow`, `QContentBuyerRow`, `QPlaylistContentRow` 및 변경 QUseCanQueryDto constructor는 부모 compile/test가 검증한다. LSP 도구는 제공되지 않았다.
- Gradle, build, lint, 실제 HTTP/SDK/Redis QA는 이번 GREEN worker에서 실행하지 않았다. 앱 전체/외부 cache/editor/RTC/provider 및 운영 DB는 기존 blocker를 유지한다.
## COR013: DB 직접 이름 JOIN 전환
### 근거와 검증 상태
- 기준은 PRD 10절과 JOIN-T1~JOIN-T3다. 위의 이전 JA 전용 batch 구현·검증 기록은 당시 이력이며 아래 분류가 현재 조회 경계다.
- 부모 제공 실제 RED 로그는 `/var/folders/yh/8xsbvpsj5wg2qnxzxdp11_gm0000gn/T/opencode/creatorname-join-consumer-red.log`다. `SearchRepositoryLocalizedNameTest.shouldSearchContentOwnerAliasWithMatchingCountAndExistingContentFilters`의 표시 값은 맞았지만 standalone alias SELECT가 0이 아닌 1이었다. 해당 SQL assertion은 그대로 유지했다.
- 공통 `CreatorNameJoin(owner, lang, alias)`의 member ID·요청 Lang·활성 이름·CREATOR 조건을 ON으로 연결한다. 목록 SQL이 COALESCE 이름을 반환하며 count와 후보 ID 쿼리에는 표시 JOIN을 추가하지 않는다. JOIN별 alias는 owner별로 분리했다.
- 이 worker는 Gradle, 테스트, build, ktlint, 실제 HTTP를 실행하지 않았다. LSP 도구도 제공되지 않았다. 아래는 소스·호출자·fixture 연결 및 정적 점검 결과이며 runtime GREEN 판정은 부모의 직렬 실행에 남긴다.
### L01~L43 현재 분류
| Inventory | 현재 구현 / 실제 쿼리와 경계 |
|---|---|
| L01~L03 | `SearchRepository.searchCreatorList/searchContentList/searchSeriesList`가 요청 Lang JOIN으로 공개 `SearchResponseItem`을 직접 투영한다. creator title+nickname을 함께 선택하고 content/series title은 그대로다. `SearchNameRow`와 후속 alias batch를 제거했다. JA EXISTS 검색 및 count·필터·page는 유지한다. |
| L04~L06, L08 | `ExplorerQueryRepository.getSearchChannel`, `MemberQueryRepositoryImpl.findByNicknameAndOtherCondition/getMemberProfile`, `BlockMemberQueryRepositoryImpl.getBlockedMemberList`에서 표시 이름을 함께 선택한다. 검색 결과는 Member를 변이하지 않는 기존 `GetRoomDetailUser`로 반환한다. 앱 caller는 요청 Lang을 명시한다. |
| L07 | `MemberService.getMyPage`는 인증 principal의 raw Member를 그대로 사용하므로 DTO 경계 sparse batch를 유지한다. 원본 편집·login·nickname 식별은 raw다. |
| L09, L11~L13 | `ExplorerQueryRepository.getCreatorRankings/getNewCreators/findCreatorByGender/getSimilarCreatorList/getRandomCreatorList/getFollowerList/getCheersList`에 JOIN을 적용했다. creator DTO 및 cheers 부모·답글 이름은 쿼리에서 선택한다. cheers 답글은 페이지 부모 IDs의 별도 원래 데이터 조회에 같은 JOIN을 적용하며 단독 alias 조회를 하지 않는다. count·차단·부모/답글 노출 의미는 유지한다. |
| L10, L14 | profile/detail은 role·차단·노출 및 중첩 조립에 필요한 raw Member 경계, fanTalk 작성/수정은 저장 entity 반환 경계다. 기존 sparse batch로 HTTP DTO/차단 오류에만 표시한다. FCM 원본 args/title과 principal은 바꾸지 않는다. |
| L15~L18 | `RankingRepository.getCreatorRankings/getAudioContentRanking/getSeriesRanking/getCompleteSeriesRanking/getSeriesAllRankingByGenre/fetchCreatorBySellContentCountRankTop20/fetchCreatorContentBySalesCountTop4/fetchCreatorBySeriesRevenueRankTop20/fetchCreatorSeriesBySales/fetchFreeContentByCreatorIdTop4/fetchCreatorContentByLikeCountTop4`에서 이름을 선택한다. creator는 기존 DTO, series는 원본 entity+SQL 표시 이름 tuple로 조립하고 RankingService/HomeService의 이름 전용 batch를 제거했다. 집계·요일·후속 content count/new 판정은 그대로다. |
| L19~L20 | 추천 채널·donation ranking의 cache producer, DTO, key, TTL은 raw·언어 중립으로 유지한다. `HomeService.fetchData`, `ExplorerService.renderDonationRanking`이 cache hit 뒤 공통 단일 JOIN current-name batch를 호출한다. cached 원본을 현재 fallback으로 간주하지 않는다. |
| L21 | `ExplorerQueryRepository.getMemberDonationRanking`도 명시 Lang이 있으면 donor JOIN을 선택하도록 전환했다. 실제 앱 caller는 여전히 L20 cached service다. null Lang의 기존 raw 모드를 보존하고 새 caller는 만들지 않았다. |
| L22~L23 | Audio 상세는 권한·구매·번역에 필요한 원본 audio/member 경계의 creator sparse batch만 유지한다. buyer와 nested comment는 각 SQL에서 이름을 선택한다. `AudioContentQueryRepositoryImpl.getLatestContentByTheme`의 locale 경로는 같은 title tuple SQL에 JOIN을 추가했고 repository renderer 의존성을 제거했다. locale=null은 기존 raw query 모드다. |
| L24~L27 | `findByTheme/findAlarmContentByTheme/findByThemeFor2Weeks/findAudioContentByCurationId/findAudioContentByCurationIdV2/findContentByCurationId`, `AudioContentCurationQueryRepository.findByCurationId`, `ContentMainTabTagCurationRepository.getTagCurationContentList`가 명시 Lang JOIN을 지원한다. 앱 main/theme/curation/tag caller는 Lang을 전달하고 후속 이름 copy/batch를 제거했다. 중립 cache를 만드는 `findAudioContentByCurationId`의 null Lang과 `getAudioContentRanking` raw producer는 유지한다. |
| L25 | `getNewContentUploadCreatorList`는 이름 포함 중립 cache producer이므로 raw다. `AudioContentMainController`의 cache-hit 이후 current-name batch를 유지한다. |
| L28~L30 | `AudioContentMainTabRepository.findCreatorByThemeContent/findCreatorWithHasFreeContent`, `RecommendSeriesRepository.getNewSeriesList/getRecommendSeriesList`가 JOIN으로 반환한다. alarm/content/free/asmr/replay/series의 모든 직접 content/curation/creator/series caller에 Lang을 전달했고 탭 전체 응답을 다시 복사하던 alias batch를 제거했다. home 탭은 변경된 RankingService/ContentSeriesService를 그대로 재사용한다. |
| L31~L32 | `ContentSeriesQueryRepositoryImpl.getSeriesListV2/getSeriesByGenreListV2/getRecommendSeriesListV2/getOriginalAudioDramaList/findByCurationIdV2/getDayOfWeekSeriesListV2`의 기존 locale tuple SQL에 JOIN을 추가했다. 목록 service의 renderSeries를 제거했다. 상세는 접근/번역/가격/요일에 필요한 raw Series entity 경계의 sparse batch를 유지한다. writer/studio/title과 공용 entity는 그대로다. |
| L33 | `AudioContentCommentQueryRepositoryImpl.findByContentId/getAudioContentCommentReplyList`가 writer 이름을 선택한다. 앱 controller 및 Audio 상세는 요청 Lang, 기존 shared ADMIN 호출은 `lang=null`의 명시 raw 모드다. KO를 raw의 대용으로 사용하지 않는다. secret/block/count/page와 원본 deleted-prefix fallback은 보존한다. |
| L34~L36 | `OrderQueryRepositoryImpl.getAudioContentOrderList/getAudioContentMainOrderList/findBuyerListByContentId`, `AudioContentQueryRepositoryImpl.fetchContentForPlaylist`에서 이름을 선택한다. 공개 buyer/playlist DTO로 직접 투영해 `ContentBuyerRow`/`PlaylistContentRow`와 이름 전용 owner IDs·copy/batch를 제거했다. Redis playlist metadata, 순서, KEEP/RENTAL/expiry 조건은 그대로다. |
| L37~L39 | `CreatorCommunityQueryRepositoryImpl.getCommunityPostList/getCommunityPost/getLatestPostListFromCreatorsYouFollow`, `CreatorCommunityCommentQueryRepositoryImpl.findByPostId/getCommunityCommentReplyList`가 JOIN 이름을 선택한다. firstComment에도 요청 Lang을 전달한다. 목록/detail의 renderPosts를 제거했고 구매 쓰기 반환의 creator sparse batch만 유지한다. shared ADMIN 댓글 기본값은 null raw, 앱만 요청 Lang이다. 본문 번역·유료 마스크·secret/filter는 그대로다. |
| L40 | `ChannelDonationMessageQueryRepositoryImpl.getChannelDonationMessageList`가 donor entity+SQL 표시 이름 tuple을 반환한다. service의 donor alias batch를 제거했다. 원본 이름의 deleted-prefix fallback, secret/default message·날짜·정렬·count는 보존한다. |
| L41 | `CanQueryRepositoryImpl.getCanUseStatus`의 room/audio/community/recipient owner 4개에 각각 고유 JOIN을 연결했다. CanService는 받은 이름으로 기존 title 우선순위를 적용한다. 후속 이름 map, copy와 `UseCanQueryDto`의 이름 batch 전용 owner IDs를 제거했다. 금액·결제/refund/distinct/page 및 resource 제목은 그대로다. |
| L42 | `CharacterCommentQueryRepositoryImpl.findDisplayComments/findDisplayReplies/findDisplayComment`가 writer 이름을 같은 SQL에서 선택한다. list/latest 및 replies의 original도 이 query를 사용하며 service의 alias batch를 제거했다. 원본 entity를 변경하지 않고 기존 comment/reply DTO로 조립한다. cursor·active·정렬·reply count와 캐릭터 자체 이름은 그대로다. |
| L43 | `AuditionApplicantQueryRepositoryImpl.getAuditionApplicantList`가 applicant member JOIN 이름을 투영한다. service에 Lang을 명시하고 alias batch를 제거했다. vote 집계·role·활성·page 조건은 유지한다. |
### 남은 이름 batch 호출: 정확히 15곳
아래는 non-v2 담당 소스에서 `nameRenderer.findCurrentNames/findLocalizedNames/render`를 검색한 결과다. 직접 DB 목록을 이미 조회했다는 이유로 남긴 batch는 없다.
| 분류 | 실제 호출 위치 | 이유 |
|---|---|---|
| NEUTRAL-CACHE, current 5곳 | `api/home/HomeService.fetchData`; `explorer/ExplorerService.renderDonationRanking`; `content/main/AudioContentMainController.getNewContentUploadCreatorList/getAudioContentCurationListWithPaging`; `content/AudioContentController.getAudioContentRanking` | cache hit 이후 현재 원본+요청 Lang 별칭을 공통 단일 JOIN batch로 읽고 새 응답을 만든다. 원본 cache payload는 유지한다. |
| PRINCIPAL, sparse 1곳 | `member/MemberService.getMyPage` | 인증 principal을 변이하지 않고 표시 DTO만 렌더한다. |
| RAW ENTITY DETAIL, sparse 4곳 | `explorer/ExplorerService.getCreatorDetail/getCreatorProfile`; `content/AudioContentService.getDetail`; `content/series/ContentSeriesService.getSeriesDetail` | role/접근/구매/가격/번역 등 기존 비즈니스 조립에 필요한 raw entity의 이름을 덮어쓰지 않는다. |
| WRITE / ERROR, sparse 5곳 | `explorer/ExplorerService.writeCheers`의 차단 오류, `renderFanTalk`의 작성/수정 반환; `content/comment/AudioContentCommentService.registerComment`의 차단 오류; `explorer/profile/creatorCommunity/CreatorCommunityService.purchasePost`의 차단 오류 및 구매 반환 | 저장·검증에 사용한 raw entity와 기존 event args/title을 유지하고 HTTP 반환/오류만 렌더한다. |
별칭 표시가 없는 원본 인증/editor/admin/partner 및 역사 저장 이름은 기존 계약을 유지한다. FCM metadata 변경 이력은 위 절 그대로이며 COR013에서 해당 event title/args를 다시 수정하지 않았다.
### 이번 source manifest
공통 prefix는 `src/main/kotlin/kr/co/vividnext/sodalive/`다. 공유 core/helper/test support, v2, live/message/fcm, chat room repository 및 부모 소유 PRD/plan은 수정하지 않았다.
```text
search/SearchRepository.kt
search/SearchResponse.kt
member/MemberRepository.kt
member/MemberService.kt
member/block/BlockMemberRepository.kt
explorer/ExplorerQueryRepository.kt
explorer/ExplorerService.kt
explorer/profile/creatorCommunity/CreatorCommunityRepository.kt
explorer/profile/creatorCommunity/CreatorCommunityService.kt
explorer/profile/creatorCommunity/comment/CreatorCommunityCommentRepository.kt
explorer/profile/channelDonation/ChannelDonationMessageRepository.kt
explorer/profile/channelDonation/ChannelDonationService.kt
api/home/HomeService.kt
rank/RankingRepository.kt
rank/RankingService.kt
content/AudioContentRepository.kt
content/AudioContentService.kt
content/GetAudioContentDetailResponse.kt
content/comment/AudioContentCommentRepository.kt
content/comment/AudioContentCommentService.kt
content/series/ContentSeriesRepository.kt
content/series/ContentSeriesService.kt
content/order/OrderRepository.kt
content/order/OrderService.kt
content/playlist/AudioContentPlaylist.kt
content/playlist/AudioContentPlaylistService.kt
content/main/AudioContentMainService.kt
content/main/curation/AudioContentCurationQueryRepository.kt
content/main/curation/AudioContentCurationService.kt
content/main/tab/AudioContentMainTabRepository.kt
content/main/tab/RecommendSeriesRepository.kt
content/main/tab/content/ContentMainTabTagCurationRepository.kt
content/main/tab/content/ContentMainTabTagCurationService.kt
content/main/tab/content/AudioContentMainTabContentService.kt
content/main/tab/free/AudioContentMainTabFreeService.kt
content/main/tab/alarm/AudioContentMainTabAlarmService.kt
content/main/tab/asmr/AudioContentMainTabAsmrService.kt
content/main/tab/replay/AudioContentMainTabLiveReplayService.kt
content/main/tab/series/AudioContentMainTabSeriesService.kt
content/theme/AudioContentThemeService.kt
can/CanRepository.kt
can/CanService.kt
can/UseCanQueryDto.kt
chat/character/comment/CharacterCommentRepository.kt
chat/character/comment/CharacterCommentService.kt
audition/applicant/AuditionApplicantRepository.kt
audition/applicant/AuditionApplicantService.kt
```
### 이번 test caller manifest와 부모 직렬 검증
공통 prefix는 `src/test/kotlin/kr/co/vividnext/sodalive/`다.
```text
search/SearchRepositoryLocalizedNameTest.kt
can/CanServiceTest.kt
api/home/HomeServiceTest.kt
osiv/OsivLazyLoadingRegressionTest.kt
explorer/profile/channelDonation/ChannelDonationMessageRepositoryTest.kt
explorer/profile/channelDonation/ChannelDonationServiceTest.kt
explorer/profile/creatorCommunity/CreatorCommunityServiceTest.kt
```
- Search 직접 constructor의 renderer 인자를 제거했다. 기존 standalone alias SELECT=0 assertion은 완화하지 않았고 같은 콘텐츠 사례에 EN 표시 이름 선택 및 EN 이름으로 검색하지 않는 JA 검색 계약 assertion을 추가했다.
- Can fixture의 제거된 내부 owner ID 인자와 renderer constructor 인자를 제거했다. Home/Community stub은 앱이 전달하는 실제 Lang을 명시했다. donation fixture는 entity+이름 tuple과 Lang matcher로 적응했다. 기존 name/filter/secret/USER/count/page 기대값은 유지했다.
- donation repository의 기존 fetch-member 사례는 `deleted_viewer3` 원본 entity가 그대로이고 SQL 표시 이름만 `viewer3`임을 함께 확인하도록 보강했다. OSIV 사례는 repository가 반환하는 기존 explorer DTO의 tags를 검증하며 세션 밖 사용 경계는 유지한다.
- `AudioContentQueryRepositoryImpl`은 더 이상 renderer 주입을 요구하지 않는다. 기존 JPA test configuration import는 다른 service/core fixture까지 함께 제공하는 경우가 있어 일괄 삭제하지 않았다. 다른 owner 소스·테스트를 수정해야 하는 확인된 컴파일 변경은 없다. 전체 compile과 v2 ADMIN의 null raw 호출 회귀는 부모가 확인한다.
- `rg`로 전환 query/caller, 제거된 내부 row/ID 참조, 15개 batch 경계, 추가 import 정렬·사용 및 130자/후행 공백을 대조했다. Kotlin compile/LSP 또는 runtime 검증을 대신하지 않는다.
- 추가 정적 delimiter 검사 대상 74개 repository/service 파일에서 괄호 불일치 0건, 담당 Kotlin 소스·변경 테스트의 130자 초과/후행 공백 검색 0건이었다. 삭제한 `SearchNameRow/ContentBuyerRow/PlaylistContentRow` 및 이름 batch 전용 Can owner ID의 Kotlin 참조도 0건이다.
아래는 **이 worker에서 실행하지 않은** 부모 직렬 검증 명령이다. 모든 parallel writer가 종료된 뒤 실행한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.search.SearchRepositoryLocalizedNameTest' --tests 'kr.co.vividnext.sodalive.content.AudioContentRepositoryLocalizedNameTest' --tests 'kr.co.vividnext.sodalive.explorer.ExplorerQueryRepositoryLocalizedNameTest' --tests 'kr.co.vividnext.sodalive.member.MemberRepositoryLocalizedNameTest' --offline --console=plain
./gradlew test --tests 'kr.co.vividnext.sodalive.explorer.ExplorerLocalizedNameEndToEndTest' --tests 'kr.co.vividnext.sodalive.v2.creatorname.application.LegacyCurrentNameReadIntegrationTest' --tests 'kr.co.vividnext.sodalive.explorer.profile.channelDonation.*' --tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.*' --tests 'kr.co.vividnext.sodalive.can.CanServiceTest' --tests 'kr.co.vividnext.sodalive.api.home.HomeServiceTest' --tests 'kr.co.vividnext.sodalive.osiv.OsivLazyLoadingRegressionTest' --offline --console=plain
./gradlew test build ktlintCheck --continue --offline --console=plain
```
File diff suppressed because it is too large Load Diff
@@ -1,233 +0,0 @@
# 크리에이터 이름 언어별 관리 PRD
> 문서 상태: COR022 레거시 메시지 전체롤백·검증 완료. 두운영파일HEAD일치, 전용projection/테스트3건 제거 후 전체2267건/실패0/오류0/skip0과lint통과, 실제HTTP23요청·발송이벤트2건·독립리뷰승인을 확인했다. 공통FCM/v2 DM은 유지하고 임시자원은 정리했다. 운영DB적용·배포·커밋·푸시는 하지 않았다.
## 문서 정보
| 항목 | 내용 |
|---|---|
| 작성일 / 최종 수정일 | 2026-10-14 / 2026-10-16 |
| 대상 제품 | 앱 내 크리에이터 표시 이름의 수동 언어별 관리 |
| 구현 계획 | `plan-task.md`, COR012 승인, 서버 구현 진행 기록 및 잔여 Gate 포함 |
| API Contract | COR012 승인, 구현 및 HTTP 테스트로 확인 |
| DDL 산출물 | `schema.sql` 초안 파일 작성 승인, DB 미적용·별도 승인 전 실행 금지 |
| 구현 승인 | COR012 승인. 운영 DB 적용·배포는 별도 승인 필요하며 외부 클라이언트 의존성은 차단 상태 |
## 1. 목표와 범위
운영자가 크리에이터의 일본어 이름을 수동 관리하고, 앱의 크리에이터 표시 이름을 요청 언어에 따라 제공한다. 관리 쓰기/API 범위는 JA만이다. 조회는 기존 `Lang` 전부를 사용하며, 해당 언어에 활성 이름이 있으면 적용하고 없으면 현재 원본 이름으로 fallback한다. KO/EN 관리 기능은 포함하지 않는다. 저장 구조는 기존 `Lang`을 재사용한다.
앱 크리에이터 표시 경로가 대상이되 COR017에서 사용자가 미사용이라고 확인한 AudioContentMainTab 계열은 이번 변경에서 완전히 제외한다. 탭 파일은 기존 HEAD와 같게 유지하며, 미사용 탭의 원본 닉네임 반환을 보장하기 위한 null 인자·별도 raw 모드·테스트는 요구하지 않는다. 공유 조회는 실제 사용 호출자의 언어별 이름과 제목 번역을 보존하며, 그 변경이 미사용 탭 결과에 간접 영향을 주는 것은 허용한다. AudioContentCuration 및 레거시 커뮤니티·팬톡은 COR015의 원본 이름 계약을 유지한다. API 자체와 기존 저장·권한·제목/본문 번역·알림 업무는 삭제하지 않는다. 그 밖의 레거시/v2 HTTP 및 v2 커뮤니티·팬톡은 유지한다. 사용자별 신규 전달은 각 수신자/세션 언어로 렌더링한다. 기존 언어별 역사 스냅샷과 이미 전달된 payload는 수정하지 않는다.
일반 USER 이름, `Member.nickname` 원본, 원본 닉네임 편집기, 로그인·인증·원본 식별 흐름은 변경하지 않는다. 자동 번역도 하지 않는다. JA 별칭은 원본 닉네임이 나중에 변경되어도 계속 우선한다. 일본어 별칭은 원본 닉네임 검색과 함께 검색 가능해야 한다.
원본은 언어가 아니라 현재 `Member.nickname`에 저장된 문자열이다. 한국어·일본어·영어 등 어떤 언어일 수도 있으며 `Lang.KO`와 동의어가 아니다. 요청 언어의 활성 CREATOR 별칭이 있으면 원본 문자열의 언어와 무관하게 별칭이 우선하고, 없거나 해제됐으면 현재 원본을 그대로 반환한다. 원본이 일본어여도 JA 별칭이 따로 등록되어 있으면 등록값을 우선한다. `Lang.KO` 기본값은 요청 언어의 기본값일 뿐 원본 언어 지정이 아니다. 원본 언어 필드나 자동 언어 감지는 추가하지 않는다.
COR019에서 `AudioContentMainController`와 `AudioContentMainService`의 이번 이름 변경도 제외한다. 두 파일은 HEAD와 같게 되돌리고, 이 서비스만 사용하는 `findByThemeFor2Weeks`/`findAudioContentByCurationId`의 이름 언어 인자·JOIN만 제거한다. 공유 `findByTheme`의 현지화는 다른 실제 사용 API 때문에 유지하며, 이를 제외 API에 한해 차단하는 별도 raw 모드는 추가하지 않는다. 기존 제목·테마 번역, 캐시, 권한·차단·성인 필터는 유지한다. 전용으로 추가된 테스트는 실제 없으므로 공유 테스트를 삭제하지 않는다.
COR020에서 `CharacterCommentService`/`CharacterCommentRepository`의 작성자 이름 현지화 변경도 제외한다. 두 파일을 HEAD 형태로 복원하고 댓글 목록·답글의 원댓글·최신 댓글은 기존 저장 nickname을 사용한다. 댓글 작성/답글/삭제/신고·권한·커서·건수·언어 감지 이벤트는 변경하지 않는다. 해당 이름 대체 기능 전용 통합테스트1개만 제거하며 배너·다른 이름 조회 테스트는 유지한다.
COR021에서 `ContentSeriesRepository`/`ContentSeriesService`의 이름 현지화 변경도 HEAD로 되돌린다. 저장소5개 목록 조회의 이름 JOIN 및 서비스 상세 이름 batch만 제거되며 기존 제목·소개·장르·요일 번역과 권한·필터·순서·페이지·건수는 보존한다. 이 서비스를 재사용하는 HomeService의 오리지널/요일별 목록과 ExplorerService의 프로필 시리즈 작성자 이름도 원본으로 돌아가는 영향을 포함한다. 공통 CreatorNameJoin/CreatorLocalizedNameService 및 별도 v2 시리즈 조회는 삭제하지 않는다. 관련 테스트1개에서는 이름 현지화 단언만 제거하고 제목 번역·원문 fallback 검증을 유지한다.
COR022에서 레거시 `/message`의 MessageService/MessageRepository 이름 변경 전체를 HEAD로 되돌린다. 문자·음성의 발신/수신/보관 목록은 기존 엔티티 조회와 원본 이름을 사용하고 차단 오류의 이름 치환도 제거한다. MessageListRow와 전용 현지화 테스트3건은 제거하되 API·발송·보관·삭제·권한·본문/시간/URL 처리 자체는 유지한다. 전체 롤백에는 문자·음성 FCM 이벤트의 nameArgumentMemberIds 추가분2곳 제거도 포함된다. 기존 senderMemberId와 공통 FCM 처리는 남으므로 푸시 본문은 원본 인자를 사용하되 알림 senderNicknameSnapshot은 수신 언어 별칭으로 저장될 수 있다. 이는 공통 알림 기능의 별도 계약이며 v2 DM/WS나 과거 snapshot까지 롤백하지 않는다.
운영자는 문자 종류 제한 없이 JA 이름을 입력하며, 비공백 값은 문자 변경이나 음역 없이 보존한다. 저장 길이는 255 code point이며, UTF-8 byte나 UTF-16 code unit이 아닌 Unicode code point 기준으로 센다. 임의 Unicode를 허용하고 255 초과 입력은 쓰기 전에 관리 경계에서 거부하며 자르지 않는다. 빈 문자열 저장은 JA 이름 해제다. 공백-only 해석, 중복 별칭의 DB 제약/회원 ID 처리, ADMIN route/대상 판정은 기술 제안이다.
인터뷰 명확도 자체 평가: 약 0.10. 차원별 점수는 Goal 1.0, Scope 0.9, Constraints 0.9, Success 0.9, Context 0.75다. 제품 질문은 정리됐으며 외부 시스템 경로·소유자 계약은 별도 blocker로 남는다.
## 2. 제품 요구사항
| ID | 상태 | 요구사항 및 수용 사례 |
|---|---|---|
| NAME001 | 확정 | 관리자가 CREATOR 회원의 JA 이름을 수동 저장·갱신·해제한다. 빈 값 저장은 해제다. |
| NAME002 | 확정 | JA 요청은 JA 별칭을 원본보다 우선하고, 미등록이면 현재 `Member.nickname`으로 fallback한다. 원본 변경 후에도 별칭을 유지한다. |
| NAME003 | COR022 범위 보정 | AudioContentMainTab/MainController/Service, CharacterCommentService/Repository, ContentSeriesService/Repository 및 레거시 message/MessageService/Repository의 이번 이름 변경을 제외하며 별도 호환 raw 모드를 만들지 않는다. AudioContentCuration/레거시 커뮤니티·팬톡의 기존 제외 계약과 나머지 앱 표면의 언어별 이름·USER 원본 보존은 유지한다. 공통FCM과 별도v2 커뮤니티·팬톡·시리즈·DM/WS는 적용 대상이다. |
| NAME004 | 확정 | JA 별칭은 요청 locale과 무관하게 원본 닉네임 검색과 함께 검색되고 기존 contains/collation 의미와 필터가 유지된다. |
| NAME005 | 확정 | 일반 USER 이름, 원본 닉네임 편집, 인증/식별 목적의 원본 사용을 변경하지 않는다. |
| NAME006 | 확정 | 기존 언어별 역사 스냅샷과 이미 발송된 payload는 변경하지 않는다. 현재 이름 조회는 요청 언어, 신규 수신자별 payload는 수신자/세션 언어를 따른다. |
| NAME007 | COR012 승인·구현 | 빈 문자열 및 공백-only는 별칭 해제로 처리한다. 그 밖의 입력 문자는 그대로 보존하며 자동 번역·음역은 없다. 저장 상한은 255 code point다. |
| NAME008 | COR014 승인 | 관리자 회원 페이지 목록·검색의 기존 `nickname`은 원본을 유지하고, `localizedNames: Map<String, String>`에 CREATOR의 모든 활성 언어별 등록 이름을 함께 반환한다. 키는 Lang.code, 미등록/해제 언어는 생략하며 미등록·일반 회원은 빈 map이다. 이름 필드는 Accept-Language로 하나를 선택하지 않는다. |
| NAME009 | COR014 승인 | 닉네임 전용 관리자 GET을 제거하고 기존 일본어 PUT의 등록·수정·소프트 해제를 유지한다. PUT의 저장 결과 응답은 유지하며 관리자 일반 콘텐츠 조회는 원본 닉네임을 유지한다. |
| NAME010 | COR018 명확화 | 원본 nickname은 언어 중립 값이다. 한국어·일본어·영어 원본 각각에 대해 요청 언어의 활성 별칭 우선/미등록·해제 시 현재 원본 fallback을 검증한다. 원본과 별칭 문자열이 같은 언어라는 이유로 별칭을 무시하지 않는다. |
### 핵심 수용 사례
| 조건 | 결과 |
|---|---|
| JA 별칭 등록 후 원본 닉네임 변경 | JA 표시/검색은 별칭을 유지하고, KO/EN은 해당 언어의 활성 이름이 있으면 적용하고 없으면 현재 원본을 사용 |
| 같은 JA 별칭을 두 CREATOR에 저장 | 중복 표시명 허용 및 `(member_id, lang)` 고유 기술 설계가 구현 승인될 경우 모두 저장, 결과 회원은 중복 행 없이 구분 |
| JA 별칭이 빈 문자열 | 기술 계획은 행/값을 보존하고 비활성화, 원본 이름 표시 및 원본 검색 지속; 미등록이면 no-op |
| 해제 후 비공백 별칭을 재저장 | 비활성 포함 member+lang 조회로 같은 ID의 행 갱신·재활성화, 반복해도 한 행 유지 |
| JA 별칭이 공백만 | 별칭 해제로 처리하는 기술 제안 승인 시 원본 표시/검색 |
| CREATOR와 USER가 한 작성자 목록에 함께 있음 | CREATOR만 이름 대체, USER는 원래 값 유지 |
| 같은 사용자의 KO/JA 채팅 세션 동시 연결 | 각각 해당 세션 언어에 맞는 신규 payload 수신 |
| 기존 언어별 스냅샷 또는 과거 발송 payload | 과거 값 불변 |
| 언어 중립 캐시/랭킹 materialization | 생산자와 소비자를 조사한 후 언어별 표시 요구 충족 여부를 분류 |
## 3. 외부 의존 및 차단
| ID | 외부 의존 | 담당 역할 | 영향 | 재개 조건 |
|---|---|---|---|---|
| EXT001 | 모바일/클라이언트 전체 표시 표면, locale 전달, client cache와 원본 이름 편집 흐름 | 모바일/클라이언트 소유자 | 서버 변경만으로 전체 앱 노출과 원본 편집 안전을 입증할 수 없음 | 표면 inventory, locale 계약, 캐시 무효화/수명, 원본 편집 경로 및 담당자 확인 |
| EXT002 | 운영자 관리 UI와 배포/인증 연결 | 운영도구/관리 UI 소유자 | 서버 관리 API만으로 운영자 사용자 흐름 완료 불가 | UI 저장소·담당자·인증 주체·배포 위치·연동 방식 확인 |
| EXT003 | RTC/live/chat 세션 locale 및 알림 수신자 언어 계약 | 클라이언트 및 메시징/알림 담당자 | 세션별 언어와 재연결 동작 확인 없이는 전달 언어를 보장할 수 없음 | locale 전달 방식, 변경 시 reconnect 계약, 수신자 언어 결정 시점과 end-to-end 검증 경로 확정 |
외부 경로는 범위에서 제외되지 않는다. 소유 저장소와 파일 경로가 확인되지 않은 외부 작업은 `[blocked]`로 남긴다. 서버 계획의 완료로 앱 전체 요구를 완료 처리하지 않는다.
## 4. 기술 조사와 구현 계약
테이블명과 문서·DDL 파일 작성 범위는 사용자 확정이다. `Lang`/소프트 lifecycle은 기존 수동 관리 패턴에 근거한 기술 결정이며 사용자가 삭제 방식을 직접 선택했다는 뜻이 아니다. COR012에서 서버 구현과 테스트가 승인됐다. API는 승인·구현됐고 운영 DB 적용은 별도 승인 대상이다.
### 별도 이름 테이블과 수동 관리 설계
기존 회원 테이블에 언어별 닉네임 컬럼을 추가하는 방식이 아니라, **크리에이터의 언어별 표시 이름만 저장하는 별도 테이블**을 설계한다. 테이블명은 사용자 확인으로 `creator_localized_name` 확정이다. DDL 초안은 같은 디렉터리의 `schema.sql`에 작성하며 DB에는 적용하지 않는다.
| 데이터 | 저장 위치와 의미 |
|---|---|
| 원본 닉네임 | 기존 `Member.nickname`, 변경하지 않음 |
| 크리에이터 회원 ID | 별도 테이블의 `member_id`, 기존 회원 식별자 참조 |
| 표시 언어 | entity `lang: Lang`, `@Enumerated(EnumType.STRING)` 및 `@Column(nullable = false, length = 10)`; DB `lang VARCHAR(10)`에 enum NAME `KO/EN/JA` 저장, 이번 쓰기는 명시 `JA`만 |
| 수동 등록 이름 | 별도 테이블의 `display_name VARCHAR(255)`, 해당 언어의 표시 이름; 255 Unicode code point 초과는 관리 경계에서 거부하고 자르지 않음 |
| 활성 상태 | `is_active`, 해제 시 false로 바꾸고 이름은 보존; 표시/별칭 검색에는 true만 사용 |
`UNIQUE(member_id, lang)`은 활성/비활성 모두에 적용하고 `is_active`를 포함하지 않는다. clear는 기존 JA 행의 `is_active=false`만 설정해 `display_name`을 보존하며, 없는 행은 no-op이다. 비공백 저장은 member+lang으로 비활성까지 찾아 같은 ID를 갱신·활성화한다. 원본 `Member.nickname`, 다른 언어 행, 과거 언어별 snapshot/전달 payload는 유지한다. 마지막 비활성 값 하나를 남기는 설계이지 모든 개정 이력이나 복원 UI가 아니다.
앱 표시 조회는 요청 `Lang`과 일치하는 활성 이름 및 대상 `Member.role=CREATOR`를 적용한다. 비활성/미등록은 현재 원본 이름으로 fallback한다. 읽기에 JA 전용 gate는 두지 않는다. 관리자 목록은 COR014에 따라 원본과 모든 활성 언어 이름을 분리해 제공하며 전용 관리 GET은 제거한다. 별칭 검색은 요청 언어와 무관하게 활성 JA·CREATOR만 포함한다.
HTTP path/응답의 `locale: ja`는 `Lang.code`이며 DB에는 소문자 `ja`가 아닌 enum NAME `JA`를 저장한다. 요청 경계는 기존 `Lang.fromCode`/`Lang.fromAcceptLanguage`를 사용하고 서비스·repository에는 명시 `Lang`을 전달한다. 자유 문자열/새 enum/언어 converter를 추가하지 않는다. 배너의 KO 기본값은 복사하지 않으며 작성자가 언어를 명시한다. 미래 언어는 기존 `Lang`과 요청 처리를 별도 확장해야 하지만 언어별 컬럼 추가는 필요 없다.
### 기존 패턴 비교와 근거
| 근거 경로·심볼 | 재사용 또는 차이 |
|---|---|
| `src/main/kotlin/kr/co/vividnext/sodalive/chat/character/ChatCharacterBanner.kt:31` (`lang`, `isActive`), `src/main/kotlin/kr/co/vividnext/sodalive/event/Event.kt:24` (`lang`, `isActive`) | 수동 언어별 관리의 기존 `Lang` enum-string/활성 상태 재사용. length 10은 새 DDL과 맞추는 명시 매핑이며 기존 KO 기본값은 재사용하지 않음 |
| `src/main/kotlin/kr/co/vividnext/sodalive/chat/character/service/ChatCharacterBannerService.kt:140` (`deleteBanner`), `src/main/kotlin/kr/co/vividnext/sodalive/admin/event/banner/AdminEventBannerService.kt:202` (`delete`) | `isActive=false` 소프트 해제 근거. 이름의 동일 행 재활성화는 이번 별도 기술 계획이며 배너가 지원한다고 주장하지 않음 |
| `src/main/kotlin/kr/co/vividnext/sodalive/chat/character/repository/ChatCharacterBannerRepository.kt:16` (`findByIsActiveTrueAndLangOrderBySortOrderAsc`) | 기존 Lang 인자·활성 필터 읽기 패턴 재사용. 배너의 KO 대체 정책은 이름 조회에 복사하지 않음 |
| `src/main/kotlin/kr/co/vividnext/sodalive/content/translation/ContentTranslation.kt:15` (`UniqueConstraint`, `contentId`, `locale`) | 소유자+언어별 고유 행만 참고. 자동 번역의 `locale: String` 저장과 달리 수동 이름은 `lang: Lang`을 사용 |
| `src/main/kotlin/kr/co/vividnext/sodalive/i18n/Lang.kt:6` (`code`, `fromCode`, `fromAcceptLanguage`), `src/main/kotlin/kr/co/vividnext/sodalive/i18n/LangInterceptor.kt:18` (`preHandle`) | 기존 KO/EN/JA enum 및 HTTP 경계 매핑 재사용, 요청 언어를 저장 문자열로 새로 정의하지 않음 |
| `src/main/kotlin/kr/co/vividnext/sodalive/common/BaseEntity.kt:16` (`id`, `createdAt`, `updatedAt`) | 관리 ID/생성·수정 시각 구조 참고. SQL 기본 TIMESTAMP 정의는 문서 유지보수 규칙 적용 |
초기 물리 DELETE 설명은 단순한 최소 기술 선택이었으며 프로젝트 관례의 필수 조건이 아니었다. 사용자는 그 이유와 기존 언어 저장 패턴 재사용을 질문했으며 소프트 삭제를 직접 선택한 것은 아니다. 위 수동 관리 근거로 현재 기술 설계를 보정했다.
| 주제 | 제안 | 근거 및 제한 |
|---|---|---|
| 도메인/저장 | `kr.co.vividnext.sodalive.v2.creatorname` 신규 도메인 및 member+lang 고유, displayName non-unique, `VARCHAR(255)` 저장; 신규 entity는 `displayName @Column(nullable = false, length = 255)` | 신규 도메인은 v2 경량 헥사고날 구조. 255 code point를 관리 경계에서 검증하고 초과 입력은 거부한다. DDL 초안 작성만 승인, 실제 DB 호환성은 미검증. 중복 표시명 정책은 인터뷰 확정 선택이 아님 |
| 관리 API | COR014: `PUT /api/v2/admin/creators/{creatorId}/localized-names/ja`만 유지, ADMIN 보호 | 필수 `displayName: String`, 빈 값 soft clear. 기존 PUT 결과 `creatorId`, `locale: ja`, `originalNickname`, nullable `displayName` 및 ApiResponse 유지. 독립 GET은 제거하고 조회는 기존 관리자 회원 목록에 통합한다. 이번 변경의 HTTP 실행 검증은 미수행이다. |
| 관리 검증 | `Member.role == CREATOR`인 대상만 허용하며, 그 중 별도 `Member.memberKind == AI_CHARACTER`도 포함. `memberKind`만 AI_CHARACTER인 `role == USER`는 허용하지 않음 | ADMIN 보호와 role 판정은 근거 기반 기술 제안. 신규 message key만 제안하며 기존 role-edit PUT 불변 |
| 공통 이름 조회 | DB 직접 projection은 `CreatorNameJoin`으로 요청 Lang의 LEFT JOIN+COALESCE를 사용한다. 중립 캐시·수신자별 전달·principal·쓰기 결과 경계는 batch를 사용하며 현재 원본이 필요한 batch는 JOIN+COALESCE 단일 SQL, sparse 별칭이 필요한 곳은 `findLocalizedNames`를 쓴다. | 읽기는 모든 기존 `Lang`에서 활성/CREATOR만 적용하며 JA-only gate가 없다. 쓰기 조회는 비활성 포함 member+lang. 행별 쿼리·전역 Jackson 변환·principal 변경 금지. `LangContext`는 HTTP 경계에서만 읽음 |
| HTTP/DTO 호환 | 레거시/v2 응답 DTO의 field 이름·타입 보존. 필요한 조회 projection에만 내부 memberId/role 추가 | 원본 닉네임 편집 API는 로컬라이즈 값을 원본으로 저장하지 않도록 외부 계약 확인 필요 |
| 검색 | 기존 원본 조건 OR alias `EXISTS`(owner `member_id` 상관, `lang=Lang.JA`/DB `JA`, `is_active=true`, owner `Member.role=CREATOR`); containsIgnoreCase 의미 유지 | 요청 locale과 무관하게 활성 JA만 별칭 검색. Explorer channel, SearchRepository creator branch, MemberRepository의 list/count에 동일 조건과 기존 필터/USER 검색 보존. 콘텐츠·시리즈 제목·detail·tag 검색은 별칭 대상 아님 |
| 푸시/저장 한계 | `FcmSendListener.sendPush`에서 언어별 payload 생성. 기존 `PushNotificationList.senderNicknameSnapshot` mapping이 255자 이름을 보존하는지 확인 | 기존 mapping/컬럼 확장은 이번 계획에 포함하지 않는다. 과거 알림 재작성·이름 자르기 금지. 실제 저장 및 외부 payload 호환성 문제가 확인되면 별도 결정 전 해당 적용은 차단한다. |
| WebSocket | handshake `Accept-Language`를 session attribute로 저장, 미전달 기본 KO. locale 변경은 reconnect 계약 제안 | Redis pubsub에는 원본 메시지/발신 ID 유지, broker에서 세션별 새 payload 구성. 공유 DTO 변이 금지. ACK와 HTTP 응답도 별도 확인 |
| 캐시/스냅샷 | 각 producer/read path를 조사해 현재 이름 조회와 불변 historical snapshot을 구별 | 기존 `LiveRecommendCacheService`의 3시간 캐시는 key에 Lang을 포함. 다른 캐시/랭킹/inbox는 자동 면제하지 않음 |
`schema.sql`은 단일 CREATE TABLE 초안이며 MySQL 컬럼/테이블 COMMENT와 기본 TIMESTAMP 정의를 따른다. signed BIGINT와 member FK/engine/charset 초안 근거는 `docs/plan-task/20260326_member_content_preference_ddl.sql:12`, COMMENT/TIMESTAMP 및 소유자+언어 unique/FK 형태 근거는 `docs/20260910_크리에이터커뮤니티게시물본문번역/schema.sql:5`다. 복합 unique가 FK 지원 인덱스이며 추가 인덱스·displayName 고유성/인덱스·언어 기본값·cascade·check·trigger를 두지 않는다. displayName은 `VARCHAR(255)`이며 실제 DB 호환성은 미검증이다. **DDL 파일 작성 완료와 DB 적용은 별개다.** 운영 반영 전에 실제 `member.id` 타입(부호 포함)·engine과 collation/contains 및 저장 호환성을 확인하고 DB 실행을 별도 승인받는다. 현재는 DB 연결/실행이나 운영 호환성을 검증하지 않았다.
## 5. 근거 경로 및 범위 추적
주요 근거와 seed inventory는 계획 문서에 실제 전체 경로 및 test target으로 분류했다. 목록은 감사 시작점이지 전수 완료 선언이 아니다. 기존 `MemberRepository` nickname 검색 경로와 legacy home/rank/recommend 및 v2 content/channel query adapter를 빠짐없이 조사한다.
이 저장소에는 모바일 앱 및 운영 UI 소스가 없다. 외부 API, 캐시 및 RTC 소유 경로는 계약이 확인되기 전 구체 경로를 추정하지 않는다.
## 6. 의사결정 기록
현재 후속 실행 범위는 COR022를 따른다. 이전 실행 금지 및 정적 승인 기록은 당시 이력으로 보존한다.
기존 결정 로그의 행은 요약하지 않고 각각 보존한다. 아래 DEC 항목은 최초 결정의 주제를 명시한 기록이다. COR 행은 그 결정을 보정하고 우선 적용한다.
| 날짜 | ID | 상태 | 결정 |
|---|---|---|---|
| 2026-10-14 | DEC001 | 확정 | 운영자가 일본어 이름을 수동 관리한다. 자동 생성/번역하지 않는다. |
| 2026-10-14 | DEC002 | 확정 | 입력 문자 종류 제한을 두지 않는다. |
| 2026-10-14 | DEC003 | 확정 | JA 이름은 일본어 표시에 우선 적용한다. 미등록 시 원본 이름을 사용한다. |
| 2026-10-14 | DEC004 | 확정 | 원본 `Member.nickname`은 보존한다. |
| 2026-10-14 | DEC005 | 확정 | 앱의 크리에이터 표시 표면을 대상으로 하며 혼합 목록에서도 CREATOR만 변경한다. |
| 2026-10-14 | DEC006 | 확정 | 미래 언어 가능성을 고려할 수 있지만 현재 KO/EN 이름 관리 기능은 만들지 않는다. |
| 2026-10-14 | DEC007 | 확정 | JA 별칭은 기존 원본 닉네임 검색과 함께 검색한다. |
| 2026-10-14 | DEC008 | 확정 | JA 이름 빈 값 저장은 별칭 제거이며 원본 fallback으로 돌아간다. |
| 2026-10-14 | COR001 | 정정 | 별칭은 원본 닉네임 변경 이후에도 우선한다. 미래 언어 준비는 기술 제안일 뿐 제품 범위가 아니다. |
| 2026-10-14 | COR002 | 정정 | 일반 USER와 원본 편집/인증/식별 흐름은 불변. 제품 업무 길이 제한을 추가하지 않는다. 중복 별칭 허용 및 회원 ID+locale 저장은 기술 제안이며 직접 확정된 인터뷰 선택은 아니다. |
| 2026-10-14 | COR003 | 정정, OQ-001 해결 | 원본 이름 검색을 유지하면서 JA 별칭 검색을 더한다. |
| 2026-10-14 | COR004 | 정정, OQ-002 해결 | 빈 문자열 저장으로 JA 이름을 해제한다. 공백-only 해제는 기술 해석 제안으로 별도 승인 대기다. |
| 2026-10-14 | COR005 | 정정, OQ-003 해결 | 과거 언어별 스냅샷/전달 payload는 불변. 현재 조회는 요청 언어, 새 수신자별 payload는 해당 수신자/세션 언어. 언어 중립 캐시를 자동 제외하지 않는다. |
| 2026-10-14 | COR006 | 정정 | `/admin/member` ADMIN 권한은 참고 근거일 뿐 신규 API 소유권 계약이 아니다. `/creator-admin/member` CREATOR/AGENT 관리 화면 대상이 아니다. |
| 2026-10-14 | COR007 | 정정 | PRD와 plan-task 문서 작성만 승인되었다. 구현/테스트/설정/DDL은 별도 승인 전 금지. |
| 2026-10-14 | DEC009 | 확정 | 기존 언어별 과거 스냅샷과 이미 전달된 payload는 변경하지 않는다. 요청 시 현재 이름을 조회하는 경로는 요청 언어, 신규 수신자별 payload는 수신자/세션 언어를 적용한다. |
| 2026-10-14 | COR008 | 후속 확정, COR007 범위 보정 | 사용자 확인으로 테이블명 `creator_localized_name` 확정, 기존 두 문서 보정과 같은 디렉터리 `schema.sql` 파일 작성만 승인. DB 적용·Kotlin·테스트·설정·운영 배포는 미승인이다. |
| 2026-10-14 | COR009 | 근거 기반 기술 결정 | 기존 수동 관리의 `Lang` enum-string과 `isActive`를 재사용한다. DB 키는 member+lang/enum NAME `JA`, HTTP locale은 `Lang.code`의 `ja`다. 초기 물리 DELETE는 단순 기술 선택이지 프로젝트 강제 관례나 사용자 요구가 아니며, 사용자가 소프트 삭제를 직접 선택한 것도 아니다. |
| 2026-10-14 | COR010 | 기술 lifecycle 보정 | clear는 행/값 보존·비활성화, absent는 no-op. 표시/검색/관리 GET은 비활성 제외, 재저장은 비활성 포함 조회로 동일 ID 재활성화. unique는 활성/비활성 전체 member+lang. 전체 이력/복원 기능은 포함하지 않는다. |
| 2026-10-14 | COR011 | 기술 저장 한계 보정 | 사용자는 TEXT가 불필요하다고 확인했다. `VARCHAR(255)`는 기본 JPA nickname 표현에 맞춘 기술 결정이며 사용자가 255를 직접 선택한 것은 아니다. 현재 저장은 255 Unicode code point로 제한하고 초과는 관리 경계에서 거부한다. COR002의 무길이 제한 표현은 현재 저장 한도에 대해 superseded이며 문자 종류 제한 없음은 유지한다. |
| 2026-10-14 | COR012 | 사용자 구현 승인 | 사용자: "DDL + 문서 확인 / 구현 승인" 및 ulw. 현재 문서의 API·저장·소프트 해제·길이·검색·전달 설계를 구현하고 테스트한다. 앞선 제품 구현 미승인 문구를 대체한다. 운영 DB 적용·배포는 승인하지 않았고 외부 저장소 계약은 확인 전 완료로 간주하지 않는다. |
| 2026-10-15 | COR013 | 사용자 조회 방식 수정 승인 | "3가지 경로에 각각 적절한 방식으로 조회하도록 수정하자". DB 직접 이름 projection은 요청 Lang의 LEFT JOIN+COALESCE, 중립 캐시·수신자별 전달 및 기존 원본 엔티티/쓰기 결과 경계는 batch, 이미 언어별로 렌더된 역사 스냅샷은 저장값을 유지한다. 읽기의 JA 전용 제한은 제거하되 검색 JA·관리 /ja 및 저장 정책은 유지한다. |
| 2026-10-15 | COR014 | 사용자 관리자 조회 통합 적용 승인 | "문서에 반영하고 적용한다". 별도 닉네임 GET 대신 기존 `/admin/member/list`와 공통 응답을 쓰는 목록·검색 4개 경로에 모든 활성 언어 이름을 추가한다. PUT의 등록·수정·해제와 결과 응답은 유지한다. 관리자 콘텐츠 원본 표시 및 레거시 관리자 회원 목록은 보존한다. 빌드·테스트 실행 없이 수정·정적 검토만 진행한다. |
| 2026-10-15 | COR015 | 사용자 선택적 롤백·테스트 정리 승인 | ContentMainTab/AudioContentCuration/레거시 커뮤니티·팬톡의 이번 이름 처리만 제거한다. v2와 공유 저장·권한·번역·알림, COR014 관리자 목록/PUT은 유지한다. LegacyCreatorNameRenderer 위임 래퍼는 제거하고 필요한 호출자는 core service를 직접 사용한다. 제거 기능만 검증하는 테스트와 불필요 fixture/import는 정리하되 기존 업무·v2·core 회귀 단언은 보존한다. 기존 미사용 메서드 자체 삭제는 제외하며 빌드·테스트 실행 및 커밋·푸시는 하지 않는다. |
| 2026-10-15 | COR016 | 사용자 최소 수정·통과 검증 승인 | 사용자가 전체 실행의 두 실패를 확인하고 최소 수정하여 통과시키도록 요청했다. AudioContentRepositoryLocalizedNameTest의 H2 번역 payload 적재만 기존 FORMAT JSON 패턴으로 보정한다. 운영 코드/converter/DDL/요구사항/테스트 기대값은 보존한다. 대상 및 회귀 테스트 실행을 재개하되 운영 DB 적용·배포·커밋·푸시는 하지 않는다. |
| 2026-10-15 | COR017 | 사용자 미사용 탭 완전 제외 승인 | AudioContentMainTab*은 사용하지 않으므로 이번 기능 변경에서 배제해도 무관함을 확인하고 수정 승인했다. 탭 7파일의 null 전달 13곳을 되돌려 HEAD diff를 없애고, 공유 운영6파일·테스트2파일에서는 미사용 탭 전용 raw 인자/분기/검증만 정리한다. 실사용 이름·제목 번역과 기존 다른 raw 경계는 유지한다. |
| 2026-10-15 | COR018 | 사용자 테스트·문서7파일 보정 승인 | 원본은 KO가 아니라 임의 언어의 저장값임을 명확히 했다. 공통 service/JOIN 테스트2파일, 대표 HTTP/메시지 테스트3파일, 기존 PRD/계획2파일만 보강한다. 운영 로직은 이미 요청 언어 별칭→원본 fallback이므로 변경하지 않는다. 조건을 생략한 KO 원본 설명을 고치고 기존 테스트에 원본 문자열3종 및 일본어 원본 HTTP/메시지 사례를 반영한다. 신규 테스트 파일·원본 언어 필드·자동 감지·쓰기 언어 확대는 제외한다. |
| 2026-10-15 | COR019 | 사용자 콘텐츠 메인 롤백 승인 | 조사 후 운영3파일(메인 controller/service 전체 변경 및 repository 전용2메서드 이름 변경)의 롤백을 승인했다. 두 메인 파일은 변경 목록에서 제외하고 실제 사용하는 공유 repository·core·v2 테스트는 보존한다. 전용 추가 테스트0건이므로 테스트 삭제는 하지 않는다. 새로운 원본 보호 모드·API 삭제·운영 적용은 포함하지 않는다. |
| 2026-10-16 | COR020 | 사용자 캐릭터 댓글 롤백·테스트 제거 승인 | CharacterCommentService/Repository 두 운영파일 변경을 HEAD로 되돌리고 LegacyCurrentNameReadIntegrationTest의 shouldLocalizeCharacterCommentWritersWithoutChangingCharacterNameOrUserReplies 1개 및 전용3import/서비스주입을 제거한다. 나머지8개 통합테스트와 캐릭터 배너 테스트는 유지한다. 신규 영구 테스트·API·원본 보호 모드 추가는 제외한다. |
| 2026-10-16 | COR021 | 사용자 시리즈 롤백·제목 검증 보존 승인 | 조사 결과 설명대로 운영2파일의 이름 처리6곳(목록JOIN5+상세batch1)을 롤백한다. 홈·프로필 재사용 경로에도 이름 표시 영향이 있음을 설명하고 진행 승인받았다. AudioContentRepositoryLocalizedNameTest의 혼합 시리즈 테스트는 이름별칭 fixture/기대값/단언만 정리하고 제목 번역·fallback 및 H2 FORMAT JSON 처리를 보존한다. 테스트 메서드/파일 전체 삭제나 새 raw 모드 추가는 하지 않는다. |
| 2026-10-16 | COR022 | 사용자 메시지 전체 롤백 승인 | 조사 결과대로 MessageService/Repository 전체HEAD복원, 전용 MessageListRow 및 MessageServiceLocalizedNameTest(3건) 파일 삭제를 승인했다. 푸시 본문 메타데이터2곳 제거·senderMemberId 및 공통 snapshot 현지화 유지라는 영향을 포함한다. 레거시 API/업무 자체와 공통 FCM·v2 DM/WS 테스트는 삭제하지 않는다. |
DEC003/005/007/008은 각각 원래 사용자 선택을 요약한 결정 기록이다. 공백-only 해석, 중복 별칭의 구체 저장 제약, 구체 API route/ADMIN 관리 경계는 후속 기술 제안이지 별도 인터뷰에서 명시된 사용자 선택이 아니다.
COR002의 member+locale·무길이 제한 표현과 COR007의 DDL 작성 금지는 당시 기록으로 보존하며 현재 범위/저장 결정은 COR008~011이 우선한다.
## 7. 진행 판정
- `plan-task.md`는 NAME001~007, EXT001~003을 구체 task와 검증에 연결한다.
- COR013의 JOIN-T1 공통 계약과 JOIN-T2 DB projection 전환은 구현 및 focused 증거 확인 완료. JOIN-T3 경계 assertion은 통과했으나 최종 전체 build/QA Gate 결과는 대기 중이다.
- 외부 모바일/운영 UI/RTC 계약은 차단 조건·담당 역할·재개 증거를 유지한다.
- COR012까지의 과거 전체 검증은 아래 이력으로 보존한다. COR013 최종 실행은 현재 미완료이며 `plan-task.md`의 COR013 진행 기록만 근거로 삼는다. 외부 앱 전체 표시, 운영 UI, RTC/client 계약 및 운영 DB/provider 한계도 미검증이며 제품 완료를 선언하지 않는다.
- 운영 DB 적용·운영 배포는 별도 승인 대상이다. 커밋·푸시는 별도 사용자 승인 없이 수행하지 않는다.
## 8. 구현 및 검토 상태, 2026-10-14
- 기반 저장/API, legacy 및 v2 내부 HTTP/검색 소비자, 서버 FCM/WebSocket/live/message 경로가 구현됐다. 세 inventory의 변경 기록과 `/var/folders/yh/8xsbvpsj5wg2qnxzxdp11_gm0000gn/T/opencode/creatorname-integrated-full.log`의 최종 성공 실행을 근거로 한다.
- 당시 최종 전체 실행: 322 suites, 2245 tests, failures 0, errors 0, skipped 0. `assemble`와 `ktlintCheck` 포함 명령이 `BUILD SUCCESSFUL`로 종료됐다. 이는 COR013 전 과거 이력이다. 이전 200 fixture/context 실패 실행과 로그도 당시 기록으로 보존한다.
- 테스트가 실제 관리 API JWT HTTP를 사용했다. 테스트 서버는 HTTP 53418, WebSocket 53427에서 기동됐고 teardown curl은 양 포트 연결 거부(exit 7)를 확인했다. Hikari pool 종료를 로그에서 확인했으며 테스트 후 잔류 JVM/Redis 프로세스는 보고되지 않았다.
- 전체 앱 클라이언트 표시/원본 편집 안전성, 운영 관리 UI, RTC reconnect/provider 및 실제 운영 DB 적용은 확인되지 않았다. EXT001~003과 운영 DB/provider 호환성은 blocker다.
- Oracle 검토에서 두 보완점이 확인됐다. 현재 이름 fallback 경로의 `findAllById` entity graph 조회를 scalar ID/nickname 조회로 바꾸고, 공통 helper 두 개를 `v2.creatorname` 하위로 이동한다. cache 실제 hit를 입증하는 테스트 assertion도 추가할 필요가 있다. 수정 담당자가 작업 중이며 아직 수정·재검증·리뷰 승인 완료로 기록하지 않는다.
- 검증 환경에 `lsp_diagnostics` 도구가 없어 LSP 진단은 수행하지 못했다. compile, 전체 테스트, assemble, ktlint 결과는 위 실행 로그가 근거다.
## 9. 최종 서버 검증, 2026-10-15
- 리뷰 지적 2건 해결: 이름 전용 현재 원본 조회를 `MemberQueryRepository.findNicknamesByIds` scalar 조회로 교체했고 공통 renderer/predicate를 `v2.creatorname` 아래로 이동했다. 1명/4명 조회에서 JA SQL 2/2회, KO·EN 1/1회, 엔티티 로드 0/0을 테스트로 확인했다.
- COR013 전 당시 전체 회귀: 322 suites, **2249 tests / failures 0 / errors 0 / skipped 0**, `test assemble ktlintCheck --continue --offline --console=plain` 성공. 이후 상위 에이전트의 `./gradlew build --offline --console=plain`도 성공했다. 이 결과는 COR013 이후 최종 검증을 뜻하지 않는다.
- 실제 표면 재검증: 상위 에이전트가 ADMIN HTTP 4개와 localhost HTTP/WebSocket 9개를 별도 실행해 **13개 모두 통과**했다. 포트 54539/54547의 Tomcat·Hikari 종료와 후속 curl exit 7, 테스트 JVM/Redis 잔존 없음도 확인했다.
- 최종 독립 리뷰: Oracle의 수정분 재검토 **APPROVE**, 중요한 잔여 코드 지적 없음. 실제 캐시 entry의 원본과 방 목록 쿼리 1회 재사용까지 검증했다.
- 외부 모바일/운영 UI/RTC 및 실제 provider/운영 MySQL 호환성은 미검증으로 유지한다. 운영 DB 적용·배포·커밋·푸시는 실행하지 않았다. 상세 명령·로그는 계획 문서 최종 기록을 따른다.
## 10. 조회 경로별 처리, COR013
1. DB에서 이름을 직접 조회하는 목록·projection은 `CreatorNameJoin(owner, lang, alias)`로 `creator_localized_name`을 LEFT JOIN한다. 회원 ID·요청 언어·활성 별칭·CREATOR 역할 조건은 ON에 두고 `COALESCE(display_name, nickname)`를 선택한다. 후속 별칭 SELECT와 이름 전용 copy/map을 제거한다. 검색 조건·정렬·집계·페이지·공개 DTO는 보존한다.
2. 중립 캐시와 Redis payload, 수신자/세션 언어가 늦게 정해지는 전달, 인증 principal 및 기존 원본 엔티티를 유지해야 하는 쓰기/오류 경계는 필요한 batch를 유지한다. 현재 원본까지 필요한 batch는 member+별칭 JOIN의 단일 SQL로 처리하고 sparse 별칭 map은 명시 fallback 의미가 있는 곳에만 쓴다. 세 inventory의 잔여 호출 분류를 따른다.
3. 이미 언어별로 렌더해 저장한 역사 이름은 그대로 반환한다. 중립 랭킹/inbox/cache는 historical rendered snapshot과 구별하며, cache hit에서도 현재 이름을 렌더한다.
읽기 서비스와 저장소는 전달받은 기존 `Lang`을 사용한다. JA/KO/EN 각각 활성 이름이 있으면 해당 값을, 없거나 비활성이면 원본을 반환한다. 현재 관리자 입력 /ja 및 저장의 일본어 범위, 검색의 JA 별칭 EXISTS는 이번 조회 리팩터링에서 확장하지 않는다. `Member.nickname` 원본과 인증/편집 경계는 그대로 둔다. 승인된 세 inventory의 COR013 최신 구간이 개별 소비자와 남은 batch를 분류한다.
### COR013 구현 및 검증 상태, 2026-10-15
- JOIN-T1 공통 `CreatorNameJoin` 및 모든 Lang의 sparse/current-name 조회 계약, JOIN-T2의 직접 DB projection 전환은 구현됐다. legacy/v2/live/message/DM 목록 경로는 각 inventory의 COR013 manifest를 기준으로 한다.
- JOIN별 owner alias는 고유하게 지정한다. 삭제 prefix 정리는 raw 원본 이름에만 적용하며 수동 별칭 원문은 바꾸지 않는다. 기존 count/group/page/filter와 공개 DTO는 보존한다.
- 기준선은 `creatorname-join-baseline.log` 성공(1m53s). core 43개 RED 중 13개 assertion 실패 뒤 GREEN 43개 통과(`creatorname-join-core-green.log`); consumer 3개 RED는 이름 출력이 아닌 추가 alias SELECT 기대 0/실제 1을 포함했다(`creatorname-join-consumer-red.log`). 수정 후 consumer 3개 통과, alias SELECT 0 확인(`creatorname-join-first-green.log`, 2m37s).
- 첫 전체 실행 `creatorname-join-full.log`은 테스트 2266개가 통과했으나 ktlint 서식 오류로 실패했다. 서식 보정 후 `creatorname-join-final-green.log`의 전체 test/build/ktlint가 성공했다. 이후 실사용이 없어진 보조 메서드 2개와 해당 passing helper 테스트 1개만 제거하고 전체 검증을 다시 실행했다.
- 최종 `./gradlew test build ktlintCheck --continue --offline --console=plain` 성공: **2265 tests / failures 0 / errors 0 / skipped 0**, `creatorname-join-release-check.log`의 `BUILD SUCCESSFUL in 13m 45s`. 실제 ADMIN JWT HTTP 4개와 localhost HTTP/WebSocket 9개도 포함되어 통과했다.
- 대표 콘텐츠·검색·라이브 추천의 별칭 전용 후속 SELECT는 각각 1회에서 0회로 줄었다. 캐시 current-name batch는 요청 Lang에 무관하게 1 SQL이며 sparse 수신자 override와 역사 스냅샷 보존도 검증했다. 운영 지연 시간 개선을 측정한 것은 아니다.
- Oracle 3-path 리뷰에 중대한 코드 지적이 없었고, 미사용 보조 메서드 제거 후 수정분 재검토도 APPROVE다. 최종 실행 결과로 runtime 조건을 충족했다. HTTP 58173/WS 58186 종료 및 후속 curl exit 7, 테스트 JVM/Redis 잔존 없음도 확인했다.
- 제품 전체 완료는 별개다. 모바일/client, 운영 UI, RTC/provider 및 실제 MySQL 호환성은 외부 확인이 필요하며 운영 DB 적용·배포·커밋·푸시는 수행하지 않는다.
## 11. 관리자 조회 통합, COR014
- 대상: `/admin/member/list`, `/admin/member/search`, `/admin/member/creator/list`, `/admin/member/creator/search`. 공통 `GetAdminMemberListResponseItem`에 `localizedNames`만 추가하고 기존 필드·totalCount·순서·페이지 크기는 유지한다. 이는 의도적인 관리자 JSON 응답 확장이다.
- 원본 `nickname`은 그대로 두고 CREATOR의 모든 활성 등록 이름을 `{"ja":"등록 이름","en":"등록 이름"}` 형태로 제공한다. 특정 언어로 필터링하거나 원본을 미등록 언어에 채우지 않는다. soft 해제된 값은 노출하지 않으며 일반 회원과 별칭 없는 회원은 `{}`다.
- 회원 페이지를 먼저 읽고 해당 페이지의 CREATOR ID들에 대한 모든 활성 언어 이름을 한 번에 조회한다. 다언어 1:N 조인으로 회원 페이지/건수가 증가하지 않도록 기존 페이지 쿼리는 보존하고 회원별 추가 조회는 하지 않는다. 역할·로그인 방식 등의 기존 번역 문구는 유지한다.
- `/search-by-nickname`과 `/creator/all/list`의 별도 간단 DTO, 관리자 콘텐츠/시리즈/댓글의 원본 닉네임 표시, 일반 앱의 COR013 언어별 표시·JA 검색은 변경하지 않는다.
- 독립 GET과 더 이상 운영 호출이 없는 단건 조회 서비스는 제거한다. `CreatorLocalizedNameResponse`는 PUT 확인 응답에 계속 사용하므로 유지한다. 별도 POST/DELETE, 전체 언어 신규 GET, 레거시 API 제거, H2 보정/DDL 변경은 추가하지 않는다.
- 실행 제한: 테스트를 먼저 작성하되 사용자 빌드 금지에 따라 Gradle·컴파일·테스트·앱 실행을 하지 않는다. 실제 RED/GREEN·HTTP 성공은 미검증으로 기록하며 이전 통과 수치를 이번 변경의 증거로 재사용하지 않는다.
### COR014 적용 결과
- 공통 관리자 목록 항목에 `localizedNames`를 추가했다. 기존 페이지 조회 후 CREATOR ID의 모든 활성 이름을 단일 scalar 조회로 묶으며, `nickname`과 기존 페이지/count 쿼리는 유지한다. 간단 선택 API와 관리자 콘텐츠 원본 이름 조회는 변경하지 않았다.
- 전용 닉네임 GET 및 미사용 `getLocalizedName` 서비스를 제거했다. PUT과 그 확인 응답 `CreatorLocalizedNameResponse`는 유지한다. 새 전체 언어 GET이나 별도 POST/DELETE는 추가하지 않았다.
- 관리자 4개 목록/검색, Accept-Language 독립, 다언어 페이지 중복 방지, USER·해제 제외, 빈 ID/일괄 쿼리 수, 제거한 GET, 기존 PUT lifecycle·권한·255/256 code point 테스트 코드를 작성·보정했다. 실행하지 않았다.
- 독립 리뷰는 **PASS(static)**이며 명백한 호출·타입·권한·페이지 계약 문제는 발견되지 않았다. 빌드/테스트/DB/HTTP 실행 성공을 의미하지 않는다. 사용하지 않는 레거시 API 제거와 H2 보정 변경은 이번 범위 밖으로 유지했다.
@@ -1,47 +0,0 @@
# COR015 레거시 이름 정리 정적 리뷰
## 리뷰 정보
- 날짜: 2026-10-15
- 대상: 기존 미커밋 COR012~014 변경 위의 COR015 선택적 롤백·테스트 정리. 전체 HEAD diff를 이번 변경으로 간주하지 않는다.
- 기준: 같은 디렉터리 상위 `prd.md` COR015, `plan-task.md` LEGACY-TRIM-T1의 S1~S3.
- 독립 검토 세션: `ses_ec179d026ffeTbyj1KNLcvwUpg`.
- 판정: **APPROVE(static)**. 확정 발견 사항 없음. 실행 검증 승인이나 테스트 통과 판정은 아니다.
## 확인 결과
| 기준 | 정적 확인 |
|---|---|
| S1 제외 영역 원본 표시 | 7개 콘텐츠 탭의 중첩 목록·랭킹·추천·태그·큐레이션, 레거시 커뮤니티 목록/상세/첫 댓글/댓글/답글/구매 및 팬톡 목록/작성/수정에서 원본을 사용한다. 기존 삭제 회원 접두사 처리를 보존한다. |
| S2 유지 대상 보존 | nullable 이름 언어는 공유 조회의 원본 모드만 제어하며 제목 번역 언어는 유지한다. Home 등 유지 호출자는 요청 Lang을 전달한다. v2 커뮤니티·팬톡 JOIN, 관리자 회원 목록의 localizedNames와 PUT을 보존한다. |
| S3 의존성·테스트 정리 | 삭제 래퍼/helper/필드의 src 참조가 없다. 테스트 생성자·조회 인자는 production과 일치하며 실제 core 빈이 필요한 4개 테스트에 설정을 유지한다. 래퍼의 SQL 수·역할·빈 입력·현재 원본 fallback 단언은 core 서비스 테스트에 통합했다. |
검토한 주요 테스트는 `AudioContentRepositoryLocalizedNameTest`, `ExplorerLocalizedNameEndToEndTest`,
`LegacyCurrentNameReadIntegrationTest`, `ExplorerServiceTest`, `LegacyFanTalkReplyCharacterizationTest`,
`CreatorLocalizedNameServiceTest`다. 삭제 테스트는 제거된 래퍼 전용이며 기존 업무·번역·권한 및 v2 회귀는 유지한다.
새 raw/shared fixture와 단언에서 정적으로 확정 가능한 실패는 발견하지 못했다.
## 검증과 한계
- 부모와 검토자의 `GIT_MASTER=1 git diff --check`: 오류 없음.
- 부모의 `rg` 잔여 참조/공유 caller 대조 및 미추적 변경 테스트 4개 `git diff --no-index --check`: 지적 없음.
- 사용자 제한으로 Gradle·빌드·컴파일·테스트·lint·앱·HTTP·DB 실행은 하지 않았다. LSP 도구도 제공되지 않는다.
- 실제 SQL 실행, Spring 컨텍스트 기동, HTTP 회귀는 미검증이다. COR013의 과거 통과 기록으로 대체하지 않는다.
- 검증용 프로세스·포트·DB 연결을 생성하지 않았다. 운영 적용·배포·커밋·푸시도 하지 않았다.
- 확정 회귀 수정 Task 전환 항목 없음. 실행 허용 후 COR014/COR015의 focused·영향 회귀 검증이 필요하다.
## COR016 실행 결과에 따른 후속 판정
- 사용자 전체 실행에서 2271건 중 2건 실패가 확인됐다. 앞선 정적 리뷰는 H2 번역 JSON fixture 차이를 놓쳤으며 실행 통과 증거로 사용하지 않는다.
- 확정 항목 `REV-COR016-001`: AudioContentRepositoryLocalizedNameTest의 두 새 번역 fixture가 JSON 객체 대신 JSON 문자열로 저장된다. 랭킹은 converter 역직렬화 예외, 시리즈는 빈 번역 제목의 원문 fallback으로 실패한다. 요구사항·기대값은 유효하고 두 테스트 모두 유지 대상이다.
- 소유 Goal: `JSON-FIXTURE-T1`. 수정은 두 fixture에 기존 H2 FORMAT JSON 적재 패턴을 추가하는 것으로 제한했다. 운영 코드와 단언은 그대로다.
- focused 검증: `./gradlew test --tests 'kr.co.vividnext.sodalive.content.AudioContentRepositoryLocalizedNameTest' --offline --console=plain` exit 0, 6건 모두 통과, 22초. 실제 H2/JPA 조회에서 닉네임 raw/KO/JA와 번역 제목 단언을 확인했다.
- 전체 회귀·ktlint 및 수정분 독립 리뷰: 진행 중. 그 결과 확인 전 전체 완료로 간주하지 않는다.
### COR016 최종 결과
- 독립 좁은 리뷰 `ses_ec1576ac3ffesO9K10ayy0JKzr`: **APPROVE**. H2-only scoped update와 flush/clear 순서, 단언 보존을 확인했다.
- 전체 테스트: 323 suites/2271 tests/실패0/오류0/skip0. 첫 복합 명령은 test lint 줄바꿈 오류로 종료 코드 1이므로 전체 명령 성공으로 기록하지 않는다.
- 후속 형식 보정: 테스트의 인자 줄바꿈과 이전 HomeService 래퍼 전환 호출의 줄바꿈 1곳을 정리했다. 운영 의미와 기대값 변화는 없다.
- 최종 focused+전체 ktlint 명령: 종료 코드 0, 40초, 대상 클래스6건+HomeService1건 모두 통과하고 ktlintCheck도 통과했다. 전체 회귀 재실행은 형식 변경뿐이므로 생략했다.
- `REV-COR016-001` 수정·검증 완료. 부모가 전체/후속 XML 집계와 테스트 프로세스 잔존 없음, HomeService 공백 제거 내용 동일을 확인했다. 상세 명령·로그는 plan-task.md의 COR016 기록을 따른다.
@@ -1,24 +0,0 @@
# COR017 미사용 탭 제외 리뷰
## 범위와 판정
- 날짜: 2026-10-15
- 기준: PRD COR017, 계획 UNUSED-TAB-T1. 기존 COR012~016 전체 diff가 아니라 미사용 탭 전용 코드 제거 변경만 평가한다.
- 검토 세션: `ses_ec125e618ffej4zvXb6whEPb0z`.
- 판정: **APPROVE**, 차단 문제 없음. 미사용 탭의 원본 닉네임 보존은 요구하지 않는다.
## 근거
| 기준 | 결과 |
|---|---|
| S1 탭 무변경 | content/main/tab의 git diff HEAD가 비어 있다. 7개 서비스의 명시 null 인자13곳이 제거됐으며 API/파일 자체는 유지한다. |
| S2 실사용 조회 보존 | Main/Theme/Home의 언어 전달과 랭킹·시리즈 제목 locale을 유지한다. nameLang 인자를 제거하고 랭킹의 기존 nullable locale 경계 및 큐레이션 raw 조회는 보존한다. |
| S3 테스트 유효성 | 실사용 KO/JA 이름·USER/원본 fallback·제목 번역/fallback·큐레이션2경로 검증과 FORMAT JSON 적재를 유지한다. ID 충돌 시 다음 고유 콘텐츠 ID를 사용하는 fixture 보정은 기존 assertNotEquals와 기능 단언을 약화하지 않는다. |
## 실행 증거
- focused 최초17건 중 fixture ID 가정 실패1건을 확인하고 같은 지정 테스트 파일만 보정했다. 최종17건 및 ktlint 통과, 21초. 두 결과는 creatorname-cor017-focused.log에 보존했다.
- 전체: `./gradlew test ktlintCheck --continue --offline --console=plain` exit0, 8분36초. 부모가 XML을 합산해 323 suites/2271 tests/실패0/오류0/skip0을 확인했다. 로그는 임시 opencode 디렉터리의 creatorname-cor017-full.log다.
- 실제 H2/JPA·기존 HTTP/WS 회귀 포함. JPA/Hikari 종료, 관련 프로세스 잔존 없음, localhost:52527 후속 curl 연결 실패(exit7)를 확인했다.
- 최종 탭 HEAD diff 없음과 git diff --check 무지적. 검토 시 대기하던 전체 실행 Gate도 해소됐다.
- 신규 회귀 수정 Task 전환 항목 없음. 운영 DB/배포/커밋/푸시는 하지 않았으며 운영 MySQL·실제 모바일/provider 검증은 수행하지 않았다.
@@ -1,16 +0,0 @@
-- DDL 파일 작성 완료, DB 미적용. 별도 승인 전 실행 금지
-- 운영 적용 전 실제 member.id 타입(부호 포함), member 테이블 engine 및 collation을 확인한다.
CREATE TABLE creator_localized_name (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '식별자',
member_id BIGINT NOT NULL COMMENT '크리에이터 회원 ID (member.id 참조)',
lang VARCHAR(10) NOT NULL COMMENT 'Lang enum 이름 (KO/EN/JA), 현재 관리 대상 JA',
display_name VARCHAR(255) NOT NULL COMMENT '수동 등록 표시 이름 (비활성 시 마지막 값 보존)',
is_active TINYINT(1) NOT NULL DEFAULT 1 COMMENT '활성 여부 (0: 이름 해제, 1: 표시 및 별칭 검색 대상)',
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
PRIMARY KEY (id),
CONSTRAINT uk_creator_localized_name_member_lang UNIQUE (member_id, lang),
CONSTRAINT fk_creator_localized_name_member
FOREIGN KEY (member_id) REFERENCES member (id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='크리에이터 언어별 수동 표시 이름';
@@ -1,370 +0,0 @@
# P2 v2 HTTP 이름 적용 지도 및 GREEN 인계
> 2026-10-15 COR013의 현재 구현 상태는 문서 마지막의 **COR013 JOIN 전환 manifest**를 따른다. 위아래의 COR012 batch 설계/검증 이력은 당시 기록으로 보존한다. COR013 runtime GREEN은 부모의 직렬 검증 전까지 미확인이다.
## 상태와 경계
- 기준: `prd.md` COR012 및 `plan-task.md` P2-T1, NAME002/003/005/006. 첫 단계의 통합 테스트 4개에 이어 아래 앱 표면의 운영 연결과 필수 생성자/fixture 적응을 구현했다. PRD/plan, 설정, DDL, core/legacy 전달 코드는 수정하지 않았다.
- **구현됨, 부모 직렬 GREEN 검증 대기**다. 부모 RED 로그 `creatorname-consumer-red.log` 100~110행에서 네 테스트의 실제 이름 assertion 실패를 확인했다. 아래 모든 HTTP 행과 blocked-message 행은 구현했으며 테스트/빌드/린트 통과나 수동 HTTP QA 완료를 주장하지 않는다.
- 경로 약어: `M/` = `src/main/kotlin/kr/co/vividnext/sodalive/`, `T/` = `src/test/kotlin/kr/co/vividnext/sodalive/`. 아래 경로는 이 prefix를 붙인 정확한 기존 파일이다.
- `v2.usercreatorchat`, `v2.creatorname`은 다른 소유자의 수정 영역이다. 추가 승인된 `v2.chat` DTO/service/controller 및 `chat/room/repository/ChatRoomRepository.kt`의 AI projection만 이 세션에서 수정했다. 검색/legacy/비동기 전달은 부모 작업이다.
## 공통 적용 결정
1. 기존 `M/i18n/LangInterceptor.kt#preHandle`이 `Accept-Language`를 해석한다. 각 HTTP controller에서 `LangContext.lang`을 읽어 facade의 명시 `lang: Lang` 인자로 전달한다. 이름 기능 때문에 내부 서비스에서 request scope를 새로 읽거나 언어를 다시 추정하지 않는다. 기존 콘텐츠 번역 로직의 언어 선택은 별도 기능으로 보존한다.
2. facade가 조회 결과의 **실제 이름 주인 member ID**를 합쳐 `CreatorLocalizedNameService.findLocalizedNames(memberIds, lang)`을 batch 호출한다. 응답 전 domain/record `copy`로 `map[id] ?: originalName`을 선택한다. 하나의 목록에 DB 행별 호출을 하지 않는다. 공유 DTO, JPA `Member.nickname`, principal, 저장 snapshot을 변이하지 않고 공개 DTO field 이름/타입도 유지한다.
3. CREATOR가 댓글 작성자/답글 작성자/후원자로 등장해도 적용 대상이다. `writerId`, donor `memberId`로 찾으며 채널 owner ID를 대신 쓰지 않는다. USER는 같은 이름 필드여도 그대로다. foundation의 활성 JA + 현재 `Member.role == CREATOR` 필터를 사용하고 `memberKind`만으로 판정하지 않는다.
4. 중립 ranking snapshot 이름은 현재 원본이 아니다. 이 두 ranking consumer는 owner IDs로 `MemberRepository.findNicknamesByIds`도 한 번 호출해 엔티티 로드 없이 현재 원본을 확보하고 JA map을 우선한다. KO/EN 또는 JA 미등록은 **현재** nickname으로 fallback한다. 삭제된 owner의 기존 표시 정책은 유지하며 저장 row를 갱신하지 않는다. 차단 마스킹된 creator ID `0`/빈 이름을 복구하지 않는다.
## 작성한 실제 회귀 테스트
| 정확한 기존 파일 / 새 심볼 | 실제 경로와 기대 동작 |
|---|---|
| `T/v2/api/content/all/adapter/in/web/MainContentAllEndToEndTest.kt#shouldSelectLocalizedCreatorNamesWithoutChangingAudioTitles` | `GET /api/v2/audio/contents?type=AUDIO`: 저장 후 원본을 변경해도 JA 별칭 우선, KO는 변경된 원본, JA 미등록 작성자는 원본, audio title 불변. 별도 USER를 먼저 저장해 content ID와 owner member ID를 분리하며 내부 owner ID는 JSON에 노출하지 않는다. |
| `T/v2/api/creator/channel/community/adapter/in/web/CreatorChannelCommunityEndToEndTest.kt#shouldLocalizeCreatorAuthorsAndLatestRepliesWithoutChangingUserNames` | `GET /api/v2/creator-channels/community-posts/{postId}`: post creator, CREATOR root comment, USER root comment, CREATOR latestReply를 함께 저장한다. JA는 CREATOR만 별칭이며 USER는 잔존 별칭 row가 있어도 원본이다. 본문은 이름 치환 대상이 아니다. |
| `T/v2/api/home/CreatorRankingControllerTest.kt#shouldRenderCurrentLocalizedNamesWithoutRewritingRankingSnapshots` | `GET /api/v2/home/rankings/creators`: 원본 이름으로 중립 snapshot 저장 후 회원 원본 변경. JA 별칭/JA 미등록 현재 원본/KO 현재 원본을 검증하고 DB snapshot 이름과 회원 원본 보존을 단언한다. |
| `T/v2/api/home/HomeRecommendationControllerTest.kt#shouldLocalizeNativeDebutCreatorResultsByRequestLanguage` | `GET /api/v2/home/recommendations/debut-creators`: 실제 live 활동으로 native CTE 후보를 만든다. 원본 변경 후 KO 현재 원본과 JA 별칭을 검증한다. repository/query service를 mock하지 않는다. |
픽스처는 기존 `saveMember`, `saveAudioContent`, `saveCommunity`, `saveCommunityComment`, `saveSnapshot`, `saveLiveRoom`과 실제 JPA 저장을 재사용한다. 별칭만 허용된 H2 `JdbcTemplate` INSERT로 저장했다. `member_id`, enum NAME `'JA'`, `display_name`, `is_active`, BaseEntity 시각 컬럼을 명시하며 production DDL 실행/새 schema 생성/반사 호출은 없다. USER의 alias row는 관리 API가 USER 저장을 허용한다는 뜻이 아니라 역할 변경 후 잔존 행과 같은 읽기 필터 회귀를 재현한다. 기존 번역/외부 미디어 mock은 유지했으며 이름 서비스는 mock하지 않았다.
### 부모 RED 명령
foundation 준비 후 한 번에 하나씩 실행한다. 첫 단계는 새 메서드만 좁혀서 실제 이름 assertion 실패인지 확인한다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.content.all.adapter.in.web.MainContentAllEndToEndTest.shouldSelectLocalizedCreatorNamesWithoutChangingAudioTitles'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.community.adapter.in.web.CreatorChannelCommunityEndToEndTest.shouldLocalizeCreatorAuthorsAndLatestRepliesWithoutChangingUserNames'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.home.CreatorRankingControllerTest.shouldRenderCurrentLocalizedNamesWithoutRewritingRankingSnapshots'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.home.HomeRecommendationControllerTest.shouldLocalizeNativeDebutCreatorResultsByRequestLanguage'
```
예상 RED 지점은 각각 `creatorNickname` JA 기대값, post/comment/reply JA 이름, ranking `nickname` JA 기대값, native debut `creatorNickname` JA 기대값이다. 테이블 미생성, 컴파일/컨텍스트 실패, SQL fixture 실패는 RED 증거로 취급하지 않는다. GREEN 뒤에는 같은 명령과 아래 HTTP owner의 전체 class 회귀를 수행한다.
### foundation 선행 인터페이스 확인
- 조사 시작 때 파일이 없었지만 인계 전 실제 소스를 다시 읽었다. `M/v2/creatorname/application/CreatorLocalizedNameService.kt#findLocalizedNames(memberIds: Collection<Long>, lang: Lang): Map<Long, String>`와 `#saveLocalizedName(creatorId: Long, lang: Lang, displayName: String)`가 현재 존재한다.
- `M/v2/creatorname/adapter/out/persistence/CreatorLocalizedNameEntity.kt`는 `creator_localized_name` 및 위 INSERT 컬럼, enum-string `Lang`, BaseEntity 상속과 일치한다. `M/v2/creatorname/adapter/in/web/AdminCreatorLocalizedNameController.kt`의 ADMIN PUT도 확인했다. 시그니처 추측이나 임시 타입은 추가하지 않았다.
- 후속 상태: 부모가 foundation 18 tests PASS 및 검토 완료를 전달했고 consumer RED도 실행했다. 초기 조사 당시의 repository `emptyMap()` 미구현 관찰은 더 이상 현재 blocker가 아니다. 이번 소비자는 실제 foundation 필수 생성자 의존성을 사용하며 nullable/optional service 우회가 없다.
## HTTP 표면별 정확한 적용 지점
아래 모든 행은 **구현됨, GREEN 대기**다. 각 controller는 `LangContext.lang`을 명시 전달하고 facade는 batch와 immutable copy를 수행한다. 아래 초기 설계와 달리 following news는 각 subtype 대신 상위 `HomeFollowingNews.creatorMemberId` 하나에 joined owner를 보존했다. live는 `HomeFollowingLive.creatorMemberId`를 사용한다. 공개 DTO에는 두 필드를 추가하지 않았다.
| 표면 / 응답 이름 | 기존 파일과 심볼 / 필요한 최소 변경 | HTTP test owner |
|---|---|---|
| 홈 추천 `lives`, `recentlyActiveCreators`, `recentDebutCreators`, `firstAudioContents`, `genreCreators[].creators`, `cheerCreators`, `popularCommunityPosts`의 `creatorNickname` | `M/v2/api/home/adapter/in/web/HomeRecommendationController.kt#getHomeRecommendations/getLives/getDebutCreators` → `M/v2/api/home/application/HomeRecommendationFacade.kt#getHomeRecommendations/getLives/getRecentDebutCreators`. 섹션 결과를 모은 후 ID 합집합 batch. banner의 국가 기반 `bannerLang`은 이름 언어로 재사용 금지. `HomeFirstAudioContentRecord.creatorId`는 이미 존재한다. | `T/v2/api/home/HomeRecommendationControllerTest.kt` |
| 홈 live `creatorNickname` | 위 `getLives` 및 `M/v2/api/home/live/adapter/in/web/HomeOnAirLiveController.kt#getOnAirLives` → `M/v2/api/home/live/application/HomeOnAirLiveFacade.kt#getOnAirLives`. 공유 `M/v2/recommendation/port/out/HomeRecommendationQueryPort.kt#HomeLiveRecommendationRecord`에 내부 `creatorMemberId` 추가, `M/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt#findLiveRecommendations`의 QueryDSL constructor projection에 `member.id` 추가. `liveRoomId/roomId`로 alias 조회 금지. | `T/v2/api/home/live/adapter/in/web/HomeOnAirLiveEndToEndTest.kt` |
| 홈 creator ranking `items[].nickname` | `M/v2/api/home/adapter/in/web/CreatorRankingController.kt#getCreatorRankings` → `M/v2/api/home/application/HomeCreatorRankingFacade.kt#getCreatorRankings`. `M/v2/ranking/application/CreatorRankingQueryService.kt#getCreatorRankings` 결과의 `items[].creatorId`를 batch key로 사용. snapshot 원본이 아닌 현재 Member fallback도 batch 조회. 기존 block mask와 rank/rankChange/isNew 유지. | `T/v2/api/home/CreatorRankingControllerTest.kt` |
| 팔로잉 creator/live/schedule/news 이름 및 recentChats | `M/v2/api/home/following/adapter/in/web/HomeFollowingController.kt#getFollowingTab` → `M/v2/api/home/following/application/HomeFollowingFacade.kt#getFollowingTab`. `M/v2/home/following/domain/HomeFollowing.kt`: `HomeFollowingCreator.creatorId`, `HomeFollowingSchedule.creatorId`, `HomeFollowingCreatorRankingNews.creatorId` 재사용. `HomeFollowingLive`, `HomeFollowingContentNews`, `HomeFollowingCommunityPostNews`에 내부 owner 추가. `M/v2/home/following/adapter/out/persistence/DefaultHomeFollowingQueryRepository.kt#findOnAirLives/findRecentNews/toHomeFollowingNews`에 현재 join한 `creator.id` selection/전달 추가. `audioContent`, `photoContent`, `communityPost`의 이름과 creatorRanking `nickname`을 분기별 copy. recentChats는 아래 v2.chat 소유 경계 사용. | `T/v2/api/home/following/adapter/in/web/HomeFollowingEndToEndTest.kt` |
| 전체 콘텐츠 audio/series `creatorNickname` | `M/v2/api/content/all/adapter/in/web/MainContentAllController.kt#getContents` → `M/v2/api/content/all/application/MainContentAllFacade.kt#getContents`. `M/v2/content/all/domain/MainContentAll.kt#MainContentAllAudio/MainContentAllSeries`에 내부 `creatorMemberId` 추가. `M/v2/content/all/adapter/out/persistence/DefaultMainContentAllQueryRepository.kt#findAudios/findSeries`에서 전달. audio row는 owner를 이미 select하지만 domain에서 버린다. series는 `member.id` selection도 추가. title 번역/정렬/pagination 불변. | `T/v2/api/content/all/adapter/in/web/MainContentAllEndToEndTest.kt` |
| 콘텐츠 추천 5종 audio card `creatorNickname` | `M/v2/api/content/recommendation/adapter/in/web/AudioRecommendationController.kt#getRecommendations` → `M/v2/api/content/recommendation/application/AudioRecommendationFacade.kt#getRecommendations`. `M/v2/content/recommendation/domain/AudioRecommendation.kt#AudioCard`에 내부 owner 추가. `M/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepository.kt#audioRows/toAudioCards`의 이미 select한 `audioContent.member.id`를 card까지 전달. `latestAudios/newAndHotAudios/freeAudios/pointAudios/recommendedAudios` 합집합 batch. `OriginalSeries`, `CommentedAudio`는 이름 필드 없음. | `T/v2/api/content/recommendation/adapter/in/web/AudioRecommendationEndToEndTest.kt` |
| 콘텐츠 overview `items[].creatorNickname` | `M/v2/api/content/overview/adapter/in/web/ContentOverviewController.kt#getContents` → `M/v2/api/content/overview/application/ContentOverviewFacade.kt#getContents/getNewAndHotContents/getFirstAudioContents`. NEW_AND_HOT은 위 `AudioCard` owner 추가 사용. FIRST_AUDIO는 `M/v2/recommendation/port/out/HomeRecommendationQueryPort.kt#HomeFirstAudioContentRecord.creatorId`가 이미 있으므로 새 owner 필드 불필요. native first-audio CTE 결과 이름도 batch copy. | `T/v2/api/content/overview/adapter/in/web/ContentOverviewEndToEndTest.kt` |
| 오디오 ranking `items[].creatorNickname` | `M/v2/api/content/ranking/adapter/in/web/AudioRankingController.kt#getRankings` → `M/v2/api/content/ranking/application/AudioRankingFacade.kt#getRankings`. `M/v2/content/ranking/domain/AudioRanking.kt#AudioRankingItem`에 내부 `creatorMemberId` 추가. `M/v2/content/ranking/application/AudioRankingQueryService.kt#toItem`에서 기존 snapshot record owner를 버리지 않고 전달. facade가 현재 Member + alias batch로 선택. locale별 content title은 손대지 않음. | `T/v2/api/content/ranking/adapter/in/web/AudioRankingControllerTest.kt` |
| 채널 home `creator.nickname`, `notices/communities[].creatorNickname`, `fanTalk.latestFanTalk.nickname`, `channelDonations[].nickname` | `M/v2/api/creator/channel/home/adapter/in/web/CreatorChannelHomeController.kt#getHome` → `M/v2/api/creator/channel/home/application/CreatorChannelHomeFacade.kt#getHome`. `M/v2/creator/channel/home/domain/CreatorChannelHome.kt`의 creator/post/member IDs 재사용. donation만 내부 donor memberId 추가: 같은 파일 `CreatorChannelDonation`, `M/v2/creator/channel/home/port/out/CreatorChannelHomeQueryPort.kt#CreatorChannelDonationRecord`, `M/v2/creator/channel/home/adapter/out/persistence/DefaultCreatorChannelHomeQueryRepository.kt#findChannelDonations`, `M/v2/creator/channel/home/application/CreatorChannelHomeQueryService.kt#toDomain`. 모든 이름 주인 합집합 batch, fan/donor가 CREATOR인 경우도 적용. | `T/v2/api/creator/channel/home/CreatorChannelHomeEndToEndTest.kt` |
| 채널 community tab/detail 및 댓글/답글 `creatorNickname/writerNickname` | `M/v2/api/creator/channel/community/adapter/in/web/CreatorChannelCommunityController.kt#getCommunityTab/getCommunityPostDetail/getCommunityComments/getCommunityReplies` → `M/v2/api/creator/channel/community/application/CreatorChannelCommunityFacade.kt`의 같은 네 심볼. `M/v2/creator/channel/community/domain/CreatorChannelCommunityTab.kt#CreatorChannelCommunityPost.creatorId`, `M/v2/creator/channel/community/domain/CreatorChannelCommunityPostDetail.kt#CreatorChannelCommunityComment/CreatorChannelCommunityReply.writerId`가 존재. detail은 post/comment/latestReply ID를 합쳐 한 번 lookup. 별도 댓글/답글 endpoint도 각각 처리. translator의 postId와 이름의 memberId를 혼용하지 않는다. | `T/v2/api/creator/channel/community/adapter/in/web/CreatorChannelCommunityEndToEndTest.kt` |
| 채널 fanTalk와 creatorReplies `writerNickname` | `M/v2/api/creator/channel/fantalk/adapter/in/web/CreatorChannelFanTalkController.kt#getFanTalkTab` → `M/v2/api/creator/channel/fantalk/application/CreatorChannelFanTalkFacade.kt#getFanTalkTab`. `M/v2/creator/channel/fantalk/domain/CreatorChannelFanTalkTab.kt#CreatorChannelFanTalk/CreatorChannelFanTalkReply.writerId` 합집합으로 batch. USER 팬 이름 보존, CREATOR 작성자/답글은 적용. | `T/v2/api/creator/channel/fantalk/adapter/in/web/CreatorChannelFanTalkEndToEndTest.kt` |
| 채널 donation `rankings[].nickname`, `donations[].nickname` | `M/v2/api/creator/channel/donation/adapter/in/web/CreatorChannelDonationController.kt#getDonationTab` → `M/v2/api/creator/channel/donation/application/CreatorChannelDonationFacade.kt#getDonationTab`. `M/v2/creator/channel/donation/domain/CreatorChannelDonationTab.kt#CreatorChannelDonationRanking.userId`는 실제 donor member ID다. donation list는 donor ID를 추가: 같은 파일 `CreatorChannelDonation`, `M/v2/creator/channel/donation/port/out/CreatorChannelDonationQueryPort.kt#CreatorChannelDonationRecord`, `M/v2/creator/channel/donation/adapter/out/persistence/DefaultCreatorChannelDonationQueryRepository.kt#findChannelDonations`, `M/v2/creator/channel/donation/application/CreatorChannelDonationQueryService.kt#toDomain`. USER 불변, CREATOR donor만 적용. | `T/v2/api/creator/channel/donation/adapter/in/web/CreatorChannelDonationEndToEndTest.kt` |
| 기프트 목록/상세 `counterpartNickname`, `giftInfo.recipientCreatorNickname/senderNickname` | `M/v2/api/gift/adapter/in/web/GiftController.kt#getGifts/getGiftDetail`가 명시 Lang 전달. facade 없는 기존 구조이므로 `M/v2/gift/application/GiftQueryService.kt#getGifts/getGiftDetail/toGiftListItem`의 결과 조립에 resolver 주입. 목록은 이미 batch 조회한 `membersById`의 counterpart IDs, 상세는 이미 읽은 sender/recipient IDs를 묶어 lookup. `applicationNo/giftId`는 key가 아님. `senderInfo.name`, 수령인 실명/주소, categoryNameSnapshot, status/sizeName은 치환 금지. command 응답에는 회원 이름이 없어 수정하지 않음. | `T/v2/api/gift/adapter/in/web/GiftControllerTest.kt` |
## 정상 응답 밖의 표시 경계
- 채널 audio/series/live 정상 응답에는 creator 이름이 없다. `M/v2/api/creator/channel/common/dto/CreatorChannelAudioContentResponse.kt`, `M/v2/api/creator/channel/audio/dto/CreatorChannelAudioTabResponse.kt`, `M/v2/api/creator/channel/series/dto/CreatorChannelSeriesTabResponse.kt`, `M/v2/api/creator/channel/live/dto/CreatorChannelLiveTabResponse.kt`의 title/seriesName을 creator 이름으로 치환하거나 필드를 신설하지 않는다.
- 단, 아래 일곱 query service는 blocked-access 메시지에 `String.format(messageTemplate, creator.nickname)`을 넣는다. 이 이름도 사용자에게 표시된다. 각각 controller → facade → 해당 함수로 `lang: Lang`을 전달하고 **오류 분기에서만** 대상 creator 한 명을 resolver batch API로 조회해 format한다. 정상 응답 facade lookup과 중복 조회하지 않는다. 기존 번역/권한/차단 정책과 message key는 유지한다.
| 정확한 query service / 심볼 | 명시 Lang 전달 facade | 기존 HTTP test owner |
|---|---|---|
| `M/v2/creator/channel/home/application/CreatorChannelHomeQueryService.kt#getHome` | `M/v2/api/creator/channel/home/application/CreatorChannelHomeFacade.kt#getHome` | `T/v2/api/creator/channel/home/CreatorChannelHomeEndToEndTest.kt` |
| `M/v2/creator/channel/community/application/CreatorChannelCommunityQueryService.kt#getCommunityTab` | `M/v2/api/creator/channel/community/application/CreatorChannelCommunityFacade.kt#getCommunityTab` | `T/v2/api/creator/channel/community/adapter/in/web/CreatorChannelCommunityEndToEndTest.kt` |
| `M/v2/creator/channel/fantalk/application/CreatorChannelFanTalkQueryService.kt#getFanTalkTab` | `M/v2/api/creator/channel/fantalk/application/CreatorChannelFanTalkFacade.kt#getFanTalkTab` | `T/v2/api/creator/channel/fantalk/adapter/in/web/CreatorChannelFanTalkEndToEndTest.kt` |
| `M/v2/creator/channel/donation/application/CreatorChannelDonationQueryService.kt#getDonationTab` | `M/v2/api/creator/channel/donation/application/CreatorChannelDonationFacade.kt#getDonationTab` | `T/v2/api/creator/channel/donation/adapter/in/web/CreatorChannelDonationEndToEndTest.kt` |
| `M/v2/creator/channel/audio/application/CreatorChannelAudioQueryService.kt#getAudioTab` | `M/v2/api/creator/channel/audio/application/CreatorChannelAudioFacade.kt#getAudioTab` | `T/v2/api/creator/channel/audio/adapter/in/web/CreatorChannelAudioEndToEndTest.kt` |
| `M/v2/creator/channel/series/application/CreatorChannelSeriesQueryService.kt#getSeriesTab` | `M/v2/api/creator/channel/series/application/CreatorChannelSeriesFacade.kt#getSeriesTab` | `T/v2/api/creator/channel/series/adapter/in/web/CreatorChannelSeriesEndToEndTest.kt` |
| `M/v2/creator/channel/live/application/CreatorChannelLiveQueryService.kt#getLiveTab` | `M/v2/api/creator/channel/live/application/CreatorChannelLiveFacade.kt#getLiveTab` | `T/v2/api/creator/channel/live/adapter/in/web/CreatorChannelLiveEndToEndTest.kt` |
audio/series/live의 controller 파일은 각각 `M/v2/api/creator/channel/audio/adapter/in/web/CreatorChannelAudioController.kt`, `M/v2/api/creator/channel/series/adapter/in/web/CreatorChannelSeriesController.kt`, `M/v2/api/creator/channel/live/adapter/in/web/CreatorChannelLiveController.kt`다. 성공 DTO는 그대로 두고 위 오류 경계의 명시 Lang 인자만 전달한다.
## neutral snapshot / native producer-consumer 분류
| 기존 파일 / 심볼 | 분류와 구현 결정 |
|---|---|
| `M/v2/ranking/adapter/out/persistence/DefaultCreatorRankingAggregationRepository.kt#aggregateAllCandidates/toCandidate` → `M/v2/ranking/application/CreatorRankingSnapshotRefreshService.kt` → `M/v2/ranking/adapter/out/persistence/CreatorRankingSnapshot.kt` → `M/v2/ranking/adapter/out/persistence/DefaultCreatorRankingSnapshotRepository.kt` → `CreatorRankingQueryService#getCreatorRankings` | native SQL이 당시 원본 `Member.nickname`을 저장하며 Lang 컬럼/수신자별 렌더링이 없는 **중립 materialization**이다. 역사 면제 아님. 조회 현재 이름 선택만 추가하고 저장 snapshot/rank/score는 불변. 새 ranking 회귀가 이 구분을 고정한다. |
| `M/v2/content/ranking/adapter/out/persistence/DefaultAudioRankingAggregationRepository.kt#AGGREGATION_SQL` → `M/v2/content/ranking/application/AudioRankingSnapshotRefreshService.kt` → `M/v2/content/ranking/adapter/out/persistence/AudioRankingSnapshot.kt` → `M/v2/content/ranking/adapter/out/persistence/DefaultAudioRankingSnapshotPersistenceAdapter.kt#toRecords/toRecord` → `AudioRankingQueryService#toItem` | `c.member_id`, `m.nickname`을 저장하는 중립 creator 이름. consumer가 locale별 `ContentTranslation` title을 고르지만 creator 이름이 언어별 역사 데이터가 되는 것은 아니다. owner 전달 + 현재 이름 batch 필요. title/renderedPayload/기존 snapshot row는 불변. |
| `M/v2/recommendation/adapter/out/persistence/RecommendationSnapshot.kt` 및 `M/v2/recommendation/application/RecommendationSnapshotRefreshService.kt` → `M/v2/recommendation/application/HomeRecommendationQueryService.kt#findCheerCreatorRecommendations/findPopularCommunityRecommendations` | section/targetId/score 후보 snapshot이고 표시 이름의 언어 snapshot이 아니다. detail 조회(`findCheerCreatorRecommendationDetails`, `findPopularCommunityRecommendationDetails`)에서 현재 member ID와 원본을 얻어 facade에서 batch. targetId는 section에 따라 creator 또는 community resource이므로 alias key로 그대로 사용하지 않음. |
| `M/v2/home/following/application/HomeFollowingNewsPublishService.kt#publishToFollowers` → `M/v2/home/following/adapter/out/persistence/HomeFollowingNewsInbox.kt` → `DefaultHomeFollowingQueryRepository#findRecentNews/toHomeFollowingNews` | Lang 없는 중립 inbox. producer는 raw creatorNickname/title/body를 저장하지만 **HTTP consumer는 creator를 join해 현재 nickname을 다시 읽는다**. creator-ranking title에 저장된 과거 nickname은 현재 응답의 이름 원천이 아니다. consumer의 joined owner ID를 전달해 언어 선택. inbox 저장값/producer는 수정하지 않음. |
| `DefaultHomeRecommendationQueryRepository#findRecentlyActiveCreators/findRecentDebutCreators/findFirstAudioContents/findCreatorsByGenre` | native SQL에서 현재 creator 이름을 읽는 current lookup. 결과 record의 creatorId로 batch한다. 새 native debut HTTP 회귀는 CTE/query/service를 실제 실행하도록 작성했다. |
| `M/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepository.kt` | card의 이름은 현재 QueryDSL member join. native most-commented 조회에는 creator 이름 응답이 없어 comment 본문/title을 치환하지 않음. recommendation candidate snapshot도 현재 card를 다시 조회하므로 이름 저장 변경 불필요. |
이 v2 조사에서 **이미 수신 언어로 렌더된 역사 이름 snapshot으로 면제할 HTTP 이름 필드는 확인되지 않았다**. `snapshot`이라는 클래스명, content title 번역 또는 과거 생성 시점만으로 면제하지 않는다.
## 다른 소유자와의 연결 및 원본 유지 영역
- `M/v2/chat/controller/ChatRoomListController.kt#getRooms` → `M/v2/chat/service/ChatRoomListService.kt#getRooms/toResponse`: DM의 `targetName`은 creator 또는 USER 상대 회원 이름이므로 대상이다. AI `targetName`은 `M/chat/room/repository/ChatRoomRepository.kt#findAiChatListRooms`의 `pc.character.name`이며 **캐릭터 제목이므로 제외**한다. 최근 메시지 본문도 이름 문자열 치환 대상이 아니다.
- 초기 조사에서 DM owner ID는 `M/v2/chat/dto/ChatRoomListDtos.kt#ChatRoomListQueryDto`에서 누락되어 있었다. 후속 승인에 따라 DTO/AI projection은 이 세션이, `M/v2/usercreatorchat/repository/UserCreatorChatRoomRepository.kt#findDmChatListRooms`의 `opponent.member.id` projection은 delivery 소유자가 각각 구현했다. 이 세션은 DM repository를 수정하지 않았다. roomId/character creatorMemberId로 이름을 치환하지 않는다.
- 후속 구현: `ChatRoomListService`가 최종 `pageRows`의 DM member IDs를 batch 처리한다. `HomeFollowingFacade`는 같은 명시 Lang으로 이미 선택된 recentChats를 받아 다시 치환하지 않는다. 실제 계약은 `ChatRoomListQueryDto(roomId, chatType, targetName, targetImagePath, lastMessage, messageType, lastMessageAt, opponentMemberId: Long?)`다. trailing 필드에 default는 없다. AI는 `cast(null as long)`, delivery 소유자가 변경한 DM JPQL은 마지막 `opponent.member.id`를 전달함을 read/rg로 확인했다. 공개 `ChatRoomListItemResponse`는 변경하지 않았다. 해당 소유자의 변경은 이 세션의 수정 파일에 포함하지 않는다.
- 앱이 아닌 운영 식별/편집 응답은 원본 유지: `M/v2/gift/application/GiftAdminQueryService.kt#getGifts/getGiftDetail` 및 `M/v2/api/admin/gift/adapter/in/web/AdminGiftController.kt`, `M/v2/api/admin/aicharacter/content/AiCharacterAdminAudioContentMapper.kt#toResponse`, `M/v2/api/admin/aicharacter/community/AiCharacterAdminCommunityPostFacade.kt#toResponse`, `M/v2/api/admin/aicharacter/fantalk/AiCharacterAdminFanTalkFacade.kt#list/createReply/updateReply`. 앱 DTO를 재사용하더라도 DTO 전역 변환을 적용하지 않는다. admin nickname 검색/원본 편집/배송 실명은 별칭 표시 대상과 분리한다.
- `M/v2/api/home/application/HomeRecommendationFacade.kt#HomeAiCharacterRecommendationRecord.toItem`의 `name`, content/series/live title, event banner, `GiftStatus.displayName`, `GiftSize.displayName`은 creator 이름이 아니며 수정하지 않는다. ADMIN charge/ranking job API는 작업 상태 응답이며 creator display-name 필드가 없다.
## GREEN 생성자·fixture 적응 지도
현재 테스트 생성자와 의존성을 읽고 `rg`로 직접 생성 지점을 대조해 아래 적응을 수행했다. 기존 facade 단위 테스트는 필수 resolver mock과 명시 Lang을 전달한다. controller slice의 `@MockBean LangContext` getter는 `Lang.KO`로 stub했다. 새 기능의 실제 DB/HTTP 검증은 위 통합 테스트가 담당하며 기존 assertion은 완화하지 않았다. `GiftQueryServiceTest`에는 foundation service/repository를 실제 import했다.
| 정확한 기존 test 파일 | 최소 적응 |
|---|---|
| `T/v2/api/home/application/HomeRecommendationFacadeTest.kt`; `T/v2/api/home/HomeRecommendationControllerTest.kt` | 현재 `HomeRecommendationFacade(queryService, preferenceService, "https://cdn.test")`. 새 resolver 및 `lang` 호출 인자 추가. 후자는 장애 로그 test에서도 facade를 3곳 직접 생성하므로 Spring 주입만 보고 끝내지 않음. |
| `T/v2/api/home/live/application/HomeOnAirLiveFacadeTest.kt`; `T/v2/recommendation/application/HomeRecommendationQueryServiceTest.kt` | facade resolver/lang 추가와 `HomeLiveRecommendationRecord` owner fixture 추가. QueryDSL positional constructor와 모든 fake port live record도 동기화. |
| `T/v2/api/home/following/application/HomeFollowingFacadeTest.kt`; `T/v2/api/home/following/dto/HomeFollowingTabResponseTest.kt`; `T/v2/home/following/application/HomeFollowingQueryServiceTest.kt` | facade resolver/lang 및 chat service 명시 Lang stub. `HomeFollowingLive/ContentNews/CommunityPostNews` 내부 owner fixture 추가. 공개 response DTO와 JSON 필드는 추가하지 않음. |
| `T/v2/api/content/all/application/MainContentAllFacadeTest.kt`; `T/v2/content/all/application/MainContentAllQueryServiceTest.kt`; `T/v2/api/content/all/dto/MainContentAllTabResponseTest.kt` | 현재 `MainContentAllFacade(queryService)`에 resolver 추가, facade 호출 lang 추가. `MainContentAllAudio/Series`의 필수 내부 owner fixture를 모두 채움. |
| `T/v2/api/content/recommendation/application/AudioRecommendationFacadeTest.kt`; `T/v2/content/recommendation/application/AudioRecommendationQueryServiceTest.kt`; `T/v2/api/content/overview/application/ContentOverviewFacadeTest.kt`; `T/v2/api/content/overview/dto/ContentOverviewPageResponseTest.kt` | `AudioRecommendationFacade(queryService)` 및 overview의 기존 두 query service/preference/host 의존성은 유지하고 resolver/lang 추가. 모든 `AudioCard` fixture owner 추가. FIRST_AUDIO record는 기존 creatorId 사용. |
| `T/v2/api/content/ranking/application/AudioRankingFacadeTest.kt`; `T/v2/api/content/ranking/dto/AudioRankingResponseTest.kt` | `AudioRankingFacade(queryService)`에 resolver 및 현재 Member batch 조회 의존성/lang 추가. `AudioRankingItem` 내부 owner fixture 추가. contentId를 owner로 쓰지 않는 assertion. |
| `T/v2/api/creator/channel/home/application/CreatorChannelHomeFacadeTest.kt`; `T/v2/creator/channel/home/application/CreatorChannelHomeQueryServiceTest.kt`; `T/v2/api/creator/channel/home/adapter/in/web/CreatorChannelHomeControllerTest.kt` | home facade resolver/lang, donor record/domain owner fixture, query service의 오류 분기 resolver/lang 의존성 및 controller facade stubs 조정. `CreatorChannelHomeQueryServiceTest`의 donation copy 기대값에도 필드 전파. |
| `T/v2/api/creator/channel/community/application/CreatorChannelCommunityFacadeTest.kt`; `T/v2/api/creator/channel/community/adapter/in/web/CreatorChannelCommunityControllerTest.kt`; `T/v2/creator/channel/community/application/CreatorChannelCommunityQueryServiceTest.kt` | 현재 `CreatorChannelCommunityFacade(service)`를 여러 메서드에서 직접 생성. resolver/lang 추가, detail/comment/latestReply 합집합 검증. query service 오류 분기에도 명시 Lang/resolver 전달. |
| `T/v2/api/creator/channel/fantalk/application/CreatorChannelFanTalkFacadeTest.kt`; `T/v2/creator/channel/fantalk/application/CreatorChannelFanTalkQueryServiceTest.kt`; `T/v2/api/creator/channel/donation/application/CreatorChannelDonationFacadeTest.kt`; `T/v2/creator/channel/donation/application/CreatorChannelDonationQueryServiceTest.kt`; `T/v2/creator/channel/donation/domain/CreatorChannelDonationQueryPolicyTest.kt` | facade/query service resolver와 명시 Lang, donor record/domain owner fixture 추가. writer/donor가 USER면 원본, CREATOR면 alias. ranking은 `LegacyCreatorChannelDonationRankingAdapter`가 넘긴 donor `userId` 재사용. |
| `T/v2/api/creator/channel/audio/application/CreatorChannelAudioFacadeTest.kt`; `T/v2/creator/channel/audio/application/CreatorChannelAudioQueryServiceTest.kt`; `T/v2/api/creator/channel/series/application/CreatorChannelSeriesFacadeTest.kt`; `T/v2/creator/channel/series/application/CreatorChannelSeriesQueryServiceTest.kt`; `T/v2/api/creator/channel/live/application/CreatorChannelLiveFacadeTest.kt`; `T/v2/creator/channel/live/application/CreatorChannelLiveQueryServiceTest.kt` | 성공 title DTO는 그대로. blocked-access 이름을 위한 명시 Lang forwarding 및 query service resolver 생성자 추가. 기존 controller MockMvc forwarding stubs의 추가 Lang도 일치시킴. |
| `T/v2/gift/application/GiftQueryServiceTest.kt#queryService`; `T/v2/api/gift/adapter/in/web/GiftControllerTest.kt` | 기존 helper는 여섯 repository + host로 `GiftQueryService`를 직접 생성한다. resolver 추가, `getGifts/getGiftDetail`에 Lang 지정. `@DataJpaTest` helper에는 실제 foundation service/repository를 구성하거나 import하며 조회 서비스를 mock해 버리지 않음. HTTP는 실제 queryService를 사용하고 기존 commandService mock은 유지. |
| `T/v2/chat/ChatRoomListServiceTest.kt`; `T/v2/chat/ChatRoomListControllerTest.kt` | service/controller 직접 생성 인자와 query DTO의 DM owner/AI null fixture, Lang 호출 인자를 조정. AI character name 불변과 DM USER 보존 확인. |
| `T/v2/content/all/adapter/out/persistence/DefaultMainContentAllQueryRepositoryTest.kt`; `T/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepositoryTest.kt`; `T/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepositoryTest.kt`; `T/v2/home/following/adapter/out/persistence/DefaultHomeFollowingQueryRepositoryTest.kt` | 기존 실제 persistence test에서 새 내부 owner ID가 resource ID와 다른 fixture로 올바르게 전달되는지 단언. projection constructor 순서와 current joined ID 전달 검증. |
위 표 외에도 owner 필드를 추가하는 각 data class의 생성 위치는 GREEN 직전에 전체 `M/`, `T/`에서 다시 `rg`한다. repository의 `Projections.constructor`, JPQL `select new`, Kotlin positional fixture는 공개 JSON 변화 없이 모두 맞춰야 한다. optional owner default `0`으로 컴파일만 통과시키지 않는다.
## GREEN 구현 범위와 검증 소유
- 운영 수정 후보는 위 HTTP 표의 controller/facade, owner를 잃는 domain/port/projection adapter, 두 ranking의 현재 이름 batch consumer, 기프트 query result 조립, 채널 오류 분기 query service로 제한한다. response DTO `from`은 기존 공개 필드를 그대로 복사하므로 원칙적으로 수정할 필요 없다.
- 읽기 근거로만 등장한 snapshot entity/producer/native aggregation, following inbox producer, admin 원본 편집기는 수정 후보가 아니다. 두 타 소유 영역은 조정 전 수정 금지다. `v2.chat` DM projection은 소유자 인계 항목이다.
- 첫 4개 테스트는 대표 RED이지 전체 surface 완료 증거가 아니다. GREEN에서는 HTTP 표의 각 owner class에 JA/KO/EN/미등록/비활성/혼합 USER 및 필요한 owner-ID 회귀를 추가하고 해당 exact class만 우선 실행한다. fixture/생성자 적응은 기존 단위/adapter 회귀로 확인한다.
- 검증 실행 예시는 `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.gift.adapter.in.web.GiftControllerTest'`, `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.home.following.adapter.in.web.HomeFollowingEndToEndTest'`다. 다른 행도 `T/` 아래 package와 class를 그대로 FQCN으로 사용한다. 단계 마지막에 부모가 `./gradlew ktlintCheck`, `./gradlew assemble`을 직렬 실행한다.
- 이 단계는 부모 RED 증거와 소스·fixture·필드·시그니처의 read/rg 대조만 수행했다. Gradle/서버 실행/DB 연결/commit/push는 하지 않았다. 사용 가능한 도구에 `lsp_diagnostics`가 없어 IDE 진단도 수행하지 못했다. 부모의 실제 GREEN 결과를 기다린다.
### 추가 확인한 중립 후원 랭킹 캐시
`M/explorer/profile/CreatorDonationRankingService.kt#getMemberDonationRanking`의 Redis key는 Lang을 포함하지 않고 raw nickname이 담긴 `MemberDonationRankingListResponse`를 캐시한다. 이 파일과 캐시 저장은 수정하지 않았다. `CreatorChannelDonationFacade`는 legacy adapter가 넘긴 donor `userId`를 batch Member 조회해 현재 원본으로 fallback하고 같은 aggregate의 JA map을 우선한다. 목록 donor와 ranking donor의 alias lookup은 합집합 한 번이다. 따라서 중립 donor cache도 역사 면제로 남기지 않았다.
### 정적 점검 결과와 남은 검증
- content/live/ranking/following/donor 내부 owner 생성 위치를 `src/main`, `src/test` 전체에서 `rg`해 모든 직접 생성 fixture를 적응했다. JPQL `select new`의 AI/DM trailing ID와 QueryDSL constructor의 donor ID 첫 인자/live owner 마지막 인자를 대조했다.
- `findLocalizedNames`는 정상 목록/aggregate별 한 번이며 blocked-access 경로는 오류 분기에서만 한 명을 batch API로 조회한다. snapshot current fallback은 batch Member 조회이고 `0L` 마스킹은 ID 집합에서 제외한다. `LangContext`는 새 이름 기능에서 controller 경계만 읽는다.
- public response DTO, snapshot entity/producer, inbox producer, core/legacy, `FcmEvent`는 수정하지 않았다. AI character name/content title/본문 및 배송 실명·주소는 치환하지 않는다.
- 부모의 `creatorname-foundation-final-lint.log`를 읽었으며 첫 단계 v2 테스트 4개에 해당하는 lint 지적은 없었다. 다른 소유자 테스트의 lint는 변경하지 않았다. 변경 파일의 길이/공백을 `rg`로 점검했으며 전체 lint 실행을 대신한 것으로 주장하지 않는다.
- 길이 검색에서 `DefaultHomeRecommendationQueryRepository.kt`의 기존 raw SQL 두 줄은 130자를 넘는다. 이번 변경은 live owner projection 한 필드이며 그 SQL 본문은 변경하지 않았다. 이 검색 결과를 새 Kotlin lint 실패로 단정하거나 무관한 SQL 포맷 변경으로 확장하지 않는다.
- 내부 연결의 알려진 누락은 없다. 남은 불확실성은 실제 compile/test/lint, H2/Hibernate의 typed-null JPQL 실행 및 전체 HTTP 응답 회귀다. 특히 `v2.chat`의 AI/DM 생성자 계약은 부모 통합 GREEN에서 검증해야 한다.
### 부모 직렬 GREEN 명령
먼저 위 네 메서드의 동일 명령으로 GREEN을 확인한 뒤 다음 정확한 기존 class 회귀를 실행한다. 명령은 이 세션에서 실행하지 않았다.
```bash
./gradlew compileTestKotlin
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.home.HomeRecommendationControllerTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.home.CreatorRankingControllerTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.home.live.adapter.in.web.HomeOnAirLiveEndToEndTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.home.following.adapter.in.web.HomeFollowingEndToEndTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.content.all.adapter.in.web.MainContentAllEndToEndTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.content.overview.adapter.in.web.ContentOverviewEndToEndTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.content.recommendation.adapter.in.web.AudioRecommendationEndToEndTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.content.ranking.adapter.in.web.AudioRankingControllerTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.home.CreatorChannelHomeEndToEndTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.community.adapter.in.web.CreatorChannelCommunityEndToEndTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.fantalk.adapter.in.web.CreatorChannelFanTalkEndToEndTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.donation.adapter.in.web.CreatorChannelDonationEndToEndTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.audio.adapter.in.web.CreatorChannelAudioEndToEndTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.series.adapter.in.web.CreatorChannelSeriesEndToEndTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.live.adapter.in.web.CreatorChannelLiveEndToEndTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.gift.adapter.in.web.GiftControllerTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.gift.application.GiftQueryServiceTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.chat.ChatRoomListServiceTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.chat.ChatRoomListControllerTest'
./gradlew ktlintCheck
./gradlew assemble
```
### 이번 GREEN 단계 실제 운영 수정 파일
아래는 `M/` 기준이다. 기존 표의 나머지 producer/DTO/admin 파일은 읽기 근거이지 수정 파일이 아니다.
```text
v2/api/content/all/adapter/in/web/MainContentAllController.kt
v2/api/content/all/application/MainContentAllFacade.kt
v2/api/content/overview/adapter/in/web/ContentOverviewController.kt
v2/api/content/overview/application/ContentOverviewFacade.kt
v2/api/content/recommendation/adapter/in/web/AudioRecommendationController.kt
v2/api/content/recommendation/application/AudioRecommendationFacade.kt
v2/api/content/ranking/adapter/in/web/AudioRankingController.kt
v2/api/content/ranking/application/AudioRankingFacade.kt
v2/content/all/domain/MainContentAll.kt
v2/content/all/adapter/out/persistence/DefaultMainContentAllQueryRepository.kt
v2/content/recommendation/domain/AudioRecommendation.kt
v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepository.kt
v2/content/ranking/domain/AudioRanking.kt
v2/content/ranking/application/AudioRankingQueryService.kt
v2/api/home/adapter/in/web/HomeRecommendationController.kt
v2/api/home/application/HomeRecommendationFacade.kt
v2/api/home/adapter/in/web/CreatorRankingController.kt
v2/api/home/application/HomeCreatorRankingFacade.kt
v2/api/home/live/adapter/in/web/HomeOnAirLiveController.kt
v2/api/home/live/application/HomeOnAirLiveFacade.kt
v2/api/home/following/adapter/in/web/HomeFollowingController.kt
v2/api/home/following/application/HomeFollowingFacade.kt
v2/recommendation/port/out/HomeRecommendationQueryPort.kt
v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt
v2/home/following/domain/HomeFollowing.kt
v2/home/following/adapter/out/persistence/DefaultHomeFollowingQueryRepository.kt
v2/api/creator/channel/home/adapter/in/web/CreatorChannelHomeController.kt
v2/api/creator/channel/home/application/CreatorChannelHomeFacade.kt
v2/creator/channel/home/domain/CreatorChannelHome.kt
v2/creator/channel/home/port/out/CreatorChannelHomeQueryPort.kt
v2/creator/channel/home/adapter/out/persistence/DefaultCreatorChannelHomeQueryRepository.kt
v2/creator/channel/home/application/CreatorChannelHomeQueryService.kt
v2/api/creator/channel/community/adapter/in/web/CreatorChannelCommunityController.kt
v2/api/creator/channel/community/application/CreatorChannelCommunityFacade.kt
v2/creator/channel/community/application/CreatorChannelCommunityQueryService.kt
v2/api/creator/channel/fantalk/adapter/in/web/CreatorChannelFanTalkController.kt
v2/api/creator/channel/fantalk/application/CreatorChannelFanTalkFacade.kt
v2/creator/channel/fantalk/application/CreatorChannelFanTalkQueryService.kt
v2/api/creator/channel/donation/adapter/in/web/CreatorChannelDonationController.kt
v2/api/creator/channel/donation/application/CreatorChannelDonationFacade.kt
v2/creator/channel/donation/domain/CreatorChannelDonationTab.kt
v2/creator/channel/donation/port/out/CreatorChannelDonationQueryPort.kt
v2/creator/channel/donation/adapter/out/persistence/DefaultCreatorChannelDonationQueryRepository.kt
v2/creator/channel/donation/application/CreatorChannelDonationQueryService.kt
v2/api/creator/channel/audio/adapter/in/web/CreatorChannelAudioController.kt
v2/api/creator/channel/audio/application/CreatorChannelAudioFacade.kt
v2/creator/channel/audio/application/CreatorChannelAudioQueryService.kt
v2/api/creator/channel/series/adapter/in/web/CreatorChannelSeriesController.kt
v2/api/creator/channel/series/application/CreatorChannelSeriesFacade.kt
v2/creator/channel/series/application/CreatorChannelSeriesQueryService.kt
v2/api/creator/channel/live/adapter/in/web/CreatorChannelLiveController.kt
v2/api/creator/channel/live/application/CreatorChannelLiveFacade.kt
v2/creator/channel/live/application/CreatorChannelLiveQueryService.kt
v2/api/gift/adapter/in/web/GiftController.kt
v2/gift/application/GiftQueryService.kt
v2/chat/dto/ChatRoomListDtos.kt
v2/chat/service/ChatRoomListService.kt
v2/chat/controller/ChatRoomListController.kt
chat/room/repository/ChatRoomRepository.kt
```
### 이번 GREEN 단계 실제 테스트 적응 파일
아래는 `T/` 기준이다. 첫 단계 네 assertion의 기대값은 유지했다. 이 단계에서는 그중 `HomeRecommendationControllerTest`의 기존 직접 facade 생성/호출도 적응했으며 다른 세 RED 파일은 변경할 필요가 없었다.
```text
v2/api/content/all/application/MainContentAllFacadeTest.kt
v2/api/content/all/adapter/in/web/MainContentAllControllerTest.kt
v2/api/content/all/dto/MainContentAllTabResponseTest.kt
v2/content/all/application/MainContentAllQueryServiceTest.kt
v2/api/content/overview/application/ContentOverviewFacadeTest.kt
v2/api/content/overview/adapter/in/web/ContentOverviewControllerTest.kt
v2/api/content/overview/dto/ContentOverviewPageResponseTest.kt
v2/api/content/recommendation/application/AudioRecommendationFacadeTest.kt
v2/api/content/recommendation/adapter/in/web/AudioRecommendationControllerTest.kt
v2/content/recommendation/application/AudioRecommendationQueryServiceTest.kt
v2/api/content/ranking/application/AudioRankingFacadeTest.kt
v2/api/content/ranking/dto/AudioRankingResponseTest.kt
v2/api/home/application/HomeRecommendationFacadeTest.kt
v2/api/home/HomeRecommendationControllerTest.kt
v2/api/home/live/application/HomeOnAirLiveFacadeTest.kt
v2/api/home/live/adapter/in/web/HomeOnAirLiveControllerTest.kt
v2/api/home/following/application/HomeFollowingFacadeTest.kt
v2/api/home/following/adapter/in/web/HomeFollowingControllerTest.kt
v2/api/home/following/dto/HomeFollowingTabResponseTest.kt
v2/home/following/application/HomeFollowingQueryServiceTest.kt
v2/recommendation/application/HomeRecommendationQueryServiceTest.kt
v2/api/creator/channel/home/application/CreatorChannelHomeFacadeTest.kt
v2/api/creator/channel/home/adapter/in/web/CreatorChannelHomeControllerTest.kt
v2/creator/channel/home/application/CreatorChannelHomeQueryServiceTest.kt
v2/api/creator/channel/community/application/CreatorChannelCommunityFacadeTest.kt
v2/api/creator/channel/community/adapter/in/web/CreatorChannelCommunityControllerTest.kt
v2/creator/channel/community/application/CreatorChannelCommunityQueryServiceTest.kt
v2/api/creator/channel/fantalk/application/CreatorChannelFanTalkFacadeTest.kt
v2/api/creator/channel/fantalk/adapter/in/web/CreatorChannelFanTalkControllerTest.kt
v2/creator/channel/fantalk/application/CreatorChannelFanTalkQueryServiceTest.kt
v2/api/creator/channel/donation/application/CreatorChannelDonationFacadeTest.kt
v2/api/creator/channel/donation/adapter/in/web/CreatorChannelDonationControllerTest.kt
v2/creator/channel/donation/application/CreatorChannelDonationQueryServiceTest.kt
v2/creator/channel/donation/domain/CreatorChannelDonationQueryPolicyTest.kt
v2/api/creator/channel/audio/application/CreatorChannelAudioFacadeTest.kt
v2/api/creator/channel/audio/adapter/in/web/CreatorChannelAudioControllerTest.kt
v2/creator/channel/audio/application/CreatorChannelAudioQueryServiceTest.kt
v2/api/creator/channel/series/application/CreatorChannelSeriesFacadeTest.kt
v2/api/creator/channel/series/adapter/in/web/CreatorChannelSeriesControllerTest.kt
v2/creator/channel/series/application/CreatorChannelSeriesQueryServiceTest.kt
v2/api/creator/channel/live/application/CreatorChannelLiveFacadeTest.kt
v2/api/creator/channel/live/adapter/in/web/CreatorChannelLiveControllerTest.kt
v2/creator/channel/live/application/CreatorChannelLiveQueryServiceTest.kt
v2/gift/application/GiftQueryServiceTest.kt
v2/chat/ChatRoomListServiceTest.kt
v2/chat/ChatRoomListControllerTest.kt
```
## COR013 JOIN 전환 manifest, 2026-10-15
### 범위와 인계 상태
- 승인 근거는 `prd.md` 10절과 `plan-task.md` JOIN-T1~T3다. 이 단계는 `v2.creatorname`, `v2.usercreatorchat`, `v2.chat` 및 core/legacy를 수정하지 않았다. `v2.chat` 전체는 delivery 소유자에게 넘어갔으며 아래 팔로잉 recentChats의 기존 명시 Lang 계약만 소비한다.
- 부모 RED 로그는 `/var/folders/yh/8xsbvpsj5wg2qnxzxdp11_gm0000gn/T/opencode/creatorname-join-consumer-red.log`다. `MainContentAllEndToEndTest.shouldSelectLocalizedCreatorNamesWithoutChangingAudioTitles`는 이름 출력 assertion 뒤 standalone alias SELECT 기대 0/실제 1에서 실패했다. 기존 2249 전체 PASS와 JOIN 기반 43 PASS는 변경 전/공통 모듈 기준선이며 이번 v2 결과로 재사용하지 않는다.
- 모든 소유 current DB 이름 projection은 기존 owner에 `CreatorNameJoin(owner, lang, uniqueAlias)`의 `name/condition/displayName`을 명시 LEFT JOIN/ON/select한다. 조건은 공통 helper의 owner ID + 요청 Lang + active + CREATOR ON이다. JA-only 읽기 guard를 만들지 않았으며 관리자 /ja 쓰기와 JA 검색은 그대로다.
- 아래 DB 읽기에서 facade 별칭 service 의존성, 후속 이름 SELECT와 이름 전용 copy/map을 제거했다. 제목 번역, 페이지 구성, CDN 변환 및 차단 마스킹 등 이름과 다른 기존 변환은 유지한다. DTO는 `val` 기반이며 회원·snapshot·inbox entity를 변이하지 않는다.
### DB 읽기 전환 지점
각 행의 경로는 앞서 정의한 `M/` prefix를 적용한다. query adapter 외에 같은 행의 service/port/facade도 함께 수정했다.
| 경로/심볼 | 현재 구현과 호출 계약 |
|---|---|
| `v2/content/all/adapter/out/persistence/DefaultMainContentAllQueryRepository.kt#findAudios/findAudioRows/findSeries` | 기존 `locale`을 `Lang.fromCode(locale)`로 재사용한다. audio/series의 실제 owner 이름을 JOIN으로 읽고 인기순 audio GROUP BY에는 raw nickname과 별칭 displayName을 함께 명시했다. `countAudios/countSeries/findSeriesIds`에는 이름 조인을 넣지 않았다. `v2/content/all/application/MainContentAllQueryService.kt#getContents(..., lang: Lang)`와 `v2/api/content/all/application/MainContentAllFacade.kt`가 언어를 전달한다. `v2/content/all/port/out/MainContentAllQueryPort.kt`의 기존 locale 계약은 유지한다. |
| `v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepository.kt#audioRows/toAudioCards` | 최신/무료/포인트/ID 기반 New&Hot·추천 card 모두 같은 JOIN을 사용한다. 기존 locale을 재사용하며 most-commented native query는 이름 출력이 없어 변경하지 않았다. `v2/content/recommendation/application/AudioRecommendationQueryService.kt#getRecommendations(member, lang)/findNewAndHotAudios(member, offset, limit, lang)`와 `v2/api/content/recommendation/application/AudioRecommendationFacade.kt`, `v2/api/content/overview/application/ContentOverviewFacade.kt`에서 전달한다. |
| `v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt#findLiveRecommendations/findCheerCreatorRecommendationDetails/findPopularCommunityRecommendationDetails` | live creator, 응원 creator, community owner 각각 고유 alias의 QueryDSL JOIN이다. community 집계 GROUP BY에 별칭 displayName을 추가하고 기존 countDistinct·필터·순서를 유지한다. `v2/recommendation/port/out/HomeRecommendationQueryPort.kt`와 `v2/recommendation/application/HomeRecommendationQueryService.kt`에 필수 Lang을 전달한다. |
| `v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt#findRecentlyActiveCreators/findRecentDebutCreators/findFirstAudioContents/findCreatorsByGenre` | native 현재 SELECT 네 곳에 LEFT JOIN + COALESCE를 넣었다. 최근 활동/장르는 후보 ranking/grouping 뒤 outer display owner에 조인하고 debut/first-audio는 현재 member에 조인한다. native `:lang`은 `lang.name` 또는 `Lang.fromCode(locale).name`으로 bind한다. CTE/window/rank/order/limit, 후보 ID/count query와 snapshot 생성 SQL은 보존한다. `findGenreCreatorRecommendations`의 private helper까지 Lang을 전달하며 first-audio port는 기존 locale을 사용한다. |
| `v2/api/home/application/HomeRecommendationFacade.kt`; `v2/api/home/live/application/HomeOnAirLiveFacade.kt` | 요청 Lang을 위 query service에 명시 전달하고 JOIN된 record를 그대로 응답 조립에 사용한다. country 기반 `bannerLang`은 배너 전용이며 creator 이름 언어로 쓰지 않는다. |
| `v2/home/following/adapter/out/persistence/DefaultHomeFollowingQueryRepository.kt#findFollowingCreators/findOnAirLives/findMonthlySchedules/findRecentNews` | 팔로잉 creator/on-air/live schedule/audio schedule/news의 현재 owner 이름을 JOIN으로 읽는다. `v2/home/following/port/out/HomeFollowingQueryPort.kt`의 네 메서드와 `v2/home/following/application/HomeFollowingQueryService.kt#findHomeFollowing(member, lang)`에 필수 Lang을 추가했다. news는 중립 inbox의 이름이 아니라 이미 조인한 현재 creator 이름을 선택한다. |
| `v2/api/home/following/application/HomeFollowingFacade.kt#getFollowingTab` | 위 JOIN 결과를 사용하며 `ChatRoomListService.getRooms(member, lang=lang, followedCreatorsOnly=true, ...)` 계약은 그대로다. recentChats를 다시 이름 치환하지 않는다. |
| `v2/creator/channel/home/adapter/out/persistence/DefaultCreatorChannelHomeQueryRepository.kt#findCreator/findChannelDonations/findFanTalkSummary` | creator/donor/latest-fanTalk writer에 각각 JOIN한다. `v2/creator/channel/home/port/out/CreatorChannelHomeQueryPort.kt`의 세 읽기 메서드에 필수 Lang을 추가했고 `v2/creator/channel/home/application/CreatorChannelHomeQueryService.kt`에서 전달한다. notices/communities도 아래 community service에 같은 Lang을 전달한다. `v2/api/creator/channel/home/application/CreatorChannelHomeFacade.kt`의 batch와 copy들을 제거했다. |
| `v2/creator/channel/community/adapter/out/persistence/DefaultCreatorChannelCommunityQueryRepository.kt#findCreator/findCommunityPosts/findHomeCommunityPosts/findCommunityPost/findCommunityComments/findLatestRepliesByCommentIds/findCommunityReplies` | post creator와 각 comment/reply writer를 JOIN한다. tuple alias는 `postCreatorDisplayName/commentWriterDisplayName`으로 지정하고 raw 회원 nickname field를 alias로 쓰지 않는다. `v2/creator/channel/community/port/out/CreatorChannelCommunityQueryPort.kt`의 해당 메서드와 `v2/creator/channel/community/application/CreatorChannelCommunityQueryService.kt#findHomeCommunityPosts/getCommunityPostDetail/getCommunityComments/getCommunityReplies`에 필수 Lang을 추가했다. `v2/api/creator/channel/community/application/CreatorChannelCommunityFacade.kt`는 JOIN 결과를 바로 매핑한다. |
| `v2/creator/channel/fantalk/adapter/out/persistence/DefaultCreatorChannelFanTalkQueryRepository.kt#findCreator/findFanTalks/findCreatorReplies` | creator와 root/reply writer 이름을 JOIN한다. `v2/creator/channel/fantalk/port/out/CreatorChannelFanTalkQueryPort.kt` 세 메서드에 필수 Lang, `v2/creator/channel/fantalk/application/CreatorChannelFanTalkQueryService.kt`의 private reply helper까지 전달한다. `v2/api/creator/channel/fantalk/application/CreatorChannelFanTalkFacade.kt`의 alias dependency/copy를 제거했다. |
| `v2/creator/channel/donation/adapter/out/persistence/DefaultCreatorChannelDonationQueryRepository.kt#findCreator/findChannelDonations` | creator/donor의 직접 DB 읽기를 JOIN으로 바꿨다. `v2/creator/channel/donation/port/out/CreatorChannelDonationQueryPort.kt` 두 메서드에 필수 Lang, `v2/creator/channel/donation/application/CreatorChannelDonationQueryService.kt`가 전달한다. `v2/api/creator/channel/donation/application/CreatorChannelDonationFacade.kt`는 DB donation 목록에 후속 치환하지 않고 중립 cache ranking만 current batch한다. |
| `v2/creator/channel/audio/adapter/out/persistence/DefaultCreatorChannelAudioQueryRepository.kt#findCreator`; `v2/creator/channel/series/adapter/out/persistence/DefaultCreatorChannelSeriesQueryRepository.kt#findCreator`; `v2/creator/channel/live/adapter/out/persistence/DefaultCreatorChannelLiveQueryRepository.kt#findCreator` | 각 `v2/creator/channel/{audio,series,live}/port/out/CreatorChannel{Audio,Series,Live}QueryPort.kt#findCreator`는 필수 Lang을 받는다. 각 `v2/creator/channel/{audio,series,live}/application/CreatorChannel{Audio,Series,Live}QueryService.kt`의 blocked-access 이름은 이 record.nickname을 그대로 사용한다. 후속 resolver 주입/오류 분기 alias SELECT를 제거했다. 정상 DTO의 제목/콘텐츠 필드는 그대로다. |
| `v2/ranking/adapter/out/persistence/DefaultCreatorRankingSnapshotRepository.kt#findLatestVisibleSnapshots` | DB의 중립 snapshot을 조회하면서 현재 Member/별칭을 LEFT JOIN한다. `COALESCE(alias, current nickname, snapshot nickname)`로 삭제된 owner의 기존 fallback도 유지하며 snapshot entity를 수정하지 않는다. 기존 최신 visible 조건/rankNo 순서를 QueryDSL로 동일하게 적용했다. `v2/ranking/port/out/CreatorRankingSnapshotPort.kt#findLatestVisibleSnapshots(type, nowUtc, lang)`와 `v2/ranking/application/CreatorRankingQueryService.kt#getCreatorRankings(viewerMemberId, lang)`는 필수 Lang이다. `v2/api/home/application/HomeCreatorRankingFacade.kt`의 Member scalar batch와 alias batch/copy를 모두 제거했다. |
| `v2/content/ranking/adapter/out/persistence/DefaultAudioRankingSnapshotPersistenceAdapter.kt#findLatestVisibleSnapshots` | 위와 같이 현재 owner/name을 snapshot 읽기에서 JOIN하며 기존 locale을 재사용한다. 제목 번역은 별개로 유지한다. `v2/content/ranking/application/AudioRankingQueryService.kt#getRankings(type, member, lang)` → 기존 snapshot port locale을 전달한다. `v2/api/content/ranking/application/AudioRankingFacade.kt`의 Member scalar batch와 alias batch/copy를 제거했다. |
`v2/creator/channel/{audio,series,live}` 행의 중괄호는 세 기존 파일의 일대일 대응이며 신규 추정 경로가 아니다. 관리 AI community/fanTalk은 별도 raw repository를 사용함을 확인했으므로 앱 query에 admin용 KO 기본값/null-language fallback을 추가하지 않았다. 원래 언어 중립 snapshot writer가 쓰는 집계기간/raw 조회 계약도 바꾸지 않았다.
`MainContentAllQueryService`, `AudioRecommendationQueryService`, `AudioRankingQueryService`, `HomeRecommendationQueryService`, `HomeFollowingQueryService`는 요청 Lang을 명시 전달받으며 더 이상 필요 없는 `LangContext` 생성자 의존성을 제거했다. 기존 locale port를 그대로 쓰는 경우 코드 ↔ enum 매핑에는 `Lang.fromCode`만 사용한다. 나머지 채널 서비스의 기존 본문/제목 번역 context는 이번 이름 조회와 무관한 동작으로 유지한다.
혼합 writer/donor record에는 조회 결과의 `isLocalizedName`을 보존해 원본 `deleted_` prefix 정리만 유지하고 별칭 원문은 정리하지 않는다. 이 flag는 내부 `CreatorChannelCommunityCommentRecord`, `CreatorChannelFanTalkRecord/ReplyRecord`, 두 `CreatorChannelDonationRecord`, 홈 `CreatorChannelFanTalkRecord`에만 있으며 공개 DTO에는 추가하지 않는다. raw fixture의 기본 false와 QueryDSL의 실제 alias-row 존재 projection을 구분한다.
### 남은 batch와 미전환 읽기의 분류
| 정확한 경계 | 유지 이유와 현재 처리 |
|---|---|
| `M/v2/api/creator/channel/donation/application/CreatorChannelDonationFacade.kt#findCurrentNames` | `M/v2/creator/channel/donation/adapter/out/legacy/LegacyCreatorChannelDonationRankingAdapter.kt` → `M/explorer/profile/CreatorDonationRankingService.kt#getMemberDonationRanking`은 Lang 없는 Redis `creator_donation_ranking_v2:...`에 raw nickname을 저장한다. cache hit는 `cachedData.rankings`를 그대로 반환하므로 DB JOIN으로 치환할 수 없는 중립 재사용 경계다. rankings donor ID만 `findCurrentNames` 한 번으로 현재 별칭/원본을 함께 조회한다. 별도 `Member.findNicknamesByIds`는 제거했다. cache entry/producer는 변이하지 않는다. |
| `M/v2/gift/application/GiftQueryService.kt#getGifts/getGiftDetail` | 기프트·배송 업무 엔티티와 sender/recipient 회원을 이미 읽어 방향/상태/존재 검증, profile, 주소 공개 범위를 조립하는 기존 경계다. 이름만을 위해 기프트 query/permission DTO를 재설계하지 않았다. 각 use case에서 `findLocalizedNames` 한 번의 sparse batch와 이미 로드한 nickname fallback을 유지하며 추가 Member 이름 query는 없다. 실명/주소/category snapshot/status/size는 치환하지 않는다. |
| 두 ranking adapter의 previous/raw 조회와 snapshot refresh/aggregation | 이전 데이터는 rank 변화 계산 또는 중립 writer 입력이며 그 이름을 직접 HTTP 이름으로 노출하지 않는다. latest 표시 read만 현재 이름 JOIN으로 바꿨다. 실제 `v2/ranking`, `v2/content/ranking` 읽기에는 Redis/Cacheable 및 `.getFirst()` 기반 공유 raw ranking cache가 없고 DB snapshot을 직접 소비함을 read/rg로 확인했다. test fake의 ArrayDeque `firstOrNull`은 cache producer가 아니다. |
| `M/v2/home/following/adapter/out/persistence/HomeFollowingNewsInbox.kt`와 publish service | 언어 중립 저장값은 그대로다. 이미 현재 creator를 조인하는 HTTP consumer는 위에서 JOIN 전환했으므로 역사 snapshot 면제가 아니다. |
| admin/원본 역할 확인, AI 캐릭터 제목, content/series/live title | 운영 식별/원본 편집과 이름 아닌 필드는 기존 raw 정책을 유지한다. 언어별로 렌더되어 저장된 historical 이름으로 면제한 소유 v2 HTTP 필드는 없다. |
| `v2.creatorname`, `v2.usercreatorchat`, `v2.chat`, core/legacy/delivery | 다른 소유자 범위다. 공통 helper/batch 계약만 소비했으며 공유 파일을 수정하지 않았다. chat recentChats의 기존 Lang 호출은 보존했다. |
소유 범위 `findLocalizedNames/findCurrentNames/findNicknamesByIds` 재검색 결과는 위 기프트 두 호출과 donation cache의 current batch 한 호출뿐이다. 단순 current DB projection으로 남긴 alias batch는 없으며 entity/snapshot/inbox 원본도 변경하지 않았다.
### 테스트/생성자 적응과 정적 증거
- 기존 facade tests의 resolver mock/MemberRepository 생성자 인자를 제거했고 query service tests의 `LangContext` 인자는 필요한 곳만 제거했다. HomeRecommendation의 모든 직접 facade 생성(장애 로그 tests 포함), 채널 seven fake ports, home/following fake ports, 두 ranking fake ports 및 snapshot adapter 직접 생성자를 현재 계약으로 맞췄다. `DefaultAudioRankingSnapshotPersistenceAdapterTest`는 기존 EntityManager로 `JPAQueryFactory`를 전달한다. nullable dependency로 테스트를 우회하지 않는다.
- `T/v2/api/content/all/adapter/in/web/MainContentAllEndToEndTest.kt#shouldSelectLocalizedCreatorNamesWithoutChangingAudioTitles`의 실제 standalone alias SQL counter 기대값 0을 그대로 유지했다. 같은 파일의 `#shouldReadActiveEnglishCreatorNameAndFallbackWhenInactive`는 활성 EN 읽기, 비활성 EN 원본 fallback, POPULAR 집계/page 개수와 제목 불변을 검증하도록 추가했다.
- `T/v2/api/creator/channel/community/adapter/in/web/CreatorChannelCommunityEndToEndTest.kt#shouldLocalizeCreatorAuthorsAndLatestRepliesWithoutChangingUserNames`의 JA/USER/본문 assertion을 유지하고 `deleted_`로 시작하는 별칭도 post/root comment/latest reply에서 원문 그대로인지 추가했다. 기존 삭제 원본 이름 정리 tests의 기대값은 완화하지 않았다.
- 추가로 적응한 ranking tests는 `T/v2/ranking/application/CreatorRankingQueryServiceTest.kt`, `T/v2/ranking/application/CreatorRankingSnapshotRefreshServiceTest.kt`, `T/v2/ranking/adapter/out/persistence/DefaultCreatorRankingSnapshotRepositoryTest.kt`, `T/v2/content/ranking/application/AudioRankingQueryServiceTest.kt`, `T/v2/content/ranking/adapter/out/persistence/DefaultAudioRankingSnapshotPersistenceAdapterTest.kt`다. reflection 기반 service method 검사에도 Lang type을 추가했다. 일본어/영어 번역 기대 tests는 기존 언어를 명시 인자로 옮겼다.
- `read/rg` 및 임시 정적 점검으로 34개 관련 계약의 언어/locale 참조 468곳을 대조했고 알려진 누락은 0이었다. `src/main`, `src/test`의 직접 생성자/override, v2 외부 import/caller, 기존 생성 QMember/QSnapshot field와 native `:lang` 네 곳의 enum NAME binding을 대조했다. 이는 컴파일/실제 SQL 실행을 대신하는 성공 주장이 아니다.
- 이 writer는 요청대로 Gradle/서버/DB/agent/commit/push를 실행하지 않았다. `lsp_diagnostics` 도구도 제공되지 않아 미실행이다. 남은 runtime 확인은 H2/MySQL 대응 JOIN/COALESCE와 boolean/enum binding, 전체 consumer 회귀 및 parent GREEN이다.
### 부모 직렬 GREEN 명령, 이 단계 미실행
먼저 새 SQL counter RED의 같은 메서드와 EN/grouping 회귀를 실행하고, 아래 module/HTTP consumer 회귀 및 빌드/린트를 한 번에 하나씩 실행한다.
```bash
./gradlew compileTestKotlin --offline --console=plain
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.content.all.adapter.in.web.MainContentAllEndToEndTest' --offline --console=plain
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.community.adapter.in.web.CreatorChannelCommunityEndToEndTest' --offline --console=plain
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.content.*' --tests 'kr.co.vividnext.sodalive.v2.api.content.*' --offline --console=plain
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.recommendation.*' --tests 'kr.co.vividnext.sodalive.v2.home.following.*' --tests 'kr.co.vividnext.sodalive.v2.ranking.*' --tests 'kr.co.vividnext.sodalive.v2.api.home.*' --offline --console=plain
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.*' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.*' --tests 'kr.co.vividnext.sodalive.v2.gift.application.GiftQueryServiceTest' --tests 'kr.co.vividnext.sodalive.v2.api.gift.adapter.in.web.GiftControllerTest' --offline --console=plain
./gradlew ktlintCheck assemble --offline --console=plain
```
정적 인계 상태는 **parent GREEN 준비**이며 위 명령의 PASS/실제 HTTP QA 완료를 기록하지 않는다. 공통 및 다른 writer 변경이 합쳐진 전체 회귀와 실제 자원 종료 검증은 부모 JOIN-GATE 소유다.
@@ -1,164 +0,0 @@
# Skill orchestration 근거 감사
## 범위와 판정
읽기 전용 조사 기준일은 2026-10-19다. 설치, 설정 등록, host discovery, skill 선택 metadata, 실제 모델 invocation은 서로 다른 사실이다. 조사에서 확인한 설치 상태만 기록하며 자동 invocation 성공을 테스트했다고 주장하지 않는다.
## 저장소 및 지침 baseline
| 항목 | 관찰 증거 |
|---|---|
| cwd / git root | `/Users/klaus/Develop/sodalive/Server/sodalive_` (동일) |
| baseline HEAD | `bf252795ed9efb9362d273c58dc7f573ba9351a4` |
| 루트 `AGENTS.md` SHA-256 | `eb99f0fa50609aa6cad7c03a546bfffc6da981348b7ee5cf59b48628e6c40331` |
| 루트 `AGENTS.md` 크기 | 5,608 bytes, 122 lines |
| baseline worktree | clean, branch `test`가 `origin/test`보다 3 commit 앞서 있음 |
| 계층 조사 | `/`, `/Users`, `/Users/klaus`, `/Users/klaus/Develop`, `/Users/klaus/Develop/sodalive`, `/Users/klaus/Develop/sodalive/Server`에 추가 AGENTS/override/CLAUDE 지침 없음. 저장소에는 루트 AGENTS만 있고 child/override/CLAUDE, `opencode.json/jsonc`, `.opencode` 설정이 없었음. |
| 전역 지침 조사 | `~/.codex/AGENTS.md`, `~/.codex/AGENTS.override.md`, `~/.config/opencode/AGENTS.md`, `~/.claude/CLAUDE.md` 없음. 조사된 범위 한정. |
루트 `AGENTS.md`의 CORE/충돌 규칙은 lines 8-78, 한국어 보고는 80-83, 프로젝트 가이드와 공개 API 경계는 92-102, PRD/plan 선행 규칙은 104-107, issue/domain docs 안내는 114-122다. 요청 문서인 `docs/agent-guides/작업절차.md`, `문서유지보수.md`, `docs/sample/sample-prd.md`, `sample-plan-task.md`도 읽었다. 기존 문서 절차는 구현 전 PRD와 plan, goal/phase gate, TDD 또는 문서 작업의 대체 검증, focused test 우선과 실행 결과 기록을 이미 규정한다. 새 정책은 이를 대체하지 않는다.
기존 routing baseline은 작업 유형별 stage 선택, 중복 책임, implicit invocation 제약을 루트에서 연결하지 않는 문서 공백이다. 이는 runtime 실패 판정이 아니다. 가이드의 Markdown 참조가 자동으로 instruction에 import된다고 간주하지 않는다. 루트 `AGENTS.md`의 경로 안내 오기 `.../sodalive` 대 실제 `.../sodalive_`는 관찰 사실이며 이번 요청의 변경 범위가 아니므로 수정하지 않는다.
## Host/설정 계층과 범위
설치 조사에서 확인한 host는 Codex `0.163.0`, OpenCode `1.19.3`이다. `CODEX_HOME`, `XDG_CONFIG_HOME`은 조사 환경에서 설정되지 않았다. 실제 실행 시 CLI arguments/profile은 미확인이다.
| 경로/집합 | 범위 판정 및 확인 내용 |
|---|---|
| `~/.codex/config.toml` | trusted project, model/approval/sandbox 설정은 관찰됐으나 skill routing permission과 혼동하지 않는다. multi_agent/plugins 및 `omo@sisyphuslabs` 사용 설정 확인. 명시적 Superpowers enabled 항목, `skills.config` disable/policy override, project doc budget/fallback/instruction override는 관찰되지 않았다. |
| `~/.codex/agents/*.toml` | 13개 role별 TOML 경로가 확인됐다. 대표 경로 `default.toml`, `explorer.toml`, `plan.toml`, `librarian.toml`, `metis.toml`, `momus.toml`, `lazycodex-code-reviewer.toml`, `lazycodex-gate-reviewer.toml`. 이들은 전역 repo 우선순위가 아니라 해당 subagent 역할 지침이다. 후자의 두 reviewer role은 `remove-ai-slops`/`programming`을 role 내부에서만 언급한다. |
| `~/.config/opencode/opencode.json` | Superpowers, Ponytail, OMO plugin 선언 확인. 명시적 instructions/skills/permission 설정은 관찰되지 않았다. |
| `~/.config/opencode/agents/` 및 `oh-my-openagent` | 전역 agents 폴더는 비어 있음. OMO 디렉터리의 `native-nudge.json`은 state이며 universal instructions가 아니다. |
| repo `.agents/skills`, `.opencode/skills` | `.agents/skills`는 비어 있고 `.opencode/skills`는 없다. `.opencode/` 자체는 존재하며 package 메타데이터와 node_modules만 있고 활성 지침/설정은 없다. |
| `~/.codex/skills` | `.system`만 있음. 이는 plain `system` 이름의 skill과 다르다. |
| `/etc/codex` | 경로 없음. |
| `~/.claude/skills` | 없음. `~/.config/opencode/skills/commit-with-validation`은 별도 user skill이며 이번 routing catalog와 혼동하지 않는다. |
Codex role별 TOML은 repo/global instruction hierarchy에 속하지 않는 role-specific guidance다. 전역 설정 파일이 있다는 사실도 skill을 자동 실행한다는 보장이 아니다.
## 공식 문서 및 참조
다음 문서/저장소 주소를 조사 근거로 사용했다. host 동작은 설치 버전과 문서 버전을 구분한다.
- Codex AGENTS: <https://learn.chatgpt.com/docs/agent-configuration/agents-md>
- Codex skills: <https://learn.chatgpt.com/docs/build-skills.md>
- OpenCode rules: <https://opencode.ai/docs/rules/>
- OpenCode skills: <https://opencode.ai/docs/skills/>
- Superpowers: <https://github.com/obra/superpowers>
- Matt Pocock skills: <https://github.com/mattpocock/skills>
- Addy Osmani skills: <https://github.com/addyosmani/agent-skills>
- Addy upstream skills index: <https://github.com/addyosmani/agent-skills/blob/main/README.md>
Codex AGENTS 문서는 global override/fallback, repo-root→cwd 지침 계층과 32 KiB 기본 예산을 설명한다. OpenCode rules v1은 cwd 상위 탐색과 instruction 결합을 설명하며 v2 문서를 설치된 v1.19.3에 혼합하지 않는다. Codex skills는 `agents/openai.yaml`의 `policy.allow_implicit_invocation: false` 및 skills 설정을 설명한다. OpenCode skills 문서의 key 표기는 `metadata["opencode/autoinvoke"]`다. OpenCode v1 공식 문서는 Codex식 top-level `disable-model-invocation` 호환을 약속하지 않는다. 명시적 요청 의도는 host가 같은 통제를 보장한다고 추정하지 않고 루트 routing에서도 존중한다.
Codex는 전역에서 비어 있지 않은 `AGENTS.override.md`를 먼저 선택하고 없으면 `AGENTS.md`를 사용한다.
프로젝트는 Git root부터 cwd까지 디렉터리마다 override, AGENTS, 설정된 fallback 순으로 최대 한 파일을 선택한다.
루트에서 하위 방향으로 결합하며 더 가까운 지침이 앞선 지침을 구체화한다.
OpenCode v1은 cwd에서 상위로 로컬 AGENTS/CLAUDE를 찾고 같은 범주에서는 먼저 일치한 파일을 선택한다.
전역 AGENTS가 없으면 Claude 전역 지침으로 fallback하며, 설정의 `instructions`는 발견한 지침과 결합한다.
OpenCode v1 문서는 `AGENTS.override.md` 지원을 명시하지 않는다. 이 파일 발견 규칙은 아래 스킬의 단계별 책임 순서와 별개다.
## Superpowers 설치 및 역할
경로 표기:
- `SP=/Users/klaus/.cache/opencode/packages/superpowers@git+https:/github.com/obra/superpowers.git/node_modules/superpowers`
- `CSP=/Users/klaus/.codex/plugins/cache/openai-curated-remote/superpowers/6.4.2`
- `U=/Users/klaus/.agents/skills`
OpenCode의 `SP/skills/<name>/SKILL.md`에서 확인된 실제 15개:
1. `using-superpowers`
2. `brainstorming`
3. `writing-plans`
4. `executing-plans`
5. `subagent-driven-development`
6. `dispatching-parallel-agents`
7. `using-git-worktrees`
8. `test-driven-development`
9. `systematic-debugging`
10. `requesting-code-review`
11. `receiving-code-review`
12. `verification-before-completion`
13. `finishing-a-development-branch`
14. `diagnosing-superpowers`
15. `writing-skills`
`deep-interview`는 별도 사용자 skill이며 이 15개 Superpowers 목록에 포함되지 않는다. Codex cache `CSP/skills/<name>/SKILL.md`에도 15개가 있으나 cache 존재는 plugin 활성/실제 호출을 증명하지 않는다. OpenCode plugin `.opencode/plugins/superpowers.js` lines 219-264는 `skills.paths` 등록, 첫 top-level 사용자 메시지에 `using-superpowers` 절차 주입, child session 제외를 수행한다. Codex에서 Superpowers 활성화/자동 invocation 성공은 미확인이다. OpenCode parent의 available skill catalog는 여러 skill을 노출하지만 CLI `debug skill`은 일부만 관찰됐다. 부분 listing으로 부재를 추정하지 않는다. OpenCode 복사본과 Codex 캐시 복사본은 동일하지 않으며 brainstorming/systematic-debugging/requesting-code-review 차이가 조사됐다.
선택 원칙: 필요한 작업에서 `using-superpowers`가 이미 주입된 경우 같은 절차를 중복 로드하지 않는다. 새 설계는 brainstorming, 계획은 `writing-plans`, 실행은 `executing-plans` inline 또는 `subagent-driven-development` 중 하나, 구현 중 TDD, 필요 시 debugging, 요청된 리뷰, 완료 전 fresh verification 순으로 연결한다. `finishing-a-development-branch`는 통합 판단이 실제 필요할 때만 쓴다. worktree는 필요한지 확인하는 것과 자동 생성하는 것을 구분하며 자동 commit은 없다. runtime tool/skill permission은 계속 우선한다.
## 사용자 영역 skill 목록과 메타데이터
### Matt Pocock set
| 정확한 경로 | 책임/선택 | 발견된 invocation metadata |
|---|---|---|
| `U/domain-modeling/SKILL.md` | domain terminology, `GLOSSARY.md`, ADR 기록/수정. | `agents/openai.yaml` display metadata만, policy block 없음. |
| `U/codebase-design/SKILL.md` | module/interface 경계, deepening/seam 설계 어휘. | display metadata만, policy block 없음. |
| `U/grilling/SKILL.md` | plan/idea/decision을 충분히 구체화한 뒤 선택지를 stress-test하는 질문. | SKILL frontmatter에 `name`, `description`만. `agents/openai.yaml`은 display metadata만. disable/policy invocation 제한 없음. |
| `U/improve-codebase-architecture/SKILL.md` | architecture 후보를 시각 보고서로 제시, 후보 선택 뒤 정해진 후속 흐름. | `disable-model-invocation: true`와 `agents/openai.yaml`의 `policy.allow_implicit_invocation: false`. explicit 요청 없이 자동 선택 금지. |
| `U/setup-matt-pocock-skills/SKILL.md` | 해당 engineering skill set 초기 설정. setup 완료 상태. | `disable-model-invocation: true`와 `policy.allow_implicit_invocation: false`. explicit 요청 없이 재실행 금지. |
정확한 경로는 위 표의 `U=/Users/klaus/.agents/skills` 치환이다. `grilling`의 일반 언어 요청 trigger는 stress-test plan/decision/idea이며 정확한 skill 이름을 요구하지 않는다. 다만 구조화된 인터뷰가 아니라 매 라운드에 정착된 전체 frontier를 질문하며 사용자의 응답을 기다리고, frontier가 비고 사용자가 확인할 때 끝난다. 이는 요구사항 discovery를 위한 단일 불확실성 질문 루프와 목적이 다르다.
### `deep-interview` 상세 근거
- 경로: `U/deep-interview/SKILL.md` (127 lines); 조사된 디렉터리에는 `SKILL.md`만 있다. Frontmatter는 `name`, `description`, `argument-hint`; `disable-model-invocation`, `agents/openai.yaml`, OpenCode autoinvoke metadata, file/tool-specific dependency가 발견되지 않았다.
- Trigger: 모호한 goal/scope/constraints/success/context, 명시적인 deep-interview 또는 생각 정리 요청. 구체적이고 작은 수정/테스트 보강에서는 제외한다.
- 순서: 기존 코드/근거로 답할 수 있으면 먼저 조사하고 사용자에게 반복 질문하지 않는다. 라운드마다 가장 큰 미해결 질문 하나를 묻고 답을 반영해 점수를 갱신한다.
- Dimensions: Goal, Scope, Constraints, Success, Context 각 0..1. `Context`는 기존 코드베이스를 변경하는 경우에만 평가한다. 새 프로젝트 가중치는 `.35/.25/.15/.25`; 기존 코드베이스 작업 가중치는 `.30/.20/.15/.20/.15`다. 모호성은 1에서 가중 명확성 합을 뺀 판단 보조값이지 객관적인 측정값이 아니다.
- 종료: ambiguity `<=.20`이고 중요한 unknown이 해결됐을 때 종료한다. 중요한 dimension이 `<=.50`이면 중요 미결점이 남아 라운드를 계속할 수 있다.
- 출력: 최종 score, dimensions, decisions, open questions를 chat에 출력한다. 고정 산출 파일 작성이나 파일 변경은 요구되지 않는다.
- 적용 한계: 정적 skill 경로상 host의 implicit invocation은 가능할 수 있지만 실제 Codex/OpenCode invocation은 테스트되지 않았다. 이 문서 작성 요청은 이미 명확하므로 이번 작업에서 skill을 실제 호출하지 않았다.
brainstorming은 새로운 동작/선택의 제품 의도를 정리하는 기본 설계 단계다. deep-interview는 특히 모호한 요구사항에만 필요한 조건부 discovery 도구다. grilling은 충분히 정해진 선택지/결정을 압박 시험하는 user-triggered 다중 질문 절차다. 이 세 가지를 모든 작업마다 순차 실행하거나 동일한 단일 질문 인터뷰로 취급하지 않는다.
### 추가 specialist 6개
| 정확한 경로 | 선택 조건 | upstream 확인 경계 |
|---|---|---|
| `U/api-and-interface-design/SKILL.md` | 공개 API/module contract 변경, 호환성, 오류, boundary input. | Upstream 동일 이름 파일 확인: `https://github.com/addyosmani/agent-skills/blob/main/skills/api-and-interface-design/SKILL.md`. 이름 대응은 검증됐지만 local provenance/byte identity는 보장하지 않는다. |
| `U/security-and-hardening/SKILL.md` | auth, sensitive data, external integrations, CORS, uploads, rate limit, elevated roles. | `https://github.com/addyosmani/agent-skills/blob/main/skills/security-and-hardening/SKILL.md`; 동일한 한계. |
| `U/ci-cd-and-automation/SKILL.md` | CI/CD/build/deploy pipeline 자동화. | `https://github.com/addyosmani/agent-skills/blob/main/skills/ci-cd-and-automation/SKILL.md`; 동일한 한계. |
| `U/observability-and-instrumentation/SKILL.md` | 운영 logging, metrics, tracing, alerting. | `https://github.com/addyosmani/agent-skills/blob/main/skills/observability-and-instrumentation/SKILL.md`; 동일한 한계. |
| `U/performance-optimization/SKILL.md` | 성능 목표/측정 병목/명시 최적화. | `https://github.com/addyosmani/agent-skills/blob/main/skills/performance-optimization/SKILL.md`; 동일한 한계. |
| `U/frontend-ui-engineering/SKILL.md` | 사용자 frontend UI/page/component. | `https://github.com/addyosmani/agent-skills/blob/main/skills/frontend-ui-engineering/SKILL.md`; 동일한 한계. |
Addy README 및 `using-agent-skills` mapping에서 같은 이름이 확인됐다. 이는 upstream correspondence만 검증하며 로컬 설치 출처/byte identity는 증명하지 않는다. 위 여섯 로컬 skill에서 invocation 제한 metadata는 관찰되지 않았지만, host가 실제로 자동 호출한다는 보장은 아니다. 예시 specialist 선택은 기존 Kotlin/Spring naming, DTO, API contract를 대체하거나 rename하지 않는다.
`U/deprecation-and-migration/SKILL.md`, `U/debugging-and-error-recovery/SKILL.md`는 존재하지 않는다. 이 참조를 active routing target으로 취급하지 않는다.
## 중복 라우팅 판정: 여섯 쌍
| 조합 | 겹치는 부분 | 고유 책임 | 선택 predicate / owner |
|---|---|---|---|
| `brainstorming` / `deep-interview` | 새 요구의 불확실성 정리. | brainstorming은 새 동작의 선택/설계; deep-interview는 모호한 목표·범위·수용기준의 인터뷰. | 설계 시작이 main; 요구 핵심이 불명확할 때만 deep-interview 먼저, 답 반영 후 brainstorming. |
| `brainstorming` / `grilling` | 아이디어와 tradeoff를 다룰 수 있음. | brainstorming은 설계를 만들고 선택; grilling은 정착된 결정 frontier를 stress-test한다. | 새 설계에서 brainstorming owner; 사용자가 결정 스트레스테스트를 요청할 때만 grilling 추가. 정확 skill명 불필요. |
| `brainstorming` / `codebase-design` | 설계 옵션을 분석할 수 있음. | brainstorming은 제품 동작/요구 선택; codebase-design은 구조적 seam/module boundary 평가. | 새 동작 설계 주체는 brainstorming; 구조 boundary가 요청/실질 이슈일 때 codebase-design 보조. |
| `codebase-design` / `api-and-interface-design` | module/interface 경계와 계약. | codebase-design은 모듈 깊이/seam; API skill은 소비자-facing 계약, 호환성, request/response/error. | 구조 평가 owner는 codebase-design; 공개 contract 하위 작업이 있을 때 API specialist만 해당 하위 범위 owner. |
| `requesting-code-review` / `security-and-hardening` | 위험과 결함 검토. | requesting-code-review는 리뷰 실행/완료 gate 프로세스; security skill은 threat model 및 보안 기준. | review delegation이 적용되면 단일 main review process, security는 criteria/specialist 보조. 같은 변경을 중복 full review하지 않고 자동 수정 금지. |
| `systematic-debugging` / general exploration | 문제 원인 조사. | debugging은 재현된 실패의 hypothesis/causal test loop; general exploration은 요청된 read-only code understanding. | 재현 가능한 오류/실패가 main이면 systematic-debugging; 광범위한 이해 질문만 있으면 일반 조사, 무관한 debugging 절차를 붙이지 않음. |
## checklist 결손과 sign-off
- 다음 네 공유 문서는 모두 없다: `/Users/klaus/.agents/references/security-checklist.md`, `/Users/klaus/.agents/references/accessibility-checklist.md`, `/Users/klaus/.agents/references/performance-checklist.md`, `/Users/klaus/.agents/references/observability-checklist.md`.
- `U/security-and-hardening/references/`에는 `hardening-patterns.md`만 있다.
- 전역 파일을 생성/수정하거나 설치하지 않는다. 해당 checklist가 필요한 audit/sign-off는 그 참조 부분에 대해 완전하다고 주장하지 않고 결손을 보고한다. 확인 가능한 자체 코드/skill guidance 검토는 별도로 수행할 수 있지만 누락된 기준을 대체한다고 주장하지 않는다.
## 후속 루트 정책의 제한 영역
루트 요약은 Skill Orchestration, Skill Priority and Selection, Requirements Discovery, Skill Routing by Task Type, Conflict and Duplication Resolution, Automatic Invocation Constraints, Verification and Completion의 7개 주제를 짧게 다룬다. skill body를 복제하지 않는다. 프로젝트 CORE/가이드/기존 naming·contract 우선, 권한, 한국어 설명, PRD/plan, focused test, no automatic commit/install을 유지한다.
## 미확인 및 비보장 사항
이번 범위에서 전역 설정·설치 파일은 변경하지 않았다. 후속으로 Codex Superpowers의 활성 상태를 확인하고
필요하면 공식 관리 절차로 활성화하거나, 설치 버전에 맞는 전문 스킬의 누락 참조를 복구하는 작업은 별도 승인이 필요하다.
호출 제한을 풀거나 우회하기 위해 frontmatter를 바꾸는 제안은 하지 않는다.
- Codex에서 Superpowers plugin의 실제 자동 활성/호출 성공, OpenCode 전체 runtime catalog와 각 모델 invocation.
- 조사 순간 이후의 config, 실행 CLI arguments/profile, tool permission 및 skill precedence.
- 캐시와 installed skill 간 byte identity; Addy upstream name correspondence는 확인됐으나 local provenance는 확인되지 않음.
- missing checklist를 사용하는 complete sign-off. 이는 결손으로 확인됨.
- 사용자 routing scenario의 runtime 재현/자동 invocation 성공.
@@ -1,174 +0,0 @@
# 스킬 오케스트레이션 구현 계획
| 항목 | 내용 |
|---|---|
| 상태 | 구현 완료 |
| 작성일 | 2026-10-19 |
| 요구사항 기준 | [`prd.md`](prd.md) |
| 현재 Phase | Phase 1: 문서 및 루트 정책 통합 |
| 현재 활성 Goal | 없음 |
## 목표
사용자 의도에 맞는 skill orchestration 정책을 루트 `AGENTS.md`에 적용하고, 근거 감사와 9개 routing scenario 및 문서 검증 증거를 완성한다.
## 현재 상태
| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
|---:|---|---:|---|---|
| 1 | 완료 | `2/2` | 없음 | 논리 대조·문서 검사·별도 검토 완료, 런타임 자동 호출은 미검증 |
동시에 하나의 미완료 Goal만 실행한다. 사용자는 안전한 조사, 문서 및 범위 내 루트 변경을 이미 명시적으로 승인했다. 후속 승인 대기 단계를 만들지 않는다.
## 범위
### 포함
- `AGENTS.md`의 기존 원칙 아래 skill orchestration 요약 변경.
- `docs/20261019_스킬오케스트레이션/`의 PRD, 계획, 근거 감사, 지정 원문 기반 9 scenario.
- scenario/PRD/audit/루트 정책 사이 일관성 및 문서 검증.
### 제외
- 앱 코드/테스트/스크립트, 전역 설정/지침, skill/plugin 파일 수정 또는 설치.
- `AGENTS.md`의 요청 범위 바깥 기존 내용 변경.
- gstack/worktree/commit/push 및 실제 skill invocation 실험.
- 자동 invocation이 동작한다고 주장하거나 누락된 checklist를 만들고 sign-off 기준을 완화하는 일.
## 문서 작업 TDD 예외
문서/정책 변경은 생산 동작을 바꾸지 않으므로 fake unit test를 만들지 않는다. 대체 검증은 네 파일 정확성, 9개 원문/필드, source·metadata 주장 및 root diff의 assertion 대조다. 실행 시 다음을 사용하고 결과를 사실대로 기록한다.
```bash
git diff --check
git diff --no-index --check /dev/null docs/20261019_스킬오케스트레이션/prd.md
git diff --no-index --check /dev/null docs/20261019_스킬오케스트레이션/plan-task.md
git diff --no-index --check /dev/null docs/20261019_스킬오케스트레이션/audit.md
git diff --no-index --check /dev/null docs/20261019_스킬오케스트레이션/routing-scenarios.md
wc -c AGENTS.md
./gradlew tasks --all
```
현재 문서 정정 작업에서는 이 명령들을 실행하지 않는다. `wc -c` 출력은 Codex의 32,768 byte 기본 budget과 비교하고, Gradle 명령은 문서 변경에 대한 프로젝트 요구 점검이다. 네 파일 신규 비교가 필요하면 `git diff --no-index -- /dev/null <위의 실제 파일 경로>`를 실행한다. 이는 차이를 출력하고 통상 exit 1이므로 차이 출력과 실제 오류를 구분한다.
### Phase 1: 문서 및 루트 정책 통합
**Phase 결과:** 루트 정책과 네 문서가 같은 책임 분리와 승인 경계를 표현하며, 지정 시나리오와 실제 점검 결과를 추적할 수 있다.
**선행조건:** 필수 프로젝트 문서와 설치 근거를 읽었고 사용자가 전체 범위를 승인했다.
- [x] **Task 1.1: 사전 문서 작성 및 정정**
**Goal ID: `P1-T1`**
- **Objective:** 정확한 범위, 조사 근거, 9개 지정 요청의 라우팅 기대를 네 문서에 일관되게 남긴다.
- **시작 조건:** 루트 지침/가이드/샘플 및 조사된 host/skill 근거 확인.
- **정확한 파일 경로:** `docs/20261019_스킬오케스트레이션/prd.md`, `plan-task.md`, `audit.md`, `routing-scenarios.md`.
- **완료 증거:** 네 파일 존재, PRD/plan이 루트 구현까지 포괄, 9개 원문과 필수 8필드, 확정된 metadata 사실, 계획된 검증을 실제 수행했다고 오기하지 않음.
- **범위 밖:** `AGENTS.md` 편집, 기존 문서/설정/skill 변경, 실제 skill invocation.
- **TDD 예외 사유:** 문서만 작성한다.
- **대체 검증 방법:** 파일 수, assertion, 시나리오/근거 대조. 검증 명령 미실행 상태를 보존한다.
- [x] 필수 문서 및 조사 근거 기반 초안 네 파일을 작성했다.
- [x] 정정 요청을 반영해 PRD/plan 범위, invocation 사실, 감사 근거 및 시나리오를 갱신했다.
- [x] **Task 1.2: 루트 skill orchestration 정책 적용**
**Goal ID: `P1-T2`**
- **Objective:** PRD의 확정 요구와 audit의 근거를 적용해 기존 루트 정책 아래에 최소 routing 요약을 반영한다.
- **시작 조건:** `P1-T1`의 정정된 문서가 있고 기존 CORE/프로젝트 규칙을 보존한다.
- **정확한 파일 경로:** 수정 `AGENTS.md`; 근거 `docs/20261019_스킬오케스트레이션/prd.md`, `audit.md`, `routing-scenarios.md`.
- **완료 증거:** 요청된 제한 영역만 바꾸고 9 scenario에 대조하며 실제 실행한 검증만 기록한다.
- **범위 밖:** 다른 기존 파일, 글로벌 설정, `SKILL.md`/plugin, 설치, gstack, 자동 commit, runtime 호출 주장.
- **TDD 예외 사유:** 자연어 정책 편집이며 독립 생산 동작이 없다.
- **대체 검증 방법:** AGENTS diff와 문서 assertion 대조, `git diff --check`, actual-path no-index whitespace check, byte budget 및 `./gradlew tasks --all` 결과.
- [x] 변경할 루트 영역을 읽고 유지할 기존 우선순위/작업 절차를 대조한다.
- [x] 분류, 조건부 deep-interview, 단일 실행 경로, 중복 방지, 권한/발견 제한, 검증 시점만 최소 문구로 반영한다.
- [x] 일반 architecture 요청에서 explicit-only skill을 선택하지 않으며 `grilling`을 explicit-only로 잘못 분류하지 않았는지 확인한다.
- [x] 9개 exact prompt와 정책을 대조하고 실제 검증 결과를 기록한다.
- [x] **Phase Gate: 정책·근거·시나리오 정합성**
**Goal ID: `P1-GATE`**
- **Objective:** 루트 변경과 네 문서가 사용자 범위, 사실 근거, 프로젝트 문서 검증 요건을 충족하는지 판정한다.
- **시작 조건:** `P1-T1`, `P1-T2` 완료.
- **정확한 파일 경로:** `AGENTS.md`, `docs/20261019_스킬오케스트레이션/{prd.md,plan-task.md,audit.md,routing-scenarios.md}`.
- **완료 증거:** 4파일/9원문 assertion, 9 scenario 8필드, diff 공백 확인, `wc -c AGENTS.md`, Gradle task 명령 결과와 미확인 조건 기록.
- **범위 밖:** 자동 호출 성공 주장, checklist 결손 은폐/완화, 무관한 수정.
- **TDD 예외 사유:** 최종 정책·문서 검토.
- **대체 검증 방법:** 위 명령을 실제 실행하고 출력 및 exit status를 기록한다. `git diff --no-index`의 정상 차이 exit 1은 whitespace 검사 실패로 취급하지 않는다.
- [x] 모든 자동/보조 라우팅 조건이 audit의 설치/metadata 근거와 일치한다.
- [x] 전역 공유 checklist 부재를 보고하고 그 checklist 기반 full sign-off를 주장하지 않는다.
- [x] 실제 검증 결과, 남은 제한, 요청 범위 외 변경 부재를 기록한다.
## 실행 순서와 의존성
| 순서 | Goal | 선행조건 | 상태 |
|---:|---|---|---|
| 1 | `P1-T1` | 필수 가이드/근거 확인 | 완료, 이 정정판으로 갱신 |
| 2 | `P1-T2` | 정정된 사전 문서 | 완료 |
| 3 | `P1-GATE` | `P1-T1`, `P1-T2` 및 실제 검증 | 완료 |
## Progress
### `P1-T1` 실행 기록 (최초 작성)
- 무엇을: PRD/plan을 별도 patch로 먼저 만들고 audit/scenarios를 뒤에 추가했다.
- 어떻게: 네 파일/9개 scenario 존재는 읽기/검색 도구로 확인했다. `git diff --check`, no-index, `wc -c`, Gradle 명령은 실행하지 않았다.
- 결과: 초안 작성은 완료했으나 이후 부모 검토에서 범위, grilling metadata, 설치 근거, checklist 결손과 scenario prompt/소유권 오류가 발견되어 아래 정정 기록을 추가했다.
### `P1-T1` 정정 기록
- 상태: 문서 정정 완료, 검증 명령 대기.
- 무엇을: 전체 사용자 승인 범위와 실제 근거, 요청 원문 그대로의 9 scenario, 명시적 요청/자동 선택 구분을 네 파일에 반영했다.
- 검증: `P1-T1` 문서 편집을 완료로 표시한다. 최종 문서 점검 명령은 실행하지 않았다.
- 이전 오류 기록을 삭제하지 않고 현재 문서 내용을 정정했다.
### `P1-T2` 실행 기록
- 상태: 대기.
- 다음 행동: 정정된 PRD/audit/scenarios를 따라 루트 정책 편집.
### `P1-T1` 부모 검증 및 `P1-T2` 착수 - 2026-10-19
- 무엇을: 네 선행 문서를 모두 읽고 설치 파일·사용자 원문과 대조했다.
- 보정: `.opencode/` 자체의 존재와 활성 설정 부재를 구분하고, deep-interview의 `argument-hint` 및 Context 평가 조건을 바로잡았다.
- `test`/`rg` 검사: 종료 코드 0. 필수 문서 존재, 시나리오 9개 및 각 8개 필드(총 72개)를 확인했다.
- 신규 네 파일의 `git diff --no-index --check /dev/null "$file"`: 종료 코드 0, 공백 오류 없음.
- 결과: 선행 문서 검증 완료. `P1-T2`는 기존 내용 보존 및 한 줄 우선순위 명확화와 7개 짧은 정책 섹션 추가를 위임해 진행 중이다.
### `P1-GATE` 실행 기록
- 상태: 대기.
- 다음 행동: 루트 편집 및 실제 검증 결과가 준비된 뒤 판정.
### `P1-T2` 완료 및 `P1-GATE` 1차 검증 - 2026-10-19
- 무엇을: 기존 우선순위 문장 한 줄을 상위 지침/권한 경계로 명확히 하고 7개 routing 섹션을 추가했다.
- 왜: Superpowers 메인 흐름과 단계별 단일 책임, 선택적 specialist, 명시 호출 전용 제한을 실제 루트 지침에 반영하기 위해서다.
- `git diff -- AGENTS.md`: 기존 본문은 우선순위 한 줄 외 보존. `git diff --numstat`는 77줄 추가/1줄 삭제다.
- `git status --short --untracked-files=all`: `AGENTS.md`와 이 폴더의 신규 네 Markdown 문서만 변경됐다.
- `git diff --check` 및 신규 네 문서의 no-index `--check`: 종료 코드 0, 공백 오류 없음.
- `test`/`rg`: 종료 코드 0. 7개 루트 heading이 각각 한 번, 9개 원문 요청과 72개 필드, 참조 파일 존재 및 내부 주석/루트 override 미생성을 확인했다.
- 수동 논리 대조: 9개 scenario 모두 현재 루트 정책에 일치. 도메인 분석·보안 리뷰·버그 수정 등 가상 작업 자체나 모델의 자동 호출은 실행하지 않았다.
- `wc -c AGENTS.md`: 17,988 bytes로 Codex 기본 32,768 byte 예산 미만이다.
- `./gradlew tasks --all`: 종료 코드 0, `BUILD SUCCESSFUL`. 기존 Gradle 9.0 관련 deprecation 경고는 유지된다.
- 전역 설정 두 개 및 deep-interview/명시 호출 제한 관련 다섯 파일의 SHA-256은 편집 전 값과 동일하다. 전역 설정·설치 파일은 수정하지 않았다.
- 다섯 변경 파일에 LSP 진단을 요청했으나 `.md` 서버가 설정되지 않아 수행할 수 없었다. 서버/설정은 추가하지 않고 문서 대조 및 공백 검사로 검증했다.
- 전체 테스트·빌드는 실행하지 않았다. 실행 코드·의존성·빌드 설정 변경이 없어 문서 정합성·diff 검사와 Gradle task 목록으로 검증했다.
- 남은 항목: 별도 최종 검토 결과와 최종 문서 공백/범위 재검사. 런타임 자동 invocation은 이번 Gate 범위 밖이며 미검증이다.
### `P1-GATE` 별도 검토 및 완료 판정 - 2026-10-19
- 별도 검토 결과: 수정 필수/권고 수준의 실질적 finding 없음. 기존 내용 보존, 실제 스킬 원문/metadata와의 일치,
명시 호출 제한, 문서 크기, checklist 결손 보고 및 변경 범위를 확인했다.
- 검토자는 Gradle·모델 실행을 반복하지 않았다. 사용자 9개 원문 대조와 Gradle/전역 파일 해시 검증은 부모 실행 결과를 근거로 한다.
- 시나리오 문서에 9개 논리 대조 PASS와 9개 런타임 자동 호출 미실행을 별도로 기록했다.
- 결과: `P1-T1`, `P1-T2`, `P1-GATE` 완료. 남은 호스트 활성화/참조 결손은 audit의 비보장 및 별도 승인 영역으로 남긴다.
- 커밋·푸시·전역 설정 변경·스킬 설치·gstack 실행은 수행하지 않았다.
- 최종 재검사: 시나리오 9개/72개 필드/논리 PASS 9행 및 미완료 계획 항목 부재를 확인했고,
변경·신규 문서 공백 검사는 종료 코드 0, `./gradlew tasks --all` 재실행도 `BUILD SUCCESSFUL`이었다.
@@ -1,67 +0,0 @@
# 스킬 오케스트레이션 요구사항
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | 구현 완료 |
| 작성일 | 2026-10-19 |
| 최종 수정일 | 2026-10-19 |
| 대상 | 루트 `AGENTS.md`의 skill orchestration 정책 및 사전 문서 |
| 관련 구현 계획 | [`plan-task.md`](plan-task.md) |
| 조사/시나리오 | [`audit.md`](audit.md), [`routing-scenarios.md`](routing-scenarios.md) |
## 1. 문제와 목표
루트 `AGENTS.md`는 일부 skill을 소개하지만 작업 유형별 선택, 순서, 중복 해소, 명시적 요청 경계와 host별 발견 한계를 한곳에서 안내하지 않는다. 이는 문서 baseline의 routing 공백이며, 자동 호출 실패라는 런타임 판정은 아니다.
목표는 사용자의 작업 유형에 맞는 최소 skill 선택 및 순서를 루트 정책으로 정리하고, 그 정책을 뒷받침하는 근거와 아홉 개의 실제 사용자 요청 예시를 함께 제공하는 것이다. 전체 승인 범위는 루트 `AGENTS.md`의 제한된 skill orchestration 영역 변경과 이 폴더의 네 문서 완성이다.
## 2. 범위
### 포함
- `AGENTS.md`에 skill 선택, 선행 순서, 중복 해소, explicit-only 처리, 자동 호출 조건, 검증/완료 경계를 좁게 추가한다.
- 다음 네 문서를 완성한다: `docs/20261019_스킬오케스트레이션/prd.md`, `plan-task.md`, `audit.md`, `routing-scenarios.md`.
- 현재 루트/전역 지침, 설치 경로, skill metadata와 공식 host 문서를 구분해 근거/불확실성을 기록한다.
- 9개 지정 요청에 각기 분류, 주 skill, 보조 skill, 실행 순서, 제외 대상, 조건부 자동 선택, 승인 경계, 관찰/검증 상태를 기록한다.
- 프로젝트 CORE와 기존 PRD/plan, TDD, focused verification, 한국어 보고 규칙을 유지한다.
### 제외
- 런타임 앱 코드, 테스트, 스크립트 또는 새 skill/plugin 구현.
- 전역/프로젝트 host 설정, global `AGENTS.md`, `SKILL.md` 변경, 설치 또는 gstack 설치.
- 문서에서 제안한 routing의 모델 자동 invocation을 테스트/보장한다고 주장하는 일.
- 요청된 루트 skill orchestration 영역 밖의 `AGENTS.md` 정리, 다른 기존 파일 변경, 자동 commit/push.
- PRD/plan 절차, API 계약, 보안 gate, 공통 tooling을 새로 정의하거나 약화하는 일.
## 3. 정책 요구사항
| ID | 요구사항 | 수용 기준 |
|---|---|---|
| ORCH-001 | 작업 산출물에 맞게 최소 skill 조합을 선택한다. | 대표 작업 유형에서 주 책임과 조건부 specialist가 구분되며 무관한 skill을 체인에 넣지 않는다. |
| ORCH-002 | 흐름은 요청의 명료도와 구현 여부에 맞춘다. | 새 기능은 brainstorming을 사용하고, 모호할 때만 deep-interview를 선택한 뒤 설계로 돌아간다. 구현은 기존 PRD/plan, 한 실행 경로, 구현 시 TDD를 따른다. |
| ORCH-003 | explicit-only 제약과 사용자 의도를 보존한다. | `improve-codebase-architecture`, `setup-matt-pocock-skills`는 implicit invocation하지 않는다. `grilling`을 metadata상 암묵 호출 금지로 오인하지 않고, 의미상 stress-test 요청일 때 조건부 선택한다. |
| ORCH-004 | 겹치는 skill은 책임별로 나눈다. | `audit.md`에 6개 쌍의 역할 차이와 선택 기준이 있고, 9개 시나리오에서 중복 실행/소유권을 판정한다. |
| ORCH-005 | 발견 상태와 실제 invocation을 분리한다. | 조건부 사용은 host에서 발견 가능하고 권한이 허용되는 경우로 한정한다. runtime 자동 호출은 테스트됐다고 하지 않는다. |
| ORCH-006 | 기존 프로젝트 정책과 상위 권한을 보존한다. | 기존 CORE/프로젝트 절차가 skill 일반 지침보다 우선한다. 자동 승인, 설치, commit을 추가하지 않는다. |
| ORCH-007 | 누락된 필수 checklist를 숨기거나 약화하지 않는다. | 전역 checklist 결손은 해당 checklist 기반 sign-off 제한으로 보고하며 파일 생성/설치/기준 완화는 하지 않는다. |
## 4. 충돌과 의존
- 시스템/플랫폼/도구 권한 및 루트 CORE와 프로젝트 규칙을 보존한다. 명확한 사용자 승인은 이 경계를 우회하지 않는다.
- 기존 `docs/agent-guides/작업절차.md`, `문서유지보수.md`의 PRD/plan 경로, goal, TDD 예외, focused test 우선 및 실제 결과 누적 요구를 유지한다.
- 조사된 shared checklist가 없으면 대체 문서를 임의로 작성하거나 full sign-off를 주장하지 않는다.
- Codex/OpenCode의 발견/우선순위는 각 host 문서에 귀속해 설명하며 하나의 공통 탐색 규칙으로 합치지 않는다.
## 5. 완료 기준
- 신규 문서는 지정 폴더 아래 정확히 네 개이며, 이 구현은 기존 `AGENTS.md`의 해당 routing 영역만 수정한다.
- 9개 scenario가 사용자 지정 원문 요청을 그대로 포함하고 각각 8개 필드를 갖는다. 문서상 논리 대조 결과와 런타임 자동 호출 미검증을 구분한다.
- `plan-task.md`의 루트 편집, 9 scenario 대조, 문서 점검 및 Gate가 실제 증거와 함께 완료된다.
- source/evidence path와 runtime 미확인 사항, checklist 결손이 정확히 구분된다.
- `git diff --check`, 신규 파일별 실제 경로 `git diff --no-index /dev/null <path>` 비교, `wc -c AGENTS.md`의 32,768 byte 기본 budget 비교, `./gradlew tasks --all` 결과는 실제 실행 뒤에만 기록한다.
## 6. 근거 범위
루트 `AGENTS.md`, 프로젝트 가이드와 샘플, 설치/설정 경로, Codex/OpenCode 공식 문서, skill 파일과 metadata를 [`audit.md`](audit.md)에 구체적으로 기록한다. 사용자 요청 원문 및 문서상 라우팅 기대는 [`routing-scenarios.md`](routing-scenarios.md)에 둔다.
@@ -1,143 +0,0 @@
# Skill routing 시나리오
## 판정 기준
각 요청 문구는 사용자가 지정한 원문 그대로다. 아래는 확인된 skill 책임을 적용한 문서상 routing 기대이며 모델 실행 결과가 아니다. 각 `관찰/검증` 필드의 PENDING은 해당 가상 업무와 모델 자동 호출을 실행하지 않았다는 뜻이다. 수정된 `AGENTS.md`와의 논리 대조는 아래 결과표에 별도로 기록한다. Host에서 해당 skill을 발견하고 도구 권한이 허용되어야 선택할 수 있다.
## 1. 로그인 기능
**요청:** 사용자 로그인 기능을 만들어줘.
- **분류:** 신규 사용자 기능, 인증/보안 경계 및 API 가능성이 있는 구현.
- **주 skill:** `brainstorming`.
- **보조 skill:** 인증/민감 정보 경계에 `security-and-hardening`; 공개 API가 포함될 때 `api-and-interface-design`; frontend가 범위일 때 `frontend-ui-engineering`.
- **실행 순서:** 요구/승인된 로그인 동작 정리 → 해당 보안/API/frontend 하위 범위 검토 → 기존 PRD/plan → 실행 경로 하나 → 구현 시 TDD → 변경 리뷰 → 완료 전 verification.
- **제외/중복:** 요구가 명료하면 `deep-interview` 제외. explicit stress-test가 아니면 `grilling` 제외. 보안 리뷰만 요청한 것이 아니므로 review skill로 구현을 대체하지 않는다.
- **조건부 자동 선택:** host discovery/permission이 허용하면 필요한 specialist만 선택 가능. 이는 자동 호출이 검증됐다는 뜻이 아니다.
- **승인/명시 요청:** 인증 방식, token lifecycle, scope 등 미정 정책을 임의 결정하지 않는다. 실제 기능 구현은 요청됐지만 보안 설계의 미결값은 해결이 필요하다.
- **관찰/검증:** PENDING. scenario simulation only; 실행 또는 자동 호출 증거 없음.
## 2. 모호한 신규 서비스
**요청:** 요구사항이 아직 모호한 신규 서비스를 설계해줘.
- **분류:** 모호한 목표/범위/성공 기준의 신규 설계.
- **주 skill:** `brainstorming`.
- **보조 skill:** ambiguity를 codebase/기존 문서로 해결할 수 없을 때만 `deep-interview`.
- **실행 순서:** 확인 가능한 기존 근거 확인 → 중요한 요구 unknown이 남으면 한 번에 가장 불확실한 질문을 하는 deep-interview → 응답 반영 → brainstorming으로 설계 정리.
- **제외/중복:** 모든 작업에서 deep-interview를 기본 실행하지 않는다. 정착된 결정 frontier를 사용자가 stress-test하라고 하지 않으면 `grilling` 제외. 구현 요청이 없으면 plan/실행/TDD 생략.
- **조건부 자동 선택:** deep-interview는 의미상 모호한 요청 조건에 맞을 수 있으나 실제 host/model 호출은 검증되지 않았다. grilling은 의미상 stress-test 요청일 때만 선택하며 명시적 skill 이름은 필수 아님.
- **승인/명시 요청:** 미정 제품 선택은 사용자에게 남기고 확정된 것처럼 기록하지 않는다.
- **관찰/검증:** PENDING. scenario simulation only; 인터뷰를 수행하지 않았다.
## 3. 결제 도메인 용어와 상태
**요청:** 결제 도메인의 용어와 상태를 정리해줘.
- **분류:** 결제 도메인 어휘와 state model 정리 요청.
- **주 skill:** `domain-modeling`.
- **보조 skill:** 상태 전이가 코드 구조/모듈 seam 평가를 요구할 때만 `codebase-design`.
- **실행 순서:** 현재 결제 코드/문서 용례를 조사 → 용어와 상태 의미를 분리해 정리 → 필요할 경우 현재 domain doc convention에 반영.
- **제외/중복:** glossary 언급만으로 ADR 작성, API 변경, 기능 구현, brainstorming-기반 신규 서비스 설계를 강제하지 않는다. 기술 seam이 없는 한 codebase-design 생략.
- **조건부 자동 선택:** glossary/domain model을 실제로 수정하는 범위면 domain-modeling이 관련된다. 파일 read-only 설명만 요청됐다면 수정 workflow로 넘어가지 않는다.
- **승인/명시 요청:** 용어의 의미/상태 전이가 코드와 다르면 제품 의미를 추측하지 말고 근거 및 미결점을 보고한다. ADR은 별도 결정 기록 필요가 있을 때만.
- **관찰/검증:** PENDING. scenario simulation only; domain 파일을 변경/검증하지 않았다.
## 4. 모듈 의존성 설계 검토
**요청:** 이 모듈의 의존성 설계를 검토해줘.
- **분류:** 기존 구조의 read-only architecture/interface evaluation.
- **주 skill:** `codebase-design`.
- **보조 skill:** 새 동작/구조 대안을 실제로 결정해야 할 때만 `brainstorming`.
- **실행 순서:** 의존성 및 호출자 근거 조사 → seam/ownership/tradeoff 평가 → 사실과 제안 분리 보고.
- **제외/중복:** 일반 architecture review는 `improve-codebase-architecture` explicit invocation을 뜻하지 않는다. HTML 보고서, `grilling`, 수정/리팩터링을 자동 시작하지 않는다.
- **조건부 자동 선택:** 일반 탐색 및 codebase-design은 질문의 구조 검토 의도에 맞는다. skill 선택은 host discovery/permission에 따라 다르며 runtime 미검증.
- **승인/명시 요청:** 파일 이동/코드 변경은 요청되지 않았으므로 읽기 전용으로 유지한다. 보고서 artifact도 임의 생성하지 않는다.
- **관찰/검증:** PENDING. scenario simulation only; 실제 의존성 분석은 수행하지 않았다.
## 5. 새 REST API 설계
**요청:** 새로운 REST API를 설계해줘.
- **분류:** 신규 API 동작 및 public contract 설계.
- **주 skill:** `brainstorming`이 system behavior/요구 설계를 소유한다.
- **보조 skill:** `api-and-interface-design`은 contract substage(호환성, request/response/error, 입력 경계)를 소유한다. 실제 trust/security boundary가 있으면 `security-and-hardening` 보조.
- **실행 순서:** 사용자/소비자 의도와 기존 contract 확인 → 필요한 신규 동작 brainstorming → API specialist의 제한된 contract 분석 → 보안 경계가 있으면 보안 검토 → 설계 결과 보고. 구현 요청이 추가되면 PRD/plan 이후 실행.
- **제외/중복:** API specialist가 전체 제품 의도나 전체 구현을 대신하지 않는다. 설계만 요청된 경우 코드/migration/test 구현은 제외.
- **조건부 자동 선택:** API contract substage가 존재할 때 API specialist 선택 가능; 보안은 경계가 있는 경우에 한한다. host discovery/permission 필요, 실제 invocation 미검증.
- **승인/명시 요청:** 기존 public schema compatibility를 깨는 변경과 미확정 error/validation 정책을 추정하지 않는다.
- **관찰/검증:** PENDING. scenario simulation only; API 계약/runtime 검증을 수행하지 않았다.
## 6. 인증 취약점 검토
**요청:** 인증 과정에 보안 취약점이 있는지 검토해줘.
- **분류:** 인증 security review, read-only.
- **주 skill:** `requesting-code-review`는 review delegation/검토 단계가 적용되는 경우 단일 main review process다.
- **보조 skill:** `security-and-hardening`은 threat model 및 security criteria를 제공한다. main review를 중복 실행하지 않는다.
- **실행 순서:** 허용 범위/인증 경계 조사 → 단일 review process로 evidence 기반 finding → 보안 기준에 따라 영향/완화안 구분 보고 → 요청된 검증만 실행.
- **제외/중복:** 자동 fix, `test-driven-development`, 구현용 brainstorming은 수정 요청이 별도로 없으면 제외한다. 두 번째 전체 security review를 같은 목적에 중복하지 않는다.
- **조건부 자동 선택:** 보안 경계 때문에 security specialist가 관련되지만 host discovery/permission에 의존한다. invocation은 미검증.
- **승인/명시 요청:** review는 수정 승인이 아니다. 체크리스트 참조가 필요한 sign-off는 checklist 결손을 밝히고 full sign-off로 표현하지 않는다.
- **관찰/검증:** PENDING. scenario simulation only; 코드 review/security test는 수행하지 않았다.
## 7. 테스트 실패 버그 수정
**요청:** 테스트에 실패하는 버그를 수정해줘.
- **분류:** 실패를 재현하고 근본 원인을 고쳐야 하는 bugfix.
- **주 skill:** `systematic-debugging`.
- **보조 skill:** 구현 변경이면 TDD 절차 및 단일 실행 경로; 마무리에 적절한 review와 fresh verification.
- **실행 순서:** 실패 재현/원인 증거 → 최소 회귀 test → 의도한 실패 확인 → 최소 수정/통과 → 직접 영향 회귀 → review → 완료 전 verification.
- **제외/중복:** 실패 원인이 명료하면 brainstorming/deep-interview/grilling을 추가하지 않는다. 일반 탐색을 별도 full process로 중복하지 않는다. 테스트 삭제/완화 금지.
- **조건부 자동 선택:** 실제 재현된 failure가 있을 때 systematic-debugging 관련. host discovery/permission 및 호출은 미검증.
- **승인/명시 요청:** 범위 변경은 기존 plan 갱신 후 진행한다. 수정 요청이므로 재현된 범위의 fix는 승인됐다.
- **관찰/검증:** PENDING. scenario simulation only; 테스트/코드 변경은 수행하지 않았다.
## 8. 기존 코드베이스 구조 개선 후보
**요청:** 기존 코드베이스에서 구조 개선 후보를 찾아줘.
- **분류:** 기존 시스템의 read-only exploratory review.
- **주 skill:** 일반 조사; 구조/경계 판단이 필요할 때 `codebase-design`.
- **보조 skill:** 일반 요청만으로는 explicit-only인 `improve-codebase-architecture`를 선택하지 않는다.
- **실행 순서:** 관련 코드/의존성 근거를 읽기 → 개선 후보/비용/근거를 설명 → 보고서/후속 작업 형식이 필요하면 사용자에게 opt-in 명시 호출을 안내.
- **제외/중복:** skill 주도의 HTML report workflow, 후보 선택 대기, `grilling`, 구현/commit을 자동 시작하지 않는다.
- **조건부 자동 선택:** `codebase-design`은 구조 평가에 조건부. `improve-codebase-architecture`는 사용자가 해당 스킬을 이름으로 명시하거나 host의 skill 선택기에서 직접 선택한 뒤에만 실행한다. 일반적인 보고서 요청도 명시 호출 제한을 우회하지 않는다.
- **승인/명시 요청:** 일반 후보 탐색은 읽기 전용 요청이다. HTML 산출물과 skill workflow의 explicit invocation은 별도 opt-in이다.
- **관찰/검증:** PENDING. scenario simulation only; 실제 repository review나 skill invocation은 수행하지 않았다.
## 9. 확정 설계 뒤 구현 재개
**요청:** 기존 설계가 확정되었으니 구현을 계속해줘.
- **분류:** 결정된 요구사항/기존 plan에 따른 연속 구현.
- **주 skill:** 하나의 plan execution path만 선택: inline 수행이면 `executing-plans`, subagent 방식이 실제 선택된 경우 `subagent-driven-development`.
- **보조 skill:** 구현 단계의 TDD, 필요한 debugging, 변경 review, fresh verification.
- **실행 순서:** 기존 PRD/plan·Decision Log 및 저장소 상태 확인 → 기존 미완료 task 실행 → 구현 시 TDD → review → 새 상태/검증 기록.
- **제외/중복:** blocker/새로운 critical gap 없이 brainstorming, deep-interview, 재계획, grilling을 반복하지 않는다. 두 execution path를 같이 실행하지 않는다.
- **조건부 자동 선택:** host에서 discover되고 permission이 허용되는 절차만 사용한다. Codex/OpenCode 자동 invocation 실제 결과는 미검증.
- **승인/명시 요청:** 기존 설계와 task를 따르는 구현은 요청됨. 새로운 제품 결정, scope expansion, 자동 commit은 포함하지 않는다.
- **관찰/검증:** PENDING. scenario simulation only; 구현/test/호출은 수행하지 않았다.
## 공통 host/승인 경계
### 문서상 논리 대조 결과 - 2026-10-19
| 시나리오 | AGENTS.md 대조 기준 | 논리 판정 | 런타임 자동 호출 |
|---|---|---|---|
| 1 | 신규 기능 흐름과 보안/API specialist 조건 | PASS | 미실행 |
| 2 | Requirements Discovery의 선택적 인터뷰와 설계 복귀 | PASS | 미실행 |
| 3 | Domain 용어/상태 및 glossary 소비/수정 구분 | PASS | 미실행 |
| 4 | 기존 dependency read-only 평가와 구조 어휘 | PASS | 미실행 |
| 5 | API 설계 main과 contract substage 책임 분리 | PASS | 미실행 |
| 6 | 단일 보안 review process와 criteria/checklist 한계 | PASS | 미실행 |
| 7 | 재현 가능한 실패의 원인 조사/TDD와 테스트 완화 금지 | PASS | 미실행 |
| 8 | 일반 조사와 explicit-only 스킬의 명시 선택 제한 | PASS | 미실행 |
| 9 | 기존 미완료 Task 재개와 중복 설계/인터뷰 금지 | PASS | 미실행 |
판정 방법: 부모 에이전트가 각 요청의 분류·주/보조 책임·순서·제외·승인 경계를 현재 루트 지침과 직접 대조했다.
`test`/`rg`로 9개 요청 원문과 8개 필드(총 72개)도 확인했다. PASS는 정책 논리의 일치만 뜻하며 실제 업무 실행이나 자동 호출 성공이 아니다.
모든 `조건부 자동 선택`은 모델이 실제로 자동 호출할 것이라는 보장이 아니다. Host가 skill을 발견하고 도구 권한이 허용될 때만 가능하다. 일반 언어상 grilling 요청은 stress-test 의도를 뜻할 수 있으며, skill 이름을 정확히 입력해야만 한다고 제한하지 않는다. 반대로 `improve-codebase-architecture`와 `setup-matt-pocock-skills`는 확인된 explicit-only metadata 때문에 일반 주제 언급만으로 선택하지 않는다. 9개 모든 관찰/검증은 PENDING이다.
@@ -1,107 +0,0 @@
# 엔지니어링 스킬 문서 설정 계획
| 항목 | 내용 |
|---|---|
| 상태 | 구현 완료 |
| 작성일 | 2026-10-19 |
| 요구사항 기준 | `docs/20261019_엔지니어링스킬설정/prd.md` |
| 현재 Phase | Phase 1: 승인 설정 반영 완료 |
| 현재 활성 Goal | 없음 |
## 목표
승인된 이슈 트래커 및 도메인 문서 설정을 저장소 안내 문서에 반영한다.
## 시작 조건
- 사용자가 설정 초안을 승인했다.
- 변경 대상과 제외 범위가 PRD에 확정되어 있다.
- 이 변경은 문서 전용이며 PRD와 계획 문서를 먼저 작성한다.
## 범위
- 포함: 승인된 `AGENTS.md` 안내 블록과 이슈 트래커·도메인 안내 문서 작성
- 제외: 런타임 파일, `.gitignore`, 스킬 설치·활성화, triage 설정, 추가 예시 문서 및 원격 작업
### Phase 1: 승인 설정 반영
**결과:** 승인된 로컬 이슈 트래커와 single-context 도메인 문서 지침을 정확한 위치에 기록한다.
#### Task 1.1: 선행 PRD 및 계획 문서 작성
**Goal ID:** `P1-T1`
- **목표:** 작업 범위, 승인 결정, 수용 기준과 검증 계획을 기록한다.
- **시작 조건:** 필수 작업 가이드와 샘플 문서를 읽는다.
- **정확한 파일:** `docs/20261019_엔지니어링스킬설정/prd.md`, `docs/20261019_엔지니어링스킬설정/plan-task.md`
- **완료 증거:** 두 문서가 존재하고 승인 범위와 검증 책임이 서로 일치한다.
- **범위 밖:** 설정 블록 및 안내 파일 작성.
- **TDD 예외 사유:** 요구사항·계획 문서 작성은 실행 동작을 변경하지 않는다.
- **대체 검증 방법:** 문서 파일과 경로를 읽어 내용 및 계획 형식을 확인한다.
- [x] **Task 1.1: 선행 PRD 및 계획 문서 작성**
#### Task 1.2: 승인된 설정 반영
**Goal ID:** `P1-T2`
- **목표:** 승인된 로컬 이슈 트래커와 도메인 문서 읽기 규칙을 반영한다.
- **시작 조건:** `P1-T1` 완료 및 사용자 초안 승인.
- **정확한 파일:** `AGENTS.md`, `docs/agents/issue-tracker.md`, `docs/agents/domain.md`
- **완료 증거:** 승인 초안과 파일 본문이 일치하고 기존 `AGENTS.md` 내용이 보존된다.
- **범위 밖:** 예시 이슈, 실제 용어집·ADR 생성, triage 설정, 원격 저장소 변경.
- **TDD 예외 사유:** 문서 전용 설정이며 애플리케이션 실행 동작을 변경하지 않는다.
- **대체 검증 방법:** 세 파일을 직접 읽고 승인 초안 및 `git diff -- AGENTS.md`와 대조한다.
- [x] **Task 1.2: 승인된 설정 반영**
#### Phase 1 Gate
**Goal ID:** `P1-GATE`
- **목표:** 다섯 파일이 승인 초안과 PRD 범위에 맞게 작성됐는지 검증한다.
- **시작 조건:** `P1-T1`, `P1-T2` 완료.
- **정확한 파일:** `AGENTS.md`, `docs/agents/issue-tracker.md`, `docs/agents/domain.md`, `docs/20261019_엔지니어링스킬설정/prd.md`, `docs/20261019_엔지니어링스킬설정/plan-task.md`
- **완료 증거:** 부모 실행자가 diff 공백 검사, 문서·참조 확인, Gradle task 목록 확인을 수행하고 결과를 기록한다.
- **범위 밖:** 전체 회귀 테스트 및 문서 외 파일 변경.
- **TDD 예외 사유:** 문서 전용 설정이라 자동화된 실패 테스트를 추가하지 않는다.
- **대체 검증 방법:** `git diff --check`, 변경 파일·문서 참조 대조, `./gradlew tasks --all` 실행 결과를 확인한다.
- **회귀 범위:** 전체 회귀는 문서 전용 변경에 필요하지 않다.
- [x] **Phase 1 Gate: 설정 및 문서 검증**
## 진행 기록
- `P1-T1`: 필수 선행 문서 작성 완료. 이 기록은 파일 생성 확인에 한하며 설정 검증은 뜻하지 않는다.
- `P1-GATE`: 부모 실행자 검증 대기. 미실행 검사는 완료로 기록하지 않는다.
### P1-T1 / P1-T2 검토 및 보정 - 2026-10-19
- 무엇을: 다섯 대상 파일을 읽고 승인 초안과 대조했다. 누락된 설정 반영 Task를 명시하고 초안 외 내부 주석을 제거했다.
- 왜: 실제 설정 작업의 추적성을 확보하고 승인된 문서 내용만 유지하기 위해서다.
- 어떻게: `git diff -- AGENTS.md`에서 기존 본문 변경 없이 안내 블록만 추가된 것을 확인했다.
- 결과: PRD·계획 경로와 안내 문서 참조가 일치하며 `P1-GATE` 최종 검증은 별도로 수행한다.
### P1-GATE 검증 - 2026-10-19
- 무엇을: 승인된 다섯 문서의 내용·참조·변경 범위와 Gradle 명령 유효성을 검증했다.
- 왜: 원격 저장소에 종속되지 않는 설정을 유지하고 기존 작업 절차에 영향을 주지 않는지 확인하기 위해서다.
- `git diff --check`: 종료 코드 0, 추적 파일 공백 오류 없음.
- 신규 네 파일에 각각 `git diff --no-index --check /dev/null "$file"`: 종료 코드 0, 공백 오류 없음.
- 신규 파일 검사 첫 시도는 zsh 특수 변수 `path`를 반복 변수로 사용해 `git` 탐색에 실패했다.
반복 변수를 `file`로 수정한 뒤 같은 검사에 통과했으며, 파일 내용이나 Git 설정은 변경하지 않았다.
- `test` 및 `rg` 검사: 종료 코드 0. 필수 파일 존재, `Agent skills` 블록 1개,
triage 설정·`CLAUDE.md`·빈 `.scratch/` 및 내부 주석 미생성을 확인했다.
- `git status --short --untracked-files=all`: 승인된 다섯 Markdown 파일만 변경·생성됐다.
- `git check-ignore -v --no-index .scratch/skill-setup/issues/01-example.md`: 종료 코드 1,
일치하는 ignore 규칙 없음. 실제 예시 파일은 만들지 않았다.
- `./gradlew tasks --all`: 종료 코드 0, `BUILD SUCCESSFUL`. 기존 Gradle 9.0 비호환 deprecated 기능 경고는 유지된다.
- Markdown 전용 변경으로 언어 서버 진단 대상 코드는 없으며, 별도 LSP 진단 도구는 제공되지 않았다.
- 전체 테스트·빌드는 실행하지 않았다. 실행 코드·의존성·빌드 설정 변경이 없어 위 문서 검사와 Gradle task 목록 확인으로 검증했다.
- 결과: `P1-T1`, `P1-T2`, `P1-GATE` 완료. 커밋·푸시 및 원격 설정 변경 없음.
### 별도 문서 검토 - 2026-10-19
- 최초 검토는 지원되지 않는 모델 오류로 실행되지 않아 사용 가능한 문서 검토 경로로 재시도했다.
- 재검토 결과: 중대한 지적 사항 없음. 승인 범위, 기존 `AGENTS.md` 보존, PRD·계획 규칙과의 일치를 확인했다.
- 검토자는 파일과 diff만 확인했으며 Gradle·공백 검사는 위 실행 결과를 기준으로 했다.
@@ -1,43 +0,0 @@
# 엔지니어링 스킬 문서 설정 PRD
## 문서 정보
| 항목 | 내용 |
|---|---|
| 상태 | 구현 완료 |
| 작성일 | 2026-10-19 |
| 최종 수정일 | 2026-10-19 |
| 대상 | 엔지니어링 스킬용 저장소 문서 설정 |
| 관련 계획 | `docs/20261019_엔지니어링스킬설정/plan-task.md` |
## 목표와 배경
원격 저장소 변경에 의존하지 않는 로컬 Markdown 이슈 관리 규칙과 single-context 도메인 문서 안내를 기록한다. 기존 `AGENTS.md`에 승인된 안내를 추가해 스킬이 저장소의 기준 문서를 찾을 수 있게 한다.
## 확정 요구사항
- 이슈 트래커는 `.scratch/<feature-slug>/issues/`의 로컬 Markdown으로 지정한다. 원격 저장소가 변경될 예정이므로 원격 이슈 트래커를 기준으로 삼지 않는다.
- 도메인 문서 구성은 single-context로 안내하며 루트 `GLOSSARY.md`와 `docs/adr/`를 참조한다.
- 루트 `AGENTS.md` 끝에 승인된 `Agent skills` 블록을 추가하고, `docs/agents/issue-tracker.md`와 `docs/agents/domain.md`에 규칙을 기록한다.
- 이 설정을 위한 PRD 및 계획 문서를 기존 날짜 디렉터리 규칙에 따라 함께 둔다.
## 수용 기준
- 승인된 설정 내용과 다섯 개의 정확한 대상 파일만 변경된다.
- 기존 `AGENTS.md` 내용은 바이트 단위로 보존되고 승인 블록만 추가된다.
- 요구사항 문서와 계획 문서의 경로, 파일 지침, 검증 계획이 서로 일치한다.
- 검증 미수행 항목을 성공으로 기록하지 않는다.
## 제외 범위
- 애플리케이션·런타임 코드, `.gitignore`, 의존성, 테스트 변경
- triage 라벨 및 triage 스킬 설정
- `GLOSSARY.md`, `GLOSSARY-MAP.md`, `docs/adr/`, `.scratch/`나 예시 이슈 생성
- 스킬 설치·활성화, 원격 서비스 사용, Git 변경
## 결정 기록
| 날짜 | 결정 | 근거 |
|---|---|---|
| 2026-10-19 | 이슈 관리는 로컬 Markdown으로 설정 | 원격 저장소 변경에 의존하지 않으며 사용자가 전체 초안을 승인함 |
| 2026-10-19 | 도메인 문서는 single-context로 안내 | 단일 루트 프로젝트이며 승인된 구성임 |
@@ -1,219 +0,0 @@
# 첫 충전 보너스 신규 지급 중단 구현 계획
| 문서 항목 | 내용 |
|---|---|
| 상태 | 구현 완료, 검증·독립 리뷰 통과, 미배포 |
| 작성일 | 2026-10-19 |
| 요구사항 기준 | [prd.md](prd.md) |
| 현재 Phase | Phase 1, 신규 생성 분기 변경 |
| 현재 활성 Goal | 없음 |
| 다음 Goal | 없음, 구현 범위 완료 |
| 작업 위치 | 현재 `test` 브랜치, 별도 worktree·브랜치 생성 없음 |
## 목표
신규 충전에서 첫 충전 보너스 작업만 만들지 않고, 기존 활성 이벤트 지급과 이미 저장된 모든 작업 계약을 보존한다.
## 현재 상태
| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
|---:|---|---:|---|---|
| 1 | 완료 | 1/1 | 없음 | 운영 배포는 별도 범위 |
사용자의 구현 승인을 받아 `P1-T1`과 독립 리뷰를 포함한 `P1-GATE`를 완료했다. 아래 문서 작성 단계의 미실행 기록은 당시 이력으로 유지한다.
## 범위
### 포함
- `ChargeEventJobService.buildSnapshot(charge, member)`에서 첫 충전 분기를 없애고 활성 이벤트 스냅샷 경로로 통일한다.
- 삭제된 분기 때문에 사용되지 않는 생성자 의존성, 함수, import와 상수를 해당 파일에서만 정리한다.
- 신규 생성 차단과 기존 활성 이벤트/저장 작업의 회귀 테스트를 추가 또는 보강한다.
### 제외
- 구매·결제 완료 경로, 유료 캔, 회원 정보 응답의 `chargeCount`, `isFirstCharged`, API, DB schema, 이벤트 enum과 기존 지급 처리 변경.
- `PENDING`/`FAILED`/`PROCESSING`/`DONE` 상태 정책, worker/admin 서비스, `publishPaidNotification`의 `FIRST_CHARGE` 분기 변경.
- `ChargeEventService.applyChargeEvent` 및 그 공유 메서드의 정리. 현재 live caller가 없지만 별도 레거시 경계다.
- migration, 과거 작업 수정/삭제/환수, feature flag, cutoff 값, dependency 추가, 별도 운영 실행.
## 구현 제약
- 기술 스택은 Kotlin, Spring Boot, JUnit 5이며 기존 서비스 패턴을 따른다.
- gateway 누락 예외 검증은 snapshot 선택보다 먼저 일어나도록 유지한다.
- 인증 여부/charge count를 조회해 첫 충전 자격을 판정하지 않는다. 매 충전에서 기존 활성 이벤트와 회원별 횟수 한도를 평가한다.
- `processJob(jobId)`는 저장 스냅샷으로 작업을 수행하므로 해당 경로와 retry/idempotency를 수정하지 않는다.
- 기존 `FIRST_CHARGE` 데이터는 배포 시점과 관계없이 보존하고 처리한다.
## Phase 1: 신규 생성 분기 변경
**Phase 결과:** 신규 `FIRST_CHARGE` 작업 생성은 중단되고 활성 이벤트 및 기존 저장 작업의 지급은 기존대로 동작한다.
**선행조건:** 별도의 구현 승인. 이 문서 작성은 구현 승인이 아니다.
**Phase 완료 조건:** `P1-T1` 완료, `P1-GATE` 통과 및 실제 결과 기록.
### 구현 항목
#### Task 1.1 신규 생성 차단과 회귀 보존
**Goal 실행 `P1-T1`**
**Objective:** 새 결제 완료 충전의 작업 스냅샷을 활성 이벤트로만 제한하면서 기존 이벤트·저장 작업의 계약을 테스트로 고정한다.
- **시작 조건:** PRD `STOP-001`~`STOP-004` 확정, 별도 구현 승인, 작업 트리에서 대상 파일 재확인.
- **완료 증거:** 모든 실행 체크박스 완료, focused test와 ktlint 결과, task Progress에 실제 명령/결과 기록.
- **범위 밖:** worker/admin 동작 수정, 결제 데이터 조작, 문서 밖 범위 확장.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/can/charge/event/ChargeEventJobService.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/can/charge/event/ChargeEventJobServiceTest.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/can/charge/event/ChargeEventJobWorkerTest.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/admin/event/charge/AdminChargeEventJobServiceTest.kt`
**Interfaces:**
- Consumes: `ChargeEventJobService.createProcessingJob(sourceChargeId: Long, memberId: Long): ChargeEventJob?`의 기존 gateway 검증, charge/member 조회, 멱등 키 조회 및 저장 계약.
- Produces: 외부 시그니처 변경 없음. `buildSnapshot(charge: Charge, member: Member): ChargeEventJob?`는 활성 이벤트 스냅샷 결과 또는 `null`만 반환한다.
- [x] **RED:** `ChargeEventJobServiceTest`에 인증 회원 첫 충전에서 신규 `FIRST_CHARGE`가 생기지 않으며, 인증 이력 조회를 하지 않고 활성 이벤트 스냅샷만 생기는 테스트를 추가한다. 15% 계산 대신 활성 이벤트 설정의 `addPercent`/제목/ID/횟수 제한으로 저장 내용을 검증한다.
- [x] **RED 확인:** 아래 focused test 명령을 실행해 새 회귀 assertion이 `FIRST_CHARGE` 분기 때문에 실패하는지 확인한다. 테스트 설정 오류나 fixture 오류는 RED로 인정하지 않는다.
- [x] **기존 동작 고정:** 활성 이벤트 테스트 픽스처로 `PG`, `PAYVERSE`, `APPLE_IAP`, `GOOGLE_IAP` 각각 gateway, container(`pg`/`ios`/`aos`), `additionalCan`, `methodSnapshot`, `ACTIVE_CHARGE_EVENT`와 event ID가 기존 규칙 그대로 저장되는지 확인한다. 프로세스 후 지급 알림의 제목/수신자/추가 캔 내용이 기존 규칙을 따르는지 검증한다. 기존 계약을 고정하는 테스트는 변경 전부터 통과해야 한다.
- [x] **RED:** 활성 이벤트 없음과 회원별 횟수 한도 소진에서 새 작업이 없고, 새로 첫 결제한 인증 회원도 일반 활성 이벤트를 적용받는 테스트를 추가한다.
- [x] **기존 동작 고정:** 과거 `FIRST_CHARGE` snapshot fixture로 활성 이벤트가 없어도 저장된 `PENDING`/`PROCESSING` 작업을 `processJob`가 저장 금액·gateway·container·method대로 한 번 처리하고 인증/자격 조회나 이벤트 조회를 다시 하지 않는지 확인한다. 네 gateway의 보너스 잔액과 첫 충전 알림을 검증하며, 별도 상태 자동 복구 동작은 기대하지 않는다.
- [x] **기존 동작 고정:** `FAILED`는 관리자 수동 retry가 `PENDING`으로 되돌린 뒤 worker에 처리되고, `DONE`은 재호출해도 재지급되지 않는 기존 동작을 검증한다.
- [x] **RED 확인:** `./gradlew test --tests '*ChargeEventJobServiceTest' --tests '*ChargeEventJobWorkerTest' --tests '*AdminChargeEventJobServiceTest'`를 실행한다. 신규 중단 assertion은 미구현 동작으로 실패하고, 저장된 작업/일반 이벤트 보존 테스트는 통과하는지 구분한다.
- [x] **GREEN:** `buildSnapshot`에서 gateway 선검증을 유지하고 `buildActiveEventSnapshot(charge, member, paymentGateway)`을 반환하도록 최소 변경한다. 미사용 `AuthRepository` 생성자 의존성/import, `buildFirstChargeSnapshot`, `ceil` import 및 더 이상 참조되지 않는 `FIRST_CHARGE_METHOD`만 제거한다.
- [x] **GREEN 확인:** 동일 focused test 명령으로 신규 차단 및 활성 이벤트/기존 작업 회귀가 통과하는지 확인한다.
- [x] **REFACTOR:** 이번 변경이 만든 중복만 정리한다. 서비스·worker·admin 테스트와 `./gradlew ktlintCheck`를 다시 실행하고 실제 결과를 Progress에 기록한다. 필요한 경우에만 테스트 fixture 중복을 정리한다.
**Task 검증 기록 (2026-10-19):** 원본 focused 11개 PASS 후 테스트를 추가했다. RED에서는 35개 중 신규 생성 assertion 9개만 실패하고 보존 테스트 26개는 통과했다. `AuthRepository`를 실제 주입한 fixture에 DI·충전 1건 stub을 설정해 기존 `FIRST_CHARGE`가 생성되는 실패를 확인했다. 최소 변경 후 서비스 25개·worker 6개·관리자 4개, 총 35개가 통과했다. 기존 테스트 삭제·완화는 없다. RED의 의존성 주입·stub은 production 의존성 제거에 맞춰 정리하되 결과 assertion은 유지했다.
#### 필수 테스트와 판정
| 테스트 이름 | 핵심 assertion |
|---|---|
| `shouldNotCreateFirstChargeJobForNewAuthenticatedCharge` | 첫 충전 대상 회원도 신규 `FIRST_CHARGE`를 만들지 않는다. 활성 이벤트가 없으면 저장 없이 `null`이다. |
| `shouldApplyActiveEventToNewChargeAcrossGateways` | 네 gateway에서 일반 이벤트의 ID·제목·비율·container를 사용한다. 예: 100캔, 일반 이벤트 10%라면 15캔이 아닌 10캔이다. |
| `shouldNotCreateJobWhenActiveEventLimitIsExhausted` | 일반 이벤트 한도가 소진되면 첫 충전 보너스로 우회하지 않고 저장 없이 `null`이다. |
| `shouldPayExistingFirstChargeSnapshotWithoutActiveEvent` | 기존 스냅샷 금액이 15이면 현재 이벤트/인증과 무관하게 15를 유지하고, 네 gateway의 해당 보너스 잔액·기록·첫 충전 알림을 검증한다. |
| `shouldProcessPendingFirstChargeJobAndSkipDoneJob` | worker의 기존 `PENDING` 처리와 `DONE` 재호출에서 지급 1회·잔액 불변을 검증한다. |
| `shouldRetryFailedFirstChargeJobWithoutChangingSnapshot` | 관리자 재시도 후 `PENDING`, retryCount 0, 원본 스냅샷 보존과 후속 지급을 검증한다. |
문서 작성의 **TDD 예외 사유:** 실행 코드 동작이 없는 문서 전용 작업이다. **대체 검증 방법:** PRD와 계획의 요구사항·파일·불변조건 대조, Markdown 참조 확인 및 `./gradlew tasks --all` 실행이다. 구현 Task `P1-T1`은 TDD 예외가 아니다.
### Phase 1 Gate
**Goal 실행 `P1-GATE`**
**Objective:** 첫 충전 신규 생성 차단과 기존 활성 이벤트/저장 작업 계약 보존을 자동 테스트 및 배포 경계 체크리스트로 판정한다.
- **시작 조건:** `P1-T1`의 모든 체크박스 완료, 해당 Progress 기록 존재.
- **완료 증거:** focused test 및 ktlint 통과, 아래 불변조건 확인, 미실행 배포 체크를 운영 검증 완료로 오인하지 않도록 기록.
- **범위 밖:** 운영 DB/결제/SQL 조작, 배포 실행, 테스트 삭제·완화, 새 복구 정책.
**Files:**
- Verify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/can/charge/event/ChargeEventJobService.kt`
- Verify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/can/charge/event/ChargeEventJob.kt`
- Verify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/can/charge/event/ChargeEventJobWorker.kt`
- Verify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/admin/event/charge/AdminChargeEventJobService.kt`
- [x] `./gradlew test --tests '*ChargeEventJobServiceTest' --tests '*ChargeEventJobWorkerTest' --tests '*AdminChargeEventJobServiceTest'` 통과 확인.
- [x] `./gradlew ktlintCheck` 통과 확인.
- [x] 코드 diff가 PRD 포함 파일과만 일치하며 enum, `processJob`, worker, admin service, 결제 API 변경이 없는지 확인.
- [x] 읽기 전용 배포 체크리스트에 cutoff 이후 신규 `FIRST_CHARGE` 부재 및 기존 snapshot 처리 지속을 남긴다. 이는 이 계획에서 실행하지 않는다.
- [x] 전체 회귀는 공통 경계/여러 domain 영향, targeted 결과로 영향 판단 불가, release/final 전체 증거 요구 또는 사용자 요청일 때 실행한다. 생략 시 근거와 focused 명령을 Progress에 기록한다.
## 실행 순서와 의존성
| 순서 | Goal | 선행조건 | 병행 가능 | 차단 시 다음 행동 |
|---:|---|---|---|---|
| 1 | `P1-T1` | 별도 구현 승인 | 아니요 | 승인이 없으면 문서 상태 유지 |
| 2 | `P1-GATE` | `P1-T1` 완료 | 아니요 | 실패 원인 소유 테스트/변경 확인 후 별도 회귀 goal 결정 |
```text
P1-T1 → P1-GATE
```
## 변경 금지 항목
- `ChargeEventJobType.FIRST_CHARGE`와 기존 저장 snapshot 처리 코드를 삭제하지 않는다.
- `publishPaidNotification`의 `FIRST_CHARGE` 처리, 지급 알림/현지화, retry, idempotency 또는 `DONE` 중복 방지를 바꾸지 않는다.
- 원본 충전, 광고/클라이언트 추적, 공개 API, DB, 구매 완료 경로를 바꾸지 않는다.
- `AuthRepository`/`ChargeRepository` 공유 메서드와 레거시 `ChargeEventService`를 삭제하지 않는다.
- cutoff 설정, migration, 운영용 SQL, 새 dependency와 관계없는 정리를 추가하지 않는다.
- RED 확인 전에 구현하지 않으며 테스트를 삭제/skip/완화하지 않는다.
## Progress
### 문서 작성 및 검증, 2026-10-19
- 상태: 문서 완료, 구현 미승인·미실행
- 무엇을: 사용자 확정 정책과 기술 범위로 PRD 및 실행 계획을 작성했다.
- 왜: 구현 전에 신규 생성 차단 범위와 기존 작업 보존 계약을 분명히 하기 위해서다.
- 어떻게:
- 가이드/샘플 및 소스·테스트 읽기 — 완료.
- `./gradlew tasks --all` — 문서 생성 후 실행, exit 0 / `BUILD SUCCESSFUL`. 계획에서 참조한 `test`, `ktlintCheck` task 등록 확인.
- 현재 `test` 브랜치 확인 및 Git 변경 범위 확인 — 신규 문서 디렉터리만 추가됐으며 소스·테스트·설정 변경 없음.
- 테스트/결제/운영 확인 — 이번 문서 작업에서는 미실행. 미래 구현 항목이며 코드 변경이나 지급 중단 효과가 발생하지 않았다.
- 남은 항목: `P1-T1` 별도 승인, 이후 `P1-GATE`.
- 다음 행동: 별도 승인 이후 `P1-T1`만 goal로 활성화한다.
## 문서 검증 기록
- [x] `./gradlew tasks --all` 실행으로 명령 유효성과 task 등록을 확인했다.
- Markdown LSP 진단은 `.md` 서버 미설정으로 불가했다. 문서 직접 읽기와 소스 대조로 보완하며, 서버를 설치하거나 설정을 바꾸지 않는다.
- 문서 전용 변경이므로 focused/전체 테스트와 ktlint를 재실행하지 않았다. 대신 문서 검토와 Gradle task 등록을 확인했다. 위 구현 체크박스는 모두 미실행 상태다.
- 앞선 동작 조사에서 관련 기존 테스트 11건이 통과했으나, 확인된 픽스처는 `ACTIVE_CHARGE_EVENT`다. 따라서 이는 신규 중단이나 `FIRST_CHARGE` 회귀 커버리지 증거가 아니며 별도 테스트가 필요하다.
### P1-T1 시작, 2026-10-19
- 사용자 승인: "승인 문서대로 구현 진행". 현재 `test` 브랜치에서 수행하며 worktree/브랜치를 생성하지 않는다.
- 사전 대조: `P1-T1`의 신규 생성 경로 변경과 `P1-GATE`의 기존 저장 작업 보존 검증은 일치한다. 공용 enum/worker/admin/원 결제 API는 변경하지 않는다.
- 기존 테스트 읽기: 일반 이벤트 지급/중복 방지/재시도를 다루며 첫 충전 신규 중단과 저장된 첫 충전 스냅샷의 회귀는 추가해야 한다.
- 승인된 범위 외 운영 DB/결제 호출/배포는 수행하지 않는다. 실제 서비스 메서드를 실행하는 격리 QA로 변경 동작을 검증한다.
### P1-T1 완료 및 P1-GATE 검증, 2026-10-19
- 운영 코드 변경은 `ChargeEventJobService.kt` 한 파일, 회귀 테스트는 기존 세 파일에 추가했다.
- 기준선: `./gradlew --no-daemon test --rerun --tests '*ChargeEventJobServiceTest' --tests '*ChargeEventJobWorkerTest' --tests '*AdminChargeEventJobServiceTest'` — 기존 11개 PASS.
- RED: 같은 focused 명령 — 35개 중 9개 의도한 실패. `expected ACTIVE_CHARGE_EVENT but was FIRST_CHARGE` 및 `expected null but was ChargeEventJob` 확인.
- GREEN/정리: `./gradlew --no-daemon test --tests '*ChargeEventJobServiceTest' --tests '*ChargeEventJobWorkerTest' --tests '*AdminChargeEventJobServiceTest' ktlintCheck` — 35개 PASS, ktlint PASS. 신규 테스트 줄바꿈 lint를 수정 후 재검증했다.
- 최종 실행: `./gradlew --no-daemon -I "$RUN_TMP/qa.init.gradle" firstBonusManualQa build ktlintCheck` — exit 0, `BUILD SUCCESSFUL in 9m 11s`. `build`가 전체 test를 실제 실행했고 322 suites / 2,291 tests / failures 0 / errors 0 / skipped 0이다.
- 빌드 산출물: `build/libs/sodalive-0.0.1-SNAPSHOT.jar`. 테스트 결과: `build/test-results/test/`, `build/reports/tests/test/index.html`.
- Kotlin LSP는 서버 미설치로 네 파일 모두 진단 불가다. 설치하지 않고 Gradle 컴파일·전체 테스트·ktlint로 보완했다. Markdown LSP도 미설정이다.
- `git diff --check` PASS. 소스 변경은 승인된 한 파일이며 enum/worker/admin/원본 결제와 `isFirstCharged`는 변경하지 않았다.
- 사용자 ULW 요청으로 전체 suite/build를 실행했다. 운영 DB/결제/푸시 호출 및 배포는 하지 않았다.
#### 독립 실행 QA 증거
임시 `BonusQa.java`와 Gradle init task가 JUnit 밖에서 실제 `createAndProcessImmediate`, `processJob`, `AdminChargeEventJobService.retry`, `ChargeEventJobWorker.runPendingJobs`를 호출했다. repository/트랜잭션/알림 전송 경계는 격리 fixture로 대체했다. 이는 실제 서비스 로직 실행 증거이며, DB 커밋·운영 결제·푸시 수신의 검증은 아니다.
| 시나리오 | 이진 판정 | 관찰 결과 |
|---|---|---|
| S1 신규 생성/일반 이벤트 | 활성 이벤트 없음은 작업·지급 0, 100캔·일반 이벤트 10%는 FIRST가 아닌 ACTIVE 10캔 한 번 | 네 gateway 모두 PASS |
| S2 한도/입력 경계 | 한도 소진은 작업 0, 결제 정보 누락은 기존 예외 | 네 gateway 모두 PASS |
| S3 저장된 첫 충전 | PENDING/PROCESSING의 저장 15캔을 정확한 지갑에 1회 지급, 원본 유료 잔액 유지, 기록·알림 일치 | 네 gateway 모두 PASS |
| S4 재시도/중복 | FAILED 관리자 재시도 후 worker 지급, DONE 재호출은 잔액·기록·알림 증가 없음 | 네 gateway 모두 PASS |
- 실행 출력: `QA PASS: 28 isolated real-service scenarios; no external payment, DB or push calls.`
- 임시 로그의 핵심 결과를 이 문서에 보존한다. QA 스크립트·init task·task 전용 캐시와 로그는 최종 리뷰 후 삭제하며 저장소에 추가하지 않는다.
#### 배포 후 별도 운영 체크리스트 (이번 실행 범위 밖)
- 모든 구버전 생성 인스턴스 drain 이후 새 `FIRST_CHARGE` 작업이 생기지 않는지 확인한다. 문서 작성일/구매 시작일을 cutoff로 사용하지 않는다.
- 이전에 생성된 `FIRST_CHARGE`의 저장 지급액·gateway·수신자·지급 기록을 대조하고 기존 재시도가 유지되는지 확인한다. 롤링 배포 중 구버전이 생성한 작업도 보존한다.
- `PROCESSING`에 새 자동 복구를 추가하지 않았고, `FAILED`는 기존 관리자 재시도가 필요하다.
### P1-GATE 최종 판정, 2026-10-19
- 상태: 완료. 별도 구현자의 결과를 부모 세션에서 직접 읽고 실행 검증한 뒤 독립 리뷰를 수행했다.
- 독립 리뷰: `APPROVED`, spec compliance와 코드 품질 모두 차단 결함 없음. S1~S4, 변경 diff, 저장 작업 enum/지급/알림/worker/admin 계약 및 RED/GREEN·전체 XML·QA 로그를 대조했다.
- 검증 수치: focused 35개 PASS, 전체 2,291개 PASS, 실패·오류·skip 0, build·ktlint PASS, Java 드라이버 28개 시나리오 PASS.
- 원본 결제/API/광고 추적·공용 enum/레거시 서비스 변경 없음. 배포 또는 데이터 migration을 수행하지 않았다.
- 사전 판단: 추가 SDD 작업 디렉터리 대신 이 계획의 Progress에 결과를 누적하고 현재 `test` 브랜치를 유지했다. 제품 정책의 추가 변경은 없다.
- 문서 최종 확인: `./gradlew --no-daemon tasks --all` 성공. Markdown/Kotlin LSP 미설정·미설치 한계는 그대로 명시한다.
- 임시 QA 자원은 task 소유 경로에만 생성했다. 검증·리뷰 결과를 이 문서에 남겼으며 최종 커밋 후 스크립트/init task/로그/캐시/메모를 제거하고 부재를 확인한다. 기존 공유 Gradle 캐시와 다른 작업의 프로세스는 건드리지 않는다.
- 남은 운영 확인: 실제 DB 커밋·다중 인스턴스 부하·PG/스토어 결제·푸시 수신 및 배포 후 신규 생성 중단은 이번 검증에 포함하지 않았다. 위 배포 체크리스트에 따라 별도로 확인한다.
@@ -1,81 +0,0 @@
# 첫 충전 보너스 신규 지급 중단 PRD
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | 구현·검증·독립 리뷰 완료, 미배포 |
| 작성일 | 2026-10-19 |
| 최종 수정일 | 2026-10-19 |
| 대상 제품 | 충전 이벤트 보너스 지급 |
| 작성자·결정권자 | 사용자 요청 |
| 관련 구현 계획 | [plan-task.md](plan-task.md) |
| 관련 review | [plan-task.md 최종 Gate 기록](plan-task.md#p1-gate-최종-판정-2026-10-19) |
## 1. 개요와 문제
변경 전에는 결제 완료 뒤 `ChargeEventJobService`가 인증 회원의 첫 충전을 판정해 원본 충전량의 15%를 올림 계산한 `FIRST_CHARGE` 작업을 만들었다. 이번 변경은 첫 충전 보너스 신규 생성을 중단하되, 이미 저장된 작업과 일반 활성 충전 이벤트의 지급 계약을 유지한다.
사용자 확인 정책: 기존 지급은 정상 동작 중이며, “이미 생성된 것은 기존대로 지급한다.” 이 문서는 정책과 구현 범위를 기록할 뿐이며, 문서 변경 자체는 실제 지급을 중단하지 않는다.
## 2. 목표와 제외 범위
### 목표
- 이후 코드가 만드는 새 보너스 작업은 기존 `ACTIVE_CHARGE_EVENT` 조건을 만족할 때만 생성한다.
- 신규 `FIRST_CHARGE` 작업을 만들지 않는다.
- 저장된 작업은 현재 worker와 관리자의 기존 계약대로 처리한다.
- 현재 `test` 브랜치에서 작업하며 별도 worktree나 브랜치를 생성하지 않는다. 문서 작성 후 사용자 승인에 따라 아래 범위만 구현한다.
### 제외
- 원본 유료 충전, 회원 정보 응답의 `chargeCount`, `isFirstCharged` 광고 추적, 클라이언트 API 변경.
- `FIRST_CHARGE` enum, 기존 작업 스냅샷, 지급·알림·현지화·재시도·멱등성 처리 제거 또는 변경.
- 과거 작업·보너스 데이터 수정/삭제, clawback, DB migration, feature flag, cutoff-date 설정.
- 새 의존성, 광범위한 정리, 사용처가 없는 레거시 서비스 제거.
## 3. 확정 요구사항과 수용 기준
| ID | 상태 | 요구사항 | 수용 기준 |
|---|---|---|---|
| STOP-001 | 확정 | 새 `FIRST_CHARGE` 작업을 생성하지 않는다. | 각 결제 게이트웨이의 검증을 통과한 신규 충전에서 생성되는 작업이 없거나 `ACTIVE_CHARGE_EVENT`뿐이다. 15% 계산 및 첫 충전 사유 스냅샷을 신규 생성 경로에서 사용하지 않는다. |
| STOP-002 | 확정 | 일반 활성 이벤트를 기존 기준으로 유지한다. | 인증 회원의 첫 결제도 같은 `buildActiveEventSnapshot` 경로를 따른다. 활성 이벤트 부재 또는 회원별 횟수 한도 소진이면 작업을 만들지 않는다. 결제 및 일반 충전 처리는 성공한다. |
| STOP-003 | 확정 | 이미 생성된 작업을 기존대로 처리한다. | 저장된 `PENDING`은 worker 대상이다. `FAILED`는 관리자 재시도 후 worker 대상이다. `PROCESSING`에는 자동 복구를 새로 추가하지 않는다. `DONE`은 재지급하지 않는다. 처리 과정은 인증/이벤트 자격을 재계산하지 않고 저장된 gateway, container, amount, method snapshot을 사용한다. |
| STOP-004 | 확정 | 원본 충전 기록과 외부 계약을 보존한다. | 유료 충전, 회원 충전 이력/광고 추적, 공개 API에는 변경이 없다. |
## 4. 기술 범위와 보존 경계
변경 지점은 [`ChargeEventJobService.kt`](../../src/main/kotlin/kr/co/vividnext/sodalive/v2/can/charge/event/ChargeEventJobService.kt)의 `buildSnapshot(charge, member): ChargeEventJob?`이다. `buildActiveEventSnapshot`을 직접 반환하도록 하며, 결제 gateway 검증은 그 호출 전에 유지한다. 이후 인증회원 첫 결제 여부와 무관하게 활성 이벤트 조회 및 횟수 제한을 적용한다.
이 변경으로 더 이상 사용하지 않는 `AuthRepository` 생성자 의존성/import, `buildFirstChargeSnapshot`, `ceil` import를 제거한다. `FIRST_CHARGE_METHOD`는 이 파일에서만 참조되며 제거 대상이다. 단, `FIRST_CHARGE` enum과 `methodSnapshot`을 이용하는 기존 작업 처리 및 `publishPaidNotification` 분기는 보존한다.
[`ChargeEventJob.kt`](../../src/main/kotlin/kr/co/vividnext/sodalive/v2/can/charge/event/ChargeEventJob.kt), [`ChargeEventJobRepository.kt`](../../src/main/kotlin/kr/co/vividnext/sodalive/v2/can/charge/event/ChargeEventJobRepository.kt), [`ChargeEventJobWorker.kt`](../../src/main/kotlin/kr/co/vividnext/sodalive/v2/can/charge/event/ChargeEventJobWorker.kt), [`AdminChargeEventJobService.kt`](../../src/main/kotlin/kr/co/vividnext/sodalive/v2/admin/event/charge/AdminChargeEventJobService.kt)와 결제 완료 경로는 수정 대상이 아니다. `ChargeEventService.applyChargeEvent`에는 현재 호출자가 없지만 이를 포함한 레거시 서비스는 이 작업에서 제거하지 않는다. 레거시가 참조하는 `AuthRepository` 및 `ChargeRepository` 공용 메서드도 유지한다.
## 5. 배포와 운영 경계
- 적용 기준은 구매 시작일이나 별도 cutoff 설정이 아니라, 새 작업을 만들지 않도록 갱신된 코드가 실제 실행되는 시점이다.
- 구버전 인스턴스가 남아 있는 rolling 배포 중에는 `FIRST_CHARGE` 작업이 더 생길 수 있다. 모든 구버전 생성 인스턴스가 drain된 뒤에야 신규 생성 중단이 완결된다.
- 배포 시점/일정은 이 문서에서 정하지 않는다.
- 배포 후 운영 확인 항목은 cutoff 이후 신규 `FIRST_CHARGE` 작업 부재와 기존 스냅샷 작업의 정상 지속 처리다. 이는 향후 확인 체크리스트이며, 실행된 운영 검증이 아니다.
## 6. 추적과 의사결정
| 요구사항 | 계획 Goal | 검증 |
|---|---|---|
| STOP-001, STOP-002 | `P1-T1` | `ChargeEventJobServiceTest` 신규 생성/활성 이벤트 회귀 |
| STOP-003, STOP-004 | `P1-T1`, `P1-GATE` | worker/admin 회귀, 충전 불변조건 테스트 |
| 날짜 | ID | 상태 | 결정 |
|---|---|---|---|
| 2026-10-19 | DEC-001 | 확정, 사용자 정책 | 첫 충전 보너스 신규 지급 중단, 생성된 작업은 기존대로 지급한다. |
| 2026-10-19 | DEC-002 | 기술 접근 | 신규 스냅샷 선택을 `buildActiveEventSnapshot`으로 단순화하고 기존 저장 작업 처리 경로는 유지한다. |
| 2026-10-19 | DEC-003 | 확정, 사용자 작업 조건 | worktree를 사용하지 않고 현재 `test` 브랜치에서 문서만 작성한다. |
| 2026-10-19 | DEC-004 | 정정, 사용자 구현 승인 | 문서대로 구현 진행 승인. `test` 브랜치/worktree 미사용 조건은 유지하며 신규 생성 분기와 관련 테스트만 변경한다. |
## 7. 성공 기준
- [x] 신규 작업 생성 테스트에서 `FIRST_CHARGE`가 생성되지 않는다.
- [x] 활성 이벤트가 있으면 신규 일반 이벤트 스냅샷만 생성되고, 이벤트 부재/한도 소진이면 작업 없이 종료한다.
- [x] PG, PAYVERSE, APPLE_IAP, GOOGLE_IAP의 기존 활성 이벤트 snapshot과 잔액/알림 계약이 유지된다.
- [x] 저장된 첫 충전 `PENDING`/`PROCESSING` 작업은 현재 방식대로 한 번 처리되고, `FAILED` 수동 재시도와 `DONE` 중복 방지가 유지된다.
- [x] 사용자 승인 이후 구현하고 focused 35개·전체 2,291개 테스트, build·ktlint와 격리 실행 QA 28개 시나리오를 통과했다. 운영 배포·실지급 확인은 별도다.
@@ -1,3 +0,0 @@
ALTER TABLE content_banner
ADD COLUMN start_date TIMESTAMP NULL DEFAULT NULL COMMENT '배너 노출 시작 시각 (UTC, NULL이면 시작 제한 없음)',
ADD COLUMN end_date TIMESTAMP NULL DEFAULT NULL COMMENT '배너 노출 종료 시각 (UTC, NULL이면 종료 제한 없음)';
@@ -1,299 +0,0 @@
# 오디오 콘텐츠 배너 예약 기간 구현 계획
| 문서 항목 | 내용 |
|---|---|
| 상태 | 구현 완료 |
| 작성일 | 2026-10-27 |
| 요구사항 기준 | `docs/20261027_콘텐츠배너예약기간/prd.md` |
| API 기준 | 관리자 예약 필드 추가, 기존 공개 API 응답 schema 유지 |
| 현재 Phase | Phase 1: 예약 저장과 노출 판정 |
| 현재 활성 Goal | 없음 (`P1-GATE` 완료) |
## 목표
관리자는 오디오 콘텐츠 배너 예약 기간을 저장·관리하고, 네 공개 오디오 배너 조회는 현재 시각에 노출 가능한 항목만 기존 조건과 순서로 반환한다.
## 현재 상태
| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 조건 |
|---:|---|---:|---|---|
| 1 | 완료 | `2/2` | 없음 (`P1-GATE` 완료) | 없음 |
- 동시에 하나의 미완료 goal만 실행한다. 순서: `P1-T1` → `P1-T2` → `P1-GATE`.
- 완료 체크박스와 검증 기록은 구현 때 실제 결과로 갱신하며, 이 계획 작성 시 검증을 실행한 것으로 간주하지 않는다.
## 범위
### 포함
- `content_banner` 예약 시각 nullable 필드와 MySQL DDL, 관리자 입력·응답, 값 검증 및 부분 수정 semantics.
- 네 공개 조회의 기간 필터 및 focused repository/service 테스트.
- DDL 선행 적용을 포함한 rollout 순서 문서화.
### 제외
- 오디오 이외 banner, scheduler, 공개 response 변경, security·권한 변경, 새 dependency, 전역 시간 설정 변경.
- live DB 실행 또는 기존 레코드 backfill.
## 기술 제약 및 구현 결정
- Kotlin/Spring/JPA/QueryDSL 기존 구조를 유지한다. 신규 architecture/dependency는 추가하지 않는다. 네 조회가 재사용하는 작은 기간 predicate는 허용한다.
- 필드는 `startDate`, `endDate`, 컬럼은 `start_date`, `end_date`, 각각 `TIMESTAMP NULL DEFAULT NULL` 초 정밀도다. 모든 컬럼에 한국어 COMMENT를 기록한다.
- 기존 관리자 이벤트 입력 관례의 KST `yyyy-MM-dd HH:mm` 문자열을 사용한다. UTC 저장 및 KST 동일 포맷 응답을 적용하고, 종료는 해당 입력 분의 `:59`로 정규화한다.
- update는 기존 `UpdateContentBannerRequest` DTO를 유지하면서 raw JSON에서 필드 존재 여부를 확인해 생략은 유지, 명시 null은 clear 처리한다. 역전 범위와 형식 검증은 이미지 upload 전에 수행하고 `common.error.invalid_request`를 사용한다.
- 공개 조회 조건은 NULL 경계의 inclusive 규칙을 따르며 `.limit()`보다 앞선 DB `.where()`에 포함한다. 기존 모든 필터·정렬을 보존한다.
- DDL migration이 애플리케이션 rollout보다 먼저다. DB 작업은 운영 자동화에 연결하지 않고 별도 승인된 절차로 실행한다.
- 구현 테스트는 JUnit 5 TDD. 공개 banner port에는 now 인자가 없으므로, 기존 nowProvider 기본 인자 관례를 참고해 해당 query 경계의 최소 clock seam을 테스트에서 고정한다. 공개 조회의 UTC now는 초 단위로 비교한다. persistence 검증은 `TIMESTAMP(0)` 컬럼에 저장 후 `flush`/`clear`/재조회한다. 초 정밀도는 완화 비교하지 않는다.
- 이 host에는 `lsp_diagnostics`가 없어 Kotlin main/test 컴파일과 ktlint로 정적 검증을 대체한다. LSP 검증으로 보고하지 않는다.
- focused 명령은 아래 Gate에 기록한 여섯 테스트 클래스와 Progress의 실제 combined 명령을 기준으로 실행한다.
### Phase 1: 예약 저장과 노출 판정
**Phase 결과:** 관리자 설정에서 시작/종료 시각을 저장하고 공개 경로가 기간 경계에 맞는 배너만 반환한다.
**선행조건:** 없음. PRD 요구사항 SCH-001~007 확정.
### Task 1.1 관리자·저장·응답
**Goal 실행 `P1-T1`:** 예약 범위를 생성·조회·부분 수정할 수 있고 DB에 정확히 왕복 저장한다.
- **시작 조건:** PRD §7~8 확정, 기존 관리자 이벤트 날짜 입력 convention 확인.
- **완료 증거:** 모든 체크박스 완료, focused test 통과, DDL 파일 작성, DB 왕복 및 업로드 전 검증 결과 기록.
- **범위 밖:** 공개 조회 필터, 공개 응답 변경, 운영 DB 적용.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/banner/AudioContentBanner.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/admin/content/banner/CreateContentBannerRequest.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/admin/content/banner/UpdateContentBannerRequest.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/admin/content/banner/AdminContentBannerService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/admin/content/banner/GetAdminContentBannerResponse.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/admin/content/banner/AdminContentBannerRepository.kt`
- Create: `docs/20261027_콘텐츠배너예약기간/alter-content-banner-reservation.sql`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/admin/content/banner/AdminContentBannerServiceTest.kt`
- Create/Test: `src/test/kotlin/kr/co/vividnext/sodalive/admin/content/banner/AdminContentBannerControllerIntegrationTest.kt`
**Interfaces:**
- Consumes: 기존 `createAudioContentMainBanner(image, requestString)`, `updateAudioContentMainBanner(image, requestString)`, `getAudioContentMainBannerList(tabId)`와 `GetAdminContentBannerResponse` projection.
- Produces: entity `startDate/endDate: LocalDateTime?`; create/update 선택 필드 `startDate/endDate: String?`; update 생략/null 구분; admin response `startDate/endDate: String?`. 포맷 `yyyy-MM-dd HH:mm` KST.
- [x] **RED:** create 값 저장, update 생략 유지 및 explicit null clear, 포맷/역전 오류와 업로드 미호출을 검증하는 focused test를 작성한다.
- [x] **RED 확인:** `./gradlew test --tests '*AdminContentBannerControllerIntegrationTest'`로 미구현 동작의 HTTP/assertion 실패를 확인한다. 기존 mock 서비스 테스트는 회귀 확인으로 유지한다.
- [x] **GREEN:** nullable entity 컬럼, 선택적 create 필드, 최소 raw JSON presence 판독, KST/UTC parsing·formatting, effective 범위 검증, 응답 projection을 구현하고 DDL을 추가한다.
- [x] **GREEN 확인:** 같은 focused test를 통과시킨다. persistence 테스트는 고정 시각으로 저장 후 `flush`/`clear`/재조회해 두 경계가 초 단위로 왕복하는지 검증한다.
- [x] **REFACTOR:** 이번 Task가 만든 중복만 정리하고 관리자 test 및 `./gradlew ktlintCheck`를 실행한다. DDL의 nullable default/comment와 PRD 일치 여부를 확인한다.
#### Task 1.1 회귀 수정: 예약 JSON 타입 오류 (`P1-T1-R1`)
- **Objective:** 예약 값이 문자열/null이 아닌 JSON 객체·배열이어도 업로드·저장 전에 `common.error.invalid_request`로 거부한다.
- **시작 조건:** P1-T1 리뷰에서 DTO 역직렬화가 예약 검증보다 먼저 실패해 `common.error.unknown`이 되는 경로 확인.
- **Files:** `AdminContentBannerService.kt`, `AdminContentBannerControllerIntegrationTest.kt` (위 Task 1.1의 전체 경로와 동일).
- **완료 증거:** create/update × start/end × 객체/배열의 실제 HTTP RED/GREEN 및 기존 focused 회귀 통과, scoped 재검토.
- **범위 밖:** 다른 DTO 필드/전역 JSON 오류 처리 변경.
- [x] **RED:** 예약 객체·배열 입력의 HTTP 공통 오류 계약 실패를 확인한다.
- [x] **GREEN:** 해당 예약 필드의 타입 검증만 최소 보강해 같은 테스트를 통과시킨다.
- [x] **REFACTOR:** `./gradlew test --tests '*AdminContentBannerControllerIntegrationTest' --tests '*AdminContentBannerServiceTest' --tests '*AudioContentBannerRepositoryTest' --console=plain` 및 ktlint 결과를 누적한다.
### Task 1.2 공개 조회 기간 필터
**Goal 실행 `P1-T2`:** 공개 네 조회가 현재 시각의 예약 가능 여부를 DB에서 limit 전에 판정한다.
- **시작 조건:** `P1-T1` 완료, entity QueryDSL metamodel 재생성 또는 빌드 convention 반영.
- **완료 증거:** 네 경로 각각의 경계·무기한·조건 보존 테스트, focused test 통과.
- **범위 밖:** 관리자 목록 예약 필터, 공개 응답 schema 또는 기존 필터/정렬 변경.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/banner/AudioContentBannerRepository.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/AudioContentRepository.kt` (`AudioContentQueryRepositoryImpl.getAudioContentMainBannerList(isAdult)`)
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepository.kt`
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/banner/AudioContentBannerVisibility.kt` (네 query의 NULL 허용 기간 조건과 초 정밀도 비교를 공유하는 작은 QueryDSL 함수)
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/content/main/banner/AudioContentBannerRepositoryTest.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepositoryTest.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepositoryTest.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/content/AudioContentRepositoryBannerTest.kt` (해당 query method에 대한 신규 통합 테스트)
- Create/Test fixture: `src/test/kotlin/kr/co/vividnext/sodalive/content/main/banner/AudioContentBannerReservationFixtures.kt` (네 JPA 테스트가 같은 고정 UTC 예약 경계 matrix만 공유하며 기존 fixture/flush·clear를 재사용)
**Interfaces:**
- Consumes: `AudioContentBanner.startDate/endDate` UTC 저장 값; 구형 `AudioContentQueryRepositoryImpl.getAudioContentMainBannerList(isAdult)`와 `AudioContentBannerQueryRepositoryImpl.getAudioContentMainBannerList(tabId, isAdult, lang)`에 해당 query 경계의 테스트 가능한 now seam, v2의 `findHomeBanners(limit, memberId, includeAdultBanners, lang)`와 `findBanners(limit, memberId, canViewAdultContent, lang)`도 같은 고정 시각 seam. 공개 API signature는 유지.
- Produces: 기존 공개 method signature와 반환 타입 유지. 예약 기간 필터는 공개 조회 결과에만 적용.
- [x] **RED:** 네 경로에서 양쪽 NULL, 시작만/종료만, inclusive 경계, 기간 밖 배너 및 limit 전에 걸러짐을 테스트한다. 기존 성인/언어/탭/active/target 조건과 정렬 유지 사례를 포함한다.
- [x] **RED 확인:** 네 repository 클래스의 신규 예약 테스트를 combined `./gradlew test --tests '*AudioContentBannerRepositoryTest.shouldExcludeFutureAndExpiredReservations' --tests '*AudioContentRepositoryBannerTest.shouldExcludeFutureAndExpiredReservations' --tests '*DefaultHomeRecommendationQueryRepositoryTest.shouldExcludeFutureAndExpiredReservationsBeforeLimit' --tests '*DefaultAudioRecommendationQueryRepositoryTest.shouldExcludeFutureAndExpiredReservationsBeforeLimit' --console=plain`로 실행해 예약 조건 assertion 실패를 확인한다.
- [x] **GREEN:** 각 기존 QueryDSL query의 `.where(...)`에 현재 시각 기준 nullable inclusive 조건을 추가한다. 별도 조회 후 메모리 필터링은 하지 않는다.
- [x] **GREEN 확인:** 각 focused test를 통과시킨다. 시각은 고정된 UTC now를 사용하고 시작·종료 동등 경계를 포함한다.
- [x] **REFACTOR:** 기존 where 조건·정렬·limit 순서와 공개 response 변화를 확인하고 네 focused test 및 `./gradlew ktlintCheck`를 다시 실행한다.
### Phase 1 Gate
**Goal 실행 `P1-GATE`:** 관리자 설정, DB migration 및 공개 조회 전체 계약이 맞는지 판정한다.
- **시작 조건:** `P1-T1`, `P1-T2` 완료.
- **완료 증거:** 아래 focused 테스트 통과, DDL과 rollout 순서 검토, 문서/변경 범위 확인 결과 기록.
- **범위 밖:** 전체 build/test 실행, 운영 DB 변경, 구현 범위 외 수정.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.admin.content.banner.AdminContentBannerServiceTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.admin.content.banner.AdminContentBannerControllerIntegrationTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.content.main.banner.AudioContentBannerRepositoryTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.content.AudioContentRepositoryBannerTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.recommendation.adapter.out.persistence.DefaultHomeRecommendationQueryRepositoryTest'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.content.recommendation.adapter.out.persistence.DefaultAudioRecommendationQueryRepositoryTest'
./gradlew ktlintCheck
```
**Expected:** 모든 명령 exit code 0. 공개 네 경로가 예약으로 선필터링되고 기존 조건/정렬 및 response schema가 보존된다. 관리자 목록에서 예약과 무관하게 기존 isActive/tab 조건으로 행이 조회된다. DDL은 nullable NULL 기본값이며 앱 rollout 전 적용이 필요하고 live DB 자동 실행은 없다.
- [x] **자동 검증:** focused 테스트 재실행, Kotlin 컴파일, ktlint 및 `bootJar` 패키징이 통과한다.
- [x] **계약 대조:** NULL 경계 네 조합, 관리자 예약 무관 조회, 네 공개 query의 limit 전 조건과 기존 필터 보존을 확인한다.
- [x] **리뷰:** P1-T2와 전체 변경 통합 검토에서 미해결 blocking finding이 없다.
- [x] **배포/문서:** DDL 선행 적용과 미검증 운영 환경 경계를 명시하고 PRD·계획·리뷰 상태를 갱신한다.
## 실행 순서
| 순서 | Goal | 선행조건 | 차단 시 행동 |
|---:|---|---|---|
| 1 | `P1-T1` | 없음 | PRD/기존 convention의 불일치만 문서화하고 임의 계약 금지 |
| 2 | `P1-T2` | `P1-T1` | 기존 query 조건을 유지하며 공개 경로 단위로 계속 검증 |
| 3 | `P1-GATE` | Task 1.1, 1.2 전체 | 실패 소유 Task에 회귀 검증 추가 |
```text
P1-T1 → P1-T2 → P1-GATE
```
## 변경 금지 항목
- 예약 기간으로 관리자 목록을 필터링하지 않는다. 기존 `isActive` 및 tab 조건은 그대로 유지한다.
- 공개 response schema, 권한, security, 다른 banner 유형은 변경하지 않는다.
- 실패 테스트를 삭제·skip·완화하지 않는다. 새 dependency·scheduler·전역 시간대 설정을 추가하지 않는다.
- 운영 DB에 DDL을 자동 실행하지 않는다. migration 적용은 애플리케이션 rollout보다 먼저다.
## Progress
### 구현 전 확인 — 2026-10-27
- 변경 전 working tree는 clean이고 현재 branch는 `test`다. 저장소 규칙에 따라 worktree를 자동 생성하지 않고 현재 작업 공간에서 진행한다.
- `./gradlew tasks --all test --tests '*AdminContentBannerServiceTest' --tests '*AudioContentBannerRepositoryTest' --console=plain` — exit 0, 기존 관리자/배너 테스트와 명령 유효성 확인.
- `./gradlew test --tests '*DefaultHomeRecommendationQueryRepositoryTest' --tests '*DefaultAudioRecommendationQueryRepositoryTest' --console=plain` — exit 0, 기존 v2 repository 회귀 baseline 확인.
- `./gradlew ktlintCheck --console=plain` — exit 0, 변경 전 포맷 baseline 확인.
- 사전 대조: P1-T1은 nullable UTC entity와 관리자 필드를 제공하고 P1-T2는 같은 필드를 소비하므로 순차 실행한다. P1-T1의 HTTP 테스트와 DB 왕복, P1-T2의 고정 now/limit 전 필터가 각 요구사항과 일치한다.
- 계획 초안의 `startAt/endAt` 및 `start_at/end_at`은 구현 전에 사용자 명명 `startDate/endDate`, `start_date/end_date`로 보정했다. 제품 동작 변경은 없다.
### P1-T1 실행 증거 — 2026-10-27
**TDD 실행 이력**
| 순서 | 명령/대상 | 실제 결과 및 판정 |
|---|---|---|
| RED 1 | `./gradlew test --tests '*AdminContentBannerControllerIntegrationTest' --console=plain` | exit 1, 6건 중 6건 실패, errors 0. 정상 multipart 생성과 GET 목록 요청 후 `Admin HTTP response must include startDate ==> expected: <true> but was: <false>` assertion으로 실패. 미구현 entity 참조나 없는 JDBC 컬럼에 의한 실패가 아니다. |
| GREEN 1 | 위와 같은 focused 명령 | exit 0, `BUILD SUCCESSFUL in 1m 59s`, 생성·목록 6건 통과. nullable 저장·KST 응답 projection 구현 후 H2 컬럼을 `TIMESTAMP(0)`으로 맞추고 고정 기대 UTC 값과 실제 재조회 값을 정확히 비교했다. |
| 테스트 작성 중 보정 | `compileTestKotlin` | multipart builder의 `.with(...)` 반환 타입이 `MockHttpServletRequestBuilder`인데 helper에서 더 좁은 타입을 선언해 3곳 컴파일 오류가 발생했다. 테스트 helper의 타입만 바로잡았으며 이 실패는 유효 RED에 포함하지 않는다. Redis/DB 설정 변경이나 production 우회는 없었다. |
| RED 2 | 위와 같은 focused 명령 | exit 1, 60건 중 52건 실패. 수정 null 해제·새 경계 적용의 HTTP 날짜 assertion 실패, 역전/잘못된 수정의 `$.success` expected false/actual true, 잘못된 생성 날짜가 `SodaException`이 아닌 예외로 처리되는 assertion 실패를 확인했다. |
| GREEN 2 | 아래 최종 focused 명령과 동일 | exit 0, `BUILD SUCCESSFUL in 37s`, 통합 60건 + 기존 서비스 1건 + 공개 repository 1건 = 62건 통과. raw `JsonNode.has` 병합과 파싱 오류 변환, 업로드 전 effective 범위 검증을 구현했다. |
| RED 3 | 통합 focused 명령 | exit 1, 64건 중 3건 실패. strict `uuuu` parser도 `+02026-10-27 10:00`을 허용해 잘못된 형식의 create start/end 및 update start에서 `$.success`가 true였다. 계약의 16자리 형식 검증을 추가하기 전에 확인한 별도 RED다. |
| 최종 GREEN | 아래 최종 focused 명령 | exit 0, `BUILD SUCCESSFUL in 37s`, 66건 통과. XML 보고서의 failures/errors/skipped는 모두 0이다. |
```bash
./gradlew test --tests '*AdminContentBannerControllerIntegrationTest' --tests '*AdminContentBannerServiceTest' --tests '*AudioContentBannerRepositoryTest' --console=plain
```
**최종 테스트 집계 및 실제 검증 범위**
| 테스트 클래스 | tests | failures | errors | skipped |
|---|---:|---:|---:|---:|
| `AdminContentBannerControllerIntegrationTest` | 64 | 0 | 0 | 0 |
| `AdminContentBannerServiceTest` | 1 | 0 | 0 | 0 |
| `AudioContentBannerRepositoryTest` | 1 | 0 | 0 | 0 |
| 합계 | 66 | 0 | 0 | 0 |
- 새 `@SpringBootTest`는 실제 controller/service/repository와 MockMvc multipart POST/PUT 및 GET을 사용하고 S3 외부 업로드만 mock한다. 기존 `EmbeddedRedisInitializer`를 해당 클래스에만 opt-in하고, 전용 H2 DB와 매 테스트 배너/탭 정리를 사용한다. 기존 서비스·공개 repository 테스트 파일은 수정하지 않았다.
- 생성 6건은 양쪽 생략/명시 null/시작만/종료만/양쪽/같은 분을 포함한다. 수정 9건은 생략 보존, 각 경계·양쪽 null 해제, 단일 경계 변경, 같은 분 및 다른 경계 해제를 반영한 병합을 검증한다. 미래·만료·무기한 예약은 관리자 목록에서 계속 보이고 기존 active/tab 조건은 보존된다.
- 형식/달력 오류는 11개 입력 × start/end × create/update = 44건이다. 생성 역전 1건 및 기존 값과 병합한 수정 역전 3건도 검증한다. 실패마다 `SodaException.messageKey == common.error.invalid_request`, S3 미호출, 생성 행 0개 또는 수정 전후 전체 DB row 완전 일치를 확인했다.
- persistence는 HTTP 서비스 트랜잭션 완료 후 별도 트랜잭션에서 `flush`/`clear`/재조회했다. H2 `start_date/end_date`는 명시적 `TIMESTAMP(0)`이다. `2026-10-27 00:00` KST의 전날 UTC 변환, `23:59` 입력의 종료 `:59`, 나노초 0, 목록의 KST 문자열/실제 JSON null을 허용오차나 절삭 비교 없이 확인했다.
- production 변경은 계획된 entity/관리자 DTO·service·repository 6파일에 한정했다. QueryDSL 보조 생성자에서 UTC를 KST 문자열로 변환해 기존 data class와 응답 필드를 유지하며 global serializer/timezone/dependency/security와 공개 query/response는 변경하지 않았다.
**DDL 및 검증 경계**
- `alter-content-banner-reservation.sql`은 MySQL `start_date/end_date TIMESTAMP NULL DEFAULT NULL`과 각 컬럼의 한국어 COMMENT만 추가한다. 기존 행은 NULL 유지, backfill 없음이며 파일 검토만 했다. 운영 적용은 별도 승인 절차로 DDL을 먼저 적용한 뒤 앱을 rollout해야 한다.
- 실제 MySQL DDL 실행, 운영 JDBC/session timezone과 MySQL TIMESTAMP 허용 범위에 대한 왕복 검증은 수행하지 않았다. H2 초 정밀도 및 Java KST/UTC 변환 검증을 운영 MySQL 검증으로 간주하지 않는다.
- `P1-T1`만 완료했다. `P1-T2` 공개 예약 필터와 `P1-GATE`는 미실행·미완료이며 해당 체크박스를 변경하지 않았다.
### P1-T1-R1 실행 증거 — 2026-10-27
- RED: 기존 잘못된 날짜의 parameterized HTTP 테스트에 객체 `{}`/배열 `[]` × `startDate/endDate` × create/update 8건만 추가했다. `./gradlew test --tests '*AdminContentBannerControllerIntegrationTest' --console=plain` — exit 1, `BUILD FAILED in 27s`, 72건 중 신규 8건만 assertion 실패, 기존 64건 통과, errors/skipped 0. HTTP 실패 응답의 resolved exception이 `SodaException`이어야 한다는 assertion에서 실패했으며 실제 원인은 DTO 매핑의 `MismatchedInputException`이었다. 컴파일/설정 오류는 없었다.
- GREEN: create/update 모두 JSON 트리를 한 번 읽고 DTO 매핑 전에 두 예약 필드만 검사한다. 생략·JSON null·문자열을 허용하고 그 외 JSON 타입을 `common.error.invalid_request`로 거부한다. 같은 트리를 `treeToValue`와 update의 `has` 판독에 재사용했다. 다른 DTO 필드나 전역 handler는 변경하지 않았고 mapping 예외를 포괄 catch하지 않는다.
- 회귀 명령: `./gradlew test --tests '*AdminContentBannerControllerIntegrationTest' --tests '*AdminContentBannerServiceTest' --tests '*AudioContentBannerRepositoryTest' --console=plain` — exit 0, `BUILD SUCCESSFUL in 38s`. 실제 `:test`가 실행됐으며 통합 72건 + 기존 서비스 1건 + 공개 repository 1건 = 74건 통과했다. `build/test-results/test/TEST-*.xml`에서 failures/errors/skipped 모두 0임을 확인했다.
- 신규 8건은 실제 MockMvc multipart 요청으로 `SodaException.messageKey == common.error.invalid_request`, S3 미호출, 생성 행 0개 또는 수정 전후 전체 DB row 일치를 검증한다. 기존 64건으로 생략 보존·명시 null 해제·날짜 정밀도/시간대·관리자 목록 회귀도 재검증했다. S3 이외 mock은 추가하지 않았다.
- scoped 자체 재검토: production 변경은 `AdminContentBannerService.kt`의 예약 JSON 타입 경계뿐이다. 나머지 변경은 기존 통합 테스트의 공통 입력 source 확장과 이 R1 체크/증거이며 P1-T2·Gate 및 기존 완료 기록은 변경하지 않았다. 전체 test/build와 운영 MySQL은 이 회귀 목표의 검증 범위에서 제외했고 Kotlin main/test 컴파일을 focused 실행으로 확인했다.
- 정적 검사 및 문서 명령 확인: `./gradlew ktlintCheck tasks --all --console=plain` — exit 0, `BUILD SUCCESSFUL in 15s`. main/test ktlint 오류는 없었으며 기존 Gradle deprecation 안내만 남았다. LSP 도구는 제공되지 않아 Kotlin 컴파일/ktlint로 대체했다. R1의 RED/GREEN/REFACTOR만 완료 처리했다.
- parent 독립 검증: `./gradlew test --rerun --tests '*AdminContentBannerControllerIntegrationTest' --tests '*AdminContentBannerServiceTest' --tests '*AudioContentBannerRepositoryTest' --console=plain` — exit 0, `BUILD SUCCESSFUL in 36s`, 실제 test 재실행. XML의 72 + 1 + 1 = 74건, failures/errors/skipped 모두 0을 직접 확인했다.
- scoped 리뷰 및 재검토: 최초 예약 JSON 객체/배열 오류 경계 P2 1건을 R1로 보완했다. 재검토에서 finding ADDRESSED, 명세 준수/코드 품질 모두 APPROVE이며 신규 actionable finding은 없었다. P1-T1/R1 완료 후 P1-T2로 이동한다.
### P1-T2 실행 증거 — 2026-10-27
- 실행 순서: 네 조회의 미구현 필터 RED 확인 → 공유 predicate/기본 UTC nowProvider 및 고정 시각 matrix → 공개 4클래스/관리자 2클래스 회귀와 ktlint. 관리자 파일 및 기존 완료 증거는 변경하지 않는다.
- 최초 RED 명령: `./gradlew test --tests '*AudioContentBannerRepositoryTest.shouldExcludeFutureAndExpiredReservations' --tests '*AudioContentRepositoryBannerTest.shouldExcludeFutureAndExpiredReservations' --tests '*DefaultHomeRecommendationQueryRepositoryTest.shouldExcludeFutureAndExpiredReservationsBeforeLimit' --tests '*DefaultAudioRecommendationQueryRepositoryTest.shouldExcludeFutureAndExpiredReservationsBeforeLimit' --console=plain`.
- 최초 RED 결과: exit 1, `BUILD FAILED in 23s`, 4건 실행/4건 assertion 실패, errors/skipped 0. 기존 생성자를 사용하고 실제 UTC 현재 시각의 ±1년으로 저장 후 flush/clear했다. 두 구형 조회는 expected `[visible]`, actual `[future, expired, visible]`; 홈 v2는 expected `[visible-1, visible-2]`, actual `[future, expired]`; 오디오 v2는 같은 이름의 CDN URL expected/actual로 실패했다. 컴파일/없는 seam/설정 오류가 아닌 실제 H2 조회 결과의 실패다.
- 중복 축소 결정: 구현 전 Files에 test-only `AudioContentBannerReservationFixtures.kt`를 추가했다. 고정 UTC now·nullable 시작/종료·기대 노출 여부만 공유하며 production test 분기나 공통 테스트 프레임워크는 추가하지 않는다.
- 종료 초 RED 명령: `./gradlew test --tests '*AudioContentBannerRepositoryTest.should*Reservation*' --tests '*AudioContentRepositoryBannerTest.should*Reservation*' --tests '*DefaultHomeRecommendationQueryRepositoryTest.should*Reservation*' --tests '*DefaultAudioRecommendationQueryRepositoryTest.should*Reservation*' --console=plain`.
- 종료 초 RED 결과: 최초 nullable inclusive predicate와 선택적 UTC seam 추가 후, 초 절삭을 추가하기 전에 실행했다. exit 1, `BUILD FAILED in 1m 22s`, 68건 중 8건 실패, errors/skipped 0. 네 경로 모두 `end-second-123456789`/`end-second-999999999`에서 expected `[candidate]`(오디오 v2는 CDN URL), actual `[]`였다. 나머지 60건은 통과해 최초 필터 RED의 4건도 GREEN을 확인했다. `TIMESTAMP(0)` 저장/flush/clear/재조회 값은 정확히 일치했으며 실패 원인은 미정규화 now 비교였다. 이후 공통 helper 내부에서 now를 한 번만 `truncatedTo(ChronoUnit.SECONDS)` 처리한다.
- GREEN 구현: `AudioContentBannerVisibility.kt`의 `QAudioContentBanner.isVisibleAt(now)`가 `(startDate IS NULL OR startDate <= currentSecond) AND (endDate IS NULL OR endDate >= currentSecond)`를 반환한다. Files의 네 query 구현에서 마지막 optional 생성자 인자 `nowProvider = { LocalDateTime.now(ZoneOffset.UTC) }`를 추가하고 해당 조회의 `.where(...)`에서 helper와 provider를 각각 한 번만 호출한다. 기존 positional 생성자 호출과 Spring 주입은 컴파일/통합 테스트로 확인했다. 기존 join/필터/order/limit/projection 및 port/method/response signature는 그대로다.
- 최종 고정 시각 검증: 공유 16-case matrix × 4경로 = 64건이다. 양쪽 NULL, 시작/종료 단독의 전·동등·후, 양쪽 범위 안·이전·이후·동등, `23:59:59.123456789`/`.999999999` 종료 초 포함, 다음 초 시작 전 제외, UTC 자정 시작 동등·전날 만료를 검증한다. H2 두 컬럼을 각 matrix에서 `TIMESTAMP(0)`로 맞춘 뒤 persist/flush/clear/재조회하여 원래 기대 시각과 정확히 비교한다. 최초 RED의 4건도 같은 기대 결과를 유지한 고정 UTC fixture로 전환했다.
- 기존 조건 회귀: v2의 미래/만료 두 선행 orders 행을 제외하고 `limit=2`를 정상 두 행이 채우는지 확인했다. 메인/구형에 탭·성인·활성·언어 적용 여부와 orders 정렬 보존 테스트 2건을 보강했다. 기존 홈 v2의 활성 대상·양방향 차단·언어·탭·성인·랜덤 tie-breaker/limit 테스트는 유지했고, 오디오 v2의 기존 배너 테스트에 비활성 creator 및 역방향 차단 대상도 추가했다. 실행 SQL에서도 네 경로의 괄호 묶인 nullable AND 조건과 v2의 order/limit 이전 where 적용을 확인했다.
- 첫 통합 GREEN: 아래 최종 명령에서 `ktlintCheck tasks --all`만 제외한 동일 6클래스 focused 명령 — exit 0, `BUILD SUCCESSFUL in 38s`, 237건 통과. 별도 `./gradlew ktlintCheck --console=plain`는 새 테스트의 긴 `saveBanner` 한 줄에서만 실패했다. `apply_patch`로 해당 호출의 인자 줄바꿈만 수정하고 전역 formatter는 실행하지 않았다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.content.main.banner.AudioContentBannerRepositoryTest' --tests 'kr.co.vividnext.sodalive.content.AudioContentRepositoryBannerTest' --tests 'kr.co.vividnext.sodalive.v2.recommendation.adapter.out.persistence.DefaultHomeRecommendationQueryRepositoryTest' --tests 'kr.co.vividnext.sodalive.v2.content.recommendation.adapter.out.persistence.DefaultAudioRecommendationQueryRepositoryTest' --tests 'kr.co.vividnext.sodalive.admin.content.banner.AdminContentBannerServiceTest' --tests 'kr.co.vividnext.sodalive.admin.content.banner.AdminContentBannerControllerIntegrationTest' ktlintCheck tasks --all --console=plain
```
- 최종 재검증: 위 명령 exit 0, `BUILD SUCCESSFUL in 37s`, 실제 `:test` 재실행 및 main/test/script ktlint 통과, Gradle task 목록 유효성 확인. `build/test-results/test/TEST-*.xml`를 직접 확인한 집계는 아래와 같으며 failures/errors/skipped는 모두 0이다.
| 테스트 클래스 | tests | failures | errors | skipped |
|---|---:|---:|---:|---:|
| `AudioContentBannerRepositoryTest` | 19 | 0 | 0 | 0 |
| `AudioContentRepositoryBannerTest` | 18 | 0 | 0 | 0 |
| `DefaultHomeRecommendationQueryRepositoryTest` | 98 | 0 | 0 | 0 |
| `DefaultAudioRecommendationQueryRepositoryTest` | 29 | 0 | 0 | 0 |
| `AdminContentBannerControllerIntegrationTest` | 72 | 0 | 0 | 0 |
| `AdminContentBannerServiceTest` | 1 | 0 | 0 | 0 |
| 합계 | 237 | 0 | 0 | 0 |
- 범위/검증 경계: production은 helper 1파일과 공개 query 4파일만 변경했다. 테스트는 기존 3클래스, 신규 구형 query 1클래스와 matrix 1파일이며 관리자·DTO·설정·dependency·DDL 파일은 수정하지 않았다. 공개 조회는 실제 JPA/QueryDSL/H2로 호출했고 관리자 73건은 기존 MockMvc/service 회귀 그대로다. LSP 대신 Kotlin main/test 컴파일과 ktlint로 확인했다. 초기 재컴파일에서 기존 다른 테스트의 unnecessary `!!`/unchecked-cast 경고와 기존 Gradle deprecation 안내가 있었고 관련 없는 코드는 변경하지 않았다.
- 사용자 지정 범위대로 전체 `test`/`build`, 운영 MySQL/DDL 실행, 별도 live HTTP 공개 API 검증은 수행하지 않았다. 공개 persistence 동작은 H2 실행 결과이며 운영 JDBC/session timezone 왕복 검증을 대체하지 않는다. P1-T2만 완료하고 활성/다음 Goal은 `P1-GATE`로 이동한다. 최종 Gate의 독립 판정과 rollout 확인은 parent에게 남기며 Phase/Gate를 완료 처리하지 않는다.
## 최종 검증 기록
- 문서 작성 검토: 필수 project guide 및 sample PRD/plan과 대상 코드·테스트 경로를 대조했다.
- 구현 검증은 수행하지 않았다. 이 산출물은 요구사항/실행 계획이며 product/test 파일은 변경하지 않았다.
### P1-T1 구현 후 추가 검증 — 2026-10-27
- 최종 `./gradlew ktlintCheck tasks --all --console=plain` — exit 0, `BUILD SUCCESSFUL in 16s`. main/test/Kotlin script ktlint와 문서 변경 후 Gradle 명령 목록을 확인했다. 앞선 `./gradlew ktlintCheck --console=plain`도 exit 0, `BUILD SUCCESSFUL in 15s`였다.
- 기존 문서 작성 검토와 구현 미실행 항목은 계획 작성 시점의 이력이다. 이후 P1-T1 구현 및 실제 RED/GREEN 결과는 Progress의 실행 증거와 최종 66건 XML 집계에 기록했다. 보고서는 `build/reports/tests/test/index.html`, 원본 집계는 `build/test-results/test/TEST-*.xml`에서 확인했다.
- LSP 도구는 host에서 제공되지 않는다. focused 명령이 실행한 `compileKotlin`/`compileTestKotlin`과 ktlint로 정적 검증을 대체하며 LSP 검증으로 보고하지 않는다.
- 전체 `test`/`build`는 실행하지 않았다. 관리자 예약 저장 경계에 한정된 P1-T1이며 공통 설정·보안·직렬화를 변경하지 않아 계획/프로젝트 가이드에 따라 focused 3클래스로 회귀 범위를 제한했다. 최초 전체 테스트 소스 컴파일 시 기존 다른 테스트의 non-null/unchecked-cast 경고와 Gradle deprecation 경고가 있었으며 관련 없는 파일은 수정하지 않았다.
### P1-GATE parent 독립 실행 — 2026-10-27
```bash
./gradlew test --rerun --tests '*AdminContentBannerControllerIntegrationTest' --tests '*AdminContentBannerServiceTest' --tests '*AudioContentBannerRepositoryTest' --tests '*AudioContentRepositoryBannerTest' --tests '*DefaultHomeRecommendationQueryRepositoryTest' --tests '*DefaultAudioRecommendationQueryRepositoryTest' ktlintCheck bootJar tasks --all --console=plain
```
- 실제 `:test`를 강제 재실행해 exit 0, `BUILD SUCCESSFUL in 46s`를 확인했다. `bootJar`는 새로 패키징했고 ktlint는 변경 코드 기준 up-to-date 통과했다. Gradle 명령 유효성도 확인했다.
- XML 직접 집계는 관리자 통합 72 + 관리자 서비스 1 + 메인 배너 repository 19 + 구형 배너 repository 18 + 홈 v2 repository 98 + 콘텐츠 추천 v2 repository 29 = 237건이다. 모든 클래스의 failures/errors/skipped는 0이다.
- `git diff --check`는 exit 0이다. 최초 clean 상태 이후 변경은 계획한 관리자·공개 query·테스트 및 작업 문서에 한정되며 기존 사용자 변경을 되돌리거나 commit/push하지 않았다.
- 관리자 surface는 실제 Spring controller/service/repository의 MockMvc multipart POST/PUT와 GET을 재실행했고, 공개 query surface는 실제 QueryDSL/JPA/H2 driver 테스트로 재실행했다. 별도 실서버 curl/운영 HTTP 검증은 수행하지 않았다.
- 전체 `test`/`check`/`build`는 실행하지 않았다. 공통 보안/설정/직렬화 변경이 없고 직접 영향받는 관리자 및 네 공개 query의 focused 회귀로 범위를 한정했다. 실행한 `bootJar`는 전체 회귀 테스트를 의미하지 않는다.
- 운영 MySQL DDL 실행, JDBC/session timezone 및 MySQL TIMESTAMP 허용 범위의 실환경 왕복은 미검증이다. 운영 DB에는 연결·변경하지 않았으며 DDL은 앱 rollout 전에 승인된 배포 절차로 적용해야 한다.
- Oracle의 P1-T2/전체 변경 통합 리뷰를 요청한 상태다. 결과를 수집하고 판정하기 전에는 Gate/Phase를 완료 처리하지 않는다.
### P1-GATE 최종 판정 — 2026-10-27
- 위 parent fresh 실행의 237건/실패 0, ktlint 및 bootJar 성공 결과와 변경 파일·DDL을 다시 대조했다.
- Oracle의 P1-T2/전체 변경 통합 검토 결과는 명세 준수 APPROVE, 코드 품질 APPROVE이며 미해결 actionable finding이 없다. 네 공개 조회의 DB 선필터링, 기본 UTC nowProvider, nullable inclusive 경계, 관리자 예약 무관 조회, QueryProjection 및 기존 응답/필터/정렬의 호환성을 확인했다.
- 상세 리뷰는 `reviews/banner-reservation-final-review.md`에 기록했다. 앞선 관리자 입력 타입 문제는 R1과 `reviews/admin-reservation-review.md`로 수정·검증 완료 상태를 보존했다.
- PRD 수용 기준과 P1-T1/R1/P1-T2/Gate가 모두 충족되어 Phase 1을 완료 처리한다. 개발 범위의 blocked 항목은 없다. 운영 DDL 적용과 실환경 MySQL/timezone 검증은 코드 완료와 구분한 배포 전 조치이며 실행하지 않았다.
- 사용자의 후속 지시로 이후 git 명령은 실행하지 않는다. 그 전에도 commit/staging/branch 변경은 하지 않았고, 후속 지시 이후에는 Gradle 명령·문서 내용만 확인했다.
@@ -1,82 +0,0 @@
# 오디오 콘텐츠 배너 예약 기간 PRD
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | 구현 완료 |
| 작성일 | 2026-10-27 |
| 최종 수정일 | 2026-10-27 |
| 대상 제품 | 관리자 오디오 콘텐츠 배너 예약 노출 |
| 작성자·결정권자 | 제품 승인 요구사항 |
| 관련 API Contract | 관리자 예약 필드 추가, 기존 공개 response 유지, 본 문서 §7 |
| 관련 구현 계획 | `docs/20261027_콘텐츠배너예약기간/plan-task.md` |
| 관련 review | `reviews/admin-reservation-review.md`, `reviews/banner-reservation-final-review.md` |
## 1. Overview
관리자는 오디오 콘텐츠 배너에 선택적인 노출 시작·종료 시각을 설정한다. 공개 배너 조회는 현재 시각이 해당 기간에 포함될 때만 배너를 반환하고, 기존 배너는 NULL 기간으로 계속 노출한다.
## 2. Problem Statement
현재 배너는 노출 시작과 종료 시점을 관리할 수 없어서 기간성 콘텐츠를 수동으로 활성화·비활성화해야 한다. 기간이 지나도 공개 조회에서 배너가 선택될 수 있다.
## 3. Goals
- 관리자가 예약 기간을 생성·조회·수정·해제할 수 있다.
- 공개 오디오 배너 조회 네 경로가 동일한 기간 조건을 적용하고 기존 필터·정렬·limit 동작을 보존한다.
- 기존 레코드의 동작과 공개 응답 스키마를 유지한다.
## 4. Non-Goals
- 오디오 이외 배너 유형, 예약 실행 scheduler, 활성 상태 자동 변경은 범위 밖이다.
- 공개 API 응답 필드, 권한·인증, 공통 시간대 설정 및 dependency 변경은 하지 않는다.
- 운영 DB에 DDL을 자동 실행하지 않는다.
## 5. 사용자 및 권한
- 사용자는 기존 관리자 배너 API의 기존 권한으로 생성·조회·수정한다. 권한 범위는 변경하지 않는다.
- 공개 조회 권한과 성인·언어·탭·비활성·차단 대상 필터는 기존 계약을 유지한다.
## 6. 핵심 흐름
1. 관리자가 생성 요청에 선택적 예약 시각을 입력한다.
2. 관리자가 목록에서 저장된 두 시각을 확인한다. 예약 여부로 관리자 목록 행을 숨기지 않는다.
3. 관리자가 수정을 생략하면 기존 값을 유지하고, 해당 필드를 JSON `null`로 보내면 그 경계만 해제한다.
4. 공개 조회는 예약 기간 안에 있는 활성 배너만 기존 조건에 따라 반환한다.
## 7. 확정 기능 요구사항 및 계약
| ID | 상태 | 요구사항 및 수용 기준 | 계약/Goal |
|---|---|---|---|
| SCH-001 | 확정 | `startDate`, `endDate`는 nullable 시각이다. 둘 다 NULL이면 항상 노출, 시작만 있으면 `startDate <= now`, 종료만 있으면 `now <= endDate`, 둘 다 있으면 `startDate <= now <= endDate`이다. | `P1-T1`, `P1-T2` |
| SCH-002 | 확정 | 관리자 생성 입력의 두 필드는 optional이다. 관리자 목록은 두 값을 반환하되 기간으로 행을 필터링하지 않으며 기존 `isActive` 및 tab 조건을 유지한다. | `P1-T1` |
| SCH-003 | 확정 | 관리자 수정은 생략한 경계를 유지하고, 명시적 JSON null은 해당 값을 해제한다. effective start가 end보다 늦으면 `common.error.invalid_request`로 거부한다. 형식 오류도 같은 공통 오류를 사용하며, 검증은 이미지 업로드 전에 끝난다. | `P1-T1` |
| SCH-004 | 확정 | 관리자 입력 형식은 기존 이벤트 입력 관례인 KST 문자열 `yyyy-MM-dd HH:mm`, 저장은 UTC다. 끝 시각은 입력 분의 `:59`까지 포함한다. 응답 시각은 KST 동일 형식이다. 이는 기존 관리자 이벤트 관례를 적용한 구현 결정이며 사용자 지정 초 형식은 아니다. | `P1-T1` |
| SCH-005 | 확정 | DB는 두 컬럼을 MySQL `TIMESTAMP NULL DEFAULT NULL` 초 정밀도로 추가하고 모든 컬럼에 설명 COMMENT를 둔다. 기존 데이터는 NULL 유지, backfill 없음. DDL은 문서로 제공하며 적용이 앱 rollout보다 먼저다. 운영 DB 자동 실행 금지. | `P1-T1`, Gate |
| SCH-006 | 확정 | 공개 경로 네 곳 모두 기간 필터를 DB 조회에 적용해 limit 전에 제외한다. 기존 조건과 정렬을 보존한다. | `P1-T2` |
| SCH-007 | 확정 | 공개 응답 schema·권한·security는 그대로 유지한다. | 전체 |
관리자 수정에서 JSON 필드 생략과 명시적 null을 구분하기 위해 raw JSON의 presence만 감지한다. 신규 dependency는 추가하지 않는다.
공개 조회 경로는 `AudioContentQueryRepositoryImpl.getAudioContentMainBannerList(isAdult)`, `AudioContentBannerQueryRepositoryImpl.getAudioContentMainBannerList(tabId, isAdult, lang)`, `DefaultHomeRecommendationQueryRepository.findHomeBanners(limit, memberId, includeAdultBanners, lang)`, `DefaultAudioRecommendationQueryRepository.findBanners(limit, memberId, canViewAdultContent, lang)`이다. 각 경로에 이미 적용된 활성·탭·언어·성인·대상 소유자/차단 조건과 기존 정렬을 보존한다.
## 8. 데이터·오류·시각
- 입력 필드명은 사용자 요청대로 `startDate`, `endDate`; 값은 `yyyy-MM-dd HH:mm` 문자열 또는 null이다. 응답은 nullable 문자열이다.
- 형식 오류 및 기간 역전은 기존 `common.error.invalid_request`로 응답한다.
- DDL 소수초 미지정 `TIMESTAMP`의 초 정밀도에 맞춰 초 단위 단일 값으로 저장·응답한다. 공개 조회의 현재 UTC 시각도 초 단위로 비교해 종료 분의 마지막 초 전체를 포함한다. 테스트는 고정 UTC 현재 시각 seam을 사용하고 실제 DB 저장 후 `flush`/`clear`/재조회로 왕복을 확인한다. H2 검증 컬럼은 `TIMESTAMP(0)`로 운영 DDL의 정밀도를 재현한다.
## 9. 성공 기준과 추적
- [x] 관리자 create/update/list에서 선택적 기간, 생략 유지와 명시적 null 해제를 검증한다. (`SCH-002~005`, `P1-T1`)
- [x] 잘못된 입력과 역전 기간이 업로드 전 공통 오류로 거부된다. (`SCH-003`, `P1-T1`, `P1-T1-R1`)
- [x] 네 공개 경로가 경계 시각 포함 여부를 판정하고 예약 외 레코드를 limit 전에 제외한다. (`SCH-001`, `SCH-006`, `P1-T2`)
- [x] 기존 공개 필터·정렬, 관리자 isActive/tab 필터, 공개 응답 schema가 보존된다. (`SCH-002`, `SCH-006~007`, Gate)
- [x] DDL과 앱 배포 순서를 문서화하고 자동 운영 DB 적용이 없다. (`SCH-005`, Gate)
## 10. 제외 항목 및 결정 기록
- 제외: 다른 banner type, scheduler, 공개 response 변경, 자동 isActive 전환, 신규 dependency, global time 설정, live DB 실행.
- 2026-10-27, DEC-001, 확정: 이벤트 관리자의 기존 KST 분 단위 입력/응답 관례를 적용하고 종료 분을 `:59`까지 포함한다. 요구사항은 timestamp 예약을 지정했으며 seconds format을 지정하지 않았으므로 기존 관리자 관례를 따른다.
- 2026-10-27, DEC-002, 확정: 기간 필터는 공개 네 조회에만 적용한다. 관리자 목록은 예약과 무관하게 기존 활성/tab 정책을 유지한다.
@@ -1,45 +0,0 @@
# 관리자 콘텐츠 배너 예약 리뷰
## 리뷰 정보
| 항목 | 내용 |
|---|---|
| 대상 | P1-T1, P1-T1-R1의 working tree 변경 |
| 일자 | 2026-10-27 |
| 리뷰어 | 독립 scoped reviewer, parent 실행 검증 |
| 기준 | `../prd.md` SCH-001~005, `../plan-task.md` |
| 상태 | 수정 검증 완료 |
## 범위와 근거
- 관리자 create/update/list, nullable entity 시각, KST/UTC 변환, MySQL DDL 및 실제 HTTP/DB 테스트를 검토했다.
- `AdminContentBannerService.kt`, `GetAdminContentBannerResponse.kt`, `AdminContentBannerRepository.kt` 및 요청 DTO와 entity의 변경을 확인했다.
- `AdminContentBannerControllerIntegrationTest.kt`의 multipart POST/PUT/GET, H2 `TIMESTAMP(0)` 별도 트랜잭션 재조회 및 S3 미호출 assertion을 확인했다.
- 공개 기간 필터는 다음 P1-T2 범위이므로 이 리뷰에서 판정하지 않았다. 운영 MySQL과 JDBC/session timezone은 검증하지 않았다.
## 발견 사항
| ID | 심각도 | 상태 | 내용 | 후속 Goal |
|---|---|---|---|---|
| REV-ADMIN-001 | Medium | 수정 완료 | 예약 필드에 JSON 객체/배열이 오면 DTO 매핑 단계에서 실패해 `common.error.unknown`으로 반환됨 | P1-T1-R1 |
### REV-ADMIN-001
- 관찰: `startDate: {}` 또는 `endDate: []`에서 Jackson 매핑 예외가 날짜 검증 전에 발생했고, 일반 예외 처리기가 예약 오류 계약과 다른 결과를 반환했다.
- 재현: create/update × start/end × 객체/배열의 HTTP 사례 8개를 추가했다. 실제 RED에서 기존 64건은 통과하고 신규 8건만 실패했다.
- 조치: 같은 JSON 트리에서 두 예약 필드의 타입을 DTO 변환 전에 검사한다. 문자열/null/생략만 허용하며 다른 필드의 기존 매핑 계약이나 전역 예외 처리는 바꾸지 않았다.
- 검증: 오류 키 `common.error.invalid_request`, S3 미호출, 생성 미저장 및 수정 전후 DB row 일치를 확인했다. 기존 생략/null·시간대·관리자 목록 테스트도 유지했다.
## 실행 증거
```bash
./gradlew test --rerun --tests '*AdminContentBannerControllerIntegrationTest' --tests '*AdminContentBannerServiceTest' --tests '*AudioContentBannerRepositoryTest' --console=plain
```
parent가 위 명령을 실행해 exit 0, `BUILD SUCCESSFUL in 36s`를 확인했다. XML 집계는 통합 72 + 기존 서비스 1 + 공개 repository 1 = 74건이며 failures/errors/skipped는 모두 0이다. 구현자의 `ktlintCheck tasks --all`도 exit 0이다. LSP 도구가 없어 Kotlin 컴파일/ktlint를 사용했다.
## 종료 판정
- 최초 발견 사항은 기존 완료 이력을 되돌리지 않고 P1-T1-R1로 누적했다.
- scoped 재검토 결과 REV-ADMIN-001은 ADDRESSED, 명세 준수와 코드 품질 모두 APPROVE다. 수정 범위의 새 actionable finding은 없다.
- 관리자 기능의 미해결 finding은 없다. P1-T2와 최종 Gate는 별도로 수행한다.
@@ -1,46 +0,0 @@
# 콘텐츠 배너 예약 최종 리뷰
## 리뷰 정보
| 항목 | 내용 |
|---|---|
| 대상 | P1-T2와 전체 working tree 변경, P1-GATE |
| 일자 | 2026-10-27 |
| 리뷰어 | Oracle 독립 통합 리뷰, parent 실행 검증 |
| 기준 | `../prd.md`, `../plan-task.md`, `admin-reservation-review.md` |
| 상태 | 판정 완료 |
## 목적과 범위
관리자 예약 설정에서 공개 배너 노출 판정까지 승인된 계약이 연결되는지 확인했다. 관리자 DTO/service/repository/응답·entity, 네 공개 query와 공유 predicate, 관련 테스트·DDL을 검토했다. 새로운 기능 설계나 다른 배너 도메인, 전역 보안·시간대 설정 변경은 범위 밖이다.
## 검토 근거
- 공개 query: `AudioContentQueryRepositoryImpl.getAudioContentMainBannerList`, `AudioContentBannerQueryRepositoryImpl.getAudioContentMainBannerList`, `DefaultHomeRecommendationQueryRepository.findHomeBanners`, `DefaultAudioRecommendationQueryRepository.findBanners` 모두 기존 조건에 공유 `isVisibleAt(now)`를 AND 적용한다. v2는 limit 전에 예약을 제외한다.
- 경계: NULL 제한 없음과 양 끝 포함, 초 단위 UTC now, 종료 분 마지막 초의 나노초·자정 경계를 확인했다. 네 생성자의 optional nowProvider는 기존 호출과 Spring 주입을 유지한다.
- 관리자: 엄격한 문자열/JSON 타입 및 effective 기간 검증이 S3·entity 변경보다 앞선다. update 생략 유지/명시 null 해제, KST 입력/응답·UTC 저장, 관리자 날짜 무관 조회와 기존 active/tab 조건을 확인했다.
- 응답: QueryProjection 보조 생성자와 생성 Q 타입의 `LocalDateTime` 인자 일치 및 UTC→KST 문자열 변환을 확인했다. 공개 서비스의 기존 DTO 매핑은 예약 필드를 공개 응답에 추가하지 않는다.
- 테스트: 공유 16-case matrix × 4 query, 실제 H2 `TIMESTAMP(0)` 저장/flush/clear/재조회, v2 limit 충족 및 관리자 multipart HTTP 계약을 확인했다.
## 실행 증거
parent가 다음 명령을 실행했다. Oracle은 같은 테스트를 중복 실행하지 않고 정적 검토를 수행했다.
```bash
./gradlew test --rerun --tests '*AdminContentBannerControllerIntegrationTest' --tests '*AdminContentBannerServiceTest' --tests '*AudioContentBannerRepositoryTest' --tests '*AudioContentRepositoryBannerTest' --tests '*DefaultHomeRecommendationQueryRepositoryTest' --tests '*DefaultAudioRecommendationQueryRepositoryTest' ktlintCheck bootJar tasks --all --console=plain
```
- exit 0, `BUILD SUCCESSFUL in 46s`; test 강제 재실행, ktlint 통과와 실행 JAR 패키징 성공.
- XML 직접 집계: 72 + 1 + 19 + 18 + 98 + 29 = 237건, failures/errors/skipped 모두 0.
- `git diff --check` exit 0. LSP 도구가 없어 main/test Kotlin 컴파일과 ktlint로 정적 검증을 대체했다.
- 관리자 surface는 MockMvc POST/PUT/GET, 공개 persistence surface는 실제 QueryDSL/JPA/H2로 실행했다. 별도 공개 live HTTP/curl과 운영 DB는 검증하지 않았다.
## 발견 사항과 종료 판정
**확정 발견 사항 없음.** 명세 준수와 코드 품질 모두 APPROVE다. P1-T2/전체 변경을 함께 검토했으며 누락된 조회 경로나 Gate를 막는 테스트 공백을 발견하지 못했다. 신규 회귀 Task 전환 항목은 없다.
앞선 관리자 JSON 객체/배열 오류는 P1-T1-R1로 수정·검증됐으며 이번 전체 검토에서도 유지됨을 확인했다. parent의 fresh 실행 결과와 함께 P1-GATE 완료 근거로 사용한다.
## 잔여 검증 경계
전체 test/check/build는 실행하지 않았고, 직접 영향받는 여섯 클래스 회귀와 bootJar 패키징만 실행했다. 운영 MySQL의 TIMESTAMP 허용 범위, JDBC/session timezone 및 실제 DDL 왕복은 미검증이며 입증된 코드 결함으로 판정하지 않았다. nullable 컬럼 추가 DDL은 backfill 없이 기존 NULL 노출을 유지하며, 앱 rollout 전에 별도 승인 절차로 적용해야 한다.
@@ -1,75 +0,0 @@
# 일반용 이벤트 상세 API 클라이언트 구현 프롬프트
아래 프롬프트는 이번에 구현한 서버 계약이다. 운영 배포 완료를 의미하지 않는다.
```text
기존 앱의 네트워크 계층과 화면 패턴을 사용해 일반 사용자용 이벤트 상세 조회를 연결해 주세요.
관리자 상세 API를 만들거나 기존 이벤트 목록/팝업 API를 변경하지 마세요.
[요청]
GET {기존 API_BASE_URL}/api/v2/events/{id}
- id: 기존 이벤트 목록/배너의 이벤트 id. 양수 64비트 정수이며 필수입니다.
- 요청 본문과 query parameter는 없습니다.
- 비로그인 호출이 가능합니다. 비로그인에는 Authorization 헤더를 보내지 마세요.
- 로그인 시 기존 Authorization: Bearer {accessToken}을 사용하세요.
- 오류 메시지 언어는 기존 Accept-Language 정책을 따릅니다.
- 이벤트 언어는 Accept-Language가 아니라 서버의 국가 판정에 따릅니다.
CloudFront-Viewer-Country 및 기존 서버 보정 정책을 사용하므로 국가를 임의로 바꾸지 마세요.
[성공: HTTP 200, application/json]
{
"success": true,
"message": null,
"data": {
"id": 123,
"thumbnailImageUrl": "https://cdn.example.com/event/thumbnail.png",
"detailImageUrl": "https://cdn.example.com/event/detail.png",
"popupImageUrl": null,
"link": "https://example.com/promotion"
},
"errorProperty": null
}
- data는 배열이 아닌 이벤트 단일 객체입니다.
- id: 정수, thumbnailImageUrl: 문자열.
- detailImageUrl, popupImageUrl, link: 문자열 또는 null.
- title, content, startDate, endDate, lang, isAdult, isPopup, totalCount는 반환하지 않습니다.
- 이미지 URL은 서버가 구성한 값을 사용하고 CDN 주소를 다시 붙이지 마세요.
- link는 이미지 URL과 별개인 이동 목적지이며 저장값 그대로 반환합니다.
- 상세 이미지가 null이어도 link가 있는 정상 이벤트일 수 있습니다.
- 이미지와 link가 모두 있을 때의 우선순위나 자동 이동은 API가 결정하지 않습니다.
기존 앱의 표시/이동 정책을 유지하고, 임의로 자동 리다이렉트를 추가하지 마세요.
- 서버는 link의 URL 형식이나 허용 스킴을 검증하지 않습니다.
링크 열기 시 기존 앱의 안전한 외부 URL 처리 정책을 적용하세요.
[조회 불가: HTTP 200]
{
"success": false,
"message": "잘못된 요청입니다.",
"data": null,
"errorProperty": null
}
- 미존재 ID, 0/음수 ID, 비활성, 시작 전/종료 후, 언어 불일치, 성인 조건 불일치가 동일한 응답입니다.
- 숫자가 아니거나 Long 범위를 넘는 id는 HTTP 200 실패 응답과 기존 공통 오류 메시지를 반환합니다.
- HTTP 200만으로 성공 판정하지 말고 success=true와 유효한 data를 확인하세요.
- message는 지역화되므로 문구로 오류 유형을 분기하지 마세요.
- 서버 내부 messageKey는 응답에 없으며 미존재와 비노출 사유를 구별할 수 없습니다.
- 이 API의 조회 불가가 HTTP 404라고 가정하지 마세요.
- 네트워크 오류와 비정상 HTTP 상태/인증 오류는 기존 앱의 공통 처리 정책을 유지하세요.
모든 오류 응답이 위 JSON 형태라고 가정하지 마세요.
[서버 노출 정책: 기존 GET /event와 동일]
- 활성이고 시작 시각 <= 현재 시각 <= 종료 시각인 이벤트만 조회됩니다.
- 서버 판정 국가가 JP이면 JA 이벤트, 그 외에는 KO 이벤트만 조회됩니다.
- 비로그인/성인 미인증 회원: isAdult=null 또는 false 이벤트.
- 성인 인증 회원: isAdult=null 또는 true 이벤트. 기존 정책상 false 이벤트는 제외됩니다.
- 관리자 계정: 성인 조건만 생략하며 활성/기간/언어 조건은 유지됩니다.
- 위 정책은 서버가 적용합니다. 클라이언트가 목록과 다른 우회 조회를 구현하지 마세요.
- 로그인 상태/국가가 바뀌면 이전 조회 결과를 무조건 재사용하지 마세요.
[클라이언트 수용 기준]
- 이벤트 id로 상세 API를 호출해 loading/success/unavailable/network-error를 구분합니다.
- nullable 이미지/link 및 링크만 있는 이벤트를 정상 처리합니다.
- HTTP 200 success=false에서도 기존 데이터를 성공 화면으로 표시하지 않습니다.
- 로그인 여부에 따른 헤더와 실제 서버 결과를 사용하고, 응답에 없는 제목/본문/날짜를 만들어 내지 않습니다.
- 기존 목록 GET /event, 팝업 GET /event/popup, 관리자 API는 그대로 유지합니다.
```
@@ -1,152 +0,0 @@
# 일반용 이벤트 상세 조회 구현 계획
**Goal:** 일반 사용자가 기존 노출 정책을 통과한 이벤트 한 건을 v2 API로 조회한다.
**Architecture:** 기존 EventRepository의 ID 조회와 EventItem을 재사용한다. 신규 controller와 read-only service는 v2 아래 배치하고 기존 controller/service는 변경하지 않는다.
**Tech Stack:** Kotlin 1.6.21, Java 17, Spring Boot 2.7.14, JPA, JUnit 5, H2.
**Spec:** [prd.md](prd.md)
**실행:** subagent-driven-development; 커밋/푸시는 별도 승인 없이 하지 않는다.
## 현재 상태
- 상태: 구현 및 검증 완료 (운영 배포 제외)
- 현재 Phase: 1
- 활성/다음 Goal: 없음 (P1-T1, P1-GATE 완료)
- 순서: P1-T1 → P1-GATE. 동시에 하나만 실행한다.
## Global Constraints
- 승인된 GET `/api/v2/events/{id}`만 추가. 관리자 상세/legacy 변경/DB·의존성 변경 제외.
- 기존 성인/언어 정책 및 이미지 변환을 그대로 유지한다.
- 모든 신규 API/하위 구현은 v2 패키지에 둔다. 불필요한 추상화/port는 만들지 않는다.
- 기존 테스트 삭제·완화, 비밀값 기록 금지. 소유 임시 자원만 정리한다.
## Review Focus
- 인증된 성인에게 `isAdult=false` 이벤트를 추가로 노출하지 않는지 확인한다.
- 관리자도 언어·기간·활성 조건을 지키는지 확인한다.
- 익명 허용이 쓰기/collection/추가 하위 경로로 확장되지 않는지 확인한다.
- null 이미지, 외부 HTTPS 이미지, 외부 link를 변경하거나 관리 엔티티를 수정하지 않는지 확인한다.
- 미존재와 비노출 오류가 동일하고 상세 정보를 누출하지 않는지 확인한다.
### Phase 1: v2 단건 조회
- [x] **Task 1.1: 일반 이벤트 상세 조회와 보안 회귀 검증**
**Goal P1-T1:** 기존 목록과 같은 노출 정책을 적용한 단일 EventItem을 반환한다.
- 시작 조건: PRD 확정, 기존 event/admin focused test 성공.
- 완료 증거: RED/GREEN 기록, S1~S3 테스트 성공, 실제 HTTP 응답 증거.
- 범위 밖: 전체 빌드/독립 리뷰는 P1-GATE; legacy 리팩터링과 추가 기능.
**Files:**
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/event/adapter/in/web/EventDetailController.kt`
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/event/application/EventDetailService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/configs/SecurityConfig.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/event/EventDetailControllerIntegrationTest.kt`
- 필요한 서비스 경계 테스트는 같은 v2/api/event 패키지에 통합 테스트로 추가한다.
**Interfaces:**
- Consumes: `EventRepository`, `AuthRepository.getAuthIdByMemberId`, `MemberContentPreferenceService.resolveCountryCode`, `EventItem`.
- Produces: `EventDetailService.getEvent(id: Long, member: Member?): EventItem`.
- Controller: `/api/v2/events`, `@GetMapping("/{id}")`, nullable `@AuthenticationPrincipal`.
- Security: GET `/api/v2/events/*`만 permitAll; `/**` 금지.
- [x] **RED:** 먼저 실제 HTTP 정상 요청 테스트를 작성하고, 조회 불가·성인 3상태·언어·관리자·응답 변환·인접 보안 시나리오를 추가한다.
- [x] **RED 확인:** `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.event.*' --console=plain`에서 미구현 route/security로 정상 요청이 실패함을 기록한다.
- [x] **GREEN:** ID 단건 로드, 양수 검사, 활성/현재 시각/언어/성인 필터, EventItem 변환, 좁은 보안 허용을 구현한다.
- [x] **GREEN 확인:** 동일 focused test로 모든 시나리오 통과를 확인한다.
- [x] **REFACTOR:** 새 중복만 필요 시 정리하고 기존 event/admin 회귀를 다시 실행한다.
**검증 세부:**
- 실제 DB에 저장한 KO/JA 및 nullable adult 필드를 비교한다. 인증 일반 회원의 auth 기록은 실제 DB로 준비한다.
- `isAdult` null/false/true 각각을 익명·미인증·인증·관리자에 대해 기존 `/event`와 비교한다.
- 미래/종료 테스트는 현재 시각에서 충분히 떨어진 값을 사용해 flake를 피한다. 기간 조건의 양끝 포함은 코드 및 가능한 기존 seam으로 검증한다.
- 이미지/링크 null, 상대 경로, HTTPS, 기존 http 문자열 보정 및 모든 응답 필드를 확인한다.
- missing/zero/negative/nonnumeric/overflow ID, non-GET, 하위 추가 경로, legacy 목록/팝업/admin 접근을 검증한다.
- RANDOM_PORT/TestRestTemplate의 상태/본문을 test output으로 남긴다. 인증은 동일 컨텍스트 MockMvc로도 검증 가능하다.
### Phase 1 Gate
- [x] **Goal P1-GATE: 동작·회귀·빌드·리뷰·정리 완료**
- 시작 조건: P1-T1 완료.
- 완료 증거: 아래 명령과 HTTP 증거, 독립 reviewer 승인, 자원 정리 확인.
- 범위 밖: 기존 전체 테스트 실패/린트 위반의 무관한 수정.
- TDD 예외 사유: 읽기 전용 완료 검증이며 테스트 추가가 아닌 실행·리뷰 단계다.
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.event.*' --tests 'kr.co.vividnext.sodalive.event.*' --tests 'kr.co.vividnext.sodalive.admin.event.banner.*' --console=plain
./gradlew test --console=plain
./gradlew bootJar ktlintCheck --console=plain
./gradlew tasks --all --console=plain
```
- LSP 도구가 노출되어 있으면 변경 파일 진단, 없으면 Kotlin compile/ktlint 결과와 미실행 사실을 기록한다.
- 사용자 ulw 지시 및 보안 matcher 추가로 전체 테스트를 실행한다. 실패가 기존 상태에서도 재현되면 별도 제한으로 기록한다.
- 고위험 reviewer 1명이 목표·S1~S3·diff·실행 증거를 확인한다. 범위 내 blocker만 수정한다.
- 소유 임시 폴더/QA 프로세스가 정리되었음을 확인한다. 공유 Gradle 캐시는 삭제하지 않는다.
- 후속 사용자 요청의 전달물: `api-client-prompt.md`에 구현된 요청/응답/오류/노출 정책을 기록하고 최종 응답에도 프롬프트로 제공한다. 문서 작업의 TDD는 해당 없으며 실제 HTTP 응답 및 코드와 대조한다.
## Progress
### 사전 검증 — 2026-10-28
- worktree: clean.
- `./gradlew test --tests 'kr.co.vividnext.sodalive.event.*' --tests 'kr.co.vividnext.sodalive.admin.event.banner.*' --console=plain`: BUILD SUCCESSFUL, 1m 1s. 구현 전 기존 목록/팝업/관리자 테스트 기준선 확보.
- 부모 세션에는 lsp_diagnostics 도구가 노출되지 않았다. 진단 성공으로 보고하지 않는다.
### P1-T1 RED — 2026-10-28
- 새 production 타입을 참조하지 않는 RANDOM_PORT/TestRestTemplate + 같은 컨텍스트 MockMvc 통합 테스트를 먼저 작성했다. S3 외 노출 정책·repository·인증 기록은 mock 없이 실제 H2로 검증한다.
- 명령: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.event.*' --console=plain --no-daemon -Pkotlin.compiler.execution.strategy=in-process`.
- 첫 실행은 도구의 120초 제한으로 test compile 중 중단되어 RED 근거로 사용하지 않았다. 같은 명령을 600초 제한으로 재실행: BUILD FAILED, 8m 59s, 28 tests completed / 15 failed / 0 errors. compile 성공 후 실제 HTTP assertion에서 expected 200 OK / actual 401 UNAUTHORIZED로 실패했다. 기존 보호 경로 13건은 통과했다.
- 정상 요청 RED 원문: `HTTP GET /api/v2/events/19 country=null -> 401 {"timestamp":"2026-10-28T09:03:37.443+00:00","status":401,"error":"Unauthorized","path":"/api/v2/events/19"}`. `shouldReturnAnonymousEventDetailWithLegacyFieldsWithoutMutatingTheEntity`의 HTTP 상태 assertion 실패이며 missing-class compile 실패가 아니다.
- RED 원본은 소유 임시 폴더의 `red-retry.log` 및 당시 `build/test-results/test/TEST-kr.co.vividnext.sodalive.v2.api.event.EventDetailControllerIntegrationTest.xml`에서 확인했다. XML은 다음 실행으로 갱신되므로 핵심 결과와 응답을 이 기록에 보존한다.
- 실행 자원: `--no-daemon`과 in-process Kotlin compile을 사용했다. 소유 임시 root는 `/var/folders/yh/8xsbvpsj5wg2qnxzxdp11_gm0000gn/T/opencode/event-detail-p1-t1.xH3EUF`이며 작업 종료 시 삭제하고 공유 캐시/다른 세션 프로세스는 건드리지 않는다.
### P1-T1 GREEN 및 인접 회귀 — 2026-10-28
- 변경 파일은 신규 `EventDetailController.kt`, `EventDetailService.kt`, 신규 `EventDetailControllerIntegrationTest.kt`, `SecurityConfig.kt`의 GET matcher 한 줄, 이 계획 문서뿐이다. 기존 엔티티/서비스/컨트롤러와 PRD는 변경하지 않았다.
- `EventRepository.findByIdOrNull`로 단건을 로드하고 read-only 서비스에서 기존 목록과 동일한 정책을 확인한다. 전체 목록 조회, 새 port/DTO/의존성, 별도 parser/exception handler는 추가하지 않았다. 관리자 우회는 성인 조건에만 적용한다.
- focused GREEN 명령: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.event.*' --console=plain --no-daemon -Pkotlin.compiler.execution.strategy=in-process` → BUILD SUCCESSFUL, 8m 26s, 28 tests / 0 failures / 0 errors / 0 skipped.
- 인접 회귀 명령: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.event.*' --tests 'kr.co.vividnext.sodalive.event.*' --tests 'kr.co.vividnext.sodalive.admin.event.banner.*' --console=plain --no-daemon -Pkotlin.compiler.execution.strategy=in-process` → BUILD SUCCESSFUL, 3m 45s. XML 합계 46 tests / 0 failures / 0 errors / 0 skipped: 신규 28, 기존 EventController 5 / EventRepository 5 / EventService 4 / AdminEventBannerController 4.
- S1: RANDOM_PORT 실제 HTTP로 익명 KO/JP/기타 국가/헤더 누락, 5개 필드 전체, nullable 이미지·link, HTTPS 보존, 상대/http 이미지 CDN 접두사, 외부 link 보존을 확인했다. `/event` 항목과 상세를 완전 비교하고 DB 재조회로 이미지 필드가 변하지 않음을 확인했다.
- S2: 실제 H2 auth 기록이 있는/없는 일반 회원과 관리자는 같은 컨텍스트 MockMvc로 검증했다. KO/JA × adult null/false/true × 익명/미인증/인증/관리자 24조합의 상세와 기존 목록을 비교했다. 인증 성인은 false를 제외하고 관리자는 false/true/null을 허용한다. 비활성/미래/종료/언어 불일치는 관리자에게도 미존재와 동일한 실패 응답이다. 양수 검사·미존재는 HTTP 200 invalid_request 및 실제 SodaException messageKey, malformed/overflow는 기존 MethodArgumentTypeMismatchException과 공통 unknown 응답을 확인했다.
- 기간은 현재 시각에서 하루 이상 떨어진 값으로 테스트했다. 정확히 같은 시각의 포함 경계는 기존 주입 seam이 없어 시계를 새로 추상화하지 않고 코드 비교로 확인했다: legacy `startDate.loe(now)` / `endDate.goe(now)`, 신규는 `startDate > now` / `endDate < now`만 거부하여 양끝을 포함한다.
- S3: 실제 HTTP 보안 13건에서 익명 POST/PUT/DELETE, collection, 추가 하위 경로, legacy 팝업/쓰기, 관리자 목록/단건 경로 모두 401을 확인했다. 익명 기존 `/event` 목록은 계속 200이며 기존 목록/팝업/관리자 회귀도 통과했다.
- 검증 중 제한: 첫 GREEN은 테스트 소스 compile 중 600초 도구 제한, 첫 인접 회귀는 180초 제한으로 종료되어 통과 근거로 사용하지 않았다. 제한을 늘려 재실행했다. 중간 GREEN의 2건 실패는 MockMvc `contentAsString`의 기본 문자셋으로 한글을 잘못 해석한 테스트 문제였다. JSON은 원본 bytes로 파싱하고 로그만 명시적 UTF-8로 읽도록 수정했으며 기대값/정책 assertion은 완화하지 않았다.
- 진단: 이 세션에도 `lsp_diagnostics` 도구가 없어 미실행. Gradle의 production/test Kotlin compile은 성공했다. 변경 파일에서 compiler 경고는 없었고 기존 다른 파일의 불필요한 `!!`/unchecked cast/미사용 인자 및 Gradle deprecated 경고는 수정하지 않았다. 전체 suite, bootJar, ktlintCheck, tasks, 독립 리뷰는 부모 담당 P1-GATE로 남겨 실행하지 않았다.
- HTTP 원본 artifact: `build/test-results/test/TEST-kr.co.vividnext.sodalive.v2.api.event.EventDetailControllerIntegrationTest.xml`의 `system-out`에 상태/본문을 기록했다. HTML은 `build/reports/tests/test/classes/kr.co.vividnext.sodalive.v2.api.event.EventDetailControllerIntegrationTest.html`. 다음 Gradle test가 덮어쓸 수 있어 핵심 응답을 아래 보존한다.
```text
HTTP GET /api/v2/events/22 country=null -> 200 {"success":true,"message":null,"data":{"id":22,"thumbnailImageUrl":"https://cdn.test/thumbnail.png","detailImageUrl":null,"popupImageUrl":null,"link":"https://external.test/promotion?from=soda&target=event#detail"},"errorProperty":null}
HTTP GET /api/v2/events/17 country=JP -> 200 {"success":true,"message":null,"data":{"id":17,"thumbnailImageUrl":"https://cdn.test/thumbnail.png","detailImageUrl":"https://cdn.test/detail.png","popupImageUrl":"https://cdn.test/popup.png","link":"https://external.test/event"},"errorProperty":null}
HTTP GET /api/v2/events/0 country=null -> 200 {"success":false,"message":"잘못된 요청입니다.","data":null,"errorProperty":null}
HTTP GET /api/v2/events/1/extra -> 401 {"timestamp":"2026-10-28T09:37:20.055+00:00","status":401,"error":"Unauthorized","path":"/api/v2/events/1/extra"}
HTTP GET /event/popup -> 401 {"timestamp":"2026-10-28T09:37:20.121+00:00","status":401,"error":"Unauthorized","path":"/event/popup"}
```
### P1-T1 Teardown Receipt — 2026-10-28
- 마지막 테스트 executor PID 18510 종료와 소유 root에 열린 파일 없음(`lsof -nP +D`)을 확인했다. mktemp root 소유 표식을 읽고 허용 parent의 canonical path·직접 하위 이름·비심볼릭링크 조건을 확인한 뒤 이 세션의 `event-detail-p1-t1.xH3EUF`만 삭제했다. macOS `/var`의 canonical path가 `/private/var`여서 첫 경로 가드는 삭제를 거부했고, 양쪽 parent를 동일하게 정규화한 후 삭제했다.
- 실제 반환: `TEARDOWN OK: owned event-detail-p1-t1.xH3EUF removed; test executor exited; no open files; shared caches untouched`. RED/GREEN의 핵심 결과와 HTTP 응답은 위에 보존했으며 Gradle XML/HTML은 worktree build 폴더에 남아 있다.
- P1-T1만 완료했다. P1-GATE 체크박스·기준·상단 실행 상태는 부모 세션 소유로 유지하며 커밋/푸시/worktree/다른 에이전트/전체 suite·build·review는 실행하지 않았다.
### P1-GATE 부모 검증 — 2026-10-28
- 부모가 새 controller/service와 전체 통합 테스트, SecurityConfig의 GET matcher 한 줄을 직접 검토했다. 기존 API 변경은 없다.
- `./gradlew bootJar --console=plain --no-daemon -Pkotlin.compiler.execution.strategy=in-process`: BUILD SUCCESSFUL, 1m 9s.
- 최초 ktlintCheck는 새 테스트 CsvSource의 줄바꿈 3건을 지적했다. 데이터/기대값은 유지하고 각 인자를 별도 줄로 배치했다.
- `./gradlew ktlintCheck --console=plain --no-daemon`: BUILD SUCCESSFUL, 1m 33s. 전체 Kotlin main/test/script 검사 통과.
- 첫 전체 테스트는 사용자 중단으로 끝났으며 성공 근거에서 제외했다. 재개 후 `./gradlew test --console=plain --no-daemon -Pkotlin.compiler.execution.strategy=in-process`: BUILD SUCCESSFUL, 19m 29s.
- 최종 XML 집계: 326 suites, 2,584 tests, failures=0, errors=0, skipped=0. 새 EventDetailControllerIntegrationTest 28건과 기존 event/admin 테스트도 포함한다.
- 실제 HTTP 표면은 RANDOM_PORT의 TestRestTemplate 호출이다. 부모 전체 테스트 실행에서도 성공/비노출/인접 보안 응답을 확인했다. 인증 사용자 행렬은 실제 DB fixture와 MockMvc로 검증했다.
- 최종 HTTP artifact: `build/test-results/test/TEST-kr.co.vividnext.sodalive.v2.api.event.EventDetailControllerIntegrationTest.xml`, timestamp `2026-10-28T10:19:56`.
- 대표 응답: `/api/v2/events/22` → HTTP 200, success=true, id=22, thumbnailImageUrl=https://cdn.test/thumbnail.png, detailImageUrl=null, popupImageUrl=null, 외부 link 보존. `/api/v2/events/0` → HTTP 200, success=false, data=null. `/event/popup` 익명 → HTTP 401.
- `./gradlew tasks --all --console=plain`: BUILD SUCCESSFUL. 문서의 Gradle 명령 존재 확인.
- 이전 리뷰 작업은 완료 알림이 있었으나 중단 후 background_output/session_read 및 정확한 로컬 session ID 조회로 결과를 회수하지 못했다. 이를 승인으로 간주하지 않고 동일 범위의 대체 리뷰 하나만 요청했다.
- `lsp_diagnostics`는 부모/구현 세션 모두 도구 미제공으로 미실행. Kotlin 컴파일·ktlint 성공을 대체 증거로 기록한다. 운영 배포와 운영 DB 호출은 수행하지 않았다.
### P1-GATE 최종 판정 및 전달 — 2026-10-28
- `./gradlew bootJar ktlintCheck tasks --all --console=plain --no-daemon -Pkotlin.compiler.execution.strategy=in-process`: 최종 재확인 BUILD SUCCESSFUL, 17s. `git diff --check`도 통과했다.
- 독립 대체 리뷰: [reviews/event-detail-review.md](reviews/event-detail-review.md), APPROVE, 확정 발견 사항 없음. 부모가 리뷰 파일을 읽고 실제 코드·HTTP·전체 테스트 근거와 대조했다. 리뷰 환경은 임시 자원/프로세스 생성 0건이다.
- 클라이언트용 [api-client-prompt.md](api-client-prompt.md)를 실제 endpoint, 5개 응답 필드, nullable 값, HTTP 200 실패 envelope, JWT/언어·국가 처리와 대조했다. 기존 API와 관리자 범위는 그대로다.
- 부모 최종 `pgrep`에서 GradleWrapperMain/Gradle Test Executor/소유 root 관련 프로세스가 없었다. 부모 root는 빈 opencode 폴더만 남아 `rmdir`로 제거했다. 소유 notepad와 구현 root도 부재를 확인했다.
- 정리 read-back: `TEARDOWN OK: parent root, implementation root and notepad absent; shared caches untouched`. 공유 캐시나 다른 세션의 파일/프로세스는 삭제하지 않았다.
- 완료 범위: 승인 API·문서·시나리오 S1~S3·전체 테스트·빌드·린트·리뷰·소유 자원 정리. 제한: LSP 미제공으로 미실행, 기간 동일 시각 경계는 코드 대조, 인증 viewer는 MockMvc 검증. 운영 배포·운영 DB 검증·커밋·푸시는 하지 않았다.
### 커밋 전 재검증 — 2026-10-29
- `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.event.*' --tests 'kr.co.vividnext.sodalive.event.*' --tests 'kr.co.vividnext.sodalive.admin.event.banner.*' bootJar ktlintCheck --console=plain --no-daemon -Pkotlin.compiler.execution.strategy=in-process`: BUILD SUCCESSFUL, 3m 55s. 테스트 5 suites / 46 tests / failures=0 / errors=0 / skipped=0. bootJar·ktlintCheck는 변경 없음으로 UP-TO-DATE다.
- `git diff --check` 및 구현·테스트의 `git diff --staged --check` 통과. 커밋 대상의 비밀값·credential artifact 포함 여부를 확인했다.
- 전체 회귀는 P1-GATE의 2,584건 성공 이후 구현 변경이 없어 재실행하지 않았다. 대신 신규 상세·기존 이벤트·관리자 배너 회귀를 실행했다.
## 종료 기준
승인 endpoint의 정상/경계/회귀가 실제 요청으로 검증되고, 테스트·빌드·사용 가능한 진단 및 독립 리뷰를 마치고 소유 QA 자원이 정리되면 종료한다. 실행 불가능하거나 기존 실패인 항목은 근거와 함께 명시하고 완료로 가장하지 않는다.
@@ -1,54 +0,0 @@
# 일반용 이벤트 상세 조회 PRD
## 문서 정보
- 작성일: 2026-10-28
- 상태: 구현 및 검증 완료 (운영 배포 제외)
- 결정권자: 사용자; 구현 담당: Sisyphus
- 구현 계획: [plan-task.md](plan-task.md)
- 클라이언트 전달 계약: [api-client-prompt.md](api-client-prompt.md)
- 최종 리뷰: [reviews/event-detail-review.md](reviews/event-detail-review.md), APPROVE
## 목표와 범위
이벤트 ID만으로 일반용 이벤트 정보를 조회할 수 있도록 `GET /api/v2/events/{id}`를 추가한다.
기존 목록과 동일한 노출 조건으로 상세 이미지와 외부 이동 링크를 반환한다.
관리자 상세 API, 기존 `/event` 계약 변경, 프론트엔드, DB 변경, 신규 의존성은 제외한다.
## 확정 요구사항
| ID | 요구사항 | 수용 기준 |
|---|---|---|
| EVT-001 | 비로그인 가능한 v2 단건 조회 | 정상 ID 요청은 HTTP 200, `success=true`, 단일 EventItem 반환 |
| EVT-002 | 기존 목록과 동일한 노출 정책 | 활성, 시작/종료 시각 포함 범위, 국가별 언어, 성인 인증 조건 일치 |
| EVT-003 | 기존 응답 필드 재사용 | id, thumbnailImageUrl, detailImageUrl, popupImageUrl, link 보존 |
| EVT-004 | 미존재와 비노출 동일 처리 | HTTP 200, `success=false`, `data=null`, 기존 invalid_request 메시지 |
| EVT-005 | 인접 API 보안 유지 | 익명 쓰기·하위 추가 경로·기존 팝업·관리자 요청은 계속 보호 |
## API 계약
- Method/path: `GET /api/v2/events/{id}`. ID는 양수 Long.
- 인증: 선택적 기존 JWT. 인증이 없으면 비성인 기준. 잘못된 JWT 처리는 기존 보안 정책 유지.
- 성공: `ApiResponse.ok(EventItem)`. 응답 필드는 기존 목록 항목과 동일하며 제목/기간 필드를 추가하지 않는다.
- 이미지: `https://`로 시작하면 그대로, 나머지 문자열은 기존 CloudFront 호스트와 `/`를 앞에 붙인다. nullable 이미지는 null 유지.
- `link`: 저장값 그대로 반환하고 서버에서 이동하거나 URL을 요청하지 않는다.
- 양수가 아닌 ID, 미존재, 비노출: `SodaException(messageKey = "common.error.invalid_request")`로 기존 HTTP 200 실패 envelope 사용.
- 숫자가 아니거나 Long 범위를 넘는 ID: 기존 Spring 바인딩과 공통 오류 처리 유지. 새 parser/handler 없음.
## 노출 정책
- `isActive == true`, `startDate <= now <= endDate`.
- `MemberContentPreferenceService.resolveCountryCode(member)` 결과가 JP면 JA, 그 외 KO.
- 관리자 역할은 성인 조건만 생략하며 활성/기간/언어는 생략하지 않는다.
- 비로그인 및 인증 기록 없는 일반 회원: 이벤트 `isAdult`가 null 또는 false.
- 인증 기록 있는 일반 회원: 이벤트 `isAdult`가 null 또는 true. 기존 목록처럼 false 이벤트는 제외한다.
- ID로 단건 조회하며 전체 목록을 가져와 검색하지 않는다.
## 검증 시나리오
| 시나리오 | 이진 성공 조건 | 실제 검증 표면 |
|---|---|---|
| S1 정상 | 익명 KO/JP, null/HTTPS/상대 이미지, 외부 link가 기존 항목과 동일 | RANDOM_PORT + TestRestTemplate 실제 HTTP 및 H2 |
| S2 경계/권한 | 미존재·비활성·예정·종료·언어 불일치·성인 제한에서 데이터 미노출; 일반/인증/관리자 정책 일치 | 실제 HTTP + 인증 MockMvc + 실제 DB |
| S3 회귀 | 기존 목록 응답 유지, 익명 팝업/관리자/POST·PUT·DELETE·추가 하위 경로 거부 | 실제 HTTP, 기존 event/admin 통합 테스트 |
## Decision Log
- 사용자 확정: 관리자 상세 불필요, 일반 상세만 추가; v2 경로 `/api/v2/events/{id}` 승인; 나머지 기존 정책 적용.
- 구현 선택: 기존 EventItem/엔티티/repository 재사용, v2 controller와 read-only service만 추가. 단건 로드 후 정책 확인으로 불필요한 port/DTO 계층을 만들지 않는다.
- 구현 선택: 미조회 오류는 기존 이벤트 수정/삭제와 공통 예외 관례를 따른다. 별도 HTTP 404 계약을 만들지 않는다.
- 사용자의 ulw 지시에 따라 실제 HTTP 증거, 전체 테스트/빌드와 독립 리뷰를 수행한다. 런타임/도구 제한은 숨기지 않는다.
- 후속 사용자 요청: 최종 결과에 클라이언트 개발자가 사용할 API 계약을 프롬프트 형태로 제공한다. 구현된 서버 계약만 명시하고 새로운 화면/서버 기능을 추가하지 않는다.
@@ -1,62 +0,0 @@
# 일반 이벤트 상세 조회 최종 코드 리뷰
**판정: APPROVE. 확정 발견 사항 없음.**
## 1. 리뷰 정보와 범위
| 항목 | 내용 |
|---|---|
| 리뷰 대상 | P1-T1 구현 및 P1-GATE의 코드·검증 증거 |
| 기준 상태 | 현재 working tree의 신규 파일 직접 열람 및 SecurityConfig의 GET matcher |
| 리뷰 일자 / 리뷰어 | 2026-10-28 / Sisyphus-Junior |
| 기준 문서 | [prd.md](../prd.md) EVT-001~005, [plan-task.md](../plan-task.md) P1-T1·P1-GATE |
| 리뷰 상태 | 판정 완료. 호스트 중단 전 리뷰의 판정은 승계하지 않음 |
변경 내용: 익명 접근 가능한 `GET /api/v2/events/{id}`가 기존 목록의 노출 정책을 적용해 단일 `EventItem`을 반환한다. 관리자 상세나 추가 응답 필드는 만들지 않는다.
신규 controller/service/test, 보안 matcher와 공통 인증·예외 경로, 기존 event Service/Repository/DTO 및 인접 회귀 결과를 검토했다. 제품·테스트·계획 문서 수정, 테스트·빌드 재실행, 별도 HTTP 실행, 에이전트·커밋은 제외했다. 다중 사용자 요청을 전제로 단건 조회와 상태 변경 여부를 확인했으며 부하 측정은 하지 않았다.
## 2. 요구사항 대조
| 기준 | 판정 및 코드·테스트 근거 |
|---|---|
| EVT-001: 일반용 단건 GET만 추가 | [EventDetailController.kt:12](/Users/klaus/Develop/sodalive/Server/sodalive_/src/main/kotlin/kr/co/vividnext/sodalive/v2/api/event/adapter/in/web/EventDetailController.kt:12)의 단일 GET mapping, nullable principal, `ApiResponse.ok` 확인. 관리자 endpoint는 추가하지 않음. [EventDetailService.kt:25](/Users/klaus/Develop/sodalive/Server/sodalive_/src/main/kotlin/kr/co/vividnext/sodalive/v2/api/event/application/EventDetailService.kt:25)는 read-only이며 ID로 조회하고 전체 목록을 검색하지 않음. |
| EVT-002: 활성·기간·언어 | [EventDetailService.kt:31](/Users/klaus/Develop/sodalive/Server/sodalive_/src/main/kotlin/kr/co/vividnext/sodalive/v2/api/event/application/EventDetailService.kt:31)의 `startDate > now` / `endDate < now` 거부는 [EventRepository.kt:21](/Users/klaus/Develop/sodalive/Server/sodalive_/src/main/kotlin/kr/co/vividnext/sodalive/event/EventRepository.kt:21)의 `loe` / `goe`와 동일하게 양끝을 포함함. [EventService.kt:92](/Users/klaus/Develop/sodalive/Server/sodalive_/src/main/kotlin/kr/co/vividnext/sodalive/event/EventService.kt:92)와 같은 country resolver로 JP→JA, 그 외→KO. 활성·기간·언어 검사는 관리자 분기보다 먼저 수행됨. |
| EVT-002: 성인 3상태 및 관리자 우회 | [EventDetailService.kt:38](/Users/klaus/Develop/sodalive/Server/sodalive_/src/main/kotlin/kr/co/vividnext/sodalive/v2/api/event/application/EventDetailService.kt:38)는 실제 auth 기록으로 판단함. 익명·미인증은 null/false, 인증 일반 회원은 null/true만 허용하므로 인증 성인에게 false를 노출하지 않음. 관리자는 성인 조건만 생략함. [EventService.kt:56](/Users/klaus/Develop/sodalive/Server/sodalive_/src/main/kotlin/kr/co/vividnext/sodalive/event/EventService.kt:56)와 [EventRepository.kt:26](/Users/klaus/Develop/sodalive/Server/sodalive_/src/main/kotlin/kr/co/vividnext/sodalive/event/EventRepository.kt:26)에 일치. 신규 테스트의 KO/JA × 3상태 × 4종 viewer 비교 및 관리자 비노출 검증 확인. |
| EVT-003: 정확히 5개 필드·이미지·link | [EventDetailService.kt:45](/Users/klaus/Develop/sodalive/Server/sodalive_/src/main/kotlin/kr/co/vividnext/sodalive/v2/api/event/application/EventDetailService.kt:45)는 [GetEventResponse.kt:13](/Users/klaus/Develop/sodalive/Server/sodalive_/src/main/kotlin/kr/co/vividnext/sodalive/event/GetEventResponse.kt:13)의 `id`, `thumbnailImageUrl`, `detailImageUrl`, `popupImageUrl`, `link`만 반환함. HTTPS 보존, 그 외 CDN 접두사는 기존 Service와 같고 nullable 이미지·link를 보존함. 외부 link에 HTTP 요청·리다이렉트하지 않으며 엔티티를 수정하지 않음. |
| EVT-004·005: 실패 envelope·보안 경계 | 양수 아님·미존재·비노출은 같은 `SodaException(common.error.invalid_request)`를 사용하며 [SodaExceptionHandler.kt:26](/Users/klaus/Develop/sodalive/Server/sodalive_/src/main/kotlin/kr/co/vividnext/sodalive/common/SodaExceptionHandler.kt:26)의 HTTP 200 실패 envelope 유지. 비숫자·Long 초과는 기존 바인딩·공통 오류 처리 유지. [SecurityConfig.kt:191](/Users/klaus/Develop/sodalive/Server/sodalive_/src/main/kotlin/kr/co/vividnext/sodalive/configs/SecurityConfig.kt:191)는 GET과 단일 segment `*`만 허용하며 쓰기·collection·추가 하위 경로·팝업·관리자 경로는 기존 인증 규칙 적용. JWT 필터를 생략하는 설정이 아니므로 기존 잘못된 JWT 처리 경로도 유지됨. |
핵심 테스트: [EventDetailControllerIntegrationTest.kt:74](/Users/klaus/Develop/sodalive/Server/sodalive_/src/test/kotlin/kr/co/vividnext/sodalive/v2/api/event/EventDetailControllerIntegrationTest.kt:74)의 응답 완전 비교·DB 재조회, `:165`의 성인 행렬, `:212`의 관리자 비노출, `:244`의 ID 오류, `:271`의 인접 보안 검증을 읽었다. RANDOM_PORT/TestRestTemplate은 실제 HTTP, 인증 MockMvc는 동일 컨텍스트와 실제 H2 member/auth/event fixture를 사용한다. 서비스·repository·인증 기록을 mock으로 대체하지 않으며 S3Uploader만 mock이다.
## 3. 검토한 실행 증거
아래는 기존 실행 결과의 확인이며 이 리뷰에서 실행한 테스트가 아니다.
| 출처 | 결과 및 확인 범위 |
|---|---|
| [신규 suite XML:2](/Users/klaus/Develop/sodalive/Server/sodalive_/build/test-results/test/TEST-kr.co.vividnext.sodalive.v2.api.event.EventDetailControllerIntegrationTest.xml:2) 직접 열람 | 2026-10-28T10:19:56, 28 tests, failures/errors/skipped 모두 0. testcase 목록과 실제 HTTP·MockMvc `system-out` 확인. |
| 같은 XML의 실제 응답 직접 열람 | `:10378` 익명 200·정확한 5필드·nullable 이미지·외부 link 보존. `:6484`, `:7407` 인증 일반 회원의 false 이벤트 거부. `:13745` 이후 관리자 비활성·미래·종료·언어 불일치 모두 동일 실패. `:10026`~`:10326`의 인접 보안 13건 모두 401. `:4568` 양수 아닌 ID도 HTTP 200, `success=false`, `data=null`, 기존 메시지 확인. |
| 기존 회귀 XML 직접 열람 | `EventControllerIntegrationTest` 5, `EventRepositoryTest` 5, `EventServiceTest` 4, `AdminEventBannerControllerIntegrationTest` 4건. 각 `build/test-results/test/TEST-kr.co.vividnext.sodalive.<클래스 전체 이름>.xml`의 testsuite/testcase를 확인했으며 합계 18건 모두 failures/errors/skipped 0. |
| 부모 세션 제공 전체 suite 증거 | `./gradlew test --console=plain --no-daemon -Pkotlin.compiler.execution.strategy=in-process`: BUILD SUCCESSFUL, 19m 29s, 326 suites / 2584 tests / failures/errors/skips 0. 전체 집계는 부모 제공 증거이며 이 리뷰에서 재집계하지 않음. |
| 부모 세션 제공 빌드·린트 증거 | `bootJar` 성공, `ktlintCheck`는 CsvSource 줄바꿈 수정 후 성공. Kotlin production/test compile 성공을 대체 진단 증거로 사용하며 LSP 성공으로 표현하지 않음. |
## 4. 발견 사항과 검증 한계
**확정 발견 사항 없음.** 승인된 EVT-001~005를 위반하는 구체 사례나 차단할 회귀를 발견하지 못했다. 회귀 수정 Task/goal 전환 항목 없음.
- 정확히 같은 시각의 기간 경계는 고정 시계 실행 테스트가 아니라 기존 QueryDSL 포함 비교와 신규 거부 조건의 코드 대조로 확인했다. 계획에서 허용한 검증 방식이며 현재 비교 연산에 결함은 없다.
- 인증 viewer는 JWT 발급·전송을 포함한 별도 실제 HTTP가 아니라 인증 MockMvc와 실제 DB fixture로 검증됐다. 이는 승인된 S2 검증 표면이며 기존 JWT 필터 경로는 코드로 확인했다.
- `lsp_diagnostics`는 부모와 이 리뷰 환경에 도구가 없어 미실행이다. 이는 진단 도구의 제한이지 확인된 코드 결함이 아니다. 테스트·빌드·린트 성공은 위에 출처를 구분해 기록했으며 재실행하지 않았다.
## 5. 리뷰 종료 판정과 정리
| 항목 | 결과 |
|---|---|
| 승인 요구사항·구현·보안·테스트 범위 확인 | 충족 |
| 발견 사항 판정 / plan 전환 | 확정 발견 사항 없음 / 해당 없음 |
| 실행 증거와 미검증 부분 구분 | 충족 |
| 최종 결론 | **APPROVE**. 이 구현의 반영을 차단할 항목 없음 |
이 판정은 구현과 제공된 증거에 대한 승인이다. 부모 소유의 P1-GATE 체크박스·상단 상태나 부모 QA 자원의 최종 정리 상태를 대신 갱신·인증하지 않는다.
**Teardown Receipt:** 이 리뷰에서 shell·테스트·빌드·서버·에이전트를 실행하지 않았고 소유 임시 root/프로세스를 생성하지 않았다. 정리 대상 0, 남은 리뷰 소유 자원 0. 공유 캐시 삭제 없음. 저장소 변경은 이 리뷰 파일뿐이다.
@@ -1,65 +0,0 @@
# 최근 공지사항 v2 API 계약
## 1. 요청
| 항목 | 계약 |
|---|---|
| Method / Path | `GET /api/v2/notices/latest` |
| 접근 | 인증 없이 허용, Authorization 필수 아님 |
| 입력 | path 변수·query·body 없음 |
| 성공 | HTTP 200, JSON `ApiResponse<List<NoticeItem>>` |
| 페이지네이션 | 없음. 항상 최대 3개, page/size/total/hasNext 없음 |
## 2. 데이터 규칙
`isActive=true`인 공지만 id 내림차순으로 최대 3개 반환한다. createdAt 최신순이 아니다. 기존 `NoticeItem`과 목록 쿼리를 재사용하며 아래 필드는 변경하지 않는다.
| 필드 | 타입 | 의미 |
|---|---|---|
| id | JSON number / Kotlin Long | 기존 공지 식별자 |
| title | string | 원래 제목 전체 |
| content | string | 원래 본문 전체, 축약·변환하지 않음 |
| date | string | 기존 UTC createdAt을 Asia/Seoul로 변환한 `yyyy-MM-dd` |
UTC `2026-10-27 15:00:00`은 `2026-10-28`이다. 날짜 formatter·timezone·필드 이름·타입을 새로 정의하지 않는다.
## 3. 성공 envelope와 예시
공통 `ApiResponse`는 success/message/data/errorProperty 네 필드를 모두 갖는다. 성공의 `success=true`, data는 null이 아닌 0~3개 배열이며 `message:null`, `errorProperty:null`이 생략되지 않고 포함된다. 2026-10-28 focused 실제 HTTP 테스트 11개에서 전체 JSON tree 비교로 확인했다. 전역 Jackson 설정은 변경하지 않는다.
```json
{
"success": true,
"message": null,
"data": [
{"id": 104, "title": "서비스 안내", "content": "공지 본문 전체\n두 번째 줄", "date": "2026-10-28"},
{"id": 103, "title": "점검 안내", "content": "점검 안내 전체", "date": "2026-10-27"},
{"id": 102, "title": "업데이트 안내", "content": "업데이트 안내 전체", "date": "2026-10-26"}
],
"errorProperty": null
}
```
활성 공지가 없으면 (전부 비활성인 경우 포함):
```json
{"success":true,"message":null,"data":[],"errorProperty":null}
```
활성 공지가 1개 또는 2개면 실제 개수만 반환하며 채우거나 반복하지 않는다. 예시 id는 설명용이며 고정 데이터나 실제 배포 응답이 아니다.
## 4. 호환성과 오류
- 기존 `GET /notice/latest`는 기존 단일 객체 또는 `data:null` 계약을 유지한다. 홈 응답도 그대로다.
- 새 permitAll은 정확한 GET 경로 하나에만 적용한다. 실제 HTTP 검증에서 익명 `POST /api/v2/notices/latest`와 `GET /api/v2/notices/private`는 HTTP 401이었다. 기존 보안 오류 응답은 아래와 같이 성공 envelope와 다르다. timestamp 값은 요청마다 달라진다.
```json
{"timestamp":"2026-10-28T06:28:16.011+00:00","status":401,"error":"Unauthorized","path":"/api/v2/notices/latest"}
```
- 기존 공통 오류 처리의 `ApiResponse.error`는 `success=false`다. 일부 공통 예외는 HTTP 200에도 오류 envelope가 오므로 클라이언트는 HTTP 상태와 success를 함께 확인한다. HTTP/보안 오류가 모두 같은 envelope라고 가정하지 않는다.
- 조회 실패를 정상 `[]`로 바꾸지 않는다. 새 오류 코드·status·전역 예외 정책·자동 fallback은 추가하지 않는다.
## 5. 제공 상태
구현 및 focused 실제 HTTP 검증 완료(공지 11개와 기존 배포 엔드포인트 4개, 총 15 tests, failures/errors/skipped 모두 0). `bootJar`와 전체 `ktlintCheck`는 통과했으나 전체 `build --continue`는 test 단계에서 20분 제한으로 종료되어 최종 Gate는 미완료다. 실응답·명령 결과와 독립 리뷰 상태는 [plan-task.md](plan-task.md)에 기록했다. 운영 배포는 수행하지 않았으며 배포 완료로 간주하지 않는다.
@@ -1,22 +0,0 @@
# 클라이언트 전달용 프롬프트
아래 내용을 클라이언트 작업자에게 전달한다. 서버 코드 구현·로컬 검증과 실제 배포는 별개다.
```text
기존 공지 UI, 레이아웃, 스타일, 진입점, 상세 이동과 내비게이션을 유지하면서 최근 공지 데이터만 아래 새 계약으로 연결해 주세요. UI 재설계나 캐러셀 추가는 하지 마세요.
API: 익명 GET /api/v2/notices/latest
요청 body/query와 인증 필수 요구는 없습니다.
응답: ApiResponse<List<NoticeItem>>
NoticeItem: id(number), title(string), content(string), date(string, yyyy-MM-dd).
data는 활성 공지 중 id 내림차순 최대 3개입니다. 순서를 다시 정렬하지 말고 서버 순서를 사용하세요. date는 이미 기존 UTC→Asia/Seoul 규칙으로 포맷된 문자열이므로 다시 timezone 변환하지 마세요. title/content는 전체 문자열을 유지하세요.
활성 공지가 없으면 data:[]이며 null이 아닙니다. 1/2개면 해당 개수만 표시하고 3개를 채우려고 중복하지 마세요. 기존 단일 공지 v1과 홈 응답 스키마는 변경되지 않습니다.
서버 배포가 확인되기 전에는 개발 환경의 명시적 mock 모드로만 작업하세요. 이 서버 작업은 운영 배포를 수행하지 않습니다. 실제 404/오류를 mock이나 v1로 자동 fallback하지 말고, 배포 후 명시적으로 API 연결을 전환하세요. production mock은 금지합니다.
공통 envelope의 success를 HTTP 상태와 함께 검사하세요. 성공 응답에는 message:null과 errorProperty:null이 생략 없이 포함됩니다(실제 HTTP 검증 완료). 기존 정책상 HTTP 200에도 success:false가 올 수 있습니다. 조회 실패를 정상 빈 목록으로 숨기지 말고 기존 화면의 오류 처리와 로딩 상태를 유지하세요. 보안/HTTP 오류가 모두 동일한 envelope라고 가정하지 마세요.
0/1/2/3개 fixture를 각각 테스트하세요. 0개일 때 기존 빈 상태, 1/2개일 때 중복 없음, 3개일 때 id 역순 유지, 상세 이동 시 동일 id/전체 본문 보존을 확인하세요. 긴 제목·여러 줄 본문·KST 날짜 경계도 기존 UI 안에서 확인하세요.
범위 밖: 캐러셀, 자동 fallback, 캐싱, 페이지네이션, 홈 응답 변경, 기존 내비게이션 변경.
계약: docs/20261028_최근공지사항_v2/api-contract.md
```
@@ -1,165 +0,0 @@
# 최근 공지사항 v2 구현 계획
> 실행 방식: 승인된 설계를 기존 작업 디렉터리에서 TDD로 구현하고 독립 검토한다. 새 worktree·commit·배포는 수행하지 않는다. 전체 테스트는 최종 Gate에서 실행한다.
| 항목 | 내용 |
|---|---|
| 작성일 | 2026-10-28 |
| 상태 | P1-T1 완료, P1-GATE 전체 회귀 시간 초과로 미완료, 미배포 |
| 요구사항 | [prd.md](prd.md) |
| API 기준 | [api-contract.md](api-contract.md) |
| 현재 Phase / 활성 Goal | Phase 1 / P1-GATE 전체 회귀 결과 확보 필요 |
**Goal:** 기존 v1·홈을 유지하면서 누구나 최근 활성 공지를 최대 3개 조회한다.
**Architecture:** 새 web controller → 읽기 전용 application service → 기존 repository 목록 쿼리. 쿼리·DTO·공통 JSON 정책은 유지한다.
**Tech Stack:** Kotlin 1.6.21, Java 17, Spring Boot 2.7.14, JUnit 5, H2, embedded Redis, TestRestTemplate.
## 전역 제약과 리뷰 초점
- 새 GET 한 경로만 permitAll로 허용한다. 주변 경로나 다른 메서드를 공개하지 않는다.
- `NoticeItem(id: Long, title: String, content: String, date: String)` 및 UTC→Asia/Seoul `yyyy-MM-dd`를 보존한다.
- createdAt이 id 순서와 반대여도 id로 정렬하며 비활성 최신 id를 제외한다.
- 빈 배열, 1/2개 배열, 전체 본문, KST 자정, v1 객체/null을 HTTP로 검증한다.
- 외부 서비스·운영 앱·스키마·의존성·UI·캐시·신규 추상화는 범위 밖이다.
### Phase 1: 최근 공지 v2 수직 슬라이스
- [x] **Task 1.1: P1-T1 실제 HTTP 조회 구현**
**Objective:** 익명 GET의 배열 계약과 기존 호환성을 실제 HTTP/DB 왕복으로 검증한다.
**시작 조건:** 사용자 승인 설계, PRD와 이 계획 작성 완료.
**완료 증거:** 의도한 RED, focused GREEN, 실응답 관찰, 계약과 검증 기록, 소유 임시 리소스 정리.
**범위 밖:** 전체 테스트·빌드·독립 리뷰는 P1-GATE 소유이며 배포는 전체 작업 범위 밖이다.
**Files:**
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/notice/application/LatestNoticeService.kt`
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/notice/adapter/in/web/LatestNoticeController.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/configs/SecurityConfig.kt`의 기존 notice 규칙 바로 옆 GET matcher 한 줄
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/notice/LatestNoticeControllerIntegrationTest.kt`
- Docs: 이 폴더의 `prd.md`, `plan-task.md`, `api-contract.md`, `client-prompt.md`
**Interfaces:**
- Consumes: `ServiceServiceNoticeRepository.getNoticeList(pageable: Pageable): List<NoticeItem>`
- Produces: `LatestNoticeService.getLatestNotices(): List<NoticeItem>`는 `PageRequest.of(0, 3)` 사용
- HTTP: `LatestNoticeController.getLatestNotices()`는 `ApiResponse.ok(service.getLatestNotices())` 반환
- [x] **RED:** RANDOM_PORT/TestRestTemplate/실제 repository·SecurityConfig, 고유 H2, 기존 날짜 alias, EmbeddedRedisInitializer, AFTER_CLASS DirtiesContext로 테스트 작성. 아직 없는 controller 타입은 참조하지 않는다.
- [x] **RED 확인:** 아래 focused 명령으로 미허용·미구현 GET의 `expected 200, actual 401` 같은 HTTP assertion 실패를 확인하고 기록한다. 컴파일/인프라 실패는 RED로 세지 않는다.
- [x] **GREEN:** production 2개 파일과 정확한 GET matcher 한 줄만 추가한다.
- [x] **GREEN 확인:** 동일 focused 명령으로 4+활성·비활성·id 정렬·본문·KST 경계·0/1/2·v1·권한 테스트가 통과하는지 확인한다.
- [x] **REFACTOR:** 불필요한 정리 없이 focused 회귀와 diff 점검, HTTP 출력 및 문서 정합성 기록을 남긴다.
```bash
./gradlew --no-daemon test --tests kr.co.vividnext.sodalive.v2.api.notice.LatestNoticeControllerIntegrationTest
./gradlew --no-daemon tasks --all
git diff --check
```
**Expected:** focused 테스트 실패 0, HTTP 200 + data 배열, 익명 POST/인접 경로 401, v1 객체/null, 명령 유효성 검증 exit 0.
#### Phase 1 Gate: P1-GATE
**Objective:** 최종 전체 회귀·빌드·독립 리뷰로 전달 가능 상태를 판정한다.
**시작 조건:** P1-T1 증거와 리소스 정리 완료.
**완료 증거:** 전체 테스트·빌드 exit 0, 독립 리뷰 결과와 잔여 위험 기록.
**범위 밖:** 실패를 숨기는 test 삭제·완화, 무관한 수정·배포.
- [ ] **[blocked] 전체 회귀 완료:** `./gradlew --no-daemon build --continue`의 전체 `test`가 20분 제한으로 종료됐다. 충분한 실행 시간이 확보된 환경에서 전체 테스트 exit 0을 확인하기 전 Gate는 완료하지 않는다.
- [x] `./gradlew --no-daemon bootJar ktlintCheck`로 패키징과 전체 lint를 검증한다.
- [x] 공지 HTTP 11개와 기존 배포 엔드포인트 HTTP 4개를 함께 재실행해 15개 통과를 확인한다.
- [x] [독립 리뷰](reviews/implementation-review.md)의 규격 적합·코드/테스트 품질 승인과 확정 발견 사항 없음을 기록한다. 이는 전체 회귀 Gate 통과나 배포 승인이 아니다.
- [x] 미배포임을 명시한다. 배포 자체는 작업 범위 밖이다.
## 실행 자원과 정리 의무
- 소유 임시 root: `/var/folders/yh/8xsbvpsj5wg2qnxzxdp11_gm0000gn/T/opencode/notice-v2-impl.thzdr5`
- 모든 shell은 `TMPDIR`를 위 root로, `NODE_COMPILE_CACHE=$TMPDIR/node-compile-cache`, `BUN_RUNTIME_TRANSPILER_CACHE_PATH=$TMPDIR/bun-transpiler`로 export한다.
- Gradle은 `--no-daemon`을 사용한다. 테스트 context는 AFTER_CLASS에 닫고 embedded Redis는 기존 initializer의 JVM 종료 hook으로 종료한다.
- [x] 보고 전 이 실행의 소유 프로세스가 종료됐는지 확인하고 위 root만 삭제한다. 공유 캐시·다른 실행자의 파일과 프로세스는 건드리지 않는다.
- LSP 도구는 현재 host에 없어 실행할 수 없다. focused Kotlin 컴파일 결과를 기록하되 LSP 검증으로 표현하지 않는다.
## Progress
### P1-T1 시작: 2026-10-28
- `test` 브랜치 초기 `git status --short --branch`: 변경 없음.
- 루트 AGENTS, 필수 agent guides, PRD/계획 샘플, TDD `writing-good-tests.md` 및 기존 쿼리·v1·홈·HTTP 테스트를 확인했다.
- 첫 baseline: `./gradlew --no-daemon test --tests kr.co.vividnext.sodalive.deployment.DeploymentEndpointIntegrationTest`는 120초 tool timeout으로 종료. 테스트 결과 XML이 없어 성공/RED로 판정하지 않는다. 원인 관찰을 위해 `--info`와 600초 제한으로 재시도한다.
- 이 단계에서 production 코드 변경은 없다.
### P1-T1 baseline 및 RED 작성: 2026-10-28
- `./gradlew --no-daemon test --tests kr.co.vividnext.sodalive.deployment.DeploymentEndpointIntegrationTest --info`: exit 0, 4 tests / 0 failures / 0 errors, 2m33s. 기존 HTTP/보안 테스트 기반 동작 확인.
- 관찰: 기존 translation/charge 스케줄러가 H2에서 `for update skip locked` 문법 오류를 로그로 남긴다. baseline에서도 발생했으며 이 범위에서 수정하지 않는다.
- fixture는 실제 repository로 저장·flush한 뒤 별도 JDBC 갱신으로 createdAt을 고정한다. BaseEntity의 PrePersist가 현재 시각으로 덮어쓰므로 이 순서가 필요하다. 서버의 조회는 별도 HTTP thread/DB 왕복이다.
- 전체 JSON tree를 literal 기대값과 비교해 null 필드 포함 여부·필드 이름·본문·날짜까지 확인한다. 생성된 id만 실제 저장 결과를 사용한다.
### P1-T1 RED 확인: 2026-10-28
- production 코드 추가 전 `./gradlew --no-daemon test --tests kr.co.vividnext.sodalive.v2.api.notice.LatestNoticeControllerIntegrationTest` 실행: exit 1, 3m42s, 11 tests / 7 failures / 0 errors / 0 skipped.
- 7개 v2 GET 검증이 모두 `expected: <200 OK> but was: <401 UNAUTHORIZED>` HTTP assertion으로 실패했다. Kotlin 컴파일과 로컬 H2/Redis/서버 초기화는 성공했다.
- 기존 v1 객체/null 및 익명 POST/인접 경로 거부의 나머지 4개 검증은 통과했다.
- RED 실응답: `HTTP GET /api/v2/notices/latest -> 401 {"timestamp":"2026-10-28T06:18:18.170+00:00","status":401,"error":"Unauthorized","path":"/api/v2/notices/latest"}`.
- 당시 XML: `build/test-results/test/TEST-kr.co.vividnext.sodalive.v2.api.notice.LatestNoticeControllerIntegrationTest.xml`. 다음 Gradle test 실행이 덮어쓰므로 실패 수와 핵심 응답을 이 문서에 보존한다.
### P1-T1 GREEN 및 HTTP 응답 관찰: 2026-10-28
- `./gradlew --no-daemon test --tests kr.co.vividnext.sodalive.v2.api.notice.LatestNoticeControllerIntegrationTest`: exit 0, 9m11s, 11 tests / 0 failures / 0 errors / 0 skipped. production/test Kotlin 컴파일도 실행·성공했다. 이 결과는 전체 `build` 성공을 뜻하지 않는다.
- 실제 HTTP 출력은 테스트의 `println`과 XML `<system-out>`에 남긴다. 확인한 artifact: `build/test-results/test/TEST-kr.co.vividnext.sodalive.v2.api.notice.LatestNoticeControllerIntegrationTest.xml`, HTML: `build/reports/tests/test/index.html`. 다음 테스트 실행으로 덮어쓸 수 있어 아래 핵심 응답을 보존한다.
- 익명 GET의 3개 응답은 id 12/11/10이며 date는 2026-10-28/2026-10-28/2026-10-29여서 createdAt 최신순이 아님을 확인했다. 더 큰 비활성 id는 제외됐다. HTML 모양 텍스트·인용부호·줄바꿈을 포함한 본문도 전체 일치했다.
- UTC 14:59:59/15:00:00의 KST 날짜, 0/1/2개, 전부 비활성, v1 객체/null, 익명 POST/인접 GET의 401을 모두 실서버 응답으로 확인했다. message/errorProperty의 명시적 null 포함도 JSON tree 완전 비교로 확정했다.
- 코드 정리로 바꿀 중복이 없어 REFACTOR production 수정은 하지 않았다. `git diff`에서 기존 notice/home 변경은 없고 SecurityConfig는 GET matcher 한 줄뿐이다.
```text
HTTP GET /api/v2/notices/latest -> 200 {"success":true,"message":null,"data":[{"id":12,"title":"최근 서비스 공지","content":"서비스 공지\n두 번째 줄: <b>전체 본문</b> & \"인용\"","date":"2026-10-28"},{"id":11,"title":"세 번째 공지","content":"본문 3","date":"2026-10-28"},{"id":10,"title":"두 번째 공지","content":"본문 2","date":"2026-10-29"}],"errorProperty":null}
HTTP GET /api/v2/notices/latest -> 200 {"success":true,"message":null,"data":[],"errorProperty":null}
HTTP GET /notice/latest -> 200 {"success":true,"message":null,"data":null,"errorProperty":null}
HTTP POST /api/v2/notices/latest -> 401 {"timestamp":"2026-10-28T06:28:16.011+00:00","status":401,"error":"Unauthorized","path":"/api/v2/notices/latest"}
HTTP GET /api/v2/notices/private -> 401 {"timestamp":"2026-10-28T06:28:16.112+00:00","status":401,"error":"Unauthorized","path":"/api/v2/notices/private"}
```
## 검증 기록
전체 테스트·빌드·독립 리뷰는 사용자 지정 역할 분담에 따라 이 실행에서 생략하고 P1-GATE에 남긴다. 테스트 클래스 추가에 대한 단일 실행 예시는 위 focused 명령을 사용한다.
- `./gradlew --no-daemon tasks --all`: exit 0, 31s. 문서의 `test`/`build`/관련 Gradle 명령이 등록됐음을 확인했다.
- `git diff --check`: exit 0. 신규 파일은 read 도구로 확인하고 변경 범위 목록을 `git status --short --untracked-files=all`로 점검했다.
- PRD의 NOTICE-001~005는 모두 P1-T1의 HTTP 검증으로 연결된다. v1/home는 코드 diff가 없고 v1은 HTTP 회귀도 확인했다. 홈 전체 응답을 호출하는 별도 회귀는 이 실행에서 수행하지 않았다.
- LSP 진단 도구 미제공, lint·전체 테스트·전체 빌드·독립 리뷰·운영 MySQL·배포 검증은 미실행이다.
- 기존 관찰 사항: H2에서 translation/charge 스케줄러의 `skip locked` 오류 로그가 GREEN에도 남는다(테스트 실패는 0). 기존 다른 테스트의 불필요 `!!`/unchecked cast 컴파일 경고, Netty macOS resolver 및 Gradle deprecation 경고도 이 범위에서 수정하지 않았다.
### P1-T1 정리 영수증 및 인계: 2026-10-28
- GREEN XML에서 Tomcat 종료와 HikariPool shutdown completed를 확인했다. Gradle test JVM도 종료됐고 프로세스 목록에 이 실행의 test worker, Redis, Kotlin compile daemon, Gradle 8.1.1 daemon은 남아 있지 않다.
- 별도 실행자의 기존 Gradle 8.14.3 daemon(pid 49992)은 소유 대상이 아니므로 종료하지 않았다.
- 소유 root가 빈 디렉터리임을 확인하고 `rmdir "$TMPDIR" && test ! -e "$TMPDIR"` 실행: exit 0. 삭제한 root는 위 `notice-v2-impl.thzdr5` 하나뿐이며 공유 캐시는 변경하지 않았다.
- P1-T1은 focused 증거와 자원 정리까지 완료했다. 전체 테스트·빌드·독립 리뷰와 운영 배포 판단은 부모 실행자의 P1-GATE로 남긴다.
### P1-GATE 실행: 2026-10-28
- `./gradlew --no-daemon build --continue`: `bootJar`/`assemble` 완료 후 전체 `:test` 단계에서 도구의 1,200,000ms 제한으로 종료됐다. 전체 테스트 수·성공 여부를 판정할 최종 결과는 없으며 전체 build 성공으로 표시하지 않는다. 원인이 특정 테스트 실패인지 단순 소요 시간인지 이 실행으로 확정하지 못했다.
- `./gradlew --no-daemon bootJar ktlintCheck`: exit 0, `BUILD SUCCESSFUL in 59s`. 산출물은 `build/libs/sodalive-0.0.1-SNAPSHOT.jar`이며 main/test/script 전체 ktlint를 통과했다.
- `./gradlew --no-daemon test --tests kr.co.vividnext.sodalive.v2.api.notice.LatestNoticeControllerIntegrationTest --tests kr.co.vividnext.sodalive.deployment.DeploymentEndpointIntegrationTest`: exit 0, `BUILD SUCCESSFUL in 3m 29s`. 두 XML에서 11+4=15 tests, failures/errors/skipped 모두 0을 확인했다.
- 최신 공지 HTTP XML timestamp는 `2026-10-28T06:57:06`, 기존 배포 HTTP XML timestamp는 `2026-10-28T06:56:23`이다. `TestRestTemplate`가 RANDOM_PORT 실서버에 요청했으며, 공지 응답의 id 12/11/10 순서·전체 필드·빈 배열·KST 날짜와 v1 객체/null, 익명 POST/인접 GET 401을 출력 및 전체 JSON 비교로 재검증했다.
- XML에서 세 테스트 서버의 `Stopping service [Tomcat]`를 확인했다. 최종 소유 자원 부재 확인은 아래 정리 기록에 남긴다.
- LSP 도구는 제공되지 않아 실행하지 못했다. Kotlin 컴파일·ktlint 성공을 LSP 실행으로 대신 표기하지 않는다. 운영 MySQL·배포·클라이언트 앱 검증은 범위 밖이다.
- 최초 독립 리뷰는 완료 알림 후 결과 조회 오류와 세션 미발견으로 판정 내용을 복구하지 못했다. 근거 없는 승인으로 처리하지 않고, 대체 독립 리뷰를 파일로 기록하도록 요청했다.
- 대체 독립 리뷰 결과: 규격 적합, 코드/테스트 품질 승인, 확정 발견 사항 없음. [implementation-review.md](reviews/implementation-review.md)에 검토 근거와 한계를 기록했다. 이후 production/test 변경은 없으며 위 15개 HTTP 재실행 결과를 이 계획에 보완했다.
- 최종 `git diff --check`: exit 0. 전체 회귀 제한을 숨기기 위한 테스트 변경·삭제·skip은 없다. commit/push/worktree 생성/배포는 수행하지 않았다.
### P1-GATE 소유 자원 정리: 2026-10-28
- 최신 HTTP XML에서 Tomcat 종료를 확인했고, 실행 후 프로세스 목록에 이 작업의 Gradle/test worker/Redis는 남아 있지 않았다. 별도 실행자의 기존 Java 프로세스는 종료하지 않았다.
- 빈 하위 `opencode/`와 검증 root `notice-v2.xbE00p`를 `rmdir`로 삭제했다. `test ! -e`로 검증 root, 구현 root `notice-v2-impl.thzdr5`, 작업 노트의 부재를 확인했다(exit 0).
- 승인된 임시 상위 디렉터리를 다시 읽어 `notice-v2` 실행/리뷰 root가 남아 있지 않음을 확인했다. 공유 캐시와 다른 작업의 디렉터리는 보존했다. 대체 리뷰어는 shell/임시 자원을 생성하지 않았다.
- 최종 상태: 구현과 로컬 HTTP 15개·패키징·lint·독립 코드 리뷰는 완료. **전체 회귀는 시간 초과로 미검증이며 P1-GATE는 보류**다. 재개 시 이미 완료한 구현을 반복하지 말고 충분한 실행 시간의 환경에서 전체 테스트 종료 결과를 확보한다.
@@ -1,48 +0,0 @@
# 최근 공지사항 v2 PRD
## 문서 정보
| 항목 | 내용 |
|---|---|
| 상태 | 구현·HTTP 15개·패키징·lint 검증 완료, 전체 회귀 시간 초과로 최종 Gate 미완료, 미배포 |
| 작성일 | 2026-10-28 |
| 결정권자 | 요청 사용자 |
| 계약 | [api-contract.md](api-contract.md) |
| 구현 계획 | [plan-task.md](plan-task.md) |
| 클라이언트 전달 | [client-prompt.md](client-prompt.md) |
## 목표와 문제
기존 `/notice/latest`는 공지 하나 또는 null을 반환한다. 이 계약과 홈 응답을 유지하면서 클라이언트가 최근 활성 공지 최대 3개를 익명으로 조회할 수 있는 별도 API를 제공한다. 최신은 작성 시각이 아니라 기존 공지 정책인 id 내림차순이다.
## 확정 요구사항과 수용 기준
| ID | 요구사항 | 수용 기준 | 추적 |
|---|---|---|---|
| NOTICE-001 | 익명 `GET /api/v2/notices/latest` | HTTP 200, `ApiResponse<List<NoticeItem>>` | 계약 §1, P1-T1 |
| NOTICE-002 | 활성 공지 중 id 내림차순 최대 3개 | 활성 4개 이상과 더 큰 비활성 id fixture에서 정확한 3개 반환, createdAt 정렬 금지 | 계약 §2, P1-T1 |
| NOTICE-003 | 기존 필드와 날짜 보존 | id/title/content/date 전체 일치, 본문 생략 없음, UTC→Asia/Seoul `yyyy-MM-dd` 날짜 경계 검증 | 계약 §2, P1-T1 |
| NOTICE-004 | 적은 데이터도 배열 | 0/1/2개 및 전부 비활성 시 각각 0/1/2개와 빈 배열 | 계약 §3, P1-T1 |
| NOTICE-005 | 기존 동작·권한 보존 | v1 객체/null 유지, 익명 POST와 인접 보호 경로는 401 | 계약 §4, P1-T1 |
## 구현 제약과 제외
- Kotlin 1.6.21, Java 17, Spring Boot 2.7.14 및 기존 의존성을 사용한다.
- 신규 v2 controller와 읽기 전용 service가 기존 `ServiceServiceNoticeRepository.getNoticeList(PageRequest.of(0, 3))`를 호출한다. 기존 `NoticeItem`과 `ApiResponse`를 재사용한다.
- 공개 보안 허용은 정확히 새 GET 한 경로만 추가한다. 공지 본문은 기존 활성 공지의 공개 데이터이며 새 사용자·인증 데이터는 취급하지 않는다.
- v1 공지 함수, 홈 응답, 기존 repository 쿼리, DB 스키마, 공통 JSON·오류 정책과 의존성은 변경하지 않는다.
- UI·캐러셀·자동 fallback·캐시·페이지네이션·신규 DTO·port·범용 facade·배포는 제외한다.
## 검증과 배포 상태
실제 SecurityConfig, RANDOM_PORT HTTP 서버, TestRestTemplate, 실제 repository, 로컬 H2와 embedded Redis로 통합 검증한다. 새 구현 클래스 참조 없이 HTTP로 먼저 실패를 확인한다. H2는 기존 MySQL 날짜 함수 alias로 쿼리를 실행하며 운영 MySQL 실검증은 별도다.
공지 HTTP 11개와 기존 배포 엔드포인트 HTTP 4개가 통과했고, `bootJar`와 전체 `ktlintCheck`가 성공했다. 전체 `build --continue`는 test 단계에서 20분 제한으로 종료되어 전체 회귀는 미검증이다. 최종 Gate 상태와 독립 리뷰는 구현 계획에 기록한다. 구현·로컬 검증은 배포 완료를 뜻하지 않으며 클라이언트는 배포 확인 전 명시적 mock을 사용한다.
## Decision Log
| 날짜 | ID | 결정 | 근거 |
|---|---|---|---|
| 2026-10-28 | NOTICE-D1 | 기존 목록 쿼리를 page 0/size 3으로 호출 | 기존 쿼리에 활성 필터·id 역순·offset/limit·날짜 projection이 존재 |
| 2026-10-28 | NOTICE-D2 | 기존 v1과 홈은 전혀 수정하지 않음 | 사용자 승인 범위 및 객체/null 호환성 |
| 2026-10-28 | NOTICE-D3 | 전체 Gate는 부모 실행자가 수행 | 명시적 작업 분담, 이 작업은 focused HTTP 검증까지만 수행 |
@@ -1,62 +0,0 @@
# 최근 공지사항 v2 구현 리뷰
## 1. 리뷰 정보와 범위
| 항목 | 내용 |
|---|---|
| 대상 | 2026-10-28 작업 트리의 P1-T1 구현 및 P1-GATE 독립 리뷰 부분 |
| 리뷰어 / 상태 | 독립 리뷰 에이전트 / 판정 완료 |
| 기준 | [PRD](../prd.md)의 NOTICE-001~005, [계획](../plan-task.md), [API 계약](../api-contract.md), [클라이언트 전달문](../client-prompt.md), [리뷰 샘플](../../sample/sample-review.md) |
| 방법 | 신규 controller/service, SecurityConfig, 통합 테스트, 기존 repository/DTO/v1 및 홈 호출 경로를 읽기 전용 대조 |
| 제외 | 코드·테스트 수정, 명령·테스트·실서버 재실행, 운영 MySQL·배포 검증 |
이전 리뷰 결과는 회수되지 않아 재사용하지 않았다. 이번 판정은 현재 파일을 직접 읽은 정적 검토와 부모 실행자가 전달한 실행 증거를 구분한다. Git SHA/diff는 이번 리뷰에서 독립 확인하지 않았으며, 기존 파일의 변경 없음은 부모의 diff 관찰을 함께 근거로 삼았다.
## 2. 판정 기준과 계약 대조
확정 계약 위반·보안 노출·주요 회귀는 수정 필요 항목으로 판정한다. 재현 조건과 코드·테스트 근거가 없는 추측이나 공개된 환경 한계는 코드 결함으로 올리지 않는다. 아래 경로는 저장소 루트 기준이며 숫자는 줄 번호다.
| 기준 | 판정 및 근거 |
|---|---|
| NOTICE-001: 익명 GET 및 배열 envelope | 적합. `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/notice/adapter/in/web/LatestNoticeController.kt:10`의 경로와 `:13`의 `ApiResponse.ok`가 목록을 직접 반환한다. `src/main/kotlin/kr/co/vividnext/sodalive/common/ApiResponse.kt:3`의 기존 네 필드를 재사용한다. |
| NOTICE-002: 활성·id DESC·DB 최대 3개 | 적합. `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/notice/application/LatestNoticeService.kt:12`가 `getNoticeList(PageRequest.of(0, 3))`를 호출한다. `src/main/kotlin/kr/co/vividnext/sodalive/notice/ServiceServiceNoticeRepository.kt:44`의 활성 필터, `:45`의 offset, `:46`의 DB limit, `:47`의 id 역순을 그대로 사용한다. 전체 조회 후 메모리 절단이나 totalCount 조회가 없다. |
| NOTICE-003: 필드·전체 본문·KST | 적합. `src/main/kotlin/kr/co/vividnext/sodalive/notice/GetNoticeResponse.kt:10`의 `NoticeItem(id: Long, title: String, content: String, date: String)`을 재사용한다. `ServiceServiceNoticeRepository.kt:36`은 원래 제목·본문을 projection하고 `:67`은 UTC→Asia/Seoul 및 `%Y-%m-%d`를 유지한다. 신규 변환·축약이 없다. |
| NOTICE-004: 0/1/2/3+ 및 전부 비활성 | 적합. service의 non-null 목록을 그대로 반환하므로 빈 목록도 `[]`이고 패딩·반복이 없다. 통합 테스트 `:59`, `:101`, `:110`, `:125`, `:142`가 활성 4개와 더 큰 비활성 id, 0/1/2개, 전부 비활성을 검증한다. |
| NOTICE-005: v1·홈·권한 보존 | 적합. `src/main/kotlin/kr/co/vividnext/sodalive/notice/ServiceNoticeController.kt:39` → `ServiceNoticeService.kt:51` → `ServiceServiceNoticeRepository.kt:51`은 단일/null 경로다. `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/home/AudioContentMainTabHomeService.kt:52`와 `GetContentMainTabHomeResponse.kt:13`도 기존 `NoticeItem?`를 유지한다. `src/main/kotlin/kr/co/vividnext/sodalive/configs/SecurityConfig.kt:194`는 정확한 GET 한 경로만 허용하고 `:214`의 나머지 인증 규칙을 유지한다. |
## 3. 코드·테스트 품질
- **품질 판정: 적합.** 읽기 전용 트랜잭션 service와 얇은 controller만 추가하며 기존 repository·DTO·envelope를 재사용한다. 신규 port·facade·캐시·페이지네이션·의존성·오류 fallback 등 불필요한 추상화가 없다.
- 테스트 기준 파일은 `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/notice/LatestNoticeControllerIntegrationTest.kt`다. `:26`의 RANDOM_PORT, `:33`의 embedded Redis, `:35`의 실제 repository/JDBC와 TestRestTemplate을 사용하며 controller/service를 mock하지 않는다. 파라미터 확장 포함 11건이다.
- `:193`은 실제 저장·flush 후 JDBC로 고정 시각을 저장한다. 이는 `src/main/kotlin/kr/co/vividnext/sodalive/common/BaseEntity.kt:29`의 PrePersist 덮어쓰기를 피하고 별도 HTTP 요청이 DB를 읽게 한다. `:185`는 상태와 전체 JSON tree를 비교하므로 null 필드 누락·추가 필드·본문 변형·배열 순서도 검출한다.
- `:59`의 id와 createdAt 역순 fixture, `:84`의 UTC 14:59:59/15:00:00 KST 경계, `:154`/`:171`의 v1 객체/null, `:176`의 POST·인접 GET 거부가 핵심 회귀를 덮는다. H2 날짜 alias는 기존 `src/test/kotlin/kr/co/vividnext/sodalive/support/H2MysqlDateFunctions.kt:10`을 사용하므로 운영 MySQL 검증과는 구분한다.
- 클라이언트 전달문도 배열·서버 순서·날짜 재변환 금지·미배포 시 명시적 mock·자동 fallback 금지를 계약과 일치하게 안내한다.
## 4. 실행 증거와 검증 한계
아래 실행 결과는 **부모 실행자가 실제 관찰하여 전달한 증거**다. 리뷰어는 명령, XML 또는 HTTP 호출을 재검증하지 않았다.
| 전달된 검증 | 결과와 한계 |
|---|---|
| focused RED | 11 tests / 7 failures. 미구현·미허용 v2 GET이 HTTP 401로 실패했으며 컴파일·인프라 실패를 RED로 세지 않았다. |
| focused GREEN XML | timestamp `2026-10-28T06:28:11`, 11 tests / 0 failures / 0 errors / 0 skipped. 전체 테스트 성공의 증거는 아니다. |
| 실제 HTTP 관찰 | v2 HTTP 200의 id 12/11/10 배열과 `[]`, v1 null/객체, 익명 POST 및 인접 GET의 401을 확인했다. 전체 필드·KST 경계는 위 focused 테스트와 계획의 응답 기록으로 연결된다. |
| `./gradlew --no-daemon bootJar ktlintCheck` | exit 0, 59초. 패키징·lint 성공이며 전체 `build` 성공으로 확대하지 않는다. |
| `./gradlew --no-daemon build --continue` | `:test`에서 1,200,000ms 후 타임아웃. **전체 테스트 및 전체 build 검증은 pending/blocked이며 P1-GATE 완료 불가.** 타임아웃 후 focused HTTP 재실행은 부모 담당 예정으로, 이 리뷰 시점에는 결과 미확인이다. |
LSP 도구는 미제공이다. 운영 MySQL의 실제 timezone 처리·배포 및 홈 전체 HTTP 응답 회귀는 미검증이다. 이 한계만을 이유로 무관한 코드 수정을 요구하지 않는다. 이번 리뷰는 shell·런타임 자원·임시 root를 생성하지 않았다.
## 5. 발견 사항과 후속 전환
**확정 발견 사항 없음.** 승인 계약과 검토 코드·테스트에서 수정이 필요한 결함을 확인하지 못했다. 신규 회귀 수정 Task/goal 전환 항목 없음.
## 6. 리뷰 종료 판정
**규격 판정: 적합. 코드·테스트 품질 판정: 승인(검토 범위 내). 독립 리뷰는 완료하되 최종 P1-GATE는 전체 회귀·전체 build 미확인으로 보류한다. 배포 승인을 뜻하지 않는다.**
남은 담당은 부모 실행자다. 타임아웃 후 focused HTTP 재실행 결과와 전체 회귀·전체 build의 종료 결과를 별도로 기록하고, 기존 문서의 Gate 상태·역할 표현을 최종 증거에 맞춰 정리한다. 이 리뷰에서는 다른 파일이나 완료 체크박스를 변경하지 않는다.
## 7. 실행자 후속 증거
- 2026-10-28: 리뷰와 독립적으로 공지·기존 배포 엔드포인트 HTTP 테스트를 함께 재실행했다. `./gradlew --no-daemon test --tests kr.co.vividnext.sodalive.v2.api.notice.LatestNoticeControllerIntegrationTest --tests kr.co.vividnext.sodalive.deployment.DeploymentEndpointIntegrationTest`가 exit 0, 3m29s로 끝났으며 XML은 11+4=15 tests, failures/errors/skipped 모두 0이다.
- production/test 수정 없이 문서의 현재 상태를 갱신했다. 전체 회귀의 시간 초과와 P1-GATE 보류는 그대로 유지한다. 이 기록은 리뷰어의 재실행 주장이 아니라 실행자의 추가 증거다.
@@ -1,5 +0,0 @@
-- 서버 배포 전에 적용한다. KO는 임시 기본 분류이며 JA 소재와 연결 이벤트 언어는 운영 담당자가 수동 확인한다.
-- lang 컬럼이 없는 기존 테이블에 한 번만 실행한다. 이미 존재하면 실행하지 않는다.
ALTER TABLE sub_banner
ADD COLUMN lang VARCHAR(10) NOT NULL DEFAULT 'KO'
COMMENT '서브 배너 노출 언어 (KO 기본, EN/JA 등록 가능)' AFTER is_active;
@@ -1,83 +0,0 @@
# 기존 관리자 서브 배너: 언어 선택만 추가하는 구현 프롬프트
## 목표와 범위
기존 관리자 프런트엔드의 서브 배너 목록·생성·수정·삭제 CRUD는 이미 구현되어 있다.
이 프롬프트만으로 기존 생성·수정 폼에 언어 선택을 추가하라. CRUD를 다시 만들거나 화면을 재설계하지 않는다.
특정 프레임워크를 가정하지 말고 작업 저장소의 기존 컴포넌트, 스타일, 폼 상태, 인증, API client, multipart 전송 방식을 재사용한다.
기존 화면·DTO·요청 직렬화·오류 처리·테스트의 영향 지점을 먼저 확인하고 최소 변경한다.
언어 필터·검색·페이지네이션, 새 의존성, feature flag, 호환성 fallback을 추가하지 않는다.
백엔드·DDL·배포는 범위 밖이며 운영 환경의 조회·변경 등 실서비스 작업은 하지 않는다.
## 연동 전 확인과 기존 API
백엔드 언어 계약은 구현·검증됐지만 운영 배포 완료를 뜻하지 않는다.
연동 전에 승인된 비운영 배포 대상의 실제 관리자 목록 응답에서 각 항목의 `lang` 반환을 확인한다.
GET 응답의 `data` 배열 항목에 `lang`이 없으면 KO로 간주하지 말고 계약 미충족으로 보고하여 연동을 중단한다. POST/PUT 응답의 언어 위치는 `data.lang`이다. 환경 자동 전환이나 mock fallback도 금지한다.
- `GET /admin/sub-banners?placement={placement}`: 기존 목록 조회. `placement`는 필수이며 `HOME_RECOMMENDATION` 또는 `CONTENT_RECOMMENDATION`이다.
- `POST /admin/sub-banners`: 기존 생성. `PUT /admin/sub-banners/{id}`: 기존 수정. PATCH나 언어 전용 경로를 만들지 않는다.
- 기존 DELETE, placement별 목록, 서버 id 오름차순, 저장 후 갱신 흐름은 그대로 둔다. 목록은 기간·언어와 무관한 삭제되지 않은 전체 항목이다.
- 기존 `Authorization: Bearer <token>`과 ADMIN 인증 흐름을 유지한다. 비관리자 응답이 반드시 403이라고 가정하지 않는다.
- 성공은 HTTP 200의 `ApiResponse`: `success`, `message`, `data`, `errorProperty`. GET의 `data`는 배열, POST/PUT은 저장된 전체 객체다.
## 데이터와 언어 선택
기존 관리자 DTO의 8필드 `id`, `placement`, `imageUrl`, `webUrl`, `androidDeepLink`, `iosDeepLink`, `startDate`, `endDate`를 보존하고 필수 `lang`을 더해 9필드로 확장한다.
기존 필드 타입은 유지한다: `id`는 정밀도를 보존할 정수 식별자, `placement`는 위 enum, `imageUrl`은 URL 문자열, 세 링크와 두 날짜는 각각 문자열 또는 null이다.
요청·응답·폼의 언어 타입은 저장소 언어에 맞는 enum 또는 리터럴 유니온 `KO | JA | EN`으로 제한하며 nullable로 만들지 않는다.
1. 기존 생성·수정 폼에 연결된 label `언어`를 가진 접근 가능한 select를 추가한다. 키보드 조작과 기존 포커스·오류 표시 패턴을 유지한다.
2. 선택지는 값/표시명을 `KO`/`한국어`, `JA`/`일본어`, `EN`/`영어`로 제공한다. 신규 생성 폼의 기본값만 KO다.
3. 수정 폼은 기존 목록 객체의 저장된 `lang`으로 채운다. JA/EN 행을 KO로 초기화하거나 비동기 로딩 중 기본값으로 덮어쓰지 않는다. 별도 상세 GET은 없다.
4. 생성·수정 시 현재 선택을 대문자 코드로 반드시 직렬화한다. 이미지·기간만 수정할 때도 저장된 언어 선택을 유지한다.
5. 필요하면 기존 목록 행 스타일에 언어 표시만 추가한다. 목록 구조·정렬·조회 조건은 바꾸지 않는다.
## 요청 직렬화: 기존 multipart에 lang만 추가
POST/PUT의 전체 요청은 기존대로 `multipart/form-data`다.
선택한 `lang`은 `Content-Type: application/json`인 **`request` JSON 파트 내부**에 넣는다.
별도 form field, header, query로 보내거나 요청 전체를 JSON으로 바꾸지 않는다.
`image` 파일 파트는 생성 시 필수, 수정 시 선택이며 생략하면 기존 이미지가 유지된다.
`placement`, `webUrl`, `androidDeepLink`, `iosDeepLink` 네 JSON 필드는 생성·수정 모두 반드시 보낸다.
수정의 네 필드는 교체 값이며 링크 null은 삭제다. 언어만 바꿀 때도 현재 placement·세 링크·이미지·기간을 보존한다.
기존 링크 유효성 검사와 원문 보존을 유지하며 언어 변경을 이유로 주소를 비우거나 변형하지 않는다.
아래는 `request` 파트 내용의 예시다. POST/PUT 모두 이 JSON을 multipart로 감싸고, POST에는 `image`도 포함한다.
PUT에서는 실제 폼의 기존 필드·기간 값을 사용한다. 이 예시의 주소나 null로 덮어쓰지 않는다.
```json
{
"placement": "HOME_RECOMMENDATION",
"webUrl": "https://example.test/promo",
"androidDeepLink": "sampleapp://promo",
"iosDeepLink": null,
"startDate": "2026-11-01 09:30",
"endDate": null,
"lang": "JA"
}
```
날짜 의미와 기존 직렬화는 변경하지 않는다. KST(`Asia/Seoul`) `yyyy-MM-dd HH:mm`이며 UTC ISO/브라우저 시간대로 변환하지 않는다.
생성의 날짜 생략/null은 무제한, 수정의 생략은 해당 경계 보존, null은 해당 경계 해제다. 시작 분 `:00`부터 종료 분 `:59`까지 포함한다.
언어만 수정할 때 기존 날짜를 의도치 않게 null로 바꾸지 않는다. 기존 날짜 검증과 개별 경계 해제 동작도 유지한다.
## 언어 오류와 운영자 안내
서버는 `lang` 생성 생략 시 KO, 수정 생략 시 기존 언어를 보존한다. 이는 서버 호환 규칙이며 새 폼은 선택값을 명시적으로 보낸다.
서버는 대소문자 무시·앞뒤 trim을 허용하지만 폼은 정규 코드만 보낸다. 명시적 null, 비문자열(숫자·boolean·배열·객체), blank, 미지원 코드는 HTTP 400이다.
언어를 지우는 null 선택지나 전송은 없다. 언어 오류 후에도 선택값·다른 필드·선택 파일·기존 이미지·날짜 상태를 지우지 않는다.
기존 HTTP 200 `success:false` 실패 처리를 유지하고 HTTP 상태와 `success`를 함께 확인한다. 400은 표준 Spring Boot body일 수 있어 `ApiResponse`로 단정하지 않는다.
앱 공개 노출은 서버가 resolve한 국가 기준 JP→JA, 그 외→KO다. 서버 회원 국가 매핑이 우선하며 일반 접속 국가 헤더 누락은 KR이다. `Accept-Language`나 관리자 브라우저 언어 기준이 아니다.
EN은 저장·관리자 목록 조회가 가능하지만 현재 앱 공개 국가 매핑에서는 노출되지 않는다. 이 안내를 폼에 눈에 보이게 표시하되 EN 선택·저장을 막지 않는다.
배너 소재 언어와 연결 이벤트 언어는 운영자가 수동으로 일치시킨다. 기존 KO 값은 자동 분류의 결과가 아니다. URL 언어 추론·파싱, 자동 번역은 하지 않는다.
## 완료 기준과 구현자 제출물
1. 신규 기본 KO와 JA/EN 선택 각각을 확인하고, POST/PUT의 `request` JSON 안에 정규 `lang`과 필수 네 필드가 포함되는 focused test를 추가한다.
2. 저장·목록 재조회·편집 재진입에서 KO/JA/EN이 유지되고, JA/EN 행이 해당 언어로 미리 선택되는지 확인한다. 이미지·날짜만 수정해도 언어가 보존되어야 한다.
3. null·비문자열·blank·미지원 언어의 400 거부와 오류 표시를 확인한다. HTTP 200 `success:false` 및 Boot 오류 body에서도 입력·이미지·날짜가 보존되는지 테스트한다.
4. 기존 목록·생성·수정·삭제와 이미지 필수/생략, 링크·기간 동작을 회귀 검증한다. 언어만 수정해도 다른 값이 바뀌지 않는지 확인한다.
5. 실제 UI에서 label과 키보드 선택·저장, EN 경고, 저장 후 재편집을 수동 QA한다. 배포 대상의 실제 `lang` 응답 확인과 누락 시 연동 중단도 기록한다.
구현자는 변경 파일 목록, focused test 실행 명령·결과, 실제 UI/manual QA 수행 내용·결과와 미검증 사항을 제출한다. 이 문서 작성 자체를 UI 구현·검증 완료로 보고하지 않는다.
@@ -1,96 +0,0 @@
# 관리자 구현 프롬프트: 가로형 서브 배너
이 프롬프트는 관리자 작업에 단독으로 사용할 수 있다. 작업 대상 repository의 실제 stack, 관리자 인증, API client, multipart 전송 및 form/list 패턴을 먼저 확인한다. 특정 framework를 전제하지 않는다. 이 작업은 frontend-only이며 서버, 저장소, schema, migration, 배포 작업으로 확장하지 않는다.
**상태:** 관리자 CRUD API 구현·검증 완료, 미배포. 백엔드 전체 테스트·lint·빌드와 독립 코드 리뷰를 통과했다. 화면 배치, 폼 표현, 삭제 확인 등 UI 선택은 작성자 추천이며 계약으로 가장하지 않는다.
2026-11-03 언어 후속 계약의 전체 2,928개 테스트·영향 HTTP 재검증·lint·빌드·독립 리뷰를 완료했다. 신규 환경은 `create-sub-banner.sql`, 기존 테이블은 `20261102_add_sub_banner_lang.sql`로 언어 컬럼을 서버 배포 전에 준비해야 한다. 운영 적용은 미실행이며 이 프롬프트의 UI 작업에서 SQL을 실행하지 않는다.
## 목표
가로형 서브 배너의 목록·생성·수정·삭제 UI를 제공한다. 레코드 하나는 `HOME_RECOMMENDATION` 또는 `CONTENT_RECOMMENDATION` placement 하나에 속한다. 별도 상세 조회는 없으므로 목록 데이터로 수정 form을 채운다.
## API 계약
아래 계약은 구현되어 있지만 아직 배포되지 않았다. 배포된 target을 확인한 뒤 그 target에만 실제 연결한다. target 오류 후 환경 변경이나 mock fallback을 자동 적용하지 않는다. fixture는 명시적인 UI 검증에서만 사용하며 mock 상태를 서버 성공으로 표시하지 않는다.
- `GET /admin/sub-banners?placement={placement}`: 필수 placement query, 삭제되지 않은 활성 배너를 기간·언어와 무관하게 모두 반환한다. 서버 언어 필터를 가정하지 않는다.
- `POST /admin/sub-banners`: 생성.
- `PUT /admin/sub-banners/{id}`: 기본 JSON 네 필드 교체. 날짜와 언어는 선택적으로 생략 보존한다. 명시적 null 해제는 두 날짜에만 허용된다.
- `DELETE /admin/sub-banners/{id}`: 소프트 삭제. 성공 시 목록에서 제거한다. 삭제된 id의 수정·재삭제는 404이며, 응답은 기존 HTTP 200과 `data:null`이다. `isActive`를 직접 보내거나 복원·활성 토글 UI를 추가하지 않는다.
- 기존 관리자 API client로 `Authorization: Bearer <token>`을 전송하고 `ADMIN` 역할이 필요하다. 익명 요청은 HTTP 401이다. 유효한 비관리자 요청은 현재 정책상 HTTP 200 `success:false`이며 403을 보장하지 않는다.
- 성공은 HTTP 200 및 네 필드 `ApiResponse<T>`: `success`, `message`, `data`, `errorProperty`. GET `data`는 전체 객체 배열, POST/PUT은 저장된 전체 객체, DELETE는 `null`. 빈 목록 `[]`.
- 관리자 응답 형식 `AdminSubBanner`는 정확히 9필드다: `id` integer JSON number(정밀도를 보존하는 불투명 식별자), `placement` enum(`HOME_RECOMMENDATION` 또는 `CONTENT_RECOMMENDATION`), `imageUrl` 절대 http/https URL 문자열, `webUrl`·`androidDeepLink`·`iosDeepLink` 각각 string|null, `startDate`·`endDate` 각각 string|null, `lang`은 `KO`·`EN`·`JA` 중 하나다. 모든 날짜는 `Asia/Seoul` 기준 `yyyy-MM-dd HH:mm` 문자열 또는 null이다. 목록, 생성, 수정 모두 이 관리자 shape를 쓴다.
- 앱은 두 추천 API의 `data.subBanners`를 사용한다. 배열 항목은 날짜·활성 필드가 없는 기존 6필드이며 활성·기간 내 항목에 앱의 웹/현재 OS 링크 조건을 적용한다. 관리자 CRUD 경로·요청·응답은 이 조회 통합으로 바뀌지 않는다.
- POST/PUT은 multipart: 파일 파트 `image`, `Content-Type: application/json`인 JSON 파트 `request`. 기본 JSON의 `placement`, `webUrl`, `androidDeepLink`, `iosDeepLink` 네 필드는 항상 모두 포함한다. 기존 네 필드는 PUT replacement이며 주소 `null`은 지운다. POST `image` 필수. PUT에서 `image` 생략은 기존 이미지 유지, 포함은 교체다.
- 선택적 `lang`은 기존 `Lang.fromCode` 규칙으로 `KO`/`EN`/`JA` 및 소문자 code를 대소문자 무시·앞뒤 trim으로 허용한다. 생성 생략은 KO, 수정 생략은 기존 언어 보존이다. 명시적 null·숫자·boolean·배열·객체·blank·알 수 없는 코드는 업로드/DB 쓰기 전에 HTTP 400이다. 언어를 지우는 null은 보내지 않는다.
- 앱 공개 서브 배너는 기존 회원 국가 resolver의 강제 매핑 우선, `CloudFront-Viewer-Country` 누락 KR 규칙으로 JP→JA, 그 외→KO만 반환한다. `Accept-Language`와 무관하며 EN은 저장 가능하지만 현재 공개 노출되지 않는다. 공개 DTO는 `lang` 없는 6필드다.
- `startDate`, `endDate`는 각각 선택적이다. create에서 생략 또는 null이면 무제한이다. update에서 생략하면 해당 저장 값을 보존하고 null이면 해당 경계만 해제한다. update는 두 날짜를 모두 제출해도 된다. 현재 저장된 placement와 주소가 예시와 같을 때 `{ "placement":"HOME_RECOMMENDATION", "webUrl":"https://example.test/promo", "androidDeepLink":"sampleapp://promo", "iosDeepLink":null, "startDate":"2026-11-01 09:30" }`는 주소를 유지하고 생략한 `endDate`를 유지한다. `"endDate":null`을 추가하면 종료만 해제한다. 날짜를 둘 다 null로 보내면 기간 제한을 모두 해제한다.
- 기간 의미: null/null은 무제한, 시작만 있으면 시작 분의 `:00`부터, 종료만 있으면 종료 분의 `:59`까지, 두 값이 있으면 양 끝을 포함한다. 같은 분도 유효하며 과거 시작일 제한은 없다.
- 입력은 엄격한 `Asia/Seoul` `yyyy-MM-dd HH:mm` 분 단위다. 초, `Z`, offset, blank string 및 존재하지 않는 KST 현지 시각 `1988-05-08 02:30`은 HTTP 400이다. 겹치는 현지 시각은 기존 앞선 offset으로 처리된다. browser local timezone이나 UTC ISO 문자열로 변환하지 않는다. 날짜 선택기에는 `KST`를 명시한다.
- 변환된 경계 instant는 UTC `1970-01-01 00:00:01`부터 `2038-01-19 03:14:07` 사이여야 한다. 이에 따른 KST 입력 범위는 시작 `1970-01-01 09:01`부터 `2038-01-19 12:14`, 종료 `1970-01-01 09:00`부터 `2038-01-19 12:13`이다. 이 범위 안의 과거 날짜는 유효하다. 잘못된 날짜/type 또는 effective start가 end보다 늦으면 HTTP 400이며 값 보정은 없다. update에서는 저장된 값과 새 값의 조합으로 검증한다.
- **작성자 제안:** form submit 경계에서 주소를 trim하고 blank를 `null`로 정규화한 뒤, 그 결과 세 주소 중 적어도 하나가 nonblank인지 검증한다. 이는 XOR 조건이 아니며 두 개 이상도 유효하다. nonblank URI 원문은 trim 외 재인코딩·변형하지 않는다.
- 웹 URL은 host를 가진 절대 http(s) URL이어야 한다. Android/iOS 딥링크는 문법적으로 유효한 절대 URI이며 `javascript`, `data`, `file`, `content` scheme은 대소문자와 무관하게 거부된다. 임의 scheme allowlist는 없다.
- 서비스가 검증하는 JSON/URI/date/type/placement 오류, 빈 파일 또는 비이미지 업로드는 HTTP 400이다. 유효한 정수 ID의 수정·삭제 대상이 없으면 HTTP 404이며 상태 오류 및 익명 401은 표준 Spring Boot `{timestamp,status,error,path}` body를 쓴다. 이는 `ApiResponse`가 아니다. multipart 파트 누락 또는 malformed multipart는 HTTP 200 `success:false`다. 프레임워크 바인딩 오류까지 모두 400이라고 가정하지 않는다. 유효한 비관리자는 HTTP 200 `success:false`다. 모든 응답에서 HTTP 상태와 `success`를 함께 확인하며 403을 전제하지 않는다.
- 파일 내용은 MIME 감지로 이미지인지 검사하며 GIF를 허용한다. 빈 파일과 비이미지는 HTTP 400이다. 현재 설정의 최대 파일/요청 크기는 1024 MB이며 제품 권장 용량이 아니다. reverse proxy 또는 배포 설정이 더 낮은 제한을 둘 수 있다. 범용 업로드 endpoint는 없다.
```json
{"placement":"HOME_RECOMMENDATION","webUrl":"https://example.test/promo","androidDeepLink":"sampleapp://promo","iosDeepLink":null,"startDate":"2026-11-01 09:30","endDate":null,"lang":"JA"}
```
POST/PUT 성공 응답 예시:
```json
{
"success": true,
"message": null,
"data": {"id": 123, "placement": "HOME_RECOMMENDATION", "imageUrl": "https://cdn.example.test/promo.jpg", "webUrl": "https://example.test/promo", "androidDeepLink": "sampleapp://promo", "iosDeepLink": null, "startDate": "2026-11-01 09:30", "endDate": null, "lang": "JA"},
"errorProperty": null
}
```
## 폼과 목록 동작
- 관리자 API는 placement별 삭제되지 않은 모든 배너를 id 오름차순으로 반환한다. 클라이언트에서 재정렬하지 않고 전부 표시한다. 별도 정렬 편집은 추가하지 않는다.
- 폼은 이미지, 세 주소, KST 시작/종료 날짜 선택기를 제공한다. 날짜 입력을 비우면 `null`을 보내며 빈 문자열은 보내지 않는다. 각 경계를 별도로 지울 수 있다. 화면에 KST를 표시하고 브라우저 지역 시각 또는 UTC ISO로 바꾸지 않는다.
- 언어 선택은 KO/EN/JA를 사용하고 편집 시 목록의 `lang`을 채운다. 언어 수정 생략을 KO로 재작성하지 않는다. 기존 행의 KO backfill은 자동 분류가 아니므로 JA 소재를 수동 확인하고 연결 이벤트 언어와 일치시킨다. 외부 URL/딥링크는 언어 추론·파싱 없이 원문을 유지한다.
- 편집은 목록의 전체 객체를 기반으로 모든 값을 채운다. 기존 이미지 URL/선택 상태, 주소 및 기간 값을 오류 후 보존한다. 기간만 바꾸는 요청은 기존 placement와 세 주소를 그대로 전송하고, image를 생략해 기존 이미지를 유지한다. 주소를 임의로 null로 초기화하지 않는다.
- 관리자 목록은 삭제되지 않은 배너의 미래/현재/만료/무기간 상태를 모두 표시하며 노출 기간으로 필터링하지 않는다. 기간 밖 레코드도 열어 수정할 수 있지만 소프트 삭제된 배너는 표시·수정하지 않는다. 같은 placement의 서버 id 오름차순을 유지한다.
- 업데이트 기본 네 JSON 필드는 항상 보내되, 날짜 필드는 둘 다 보내거나 필요한 경계만 보내거나 생략할 수 있다. 생략은 보존, 명시적 null은 해당 경계 해제다. API의 생략 보존 의미는 UI가 두 날짜를 모두 보낼 때도 유지된다.
- 최소 한 주소 검증, 주소 trim/null 직렬화, URI 원형 보존을 적용한다.
- 날짜 선택값은 KST 분 문자열로 직렬화한다. 시간대 변환으로 날짜나 분을 바꾸지 않는다. create의 날짜 미입력은 null/no-bound로 보내거나 생략할 수 있다. update에서 미입력 경계를 보존하려면 해당 필드를 생략하고, 사용자가 지웠으면 명시적 null을 보낸다.
- 저장 후 해당 placement 목록을 갱신한다. 실패 시 입력값과 기존 이미지 상태를 보존하고 실패를 알린다. autosave는 두지 않는다.
- 삭제 확인, 중복 제출 방지, 상태 표시 및 성공 후 갱신은 기존 관리자 UI 패턴을 따른다. mutation 자동 재시도는 하지 않으며 timeout 결과가 불명확하면 상태를 조회한다.
- 조회 실패를 빈 성공으로 취급하지 않는다.
- 필요하면 두 딥링크 주소를 입력해 특정 OS만 지원하는 레코드임을 설명할 수 있으나 별도 기능으로 확장하지 않는다.
## 주소 조합 acceptance matrix (작성자 제안)
`web`, `android`, `ios` 열은 해당 주소가 nonblank인 경우다. 빈 값은 null로 전송한다. Valid 여부는 최소 한 값 요구에 따른다.
Android/iOS 탭 동작은 작성자 추천이며 제품 승인된 UI 동작이 아니다. 권장 흐름은 현재 OS 딥링크 우선, 없으면 웹 URL이다.
| web | android | ios | 유효 | Android 동작 | iOS 동작 |
|---|---|---|---|---|---|
| 없음 | 없음 | 없음 | 아니오 | 표시 안 함 | 표시 안 함 |
| 있음 | 없음 | 없음 | 예 | 웹 | 웹 |
| 없음 | 있음 | 없음 | 예 | Android 딥링크 | 표시 안 함 |
| 없음 | 없음 | 있음 | 예 | 표시 안 함 | iOS 딥링크 |
| 있음 | 있음 | 없음 | 예 | Android 딥링크 우선, 실패 시 웹 | 웹 |
| 있음 | 없음 | 있음 | 예 | 웹 | iOS 딥링크 우선, 실패 시 웹 |
| 없음 | 있음 | 있음 | 예 | Android 딥링크 | iOS 딥링크 |
| 있음 | 있음 | 있음 | 예 | Android 딥링크 우선, 실패 시 웹 | iOS 딥링크 우선, 실패 시 웹 |
## 필수 테스트와 완료 확인
- 언어 KO/EN/JA 입력·응답, 생성 생략 KO, 수정 생략 유지, null·비문자열·blank·unknown 거부 및 관리자 전체 언어 목록을 확인한다.
- 여덟 주소 조합의 form 유효성 및 Android/iOS 대상 판단.
- 전부 null로 수정할 때 오류, `null`로 한 필드 지우기, 공백 trim, URI 원형 보존.
- 두 날짜 null, 시작만, 종료만, 같은 분, 경계의 `:00` 및 `:59`, 과거 날짜가 유효한 경우를 확인한다.
- create 날짜 생략/null, update 날짜 생략 보존, 개별 null 해제, 두 경계 해제, loaded date 재전송, 유효 범위가 retained/new 값 조합으로 검증됨을 확인한다.
- 잘못된 날짜/type, blank, 초, `Z`/offset 및 시작이 종료보다 늦은 값이 거부되고 자동 교환/rollover되지 않는지 확인한다.
- 미래/현재/만료/무기간 레코드가 관리자 목록에 남고 기간 외 레코드도 편집 가능한지 확인한다. 일정만 수정하고 image를 생략하면 기존 이미지가 유지되어야 한다.
- 여러 항목 표시, placement별 목록 분리, create/update/delete 성공과 실패.
- 실패 시 입력·이미지 상태 보존, 삭제 확인, 중복 제출 방지 및 timeout 후 중복 POST 방지 흐름.
- 인증/권한 실패와 목록 조회 실패를 empty로 오인하지 않는 상태.
프롬프트는 frontend-only로 실행한다. 백엔드 검증은 완료됐지만 운영 DB 적용·배포는 하지 않았다. 배포 target이 확인되기 전 운영 요청이나 배포 성공을 주장하지 않는다. UI를 수정하는 작업은 기존 프로젝트 방식으로 검증하고, 서버 코드 및 API는 변경하지 않는다.
@@ -1,149 +0,0 @@
# 가로형 서브 배너 API 계약
> **상태: 소프트 삭제·두 추천 API 통합 구현 및 검증 완료, 미배포.** 최종 전체 테스트 2,682개(실패·오류·무시 0), lint·bootJar 및 독립 리뷰를 통과했다. 운영 DB 적용과 배포는 수행하지 않았다.
2026-11-03 언어 후속 Phase 7 검증도 완료했다. 전체 2,928개 통과, 테스트 공백 수정 후 영향 HTTP 26개·전체 lint·bootJar 재확인 및 독립 리뷰 APPROVE다. 위 2,682개는 기존 Phase 2~6 이력이며 후속 증거는 `plan-task.md` Phase 7에 기록한다. 운영 DDL·배포는 미실행이다.
## 1. 공통 형식
애플리케이션 성공 응답은 네 필드를 가진 `ApiResponse<T>` 형식이다. 아래는 관리자 빈 목록 예시이며, 두 추천 GET의 data는 §2의 응답 객체다.
```json
{
"success": true,
"message": null,
"data": [],
"errorProperty": null
}
```
`data`는 조회의 응답 객체 또는 목록, 생성·수정의 전체 배너 객체, 삭제의 `null`이다. 성공 요청은 HTTP 200이다. 일부 요청 오류도 기존 handler에 따라 HTTP 200의 `success:false`로 응답하므로 HTTP 상태와 `success`를 모두 확인한다.
```json
{
"id": 123,
"placement": "HOME_RECOMMENDATION",
"imageUrl": "https://cdn.example.test/sub-banner.jpg",
"webUrl": "https://example.test/promo?x=a%2Fb",
"androidDeepLink": "sampleapp://promo/item?id=a%2Fb",
"iosDeepLink": null
}
```
| 필드 | 타입 | 규칙 |
|---|---|---|
| `id` | integer JSON number | 불투명 식별자. 소비 클라이언트의 정밀도 안전 ID 전략을 사용한다. |
| `placement` | enum | `HOME_RECOMMENDATION` 또는 `CONTENT_RECOMMENDATION` |
| `imageUrl` | string | 서버가 생성한 저장 키를 기반으로 만든 절대 `http` 또는 `https` URL. 클라이언트 파일명은 저장 키가 아니다. |
| `webUrl` | string 또는 null | 절대 `http` 또는 `https` URL |
| `androidDeepLink` | string 또는 null | Android 대상 링크 원문 |
| `iosDeepLink` | string 또는 null | iOS 대상 링크 원문 |
공개 `SubBanner`는 정확히 위 6필드이며 `lang`·날짜·활성 필드를 추가하지 않는다. 앱 응답은 국가별 언어·기간 필터 적용 후의 기본 필드만 반환한다. 세 주소 중 하나 이상은 공백이 아닌 값이어야 한다. 입력 주소는 trim 후 공백이면 `null`로 보내고, nonblank URI는 trim 외 재인코딩·정규화·손상을 가하지 않는다. `webUrl`은 host를 가진 절대 http(s) URL이어야 한다. OS 딥링크는 유효한 절대 URI이며 `javascript`, `data`, `file`, `content` scheme은 대소문자와 무관하게 거부된다. 임의 scheme allowlist는 없다.
관리자 전용 `AdminSubBanner`는 `SubBanner`의 기본 필드에 nullable `startDate`, `endDate`와 필수 `lang`을 더한 정확히 9필드다. 관리자 GET 및 POST/PUT 응답은 모두 `AdminSubBanner`를 반환한다. 날짜는 `Asia/Seoul` 기준 `yyyy-MM-dd HH:mm` 문자열 또는 null이고, `lang` 응답은 `KO`, `EN`, `JA` 중 하나다.
요청의 `lang`은 선택적 문자열이며 기존 `Lang.fromCode` 규칙을 사용한다. `KO`/`EN`/`JA` 및 `ko`/`en`/`ja`를 대소문자 구분 없이, 앞뒤 공백을 제거해 허용한다. 생성 생략은 KO, 수정 생략은 저장된 언어 유지다. 명시적 null, 숫자·boolean·배열·객체, blank 문자열, 알 수 없는 코드는 HTTP 400이며 이미지 업로드·DB 쓰기 전에 거부한다. 날짜의 null 해제와 달리 언어 null은 허용하지 않는다.
관리자 기간 의미는 기존 콘텐츠 배너 예약과 동일하다. null/null은 무제한, 시작만 있으면 시작부터, 종료만 있으면 해당 종료 경계까지 포함하며 시작과 종료가 같은 분인 것도 유효하다. 입력·응답은 분 단위지만 실제 노출 판정은 초 단위로 양 끝을 포함한다. 시작 경계는 입력 분의 `:00`, 종료 경계는 입력 분의 `:59`다. 예를 들어 종료 입력이 `2026-11-01 12:00`이면 `12:00:59`까지 포함하고 `12:01:00`부터 제외한다. API 문자열에는 초, `Z`, offset을 표현하거나 받지 않는다.
요청 날짜는 선택적이다. 생성 시 생략 또는 null은 해당 경계를 제한 없음으로 둔다. 수정 시 생략은 저장된 경계를 유지하고 명시적 null은 그 경계만 해제한다. 두 날짜의 유효 범위는 수정 후 유지되는 값과 새 값을 합쳐 검증한다. 입력은 엄격한 Asia/Seoul `yyyy-MM-dd HH:mm` 분 단위다. 잘못된 형식, 문자열이 아닌 값, 빈 문자열, 초/시간대가 포함된 값, 존재하지 않는 KST 현지 시각(1988-05-08 02:30), 시작이 종료보다 늦은 값은 HTTP 400이다. 존재하는 겹침 시각은 기존의 앞선 offset을 사용한다. 자동 교환이나 날짜 넘김 보정, 과거 날짜 제한은 없다.
UTC로 변환된 경계 instant는 `1970-01-01 00:00:01`부터 `2038-01-19 03:14:07` 사이여야 한다. 이에 따라 시작 입력 허용 범위는 KST `1970-01-01 09:01`부터 `2038-01-19 12:14`, 종료 입력은 `1970-01-01 09:00`부터 `2038-01-19 12:13`이다. 범위 바깥을 포함해 변환 instant가 저장 가능 범위를 벗어나면 HTTP 400이다. 이 범위 안의 유효한 과거 날짜는 허용된다.
## 2. 앱 추천 조회
| 항목 | 계약 |
|---|---|
| Method / Path | `GET /api/v2/home/recommendations` |
| Query | 서브 배너용 query 없음. endpoint가 `HOME_RECOMMENDATION` placement를 결정한다. |
| 접근 | 익명 조회 가능. 로그인 사용자도 기존 클라이언트 헤더를 유지해 조회한다. |
| 성공 | HTTP 200, `ApiResponse<HomeRecommendationResponse>` |
| `data` | 기존 홈 추천 응답 객체의 모든 필드와 `subBanners: SubBanner[]`를 포함한다. 기존 `banners` 및 추천 섹션은 유지한다. |
| `data.subBanners` | 해당 placement의 활성 배너 중 회원 국가별 언어와 현재 노출 기간에 맞는 전체 항목, id 오름차순. 페이지네이션·묵시적 절단 없음. 결과가 없으면 `[]`. 언어·날짜·활성 필드는 응답하지 않는다. |
```json
{
"success": true,
"message": null,
"data": {
"lives": [],
"banners": [],
"recentlyActiveCreators": [],
"recentDebutCreators": [],
"firstAudioContents": [],
"aiCharacters": [],
"genreCreators": [],
"cheerCreators": [],
"popularCommunityPosts": [],
"subBanners": [{"id":123,"placement":"HOME_RECOMMENDATION","imageUrl":"https://cdn.example.test/sub-banner.jpg","webUrl":"https://example.test/promo","androidDeepLink":"sampleapp://promo","iosDeepLink":null}]
},
"errorProperty": null
}
```
`GET /api/v2/audio/recommendations`도 익명 조회 가능하며 로그인 사용자는 기존 클라이언트 헤더를 유지한다. 이 endpoint는 `CONTENT_RECOMMENDATION`을 사용하고 기존 `banners`, `originalSeries`, `latestAudios`, `newAndHotAudios`, `freeAudios`, `pointAudios`, `mostCommentedAudios`, `recommendedAudios` 필드에 `subBanners: SubBanner[]`를 추가한다. `data.subBanners`에는 동일한 전체·활성·기간 필터 및 id 오름차순 규칙이 적용되며, 빈 결과는 `[]`다. 두 API 모두 기존 추천 `data`를 배너 배열로 대체하지 않으며 별도 placement query를 보내지 않는다.
`GET /api/v2/sub-banners`는 더 이상 공개 앱 조회 경로가 아니며 별도 요청으로 사용하지 않는다. 이를 새 alias로 취급하지 않는다. 서버가 반환한 항목에 기존 OS별 링크 필터를 적용하며 날짜와 활성 상태는 클라이언트에서 판단하지 않는다.
두 추천 GET은 Authorization 헤더 없이 200으로 조회할 수 있다. 아래 인증 오류 설명은 관리자 등 인증이 필요한 경로에 적용되며, 앱 추천 조회에 새 로그인 조건을 추가하는 것이 아니다. 서브 배너 전용 HTTP 요청·서버 fallback은 없다.
두 endpoint의 서브 배너 언어는 기존 `MemberContentPreferenceService.resolveCountryCode(member)`로 판정한다. 강제 회원 매핑이 접속 국가 헤더보다 우선하며, 일반 회원·익명은 `CloudFront-Viewer-Country`를 사용하고 누락 시 KR이다. JP는 JA, KR·US 등 그 외는 KO만 조회한다. `Accept-Language`나 `LangContext`로 선택하지 않고 별도 언어 query도 받지 않는다. EN은 관리자에서 저장·조회할 수 있지만 현재 공개 국가 매핑으로는 노출되지 않는다. 이벤트 연결을 파싱하거나 외부 링크를 번역하지 않으며 기존 링크 원문을 유지한다.
## 3. 관리자 목록과 변경
관리자 경로는 `Authorization: Bearer <token>` 인증과 `ADMIN` 역할이 필요하다. 유효한 비관리자 요청이 반드시 403을 반환하는 것은 아니며 현재 정책 응답은 HTTP 200 `success:false`다.
| Method / Path | 목적 | 성공 data |
|---|---|---|
| `GET /admin/sub-banners?placement={placement}` | placement별 삭제되지 않은 활성 레코드, 기간·언어 무관. 필수 query, id 오름차순 | `AdminSubBanner[]` |
| `POST /admin/sub-banners` | 신규 생성 | 생성된 `AdminSubBanner` |
| `PUT /admin/sub-banners/{id}` | 원래 네 JSON 필드는 교체, 날짜와 언어 필드는 선택적 생략 보존 | 수정된 `AdminSubBanner` |
| `DELETE /admin/sub-banners/{id}` | 소프트 삭제 | `null` |
삭제는 내부 `is_active` 값을 false로 변경하며 행·이미지 key·주소·기간·생성 시각과 S3 이미지는 보존한다. 생성 기본값은 true다. 삭제된 id는 관리자/공개 목록에서 제외하고, 수정·재삭제는 없는 대상과 동일하게 404다. 성공 응답은 기존 HTTP 200 및 `data:null`을 유지한다. `isActive` 요청/응답 필드나 복구·활성 토글 API는 추가하지 않는다.
POST와 PUT은 `multipart/form-data`다. `image` 파트는 파일이며, `request` 파트는 `Content-Type: application/json`인 JSON이다. 별도 이미지 업로드 endpoint는 없다.
```json
{
"placement": "HOME_RECOMMENDATION",
"webUrl": "https://example.test/promo",
"androidDeepLink": "sampleapp://promo",
"iosDeepLink": null,
"startDate": "2026-11-01 09:30",
"endDate": null,
"lang": "JA"
}
```
- POST: `image` 필수.
- PUT은 기존 네 필드 `placement`, `webUrl`, `androidDeepLink`, `iosDeepLink`를 모두 보낸다. 이 네 필드와 placement는 기존처럼 필수 replacement 값이다. 주소 `null`은 해당 주소를 지운다. 이는 전체 JSON replacement가 아니며 아래 날짜와 언어 필드는 생략 보존한다.
- `lang` 생성 생략은 KO, 수정 생략은 기존 언어 유지다. 언어를 바꾸려면 유효한 문자열을 보내며 명시적 null은 지우기가 아니라 HTTP 400이다.
- `startDate`, `endDate`는 요청에서 각각 선택적이다. POST에서 생략 또는 null이면 무제한 경계다. PUT에서 생략하면 기존 경계를 보존하고, null이면 그 경계만 해제한다. 둘 다 보낼 필요는 없다. PUT은 날짜 두 필드를 모두 보내도 된다.
- 기간만 수정하더라도 `placement`와 세 주소는 현재 저장된 값을 그대로 보낸다. 예를 들어 현재 주소가 아래 예시와 같을 때 `{"placement":"HOME_RECOMMENDATION","webUrl":"https://example.test/promo","androidDeepLink":"sampleapp://promo","iosDeepLink":null,"startDate":"2026-11-01 09:30"}`는 생략한 `endDate`를 유지한다. 같은 주소를 유지하며 `"startDate":null,"endDate":null`을 보내면 양쪽 경계만 해제한다. 기간 변경을 위해 기존 주소를 임의로 null로 바꾸지 않는다.
- PUT에서 `image` 생략 시 기존 이미지를 유지하고, 포함 시 교체한다.
- 수정 화면은 목록 응답의 전체 객체로 채우며 별도 상세 GET은 두지 않는다.
- 파일 내용은 이미지여야 하며 MIME 감지로 검사한다. GIF를 허용한다. 빈 파일과 비이미지는 HTTP 400이다. 현재 서버 설정의 최대 파일/요청 크기는 각각 1024 MB이며, 이는 제품 권장 용량이 아니다. reverse proxy나 배포 설정은 더 낮은 제한을 둘 수 있다.
관리자 목록에는 삭제되지 않은 활성 레코드의 미래 시작·현재 노출·종료된 기간·양쪽 null 상태가 모두 포함되며 기간으로 숨기지 않는다. 소프트 삭제된 행은 기간과 무관하게 제외한다. 같은 placement/id 오름차순을 사용한다.
## 4. 기존 배너 예약 근거
예약 의미는 기존 콘텐츠 배너 예약 동작을 따른다. 날짜의 외부 API 표현은 위 형식과 경계 규칙을 따른다.
## 5. 오류와 재시도
서비스가 검증하는 JSON/URI/날짜/타입/placement 오류와 업로드된 빈 파일 또는 비이미지는 HTTP 400이다. 유효한 정수 ID로 조회한 수정·삭제 대상이 없으면 HTTP 404이며, 이들 상태 오류는 표준 Spring Boot 형식 `{"timestamp":...,"status":...,"error":...,"path":...}`을 사용하고 `ApiResponse`가 아니다. 인증되지 않은 요청은 HTTP 401과 같은 표준 형식이다. 유효한 비관리자 요청은 현재 권한 정책에 따라 HTTP 200 `ApiResponse`의 `success:false`를 반환하며 403을 보장하지 않는다. `image`/`request` multipart 파트 누락 및 malformed multipart는 기존 handler에 따라 HTTP 200 `success:false`다. 프레임워크 바인딩 오류까지 모두 400이라고 가정하지 않는다. 소비자는 모든 응답에서 HTTP 상태와 `success`를 함께 확인하며 구체적인 오류 코드나 `errorProperty` 값을 가정하지 않는다.
```json
{"success":false,"message":"요청을 처리할 수 없습니다.","data":null,"errorProperty":null}
```
이 예시는 HTTP 200의 `success:false` 응답 예시다. 표준 Spring Boot 상태 오류의 body는 위 ApiResponse 형식이 아니다. `Idempotency-Key`는 제공되지 않는다. POST/PUT/DELETE를 자동 재시도하지 않고 중복 제출을 막는다. 결과를 알 수 없는 timeout 뒤, 특히 POST는 재시도 전 GET으로 상태를 대조한다.
## 6. 제공 상태와 호환성
관리자 CRUD·소프트 삭제·두 추천 API 통합을 구현하고 최종 전체 2,682개 테스트와 lint·bootJar·독립 리뷰를 통과했다. 실제 HTTP/DB 및 단계별 실행 증거는 [plan-task.md](plan-task.md)에 있다. DDL은 독립 H2에 적용해 검증했지만 native MySQL 및 운영 DB에는 적용하지 않았다. 구현·검증 완료를 운영 배포 완료로 간주하지 않는다.
서버 배포 전에 신규 환경은 [create-sub-banner.sql](create-sub-banner.sql), 기존 테이블은 [20261102_add_sub_banner_lang.sql](20261102_add_sub_banner_lang.sql)을 적용해 `lang VARCHAR(10) NOT NULL DEFAULT 'KO'`를 준비해야 한다. 기존 `is_active` 등 선행 스키마도 필요하다. 이관 파일은 동적 SQL 없는 단일 `ALTER TABLE`이며 **lang 컬럼이 없는 기존 테이블에 한 번만 실행한다. 이미 컬럼이 있거나 신규 CREATE를 적용한 DB에서는 실행하지 않는다.** 기존 행은 컬럼 추가 시 KO 기본값을 가지며 별도 UPDATE는 필요하지 않다. KO는 기존 행의 언어를 추론한 결과가 아니므로 운영 담당자가 JA 소재를 수동 분류하고 연결 이벤트 언어와 일치하는지 검토해야 한다. 외부 링크는 원문 그대로이며 자동 언어 분류·링크 파서는 없다. 통합 추천 조회도 새 컬럼을 사용하므로 migration 전에 서버 코드를 배포하지 않는다. SQL의 운영 적용·native MySQL 검증·배포는 이번 작업에서 수행하지 않는다.
@@ -1,107 +0,0 @@
# 앱 구현 프롬프트: 가로형 서브 배너
이 프롬프트는 앱 작업에 단독으로 사용할 수 있다. 현재 repository에 접근해 실제 앱 stack과 기존 화면·URL opener·API client 패턴을 먼저 확인하고 그 패턴에 맞춰 작업하라. 특정 framework를 가정하지 말고 기존 API를 변경하지 않는다.
**상태:** 소프트 삭제와 두 추천 API 통합의 백엔드 구현·검증 완료, 미배포. 전체 테스트·lint·빌드와 독립 리뷰를 통과했다. 제공 환경을 확인하기 전 운영 연동 또는 서버 배포가 완료됐다고 가정하지 않는다.
2026-11-03 국가별 언어 후속 계약의 전체 2,928개 테스트·영향 HTTP 재검증·lint·빌드·독립 리뷰를 완료했다. 서버 배포 전 신규 환경은 `create-sub-banner.sql`, 기존 테이블은 `20261102_add_sub_banner_lang.sql`로 `lang` 컬럼을 준비해야 한다. 운영 적용은 미실행이며 앱 작업에서 migration이나 운영 DB 변경을 실행하지 않는다.
## 목표
메인 홈 추천과 메인 콘텐츠 추천 화면에 가로형 서브 배너 영역을 추가한다. 각 placement 목록에 여러 배너가 있을 수 있다. 아래 API와 데이터 계약은 구현된 계약이다. 화면 배치, 표현, 링크 우선순위, fetch 실패 시 UI 처리는 작성자 추천이며 기존 앱 패턴을 따른다.
## API 계약
추천 API 통합 계약:
- 홈: `GET /api/v2/home/recommendations`, 익명 조회 가능, `data.subBanners`의 placement는 `HOME_RECOMMENDATION`으로 고정.
- 콘텐츠 추천: `GET /api/v2/audio/recommendations`, 익명 조회 가능, `data.subBanners`의 placement는 `CONTENT_RECOMMENDATION`으로 고정.
- 비로그인 사용자는 Authorization 헤더 없이 두 GET을 조회할 수 있다. 로그인 화면으로 차단하지 않는다. 로그인 사용자는 기존 클라이언트 헤더를 그대로 유지하며, 별도 서브 배너 요청을 추가하지 않는다.
- 응답은 기존 추천 `data` 객체에 `subBanners: SubBanner[]`를 추가한 `ApiResponse`다. 기존 추천 필드와 `banners`를 보존하며 `data`를 배너 배열로 바꾸지 않는다. 서브 배너용 placement query는 보내지 않는다.
- 성공은 HTTP 200이며 envelope는 `success`, `message`, `data`, `errorProperty` 네 필드다. 클라이언트는 HTTP status와 `success`를 모두 확인한다. HTTP 200의 `success:false`도 실패다. 다른 HTTP 오류도 성공으로 처리하지 않는다.
- 배너 객체: `id` 정수(JSON number, 불투명 ID로 앱의 정밀도 안전 전략 사용), `placement` enum, `imageUrl` 절대 http/https URL, `webUrl` string|null, `androidDeepLink` string|null, `iosDeepLink` string|null. 다른 배너 필드는 가정하지 않는다.
- 공개 `SubBanner` DTO는 위 기본 필드 그대로이며 `startDate`/`endDate`/`isActive`를 추가하거나 가정하지 않는다. 서버는 활성 배너 중 현재 노출 기간 안인 항목 전체를 id 오름차순으로 `data.subBanners`에 반환하고, 결과가 없어도 배열을 `[]`로 반환한다. 앱은 그 목록에 기존 웹 URL/현재 OS 링크 필터를 적용한다. 응답 순서와 placement는 보존한다.
- 두 추천의 `data.subBanners`는 국가별 언어 조건도 서버에서 적용한다. 기존 회원 국가 resolver의 강제 매핑이 우선하며 일반 회원·익명은 `CloudFront-Viewer-Country`를 사용하고 누락 시 KR이다. JP→JA, 그 외(KR·US 포함)→KO다. `Accept-Language`/`LangContext` 또는 기기 언어로 대체하지 않고 별도 language query나 클라이언트 언어 필터를 추가하지 않는다. 공개 DTO는 정확히 위 6필드이고 `lang`은 없다. EN은 관리자 저장·조회 가능하지만 현재 공개 노출되지 않는다.
- 더 이상 사용하지 않을 별도 앱 요청은 `GET /api/v2/sub-banners`다. 앱에서 해당 endpoint를 호출하거나 대체용 두 번째 요청을 추가하지 않는다. 삭제된 경로의 구체적인 오류 status를 가정하지 않는다.
- 기간 판단은 서버가 맡는다. 기기 시계로 기간을 다시 계산하거나 로컬 예약 timer를 추가하지 않는다.
- 관리자 언어 계약은 생성 생략 KO·수정 생략 유지이며 null·비문자열·blank·unknown은 업로드/쓰기 전 400이다. 관리자 목록은 모든 언어다. 기존 KO backfill은 자동 언어 분류가 아니므로 운영 담당자가 JA 소재와 연결 이벤트 언어를 수동 검토한다. 앱은 이벤트 링크를 파싱해 언어를 추정하지 않고 외부 URL/딥링크 원문을 유지한다.
- 서브 배너만을 위한 별도 fetch는 없다. 추천 API의 통신 실패는 기존 추천 화면의 오류 정책으로 처리하며 정상 `subBanners:[]`로 바꾸지 않는다. 개별 배너의 이미지 로딩·링크 실행 실패는 기존 추천 콘텐츠의 표시와 분리한다.
홈 추천 성공 응답 예시 (기존 추천 필드는 예시 데이터로 유지, 서브 배너 두 항목):
```json
{
"success": true,
"message": null,
"data": {
"lives": [],
"banners": [],
"recentlyActiveCreators": [],
"recentDebutCreators": [],
"firstAudioContents": [],
"aiCharacters": [],
"genreCreators": [],
"cheerCreators": [],
"popularCommunityPosts": [],
"subBanners": [
{"id": 101, "placement": "HOME_RECOMMENDATION", "imageUrl": "https://cdn.example.test/one.jpg", "webUrl": "https://example.test/one", "androidDeepLink": "sampleapp://one", "iosDeepLink": null},
{"id": 102, "placement": "HOME_RECOMMENDATION", "imageUrl": "https://cdn.example.test/two.jpg", "webUrl": null, "androidDeepLink": null, "iosDeepLink": "sampleapp://two"}
]
},
"errorProperty": null
}
```
빈 목록 응답:
```json
{"success":true,"message":null,"data":{"lives":[],"banners":[],"recentlyActiveCreators":[],"recentDebutCreators":[],"firstAudioContents":[],"aiCharacters":[],"genreCreators":[],"cheerCreators":[],"popularCommunityPosts":[],"subBanners":[]},"errorProperty":null}
```
콘텐츠 추천도 기존 `data` 구조를 유지한다. 빈 데이터 예시는 다음과 같으며, 배너가 있으면 `subBanners`에 `CONTENT_RECOMMENDATION` 항목이 들어간다.
```json
{"success":true,"message":null,"data":{"banners":[],"subBanners":[],"originalSeries":[],"latestAudios":[],"newAndHotAudios":[],"freeAudios":[],"pointAudios":[],"mostCommentedAudios":[],"recommendedAudios":[]},"errorProperty":null}
```
## 표시 규칙
- 서버 응답의 id 오름차순은 유지한다. 아래 UI 선택은 작성자 추천이다: 모든 표시 대상 항목을 수직으로 나열하고 새 slider/autoplay는 추가하지 않는다.
- placement별 화면 내 정확한 위치는 기존 화면을 살펴 정한다. main banner 뒤에 배치하는 것은 작성자 추천이며 확정된 API 동작이 아니다.
- 작성자 추천: 이미지 원본 비율에 맞춰 표시하고, 필터 결과가 없을 때 영역과 여백을 숨긴다. 기존 화면 레이아웃에 맞게 적용하며 이를 API 계약으로 간주하지 않는다.
- 표시 조건은 대상 OS 딥링크 또는 웹 URL 보유다. 대상 OS 딥링크가 있어도 앱 설치/launch 가능 여부로 사전 필터링하지 않는 것은 작성자 추천이다.
- 기간 필터가 적용된 서버 결과에 기존 OS별 링크 필터를 그대로 적용한다. 공개 날짜 필드를 읽거나 클라이언트에서 기간을 판단하지 않는다.
## 링크 처리와 보안
작성자 추천: 탭 시 대상 OS 딥링크가 있으면 우선 기존 플랫폼 URL opener로 열고, 없으면 웹 URL을 연다. 딥링크 시도 실패 시 웹 URL이 있으면 한 번 대체 시도할 수 있다. 다른 OS 딥링크를 대체 수단으로 쓰지 않는다. 구체적인 우선순위와 실패 피드백은 기존 앱 링크 처리 패턴을 따른다.
웹 URL은 절대 `http`/`https` URL이며 host가 필요하다. 딥링크는 절대 URI이고 `javascript`, `data`, `file`, `content` scheme은 대소문자와 무관하게 거부된다. 클라이언트에서도 임의 입력을 실행하거나 문자열 연결/eval하지 않는다. URI 원문은 재인코딩·정규화하지 않는다. 네트워크 응답은 외부 입력으로 검증한다.
## 링크 존재 조합 확인표 (작성자 추천)
`있음`은 해당 주소가 nonblank임을 뜻한다. 아래 탭 동작은 작성자 추천이며 UI 의무 계약이 아니다.
| web | Android | iOS | 유효 표시 대상 | Android 탭 | iOS 탭 |
|---|---|---|---|---|---|
| 없음 | 없음 | 없음 | 없음 | 표시 안 함 | 표시 안 함 |
| 있음 | 없음 | 없음 | 양쪽 | 웹 | 웹 |
| 없음 | 있음 | 없음 | Android | 딥링크 | 표시 안 함 |
| 없음 | 없음 | 있음 | iOS | 표시 안 함 | 딥링크 |
| 있음 | 있음 | 없음 | 양쪽 | 딥링크 우선, 실패 시 웹 | 웹 |
| 있음 | 없음 | 있음 | 양쪽 | 웹 | 딥링크 우선, 실패 시 웹 |
| 없음 | 있음 | 있음 | 양쪽 | Android 딥링크 | iOS 딥링크 |
| 있음 | 있음 | 있음 | 양쪽 | 딥링크 우선, 실패 시 웹 | 딥링크 우선, 실패 시 웹 |
## 수용 및 검증
실제 앱 구조에 맞는 테스트를 추가한다. 최소 검증 범위:
- 모든 항목 표시, 응답 순서 유지, 홈/콘텐츠 placement 격리, 빈 목록에서 gap 없음.
- JP와 KR·US·국가 누락 및 강제 매핑에서 서버가 선택한 목록을 그대로 소비하고 공개 6필드에 `lang`을 요구하지 않는지 확인한다.
- URI 입력을 보존하면서 대상 OS 링크 우선, OS 링크 부재 시 웹, 딥링크 실패 시 웹 fallback 한 번, 양쪽 실패 시 비치명 상태.
- 다른 OS 링크를 실행하지 않고 잘못된 scheme을 거부한다.
- 비로그인 두 GET의 `data.subBanners`를 소비하며 별도 배너 요청이 발생하지 않는다. 추천 API 오류와 정상 빈 배열을 구분하고, 개별 이미지·링크 오류는 다른 추천 콘텐츠를 깨뜨리지 않는다.
- fixture 검증은 명시 모드에 한정되고 정상 운영 요청에 자동 적용되지 않는다.
최소 변경으로 구현하고 관련 focused test, 프로젝트 type/lint 검사, 실제 화면에서 두 영역·빈 상태·tap 동작을 확인한다. 서버나 API를 구현하지 말고, 서버 준비를 완료했다고 보고하지 않는다.
@@ -1,16 +0,0 @@
CREATE TABLE sub_banner (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '서브 배너 ID',
placement VARCHAR(32) NOT NULL COMMENT '노출 위치: HOME_RECOMMENDATION, CONTENT_RECOMMENDATION',
image_path LONGTEXT NOT NULL COMMENT '배너 이미지 S3 object key',
web_url LONGTEXT NULL COMMENT '웹 이동 URL',
android_deep_link LONGTEXT NULL COMMENT 'Android 이동 딥링크',
ios_deep_link LONGTEXT NULL COMMENT 'iOS 이동 딥링크',
start_date TIMESTAMP NULL DEFAULT NULL COMMENT '노출 시작 시각 (UTC 초 단위, NULL이면 시작 제한 없음)',
end_date TIMESTAMP NULL DEFAULT NULL COMMENT '노출 종료 시각 (UTC 초 단위, NULL이면 종료 제한 없음)',
is_active BOOLEAN NOT NULL DEFAULT TRUE COMMENT '활성 여부 (false이면 삭제)',
lang VARCHAR(10) NOT NULL DEFAULT 'KO' COMMENT '서브 배너 노출 언어 (KO 기본, EN/JA 등록 가능)',
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
PRIMARY KEY (id),
INDEX idx_sub_banner_placement_id (placement, id)
) COMMENT = '가로형 서브 배너';
@@ -1,665 +0,0 @@
# 가로형 서브 배너 백엔드 구현 계획
| 문서 항목 | 내용 |
|---|---|
| 상태 | P7 언어 기능·P8 정적 이관 SQL 검증 및 리뷰 완료, 미배포 |
| 작성일 | 2026-10-29 |
| 요구사항 기준 | [prd.md](prd.md) |
| API 기준 | [api-contract.md](api-contract.md), 실제 구현·HTTP 검증 계약 |
| 현재 Phase | Phase 2~8 완료 |
| 현재 활성 Goal | 없음 |
| 다음 Goal | 없음 |
## 목표
두 placement의 서브 배너를 독립 테이블과 백엔드 API로 제공한다. 기존 문서 준비 Goal `DOC-T1`~`DOC-T5`는 완료된 역사적 문서 작업이다. 이후 사용자가 문서대로 백엔드 코드 및 DDL 생성을 승인했으며, 운영 DB 적용·배포는 범위 밖이다.
## 범위
### 포함
- `prd.md`의 요구사항 요약과 결정 상태 기록
- `api-contract.md`의 실제 API 계약
- 독립 `v2.subbanner` 기능 모듈·DDL·관리자 CRUD·소프트 삭제 및 기존 두 추천 GET 응답 합성
- 현재 구현 작업은 신규 subbanner 코드·테스트·DDL 파일 생성과 실제 계약 문서 동기화를 포함한다. 이전 문서 전용 작업은 별도 완료 이력으로 보존한다.
### 제외
- **현재 제외:** 운영 DB DDL 적용·배포. 코드 변경이 포함된 이번 구현에서는 테스트·lint·빌드를 실행했다. 문서 전용 변경에 대한 Gradle 생략 규칙은 유지한다.
- **향후 구현 범위 밖:** 앱/관리자 실제 UI, 기존 대형 배너 변경, scheduler/job, 순서 편집, 활성화 switch, analytics
- 배포, 운영 DB 직접 변경, 기존 콘텐츠 배너 schema migration
- 운영 배포가 완료됐다는 주장
- 신규 dependency, global exception rewrite, 공통 utility wrapper
- 앱/client network 통합은 backend 구현 후 별도 계약 검토와 제공이 끝날 때까지 차단한다. backend를 알 수 없는 외부 block으로 취급하지 않는다.
### 승인된 언어 후속 범위
- [2026-11-02 승인 후속] 재사용 `Lang`의 KO/EN/JA로 서브 배너를 저장한다. 관리자 생성 누락은 KO, 수정 누락은 유지, explicit null/non-text/invalid는 upload/write 전 HTTP 400이다. Public 조회는 member 국가로 JP→JA, 그 외→KO를 선택하며 관리자 목록은 언어 미필터다.
- public `SubBannerResponse`는 기존 필드를 유지하고, 운영 DB/DDL 실행·UI·event link parsing·event detail/adult 변경·새 dependency는 금지한다.
- 신규 설치용 `create-sub-banner.sql`과 `20261102_add_sub_banner_lang.sql`을 함께 갱신한다. KO backfill은 소재의 JA 여부와 연결 이벤트 언어를 자동 추정하지 않으며, 운영 담당자의 수동 분류·확인을 적용 전에 요구한다.
## 문서 변환 Goal
### `DOC-T5` 백엔드 계획 문서 변환
**Goal 실행 `DOC-T5`:** 사용자 승인 범위에서 PRD와 계획 문서만 backend 요구사항 및 향후 구현 계획으로 변환한다.
- **시작 조건:** `DOC-T1`~`DOC-T4`의 기존 문서 결과가 있고 사용자가 backend 문서 보완과 문서 검증 지침 수정을 승인했다.
- **완료 증거:** 지정된 기존 문서 세 파일만 수정, 신규 backend Goal은 전부 미체크, 과거 DOC 체크박스/Gates/Progress와 이전 Gradle 증거 보존.
- **범위 밖:** API 구현 승인, 코드·SQL 신규 파일 작성, Gradle/test/build 실행, 앱·관리자 prompt 변경.
- **TDD 예외 사유:** 문서 전용 변경이다.
- **대체 검증 방법:** PRD 요구 ID↔Goal 추적, 정확한 path/signature 일치, 과거 완료 기록과 미실행 검증 상태를 수동 대조한다.
- [x] PRD와 backend Phase/Goal 초안 작성 완료.
- [x] 부모 작업자가 문서 대조·공백 검사 및 범위를 확인했다. 아래 `DOC-T5` 최종 검증 기록을 따른다.
## 백엔드 구현 공통 제약
- 기술 기준은 저장소의 Kotlin·Java 17·Spring Boot 2.7.14·JPA/QueryDSL·JUnit 5와 Gradle Wrapper를 그대로 사용한다. 버전·dependency 변경은 계획에 포함하지 않는다.
- 서브 배너 도메인·관리자는 `v2/subbanner`에 두고 기존 `v2/api/home` 및 `v2/api/content/recommendation`의 facade/DTO에서 응답을 합성한다. 대응 테스트 경로도 같은 책임을 따른다.
- 데이터 계층은 한 개의 독립 기능 모듈로 유지한다. `SubBannerController`는 P6에서 제거했고, `AdminSubBannerController`와 `SubBannerService`·persistence·6필드 public DTO는 재사용한다. 단일 클래스 파일명은 ktlint 규칙을 따른다.
- 현재 앱 조회는 `GET /api/v2/home/recommendations`, `GET /api/v2/audio/recommendations`의 `data.subBanners`다. 관리자 경로는 `/admin/sub-banners`를 유지한다. 이전 Phase의 standalone GET 기록은 당시 구현 이력이며 현재 계약은 [api-contract.md](api-contract.md)를 따른다.
- 파일/링크/날짜 입력을 경계에서 검사한다. 오류는 기존 `ApiResponse`/`SodaExceptionHandler` 사실을 확인하고 global handler는 고치지 않는다.
- DDL은 `docs/20261029_가로형서브배너/create-sub-banner.sql`이며 P5에서 is_active 기본 true를 추가했다. 테스트용 Flyway/자동 live migration을 만들지 않는다.
- 기존 S3Uploader, 이미지 검증기 및 QueryDSL/JPA를 재사용한다. GIF는 허용하며 S3 object 자동 삭제/정리는 제공하지 않는다. 새 dependency는 추가하지 않았다.
- 시간은 KST 분 입력→UTC 초 단위 DB 값→KST 분 응답이다. `TIMESTAMP` DDL precision을 확인하고 service에서 한번 얻은 `now`를 초 단위로 정규화한다.
- 각 단계의 원래 명령은 계획이며 실제 실행 결과는 해당 Progress를 따른다. 문서 전용 변경은 Gradle을 실행하지 않고, 코드 변경의 Gate는 테스트·lint·빌드 증거로 판정한다.
## Historical Phase 1: 문서 작성 완료 기록
아래 `DOC-T1`~`DOC-T4`, Gate와 Progress는 기존 문서 작업 이력이다. 새 backend Phase의 완료 상태나 구현 착수 근거가 아니다.
**Phase 결과:** 요구사항, 제안 API와 두 독립 구현 프롬프트가 서로 일치하는 문서 묶음.
### Task 1.1 요구사항과 준비 계획
**Goal 실행 `DOC-T1`:** 샘플에 맞춰 PRD와 문서 작성 계획을 작성한다.
- **시작 조건:** 사용자 확정 요구, 프로젝트 문서 가이드 및 샘플 확인.
- **완료 증거:** 정확한 파일 두 개 작성, `USER REQUIREMENTS`와 `AUTHOR PROPOSALS` 구분.
- **범위 밖:** 코드 구현, 추가 계획 문서.
- **TDD 예외 사유:** 문서 전용 변경으로 실행 동작이 없다.
- **대체 검증 방법:** 요구사항 표와 문서 가이드 대조.
**Files:** `docs/20261029_가로형서브배너/prd.md`, `docs/20261029_가로형서브배너/plan-task.md`
- [x] 요구사항, 비목표, 외부 의존, 결정 기록 작성.
- [x] 구현 계획을 문서 준비 범위로 한정.
### Task 1.2 계약 및 독립 프롬프트
**Goal 실행 `DOC-T2`:** API 제안과 독립 실행 가능한 앱·관리자 프롬프트를 작성한다.
- **시작 조건:** `DOC-T1` 문서 완료.
- **완료 증거:** 요청된 세 파일 작성, API 필드/라우트/오류 상태가 PRD와 일치, 각 prompt에 필요한 계약을 자체 포함.
- **범위 밖:** 서버 구현 지시, 실 API 연결, 특정 앱/admin 코드베이스 존재 가정.
- **TDD 예외 사유:** 문서 전용 변경으로 실행 동작이 없다.
- **대체 검증 방법:** PRD/API/prompt 사이 필드, 인증, 주소 처리, 차단 조건 교차 점검.
**Files:** `docs/20261029_가로형서브배너/api-contract.md`, `docs/20261029_가로형서브배너/app-prompt.md`, `docs/20261029_가로형서브배너/admin-prompt.md`
- [x] endpoint와 전송 형식을 하나의 최소 제안으로 고정한다.
- [x] 두 prompt를 별도 사용 가능하게 만들고 백엔드 구현 지시를 제외한다.
- [x] 콘솔에 prompt 본문을 출력하지 않는다.
### Task 1.3 출처 표기 및 독립 사용성 보정
**Goal 실행 `DOC-T3`:** 초안 검토에서 발견한 확정 요구·제안 혼용을 고치고 프롬프트의 독립 사용성을 검증한다.
- **시작 조건:** `DOC-T2` 작성 완료와 부모 검토.
- **완료 증거:** 제안 상태, 응답 예시, 주소 조합표, URL 검증 및 순서 설명을 부모가 직접 대조.
- **범위 밖:** 새로운 제품 결정, 서버 구현 및 실제 앱·관리자 연결.
- **Files:** 같은 디렉터리의 `prd.md`, `api-contract.md`, `app-prompt.md`, `admin-prompt.md`.
- **TDD 예외 사유:** 실행 코드가 없는 문서 보정.
- **대체 검증 방법:** 아래 Progress의 직접 대조·독립 검토·공백 검사.
- [x] 사용자 확정 범위와 작성자 제안을 분리하고 두 프롬프트의 계약·검증 사례를 보완했다.
### DOC-T4 후속: 관리자 노출 기간
**Goal 실행 `DOC-T4`:** 사용자 확인을 받은 콘텐츠 배너 동등 노출 기간 설정을 기존 다섯 문서에 일관되게 반영한다.
- **시작 조건:** 사용자가 관리자 페이지에서 콘텐츠 배너와 동일하게 노출 기간 설정이 필요하다고 확인했다.
- **범위:** 기존 문서만 수정한다. 구현 계획의 TDD 예외는 문서 전용 변경으로 실행 동작이 없기 때문이다.
- **Files:** `docs/20261029_가로형서브배너/prd.md`, `docs/20261029_가로형서브배너/plan-task.md`, `docs/20261029_가로형서브배너/api-contract.md`, `docs/20261029_가로형서브배너/app-prompt.md`, `docs/20261029_가로형서브배너/admin-prompt.md`.
- **완료 기준:** 시작·종료 경계 의미, KST 입력/응답 형식, create/update 생략·null 규칙, 기간 역전 검증, 공개 응답 DTO 불변, 관리자 기간 무관 목록, 앱 기간 필터와 OS 필터가 모든 문서에서 일치한다. 관리자 프롬프트에 KST 입력, 경계 개별 해제, 오류/편집 보존 및 기간 외 기록 편집 기준을 포함한다.
- **TDD 예외 사유:** 문서 전용 변경으로 실행 동작이 없다.
- **대체 검증 방법:** 다섯 문서의 용어·JSON 예시·요청/응답 규칙 상호 대조와 공백 검사.
- **부모 검증:** 아래 후속 `DOC-T4-GATE`와 부모 작업자의 `./gradlew tasks --all` 검증은 별도로 수행한다. 과거 `DOC-GATE` 완료 기록은 유지한다.
- [x] 다섯 기존 문서에 후속 요구와 독립 프롬프트 세부사항을 반영한다.
- [x] 부모가 문서 내용을 검토하고 후속 검증을 수행했다.
#### 후속 Gate `DOC-T4-GATE`
- **시작 조건:** `DOC-T4` 문서 보완 완료.
- **완료 증거:** 기존 콘텐츠 배너 규칙과 다섯 문서 대조, 공백 검사, Gradle 문서 검증 명령 결과 기록.
- **범위 밖:** 실제 API·관리자 화면 구현 및 실연동 완료 판정.
- [x] 부모가 노출 기간 문서의 후속 검증을 완료했다.
### Phase 1 Gate `DOC-GATE`
- **시작 조건:** `DOC-T1`, `DOC-T2`, `DOC-T3` 작성 완료.
- **완료 증거:** 요청된 파일만 관리했으며 문서 내용과 경로를 대조.
- **범위 밖:** 제품 기능 구현 완료, API 제공·배포 완료 판정.
- [x] 부모 작업자가 변경 파일과 요구사항 추적을 검증했다.
`DOC-GATE`의 기존 완료 기록은 `DOC-T3` 당시 검증 기록이다. `DOC-T4` 후속 반영은 별도 `DOC-T4-GATE`와 아래 부모 검증 기록으로 판정하며 과거 완료 기록으로 대체하지 않는다.
검증 명령: 부모 작업자가 `./gradlew tasks --all`을 실행했고 `BUILD SUCCESSFUL`, 종료 코드 0을 확인했다. 상세 증거는 아래에 누적한다.
## Historical DOC-T1~DOC-T4 변경 금지
아래 지침은 당시 문서-only 작업 범위의 기록이며 새 backend 계획에는 적용하지 않는다.
- 기존 다섯 파일 외의 파일을 변경하지 않는다.
- backend, DB/schema/migration, architecture, 배포 구현 지시를 작성하지 않는다.
- 제안 경로를 실제 배포 경로라고 표현하지 않는다.
- 요청된 다섯 파일 이외의 파일을 만들지 않는다.
## Progress
### `DOC-T1` 1차 실행, 2026-10-29
- 상태: 완료
- 무엇을: PRD와 문서 준비 계획 작성.
- 왜: 앱/관리자 구현 요청 전에 사용자 요구와 문서 범위를 분명히 하기 위해.
- 어떻게: 프로젝트 작업절차·문서유지보수 가이드 및 샘플과 기존 API 근거를 읽고 요구사항을 분리해 기록.
- 남은 항목: `DOC-T2`, 부모 최종 검증.
- 다음 행동: 계약과 프롬프트 작성.
### `DOC-T2` 1차 실행, 2026-10-29
- 상태: 작성 완료, 부모 검증 대기
- 무엇을: API 제안, 독립 앱 프롬프트, 독립 관리자 프롬프트 작성.
- 왜: 별도 담당자가 현재 코드베이스나 prompt 원문 없이도 요구와 제안 계약을 이해하도록 하기 위해.
- 어떻게: PRD의 요구사항 및 차단 경계를 계약 모델·endpoint·수용 기준에 대조.
- 남은 항목: 부모 작업자의 문서 검토와 `./gradlew tasks --all`.
- 다음 행동: 부모가 Gate 검증을 기록한다.
### `DOC-T3` 후속 보정 및 `DOC-GATE`, 2026-10-29
- 상태: 문서 보정·최종 검증 완료. 제품 기능과 신규 API는 미구현이다.
- 무엇을: 사용자 확정 요구와 작성자 제안의 출처를 정정하고, 두 독립 프롬프트의 JSON 예시·8가지 주소 조합·오류 처리·multipart·null 삭제 규칙을 대조했다.
- 왜: 실제로 제공되지 않은 API나 승인되지 않은 링크 우선순위를 확정 계약처럼 전달하지 않기 위해.
- 어떻게: 부모가 다섯 파일 전체와 기존 추천/관리자 Controller·배너 DTO·공통 응답 근거를 직접 읽었다. 앱의 위험 URI scheme 표기를 `javascript`로 정정하고 대소문자 무관 검사를 명시했다.
- 독립 검토: 첫 검토 에이전트는 모델 호환성 오류로 실행되지 않았다. 대체 검토는 완료됐으며 순서 충돌 후보 1건을 보고했다. 부모 대조 결과 서버의 id 오름차순과 클라이언트의 응답 순서 보존은 양립하므로 충돌은 아니다. 오해를 줄이도록 두 프롬프트에 서버 순서와 클라이언트 재정렬 금지를 함께 적었다. 그 외 중대한 누락은 보고되지 않았다.
- 명령 검증: `./gradlew tasks --all` 재실행은 `BUILD SUCCESSFUL in 999ms`, 종료 코드 0이었다. 기존 Gradle deprecation 안내가 있었다.
- 공백 검증: 다섯 파일 각각 `GIT_MASTER=1 /usr/bin/git diff --no-index --check -- /dev/null 파일경로` 실행, 출력 없음·종료 코드 0. 최초 셸 검사에서 zsh의 예약 변수 `path`로 명령 검색이 실패해 `doc_path`와 절대 git 경로로 고친 뒤 재실행했다. 파일 내용 문제는 아니었다.
- 변경 범위: `GIT_MASTER=1 /usr/bin/git -c core.quotePath=false status --short --untracked-files=all`에서 해당 디렉터리의 새 Markdown 다섯 개만 확인했다. 기존 파일 변경, 커밋, 배포는 없다.
- 생략·한계: 문서만 변경하여 전체 테스트·빌드 및 실제 앱/관리자 화면 QA는 실행하지 않았다. Markdown LSP 진단 도구가 제공되지 않아 직접 내용 대조와 공백 검사로 대체했다. 신규 API 실연동은 계약 합의·제공 후 별도 검증이 필요하다.
### `DOC-T4` 후속 반영, 2026-10-29
- 상태: 문서 수정 완료, 부모 검증 대기. 기존 `DOC-GATE`의 과거 완료 상태는 변경하지 않으며 이번 검증은 `DOC-T4-GATE`로 구분한다.
- 무엇을: 콘텐츠 배너와 같은 기간 설정 요구를 기존 다섯 문서에 반영한다.
- 왜: 관리자가 가로형 서브 배너에도 예약 노출 경계를 설정하고 목록에서 기간 외 레코드까지 관리할 수 있도록 계약 제안을 명확히 하기 위해.
- 어떻게: 기존 콘텐츠 배너 예약 PRD와 구현을 근거로 KST 분 정밀도, 종료 분 inclusive 경계, 생성/수정 null 의미를 문서화한다. 공개 `SubBanner`는 유지하고 기간 필터는 앱 조회 보장으로만 정의한다.
- 남은 항목: 부모 작업자의 문서 검토, `./gradlew tasks --all` 및 최종 문서 검증.
- 변경 범위: 지정된 기존 다섯 Markdown만 수정. 코드·신규 파일·API 구현은 없다.
- 생략·한계: 이 후속 문서 작업에서는 Gradle, 런타임 및 배포 검증을 수행하지 않았다. 신규 API는 제안 상태이며 구현·승인은 별도다.
### `DOC-T4-GATE` 부모 검증, 2026-10-29
- 상태: 문서 후속 검증 완료. 신규 API와 실제 관리자·앱 기능의 구현 완료를 뜻하지 않는다.
- 무엇을·왜: 다섯 문서를 직접 읽고 기존 콘텐츠 배너의 PRD·Service·응답 formatter·노출 조건과 대조하여 날짜 계약의 차이를 방지했다.
- 대조 결과: KST 분 입력/응답과 초 단위 포함 경계를 구분했고, null/null·한쪽 경계·동일 분·역전/잘못된 입력·수정 생략 유지와 null 해제 규칙이 일치한다. 관리자 목록은 기간 무관, 공개 목록은 기간 내 항목만 반환하며 공개 DTO와 기존 OS 링크 필터는 유지한다.
- 보정: 관리자 응답의 기존 필드 타입을 보존하고 요청·응답 JSON 예시의 기간을 맞췄다. 기간만 수정할 때 기존 주소와 이미지를 보존하도록 명시했으며, 과거 Gate와 후속 Gate를 분리했다.
- 명령: `./gradlew tasks --all`은 `BUILD SUCCESSFUL in 1s`, 종료 코드 0. 다섯 파일 각각 `GIT_MASTER=1 /usr/bin/git diff --no-index --check -- /dev/null 파일경로`도 출력 없음·종료 코드 0이었다.
- 범위: `GIT_MASTER=1 /usr/bin/git -c core.quotePath=false status --short --untracked-files=all`에서 기존 서브 배너 Markdown 다섯 개만 확인했다. 새 문서·코드 변경·커밋·배포는 없다.
- 생략·한계: 문서 변경이므로 전체 테스트·빌드 및 실제 관리자/앱 UI·API 연동은 검증하지 않았다. Markdown LSP 도구 미제공으로 직접 계약 대조와 공백 검사로 대체했다. 신규 API는 계약 제안 상태를 유지한다.
## Phase 2: 데이터 모델 및 기간 규칙
**Phase 결과:** 새로운 독립 테이블과 도메인/persistence 계층에서 배너를 저장하고 placement, 주소, 기간 규칙을 보장한다.
**선행조건:** 부모가 backend 요구사항과 제안 API를 검토하고 구현 착수를 별도 승인. 과거 Phase 1/DOC Gate 완료는 backend 구현 승인이 아니다.
### Task 2.1 독립 데이터 모델, 기간 처리와 DDL
**Goal 실행 `P2-T1`:** `SubBanner` 저장 모델과 독립 SQL artifact를 정의하고 DB 왕복으로 초 정밀도 및 기간 규칙을 증명한다.
- **요구사항:** `SB-001`, `SB-002`, `SB-006`, `SB-010`.
- **완료 증거:** 도메인 및 repository test, DDL의 테이블/컬럼 comment와 nullable UTC second-precision period, JPA flush/clear/reload 결과 기록.
- **시작 조건:** backend 착수 승인. 첫 구현 checkpoint에서 GIF 허용 여부와 S3 object 삭제/교체 실패 시 정책을 검토하고 사용자 확인이 필요한 선택은 구현 전에 결정 기록에 추가한다. 권고안은 기존 Tika `image/*` 검증을 재사용하고 GIF 허용, 기존 DB 변경 없음, S3 자동 cleanup 미보장이다.
- **범위 밖:** API/controller, multipart upload, 운영 DB 적용, 기존 content_banner migration.
- **TDD 예외 사유:** 없음.
**Files (모두 PROPOSED):**
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/domain/SubBanner.kt`
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/domain/SubBannerPlacement.kt`
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/port/out/SubBannerRepository.kt`
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/adapter/out/persistence/SubBannerEntity.kt`
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/adapter/out/persistence/DefaultSubBannerRepository.kt`
- Create: `docs/20261029_가로형서브배너/create-sub-banner.sql`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/subbanner/domain/SubBannerTest.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/subbanner/adapter/out/persistence/SubBannerPersistenceTest.kt`
**Interfaces:**
- Produces: `enum class SubBannerPlacement { HOME_RECOMMENDATION, CONTENT_RECOMMENDATION }`; `data class SubBanner(val id: Long? = null, val placement: SubBannerPlacement, val imagePath: String, val webUrl: String?, val androidDeepLink: String?, val iosDeepLink: String?, val startDate: LocalDateTime?, val endDate: LocalDateTime?)`; `interface SubBannerRepository { fun findById(id: Long): SubBanner?; fun findAllByPlacement(placement: SubBannerPlacement): List<SubBanner>; fun findVisibleByPlacement(placement: SubBannerPlacement, now: LocalDateTime): List<SubBanner>; fun save(subBanner: SubBanner): SubBanner; fun deleteById(id: Long) }`. `imagePath`는 S3 object key이며 DTO에서만 기존 `cloud.aws.cloud-front.host`와 조합해 `imageUrl`을 만든다.
- Consumes: 기존 `BaseEntity`, QueryDSL/JPA와 프로젝트 DDL convention. 만든 repository의 `findVisibleByPlacement`에서 null 경계 독립 unbounded, 양끝 포함, id asc 정렬.
제안 테이블은 `sub_banner`이며 아래 매핑을 `SubBannerEntity` 및 향후 SQL에 함께 적용한다. 이는 검토용 저장 설계이지 기존 테이블이나 확정된 운영 스키마가 아니다.
| 컬럼 | 제안 MySQL 타입·규칙 | 매핑 |
|---|---|---|
| `id` | `BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY` | `BaseEntity.id` |
| `placement` | `VARCHAR(32) NOT NULL` | `SubBannerPlacement`, enum 이름 저장 |
| `image_path` | `LONGTEXT NOT NULL` | 서버가 생성한 S3 object key, 절대 URL 아님 |
| `web_url`, `android_deep_link`, `ios_deep_link` | 각각 `LONGTEXT NULL` | 기존 URI를 255자 등으로 잘라 저장하지 않음 |
| `start_date`, `end_date` | 각각 `TIMESTAMP NULL DEFAULT NULL` | UTC 초 단위, H2 검증 컬럼은 `TIMESTAMP(0)` |
| `is_active` | `BOOLEAN NOT NULL DEFAULT TRUE` | `SubBannerEntity.isActive`; P5 후속 소프트 삭제 시 false |
| `created_at` | `TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP` | `BaseEntity.createdAt` |
| `updated_at` | `TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP` | `BaseEntity.updatedAt` |
모든 컬럼·테이블에 MySQL COMMENT를 붙이고 `(placement, id)` 인덱스를 둔다. `BaseEntity`와 전역 시간 설정은 변경하지 않는다. DDL은 신규 table CREATE 한 개이며 rollback 제안은 데이터 보존 확인 및 별도 승인 이후 해당 신규 table만 DROP, 자동 rollback 실행은 금지다. 삭제는 승인된 구현에서 해당 DB row만 제거하는 제안이며 S3 object는 자동 삭제하지 않는다.
- [x] **RED:** 링크 불변식·기간·목록·수정·삭제의 실패 테스트를 먼저 작성했다.
- [x] **RED 확인:** 위 두 focused 클래스에서 26개 중 19개 assertion failure를 확인했다. 컴파일 실패는 RED 증거로 세지 않았다.
- [x] **GREEN:** domain, Entity, QueryDSL repository와 신규 테이블 DDL을 구현했다.
- [x] **GREEN 확인:** 같은 focused 테스트 26개 통과. 실제 H2 `TIMESTAMP(0)`의 flush/clear/reload, 긴 URI, 기간·placement·25개 초과 목록·수정·삭제를 검증했다.
- [x] **REFACTOR:** 직접 영향 배너·creatorname 회귀를 포함한 50개 테스트와 `ktlintCheck` 통과. 부모의 별도 focused 재실행도 26개 통과했다.
### Phase 2 Gate
**Goal 실행 `P2-GATE`:** 독립 schema와 시간/persistence 경계를 backend feature로 확정한다.
- **시작 조건:** `P2-T1` 완료.
- **완료 증거:** focused 테스트 통과, SQL review에서 신규 table 외 변경 없음, 결정 checkpoint 기록.
- **범위 밖:** 운영 DB 적용, app/admin 구현.
- **검증:** `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.subbanner.*'` 및 `./gradlew ktlintCheck`, 둘 다 **구현 시 실행, 이번 작업 미실행**. 전체 test/build는 공통 보안/설정 영향 또는 final Gate 등 project guide 조건에서만 실행한다.
- **Expected:** DB reload 뒤 날짜 정확도와 모든 허용 링크 조합 확인, ktlint 성공, live DDL 실행 0회.
- [x] `P2-T1` 완료 증거 확인. 독립 P2 리뷰는 명세·품질 승인, 차단 사항 없음.
- [x] DDL과 Entity의 테이블·컬럼·정밀도·index·COMMENT 일치 및 기존 데이터 비변경을 검토했다. 운영 적용·rollback은 별도 승인 대상이다.
| Goal | 선행조건 | 종속 산출물 |
|---|---|---|
| `P2-T1` | backend 착수 승인 | domain/repository 인터페이스, 신규 SQL artifact |
| `P2-GATE` | `P2-T1` | Phase 3 착수 조건 |
## Phase 3: 관리자 API 및 multipart 이미지
**Phase 결과:** ADMIN만 multipart 기반 CRUD를 수행하고, 유효성 검사 실패가 image upload/DB 변경 없이 끝난다.
**선행조건:** `P2-GATE` 완료 및 관리자 API contract 검토.
### Task 3.1 관리자 CRUD
**Goal 실행 `P3-T1`:** 관리자 CRUD와 이미지 업로드를 구현하고 요청 검증, 병합 기간, 응답 envelope를 통합 테스트로 확인한다.
- **요구사항:** `SB-003`~`SB-007`, `SB-011`, `SB-012`.
- **완료 증거:** create/list/update/delete 통합 테스트, DB 저장된 URI exact preservation, S3 object key의 기존 CDN URL 변환, 기간 KST exact roundtrip, 검증 실패 전 upload/save 없음.
- **시작 조건:** `P2-GATE`, ADMIN route/API draft review. 이미지 정책은 `P2-T1` decision checkpoint에서 확정.
- **범위 밖:** 공개 조회, ordering, cleanup scheduler, 공통 exception rewrite, 무단 400/404 보장.
**Files (Create는 신규 제안 경로, Reference는 기존 파일):**
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/adapter/in/web/AdminSubBannerController.kt`
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/dto/SubBannerRequest.kt`
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/dto/AdminSubBannerResponse.kt`
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/application/SubBannerService.kt`
- Reference: `src/main/kotlin/kr/co/vividnext/sodalive/configs/SecurityConfig.kt`의 관리자 경로는 기존 `anyRequest().authenticated()` 유지, 별도 permitAll 추가나 이 Task의 설정 수정은 없다.
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/subbanner/adapter/in/web/AdminSubBannerControllerIntegrationTest.kt`
- 서비스 동작은 위 실제 HTTP→service→JPA 통합 테스트에서 검증한다. 같은 시나리오만 반복하는 별도 service unit test는 추가하지 않는다.
**Interfaces:**
- Consumes: `SubBannerRepository`, `SubBannerPlacement`, 기존 `S3Uploader.upload(inputStream: InputStream, bucket: String, filePath: String, metadata: ObjectMetadata? = null): String`의 반환 object key, 해당 key를 public `imageUrl`로 만드는 기존 CDN 변환 방식, `validateImage(file: MultipartFile, gifAllowed: Boolean)`.
- Produces: `SubBannerService.findAllByPlacement(placement: SubBannerPlacement): List<SubBanner>`, `create(image: MultipartFile, request: String): SubBanner`, `update(id: Long, image: MultipartFile?, request: String): SubBanner`, `delete(id: Long): Unit`. 서비스는 raw JSON의 필드 존재 여부·타입을 검사한 뒤 DTO로 변환하여 생략된 날짜와 명시적 null을 잃지 않는다. 기본 4필드의 누락도 검증한다. Controller at `/admin/sub-banners`: `GET list(placement): ApiResponse<List<AdminSubBannerResponse>>`; `POST create(image: MultipartFile, request: String): ApiResponse<AdminSubBannerResponse>`; `PUT /{id} update(id: Long, image: MultipartFile?, request: String): ApiResponse<AdminSubBannerResponse>`; `DELETE /{id} delete(id: Long): ApiResponse<Any>`. DELETE는 서비스의 Unit을 data로 전달하지 않고 `data:null`인 성공 응답을 만든다. Controller class ADMIN preauthorization. `AdminSubBannerResponse` has `id, placement, imageUrl, webUrl, androidDeepLink, iosDeepLink, startDate, endDate`; create/update request wire fields follow `api-contract.md`. 공개 서비스 메서드는 `P4-T1`에서 추가한다.
- [x] **RED:** 실제 HTTP/JWT/H2/S3 대체 경계에서 CRUD·8개 주소 조합·JSON/URI/날짜 검증·생략/null·이미지 실패·기간 무관 목록 테스트를 먼저 작성했다.
- [x] **RED:** 익명 및 모든 비관리자 역할 거부, 없는 id의 404·무변경 테스트도 작성했다.
- [x] **RED 확인:** 신규 HTTP 테스트 39개에서 assertion failure 39개를 확인했다. 이후 DST gap 회귀에서도 43개 중 2개가 기대 400/실제 200으로 실패했다.
- [x] **GREEN:** 관리자 controller·service·DTO를 구현했다. 검증 후에만 업로드/저장하며 트랜잭션·이미지 보존·row 삭제·실제 오류 계약을 적용했다.
- [x] **GREEN 확인:** 최초 39/39, DST 회귀 수정 후 실제 HTTP 43/43 통과. POST/PUT 시작·종료 gap 거부·upload 0·DB 불변과 정상 과거/overlap 왕복을 확인했다.
- [x] **REFACTOR:** 수정 전 직접 영향 회귀 161/161 및 수정 후 focused 43/43·`ktlintCheck` 통과. 파일명은 클래스명에 맞춰 단수형으로 정리했다.
### Phase 3 Gate
**Goal 실행 `P3-GATE`:** CRUD 및 업로드의 검증 순서와 계약 응답을 판정한다.
- **시작 조건:** `P3-T1` 완료.
- **완료 증거:** multipart integration test, 저장 후 DB 확인, validation-failure 무변경 증거, 공통 응답 envelope 대조.
- **범위 밖:** public GET, browser UI, S3 object cleanup 보장.
- **검증:** `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.subbanner.adapter.in.web.AdminSubBannerControllerIntegrationTest'`와 `./gradlew ktlintCheck`. 실제 security 공통 영향을 수정했을 때는 `./gradlew test`로 검증을 확대한다. 실행 증거는 아래 Progress에 기록한다.
- **Expected:** 검증 실패는 upload/DB mutation 0회, 성공 POST/PUT 객체 및 DELETE null 응답, ADMIN만 변경.
- [x] `P3-T1` 완료 증거 확인. 독립 P3 리뷰의 DST blocker를 RED→GREEN으로 수정하고 scoped 재검토 승인.
- [x] 실제 400/404 Boot 오류 body, 익명 401, 비관리자·multipart 바인딩 오류의 기존 200 `success:false`를 HTTP로 확인했다. 소비자 문서의 최종 계약 동기화는 P4 최종 Gate에서 수행한다.
| Goal | 선행조건 | 종속 산출물 |
|---|---|---|
| `P3-T1` | `P2-GATE`와 API contract review | 관리자 CRUD endpoint 및 request/response DTO |
| `P3-GATE` | `P3-T1` | Phase 4 착수 조건 |
## Phase 4: 공개 기간 조회 및 보안 Gate
**Phase 결과:** 정확한 공개 GET만 익명 허용하고 현재 기간의 전체 목록을 id asc로 반환한다. 관리자/인접 method 보호를 end-to-end 확인한다.
**선행조건:** `P3-GATE` 완료.
### Task 4.1 공개 GET, 기간 filtering과 권한 통합 검증
**Goal 실행 `P4-T1`:** 익명 공개 조회와 접근 정책을 구현하고 운영 경로에 실제 공개 범위 외 노출이 없음을 검증한다.
- **요구사항:** `SB-007`~`SB-009`, `SB-011`.
- **완료 증거:** public/admin DTO 차이, placement/date/ordering, 정확한 GET 공개와 보호된 변형 경로 및 role test.
- **시작 조건:** `P3-GATE` 완료, proposed endpoint contract 확인.
- **범위 밖:** app OS link filtering, UI, pagination, active toggle, scheduler.
**Files (신규 경로 PROPOSED):**
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/adapter/in/web/SubBannerController.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/application/SubBannerService.kt` (공개 조회 및 고정 시각 seam 추가)
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/dto/SubBannerResponse.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/configs/SecurityConfig.kt`, 정확한 `GET /api/v2/sub-banners`만 permitAll.
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/subbanner/adapter/in/web/SubBannerControllerIntegrationTest.kt`
- 보안 시나리오는 같은 실제 HTTP/JWT/H2 context의 `SubBannerControllerIntegrationTest`에 통합했다. 중복 HTTP fixture와 별도 security test 클래스는 만들지 않았다.
**Interfaces:**
- Consumes: `P2-T1`의 `SubBannerRepository.findVisibleByPlacement(placement: SubBannerPlacement, now: LocalDateTime): List<SubBanner>`와 `P3-T1`의 CDN URL 조립 규칙.
- Produces: `SubBannerService.findVisibleByPlacement(placement: SubBannerPlacement): List<SubBanner>`와 `SubBannerController.getSubBanners(placement: SubBannerPlacement): ApiResponse<List<SubBannerResponse>>`. 서비스는 기존 `nowProvider: () -> LocalDateTime` 주입 패턴으로 UTC 시각을 한 번 얻어 초 단위 절삭 후 같은 값을 repository에 전달한다. public DTO는 정확히 `id, placement, imageUrl, webUrl, androidDeepLink, iosDeepLink`, 날짜 미포함. `SecurityConfig`에서 해당 GET만 익명 허용.
- [x] **RED:** 고정 시각·실제 DB·HTTP로 23개 공개 조회/권한 테스트를 작성했다. 두 placement, 전체 25개 목록, 빈 결과, nullable·초·소수초·자정 경계, 6필드 DTO 및 OS 비필터를 포함한다.
- [x] **RED 확인:** 공개 경로 미구현 상태에서 23개 중 22개 assertion failure(기대 200/400, 실제 401)를 확인했다.
- [x] **GREEN:** public controller/DTO·서비스 조회 및 정확한 GET matcher 한 줄을 추가했다. 기존 권한·추천 응답은 유지했다.
- [x] **GREEN 확인:** 실제 HTTP 23/23 통과. GET 외 method·HEAD·인접 경로·관리자 보호와 요청 시각 1회 조회를 검증했다.
- [x] **REFACTOR:** 기존 홈/오디오 추천 회귀 포함 96/96 및 ktlint 통과. 부모의 최종 전체 suite에서도 신규 92개를 포함한 2,676개가 통과했다.
### Phase 4 Gate
**Goal 실행 `P4-GATE`:** 신규 public/admin endpoint의 데이터·security·API 계약을 최종 검증한다.
- **시작 조건:** `P4-T1` 완료.
- **완료 증거:** Phase 2~4 focused tests 통과, 신규 SQL review, security behavior와 실제 공통 오류 응답 기록.
- **범위 밖:** API 배포/운영 DB 적용, 앱·관리자 client 연동 완료 주장.
- **검증:** `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.subbanner.*'` 및 관련 추천 회귀로 확인한 뒤 보안 설정 변경과 사용자 ulw 요구에 따라 부모가 `./gradlew test ktlintCheck bootJar --continue --console=plain`을 실행했다. 결과는 아래 최종 검증 기록을 따른다.
- **직접 영향 회귀:** `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.home.dto.recommendation.HomeRecommendationResponseTest' --tests 'kr.co.vividnext.sodalive.v2.api.content.recommendation.adapter.in.web.AudioRecommendationEndToEndTest'`는 **구현 시 실행, 이번 작업 미실행**이다. 기존 추천 응답이 바뀌지 않았는지 확인한다.
- **Expected:** focused test 성공, backend artifact bootJar 성공, exact public GET만 anonymous, 관리자 CRUD ADMIN-only, 전체 8 조합 및 기간/DB 정밀도 규칙 통과. 운영 DDL 실행과 app integration 완료 판정 0건.
- [x] `P4-T1` 및 모든 선행 Gate 증거 확인. 전체 테스트·lint·bootJar와 독립 최종 코드 리뷰 통과.
- [x] API 계약·앱/관리자 프롬프트를 실제 구현에 맞추고 미배포·운영 DB 미적용 상태를 구분했다.
| Goal | 선행조건 | 종속 산출물 |
|---|---|---|
| `P4-T1` | `P3-GATE` | public GET, 기간 query, exact security matcher |
| `P4-GATE` | `P2-GATE`, `P3-GATE`, `P4-T1` | backend 구현 검증, 별도 client integration 재개 조건 |
### 백엔드 실행 의존성
```text
P2-T1 → P2-GATE → P3-T1 → P3-GATE → P4-T1 → P4-GATE
```
backend checkbox는 실제 검증 후 갱신한다. 문서 작성/부모 검토 완료만으로 구현 완료를 표시하지 않는다. 사용자 구현 승인에 따라 순차적으로 한 개의 Goal만 active한다.
## Current Progress
### `DOC-T5` 문서 변환 초안, 2026-10-29
- 상태: 작성 초안 완료, 작성자 대조 및 부모 검증 대기.
- 무엇을: 기존 `prd.md`와 `plan-task.md`에 backend requirements와 `P2`~`P4` 향후 implementation plan을 추가했다. DOC-T1~4 역사적 checkbox/Gate/Progress는 유지했다.
- 왜: 앱·관리자 실제 구현 전에 서버 기능과 persistence를 codebase 근거에 맞게 검토할 수 있도록 하기 위해.
- 어떻게: API draft, project guides 및 기존 security, S3, image validation, reservation, exception, JPA test patterns를 대조했다. API 전면 승인·배포·구현 상태로 표현하지 않았다.
- 검증: PRD ID와 Goal, exact paths/signatures, proposed API shapes, 향후 DDL, historical checkboxes 및 미착수 backend checkboxes를 직접 대조했다. 이번 작업에서 Gradle/test/build를 실행하지 않았다.
- 남은 항목: 작성자 문서 대조 및 부모 검토. backend 구현은 별도 승인 대기.
- 다음 행동: 부모가 이 문서 Gate를 검증하고 반영한다.
### `DOC-T5` 부모 최종 문서 검증, 2026-10-29
- 상태: 백엔드 PRD·계획 문서 보완 및 문서 검증 지침 수정 완료. 백엔드 구현은 미착수이며 `P2-T1`과 모든 후속 구현 Task/Gate는 미완료다.
- 무엇을·왜: 프롬프트 작성 계획을 실제 백엔드 개발에 사용할 수 있는 요구사항·파일·인터페이스·TDD·Gate 계획으로 보완하고, 문서만 바꿀 때 불필요한 Gradle 실행을 제거했다.
- 문서 대조: `SB-001`~`SB-012`를 `P2-T1`·`P3-T1`·`P4-T1`과 연결했다. 사용자 확정과 작성자 제안을 구분하고, 8개 주소 존재 조합 중 모두 없는 경우만 거부·나머지 7개 허용으로 PRD/테스트 이름/계약을 맞췄다. 기간 형식·생략/null·노출 경계·관리자/공개 DTO는 기존 API 초안과 일치한다.
- 파일·책임 대조: 신규 파일은 모두 제안 경로로 표시했다. 저장 object key인 `imagePath`와 응답 `imageUrl`을 구분하고 각 Phase의 서비스 제공 메서드, 변경 파일, 신규 테이블 매핑을 일치시켰다. 기존 구현과 회귀 테스트 경로를 직접 확인했다.
- 이력 대조: `DOC-T1`~`DOC-T4`의 완료 체크박스와 과거 Gradle 실행 결과는 삭제하거나 새 작업 증거로 재사용하지 않았다. 새 백엔드 Task/Gate의 체크박스는 모두 미체크다.
- 공백 검사: `GIT_MASTER=1 /usr/bin/git diff --check -- docs/agent-guides/문서유지보수.md`와 PRD/계획 각각의 `git diff --no-index --check -- /dev/null 파일경로`는 출력 없음·종료 코드 0이었다.
- 범위 대조: 현재 승인 범위에서 수정한 파일은 이 PRD·계획 및 `docs/agent-guides/문서유지보수.md` 세 개다. 이전 작업에서 존재한 앱/관리자 prompt와 API 초안은 변경 대상에 넣지 않았다. 새 코드·SQL·빌드 설정·배포 변경은 없다.
- 미실행·사유: 사용자 승인과 수정한 문서 전용 검증 지침에 따라 이번 작업에서는 `./gradlew tasks --all`·테스트·빌드를 실행하지 않았다. 위 구현 단계의 명령들은 향후 검증 계획이며 이번 실행 결과가 아니다. 실제 API 동작과 배포는 검증하지 않았다.
- 다음 행동: PRD/API 제안을 검토하고 별도로 구현 착수를 승인한 뒤 `P2-T1`부터 재개한다. 이미지/GIF 및 S3 객체 보존 정책의 검토 checkpoint를 건너뛰지 않는다.
### 백엔드 구현 착수, 2026-10-29
- 승인: 사용자가 "문서대로 백엔드 코드, DDL 생성 진행"을 요청했다. 기존 설계의 독립 리소스·API·권한·기간 계약을 구현 기준으로 사용한다. 운영 DB 및 AWS에 검증용 요청을 보내지 않는다.
- 실행 방식: 단일 구현 담당자에게 단계별 작업을 위임하고 부모가 파일·실행 증거를 검증한다. 기존 `test` 브랜치에서 진행하며 새 worktree를 자동 생성하거나 이전 문서 변경을 되돌리지 않는다.
- 결정: GIF는 기존 이미지 검증기의 허용 옵션으로 지원하며, 삭제는 DB row에 한정하고 S3 object는 자동 삭제하지 않는다. 입력 오류/없는 리소스의 400/404는 신규 경계에서 처리하고 기존 공통 예외·권한 거부 정책은 변경하지 않는다.
- 검증 시나리오: 관리자 실제 HTTP CRUD와 7개 유효 주소 조합, 모두 빈 주소·잘못된 형식의 무변경 거부, KST 생략/null 및 DB 왕복, 기간/placement 공개 조회와 20개 초과 무절단 목록, 익명/비관리자 권한 거부 및 기존 추천 회귀를 확인한다.
- 도구 한계: 현재 host는 `lsp_diagnostics`를 제공하지 않는다. Kotlin 컴파일과 ktlint로 정적 오류를 검사하되 LSP 검증 완료로 표현하지 않는다.
- 자원: 실행 임시 root는 `/var/folders/yh/8xsbvpsj5wg2qnxzxdp11_gm0000gn/T/opencode/subbanner-ulw.kY4Cw5`다. 생성한 test/QA 자원만 종료·정리하며 기존 공유 Gradle 캐시는 삭제하지 않는다.
### `P2-T1` 및 `P2-GATE`, 2026-10-29
- 완료: `SubBanner`·placement·저장소 port·JPA Entity·QueryDSL adapter와 `create-sub-banner.sql`, domain/persistence 테스트를 생성했다.
- RED/GREEN: 두 신규 클래스 26 tests 중 의도한 assertion failure 19개 확인 후 26/26 통과. 기존 배너 baseline 19/19, 직접 영향 배너·creatorname 포함 Gate 50/50 및 전체 `ktlintCheck` 통과.
- 부모 검증: 신규 두 클래스 focused 명령을 다시 실행해 `BUILD SUCCESSFUL in 16s`, XML domain 2 + persistence 24, failures/errors/skipped 모두 0을 확인했다. 전체 변경 소스·테스트·DDL을 읽었고 독립 리뷰도 P2 승인이다.
- 결정: 기간 저장 경계는 repository에서 한 번 초 절삭한 값으로 저장/반환해 DB 반올림을 방지한다. 현재 UTC 시각도 repository query 경계에서 초 절삭한다. 서비스의 UTC 분 입력 정규화와 함께 사용한다.
- 한계: 로컬 MySQL 실행 파일과 실행 중 Docker daemon이 없어 운영 MySQL 적용을 검증하지 않았다. H2 MySQL mode와 DDL/Entity 대조로 확인했으며 운영 DB에는 적용하지 않았다. 전체 suite/HTTP는 후속 Gate에서 수행한다.
- 별도 DDL 직접 검증: task-owned Java/Hibernate driver가 작성한 SQL을 독립 H2에 적용한 뒤 실제 repository CRUD·초 정밀도·기간·placement·잘못된 주소 조합을 검증했다. `MANUAL QA PASS`, `BUILD SUCCESSFUL in 6s`. 초기 driver naming 설정 및 Java fluent setter 오류를 driver에서만 수정했으며 제품 코드는 변경하지 않았다.
### `P3-T1` 및 `P3-GATE`, 2026-10-29
- 완료: 관리자 CRUD·service·request/admin response DTO·실제 random-port JWT HTTP 테스트를 구현했다. 이미지 스트림은 use로 닫고 검증 전에 업로드/저장하지 않는다. 기본 4필드 필수 교체와 날짜 필드의 생략 유지/null 해제를 구분했다.
- 증거: baseline 기존 HTTP/service 5/5; 신규 scaffold RED 39 assertion failures → GREEN 39/39. 기존 배너/creatorname 포함 직접 영향 회귀 161/161, full ktlint 통과. 별도 service unit test 대신 실제 HTTP→service→JPA 경로의 비중복 검증을 유지했다.
- 리뷰 수정: `1988-05-08 02:30`의 Asia/Seoul DST gap 자동 보정을 JDK17과 실제 HTTP로 재현했다. gap 회귀 2 failures → 유효 offset 부재를 거부하도록 수정 → 43/43 및 ktlint 통과. 독립 scoped 재검토는 ADDRESSED/APPROVE다.
- 실제 응답: DELETE HTTP200 `{"success":true,"message":null,"data":null,"errorProperty":null}`. JSON/URI/기간 검증 400과 없는 id 404는 Spring Boot 오류 body. 익명 401, 모든 비관리자와 필수 multipart part 누락은 기존 정책의 HTTP200 `success:false`다.
- 저장 한계: MySQL TIMESTAMP가 표현 가능한 UTC `1970-01-01 00:00:01`~`2038-01-19 03:14:07` 밖 입력은 업로드 전에 400으로 거부한다. 이는 임의의 과거 날짜 제한이 아니다. S3 업로드 후 DB 실패 시 새 object 잔존 가능성은 보존하며 자동 정리를 추가하지 않았다.
- 부모 확인: 실제 소스·테스트를 읽고 최종 XML 43 tests/failures0/errors0/skipped0을 확인했다. P4 후 부모가 전체 HTTP·회귀·빌드를 다시 실행한다.
### `P4-T1` 및 `P4-GATE` 최종 실행, 2026-10-29
- 완료: 공개 controller/6필드 DTO, UTC nowProvider를 한 번 읽는 read-only 서비스 조회, 정확한 `GET /api/v2/sub-banners` 허용 matcher 한 줄과 실제 HTTP 테스트를 구현했다. 기존 추천 API 응답·테이블·공통 예외 정책·dependency는 변경하지 않았다.
- RED/GREEN: 공개 HTTP 23개 중 22개 assertion failures(기대 200/400, 실제 401) → 23/23 통과. JSON fixture의 LongNode/IntNode 차이는 기대 map의 serialize/readTree로 해소하고 전체 JSON tree 비교는 유지했다. 공개·관리자 보안 테스트는 동일 실제 HTTP context로 통합했다.
- 관련 회귀: 신규 92개(domain 2, persistence 24, 관리자 HTTP 43, 공개 HTTP 23) + 기존 홈/오디오 추천 4개 = 96/96, ktlint 통과.
- 부모 최종 명령: `./gradlew test ktlintCheck bootJar --continue --console=plain` → exit 0, `BUILD SUCCESSFUL in 12m 27s`. `build/reports/tests/test/index.html`의 총 2,676 tests, failures 0, ignored 0, 성공률 100%를 확인했다. `build/libs/sodalive-0.0.1-SNAPSHOT.jar` 생성 확인. 현재 코드로 전체 실제 HTTP 테스트도 재실행됐다.
- 실제 HTTP 증거: 관리자 POST/PUT 200의 관리자 8필드, DELETE 200 `{"success":true,"message":null,"data":null,"errorProperty":null}`. 익명 공개 GET은 200의 6필드 배열/빈 배열, 누락·잘못된 placement는 400. 익명 POST/PUT/DELETE/HEAD/PATCH와 인접 GET은 401이며 비관리자 admin은 기존 200 `success:false`다. 원본 응답은 `build/test-results/test/TEST-kr.co.vividnext.sodalive.v2.subbanner.adapter.in.web.*.xml`의 `HTTP EVIDENCE`에 기록돼 있다. Authorization/JWT는 출력하지 않았다.
- 기간 증거: 고정 now의 시작 `:00`, 종료 `:59.999999999` 포함, 다음 초/다음 날 제외, 한쪽·양쪽 null, 두 placement 격리, 25개 무절단 id 순서, iOS 요청에도 Android-only 행을 반환하는 서버 OS 비필터를 실제 DB·HTTP로 확인했다.
- 독립 최종 리뷰: production 11개·대응 테스트 4개·DDL·SecurityConfig diff·호출 경계를 검토한 결과 `APPROVE`, Must fix/Should fix 없음. 기존 P3 DST gap blocker의 RED→GREEN 및 재검토 승인도 확인했다. 부모가 리뷰와 별도로 전체 실행 결과를 확인했다.
- 문서: API 계약과 앱/관리자 프롬프트를 실제 경로·shape·오류·날짜 허용 범위·이미지 정책으로 갱신했다. 문서 동기화 중 잘못 적힌 경로 ID 형식의 400 보장은 제거했으며 프레임워크 바인딩 오류까지 같은 상태라고 가정하지 않는다.
- 남은 한계: 운영 DB DDL 적용·배포·실제 AWS 업로드·native MySQL 실행·앱/관리자 UI는 수행하지 않았다. DDL은 독립 H2에 실제 적용해 검증했다. host에 LSP 도구가 없어 Kotlin 컴파일/ktlint로 대체했으며 LSP clean으로 주장하지 않는다. S3 업로드 후 DB 실패 시 orphan 및 교체/삭제 후 기존 object 보존 가능성은 승인된 범위대로 남긴다.
- 종료 확인: 변경 파일의 `git diff --check` 및 신규 파일 공백 검사 통과, PRD/plan 미완료 체크박스 없음. `pgrep`에서 Gradle Test Executor·embedded Redis·일회성 QA driver 잔존 없음. 검증 요약을 본 문서에 보존한 뒤 이번 소유 run root·child roots·QA driver·note·cache를 제거하고 경로 부재를 확인했다. 기존 공유 캐시·worktree·소스·빌드 결과/테스트 보고서는 보존했으며 커밋·푸시는 하지 않았다.
## Phase 5: is_active 소프트 삭제
앞선 하드 삭제 구현·검증은 당시 완료 이력이다. 이번 사용자 결정은 이를 대체하는 후속 변경이며 기존 완료 체크박스를 되돌리지 않는다.
### Task 5.1 저장·조회·삭제 경계 변경
**Goal `P5-T1`:** DELETE가 행을 보존하며 is_active만 false로 바꾸고, 삭제된 배너가 모든 소비자 조회와 수정 경로에서 제외된다.
- 시작 조건: `DEC-010` 사용자 승인 및 기존 P2~P4 완료.
- Files: `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/adapter/out/persistence/SubBannerEntity.kt`, `DefaultSubBannerRepository.kt`; `src/test/kotlin/kr/co/vividnext/sodalive/v2/subbanner/adapter/out/persistence/SubBannerPersistenceTest.kt`, `adapter/in/web/AdminSubBannerControllerIntegrationTest.kt`, `adapter/in/web/SubBannerControllerIntegrationTest.kt`; `docs/20261029_가로형서브배너/create-sub-banner.sql` 및 기존 PRD/API/프롬프트/계획.
- 완료 증거: DB 행과 기존 필드 보존, false 갱신, findById/관리자 목록/공개 목록 제외, 수정·재삭제 404, 기본 true와 DTO 불변을 실제 persistence/HTTP 테스트로 확인한다.
- 동시 경계: 수정 요청이 활성 entity를 로드한 뒤 다른 트랜잭션의 DELETE가 커밋하더라도, 먼저 시작한 수정이 삭제 상태를 true로 되돌리지 않아야 한다. 두 독립 EntityManager의 겹치는 트랜잭션과 새 조회 context로 재현·검증한다.
- 범위 밖: 활성 토글·복원 API·isActive 요청/응답 필드·S3 삭제·기존 완료 이력 삭제·운영 DDL 적용. 아직 미배포인 신규 CREATE DDL을 보완하며 추측한 레거시 migration은 추가하지 않는다.
- [x] **RED:** 행 보존/비활성/목록 제외·기간·placement·수정/재삭제 경계를 먼저 테스트했다. 추가 리뷰에서 발견한 stale managed entity도 두 트랜잭션으로 재현했다.
- [x] **RED 확인:** 기존 하드 삭제/컬럼 부재 assertion 8개 실패, 이후 동시 상태 덮어쓰기 회귀 1개 실패를 각각 확인했다.
- [x] **GREEN:** entity/DDL 기본 true, DELETE false 갱신, 모든 소비자 조회의 활성 필터와 entity-local DynamicUpdate를 구현했다.
- [x] **GREEN 확인:** focused 99/99 및 실제 HTTP에서 행·필드·S3 보존/미노출/404·기존 DTO/권한/기간 규칙과 동시 수정의 비복원을 확인했다.
- [x] **REFACTOR:** 직접 영향만 정리하고 ktlint·DDL 실제 H2 실행·독립 scoped 재검토를 통과했다. 전체 Gate는 별도 진행한다.
### Phase 5 Gate `P5-GATE`
- 시작 조건: `P5-T1` 완료.
- 완료 증거: 실제 HTTP 시나리오·전체 테스트·ktlint·bootJar·독립 리뷰·자원 정리 기록.
- [x] P6를 포함한 최종 전체 테스트 2,682개·lint·bootJar 및 독립 리뷰 통과. DDL의 is_active 기본 true와 entity 일치, 행 보존·조회 제외·동시 비복원을 검증했다. 자원 정리 영수증은 아래 최종 기록을 따른다.
- 도구 한계: LSP 및 native MySQL 실행 환경은 미제공이다. 컴파일/ktlint와 H2 검증으로 대체하되 운영 적용 검증으로 표현하지 않는다.
### `P5-T1` 1차 검증 및 리뷰, 2026-10-29
- baseline: 기존 서브 배너 focused 92/92 통과. 회귀 테스트를 먼저 변경해 기존 하드 삭제와 컬럼 부재로 인한 assertion 8개 실패를 확인했다.
- 1차 GREEN: entity 기본 true/nonnull, DELETE false 갱신, id/관리자/공개 활성 필터와 authored CREATE의 default true를 구현했다. focused 98/98 및 ktlint 통과. 실제 HTTP에서 DELETE 200/null, DB 행·payload·이미지·생성 시각 보존, 비활성 PUT/재DELETE404와 upload0을 확인했다.
- 독립 리뷰: 순차 삭제 경계는 통과했으나, 삭제 전 true entity를 보관한 수정 트랜잭션의 Hibernate 전체 컬럼 UPDATE가 뒤늦게 is_active=true를 덮을 수 있다는 P1 blocker를 확인했다. 기존 flush/clear 후 stale-domain 테스트와 다른 경계이므로 두 트랜잭션 회귀 RED→GREEN을 추가한다. 전체 완료 판정은 수정·재검토 후 수행한다.
### `P5-T1` 동시 경계 수정 및 Gate 진행, 2026-10-29
- 수정: `@DynamicUpdate`를 SubBannerEntity에만 추가해 payload 수정이 변경하지 않은 is_active를 SQL에 포함하지 않도록 했다. 새 잠금·버전 컬럼·외부 API는 추가하지 않았다.
- 재현: T1이 활성 managed entity를 유지한 상태에서 T2 DELETE 커밋 후 T1 payload UPDATE를 커밋했다. 제3 context에서 false를 기대했으나 true가 된 assertion RED 1건을 확인했다. 수정 뒤 persistence29/29와 focused99/99·ktlint가 통과했고 원래 stale-domain 회귀도 유지했다. 독립 재검토는 ADDRESSED/APPROVE다.
- 실제 SQL: 삭제는 `set updated_at=?, is_active=? where id=?`, 일반 payload 변경은 `set updated_at=?, web_url=? where id=?`로 관찰돼 삭제 상태가 덮이지 않았다. 테스트의 독립 EntityManager 3개와 커밋된 fixture는 finally로 정리했다.
- 전체 검증 1차: 부모의 `./gradlew test ktlintCheck bootJar --continue --console=plain`은 `bootJar` 뒤 `:test` 수행 중 실행 도구의 1,200,000ms 제한으로 종료됐다. 테스트 실패나 전체 성공을 판정할 출력은 없었다. 기존 99개 focused HTML을 전체 성공 증거로 재사용하지 않았다.
- 조사·재시도: 종료 후 Gradle Test Executor/embedded Redis 잔존 없음을 확인했다. 코드·테스트·빌드 설정은 바꾸지 않고, 테스트별 진행만 기록하는 임시 init script를 사용해 동일 전체 명령을 2,400,000ms 제한으로 한 번 재실행 중이다. 이 기록은 최종 통과 주장이 아니다.
## Phase 6: 두 추천 API에 서브 배너 통합
### Task 6.1 비로그인 추천 응답 합성 및 기존 앱 GET 제거
**Goal `P6-T1`:** 홈·콘텐츠 추천 GET에서 한 요청으로 기존 추천 데이터와 `subBanners`를 받고, 별도 서브 배너 조회 endpoint는 제공하지 않는다.
- 시작 조건: 사용자 `DEC-011` 승인, P5 focused 99개 및 독립 재리뷰 승인. P5 전체 Gate는 이번 통합 이후 최종 코드로 함께 판정한다.
- Files: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacade.kt`, `dto/recommendation/HomeRecommendationResponse.kt`; `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/content/recommendation/application/AudioRecommendationFacade.kt`, `dto/AudioRecommendationsResponse.kt`; 기존 `v2/subbanner/adapter/in/web/SubBannerController.kt` 삭제 및 `configs/SecurityConfig.kt`의 해당 단일 permitAll 제거. 두 facade/DTO 직접 생성 테스트 호출자와 기존 실제 HTTP subbanner 테스트를 추천 통합 시나리오로 갱신한다.
- 인터페이스: 두 facade는 기존 `SubBannerService.findVisibleByPlacement` 및 `SubBannerResponse.from`을 재사용한다. HOME/CONTENT placement는 해당 facade가 고정하며 클라이언트 placement query나 OS 조건을 추가하지 않는다. `data.subBanners: List<SubBannerResponse>`는 항상 존재하며 없으면 `[]`다.
- 범위 밖: 관리자 API/DDL·소프트 삭제 변경, 기존 banners 교체, 새 fallback/cache/endpoint, 앱 UI 코드, 운영 배포. 기존 추천의 익명 GET 허용은 유지한다.
- [x] **RED:** 두 추천 GET의 실제 익명 HTTP에서 subBanners·활성/기간·배열·legacy 보존·폐기 handler 부재를 검사했다.
- [x] **RED 확인:** 29개 중 26 assertion failures를 확인했다. 통합 필드 부재와 폐기 대상 경로가 여전히 200인 것을 재현했다.
- [x] **GREEN:** 두 facade/DTO에 필수 배열을 합성하고 모든 직접 생성 호출자를 수정했다. standalone controller와 해당 permitAll 한 줄을 제거했다.
- [x] **GREEN 확인:** 같은 RED 명령 29/29 및 subbanner/home/audio 전체 관련 회귀 161/161 통과. 두 실제 추천 GET에 기존 소프트 삭제/기간/권한/무절단 시나리오를 이식했다.
- [x] **REFACTOR:** API 계약·앱 프롬프트를 `data.subBanners`로 갱신했다. 기존 기능·보안 및 JSON assertion을 완화하지 않았고 ktlint와 독립 P6 리뷰를 통과했다.
### 통합 최종 Gate `P6-GATE`
- 시작 조건: P6-T1 및 P5 focused/리뷰 완료.
- [x] 소프트 삭제·두 추천 통합 focused/전체 테스트·ktlint·bootJar·독립 리뷰를 통과하고 실제 HTTP 증거를 기록했다.
- [x] 앱 프롬프트/API 문서·소프트 삭제 DDL·행 보존·비로그인 조회·폐기 endpoint 부재를 확인했다. 소유 QA 자원 정리는 최종 종료 기록에 남긴다.
### 전체 검증 범위 변경, 2026-10-29
- 사용자 추가 요청으로 변경 전 코드를 대상으로 실행 중이던 전체 검증 runner를 개별 취소했다. 소프트 삭제 구현은 유지하며 P6 통합 코드로 최종 검증을 새로 수행한다. 이는 전체 테스트 통과/실패 판정이 아니다.
- 취소 당시 Gradle wrapper/test-worker PID를 확인한 뒤 후속 ps/lsof에서 해당 프로세스 부재를 확인했다. 공유 daemon·다른 작업 프로세스는 종료하지 않았다.
### `P6-T1` 구현·focused·독립 리뷰, 2026-10-29
- 구현: HomeRecommendationFacade는 HOME_RECOMMENDATION, AudioRecommendationFacade는 CONTENT_RECOMMENDATION을 고정해 기존 SubBannerService/6필드 DTO를 재사용한다. 기존 추천 DTO의 필수 `subBanners` 배열을 추가했고 모든 기존 필드/기존 banners 매핑을 그대로 유지했다. standalone 앱 controller와 정확한 GET 허용 matcher를 제거했다. 관리자 CRUD·DDL·소프트 삭제 저장소·DynamicUpdate는 변경하지 않았다.
- TDD: 컴파일 후 RED 29개 중 26개 assertion failures → GREEN 29/29. 기존 소켓 테스트를 `RecommendationSubBannerIntegrationTest`로 이식했으며, 폐기된 placement query 검증은 두 화면의 고정 placement 및 handler 부재 검증으로 대체했다. 삭제된 테스트를 통과를 위한 우회로 사용하지 않았다.
- focused: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.subbanner.*' --tests 'kr.co.vividnext.sodalive.v2.api.home.*' --tests 'kr.co.vividnext.sodalive.v2.api.content.recommendation.*' ktlintCheck --console=plain` → 161/161, failures/errors/skipped 0, `BUILD SUCCESSFUL in 2m 25s`.
- 실제 HTTP: 두 GET은 Authorization 없이 200이며 `data.subBanners:[]` 또는 정확한 6필드 목록을 반환했다. HOME의 기존 9개+신규 배열=10필드, AUDIO의 기존 8개+신규 배열=9필드 전체와 비어 있지 않은 legacy banners를 정확히 비교했다. 각 placement 25개 전체·기간 소수초/자정·삭제 행 9개 중 비활성 4개 보존·OS 비필터를 확인했다. 폐기된 경로는 인증 GET 404/익명 401이며 handler mapping에도 없다.
- 독립 P6 리뷰: APPROVE, 차단 사항 없음. 직접 생성 테스트 호출자 6파일과 실제 HTTP 이식 전체를 확인했고 이전 P5 동시 삭제 비복원 회귀도 유지됨을 확인했다.
- 부모 확인: facade/DTO 변경, 기존 테스트 diff 및 새 실제 HTTP 테스트 전체와 앱/API 문서를 읽었다. 통합 이후에는 별도 배너 fetch가 없으므로 앱 프롬프트의 오류 처리를 추천 API 오류와 개별 이미지/링크 오류로 구분했다.
- 배포 조건: 추천 API도 신규 테이블/컬럼을 조회하므로 현재 DDL 준비가 서버 배포보다 선행해야 한다. 운영 DB 적용·배포는 수행하지 않는다.
- 최종 실행: 안정된 P5+P6 코드로 테스트별 진행 로그만 추가한 임시 init script와 함께 전체 `test ktlintCheck bootJar --continue`를 실행 중이다. 이전 취소/timeout 결과나 focused 통과를 전체 통과로 대체하지 않는다.
### `P5-GATE`·`P6-GATE` 최종 전체 검증, 2026-10-29
- 결과: 안정된 최종 코드에서 `./gradlew test ktlintCheck bootJar --continue --console=plain`과 동작을 바꾸지 않는 임시 테스트 진행 로그 init script를 사용해 1회 실행했다. exit 0, `BUILD SUCCESSFUL in 15m 46s`. 전체 2,682 tests, failures/errors/skipped/ignored 모두 0이다. 부모가 fresh HTML 및 `QA_SUITE_RESULT tests=2682 failed=0 skipped=0` 원본 로그를 직접 확인했다.
- 빌드/정적 검사: `bootJar`가 이번 실행에서 생성됐고 `build/libs/sodalive-0.0.1-SNAPSHOT.jar`를 확인했다. `ktlintCheck`는 변경 없는 소스의 선행 성공 결과를 사용한 UP-TO-DATE 상태이며 전체 명령은 성공했다. Kotlin 컴파일과 선행 focused lint도 통과했다. LSP 도구 미제공을 LSP 성공으로 표현하지 않는다.
- 실제 HTTP: 최종 suite에도 `RecommendationSubBannerIntegrationTest` 24개가 실행됐다. 두 추천 GET의 Authorization 없는 200과 `data.subBanners`, 정확한 기존 root 필드/legacy banners 보존, 활성·기간·placement·25개 무절단, 폐기 경로의 handler 부재/인증 404·익명 401, admin 보호 및 삭제 행 보존을 확인했다. 이전 standalone 테스트 클래스는 source/build/report에서 사라졌고 새 클래스의 XML/HTML은 이번 실행에서 갱신됐다.
- 소프트 삭제: 실제 DELETE는 200/data:null을 유지하며 row/is_active=false/기존 payload 보존, 삭제 후 수정·재삭제404, 관리자·추천 조회 제외를 확인했다. 두 EntityManager의 겹치는 트랜잭션에서도 삭제 상태가 true로 돌아가지 않는 회귀를 유지했다. 앱·관리자에 isActive 필드나 복구 API를 추가하지 않았다.
- 리뷰: P5의 유일한 동시성 blocker는 재현 RED→DynamicUpdate GREEN 후 ADDRESSED/APPROVE. P6 독립 리뷰는 추가 차단 없이 APPROVE다. 각각의 검토와 별개로 부모가 전체 실행 결과·변경 파일·문서를 확인했다.
- 증거 위치: `build/reports/tests/test/index.html`, `build/test-results/test/TEST-*.xml`. 실제 응답은 RecommendationSubBannerIntegrationTest/AdminSubBannerControllerIntegrationTest XML의 HTTP EVIDENCE/DB EVIDENCE, 동시 경계는 SubBannerPersistenceTest XML의 CONCURRENCY EVIDENCE에 남는다. 테스트 토큰은 출력하지 않았다.
- 이전 중단 구분: P5 첫 전체 실행은 20분 도구 제한, 두 번째 진행 로그 실행은 사용자 P6 범위 변경 때문에 취소했다. 둘 다 통과 증거로 사용하지 않았으며 최종 P5+P6 전체 실행만 이번 완료 판정에 사용했다.
- 운영 한계: DDL 파일만 생성·보완했으며 native MySQL·운영 DB·실제 AWS·앱/관리자 UI·배포는 수행하지 않았다. 서버 배포 전에 현재 sub_banner/is_active DDL 준비가 필요하다. 기존 테이블을 이미 별도로 생성한 환경은 배포 담당자가 스키마 차이를 확인해야 하며 자동 migration/운영 변경은 하지 않는다.
- 종료 영수증: tracked/new 파일 공백 검사 통과, PRD/plan 미완료 체크박스 없음, production source에 폐기 `/api/v2/sub-banners` 경로 없음. 테스트 wrapper/worker·embedded Redis 잔존 없음을 확인한 뒤 이번 소유 `subbanner-soft-delete.wmREV2` root와 child root·note·진행 로그 스크립트·cache를 제거하고 경로 부재를 확인했다. 공유 Gradle daemon/cache·기존 worktree·소스·JAR·build 테스트 보고서는 보존했다. 커밋·푸시는 하지 않았다.
### 커밋 전 영향 범위 재검증, 2026-10-29
- 무엇을·왜: 커밋할 최종 변경의 서브 배너·홈·콘텐츠 추천 경계를 재검증했다. 제품 코드와 테스트는 수정하지 않았다.
- 명령: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.subbanner.*' --tests 'kr.co.vividnext.sodalive.v2.api.home.*' --tests 'kr.co.vividnext.sodalive.v2.api.content.recommendation.*' ktlintCheck bootJar --console=plain`.
- 결과: 종료 코드 0, `BUILD SUCCESSFUL in 5m 5s`. 최신 HTML/XML에서 161 tests, failures/errors/skipped 0을 확인했다. 테스트는 재실행됐으며 lint·컴파일·bootJar는 입력 변경이 없어 UP-TO-DATE였다.
- 전체 회귀 생략: 이전 최종 Gate의 전체 2,682개 통과 이후 제품 코드 변경이 없어 전체 suite를 반복하지 않았다. 이번 영향 범위 실행으로 `build/reports/tests/test/index.html`과 XML은 161개 결과로 갱신됐으며, 과거 전체 결과와 구분한다.
- 운영 한계: 운영 DB·native MySQL·실제 AWS·앱/관리자 UI·배포는 이번에도 검증하지 않았다. 서버 배포 전에 현재 DDL 준비가 필요하다.
## Phase 7: 서브 배너 언어 후속
2026-11-02 사용자 승인으로 새 Phase를 추가한다. Phase 2~6의 완료 상태와 검증 기록은 당시 계약의 이력이며 수정하지 않는다.
### Task 7.1 저장·관리자 계약·공개 국가별 조회
**Goal `P7-T1`:** 서브 배너가 기존 `Lang`을 저장하고 관리자가 안전하게 언어를 관리하며, 두 공개 추천 API가 회원 국가에 맞는 언어만 반환한다.
- 요구사항: PRD `SB-013`, `DEC-012`.
- 시작 조건: `DEC-012` 승인과 기존 Phase 2~6 완료.
- 완료 증거: baseline 기록, language 저장/기본값/수정 보존 persistence 및 실제 관리자/public HTTP 테스트의 RED→GREEN 결과, DDL 두 경로 검토, 독립 코드 리뷰.
- 범위 밖: 앱·관리자 UI, public `SubBannerResponse` 변경, event link parsing, event detail/adult 정책, dependency, 운영 DB/DDL 실행, 기존 언어 자동 추론.
- **Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/domain/SubBanner.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/adapter/out/persistence/SubBannerEntity.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/adapter/out/persistence/DefaultSubBannerRepository.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/port/out/SubBannerRepository.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/dto/SubBannerRequest.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/dto/AdminSubBannerResponse.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/application/SubBannerService.kt`
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacade.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/content/recommendation/application/AudioRecommendationFacade.kt`
- Modify: `docs/20261029_가로형서브배너/create-sub-banner.sql`
- Create: `docs/20261029_가로형서브배너/20261102_add_sub_banner_lang.sql`
- Modify: `docs/20261029_가로형서브배너/api-contract.md`, `docs/20261029_가로형서브배너/admin-prompt.md`, `docs/20261029_가로형서브배너/app-prompt.md` (실제 언어 계약과 배포 주의사항 동기화; UI 구현 제외)
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/subbanner/domain/SubBannerTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/v2/subbanner/adapter/out/persistence/SubBannerPersistenceTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/v2/subbanner/adapter/in/web/AdminSubBannerControllerIntegrationTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/v2/subbanner/adapter/in/web/RecommendationSubBannerIntegrationTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacadeTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/content/recommendation/application/AudioRecommendationFacadeTest.kt`
- **Interfaces:** `SubBanner.lang: Lang = Lang.KO`; admin request optional `lang` preserving JSON presence/type distinctions; `AdminSubBannerResponse.lang: Lang`; repository `findVisibleByPlacement(placement: SubBannerPlacement, lang: Lang, now: LocalDateTime): List<SubBanner>`. Public service accepts `Member?`, resolves through existing `MemberContentPreferenceService.resolveCountryCode(member)`, then passes required `Lang`. Both existing facades pass their `member`. Admin list receives no language filter. `SubBannerResponse` remains unchanged.
- [x] **Baseline:** 부모의 사전 통과 113개 중 서브 배너 기존 4개 클래스 98개를 확인했다. 원본 `/tmp/soda-banner-ulw.HDkpg4/baseline.log`. 두 facade 클래스는 사전 baseline 범위 밖이며 이번 GREEN에서 10개를 검증했다. 운영 DDL은 실행하지 않았다.
- [x] **RED:** domain KO 기본값, 관리자 9필드·생성 언어·invalid 입력 400 및 공개 두 JP 경로의 KO 제외를 실제 HTTP/응답 assertion으로 먼저 추가했다. invalid 입력은 실제 DB 상태·업로드·repository save 호출 0회를 검증한다.
- [x] **RED 확인:** domain/admin/public 81개 중 언어 관련 assertion 15개 실패, 오류 0을 확인했다. 컴파일·설정 RED가 아니다. `/tmp/soda-banner-impl.CfAkhD/subbanner-red.log`와 `subbanner-*-red.xml`.
- [x] **GREEN:** 기존 `Lang`, 생성 KO·수정 생략 보존, 부작용 전 검증, facade의 member 전달, repository 필수 언어 조건 및 두 SQL artifact를 구현했다. typed persistence 언어 왕복·필터·변경과 기존 호출부도 함께 갱신했다.
- [x] **GREEN 확인:** focused 123개 실패·오류·무시 0. 실제 관리자 KO/JA/EN·수정 생략 보존·invalid 입력, 두 추천 JP/KR/US/누락·강제 회원, 공개 정확히 6필드 및 기존 기간·소프트 삭제·정렬·링크 회귀가 통과했다.
- [x] **REFACTOR:** 전체 2,928개 테스트, 공백 수정 후 영향 26개 HTTP 테스트·전체 ktlint·bootJar 및 독립 리뷰를 확인했다. 운영 DDL과 도구가 없는 LSP 진단은 실행하지 않았다.
```bash
export TMPDIR=/tmp/soda-banner-impl.CfAkhD NODE_COMPILE_CACHE=/tmp/soda-banner-impl.CfAkhD/node-compile-cache BUN_RUNTIME_TRANSPILER_CACHE_PATH=/tmp/soda-banner-impl.CfAkhD/bun-transpiler
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.subbanner.domain.SubBannerTest' --tests 'kr.co.vividnext.sodalive.v2.subbanner.adapter.out.persistence.SubBannerPersistenceTest' --tests 'kr.co.vividnext.sodalive.v2.subbanner.adapter.in.web.AdminSubBannerControllerIntegrationTest' --tests 'kr.co.vividnext.sodalive.v2.subbanner.adapter.in.web.RecommendationSubBannerIntegrationTest' --tests 'kr.co.vividnext.sodalive.v2.api.home.application.HomeRecommendationFacadeTest' --tests 'kr.co.vividnext.sodalive.v2.api.content.recommendation.application.AudioRecommendationFacadeTest' --console=plain --no-daemon -Pkotlin.compiler.execution.strategy=in-process
./gradlew test ktlintCheck bootJar --continue --console=plain
```
**DDL requirements:** both SQL artifacts define `lang VARCHAR(10) NOT NULL DEFAULT 'KO'` with a column comment. DEC-013 supersedes the original guarded migration with one static ALTER TABLE for an existing table without lang. Existing rows receive KO; do not rerun when lang exists. Before production application, operations must manually identify JA banners and verify language consistency against linked events. No event link parser or automatic classification is allowed. Production DB/DDL execution is not part of this goal.
### Phase 7 Gate `P7-GATE`
- 시작 조건: `P7-T1` 완료.
- 완료 증거: full test suite·ktlint·bootJar 성공, 실제 관리자와 두 추천 HTTP 경로 검증, 두 SQL artifact/수동 분류 경고 대조, 독립 리뷰에서 미해결 차단 사항 없음.
- 범위 밖: 운영 DB 적용·배포·UI.
- [x] 국가 resolver 재사용·관리자 전체 언어·public DTO 불변·invalid 부작용 0을 확인하고 이전 Phase 이력을 보존했다. 전체 검증 및 최종 Oracle 승인으로 Gate를 완료했다.
### Phase 7 구현 Progress, 2026-11-02
- RED는 위 명령 중 domain/admin/public 3개 클래스를 실행해 `81 tests completed, 15 failed`를 확인했다. 실패는 KO 기본값/관리자 lang 필드 누락, invalid lang의 200 수락, JP에서 KO 노출이다. 원본 XML은 `/tmp/soda-banner-impl.CfAkhD/subbanner-domain-red.xml`, `subbanner-admin-red.xml`, `subbanner-public-red.xml`이다. 개별 typed persistence 테스트를 별도 RED 실행한 것으로 주장하지 않는다.
- GREEN은 위 6개 클래스 명령이며 `/tmp/soda-banner-impl.CfAkhD/subbanner-green.log`에 `BUILD SUCCESSFUL in 8m 28s`가 남는다. Domain 3, Persistence 32, Admin HTTP 52, Public HTTP 26, Home facade 8, Audio facade 2로 총 123개가 통과했다.
- 실제 HTTP/DB 증거는 `subbanner-http-db-evidence.log`의 HTTP 121건과 `subbanner-green-TEST-*.xml`에 보관했다. 신규 언어 경로는 두 추천 각각 익명 JP/KR/US/누락·강제 JP/KR를 실제 JWT/회원/resolver로 검증한다. EN 행이 있어도 공개 목록에서 제외되고, admin은 KO/JA/EN을 모두 반환한다. invalid 8종 POST/PUT 16건은 400이며 실제 DB 불변·S3 상호작용 없음·repository save 0회가 통과했다.
- H2 flush/clear/재조회에서 모든 언어의 문자열 저장·변경·언어 조건 및 `VARCHAR(10) NOT NULL`을 확인했다. 기존 CREATE SQL 실행 테스트도 H2에서 KO default/NOT NULL/길이 10을 검증했다. migration은 기존 event DDL의 information_schema/PREPARE 패턴과 대조만 했고 native MySQL·운영 DDL은 실행하지 않았다. 기존 초 정밀도·소프트 삭제/동시성·링크 검증은 유지했다.
- API 계약/관리자·앱 프롬프트에 생성 생략 KO·수정 생략 유지·null/type/blank/unknown 400, JP→JA/그 외→KO, admin 전체 언어, EN 비노출, 공개 6필드 및 migration-before-deploy를 반영했다. KO backfill은 자동 분류가 아니므로 JA 소재와 연결 이벤트 언어를 수동 확인해야 한다. 외부 링크 원문은 유지하며 파서를 추가하지 않았다.
- 사용자 지정 종료 경계에 따라 전체 suite·ktlint·bootJar·독립 리뷰와 `P7-GATE`는 부모가 수행하도록 미완료 유지한다. LSP 진단 도구 없음, 실제 AWS/UI/운영 DB/배포 미검증. Gradle 및 embedded Redis 소유 프로세스가 종료됐음을 확인했고 evidence는 남겼다. 모든 변경 파일·명령·제한은 `/tmp/soda-banner-impl.CfAkhD/implementation-report.md`에 기록한다. 기존 Phase 2~6 기록과 부모 PRD 변경은 보존했다.
- 최종 source 상태에서 위 6개 클래스와 Phase 3의 5개 클래스를 한 focused 명령으로 재실행했다. `/tmp/soda-banner-impl.CfAkhD/final-focused.log`: `BUILD SUCCESSFUL in 8m 8s`, 총 145개 실패·오류·무시 0. 전체 suite는 실행하지 않았다. 최종 11개 XML은 `final-TEST-*.xml`, 실제 HTTP 185건과 DB/동시성 증거는 `final-http-db-evidence.log`에 별도 보관했다.
### Phase 7 최종 검증 Progress, 2026-11-03
- 부모가 `./gradlew test ktlintCheck bootJar --continue --console=plain --no-daemon -Pkotlin.compiler.execution.strategy=in-process`를 실행했다. 전체 XML을 집계해 336 suites / 2,928 tests / failures=0 / errors=0 / skipped=0을 확인했고 JAR도 생성됐다. 최초 명령은 `RecommendationSubBannerIntegrationTest.kt`의 생성자 인자 줄바꿈 1곳(5개 lint 진단) 때문에 exit 1, 15m 50s였다.
- 값·순서·동작 변경 없이 인자만 줄별로 배치했다. `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.subbanner.adapter.in.web.RecommendationSubBannerIntegrationTest' ktlintCheck bootJar --continue --console=plain --no-daemon -Pkotlin.compiler.execution.strategy=in-process`: exit 0, `BUILD SUCCESSFUL in 4m 32s`, 26 tests / failures=0 / errors=0 / skipped=0, 전체 lint 통과, bootJar UP-TO-DATE.
- 전체 회귀 뒤 테스트 공백만 달라져 영향 HTTP suite만 재실행했다. 현재 `build/test-results/test`/HTML은 26개 결과이며, 전체 2,928개 수치는 갱신 전 부모의 직접 집계다. 실제 HTTP·DB 검증은 테스트 대체가 아니라 RANDOM_PORT 서버를 대상으로 한 TestRestTemplate 요청과 저장소 재조회다.
- 부모가 production diff, 입력·저장·조회 경로, 테스트 assertion, SQL 두 개와 소비 문서를 직접 대조했다. LSP 도구가 없어 미실행이며 Gradle 컴파일·lint로 대체했다. 운영 DB/native MySQL/AWS/UI/배포는 제외한다.
- 원본 `/tmp/soda-banner-ulw.HDkpg4/full-verification.log`, `final-verification.log` 및 구현자 임시 증거는 작업 종료 시 정리한다. 재현 테스트 소스, 최신 build reports, 본 검증 기록과 [공동 리뷰](reviews/banner-language-review.md)를 남긴다.
- 독립 Oracle 리뷰는 명세·코드·시나리오 APPROVE, 후속 공백 delta 및 최종 검증 Gate도 APPROVE했다. 미해결 발견 사항 없음. `P7-T1/P7-GATE` 완료이며 운영 DDL·배포는 별도다.
- 서브 배너 구현·SQL·테스트 커밋 `c4c61e36`, hook/메시지 검사 통과. 소유 임시 자료·QA 프로세스 정리와 build 산출물 보존은 공동 리뷰의 종료 증거에 기록했다. 운영 DDL·배포·push는 하지 않았다.
## Phase 8: 정적 이관 SQL
### Task 8.1 단일 ALTER TABLE 전환 (`P8-T1`)
- Objective: 저장 프로시저·동적 SQL 없이 기존 lang 미존재 테이블에 KO 기본 언어 컬럼을 추가한다.
- 시작 조건: DEC-013 사용자 요청, 기존 SQL 및 MySQL ALTER 문법 확인.
- Files: `docs/20261029_가로형서브배너/20261102_add_sub_banner_lang.sql`, `prd.md`, `api-contract.md`, `plan-task.md`.
- 범위 밖: 앱 코드·신규 CREATE 변경, 이미 존재하는 컬럼 정정, 자동 재실행, 운영 DB 접속·실행.
- TDD 예외: 애플리케이션 로직 변경 없이 배포 SQL 표현을 단순화한다. H2에서 기존 MySQL PREPARE가 실패하는 것을 기능 RED로 가장하지 않는다.
- 대체 검증: 실제 SQL 파일을 독립 H2 MySQL 모드에 적용하는 임시 JDBC assertion으로 기존 행 보존/KO 초기값, 새 행 기본값, JA/EN 보존, NULL 거부, 재실행 실패 후 값 불변을 확인한다. native MySQL 실행 증거와 구분한다.
- [x] 단일 정적 SQL 및 실행 전제/재실행 제한을 관련 계약에 반영했다.
- [x] 독립 DB 확인, 문서 대조와 `git diff --check`를 수행했다.
### Phase 8 Gate (`P8-GATE`)
- 완료 증거: S1 기존 행/컬럼, S2 신규 기본값·명시 언어·NULL 거부, S3 재실행 실패·값 보존이 통과하고 scoped 리뷰가 승인한다.
- [x] 실제 SQL 검증·독립 리뷰 APPROVE를 기록하고 소유 임시 자원을 정리했다. 애플리케이션 변경이 없어 Gradle 전체 suite는 반복하지 않았다.
### Phase 8 검증 기록 — 2026-11-03
- MySQL 8.0 공식 [ALTER TABLE 문법](https://dev.mysql.com/doc/refman/8.0/en/alter-table.html)의 정적 `ADD COLUMN column_definition [AFTER col_name]`를 확인했다. 직접 fetch는 403으로 실패해 검색 결과의 공식 문법을 확인했다. MySQL에 MariaDB의 `ADD COLUMN IF NOT EXISTS` 문법을 가정하지 않았다.
- 실제 변경한 SQL 파일을 캐시된 H2 2.1.214의 MySQL 모드에서 임시 Java/JDBC driver로 실행했다. 명령: `java --class-path /Users/klaus/.gradle/caches/modules-2/files-2.1/com.h2database/h2/2.1.214/d5c2005c9e3279201e12d4776c948578b16bf8b2/h2-2.1.214.jar /tmp/soda-banner-sql.CIhdCg/VerifyMigration.java docs/20261029_가로형서브배너/20261102_add_sub_banner_lang.sql`. exit 0, 모든 assertion PASS.
- S1: 기존 활성·비활성 두 행의 ID/이미지/활성값 보존, 두 행의 새 lang=KO, VARCHAR(10)/NOT NULL 확인.
- S2: 새 행의 언어 생략 KO, 명시적 JA/EN 저장 유지, 명시적 NULL 거부(SQLState 23502) 확인.
- S3: 같은 SQL 재실행은 duplicate column(SQLState 42S21)으로 실패하고 JA/EN/KO 값이 바뀌지 않음을 확인했다. 이는 재실행 허용이 아니라 한 번만 실행해야 한다는 계약 검증이다.
- Native MySQL·운영 DB에는 실행하지 않았으며, H2 결과를 MySQL 실행 증거로 표현하지 않는다. 앱 소스·CREATE SQL 변경이 없어 Gradle 테스트/빌드/린트는 반복하지 않았다. 임시 driver는 결과 기록 후 정리한다.
- 독립 scoped 리뷰 `ses_e630f286affevZ6Rc77rxuL3Dn`: APPROVE, 문서화된 1회 실행 전제 아래 데이터 손실 회귀·차단 사항 없음. 기존 Phase 7의 동적 SQL 검토 기록은 당시 이력이며 현재 계약은 DEC-013/P8이다.
- Teardown: Java 검증 프로세스 잔존 없음 확인, 소유 `/tmp/soda-banner-sql.CIhdCg`와 `/tmp/soda-sql-review.439u9H`의 내용·실경로를 확인한 뒤 삭제하고 부재를 확인했다. 임시 notepad도 삭제했다. 공유 H2/Gradle 캐시는 보존했다.
## 관리자 언어 증분 프롬프트 (`DOC-LANG-T1`) — 2026-11-03
- Objective: 언어 변경 전 관리자 CRUD가 이미 적용된 프로젝트에서 언어 선택만 추가할 수 있는 독립 프롬프트를 제공한다.
- 기준: 사용자 후속 요청, 기존 `SB-013` 및 관리자 API 계약. 새로운 API/제품 정책을 정의하지 않는다.
- Files: 신규 `docs/20261029_가로형서브배너/admin-language-prompt.md`, 이 계획의 검증 기록.
- 범위 밖: 관리자 전체 재구현, 실제 UI/서버/SQL 변경·운영 연동·배포.
- TDD 예외: 문서 전용. 생성 multipart의 lang, 수정 기존 언어 보존, 유효 enum/오류·노출 정책을 현재 코드/계약과 대조하고 `git diff --check`로 검증한다. Gradle·브라우저 QA는 실제 UI 구현 작업에서 수행한다.
- [x] 신규 증분 프롬프트를 작성하고 현재 계약과 대조했다.
- [x] 문서 내용 대조·공백 검증과 소유 임시 자원 정리를 완료했다. 문서 변경만 단일 커밋으로 기록한다.
### DOC-LANG-T1 검증 기록
- 기존 관리자 CRUD는 사용자 진술을 기준으로 이미 적용된 것으로 두고 전체 재구현 대신 언어 필드 추가만 지시했다. 새로운 framework/UI 디자인이나 backend 계약은 만들지 않았다.
- 새 `admin-language-prompt.md` 전체를 부모가 읽고 기존 `admin-prompt.md`, `api-contract.md`, `AdminSubBannerController`, `SubBannerService`, request/response DTO와 대조했다. S1 생성 KO/JA/EN 및 multipart `request.lang`, S2 수정 저장값 보존·invalid 처리, S3 기존 CRUD/기간/이미지/링크 보존과 EN 비노출 안내를 확인했다.
- GET `data` 배열 항목의 lang 및 POST/PUT `data.lang` 위치를 명확히 했다. 언어 누락 응답을 KO로 추정하거나 미확인 배포 상태를 성공으로 간주하지 않도록 명시했다.
- 문서 전용으로 Gradle·LSP·브라우저·실제 관리자 요청은 실행하지 않았다. 실제 UI 구현자에게 focused test와 실제 화면 QA 증거 제출을 요구했다.
- Teardown: 소유 `/tmp/soda-admin-prompt.McfWCQ`, `/tmp/soda-admin-prompt-worker.jDSFlG`가 비어 있음을 확인하고 제거 후 부재를 확인했다. 임시 notepad도 삭제했다. 실행 서버·브라우저·QA 프로세스를 생성하지 않았다. 기존 관리자 전체 프롬프트와 backend 코드는 변경하지 않았다.
-167
View File
@@ -1,167 +0,0 @@
# 가로형 서브 배너 백엔드 요구사항
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | Phase 7 언어 기능·Phase 8 정적 이관 SQL 검증 및 리뷰 완료, 미배포 |
| 작성일 | 2026-10-29 |
| 최종 수정일 | 2026-11-03 |
| 대상 기능 | 가로형 서브 배너 백엔드 및 영속성 |
| 관련 API 계약 | [api-contract.md](api-contract.md), 구현·실제 HTTP 검증 기준 |
| 구현 계획 | [plan-task.md](plan-task.md) |
## 요구사항 상태와 현재 승인 범위
- 기존 `USER REQUIREMENTS`는 사용자가 확정한 제품 요구이며, 아래 `USER REQUIREMENTS`와 `DEC-001`, `DEC-005`에 보존한다.
- 초기 API·저장 모델 제안은 `DEC-009`의 사용자 구현 승인에 따라 구현했으며 실제 검증한 계약은 `api-contract.md`에 기록한다. 앱 레이아웃·링크 우선순위 등 UI 추천은 백엔드 구현 완료와 구분한다.
- **현재 승인 범위는 문서대로 백엔드 코드와 DDL 파일을 생성하고 검증하는 것이다.** 운영 DB 적용·배포·앱/관리자 UI 구현은 제외한다. 앞선 문서-only 승인 이력은 Decision Log에 보존한다.
- API 및 저장 모델은 이 문서와 API 계약을 기준으로 구현하되 완료·검증·배포 상태는 구분한다. 소비자 프롬프트는 실제 구현 계약과 다른 설명이 남지 않도록 완료 시 상태를 맞춘다.
## USER REQUIREMENTS
- 가로형 서브 배너 기능이 필요하다.
- 관리자는 배너를 생성, 조회, 수정, 삭제할 수 있어야 한다.
- 웹 URL, Android 딥링크, iOS 딥링크는 각각 선택적으로 등록하며 적어도 하나가 있어야 한다. 정확히 하나만 허용하는 XOR 조건은 아니다. 세 값이 모두 없는 조합은 거부하고 나머지 7개 존재 조합은 허용한다.
- 노출 위치는 메인 홈 추천과 메인 콘텐츠 추천이며, 각 위치에 여러 배너를 조회할 수 있어야 한다.
- 앱은 서버가 반환한 배너 중 웹 URL 또는 현재 대상 OS 링크가 있는 항목을 표시한다.
- 관리자는 기존 콘텐츠 배너 예약 기간과 같은 선택적 시작·종료 기간을 설정할 수 있다.
- 삭제는 `is_active`를 이용한 소프트 삭제로 수행한다. 생성 기본값은 true이며 삭제 시 false로 변경해 행과 기존 데이터를 보존한다.
- 앱 조회는 기존 홈 추천·콘텐츠 추천 API의 `data.subBanners` 배열로 제공하며 두 GET 모두 비로그인 접근을 유지한다. 별도 앱 조회 `/api/v2/sub-banners`는 제거한다. 앱 프롬프트도 이 계약으로 갱신한다.
## 초기 제안과 구현 결정
- 한 레코드에 한 placement를 저장하고 같은 소재를 두 곳에 노출하려면 각각 등록한다. `DEC-003`의 초기 제안을 구현에 적용했으며 최초 사용자 발화로 소급하지 않는다.
- 주소는 trim 후 빈 문자열을 null로 정규화하고 URI 원문을 보존한다. `DEC-002`의 입력 처리 제안을 구현했다.
- 독립 테이블, 서버 생성 이미지 key 및 이미지 검증을 유지한다. 초기 DB row 물리 삭제는 `DEC-010`에 따라 `is_active=false` 소프트 삭제로 변경한다. 이미지의 기존 S3 object 자동 삭제는 제공하지 않는다.
## 목표와 비목표
### 목표
- **G1:** 독립 테이블과 백엔드 도메인으로 두 placement의 배너 레코드를 격리하고, 생성·조회·수정·삭제 후 DB 재조회에서도 데이터가 보존된다. (`SB-001`~`SB-003`, `SB-010`)
- **G2:** 관리자 API는 ADMIN만 사용하고 이미지 multipart 포함 CRUD를 제공하며, payload 검증이 업로드와 영속화보다 먼저 이뤄진다. (`SB-004`~`SB-007`, `SB-011`)
- **G3:** 공개 GET은 placement와 유효 기간으로 필터링하고 전체 목록을 id 오름차순으로 반환하며, 날짜 없는 공개 DTO와 공통 응답 envelope를 유지한다. (`SB-008`~`SB-009`)
- **G4:** 배포 DDL은 적용·롤백 영향을 명시하며 기존 콘텐츠 배너 테이블과 데이터를 변경하지 않는다. (`SB-010`)
- **G5 (2026-11-02 승인 후속):** 서브 배너는 기존 `Lang`으로 저장되고 두 추천 API는 회원 접속 국가에 맞는 언어만 반환하며, 관리자는 모든 언어 항목을 조회·관리할 수 있다. (`SB-013`)
### 포함 범위
- Kotlin/Spring 도메인, application service, persistence adapter와 DTO/controller.
- 공개 단일 GET 및 관리자 CRUD endpoint, 보안 matcher, 이미지 업로드 연동.
- 신규 테이블 생성용 SQL artifact와 테스트, 시간 정밀도 및 접근 제어 검증.
### 제외 범위
- 앱 및 관리자 실제 UI 구현, 기존 대형 콘텐츠 배너 변경, 예약 스케줄러/job, 순서 편집, 별도 활성 토글·삭제 복구 UI/API, 분석.
- 새 라이브러리, 공통 예외 처리기 전면 변경, 배포 실행, 운영 DB 직접 변경.
- 기존 콘텐츠 배너 테이블 migration. 새 서브 배너 전용 테이블만 제안한다.
- idempotency key, pagination, 자동 재시도 또는 요청 간 exactly-once 보장.
## 대상 사용자와 권한
| 주체 | 허용 동작 | 거부 조건 |
|---|---|---|
| 익명 앱 클라이언트 | 지정 placement의 공개 GET | 다른 HTTP method 및 인접 경로는 기존 인증 정책 적용 |
| `ADMIN` | 모든 관리자 CRUD | 인증되지 않았거나 ADMIN이 아닌 요청은 변경 전 거부 |
## 기능 요구사항
아래 요구사항은 `DEC-009`의 구현 승인에 따라 완료했으며 각 행을 [plan-task.md](plan-task.md)의 실행 Goal·검증 증거에 연결한다. 상태 열의 초기 제안 표기는 요구사항 출처이며 현재 미구현을 뜻하지 않는다. 최종 wire 계약은 `api-contract.md`를 따른다.
| ID | 상태 | 요구사항 | 수용 기준 | 계약 / Goal |
|---|---|---|---|---|
| `SB-001` | 작성자 영속성 제안 | 서브 배너는 독립적인 테이블에 저장한다. placement는 `HOME_RECOMMENDATION` 또는 `CONTENT_RECOMMENDATION` 하나다. | 신규 레코드가 제안 SQL의 독립 테이블에서 저장/조회되고, 기존 콘텐츠 배너 테이블에는 schema/data 변경이 없다. | §1, `P2-T1` |
| `SB-002` | API 형태 제안, 최소 주소 조건 확정 | 응답 객체는 id, placement, imageUrl, 세 nullable 링크를 가진다. 내부 저장 모델은 CDN URL 대신 object key인 imagePath를 보관한다. | 8개 존재 조합 중 모두 null인 경우는 거부하고 나머지 7개 조합은 허용한다. 관리자와 공개 DTO에만 imagePath를 절대 imageUrl로 조립한다. | §1, `P2-T1`, `P3-T1` |
| `SB-003` | CRUD 확정, 응답·정렬 제안 | 관리자는 placement별 활성 목록, 생성, 수정, 삭제를 수행한다. | GET은 삭제되지 않은 행을 기간과 무관하게 id 오름차순으로 반환한다. 생성/수정은 저장된 객체, 삭제는 `data:null`로 응답한다. | §3, `P3-T1`, `P5-T1` |
| `SB-004` | 최소 주소 조건 확정, 정규화·URI 안전 규칙 제안 | 세 링크는 각각 nullable이며 trim 후 최소 하나가 nonblank여야 한다. | 모든 8개 존재 조합을 검사하며 모두 null/blank인 경우만 거부한다. 공백뿐인 값은 null 처리한다. nonblank 값은 trim 외 원문 byte/문자열을 재인코딩하거나 정규화하지 않는다. web URL은 absolute http/https, 딥링크는 유효한 URI이며 `javascript`, `data`, `file`, `content` scheme은 대소문자와 무관하게 거부한다. 별도의 임의 scheme allowlist는 추가하지 않는다. | §1, `P3-T1` |
| `SB-005` | 작성자 안전 제안 | 이미지가 필수인 생성과 선택적 이미지 교체 수정을 지원한다. | MIME/type 검증 및 모든 request 검증이 S3 업로드와 DB 변경 전에 끝난다. 업로드 실패 시 기존 이미지 값은 바뀌지 않는다. DB rollback이 이미 완료된 S3 업로드를 되돌린다고 가정하지 않는다. | §3, `P3-T1` |
| `SB-006` | 사용자 확정 | 선택적 `startDate`, `endDate`를 독립적으로 설정·조회·수정·해제한다. | KST `yyyy-MM-dd HH:mm`만 받고 응답한다. 생성 누락/null은 unbounded, 수정 누락은 유지, 수정 null은 해당 경계 해제다. 병합 후 날짜 역전은 저장하지 않는다. | §1, §3, `P2-T1`, `P3-T1` |
| `SB-007` | 확정 요구, 상태 매핑은 기존 정책 확인 필요 | 관리자 GET/POST/PUT/DELETE는 ADMIN 권한이어야 한다. | 익명 및 non-ADMIN이 CRUD를 시도해도 데이터가 변하지 않는다. 테스트는 실제 공통 접근 거부 handler의 HTTP/envelope 동작을 확인하고 임의로 403을 가정하지 않는다. | §3, `P3-T1`, `P4-T1` |
| `SB-008` | 사용자 후속 확정 | 두 추천 API가 각 화면 placement의 활성·기간 내 전체 서브 배너를 함께 반환한다. | 비로그인 `GET /api/v2/home/recommendations`는 HOME_RECOMMENDATION, `GET /api/v2/audio/recommendations`는 CONTENT_RECOMMENDATION의 `data.subBanners`를 반환한다. id 오름차순·빈 배열·기간 경계·무절단 규칙은 유지하고 별도 앱 조회 endpoint를 제거한다. | §2, `P6-T1` |
| `SB-009` | 사용자 후속 확정 | 기존 추천 응답에 `subBanners`만 추가하고 다른 필드는 보존한다. | 각 배열 항목은 기존 6필드 `{id, placement, imageUrl, webUrl, androidDeepLink, iosDeepLink}`다. 기존 `banners`와 추천 콘텐츠를 교체하지 않는다. 날짜·isActive는 노출하지 않으며 OS 필터는 앱 책임이다. | §1, §2, `P6-T1` |
| `SB-010` | 작성자 데이터 안전 제안 | 신규 테이블 DDL과 적용 전후 안전성을 제공한다. | `docs/20261029_가로형서브배너/create-sub-banner.sql`에 모든 column/table COMMENT, nullable UTC `TIMESTAMP` 기간 컬럼, 필요 시 기존 audit timestamp 관례를 포함한다. 계획에 적용 조건과 rollback 절차를 적고 자동 live DDL은 하지 않는다. | §1, `P2-T1` |
| `SB-011` | 작성자 API/오류 제안 | 성공 envelope와 계약된 응답 shape를 일관되게 유지한다. | 성공은 `ApiResponse<T>` 4필드, HTTP 200, 관리자 빈 목록 `[]`, 관리자 POST/PUT 객체, DELETE `null`, 공개 날짜 미포함. 잘못된 입력/없음 상태의 status는 API 계약 검토 후 기존 handler를 활용하거나 endpoint 경계에서 처리한다. | `api-contract.md` §1, §5, `P3-T1`, `P4-T1` |
| `SB-012` | 사용자 후속 확정 | 관리자 삭제는 `is_active=false` 소프트 삭제다. | DB 행·이미지 key·주소·기간·생성 시각을 보존한다. 관리자/공개 목록과 id 조회에서 비활성 행을 제외하며 삭제된 id 수정·재삭제는 404다. 응답에 isActive를 추가하지 않고 S3는 보존한다. 복구/활성 토글/cleanup은 범위 밖이다. | §3, `P5-T1` |
| `SB-013` | 사용자 후속 확정, 2026-11-02 | 서브 배너 언어는 기존 `Lang`의 `KO`, `EN`, `JA` 중 하나로 저장한다. 관리자 생성에서 생략하면 KO, 수정에서 생략하면 기존 값을 유지하고 응답에는 `lang`을 포함한다. 공개 추천은 기존 회원 국가 판정 JP→JA, 그 외→KO를 적용한다. | 명시적 null·비문자열·잘못된 코드는 HTTP 400이며 업로드/저장 전 거부된다. 관리자 목록은 언어 미필터 전체 조회다. public repository에는 필수 `Lang` 조건을 전달하고 public `SubBanner` DTO는 변경하지 않는다. 기존 행은 KO로 backfill하며 JA 분류 및 연결 이벤트와의 언어 정합성은 운영 담당자가 수동 확인한다. | §3, `P7-T1`, `P7-GATE` |
## API 및 데이터 계약
- 앱 조회: `GET /api/v2/home/recommendations`, `GET /api/v2/audio/recommendations`의 `data.subBanners` 배열. 비로그인 허용, 화면별 placement 고정, 페이지네이션 없음, id 오름차순. 별도 `/api/v2/sub-banners`는 제거한다.
- 관리자: `GET/POST /admin/sub-banners`, `PUT/DELETE /admin/sub-banners/{id}`, ADMIN 전용. GET은 필수 placement query.
- 성공은 HTTP 200과 공통 `ApiResponse` `{success,message,data,errorProperty}`. POST/PUT multipart에는 `image`와 JSON `request`; POST image 필수, PUT image 선택. PUT의 기존 네 필드는 필수 replacement이고 날짜만 선택적 보존/해제다.
- 두 추천 응답의 `subBanners` 항목은 기본 6필드, 관리자 DTO는 날짜 문자열 두 필드를 더한다. 추천 응답의 기존 `banners` 등 모든 기존 필드는 유지한다.
- 관리자 목록은 삭제되지 않은 활성 행의 모든 기간 상태를 반환한다. 공개 조회는 활성 행에 현재 기간 필터를 추가하며 앱에서 로컬 시간으로 기간 판정하지 않는다.
- 입력 검증과 없는 id는 `ResponseStatusException`을 통해 400/404 Boot 오류 body를 반환한다. 익명은 401, 유효한 비관리자 및 multipart 바인딩 오류는 기존 handler의 200 `success:false`다. 공통 예외 정책을 변경하지 않았다.
## 시간·검증·저장 규칙
- 입력 시각은 엄격한 KST `yyyy-MM-dd HH:mm` 분 정밀도만 허용한다. 초, offset, `Z`, 공백/빈 문자열, raw scalar의 문자열 외 타입, 잘못된 달력 날짜 및 병합 후 start > end는 저장/업로드 전에 거부한다.
- 시작 분은 `:00`, 종료 분은 `:59`까지 포함한다. 동일 분 경계는 유효하다. null 경계는 독립적으로 unbounded다.
- 저장 경계는 KST 입력에서 한 번 정규화한 UTC 초 단위 값이며, 그 값을 영속화와 관리자 응답 변환에 공통 사용한다. DB flush/clear/reload 후 시작 `:00`·종료 `:59`와 관리자 날짜 문자열을 정확히 왕복 비교한다. 공개 조회의 현재 시각은 한 번만 얻어 초 단위로 절삭한다. 이 시각 seam에 나노초 `0`, `123456789`, `999999999` 및 날짜 경계를 넣어 종료 분 마지막 초와 다음 초의 판정을 확인한다. 분 형식 API에 소수초 입력을 허용하는 것은 아니다.
- 링크 입력은 JSON 원문 유형 확인 후 trim 처리한다. nonblank URI는 trim 이후 원문을 보존한다. 기존 Tika 기반 `validateImage(file, gifAllowed = true)`를 호출해 이미지 내용을 검사하고 GIF를 허용한다. 빈 파일은 거부한다. 신규 dependency나 임의 추가 크기 제한은 없다.
- 현재 `application.yml` multipart 제한은 파일 및 요청 각각 1024MB다. 이를 새 제품 상한으로 해석하거나 몰래 변경하지 않는다.
- `S3Uploader.upload(InputStream, bucket, filePath, metadata?)` 반환은 object key다. `imageUrl` 생성 시 기존 CDN 변환 관례를 사용하며 object key를 URL로 오인해 응답하지 않는다. 저장 실패 뒤 이미 업로드된 S3 객체는 자동 삭제/rollback을 보장하지 않으며 cleanup job은 범위 밖이다.
- 삭제는 `is_active=false`만 반영하고 DB 행과 S3 object를 보존한다. 관리자 목록은 활성 행의 모든 기간 상태를, 공개 목록은 활성 행 중 기간 내 항목만 반환한다.
## 근거와 제안 경계
현행 동작 근거:
- 추천 배너 구조: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/common/dto/RecommendationBannerResponse.kt`, `.../v2/api/home/adapter/in/web/HomeRecommendationController.kt`, `.../v2/api/content/recommendation/adapter/in/web/AudioRecommendationController.kt`.
- 기존 관리자 배너: `src/main/kotlin/kr/co/vividnext/sodalive/admin/content/banner/AdminContentBannerController.kt`, `AdminContentBannerService.kt`, `GetAdminContentBannerResponse.kt`.
- 예약 기간 규칙: `docs/20261027_콘텐츠배너예약기간/prd.md` §6-8, `src/main/kotlin/kr/co/vividnext/sodalive/content/main/banner/AudioContentBannerVisibility.kt`, `docs/20261027_콘텐츠배너예약기간/alter-content-banner-reservation.sql`.
- 경량 헥사고날 패키지와 권한: `docs/agent-guides/코드스타일.md`, `src/main/kotlin/kr/co/vividnext/sodalive/configs/SecurityConfig.kt`.
- 응답/예외 사실: `src/main/kotlin/kr/co/vividnext/sodalive/common/ApiResponse.kt`, `SodaExceptionHandler.kt`.
- 이미지 업로드/검증: `src/main/kotlin/kr/co/vividnext/sodalive/aws/s3/S3Uploader.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/utils/ImageValidation.kt`.
- 테스트 관례: `src/test/kotlin/kr/co/vividnext/sodalive/admin/content/banner/AdminContentBannerControllerIntegrationTest.kt`, `AdminContentBannerServiceTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/dto/recommendation/HomeRecommendationResponseTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/content/recommendation/adapter/in/web/AudioRecommendationEndToEndTest.kt`.
신규 `v2.subbanner` 경로와 SQL은 구현되어 있다. 기존 `v2.creatorname` 패턴을 따른 단일 독립 기능 모듈이며 불필요한 API composition 모듈이나 utility wrapper를 추가하지 않았다.
## 수용 기준
- [x] `SB-001`~`SB-012` 각각을 구현 Goal·테스트·Gate 증거로 연결했다.
- [x] 신규 테이블, 기간 및 기본 CRUD는 기존 콘텐츠 배너 schema/data를 변경하지 않는다.
- [x] 관리자 기간 경계를 실제 DB flush/clear/reload와 HTTP 날짜 왕복으로 정확히 검증했다.
- [x] 익명 public GET만 permitAll이며 인접 경로·다른 method·관리자 권한 보호를 실제 HTTP로 검증했다.
- [x] payload 검증 실패의 이미지 upload/DB mutation 0회와 실제 오류 응답을 검증했다.
- [x] 전체 2,676 tests, lint, bootJar 및 독립 최종 리뷰 통과. 운영 DB 적용·배포는 별도이며 완료로 표시하지 않는다.
- [x] 후속 P5·P6는 전체 2,682 tests(실패·무시 0), lint·bootJar와 독립 리뷰를 통과했다. 비로그인 두 추천 응답의 subBanners와 standalone handler 제거, 소프트 삭제 행 보존 및 동시 비복원을 실제 HTTP/DB로 검증했다. 앞선 2,676건은 초기 구현 이력이다.
- [x] 후속 `SB-013`: 기존 `Lang` 필드, 관리자 생성 KO 기본값·수정 생략 유지·잘못된 값의 부작용 전 HTTP 400, 관리자 전체 언어 목록, 두 공개 추천 API의 회원 국가별 언어 필터와 public DTO 불변을 검증했다. (`P7-T1`, `P7-GATE`; 2026-11-03 전체 2,928개 및 영향 HTTP 재검증 완료)
## Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 |
|---|---|---|---|---|
| 2026-10-29 | DEC-001 | 사용자 확정 | 가로형 서브 배너, 관리자 CRUD, 세 nullable 주소 중 최소 하나, 두 추천 placement, 각 목록 다중 항목, 웹 URL 또는 대상 OS 딥링크가 있는 앱 항목 표시 | 사용자 확인 |
| 2026-10-29 | DEC-002 | 작성자 제안 | trim 후 blank를 null로 만들고 nonblank URI를 변형하지 않음 | 입력 안전성 제안, 승인되지 않음 |
| 2026-10-29 | DEC-003 | 작성자 제안 | API 경로·모델·정렬 순서·단일 placement 레코드 정책 | 일관된 최소 계약 제안, 승인 및 서버 제공 대기 |
| 2026-10-29 | DEC-004 | 작성자 제안 | 대상 OS 딥링크 우선 및 실패 시 웹 URL fallback | 앱 이동 정책 제안, 승인되지 않음 |
| 2026-10-29 | DEC-005 | 사용자 확정 | 관리자에서 콘텐츠 배너와 같은 선택적 노출 기간을 설정한다. KST 분 형식 및 경계 의미는 기존 콘텐츠 배너 예약 동작을 따른다. | 사용자 확인 및 기존 콘텐츠 배너 근거 |
| 2026-10-29 | DEC-006 | 사용자 승인, 범위 제한 | 이번 승인으로 기존 디렉터리의 PRD와 plan-task를 백엔드 요구사항 및 구현 계획으로 완성한다. 이번 변경은 문서 전용이며 제안 API 전체 승인이나 실제 구현 승인이 아니다. | 사용자 요청의 현재 작업 승인 범위 |
| 2026-10-29 | DEC-007 | 작성자 구현 권고, 검토 필요 | 독립 `v2.subbanner` 모듈과 제안된 신규 테이블을 사용한다. 이미 업로드된 S3 객체의 DB rollback 후 자동 정리는 보장하지 않으며 삭제 정책은 첫 구현 Task에서 확인한다. | 현행 코드 패턴과 S3/DB transaction 한계. 사용자 제품 결정으로 간주하지 않음 |
| 2026-10-29 | DEC-008 | 사용자 승인 | 문서 전용 작업의 검증은 문서 대조와 공백 검사로 한정하고 Gradle·테스트·빌드는 실행하지 않는다. 향후 구현용 명령을 문서에 적는 것만으로 실행 검증을 요구하지 않는다. | 사용자 승인 및 `docs/agent-guides/문서유지보수.md`의 검증 지침 수정 |
| 2026-10-29 | DEC-009 | 사용자 구현 승인 | 문서대로 백엔드 코드와 DDL 파일을 구현한다. 운영 DB 적용·배포는 승인 범위에 포함하지 않는다. 기존 기간·독립 API 모델을 사용하며 검증 시 H2·테스트 JWT·S3 대체 객체로 외부 부작용을 격리한다. | 후속 사용자 요청 및 ulw 실행 |
| 2026-10-29 | DEC-010 | 사용자 후속 확정·정정 | `is_active BOOLEAN NOT NULL DEFAULT TRUE`를 추가하고 DELETE는 false 갱신으로 변경한다. 삭제된 행은 모든 소비자 조회에서 제외하며 응답·권한·기간·S3 정책은 유지한다. 앞선 하드 삭제 완료 기록은 당시 이력으로 보존한다. | "is_active를 두고 소프트 삭제로 하자" |
| 2026-10-29 | DEC-011 | 사용자 후속 확정·정정 | 별도 앱 GET을 제거하고 두 추천 GET에 `data.subBanners`를 추가한다. 두 GET 모두 비로그인 접근을 유지하고 앱 프롬프트도 함께 변경한다. 관리자 CRUD·소프트 삭제·기간·응답 항목은 유지한다. | 두 추천 API 통합 및 앱 프롬프트 수정 요청 |
| 2026-11-02 | DEC-012 | 사용자 후속 확정 | 서브 배너에 기존 `Lang` enum 필드를 추가한다. 관리자 생성 누락은 KO, 수정 누락은 유지, 명시적 null·비문자열·invalid는 HTTP 400이며 upload/write 전 검증한다. 관리자 목록은 언어 전체 조회, 공개 두 추천은 회원 국가 기준 JP→JA/그 외→KO로 필터링한다. public DTO는 유지한다. | 승인된 최소 이벤트/서브 배너 언어 후속 수정 |
| 2026-11-03 | DEC-013 | 사용자 후속 변경 | 이관 파일을 SET/PREPARE/EXECUTE 없는 정적 ALTER TABLE 한 문장으로 변경한다. lang 컬럼이 없는 기존 테이블에 한 번만 적용하며 이미 존재하면 실행하지 않는다. 컬럼 정의와 KO 기본값은 유지한다. | 프로시저 없이 순수 SQL로 변경 요청 |
## 후속 사용자 요구사항: 관리자 노출 기간
- 관리자는 가로형 서브 배너의 선택적 `startDate`, `endDate`를 설정·조회·수정·해제할 수 있다.
- 두 경계는 독립적 nullable 값이다. 둘 다 null이면 기간 제한이 없고, 시작만 있으면 시작 시각부터, 종료만 있으면 종료 경계까지 노출한다. 같은 분의 시작/종료도 유효하다.
- 관리자 입력과 응답은 `Asia/Seoul`의 `yyyy-MM-dd HH:mm` 문자열이며 분 정밀도다. 시작 분은 `:00`부터 포함하고 종료 분은 `:59`까지 포함한다. 초, `Z`, offset은 받지 않는다.
- 공개 조회는 현재 기간 안에 있는 항목 전체를 반환한다. 앱은 그 결과에 기존 웹 URL/현재 OS 딥링크 필터를 적용하며 앱 로컬 시계로 기간을 계산하지 않는다.
- 공개 DTO에는 날짜·활성 필드를 추가하지 않는다. 관리자 목록은 삭제되지 않은 활성 행의 미래·현재·만료·무제한 상태를 모두 포함한다.
- 기존 근거는 `docs/20261027_콘텐츠배너예약기간/prd.md` §6-8, `AdminContentBannerService.kt` 및 `GetAdminContentBannerResponse.kt`다. 신규 계약의 승인이나 구현을 뜻하지 않는다.
## 후속 사용자 요구사항: 서브 배너 언어 — 2026-11-02
- `SubBanner` domain, JPA entity/storage, admin request와 admin response에 기존 `Lang`의 `KO`, `EN`, `JA`를 추가한다. 새 enum은 만들지 않는다.
- 관리자 create에서 `lang`을 생략하면 KO로 저장한다. update에서 생략하면 기존 언어를 보존한다. 명시적 null, JSON 비문자열 또는 유효하지 않은 코드는 HTTP 400으로 거부하고 S3 upload와 DB write 이전에 검증한다.
- 관리자 목록은 기존 placement 조건 외 언어 필터를 추가하지 않으며 응답마다 `lang`을 반환한다. public `SubBannerResponse`에는 `lang`을 노출하지 않는다.
- 공개 조회 service는 member를 받아 기존 `MemberContentPreferenceService.resolveCountryCode(member)`로 JP→JA, 그 외→KO를 선택하고 이를 필수 Lang으로 repository에 전달한다. 두 추천 facade는 기존 member를 service에 전달한다.
- 기존 테이블 CREATE SQL에는 `lang VARCHAR(10) NOT NULL DEFAULT 'KO'`를 포함한다. 별도 migration은 DEC-013에 따라 lang 컬럼이 없는 기존 테이블에 같은 정의를 단일 정적 ALTER TABLE로 추가한다. 기존 행은 KO 기본값을 가지며 자동 존재 검사·재실행 건너뛰기는 제공하지 않는다. 이미 lang이 있으면 실행하지 않는다.
- KO backfill은 기존 행의 언어를 자동 추론하지 않는다. 운영 적용 전에 배너 소재를 검토해 JA 배너와 연결 이벤트의 언어를 운영 담당자가 수동 분류·정합성 확인해야 한다. 운영 DB에 DDL을 실행하지 않는다.
- 제외: 앱/관리자 UI, event link parsing, event detail/adult 정책 변경, 새 dependency, public DTO 변경, 운영 DB·DDL 실행.
@@ -1,52 +0,0 @@
# 메인 탭·서브 배너 언어 후속 리뷰
## 리뷰 정보
- 일자: 2026-11-02
- 대상: 이벤트 언어 `P3-T1/P3-GATE`, 서브 배너 `P7-T1/P7-GATE`.
- 기준: `7fce26ad` 이후 현재 `test` 브랜치 변경. 별도 worktree 없음.
- 독립 리뷰어: Oracle (`ses_e634d4707ffe00405lhcwZXMXM`). 기록 담당: Sisyphus.
- 요구사항: 이벤트 PRD `EVENT-LANG-010`, 서브 배너 PRD `SB-013/DEC-012`, 기존 API 계약.
## 판정
**명세 준수 APPROVE, 코드 품질·시나리오 커버리지 APPROVE. 확정 발견 사항 없음.**
초기 리뷰 시 전체 검증은 진행 중이므로 전체 Gate 완료 판정은 보류했다. 후속 실행 결과는 아래에 누적한다.
| 시나리오 | 확인한 근거 |
|---|---|
| S1 메인 탭 | 여섯 호출부가 기존 `isAdult`를 보존하고 `resolveCountryCode(member)`로 JP→JA/그 외→KO를 전달한다. `EventBannerLanguageIntegrationTest`가 실제 HTTP에서 정확한 ID·순서·5필드, 일반/강제 국가와 익명 홈을 검증한다. |
| S2 공개 서브 배너 | 두 facade가 member를 전달하고 repository가 언어 equality를 기존 활성·기간 조건과 결합한다. `RecommendationSubBannerIntegrationTest`가 JP/KR/US/누락/강제 국가, 빈 결과, EN 제외, 6필드 및 원문 링크를 확인한다. |
| S3 관리자 | 생성 언어 생략 KO, 수정 생략 보존, explicit null/non-text/blank/unknown의 업로드·쓰기 전 400을 검증한다. 실제 DB 불변, S3 상호작용 0, 실제 repository spy save 0을 함께 확인한다. 관리자 조회는 모든 언어·9필드다. |
| S4 인접 회귀 | focused 11개 클래스 145 tests, failures/errors/skipped 0. 기존 기간·초 정밀도·소프트 삭제·정렬·무절단 테스트 보존. 전체 suite/lint/build는 초기 리뷰 시 진행 중이었다. |
## 검토한 증거
- 신규 실제 HTTP 테스트와 기존 서브 배너 domain/persistence/admin/recommendation 및 facade 테스트의 assertion을 직접 검토했다.
- `final-focused.log`의 `BUILD SUCCESSFUL in 8m 8s`, 11개 XML의 145 tests 및 실제 HTTP 185건/DB 증거를 대조했다. 해당 임시 원본은 작업 종료 시 정리하며 핵심 결과를 이 문서와 두 계획에 보존한다.
- 신규 CREATE와 기존 테이블 migration의 guarded 컬럼 추가 → NULL만 KO backfill → NOT NULL/default 흐름을 검토했다. H2 CREATE 검증과 native MySQL 실행을 구분한다.
- LSP 도구가 없어 `lsp_diagnostics`는 미실행이며 Gradle 컴파일·lint를 대체 근거로 사용한다. LSP 통과로 표현하지 않는다.
## 운영 한계
운영 DB·native MySQL·실제 AWS·앱/관리자 UI·배포는 검증 범위 밖이다. 서버 배포 전에 스키마를 준비해야 한다. 임의 링크에 이벤트 관계나 자동 언어 검증을 추가하지 않았으므로 JA 소재 및 연결 이벤트 언어의 수동 정합성 확인이 필요하다. 이벤트 상세·성인 정책은 변경하지 않는다.
## 후속 검증
전체 검증 결과와 소유 자원 정리 증거는 실행 종료 후 누적한다. 확정 결함이 없어 회귀 수정 Goal 전환 항목은 없다.
### 2026-11-03 부모 재검증
- `./gradlew test ktlintCheck bootJar --continue --console=plain --no-daemon -Pkotlin.compiler.execution.strategy=in-process`: 전체 336 suites / 2,928 tests / failures=0 / errors=0 / skipped=0, bootJar 성공. 테스트 인자 줄바꿈 한 곳만 lint 실패해 최초 명령 exit 1 (15m 50s).
- 제품 코드 변경 없이 테스트 인자 배치만 수정한 뒤 해당 `RecommendationSubBannerIntegrationTest`와 `ktlintCheck bootJar` 재실행: exit 0, 26 tests / 실패·오류·무시 0, `BUILD SUCCESSFUL in 4m 32s`.
- 전체 XML은 재실행 전에 부모가 집계했다. 현재 보고서는 26개 재실행 결과로 갱신되어 있으며 전체 성공 기록과 구분한다. 공백 변경만 있어 전체 재실행 대신 영향받은 실제 HTTP suite를 다시 구동했다.
- 기존 Oracle 세션의 continuation 도구가 `Task not found`를 반환해 새 Oracle 세션에 공백 delta와 최종 실행 증거만 재판정하도록 전달했다. 전면 리뷰를 중복 수행하지 않는다.
- 후속 Oracle (`ses_e6323aa1afferoJ13TsZawApwR`) 판정: **APPROVE. 동작 변경 없음, 영향 HTTP 26개 및 lint/build Gate 승인, 추가 발견 사항 없음.** 전체 2,928개 집계는 XML 갱신 전 부모 기록에 의존함을 명시했다. 부모는 최종 bash 실행의 정상 반환과 `BUILD SUCCESSFUL`을 직접 확인했다.
- 최종 결론: 승인된 backend 범위의 `P3-GATE/P7-GATE` 완료. 운영 배포 성공이나 LSP 실행을 주장하지 않는다.
## 종료 증거
- 제품 커밋: `255da2b6` (메인 탭 필터·HTTP 회귀), `c4c61e36` (서브 배너 언어·SQL·테스트). 두 커밋의 ktlint hook 및 커밋 메시지 검증 통과. `git diff --exit-code -- src` 정상으로 hook 후 추가 소스 변경 없음.
- 전체 검증 runner PID `49134` 종료, `pgrep -fl 'GradleDaemon|GradleWorkerMain|redis-server'` 결과 없음. 랜덤 포트 테스트 서버는 테스트 컨텍스트 종료로 정리됐다.
- 소유 임시 경로 `/tmp/soda-banner-ulw.HDkpg4`, `/tmp/soda-banner-worker.AMcPYe`, `/tmp/soda-banner-impl.CfAkhD`, `/tmp/soda-banner-review.tIFyeb`는 소유·실경로 확인 후 삭제하고 네 경로 모두 부재를 확인했다. 임시 notepad도 삭제했다. 공유 Gradle 캐시와 저장소 build reports/JAR는 보존했다.
- worktree 생성·운영 DDL·배포·push 없음. 현재 `test` 브랜치에서 완료했다.
@@ -1,9 +0,0 @@
-- 수동 배포용 additive schema이며 운영 DB에서 자동 실행하지 않는다.
-- 서버/JDBC/DB UTC 확인 후 schema를 먼저 적용하고, 공개 필터가 포함된 앱으로 모든 reader를 교체한다.
-- 이전 reader가 하나라도 남아 있으면 예약 공지를 노출하므로 전체 교체 전에는 예약 쓰기/admin 사용을 금지한다.
-- 기존 row는 NULL/FALSE를 유지하며 created_at 변경이나 backfill을 수행하지 않는다.
ALTER TABLE service_notice
ADD COLUMN publish_at TIMESTAMP NULL DEFAULT NULL COMMENT '예약 공개 시각(UTC)';
ALTER TABLE service_notice
ADD COLUMN is_scheduled BOOLEAN NOT NULL DEFAULT FALSE COMMENT '예약 공개 여부';
@@ -1,100 +0,0 @@
# 관리자 공지 예약 공개 API 연동 작업
아래 요구사항에 따라 기존 ADMIN 공지사항 생성·수정 화면의 API 연동을 변경하세요. 이 작업은 기존 화면에 예약 공개 입력과 처리만 추가하며 화면을 새로 설계하지 않습니다. **아래 API 계약을 기준으로 작업하며 실제 연결은 대상 API 사용 가능 여부를 확인한다.**
## 작업 범위
- 기존 공지 생성과 수정 기능에 선택적 예약 공개 시각 `publishAt` 입력과 전송을 추가합니다.
- API 요청·응답 및 화면 상태 연결만 다룹니다. 서버 구현이나 서버 설정을 변경하지 않습니다.
- 기존 화면 구조와 사용자 동작을 유지하고, 필요한 API 연동만 수정합니다.
## 공통 계약
- 기존 ADMIN Bearer 인증을 재사용합니다. 새 인증 흐름이나 권한 체계를 만들지 않습니다.
- 성공은 `ApiResponse`의 `success`, `message`, `data`, `errorProperty` envelope로 판별합니다. HTTP 200이어도 `success: false`면 실패입니다.
- 오류 응답의 기존 필드를 보존하고, 사용자에게는 응답 `message`를 표시합니다. 인증 오류는 기존 로그인 흐름을 따릅니다.
- 시각 문자열은 모두 Asia/Seoul 기준 `yyyy-MM-dd HH:mm:ss`입니다. `T`, `Z`, offset, 밀리초를 포함하지 않습니다.
- 브라우저 시간대를 거쳐 변환하거나 KST 시각을 다시 변환하지 않습니다. 표시·입력한 시각을 그대로 계약 형식으로 보내 이중 시간대 이동을 막습니다.
## 생성
`POST /notice`
요청 필드: `title`, `content`, 선택 필드 `publishAt` (`string | null`).
```json
{
"title": "서비스 점검 안내",
"content": "점검 시간과 안내 내용",
"publishAt": "2026-11-15 09:00:00"
}
```
- `publishAt` 생략 또는 `null`은 즉시 공개입니다.
- 미래의 유효한 시각 문자열은 예약 공개입니다. 예시 시각은 실제 요청 시점보다 미래여야 합니다.
- 현재 또는 과거 시각은 허용하지 않습니다. 오류를 정상 성공처럼 처리하지 않습니다.
- 요청에 `isScheduled`, `createdAt`, `isActive`를 추가하지 않습니다. 생성 성공 응답의 `data`는 숫자 공지 ID입니다.
## 수정
`PUT /notice`
요청 필드: 필수 `id`, 선택 `title`, `content`, `publishAt` (`string | null`).
```json
{
"id": 42,
"publishAt": "2026-11-20 10:30:00"
}
```
- `publishAt` 생략은 기존 예약 상태를 보존합니다. 제목만 또는 본문만 수정할 때도 이 규칙을 따릅니다.
- 명시적 `null`은 아직 공개되지 않은 예약 공지를 지금 공개하겠다는 의도일 때만 보냅니다.
- 미래 시각 문자열은 아직 공개되지 않은 예약 공지의 예약 시각을 변경합니다. 시각만 변경하는 요청도 유효합니다.
- 이미 공개된 공지는 제목·본문 수정은 허용되지만 공개 시각 변경은 허용되지 않습니다. 그런 요청의 API 실패를 존중하고 우회하거나 재시도하지 않습니다.
- 제목만 수정할 때 폼에 조회한 `publishAt` 값이 있어도 요청에서 반드시 생략합니다. 기본값 `null`을 무심코 직렬화하지 말고, 사용자가 즉시 공개 전환을 명시한 경우에만 `publishAt: null`을 보냅니다.
- 수정 성공 시 `data`의 구체적인 값에 의존하지 않습니다. `success`를 확인한 뒤 목록을 다시 조회합니다.
## 관리자 목록
`GET /api/v2/admin/notices?page=0&size=20`
기존 ADMIN 인증을 사용합니다. 공개된 항목만 반환하는 공개 공지 API를 대신 사용하지 않습니다. ADMIN 토큰으로 공개 API를 호출해도 예약 공개 전 공지는 반환되지 않습니다.
응답 `data` 형식:
```json
{
"totalCount": 1,
"noticeList": [
{
"id": 42,
"title": "서비스 점검 안내",
"content": "점검 시간과 안내 내용",
"isActive": true,
"isScheduled": true,
"publishAt": "2026-11-15 09:00:00",
"createdAt": "2026-10-30 14:20:00"
}
]
}
```
각 항목은 `id`, `title`, `content`, `isActive`, `isScheduled`, `publishAt`, `createdAt`을 가집니다. `publishAt`은 공개 시각 문자열 또는 `null`이며, 예약을 즉시 공개로 전환한 항목에는 전환 시각이 들어 있습니다. `null`은 시각을 지정하지 않고 즉시 등록한 공지입니다. 목록에는 활성 공개 공지와 아직 공개되지 않은 활성 예약 공지가 모두 포함됩니다. 페이지 인덱스는 0부터 시작하고 `totalCount`는 이 관리자 목록의 전체 대상 건수입니다.
별도의 공지 상세 API는 없습니다. 편집 시 목록에서 받은 전체 항목을 사용하고, 존재하지 않는 상세 경로를 만들지 않습니다.
## 날짜 표시와 목록 갱신
- 예약 공개 공지의 날짜 표시는 `publishAt`의 KST 날짜를 사용합니다.
- 즉시 생성된 공지와 예약에서 즉시 공개로 전환한 공지의 날짜 표시는 원래 등록 시각인 `createdAt`의 KST 날짜를 사용합니다.
- `isScheduled`는 응답 전용 표시 상태이며 요청에 보내지 않습니다. 예약이 자연 공개된 뒤에도 `true`일 수 있으므로 이를 미공개 여부로 해석하지 않습니다. `isScheduled`와 미래 `publishAt`을 함께 화면 동작 판단에 참고할 수 있지만, 공개 경계를 최종 판단하는 주체는 API입니다. 클라이언트 시계나 이 불리언만으로 공개 상태를 확정하거나 API 거부를 무시하지 않습니다.
- 생성·수정 성공 후 목록을 다시 조회합니다. 응답은 공개 시각 내림차순, 같은 시각이면 ID 내림차순입니다. 이 순서를 유지하고 표시 날짜를 기준으로 클라이언트에서 재정렬하지 않습니다. 특히 예약을 즉시 공개로 전환한 경우 표시 날짜는 원래 등록일이지만 목록 순서는 공개 시각 변경에 따라 달라질 수 있습니다.
- 목록을 불러오거나 저장할 수 없을 때 임의의 공개 API로 자동 대체하지 않습니다. API 실패를 보존해 기존 오류 흐름으로 처리합니다.
## 완료 확인
- 생성에서 `publishAt` 생략/null은 즉시 공개, 미래 시각은 예약 요청으로 전달됩니다.
- 수정에서 `publishAt` 생략은 보존, 명시적 null은 의도된 즉시 전환, 미래 시각은 재예약으로 전달됩니다. 제목만 수정할 때 `publishAt`은 생략됩니다.
- 관리자 목록은 위 경로와 페이지 파라미터를 사용하며 응답의 `success`를 확인하고 목록 순서를 유지합니다.
- 모든 시각 요청·표시는 KST `yyyy-MM-dd HH:mm:ss`이며 브라우저 시간대 변환을 추가하지 않습니다.
@@ -1,357 +0,0 @@
# 공지사항 예약 공개 구현 계획
> 실행자: 아래 Goal을 순서대로 하나씩 실행하고 각 체크박스와 실제 검증 결과를 누적한다. 구현 Task는 RED → RED 확인 → GREEN → GREEN 확인 → REFACTOR를 따른다. 사용자 후속 요청으로 SQL/source/test 구현이 승인됐다.
**Goal:** ADMIN이 예약 공지를 안전하게 관리하고 모든 공개 consumer가 공개 시점·정렬·날짜 계약을 지킨다.
**Architecture:** 현재 notice domain/repository와 ServiceNoticeController를 확장하고 v2 ADMIN 목록 조립 endpoint를 추가한다. 공개 query는 역할과 무관한 단일 visibility predicate를 사용하며 reservation write는 기존 notice row의 pessimistic lock에서 검증한다.
**Tech Stack:** Kotlin, Spring Boot 2.7.14, Spring Data JPA, QueryDSL, MySQL, 기존 H2/JUnit 5 테스트 구성. 신규 dependency 없음.
**Spec:** [prd.md](prd.md)
## Global Constraints
- PRD §3~§7의 사용자 확정 권한·공개 정책·응답 호환성을 변경하지 않는다.
- P1-T1은 사용자 확인(서버 UTC·DB UTC·신규 publish_at 초 단위 TIMESTAMP)으로 완료한다. 기존 created_at 정밀도 복제·변경은 하지 않는다.
- 운영 rollout은 additive schema → 전체 read-aware app 교체 → 예약 쓰기/admin 사용 순서이며 feature flag는 추가하지 않는다.
- DB/source/test 변경은 승인된 구현 Task에서 수행한다. 운영 DB 적용·접속 및 배포는 제외한다.
| 문서 항목 | 내용 |
|---|---|
| 상태 | 기능 구현·관련 검증·리뷰 완료, 전체 회귀 timeout으로 최종 Gate 보류 |
| 작성일 | 2026-10-30 |
| 요구사항 기준 | [prd.md](prd.md) |
| API 기준 | `prd.md` §7 |
| 현재 Phase | Phase 3, 전체 회귀 완료 증거 대기 |
| 현재 활성 Goal | 없음, `P3-GATE` blocked |
## 목표
관리자는 활성 공지 예약을 안전하게 관리하고, 공개 클라이언트는 공개 경계에 도달한 공지만 승인된 순서와 날짜로 조회한다.
## 현재 상태 및 실행 규칙
| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 조건 |
|---:|---|---:|---|---|
| 1. 저장 계약과 쓰기 | 완료 | 3/3 | 없음 | 사용자 승인 계약·104개 회귀·단계 리뷰 통과, 운영 적용은 별도 |
| 2. 공개 조회와 관리자 목록 | 완료 | 1/1 | 없음 | 관련 HTTP·DB 122개 및 최종 리뷰 승인 |
| 3. 통합 회귀 (Gate only) | blocked | 해당 없음 | `P3-GATE` | 전체 test 20분 timeout, 전체 회귀 성공 미확인 |
- 동시에 하나의 미완료 Goal만 실행한다. 아래 순서대로 앞 Goal의 완료 증거를 남긴 뒤 다음으로 진행한다.
- 신규 컬럼 초 정밀도·서버/DB UTC는 사용자 승인값이다. 기존 컬럼의 물리 정밀도는 추정하지 않으며 운영 DB에 접속하지 않는다.
- 완료 증거가 기록된 항목만 체크한다. 미완료 테스트 명령과 수동 HTTP 확인은 계획값이다.
## 범위
### 포함
- §7 계약을 기준으로 기존 notice entity, 입력·service, query, 새 ADMIN 목록 API와 security를 변경한다.
- 예약 쓰기, 공개 필터·정렬·표시 날짜, 시각 정밀도와 동시 변경 보호를 테스트한다.
- 기존 공개 v1/v2 응답·권한·오류 assertion을 보존하며 실제 HTTP에서 검증한다.
### 제외
- 관리자/클라이언트 UI, scheduler, catch-up 작업, cache, 신규 role/dependency, 검색/추가 필터, 복원, bulk schedule.
- 운영 DDL 자동 적용/실제 DB 접근, BaseEntity/global timezone 리팩터링, 과거 레코드 backfill.
## 기술 제약과 파일 책임 지도
| 책임 | 현재 파일 또는 계획 파일 |
|---|---|
| 상태/기존 쓰기와 입력 | `src/main/kotlin/kr/co/vividnext/sodalive/notice/ServiceNotice.kt`, `ServiceNoticeService.kt`, `CreateNoticeRequest.kt`, `UpdateNoticeRequest.kt` |
| 기존 쓰기 controller boundary | `src/main/kotlin/kr/co/vividnext/sodalive/notice/ServiceNoticeController.kt` |
| 공개 query 및 ADMIN query | `src/main/kotlin/kr/co/vividnext/sodalive/notice/ServiceServiceNoticeRepository.kt` |
| admin query projection | 신규 `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/admin/notice/dto/AdminNoticeItem.kt` (`@QueryProjection`, createdAt/publishAt KST formatted `AdminNoticeItem` 최소 projection). 기존 query 구현 위치는 유지하고 신규 API DTO는 v2에 둔다. |
| 기존 public latest 조립 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/notice/application/LatestNoticeService.kt` |
| ADMIN 목록 endpoint/application/DTO | 새 파일 `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/admin/notice/adapter/in/web/AdminNoticeController.kt`, `application/AdminNoticeService.kt`, `dto/AdminNoticeResponse.kt` (추가 DTO는 필요 최소로 구현) |
| 보안 | `src/main/kotlin/kr/co/vividnext/sodalive/configs/SecurityConfig.kt` |
| admin response DTO | 신규 `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/admin/notice/dto/AdminNoticeResponse.kt`; `{totalCount: Int, noticeList: List<AdminNoticeItem>}` wrapper와 item 필드만 정의 |
| 통합 HTTP 회귀 | `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/notice/LatestNoticeControllerIntegrationTest.kt` |
| 쓰기/admin HTTP 통합 | 신규 `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/admin/notice/AdminNoticeControllerIntegrationTest.kt` |
| query/DB 회귀 | 신규 `src/test/kotlin/kr/co/vividnext/sodalive/notice/ServiceNoticeQueryRepositoryTest.kt` |
| entity 회귀 | 신규 `src/test/kotlin/kr/co/vividnext/sodalive/notice/ServiceNoticeTest.kt` |
| 홈 latest 연결 회귀 | 신규 `src/test/kotlin/kr/co/vividnext/sodalive/content/main/tab/home/AudioContentMainTabHomeServiceIntegrationTest.kt`; production linkage는 `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/home/AudioContentMainTabHomeService.kt`의 `noticeService.getLatestNotice()`다. 기존 `api/home/HomeServiceTest.kt`는 다른 서비스를 검사하므로 수정하지 않는다. |
## Review Focus
- 경계와 role 격리: 예약 Nov 1, fixed now Oct 30; 익명·일반·ADMIN의 public endpoints 모두 미공개 제외, boundary exact instant 포함 (`LatestNoticeControllerIntegrationTest`).
- 제한 적용 순서와 동률: eligible 4건 뒤 더 최신 id의 미공개 예약들을 추가해도 top 3가 유지되고, 같은 publishAt이면 id DESC (`ServiceNoticeQueryRepositoryTest`).
- 시간 캡처와 날짜 분리: count/list가 nowProvider를 한 번 호출; scheduled→immediate가 KST 자정을 넘어도 date는 original createdAt, 정렬은 conversion instant (`ServiceNoticeQueryRepositoryTest`, `AdminNoticeControllerIntegrationTest`).
- 기존 소비자 연결: v1 object/null과 홈 `latestNotice`가 같은 filtered `getLatestNotice()`를 사용하고 기존 full-field assertion 유지 (`LatestNoticeControllerIntegrationTest`, `AudioContentMainTabHomeServiceIntegrationTest`).
- 경계 입력/DB 정밀도/동시 수정: non-string/non-null publishAt 거부, exact DB round-trip nanos 0/123456789/999999999, lock 대기 중 publishAt 경과 시 update 거부, schedule→immediate와 competing re-reserve 결과가 순차화됨 (`AdminNoticeControllerIntegrationTest`).
실제 기존 스키마는 미조회다. `docs/20261030_공지사항예약공개/alter-service-notice-publication.sql`에 사용자 승인된 초 단위 신규 컬럼만 추가한다. 기존 created_at은 변경하지 않는다. 배포 순서는 additive schema 및 연결 UTC 확인 → 공개 query filter가 포함된 새 앱 버전으로 전체 instance 교체 → 운영 조정으로 예약 쓰기/admin 사용 활성화다. 이전 앱 instance가 남아 있는 동안 예약을 쓰면 기존 공개 reader가 이를 노출할 수 있으므로 rollout 순서와 관리자 사용 통제로 쓰기를 막는다.
## 전역 API·데이터 인터페이스
구현 기준은 `prd.md` §7이며 이 계획은 별도 API contract 파일을 만들지 않는다.
- 공개 응답 `NoticeItem(id: Long, title: String, content: String, date: String)` 및 v1 object-or-null, v2 최대 3개 array, 목록의 `totalCount/noticeList` envelope를 보존한다.
- ADMIN `GET /api/v2/admin/notices?page={0-based}&size={pageSize}`는 ADMIN 전용이며 `ApiResponse<{totalCount: Int, noticeList: AdminNoticeItem[]}>`를 반환한다. item 필드: `id`, `title`, `content`, `isActive`, `isScheduled`, `publishAt`, `createdAt`; 시각은 KST `yyyy-MM-dd HH:mm:ss`, `publishAt` nullable.
- `POST /notice`: 기존 `{title,content}` + optional nullable `publishAt`; 생략/null 즉시, 미래 문자열 예약. 기존 생성 ID 응답 보존.
- `PUT /notice`: 기존 `id,title?,content?` + optional nullable `publishAt`; 필드 부재 보존, explicit null 즉시 전환, 미래 시각 재예약. 공개된 공지의 publishAt 변경 거부. 기존 수정 응답 보존.
- 오류는 기존 `SodaException(common.error.invalid_request)`와 `ApiResponse` 처리. 보안 HTTP status는 현재 SecurityConfig/handler를 따르며 통합 테스트로 확인한다.
- 저장 제안: `publishAt: LocalDateTime?` UTC와 `isScheduled: Boolean=false`. 실제 타입·물리 정밀도는 DDL 확인 후 확정한다. 새 `publishAt`의 업무/API 계약은 초 단위이며 즉시 전환 now를 저장 경계에서 한 번만 초 절삭해 엔티티/응답에 같은 값을 사용한다. 물리 컬럼이 `(3)/(6)`이어도 이 새 필드의 나노초는 0을 유지한다. 기존 `createdAt`은 절삭하지 않는다. 예약의 미래 여부와 공개 경계 판정에는 캡처한 원본 UTC now를 사용한다.
- 공개 repository 계약은 `getNoticeTotalCount(now: LocalDateTime): Int`, `getNoticeList(pageable: Pageable, now: LocalDateTime): List<NoticeItem>`, `getLatestNotice(now: LocalDateTime): NoticeItem?`다. `ServiceNoticeService.getNoticeList(pageable, timezone)` 및 `getLatestNotice()` 외부 진입 시그니처는 유지하고 각 메서드에서 now를 한 번 캡처한다. count/list는 같은 캡처값을 전달한다. v2 `LatestNoticeService.getLatestNotices()`도 내부 nowProvider로 한 번 캡처해 repo에 전달한다.
- 공개 조건은 `isActive AND (publishAt IS NULL OR publishAt <= now)`, 순서는 `COALESCE(publishAt, createdAt) DESC, id DESC`. 표시 날짜 source는 scheduled일 때 `publishAt`, 그 외 `createdAt`다.
- `ServiceServiceNoticeRepository`에 `@Lock(LockModeType.PESSIMISTIC_WRITE) @Query("select notice from ServiceNotice notice where notice.id = :id") fun findByIdForUpdate(@Param("id") id: Long): ServiceNotice?`를 추가한다. `ServiceNoticeService.update(request: UpdateNoticeRequest, publishAtPresent: Boolean = false)`는 transaction에서 이 lock으로 row를 읽고 난 뒤 now를 캡처해 검사한다. 공개된 공지에 명시된 publishAt 변경은 거부한다. 동시 요청의 선형화 지점은 잠금 후 eligibility 검사이며 시간 경계가 이후 통과하는 것은 query-time 공개 정책에 맡긴다.
- `AdminNoticeItem` projection은 `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/admin/notice/dto/AdminNoticeItem.kt` 한 곳에 두고, repository admin methods는 `getAdminNoticeTotalCount(): Int`, `getAdminNoticeList(pageable: Pageable): List<AdminNoticeItem>`다. `AdminNoticeService.getNoticeList(pageable: Pageable): AdminNoticeResponse`와 ADMIN controller output은 이 응답 타입을 사용한다. 별도 중복 projection은 만들지 않는다.
## Phase 1: schema 확인 및 예약 쓰기
**Phase 결과:** 안전한 저장 정밀도를 확인하고 생성·예약 변경·즉시 전환이 잘못된 공개 상태를 만들지 않는다.
**선행조건:** 없음. P1-T1 차단 해제 전 구현 Task를 시작하지 않는다.
**Phase 완료 조건:** `P1-T1`~`P1-T3`와 `P1-GATE` 완료.
- [x] **Task 1.1: 사용자 UTC·신규 컬럼 계약 확인 (`P1-T1`)**
- [x] **Task 1.2: 모델·생성·시각 검증 (`P1-T2`)**
- [x] **Task 1.3: 수정과 경합 방지 (`P1-T3`)**
- [x] **Phase 1 Gate (`P1-GATE`)**
### Task 1.1 운영 schema와 시간 계약 확인
**Goal 실행 `P1-T1`:** 사용자 확인을 근거로 서버·DB UTC와 신규 컬럼 초 정밀도를 확정한다. 기존의 운영 DDL 선행 조건은 NS-D5로 정정됐다.
- **시작 조건:** 사용자 후속 승인 및 PRD NS-D5.
- **완료 증거:** 사용자 서버 UTC·DB UTC 확인, 새 publish_at 초 단위 TIMESTAMP 승인과 기존 created_at 미변경 결정 기록.
- **범위 밖:** 운영 DB 접속/변경, 기존 물리 컬럼 정의를 확인한 것으로 주장하기.
- **Files:** 확인 `src/main/kotlin/kr/co/vividnext/sodalive/notice/ServiceNotice.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/common/BaseEntity.kt`; 기록은 이 문서와 PRD NS-D5.
- **Interfaces:** 신규 MySQL `publish_at TIMESTAMP NULL DEFAULT NULL`, H2 검증 `TIMESTAMP(0)`; 기존 created_at 미변경. `is_scheduled BOOLEAN NOT NULL DEFAULT FALSE`, 두 컬럼 COMMENT 및 기존 NULL/FALSE 유지.
- **TDD 예외 사유:** 사용자 확인과 계약 결정 기록이며 동작 코드 변경이 아니다.
- **대체 검증 방법:** 엔티티·상속 시각 필드 재확인 및 사용자 승인 내용 대조.
- [x] 서버·DB UTC 사용자 확인을 기록했다.
- [x] 신규 publish_at은 초 정밀도, 기존 created_at은 변경하지 않기로 확정했다.
- [x] 운영 연결 설정 실확인과 DDL 적용은 배포 전 확인으로 분리했다.
### Task 1.2 모델·생성·시각 검증
**Goal 실행 `P1-T2`:** schema gate 결과에 맞춘 SQL/entity 상태 모델로 즉시 생성과 미래 예약을 정확히 저장한다.
- **시작 조건:** `P1-T1` 완료 및 정밀도/timezone 계약 기록.
- **완료 증거:** 생성 API에서 생략/null 즉시, 미래 KST 예약 UTC 저장, 과거/현재·strict format 오류, entity 상태, actual DB flush/clear/reload 정밀도 검증 통과.
- **범위 밖:** 수정·관리자 목록·공개 필터.
- **Files:** Create `docs/20261030_공지사항예약공개/alter-service-notice-publication.sql`; Modify `src/main/kotlin/kr/co/vividnext/sodalive/notice/ServiceNotice.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/notice/ServiceNoticeController.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/notice/CreateNoticeRequest.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/notice/ServiceNoticeService.kt`; Create/Test `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/admin/notice/AdminNoticeControllerIntegrationTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/notice/ServiceNoticeTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/notice/ServiceNoticeQueryRepositoryTest.kt`. Entity 기본값은 unit test, 실제 DB 왕복은 repository test가 담당한다.
- **Interfaces:** Consumes: `P1-T1` 정밀도 계약. Create controller signature `createNotice(@RequestBody fields: JsonNode)` accepts object with optional `publishAt` string/null only, maps to existing `CreateNoticeRequest`, then calls existing `service.save(request)`. Produces: `publishAt` nullable UTC, `isScheduled` default false; creation is scheduled=false & publishAt null or scheduled=true & validated future UTC.
- **TDD:**
- [x] **RED:** entity test에서 기본값 `isScheduled=false,publishAt=null` assertion 및 HTTP create assertion 작성. publishAt 미입력/null은 즉시; 미래 KST `2026-11-01 09:00:00`은 UTC `2026-11-01T00:00:00`; 과거/현재·strict invalid calendar·non-string/non-null JSON은 `common.error.invalid_request` assertion.
- [x] **RED 확인:** `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.admin.notice.AdminNoticeControllerIntegrationTest' --tests 'kr.co.vividnext.sodalive.notice.ServiceNoticeTest' --tests 'kr.co.vividnext.sodalive.notice.ServiceNoticeQueryRepositoryTest'`에서 미구현 assertion 실패 확인.
- [x] **GREEN:** SQL에 초 단위 `publish_at TIMESTAMP NULL DEFAULT NULL COMMENT '예약 공개 시각(UTC)'` 및 `is_scheduled BOOLEAN NOT NULL DEFAULT FALSE COMMENT '예약 공개 여부'`를 추가한다. 기존 row는 `publish_at=NULL,is_scheduled=FALSE`로 유지하고 backfill 금지. Create JSON object boundary도 `ServiceNoticeController`에서 `publishAt` string/null만 허용하고 `ObjectMapper`로 `CreateNoticeRequest` 변환 후 service 호출하도록 한다. 이어서 최소 entity·validation 구현. Parser pattern은 `uuuu-MM-dd HH:mm:ss` + `ResolverStyle.STRICT`, wire 표기는 `yyyy-MM-dd HH:mm:ss`; `nowProvider`는 SubBannerService 패턴으로 필요한 service에만 주입.
- [x] **GREEN 확인:** `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.admin.notice.AdminNoticeControllerIntegrationTest' --tests 'kr.co.vividnext.sodalive.notice.ServiceNoticeTest' --tests 'kr.co.vividnext.sodalive.notice.ServiceNoticeQueryRepositoryTest'` 통과. `ServiceNoticeQueryRepositoryTest.shouldPersistAndReloadScheduledPublishAt`는 KST `2026-11-01 09:00:00` 예약을 실제 DB flush/clear/reload한 값이 UTC `2026-11-01T00:00:00`과 정확히 같음을 검증한다. 나노초 now 입력의 즉시 전환 검증은 해당 기능을 만드는 P1-T3가 소유한다.
- [x] **REFACTOR:** 이번 Task 중복만 정리하고 같은 focused test, 직접 영향 notice regression, ktlint 결과 기록.
- [x] **SQL metadata check:** SQL은 `ALTER TABLE service_notice`에 nullable `publish_at`과 `is_scheduled NOT NULL DEFAULT FALSE`를 추가하고 두 컬럼에 COMMENT를 포함해야 한다. 기존 rows는 NULL/FALSE 유지, backfill 및 live 실행은 없어야 한다. SQL 정밀도는 P1-T1 evidence와 일치해야 한다.
### Task 1.3 수정과 경합 방지
**Goal 실행 `P1-T3`:** 예약 미공개 공지의 시각 변경과 즉시 전환을 지원하며 공개된 공지를 다시 감추지 못하게 한다.
- **실행 보완:** 기존 delete도 같은 `findByIdForUpdate`로 읽는다. 삭제/예약 변경이 같은 엔티티를 오래된 값으로 flush하여 다른 필드를 덮거나 삭제를 되돌리는 경합을 막기 위한 최소 변경이며, 기존 삭제 API·응답·soft delete 정책은 유지한다. 삭제와 즉시 공개/재예약 경합의 최종 `isActive=false` 및 최신 예약 필드 보존을 테스트한다.
- **시작 조건:** `P1-T2` 완료 및 생성 contract 확정.
- **완료 증거:** update 생략/명시 null/future 및 title/content 기존 규칙, schedule-only update, 공개 경계 거부, 동시 공개 race 보호 테스트 통과.
- **범위 밖:** 제목/본문 정책 변경, 복원, 사용자 제공 시각을 기준으로 권한 판정.
- **Files:** Modify `src/main/kotlin/kr/co/vividnext/sodalive/notice/ServiceNoticeController.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/notice/UpdateNoticeRequest.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/notice/ServiceNoticeService.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/notice/ServiceServiceNoticeRepository.kt`; Test `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/admin/notice/AdminNoticeControllerIntegrationTest.kt`, 신규 `src/test/kotlin/kr/co/vividnext/sodalive/notice/ServiceNoticeConcurrencyIntegrationTest.kt`. HTTP와 DB 정밀도는 전자, 독립 transaction의 결정적 row-lock 경합은 후자가 담당한다.
- **Interfaces:** Consumes: P1-T2 create model. Controller signature `updateNotice(@RequestBody fields: JsonNode)` checks `fields.isObject` and if present accepts `publishAt` only when `isTextual || isNull`; maps `objectMapper.treeToValue(fields, UpdateNoticeRequest::class.java)` then calls `service.update(request, publishAtPresent = fields.has("publishAt"))`. Service signature `update(request: UpdateNoticeRequest, publishAtPresent: Boolean = false)` retains existing callers. Produces: repository `findByIdForUpdate(id: Long): ServiceNotice?` with `@Lock(PESSIMISTIC_WRITE)`; locked/rechecked update, reservation-only time edits, immediate conversion `publishAt=serverNow,isScheduled=false`.
- **TDD:**
- [x] **RED:** update HTTP tests pin `shouldPreserveScheduleWhenPublishAtIsOmitted`, `shouldConvertScheduledNoticeToImmediateWhenPublishAtIsNull`, `shouldRescheduleUnpublishedNotice`, `shouldAllowScheduleOnlyUpdate`, `shouldRejectRescheduleAfterPublishBoundary`, `shouldRejectInvalidUpdatePublishAtWithoutPartialChanges`, and title/content-only behavior. Existing blank/null validation expectations stay unchanged. `shouldRejectUpdateWhenLockWaitCrossesPublishAt` and competing `shouldSerializeImmediateConversionAndReschedule` exercise lock scheduling. 즉시 전환 now에 nanos 0/123456789/999999999와 UTC 23:59:59 경계를 주입하고 DB flush/clear/reload한 publishAt의 나노초가 0이며 다음 초·날짜로 반올림되지 않는지 검증한다. 저장값을 assertion에서 다시 절삭해 비교하지 않는다.
- [x] **RED 확인:** `./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.v2.api.admin.notice.AdminNoticeControllerIntegrationTest'` exit 1, 80개 중 41개 assertion 실패. 상태 전이 최소 구현 뒤 이 class와 `--tests 'kr.co.vividnext.sodalive.notice.ServiceNoticeConcurrencyIntegrationTest'` 실행에서 HTTP 80개 통과, 잠금 부재로 동시성 9개 실패를 확인했다. compiler 오류를 RED로 계산하지 않았다.
- [x] **GREEN:** transaction 안에서 `findByIdForUpdate(id)` row lock을 수정 필드 변경 전에 얻고 fresh now를 잠금 뒤 한 번 캡처해 active·미공개 예약 eligibility를 재검사한다. 원본 now로 미래 여부를 비교하고 즉시 전환 저장값만 `now.truncatedTo(SECONDS)`로 만든다. title/content-only update와 delete도 같은 lock을 쓴다.
- [x] **GREEN 확인:** `./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.notice.ServiceNoticeConcurrencyIntegrationTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.notice.AdminNoticeControllerIntegrationTest'` exit 0, 89개 통과. H2 `INFORMATION_SCHEMA.SESSIONS.BLOCKER_ID`와 실행 중 SELECT FOR UPDATE를 확인한 뒤 old `publishAt` 경계로 now를 옮겨 거부됨을 검증했다. 즉시 전환→재예약, 제목↔재예약, 삭제↔즉시 전환/재예약 경합의 최종 DB를 재조회했다. 선형화는 lock 이후 eligibility check이며 wall-clock boundary 통과를 차단한다고 주장하지 않는다.
- [x] **REFACTOR:** 추가한 테스트의 출력 포맷만 정리한 뒤 아래 Phase 1 명령으로 직접 영향 notice 5개 class 104개 및 ktlintCheck 통과. 기존 테스트 삭제·완화·skip은 없다.
#### Phase 1 Gate
**Goal 실행 `P1-GATE`:** 시간 저장 계약, 생성·수정 상태 전이를 판정한다.
- **시작 조건:** 모든 Phase 1 task 완료, schema gate 근거 포함.
- **완료 증거:** P1 focused tests와 정밀도 대조표 통과, Progress에 실행 결과 및 차단 여부 기록.
- **범위 밖:** schema 확인 없이 구현 진행 또는 실패 test 완화.
- **TDD 예외 사유:** 통합 검증 gate이며 자체 production 기능을 추가하지 않는다.
- **대체 검증 방법:** 해당 focused test 명령과 저장소 문서/DDL 대조표 확인.
- [x] `./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.notice.ServiceNoticeConcurrencyIntegrationTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.notice.AdminNoticeControllerIntegrationTest' --tests 'kr.co.vividnext.sodalive.notice.ServiceNoticeQueryRepositoryTest' --tests 'kr.co.vividnext.sodalive.notice.ServiceNoticeTest' --tests 'kr.co.vividnext.sodalive.v2.api.notice.LatestNoticeControllerIntegrationTest' ktlintCheck` exit 0, 104개 통과.
- [x] 사용자 승인 신규 MySQL TIMESTAMP 초 단위 계약과 H2 fixture TIMESTAMP(0)이 일치하고 exact DB 왕복 입력 nanos 0/123456789/999999999 및 UTC 23:59:59 결과를 Progress와 stage report에 기록했다. 기존 created_at의 물리 정밀도를 추정·변경하지 않았다.
- [x] 실제 JWT/HTTP에서 익명 write 401, 일반 회원의 기존 HTTP 200 권한 오류, ADMIN 생성 ID 및 PUT/DELETE `data={}` 응답과 soft delete를 보존했다.
- **후속 검증 대기:** 관리자 GET 응답의 publishAt을 KST→UTC 복원하여 DB와 비교하는 검증은 P2 endpoint 구현 후 수행한다. 이 단계의 DB 왕복 통과를 응답 시각 비교 통과로 대체하지 않는다. 상단 전체 Phase 상태와 Gate 완료 판정은 본 단계에서 변경하지 않는다.
## Phase 2: 공개 조회와 관리자 목록
**Phase 결과:** 공개 query는 예약 미공개를 역할 관계없이 차단하고 ADMIN의 별도 목록은 활성 예약을 모두 보여 준다.
**선행조건:** `P1-GATE` 완료, 외부 schema gate 충족.
- [x] **Task 2.1: 공유 query, 관리자 endpoint, 공개 HTTP 회귀 (`P2-T1`)**
- [x] **Phase 2 Gate (`P2-GATE`)**
### Task 2.1 공유 query, 관리자 endpoint, 공개 HTTP 회귀
**Goal 실행 `P2-T1`:** 모든 notice 조회가 승인된 가시성·정렬·날짜 정책을 따르고 ADMIN 목록은 예약을 포함한다.
- **시작 조건:** `P1-GATE` 완료, PRD §7 계약 확인.
- **완료 증거:** 공개 count/list/v1 latest/v2 latest와 관리자 페이지의 query/HTTP assertion 통과, auth matrix 확인.
- **범위 밖:** UI, 공개 역할 우회, 추가 검색/filter, 스케줄러.
- **Files:** Modify `src/main/kotlin/kr/co/vividnext/sodalive/notice/ServiceServiceNoticeRepository.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/notice/ServiceNoticeService.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/notice/application/LatestNoticeService.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/configs/SecurityConfig.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/notice/LatestNoticeControllerIntegrationTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/admin/notice/AdminNoticeControllerIntegrationTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/notice/ServiceNoticeQueryRepositoryTest.kt`; Create `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/admin/notice/dto/AdminNoticeItem.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/admin/notice/adapter/in/web/AdminNoticeController.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/admin/notice/application/AdminNoticeService.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/admin/notice/dto/AdminNoticeResponse.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/content/main/tab/home/AudioContentMainTabHomeServiceIntegrationTest.kt`.
- **Interfaces:** Consumes: P1 model/write contract. Preserve `ServiceNoticeService.getNoticeList(pageable: Pageable, timezone: String)` and `getLatestNotice()` public signatures. Repository methods: `getNoticeTotalCount(now: LocalDateTime): Int`, `getNoticeList(pageable: Pageable, now: LocalDateTime): List<NoticeItem>`, `getLatestNotice(now: LocalDateTime): NoticeItem?`; admin methods `getAdminNoticeTotalCount(): Int`, `getAdminNoticeList(pageable: Pageable): List<AdminNoticeItem>`. Each public service captures now once; list and count receive same now. `AdminNoticeController.getNotices(pageable: Pageable): ApiResponse<AdminNoticeResponse>` delegates to `AdminNoticeService.getNoticeList(pageable): AdminNoticeResponse`, whose exact output is `{totalCount: Int, noticeList: List<AdminNoticeItem>}`.
- **TDD:**
- [x] **RED:** repository/HTTP tests pin named cases: `shouldExcludeScheduledNoticeBeforeBoundaryForAdminOnPublicRoutes` uses Nov 1 scheduled + fixed Oct 30 now for anonymous, member, ADMIN; `shouldIncludeNoticeAtExactPublishBoundary`; `shouldApplyPublicFilterBeforeLatestLimit` adds newer unpublished ids beyond 3 eligible items and still expects eligible top 3; `shouldOrderEqualPublishTimesByIdDescending` uses two distinct rows with equal `publishAt`; `shouldCaptureNowOnceForCountAndList` expects provider call count 1 and identical now arguments; `shouldUseRegistrationDateButConversionTimeForImmediateScheduleConversion` has registration Oct 31 23:50 KST, conversion Nov 1 00:10 KST, competitor effective time Nov 1 00:05 KST, and expects conversion notice first in order but its displayed date `2026-10-31`. Assert v1 latest object/null and preserve every full-field assertion. Admin HTTP verifies active schedule inclusion/inactive exclusion. Rewrite existing id-only order fixtures while retaining all full-field/auth/format assertions.
- [x] **RED 확인:** `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.notice.LatestNoticeControllerIntegrationTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.notice.AdminNoticeControllerIntegrationTest' --tests 'kr.co.vividnext.sodalive.notice.ServiceNoticeQueryRepositoryTest' --tests 'kr.co.vividnext.sodalive.content.main.tab.home.AudioContentMainTabHomeServiceIntegrationTest'`에서 요구 동작 부재로 실패 확인.
- [x] **GREEN:** count/list/latest에 동일 가시성 predicate, effective time/id ordering, 표시 날짜 source 적용. `ServiceNoticeService` public methods preserve signatures and capture now once; v2 latest captures once and passes to repository. Admin projection uses the exact `AdminNoticeItem.kt` path above. Add separate ADMIN-only route authorization without role-dependent public visibility.
- [x] **GREEN 확인:** `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.notice.LatestNoticeControllerIntegrationTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.notice.AdminNoticeControllerIntegrationTest' --tests 'kr.co.vividnext.sodalive.notice.ServiceNoticeQueryRepositoryTest' --tests 'kr.co.vividnext.sodalive.content.main.tab.home.AudioContentMainTabHomeServiceIntegrationTest'` 통과. 익명/비관리자/ADMIN으로 API를 호출해 익명 정상 공개 조회, 모든 역할에서 예약 비공개, ADMIN 목록만 예약 포함을 확인. P1-T3의 세 나노초 입력으로 생성한 즉시 전환 DB publishAt과 관리자 GET의 publishAt을 KST에서 UTC로 복원한 값을 정확히 비교한다.
- [x] **REFACTOR:** 새 코드에서 생긴 중복만 정리하고 위 네 focused test, ktlintCheck 및 영향 범위 notice regression 결과 기록.
- [x] **Compatibility check:** `AudioContentMainTabHomeService.fetchData` at `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/home/AudioContentMainTabHomeService.kt` already calls `ServiceNoticeService.getLatestNotice()`. Keep that entrypoint filtered; verify `AudioContentMainTabHomeServiceIntegrationTest` asserts `latestNotice` uses expected visible item and excludes an unpublished scheduled notice. Preserve `/notice/latest` object/null and current complete response fields.
- [x] **Admin timestamp display check:** `createdAt` is formatted in KST `yyyy-MM-dd HH:mm:ss` for output only. Preserve the source DB value/precision; do not change existing `created_at` DDL or truncate stored values to seconds.
- **실행 증거:** 아래 Progress의 P2 실행 기록 및 소유 임시 루트 `stage-report.md`에 실제 명령·exit·HTTP·DB 결과를 기록했다. SecurityConfig 수정 없이 기존 authenticated 정책과 새 controller의 ADMIN method guard를 사용했다.
#### Phase 2 Gate
**Goal 실행 `P2-GATE`:** 공개 query와 ADMIN 조회가 서버 API 표면에서 계약대로 동작하는지 판정한다.
- **시작 조건:** `P2-T1` 완료.
- **완료 증거:** 최신 full-field HTTP, auth, 페이지네이션 전 filter, 정렬/표시 날짜 확인.
- **범위 밖:** frontend 및 운영배포/실 DB 수행.
- **TDD 예외 사유:** 구현 Task 결과 종합 확인.
- **대체 검증 방법:** 아래 HTTP 시나리오의 실제 응답 상태/envelope와 focused integration 결과를 기록한다.
- [x] `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.notice.LatestNoticeControllerIntegrationTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.notice.AdminNoticeControllerIntegrationTest' --tests 'kr.co.vividnext.sodalive.notice.ServiceNoticeQueryRepositoryTest' --tests 'kr.co.vividnext.sodalive.content.main.tab.home.AudioContentMainTabHomeServiceIntegrationTest'` 성공.
- [x] 실행 서버에서 anonymous `GET /api/v2/notices/latest`, non-admin/anonymous `GET /api/v2/admin/notices?page=0&size=20`, ADMIN 같은 관리자 GET의 실제 status와 ApiResponse/data fields 기록.
- [x] ADMIN 토큰을 붙인 `GET /notice`, `/notice/latest`, `/api/v2/notices/latest` 모두 boundary 이전 예약 공지를 제외하고 관리자 GET만 이를 반환함을 확인.
## Phase 3: 회귀와 최종 증거
**Phase 결과:** 예약 공개 변경이 기존 notice contract를 유지하고 완료 여부가 검증 기록과 함께 판정된다. 이 phase는 `P3-GATE` 하나뿐이며 별도 Task goal은 없다.
**선행조건:** `P2-GATE` 완료.
- [ ] **Phase 3 Gate (`P3-GATE`)**
**Goal 실행 `P3-GATE`:** 기존 public/admin notice 동작의 영향 범위를 검증하고 남은 schema/배포 의존성을 분명히 한다.
- **시작 조건:** Phase 1~2 완료 및 focused HTTP 검증 통과.
- **완료 증거:** 선택된 package regression, `ktlintCheck`, conditional full regression 결과와 미실행 근거를 기록. DB 운영 확인 및 수동 migration/rollout은 별도 승인·절차가 완료되기 전 미완료로 남긴다.
- **범위 밖:** unrelated test 수정, 운영 migration 실행, 배포 선언.
- **Files:** Verify only `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/notice/LatestNoticeControllerIntegrationTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/admin/notice/AdminNoticeControllerIntegrationTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/notice/ServiceNoticeQueryRepositoryTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/notice/ServiceNoticeTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/content/main/tab/home/AudioContentMainTabHomeServiceIntegrationTest.kt`; 변경 필요한 실패가 생기면 이 gate에서 범위를 넓히지 않고 새 regression task를 추가.
- **Interfaces:** Consumes: P1/P2 API와 data contract. Produces: 검증 결과/미확인 목록이며 API 계약 변경 없음.
- **TDD 예외 사유:** release-level 검증 gate이며 별도 기능 구현 없음.
- **대체 검증 방법:** focused commands, 직접 영향 notice package 회귀, lint, 실제 HTTP role matrix. 전체 test는 아래 조건에서만 실행한다.
- [x] 실제 실행: `./gradlew --offline --no-daemon test --tests 'kr.co.vividnext.sodalive.notice.*' --tests 'kr.co.vividnext.sodalive.v2.api.notice.*' --tests 'kr.co.vividnext.sodalive.v2.api.admin.notice.*' --tests 'kr.co.vividnext.sodalive.content.main.tab.home.AudioContentMainTabHomeServiceIntegrationTest' ktlintCheck bootJar --continue` exit 0, 4분 9초, 122개 통과.
- [x] 직접 영향 notice/home regression, `ktlintCheck`, `bootJar` 성공. `build/libs/sodalive-0.0.1-SNAPSHOT.jar` 생성 확인.
- [ ] 사용자 ULW 전체 suite 검증 요청에 따라 `./gradlew --offline --no-daemon test ktlintCheck bootJar --continue`를 실행했으나 test 단계 20분 timeout으로 미완료다. 전체 test 성공으로 표시하지 않는다. 장시간 정체 원인은 미확인이고 관련 코드 수정이나 test skip 없이 후속 확인 대상으로 남긴다.
- [x] 기존 v1 object/null, v2 최대 3개 array, 목록 응답 shape, create ID 및 update/delete 기존 success response assertion 유지 확인.
- [x] 독립 최종 리뷰 APPROVED. 요구사항을 위반하는 구체적 결함이 없다고 판정했으며 전체 suite 미완료와 운영 DB 미검증은 별도로 남겼다.
## 실행 순서
| 순서 | Goal | 선행조건 | 상태/차단 시 행동 |
|---:|---|---|---|
| 1 | `P1-T1` | 없음 | schema 근거 없음이면 외부 조건 대기, 코드 구현 금지 |
| 2 | `P1-T2` | `P1-T1` | 저장 precision과 시간 contract 고정 |
| 3 | `P1-T3` | `P1-T2` | 상태 전이 및 race guard |
| 4 | `P1-GATE` | Phase 1 tasks | 실패 task로 회귀 추가 |
| 5 | `P2-T1` | `P1-GATE` | 공개/Admin query와 API 구현 |
| 6 | `P2-GATE` | `P2-T1` | 실제 HTTP auth matrix 수행 |
| 7 | `P3-GATE` | `P2-GATE` | 관련 test/lint 및 조건부 full regression 기록 |
## 변경 금지 및 중단 규칙
- 승인되지 않은 역할·UI·scheduler·복원·bulk 기능을 추가하지 않는다. 공개 API는 role-aware visibility bypass를 두지 않는다.
- 기존 ID-only test 기대는 승인된 새 공개 순서에 맞춰 fixture를 수정하되 response, 날짜 format, 권한 assertion은 지우거나 완화하지 않는다.
- 신규 TIMESTAMP 초 정밀도와 서버·DB UTC는 NS-D5 승인값을 사용한다. 기존 created_at 및 BaseEntity는 변경하지 않는다. 운영 직접 확인은 수행했다고 주장하지 않는다.
- 공통 security/error handling을 변경할 필요가 생기면 먼저 계획을 갱신하고 실제 기존 동작과 요구를 재검토한다.
- 검증 실패는 원인 test를 삭제/skip/허용오차로 감추지 않는다. scope 밖 issue는 기록만 한다.
- 커밋은 필수 단계가 아니며, 본 요청은 커밋을 승인하지 않는다.
## Progress
현재 문서 작성 시점에는 향후 구현을 실행하지 않았다. 각 Goal 완료 후 실제 실행 명령, 핵심 결과, 다음 행동을 아래에 누적한다. 미실행 검증을 성공으로 표시하지 않는다.
### P1-T1 1차 실행: 2026-10-30
- 상태: **blocked**, 운영 스키마·배포 시간대 자료 대기. 체크박스는 완료 처리하지 않는다.
- 무엇을: 구현 승인 후 저장소 SQL/DDL·관련 문서·시각 처리 코드와 설정의 비민감 항목을 재확인했다. 실제 `service_notice` 정의는 발견하지 못했다.
- 근거: `src/main/resources/application.yml:126`은 `ddl-auto: validate`이며, `src/main/kotlin/kr/co/vividnext/sodalive/common/BaseEntity.kt:31`은 `LocalDateTime.now()`로 등록 시각을 설정한다. 이 정보는 운영 `created_at` 타입·소수초 정밀도 또는 운영 JVM/JDBC/DB 시간대를 증명하지 않는다.
- 확인 방법: 저장소 SQL/DDL 후보와 `service_notice` 정의 검색, `serverTimezone`, `connectionTimeZone`, `hibernate.jdbc.time_zone`, `user.timezone`, `TimeZone.setDefault` 설정 검색. 운영 DB·네트워크에는 접속하지 않았다. 비밀값은 기록하지 않는다.
- 재개 조건·담당: 운영 DB/배포 담당자가 `SHOW CREATE TABLE service_notice` 결과, 같은 환경의 DB 세션/전역 시간대 및 운영 JVM/JDBC 시간대 설정을 제공하면 확인 결과를 기록하고 P1-T1을 재판정한다. JDBC URL 전체나 자격증명 대신 시간대 옵션만 받는다.
- 미실행: P1-T2 이후 소스·SQL·테스트 구현과 Gradle·HTTP 검증. 선행 근거 없이 스키마를 추정하지 않는 승인 계획을 따른다.
### P1-T2 실행: 2026-10-30
- 상태: **P1-T2 완료**. 생성·모델·additive SQL만 구현했다. P1-T3, 모든 Gate, 관리자 목록과 공개 query는 변경하거나 완료 처리하지 않았다.
- 증거 루트: `/var/folders/yh/8xsbvpsj5wg2qnxzxdp11_gm0000gn/T/opencode/notice-p1t2.lPSBOW`. 상세 명령·파일 목록은 `stage-report.md`, 실행 로그와 JUnit XML은 같은 디렉터리에 보관한다.
- 기준 검증: 운영 코드 변경 전 `./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.v2.api.notice.LatestNoticeControllerIntegrationTest'` exit 0, 11개 통과 (`baseline.log`, `baseline-latest.xml`). 기존 테스트 assertion은 수정하지 않았다.
- RED: 신규 실제 JWT/HTTP 테스트 단독 실행 exit 1, 29개 중 27개 assertion 실패. `publishAt=42`가 HTTP 200 success=true와 생성 ID로 수락됐다 (`red-http.log`, `red-http.xml`). 컴파일 가능한 모델/DTO 필드와 typed assertion 추가 뒤 본 Task의 세 focused class 실행 exit 1, 38개 중 32개 assertion 실패. 예약 DB flush/clear/reload가 기대 UTC 대신 null, HTTP 예약 상태가 true 대신 false였다 (`red-focused.log`, `red-focused-db.xml`, `red-focused-http.xml`). 컴파일 오류를 RED로 계산하지 않았다. entity 기본값은 이 구조 단계에서 통과했다.
- GREEN: `./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.v2.api.admin.notice.AdminNoticeControllerIntegrationTest' --tests 'kr.co.vividnext.sodalive.notice.ServiceNoticeTest' --tests 'kr.co.vividnext.sodalive.notice.ServiceNoticeQueryRepositoryTest'` exit 0, 39개 통과 (`green-focused-retry.log`, `green-focused-*.xml`). 첫 GREEN 시도는 도구 120초 제한으로 중단됐으며 성공으로 계산하지 않았다. 해당 프로세스 종료를 확인한 뒤 PID·log·exit 파일을 남기는 소유 runner로 재실행했다.
- 실제 경계: 생략/null 즉시 생성과 생성 ID/envelope, 엄격한 KST 형식·달력·현재/과거·JSON 타입 거부, MySQL 상한 KST `2038-01-19 12:14:07` 수락 및 다음 초 거부, 익명 HTTP 401와 비ADMIN의 기존 HTTP 200 권한 오류, 제목/본문 공백 오류를 확인했다. `TIMESTAMP(0)`을 명시한 H2에서 KST `2026-11-01 09:00:00` 생성값을 flush/clear/reload하여 UTC `2026-11-01T00:00:00`, nano=0과 정확히 비교했다.
- SQL: 작성한 MySQL additive SQL을 로컬 H2 MySQL mode에 실제 실행하여 기존 row의 NULL/FALSE, 두 컬럼 COMMENT·nullability, is_scheduled NOT NULL 및 기존 created_at 소수초 보존을 확인했다. H2 기본 TIMESTAMP 정밀도를 MySQL과 같다고 주장하지 않으며 생성 저장 fixture는 별도로 TIMESTAMP(0)에 고정했다. 운영 DB 접속·SQL 실행·backfill은 하지 않았다.
- 최종 회귀: `./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.notice.*' --tests 'kr.co.vividnext.sodalive.v2.api.notice.*' --tests 'kr.co.vividnext.sodalive.v2.api.admin.notice.AdminNoticeControllerIntegrationTest' ktlintCheck` exit 0, 총 50개 통과(HTTP 35, DB 3, entity 1, 기존 latest HTTP 11), failure/error/skip 모두 0 (`final-regression.log`, `final-{http,db,entity,latest}.xml`). Kotlin 컴파일 및 ktlintCheck 통과, `git diff --check` 공백 오류 없음.
- 미실행: LSP 도구가 없어 compiler/lint로 대체했다. 단일 notice 생성 단계이며 공통 보안·오류·설정 변경이 없어 전체 test/build와 release 감사는 실행하지 않았다. 시간대는 사용자 UTC 확인을 전제로 했으며 운영 연결 실확인·배포는 제외했다. 공개 필터 전 단계이므로 현재 산출물만으로 운영 예약 쓰기를 활성화하면 안 된다.
### P1-T3 실행 및 Phase 1 검증 증거: 2026-10-30
- 상태: **P1-T3 완료**, Phase 1 검증 항목 충족. 공개 query·관리자 GET·client-prompt.md는 변경하지 않았고 전체 Phase 상태/다음 Goal 전환은 별도 판정으로 남겼다.
- 기준선: 부모 실행에서 기존 notice 4개 class 50개 통과 및 생성 단계 리뷰 승인을 확인한 채 재개했다. P1-T2 RED는 반복하지 않았다.
- 증거 루트: `/var/folders/yh/8xsbvpsj5wg2qnxzxdp11_gm0000gn/T/opencode/notice-p1t3.FfcAgS`. `stage-report.md`에 변경 파일·명령·실제 HTTP 발췌·DB 정밀도 대조표·경합 결과를 기록했다. 각 phase의 `.command.json`, `.runner.pid`, `.gradle.pid`, `.log`, `.exit.json` 및 notice JUnit XML을 보존했다. TMPDIR와 Node/Bun cache 경로를 이 루트로 격리한 단일 detached Gradle을 순차 실행했다.
- HTTP RED: `red-http` exit 1, 80개 중 41개 assertion 실패. `{"id":22,"title":"반영 금지","content":"반영 금지","publishAt":42}`가 HTTP 200 success=true, `data={}`로 수락됐고 schedule-only/null은 update-required로 거부됐다. 컴파일 오류·timeout을 RED 또는 성공으로 계산하지 않았다.
- 잠금 RED→GREEN: Task 1.3의 두 class 명령으로 `red-lock` exit 1(HTTP 80 통과, 동시성 9 실패) → `green-focused` exit 0(89개 통과). 첫 실패는 SELECT FOR UPDATE 대기 부재 assertion이다. CountDownLatch/TransactionTemplate과 H2 실제 BLOCKER_ID를 사용해 sleep·repository mock 없이 순서를 고정했다. 모든 대기/future를 제한하고 finally에서 barrier/future/executor를 정리했다.
- 실제 HTTP/DB: 미래 KST `2026-11-02 10:00:00` PUT은 HTTP 200 기존 성공 envelope와 UTC `2026-11-02T01:00:00`, isScheduled=true를 저장했다. 명시 null PUT은 HTTP 200 `{"success":true,"message":"수정되었습니다.","data":{},"errorProperty":null}`이고, 잘못된 시각·이미 공개/즉시/비활성 공지의 시각 변경은 기존 HTTP 200 invalid_request envelope다. 잘못된 예약에 동반한 제목·본문은 부분 반영되지 않았다. omitted 시각과 공개 후 title/content-only 수정 및 기존 ID/수정 필드 누락 오류도 보존했다.
- 정밀도 대조: UTC `2026-10-30T00:00:00`과 `2026-10-30T23:59:59` 각각에 nanos `0/123456789/999999999`를 입력했다. TIMESTAMP(0) metadata=0인 DB에서 flush/clear/reload한 결과는 각각 정확히 `2026-10-30T00:00:00`과 `2026-10-30T23:59:59`, nano=0이다. 다음 초·다음 날짜로 반올림하지 않고 original createdAt=`2026-10-29T14:59:59.123456`을 보존했다. P2 관리자 응답 시각과 DB 비교는 **미검증/pending**이다.
- 경합 DB: 대기 중 old publishAt 정각 도달 시 fresh now 검사로 거부, 즉시 전환 선행 후 재예약 거부, 제목/재예약 어느 순서에서도 최신 값 보존, 삭제와 전환/재예약 어느 순서에서도 isActive=false와 마지막 유효 예약 필드를 보존했다. 삭제 후 제목-only 수정도 삭제를 되돌리지 않았다.
- 최종 회귀: Phase 1에 기재한 5개 class + ktlintCheck 명령 `final-regression` exit 0, 111.0초. HTTP 80, 동시성 9, DB 3, entity 1, 기존 latest HTTP 11 = **104개**, failure/error/skip 0. Kotlin compiler와 main/test/script ktlint 통과. LSP 도구는 없어 compiler/lint로 대체했다.
- 미실행/제한: 전체 suite/build와 독립 최종 리뷰는 이 단계 범위 밖으로 남겼다. 운영 DB·외부 서비스 접속, migration, commit/worktree, 전역 인증·오류·timezone/BaseEntity 변경 및 신규 dependency는 없다. 공개 필터가 아직 없으므로 이 산출물만으로 운영 예약 쓰기를 활성화하면 안 된다.
### P2-T1 및 P2-GATE 실행: 2026-10-30
- 상태: **P2-T1/P2-GATE 검증 충족**. 중단된 작업의 기존 테스트·P1 구현을 유지하고 공개 query와 ADMIN GET만 마무리했다. 상단 전체 Phase/활성 Goal 및 P3 판정은 부모 작업이 갱신한다.
- 증거 루트: `/var/folders/yh/8xsbvpsj5wg2qnxzxdp11_gm0000gn/T/opencode/p2-notice.TWFcpR`. `stage-report.md`, `red.log`/`red.exit`, `red-summary.json`, `red-TEST-*.xml`, `green-final.log`/`green-final.exit`, `green-final-summary.json`, `green-final-TEST-*.xml`을 보존했다. 모든 명령에서 TMPDIR 및 Node/Bun cache 경로를 이 소유 루트로 지정했고 Gradle은 순차·offline 실행했다.
- RED: 위 Task 2.1의 4개 class에 `--offline --no-daemon`을 붙여 실행, exit 1. 112개 중 25개 실패이며 공개 count 4→9, now 호출 1→0, 예약 노출·날짜·정렬 및 ADMIN GET 404 등 **24개 assertion 실패**를 확인했다. 나머지 홈 1개는 직접 service 호출의 request-scoped LangContext fixture 오류로 RED 증거에서 제외하고 테스트에 request scope를 설정·finally 정리했다. compiler 오류를 RED로 계산하지 않았다.
- 구현: 공개 predicate를 pagination/limit 전에 적용하고 유효 시각/id 역순과 scheduled 여부별 KST 날짜를 사용한다. public 서비스는 now를 한 번 얻으며 count/list가 공유한다. ADMIN은 별도 active-only projection·read-only service·ADMIN controller로 미래 예약도 조회한다. H2 테스트 formatter에 `%s`→`ss`만 추가했다. 전역 auth/timezone/formatter/기존 created_at은 변경하지 않았다.
- 중간 검증: `green.log` exit 1은 기존 P2 초안의 인자 줄바꿈 ktlint 위반으로 test task 전에 중단됐다. 이를 고친 뒤 재실행했으며 이 중간 실행은 테스트 통과 증거가 아니다.
- GREEN: `./gradlew --offline --no-daemon --continue test --tests 'kr.co.vividnext.sodalive.v2.api.notice.LatestNoticeControllerIntegrationTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.notice.AdminNoticeControllerIntegrationTest' --tests 'kr.co.vividnext.sodalive.notice.ServiceNoticeQueryRepositoryTest' --tests 'kr.co.vividnext.sodalive.content.main.tab.home.AudioContentMainTabHomeServiceIntegrationTest' --tests 'kr.co.vividnext.sodalive.notice.ServiceNoticeConcurrencyIntegrationTest' --tests 'kr.co.vividnext.sodalive.notice.ServiceNoticeTest' ktlintCheck` exit 0, 3분 37초. **122개**(ADMIN/write HTTP 92, latest HTTP 13, query/DB 6, 실제 홈 1, 동시성 9, entity 1), failure/error/skip 0. Kotlin compiler와 main/test/script ktlint 통과. P1 기존 104개를 포함하며 새 full-field assertions를 완화하지 않았다.
- 실제 로컬 HTTP: RANDOM_PORT Tomcat + 실제 JWT·H2·embedded Redis로 검증했다. 익명 latest HTTP 200의 array/object/null, 모든 역할에서 future 제외, ADMIN 목록의 active future 포함·0-based page·빈 페이지·전체 DTO를 확인했다. 관리자 GET은 익명 401, USER HTTP 200 `success=false,message="You do not have permission."`, ADMIN HTTP 200 성공 envelope다. 실제 `/v2/audio-content/main/home`도 HTTP 200에서 공개 공지 `latestNotice={id:1,title:"공개 공지",content:"홈 전체 본문",date:"2026-10-30"}`를 반환했다. notice와 홈 의존성 mock은 없다.
- 정밀도: PUT-null의 UTC `2026-10-30T00:00:00` 및 `23:59:59` 각각 nanos 0/123456789/999999999를 flush/clear/reload했다. DB의 정확한 초 단위 값과 관리자 GET KST `2026-10-30 09:00:00`/`2026-10-31 08:59:59`를 UTC로 복원한 값이 6건 모두 일치했다. 기존 createdAt=`2026-10-29T14:59:58.123456` 보존과 예약 자연 공개 뒤 isScheduled=true도 검증했다.
- 제한: Kotlin LSP 미설치·기존 설치 거부 상태여서 compiler/lint로 대체했다. 전체 suite/build·독립 최종 리뷰·P3는 부모 작업 담당이다. 운영 DB/migration/배포·의존성 추가·commit/stage/push/worktree·client-prompt.md 변경은 없다. JVM 목록과 각 환경의 TMPDIR를 대조해 이 소유 루트의 실행 중 Gradle/worker/Kotlin daemon이 없음을 확인했다.
## 추적성
### P1-T1 2차 실행: 사용자 확인으로 완료
- 사용자 확인: "서버 UTC, DB UTC로 되어 있다. publish_at은 네가 말한대로 처리".
- 결정: 새 publish_at은 초 단위 TIMESTAMP로 독립 정의하며 기존 created_at 정밀도 복제 조건을 제거했다. 기존 DDL 미조회 사실과 이전 차단 기록은 유지한다.
- 상태: P1-T1 완료, P1-T2 구현 시작 가능. 운영 DB 적용과 연결 UTC 실검증은 배포 전 별도 확인한다.
| 요구사항 | 구현 Goal | 자동 검증 | 수동/외부 검증 |
|---|---|---|---|
| NS-001, NS-003 | `P1-T2`, `P1-T3`, `P3-GATE` | admin integration, 기존 write response | anonymous/non-admin/admin mutation auth |
| NS-004 | `P1-T3`, `P3-GATE` | omitted/null/future/schedule-only 및 공개 경계 concurrency integration | 별도 UI 없음 |
| NS-005, NS-006, NS-007 | `P2-T1`, `P2-GATE` | 경계 전/정각/후, sort tie, 표시 날짜와 full fields | ADMIN token public query와 경계 이후 재조회 |
| NS-008 | `P2-T1`, `P2-GATE` | admin page와 visibility integration | 익명/비ADMIN 거부, ADMIN active scheduled 포함 |
| NS-009 | `P1-T1`, `P1-T2`, `P1-T3`, `P1-GATE`, `P2-GATE` | 운영 정밀도에 맞춘 DB round-trip nanos 0/123456789/999999999 및 관리자 응답 완전 일치 | 실제 DDL/JDBC/DB timezone 권위 자료 확인 |
## 검증 기록
### 2026-10-30 최종 구현 검증
- 기능 상태: P1-T2/P1-T3/P2-T1 및 Phase 1~2 완료. 관리자 등록·수정·별도 조회, 공개 목록·최신·홈 필터, 정렬·날짜, UTC/KST·초 정밀도, 동시 수정/삭제를 구현했다. 전체 회귀 성공 증거가 없으므로 P3-GATE는 blocked다.
- 전체 suite: `./gradlew --offline --no-daemon test ktlintCheck bootJar --continue`는 1,200,000ms 제한 초과로 종료됐다. `bootJar` 실행은 완료됐으나 test 종료 결과가 없어 전체 성공을 주장하지 않는다. timeout 후 잔여 Gradle 29742/test worker 29822의 종료를 확인했고 반복 전체 실행은 하지 않았다. 원인 stack 수집 시에는 이미 프로세스가 종료되어 원인을 특정하지 못했다.
- 최종 focused: P3-GATE에 적힌 실행 명령이 `BUILD SUCCESSFUL in 4m 9s`, exit 0. 최신 JUnit XML 기준 ADMIN/write HTTP 92, latest HTTP 13, query/DB 6, 홈 1, 동시성 9, entity 1 = 122개, failure/error/skip 모두 0. 실제 Tomcat·JWT·H2·embedded Redis로 전체 envelope와 DB 재조회 상태를 검증했다. 이는 MockMvc만의 결과가 아니라 실제 localhost HTTP 요청 결과다.
- 코드 품질: Kotlin 컴파일, `ktlintCheck`, 패키징 성공. `lsp_diagnostics` 확인 결과 kotlin-ls 미설치 및 기존 설치 거부로 LSP 진단은 불가했다. 공통 보안 설정·BaseEntity·기존 created_at·dependency는 변경하지 않았다. 테스트용 MySQL 날짜 함수의 `%s`만 보강했다.
- 최종 리뷰: Oracle 결과 회수 도구 오류로 사용 가능한 보고서가 없어 단일 대체 reviewer가 전체 diff·신규 파일·계약·테스트 근거를 검토했다. 결과 APPROVED, 차단 코드 결함 없음. 첫 결과를 승인으로 간주하거나 중복 리뷰 성공으로 계산하지 않았다.
- 관리자 프롬프트: `client-prompt.md`에 API 요청/응답·생략/null·권한·날짜 형식만 제공했다. 서버 내부 구현·DB 설정은 포함하지 않았다.
- 배포 주의: 신규 컬럼 수동 적용 및 연결 UTC 확인 → 모든 앱 reader 교체 → 관리자 예약 사용 순서를 지킨다. 운영 DB 접속/SQL 실행/배포/커밋·push는 하지 않았다.
- 증거 보존: 단계별 임시 루트의 실행 요약은 이 문서에 누적돼 있다. 임시 로그·runner·cache는 정리 대상으로 전환했으며 원래 기록은 삭제하지 않는다. 최신 실제 HTTP·DB 증거는 `build/test-results/test/TEST-*.xml`, HTML 결과는 `build/reports/tests/test/index.html`에 있다. 임시 경로는 영구 산출물 링크가 아니다.
- 정리 완료: 실행 프로세스 종료와 각 루트의 소유 보고서/명령 파일을 확인한 뒤 `notice-impl.6a7hk3`, `notice-p1t2.lPSBOW`, `notice-p1t3.FfcAgS`, `notice-p2.8nhNQr`, `p2-notice.TWFcpR` 다섯 임시 루트만 제거하고 각 경로의 부재를 확인했다. 기존 IDE/다른 프로젝트 JVM·공유 cache·다른 임시 디렉터리는 변경하지 않았다.
### 2026-10-30 문서 작성·검토
- 무엇을: PRD와 구현 계획 두 파일만 작성했다. 실제 구현·SQL·테스트 파일은 생성하지 않았고, 향후 구현 체크박스는 모두 미완료다.
- 왜: 인터뷰로 확정한 공개 정책을 API·DB·구현 Goal·수용 테스트로 연결하기 위해 문서 전용 검증을 수행했다.
- 어떻게: 두 문서 전체와 관련 소스를 대조했다. 독립 builder check 결과 중요한 미결 사항이 없었고, 작성자 검토에서 홈 테스트 대상을 실제 공지 조립 서비스로 수정하고 저장·응답의 초 단위 계약과 검증 소유 Task를 구체화했다.
- 공백 검사: `GIT_MASTER=1 git diff --no-index --check /dev/null docs/20261030_공지사항예약공개/prd.md` 및 같은 명령의 `plan-task.md` 검사에서 공백 오류가 없었다. `rg`의 완료 체크박스·trailing whitespace·미해결 placeholder 검사도 출력이 없었다.
- 변경 범위: `GIT_MASTER=1 git -c core.quotePath=false status --short --untracked-files=all`에서 이 디렉터리의 두 Markdown 파일만 신규 파일로 확인했다. Gradle, 테스트, 빌드, live HTTP, 운영 DB 검증은 문서 전용 요청이므로 실행하지 않았다. 운영 DDL·정밀도·시간대는 `P1-T1`의 외부 확인 차단 조건이다.
### 2026-10-30 커밋 전 재검증
- 사용자 `/commit-with-validation` 요청으로 기존 변경의 커밋을 승인받았다. 전역 공용 절차와 저장소 커밋 규칙을 확인하고 변경 파일 전체를 점검했다.
- 실행: `./gradlew --offline --no-daemon test --tests 'kr.co.vividnext.sodalive.notice.*' --tests 'kr.co.vividnext.sodalive.v2.api.notice.*' --tests 'kr.co.vividnext.sodalive.v2.api.admin.notice.*' --tests 'kr.co.vividnext.sodalive.content.main.tab.home.AudioContentMainTabHomeServiceIntegrationTest' ktlintCheck bootJar --continue`.
- 결과: exit 0, `BUILD SUCCESSFUL in 1m 31s`. test task는 실제 재실행됐으며 최신 JUnit XML의 6개 class 합계 122개, failure/error/skip 모두 0이다. 컴파일·lint·bootJar는 변경 없음으로 UP-TO-DATE였다. `git diff --check`도 통과했다.
- 전체 suite는 이번 커밋 검증에서 재실행하지 않았다. 구현 변경 없이 기존 산출물을 커밋하는 범위이므로 직접 영향 notice/home 회귀를 검증했다. 이전 전체 suite timeout과 P3-GATE blocked 상태는 유지한다. 운영 DB 검증·DDL 적용·배포는 수행하지 않았다.
@@ -1,163 +0,0 @@
# 공지사항 예약 공개 PRD
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | 기능 구현·관련 테스트 122개·패키징·리뷰 완료, 전체 회귀 timeout으로 최종 Gate 보류, 미배포 |
| 작성일 | 2026-10-30 |
| 최종 수정일 | 2026-10-30 |
| 대상 제품 | 관리자 공지사항 예약 공개와 공개 공지 조회 |
| 작성자·결정권자 | 제품 승인 요구사항, 기술 제안은 본 문서에 구분 표기 |
| 관련 API Contract | 본 문서 §7 |
| 관련 구현 계획 | [plan-task.md](plan-task.md) |
| 관련 review | 없음 |
## 1. 목표와 문제
관리자는 공지를 미리 등록하고 지정한 시각에 공개할 수 있어야 한다. 예약 전 공지는 관리자 목록에서 확인하고 관리할 수 있지만, 관리자 권한이 있더라도 일반 공개 조회에서는 예약 시각 전 공지를 볼 수 없어야 한다. 구현 범위는 서버 API, DB, 테스트이며 관리자·클라이언트 UI는 제외한다.
## 2. 결정 상태와 범위
| 구분 | 내용 |
|---|---|
| 사용자 확정 정책 | §3~§8의 권한, 상태 전이, 날짜·정렬·공개 경계, 기존 API 호환 정책 |
| 구현 설계 결정 | nullable `publishAt`와 `isScheduled`, API 입력 의미, `yyyy-MM-dd HH:mm:ss` KST 형식, 관리자 목록 경로와 페이지 계약 |
| 사용자 추가 확인 | 서버 UTC, DB UTC. 신규 `publish_at`은 초 단위 MySQL `TIMESTAMP NULL DEFAULT NULL`로 확정한다. 기존 `created_at`의 정밀도를 복제하거나 변경하지 않는다. 기존 운영 DDL은 미조회이며 배포 전 신규 컬럼 적용·연결 시간대 확인은 유지한다. |
## 3. 목표와 제외
### 목표
- 관리자는 예약 공개 공지를 포함한 활성 공지 목록과 예약 시각을 확인하고 기존 생성·수정·삭제 권한으로 관리한다.
- 공개 목록과 최근 공지는 예약 시각이 현재 시각 이하인 활성 공지만 반환한다.
- 기존 공개 응답 형식, 권한, 삭제 방식은 보존하되 공개 순서와 `date` 값은 승인된 정책으로 변경한다.
- DB 시각은 UTC로 저장하고 관리자 입력·표시와 클라이언트 날짜 표시는 KST를 적용한다.
### 제외
- 관리자 페이지와 클라이언트 UI, 예약 공개 scheduler·catch-up 작업, 캐시, 역할 신설, 복원, 일괄 예약, 신규 의존성.
- 공지 상세 API, 검색·상태 필터, 글로벌 시간대/BaseEntity 변경, 과거 레코드 backfill.
- 운영 DB에 대한 자동 DDL 적용 또는 실제 운영 DB 접속.
## 4. 사용자와 권한
| 작업 | 익명 | 일반 인증 사용자 | ADMIN |
|---|---:|---:|---:|
| 기존 공개 목록·v1/v2 최근 공지 조회 | 허용된 기존 경로만 | 기존 정책 유지 | 공개 규칙만 적용, 예약 미공개 우회 금지 |
| 활성 예약 포함 관리자 목록 조회 | 거부 | 거부 | 허용 |
| 공지 생성·수정·삭제 | 거부 | 거부 | 기존 ADMIN 전용 정책 유지 |
예약 공개 관리자 API는 별도 관리자 조회 경로다. 공개 API는 인증 주체의 역할에 따라 예약 공지를 노출하지 않는다. 현재 공통 `SodaExceptionHandler`의 business/AccessDenied 오류는 `ApiResponse.error` 응답을 사용하며 HTTP 상태를 임의로 새로 정하지 않는다. 익명 인증 실패는 현재 SecurityConfig 및 entry point 계약을 따른다. 실제 통합 검증에서 status와 envelope를 확인한다.
## 5. 상태·데이터 정책
### 제품 정책
1. 기존 활성 상태(`isActive`)와 등록·수정·삭제 권한은 유지한다. 기존 공지는 계속 공개된 공지로 간주하되 `isActive=false`면 공개 조회에서 제외한다. 예약 시각 변경으로 이미 공개된 공지를 숨기거나 재예약할 수 없다는 뜻이며, 기존 ADMIN soft delete는 계속 허용한다.
2. 생성 시 공개 시각 생략 또는 JSON `null`은 즉시 공개다. 미래 시각은 예약이며 과거 시각은 거부한다.
3. 예약 공개 시각에 도달하면 `publishAt <= now`인 공개 조회에서 자동으로 공개된다. 공개 여부는 query 시각으로 계산하며 scheduler가 필요 없다. 서비스 중단 중 catch-up 작업 없이 재기동 후 다음 조회가 경계를 판정한다.
4. 아직 공개되지 않은 예약 공지만 공개 시각을 변경하거나 즉시 공개로 전환할 수 있다. 공개 시각 변경으로 이미 공개된 공지를 숨기거나 재예약할 수 없다. 기존 ADMIN soft delete 권한은 유지한다. 제목·본문 수정 규칙은 유지하고 예약 시각만 수정하는 요청도 허용한다.
5. 공개 결과는 유효 공개 시각 내림차순, 동률이면 기존 등록 순서인 `id` 내림차순이다. 즉시 공개 전환 시 정렬용 유효 공개 시각은 전환 시각이다.
6. 자동 예약 공개 날짜는 예약 공개 시각의 KST 날짜다. 즉시 생성 공지 날짜는 원래 등록 시각의 KST 날짜다. 예약을 즉시 공개로 전환해도 표시 날짜는 원래 등록 시각을 유지한다. 이 날짜 표시 규칙은 정렬에 쓰이는 유효 공개 시각과 별개다.
7. 관리자 입력·응답 시각은 `Asia/Seoul`, DB 시각은 UTC다.
### 구현 설계 결정
- 저장 필드는 nullable UTC `publishAt`와 `isScheduled`(기본 `false`)로 제안한다. 기존·즉시 공지는 `publishAt=NULL`, 예약 공지는 미래 시각과 `isScheduled=true`를 저장한다. 예약에서 즉시 공개로 바꿀 때 서버 시각을 `publishAt`에 저장하고 `isScheduled=false`로 한다. `publishAt`을 NULL로 초기화하면 전환 시각 정렬이 깨지므로 금지한다.
- 공개 여부는 `isActive AND (publishAt IS NULL OR publishAt <= now)`다. 표시 날짜의 원본은 `isScheduled=true`일 때 `publishAt`, 그 외에는 `createdAt`이다. 공개 정렬 키는 `COALESCE(publishAt, createdAt) DESC, id DESC`다.
- 공개 필터는 count 및 목록에서 pagination/limit 전에 적용한다. 목록, v1 latest, v2 latest 모두 같은 가시성 및 정렬 규칙을 사용한다. 관리자 목록은 별도 ADMIN 전용 조회로 활성 전체를 반환하고 공개 여부로 숨기지 않는다.
- 별도 상태 엔진, 공개 모드 이력, backfill은 두지 않는다. `isScheduled`만으로 예약값과 즉시값을 구분한다.
- 사용자 후속 승인에 따라 신규 `publish_at`은 초 단위 MySQL `TIMESTAMP NULL DEFAULT NULL`와 COMMENT로 추가한다. 기존 컬럼 정밀도 복제는 하지 않으며 `created_at`, `BaseEntity`, 전역 timezone 설정은 변경하지 않는다. 서버·DB UTC는 사용자 확인을 근거로 하고 운영 DB 직접 조회를 수행했다는 뜻은 아니다.
## 6. 흐름 및 시간·동시성 규칙
### 쓰기
- 기술 계약 선택: 생성 요청은 기존 `title`, `content`와 선택 입력 `publishAt`을 받는다. 필드 생략/JSON null은 즉시 생성, 유효한 미래 KST 시각은 UTC 예약으로 저장한다. 제목·본문 기존 blank 검증은 유지한다.
- 수정은 기존 `id`, 선택적 `title`, `content`와 선택 입력 `publishAt`을 받는다. 공개 시각 필드 생략은 보존, 명시적 null은 예약 미공개일 때 즉시 전환, 유효한 미래 시각은 예약 미공개일 때 재예약이다. 예약 시각만 보내는 수정도 유효하다. 제목·본문만 수정하는 기존 사용법은 유지한다.
- 현재 DTO의 nullable 필드만으로 JSON 생략과 null을 구분할 수 없으므로 입력 경계에서 field presence를 구분한다. 배너 선례처럼 JSON tree의 `has("publishAt")` 검사가 설계 참고다. null 제목/본문을 예약 전환 의미로 오해하지 않는다.
- 기술 계약 선택: wire format은 KST `yyyy-MM-dd HH:mm:ss`이며 파서는 `uuuu-MM-dd HH:mm:ss` + `ResolverStyle.STRICT`를 사용한다. UTC 변환 후 미래여야 하며 현재 시각도 거부한다. 포맷 오류, 과거/현재 시각, 잘못된 전환은 `SodaException(messageKey="common.error.invalid_request")`를 사용한다. HTTP 400을 별도 강제하지 않는다. 숫자 범위는 P1-T1에서 확인된 실제 timestamp 타입 기준으로만 검사하며 임의 범위를 만들지 않는다.
- 수정 boundary는 기존 `ServiceNoticeController.updateNotice`가 JSON object `JsonNode`를 받도록 하고, `publishAt`은 JSON string 또는 JSON null만 허용한다. object가 아니거나 필드가 다른 타입이면 거부한다. 컨트롤러는 `ObjectMapper`로 기존 `UpdateNoticeRequest`를 변환하고 `service.update(request, publishAtPresent = fields.has("publishAt"))`를 호출한다. `title/content/id`의 기존 nullable/blank 동작을 보존한다. omitted `publishAt`은 explicit null과 다르다.
- 기술 결정: 기존 JPA repository에 `findByIdForUpdate(id: Long): ServiceNotice?`를 `PESSIMISTIC_WRITE`로 구현한다. 수정 transaction은 이 잠금을 먼저 획득한 뒤 fresh UTC now와 현재 상태를 읽고 eligibility를 판정한다. title/content-only 수정도 같은 잠금을 거쳐 stale JPA flush가 새 schedule 값을 덮지 않게 한다. 잠금 뒤 공개 시각이 이미 경과했으면 시간 변경을 거부한다. 변경의 선형화 지점은 잠금 후 eligibility 검사 시점이며, wall-clock 시간이 이후에도 경계를 넘을 수 있음은 정상적인 query-time 공개 정책이다. 공개 query는 row lock을 얻지 않는다.
### 읽기와 정밀도
- 공개 서비스 조회는 요청 단위로 UTC now를 한 번 캡처하고 count와 목록이 같은 값을 사용한다. 기존 `nowProvider` 테스트 seam 패턴을 재사용하며 전역 Clock 추상화는 도입하지 않는다. 기존 `ServiceNoticeService.getNoticeList(pageable, timezone)`와 `getLatestNotice()` 진입 시그니처를 유지하고 내부에서 시각을 한 번 캡처한다. v2 `LatestNoticeService`는 같은 now를 받는 repository query를 사용한다.
- 새 `publishAt`의 업무·API 계약은 초 단위다. 예약 입력은 초 단위로 파싱하고, 즉시 전환은 한 번 캡처한 UTC now를 저장 경계에서 초 절삭한 단일 값으로 저장·반환한다. 확인된 물리 컬럼이 `(3)/(6)`이어도 이 새 필드의 값은 나노초 0을 유지하며, 기존 `createdAt`의 정밀도나 저장값에는 적용하지 않는다. 미래 여부와 기존 공개 경계 판정은 잠금 후 캡처한 원본 now를 기준으로 한다. 즉시 생성 공지는 `publishAt=NULL`이라 `BaseEntity.PrePersist`의 등록 시각과 별도 시계값을 중복 저장하지 않는다.
- 저장 정밀도 왕복 테스트는 즉시 전환의 now에 nanos `0`, `123456789`, `999999999`를 고정 입력으로 포함해 DB `flush/clear/reload`를 수행한다. 새 `publishAt`의 예상 나노초는 모두 0이며 다음 초·날짜로 반올림되지 않아야 한다. 관리자 응답의 `publishAt`을 KST에서 UTC로 복원한 값과 DB 값도 정확히 같아야 한다. `createdAt`의 초 단위 응답은 표시 형식일 뿐 DB 원본과 소수초까지 같다는 주장이 아니다. 테스트 DB의 컬럼 정밀도는 확인된 운영 계약에 맞추며 H2가 운영 정밀도와 같다고 가정하지 않는다.
## 7. API 계약
공통 성공 envelope는 기존 `ApiResponse` (`success`, `message`, `data`, `errorProperty`)를 유지한다. POST 생성 응답의 숫자 ID와 PUT/DELETE 성공 응답의 `data: {}` 및 message를 유지한다. PUT/DELETE 값은 실제 HTTP 검증으로 확인했으며 기존 문서의 null 표기를 정정한다. 아래 `publishAt`은 JSON request body 필드다. Route, 필드 presence semantics, wire format, 오류 키는 사용자 정책을 구현하기 위한 기술 계약 선택이며 사용자가 직접 지정한 세부 스키마로 간주하지 않는다.
### 7.1 기존 공개 조회 계약 보정
| Method / path | 인증 | 응답 |
|---|---|---|
| `GET /notice` | 기존 인증 정책 | `ApiResponse<{totalCount: Int, noticeList: NoticeItem[]}>` |
| `GET /notice/latest` | 기존 공개 정책 | `ApiResponse<NoticeItem \| null>` |
| `GET /api/v2/notices/latest` | 기존 공개 정책 | `ApiResponse<NoticeItem[]>`, 최대 3개 |
`NoticeItem = {id: Long, title: String, content: String, date: String}`를 유지한다. 페이지 응답의 모양과 파라미터 관례는 기존 계약대로 둔다. 세 응답은 모두 활성 공개 공지만 반환하며 동일한 유효 공개 시각 DESC, `id` DESC를 적용한다. `date`는 §5의 표시 규칙에 따른 KST `yyyy-MM-dd`다. 예약 공지는 경계 시각 이전에는 ADMIN 토큰을 포함한 공개 요청에도 제외한다.
### 7.2 관리자 목록
| Method / path | 인증·인가 | 요청 | 성공 응답 |
|---|---|---|---|
| `GET /api/v2/admin/notices` | ADMIN만 | `page: Int` (0부터), `size: Int` (Spring Pageable 관례) | `ApiResponse<{totalCount: Int, noticeList: AdminNoticeItem[]}>` |
`AdminNoticeItem = {id: Long, title: String, content: String, isActive: Boolean, isScheduled: Boolean, publishAt: String \| null, createdAt: String}`. `publishAt`과 `createdAt`은 KST `yyyy-MM-dd HH:mm:ss`; `publishAt=null`은 공개 시각이 지정되지 않은 즉시 공지다. `createdAt` 응답 표시를 초 단위 문자열로 포맷하는 것은 원본 DB 정밀도나 저장값을 절삭하는 것을 뜻하지 않는다. 목록은 활성 공지 전체를 공개 여부와 무관하게 페이지네이션하며 정렬은 공개 조회와 동일한 유효 공개 시각 DESC, id DESC다. 검색·추가 필터는 제공하지 않는다.
### 7.3 생성 및 수정 요청
| Method / path | 요청 계약 | 결과 |
|---|---|---|
| `POST /notice` | `{title: String, content: String, publishAt?: String \| null}` | 기존 성공 `data` 공지 ID 유지 |
| `PUT /notice` | `{id: Long, title?: String \| null, content?: String \| null, publishAt?: String \| null}` | 기존 성공 응답 유지 |
| 기존 DELETE 경로 | 변경 없음 | 기존 soft delete 및 응답 유지 |
요청 예: `{"title":"점검 안내","content":"본문","publishAt":"2026-11-01 09:00:00"}`는 KST 09:00 예약이다. 생성 요청에서 필드를 빼거나 null이면 즉시 공개다. 수정 요청에서 필드를 빼면 저장값 보존, null이면 예약 미공개 공지를 지금 공개로 전환, 미래 시각 문자열이면 예약 미공개 공지를 재예약한다. 수정 시 공개된 공지는 `publishAt` 필드를 바꾸는 모든 요청을 거부한다. title/content 수정은 기존 동작과 검증을 유지하고 시각-only 요청을 허용한다.
오류는 기존 `ApiResponse.error`와 `common.error.invalid_request` 정책을 사용한다. 오류 envelope/status를 전역 변경하지 않는다. 상세한 unauthorized/forbidden HTTP status를 신규 계약으로 약속하지 않고 현재 SecurityConfig, entry point, exception advice의 실제 응답을 통합 테스트한다.
## 8. 수용 기준과 요구사항 추적
| ID | 상태 | 요구사항 및 검증 가능한 수용 기준 | 계약 / 계획 Goal |
|---|---|---|---|
| NS-001 | 확정, 사용자 | 기존 쓰기 API ADMIN-only 권한과 생성/수정/삭제 응답을 보존한다. | §4, §7.3 / P1-T2, P1-T3, P3-GATE |
| NS-002 | 확정, 사용자 | 공개 조회는 활성 및 공개 경계 조건을 pagination 전 적용한다. ADMIN도 공개 API로 미공개 예약 공지를 받지 않는다. | §4, §5, §7.1 / P2-T1, P3-GATE |
| NS-003 | 확정, 사용자 | 미지정/null 생성은 즉시, 미래는 예약, 과거는 common invalid request로 거부한다. | §5, §7.3 / P1-T2 |
| NS-004 | 확정, 사용자 | 미공개 예약만 시각 변경/즉시 전환 허용. 기존 title/content 수정 유지, 시각-only 수정 허용. 이미 공개된 공지의 시각 변경은 거부. | §5, §6, §7.3 / P1-T3, P3-GATE |
| NS-005 | 확정, 사용자 | 공개는 `publishAt <= captured now`, scheduler 불필요, 중단 후 다음 조회에서 공개된다. | §5~6 / P2-T1 |
| NS-006 | 확정, 사용자 | 정렬은 유효 공개 시각 DESC, 동률 id DESC. 즉시 전환은 현재 시각 정렬. | §5, §7.1 / P2-T1, P3-GATE |
| NS-007 | 확정, 사용자 | 예약 공개 날짜는 예약 시각 KST 날짜, 즉시 생성/전환 날짜는 원래 등록 시각 KST 날짜. 관리자 시각 KST, DB UTC. | §5~7 / P1-T1, P2-T1 |
| NS-008 | 확정, 사용자 | ADMIN 목록은 활성 예약 미공개 공지도 포함하고 ADMIN 전용이다. | §4, §7.2 / P2-T1, P2-GATE |
| NS-009 | 확정, 사용자 후속 승인 | 서버·DB UTC, 새 publish_at은 초 단위 TIMESTAMP. 기존 created_at은 미변경. 신규 컬럼의 DB 왕복 및 UTC/KST 변환을 검증한다. 운영 적용과 연결 설정 실확인은 배포 전 수행한다. | §2, §6 / P1-T1, P1-T3, P2-GATE |
## 9. 구현 위치 근거 및 의존성
- 기존 쓰기와 public query: `src/main/kotlin/kr/co/vividnext/sodalive/notice/ServiceNotice.kt`, `ServiceNoticeService.kt`, `ServiceServiceNoticeRepository.kt`, `CreateNoticeRequest.kt`, `UpdateNoticeRequest.kt`, `GetNoticeResponse.kt`.
- v2 최신 공지 service와 실제 HTTP regression: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/notice/application/LatestNoticeService.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/notice/LatestNoticeControllerIntegrationTest.kt`.
- KST 엄격 파싱 및 JSON field presence 선례: `src/main/kotlin/kr/co/vividnext/sodalive/v2/subbanner/application/SubBannerService.kt`.
- UTC now 주입 seam 선례: `SubBannerService.kt`와 `src/main/kotlin/kr/co/vividnext/sodalive/content/AudioContentRepository.kt`.
- 운영 공지 DDL은 저장소 검색으로 발견되지 않았다. 실제 DB/DDL/JDBC 설정은 확인되지 않았고 별도 선행 확인이 필요하다.
## 10. 완료 기준
- [x] NS-001~NS-008의 각 계약·권한·상태 전이가 계획의 자동 또는 수동 검증으로 추적된다.
- [x] 공개 query 경계, role에 따른 가시성 누출 방지, 동률 정렬, 날짜 표시와 전환 정렬 구분을 실제 HTTP로 검증했다.
- [x] 사용자 확정 UTC·초 단위 신규 컬럼 계약과 모델·정규화 전략이 일치하고 로컬 DB 왕복 테스트를 통과했다. 운영 적용·연결 시간대 실확인은 배포 전 조건으로 별도 기록한다.
- [x] 저장 왕복 검증과 기존 full-field HTTP assertion을 유지했다. 기존 id-only fixture 기대는 승인된 공개 정렬에 맞게 변경했고 다른 응답·보안 assertion을 유지했다.
전체 회귀 `./gradlew --offline --no-daemon test ktlintCheck bootJar --continue`는 test 단계에서 20분 timeout으로 종료됐다. 전체 suite 성공은 미확인이다. 별도의 최종 focused 실행은 실제 HTTP·DB 122개, `ktlintCheck`, `bootJar`가 모두 exit 0이었고 독립 최종 리뷰는 승인됐다. Kotlin LSP는 미설치/기존 설치 거부로 compiler·lint를 사용했다. 운영 DB 적용과 배포는 수행하지 않았다.
## 11. Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 |
|---|---|---|---|---|
| 2026-10-30 | NS-D1 | 사용자 확정 | 공개 정책, 권한, 정렬, KST 날짜 표시, 경계 공개, UI 제외는 승인 요구사항을 그대로 따른다. | 이번 작업의 승인 정책 |
| 2026-10-30 | NS-D2 | 기술 결정 | 예약 상태는 nullable `publishAt` + `isScheduled`로 표현하고 공개 전환 시 `publishAt`에 서버 now를 보존한다. | 전환 정렬과 표시 날짜 정책을 분리하며 backfill을 피함 |
| 2026-10-30 | NS-D3 | 기술 결정 | 관리자 시각 문자열은 엄격한 KST `yyyy-MM-dd HH:mm:ss`; 오류 키는 기존 `common.error.invalid_request`다. | 기존 KST 입력/presence 구현 선례, 공통 예외 정책 |
| 2026-10-30 | NS-D4 | 미확인 차단 | 기존 및 신규 timestamp 실제 정밀도와 DB/JDBC timezone은 운영 DDL 확인 전 확정하지 않는다. | 공지 DDL이 저장소에 없고 시간 정밀도 가이드가 사전 확인을 요구함 |
| 2026-10-30 | NS-D5 | 사용자 승인, NS-D4 정정 | 서버 UTC·DB UTC 확인. 새 publish_at은 초 단위 TIMESTAMP로 독립 정의하고 기존 created_at은 변경하지 않는다. 기존 DDL 미확인은 구현 차단에서 배포 전 확인으로 이동한다. | 사용자: "서버 UTC, DB UTC로 되어 있다. publish_at은 네가 말한대로 처리" |
@@ -1,71 +0,0 @@
# 추천 API 실제 HTTP 검증
## 실행 증거
- 실행일: 2026-10-31. 제품 변경 기준: `969f999a`와 동일한 제품 코드.
- 표면: `SpringBootTest(RANDOM_PORT)` + `TestRestTemplate`, loopback HTTP, 격리 H2 및 embedded Redis.
- 인증: 테스트 DB에 저장한 회원과 Auth, 실제 `TokenProvider.createToken`으로 발급한 Bearer JWT. MockMvc principal 주입이 아니다.
- fixture는 `TransactionTemplate`으로 commit한 뒤 HTTP 요청했다. 운영 DB 및 외부 API를 호출하지 않았다.
- 결과: HTTP 요청 **104건**, 상태·응답·정책 비교 판정 **216건**, 실패 **0건**, `BUILD SUCCESSFUL in 30s`.
- 두 추천 API 및 `/api/v2/events/{id}`를 함께 호출해 추천 배너의 이벤트 ID와 상세 조회 허용 ID를 비교했다.
실행 명령은 아래와 같다. QA_ROOT는 작업 소유 임시 디렉터리였으며 최종 자원 정리 대상이다.
```bash
./gradlew --init-script "$QA_ROOT/socket-qa.init.gradle" test \
--tests kr.co.vividnext.sodalive.v2.qa.RecommendationSocketQaTest
```
원본 `evidence-second/summary.json`, `responses.json`을 직접 읽고 아래 결과를 발췌했다. 토큰·인증 헤더·Auth 개인정보는 보존하지 않는다. 아래 ID는 테스트 fixture ID이지 운영 이벤트 ID가 아니다.
## 실제 결과
| 국가 / Accept-Language | 조회자 | 홈 이벤트 ID 순서 | 오디오 이벤트 ID 순서 | 상세 허용 ID 집합 | 판정 |
|---|---|---|---|---|---|
| KR / ja | 익명 | 1, 2 | 1, 2 | 1, 2 | PASS |
| KR / ja | 미인증 | 1, 2 | 1, 2 | 1, 2 | PASS |
| KR / ja | 인증 | 1, 3 | 1, 3 | 1, 3 | PASS |
| KR / ja | ADMIN | 1, 2, 3 | 1, 2, 3 | 1, 2, 3 | PASS |
| JP / ko | 익명 | 8, 9 | 8, 9 | 8, 9 | PASS |
| JP / ko | 미인증 | 8, 9, 8 | 8, 9, 8 | 8, 9 | PASS |
| JP / ko | 인증 | 8, 10 | 8, 10 | 8, 10 | PASS |
| JP / ko | ADMIN | 8, 9, 10 | 8, 9, 10 | 8, 9, 10 | PASS |
JP 미인증의 마지막 ID 8은 동일한 전체 대상 이벤트에 연결된 별도 성인 배너다. 해당 회원은 성인 표시 설정이 켜져 있어 배너 자체 조건은 통과하지만, 인증 전용 이벤트 ID 10은 노출되지 않는다. 이벤트 중복 제거를 추가하지 않고 기존 배너 단위 계약을 유지한다.
모든 행에서 성공 envelope, 기존 top-level 필드 집합, 정확한 배너 이미지 순서, LINK 유지, `subBanners: []`를 확인했다. 홈은 `aiCharacters: []`, 오디오는 해당 필드가 없다. 인증 회원의 성인 표시 설정은 꺼져 있었어도 인증 대상 이벤트 배너 자체가 비성인이면 정상 노출됐다.
## HTTP 응답 발췌
익명 KR 요청의 홈 응답에서 관찰한 부분이다. 전체 응답 예시가 아닌 실제 필드 발췌다.
```json
{
"success": true,
"data": {
"aiCharacters": [],
"subBanners": [],
"banners": [
{ "imageUrl": "https://cdn.test/qa/KR/HOME/all.png", "eventItem": { "id": 1 } },
{ "imageUrl": "https://cdn.test/qa/KR/HOME/false.png", "eventItem": { "id": 2 } },
{ "imageUrl": "https://cdn.test/qa/KR/HOME/retained-link.png", "eventItem": null },
{ "imageUrl": "https://cdn.test/qa/KR/HOME/creator-block.png", "creatorId": 4 }
]
}
}
```
## 경계 및 인접 표면
- 비활성·시작 전·종료 후·이벤트 언어 불일치·연결 이벤트 없는 EVENT 배너는 제외됐다. ADMIN도 이를 우회하지 못했다.
- 배너 자체의 비활성·탭·언어·예약·성인 조건을 유지했고, 로그인 회원에게 차단된 CREATOR 배너는 제외됐다.
- LINK 문자열에 이벤트처럼 보이는 URL이 있어도 임의 파싱하지 않고 기존 배너로 유지했다.
- fixture 이벤트 전체를 비활성화하고 비EVENT 배너도 비활성화한 후 4종 조회자 × KR/JP × 두 API에서 `banners: []`를 확인했다.
- 이 HTTP 검증은 넓은 시간창을 사용했다. 정확한 나노초 경계·limit·random tie·AI 조회 비호출·전용 AI endpoint 보존은 계획의 focused 테스트 증거로 별도 검증한다.
## 실행 중 보정 및 한계
- 첫 QA 실행은 HTTP 요청 이전에 Spring Redis `setConfig("save", "")`의 빈 값 검증에서 실패했다. 제품 결함이 아니며 임시 harness만 raw `CONFIG SET save` 호출로 바꾼 뒤 재실행했다.
- 두 번째 실행이 위 PASS 결과다. 임시 Redis의 snapshot 저장만 끄고 테스트 토큰을 종료 시 삭제하도록 구성했다.
- 운영 MySQL 데이터·Event 컬럼 저장 정밀도는 검증하지 않았다. LSP 도구가 없어 LSP 진단을 실행했다고 주장하지 않는다.
- 최종 전체 빌드·리뷰·임시 자원 정리 결과는 `plan-task.md`의 Gate 기록을 따른다.
@@ -1,344 +0,0 @@
# 추천 화면 AI 캐릭터 및 이벤트 배너 노출 정책 구현 계획
> 실행 전제: 구현을 시작하려면 사용자의 별도 실행 승인이 필요하다. 승인 전 본 계획의 모든 실행 체크박스는 미완료 상태로 둔다.
**Goal:** 홈 추천 aggregate에서는 AI 캐릭터를 항상 빈 배열로 반환하고, 홈·오디오 추천의 EVENT 배너에는 기존 이벤트 상세 노출 정책을 적용한다.
**Architecture:** 홈 aggregate는 AI 추천 query 경로를 호출하지 않는다. 각 추천 repository의 기존 배너 QueryDSL 조회에만 EVENT 적격 조건을 추가한다. 이벤트 시간은 상세 조회와 같은 system-default `LocalDateTime` 의미로 별도 평가하고, 기존 배너 예약용 UTC clock은 변경하지 않는다.
**Tech Stack:** Kotlin 1.6.21, Spring Boot 2.7.14, Java 17, JUnit 5, QueryDSL 5.0.0, Spring Data JPA, H2 MySQL mode 테스트.
**Spec:** [`prd.md`](prd.md)
---
## 문서 및 실행 상태
| 항목 | 상태 |
|---|---|
| 문서 상태 | 구현 및 검증 완료 · 전체 빌드는 UTC 환경 기준 |
| 작성일 | 2026-10-31 |
| 요구사항 기준 | `docs/20261031_추천화면AI캐릭터및이벤트배너노출정책/prd.md` |
| API 기준 | PRD §8, 기존 응답 schema 유지 |
| 현재 Phase | Phase 1 · 추천 응답 노출 정책 일치 |
| 현재 활성 Goal | 없음 · `P1-GATE` 완료 |
| 실행 순서 | `P1-T1` → `P1-T2` → `P1-T3` → `P1-GATE` |
계획 작성 당시에는 구현하지 않았으며, 이후 사용자의 `문서대로 진행` 및 `ulw` 승인에 따라 구현했다. 개별 실행 기록은 당시 상태를 보존하고, 현재 상태는 상단 표와 최신 Gate 기록을 따른다.
## Global Constraints
- `REC-AI-001`에 따라 홈 aggregate의 `aiCharacters`는 익명·회원·ADMIN 모두 `[]`이고 null 또는 생략이 아니다. 해당 경로에서 AI query/fallback을 호출하지 않는다.
- 오디오 추천 DTO에 AI 캐릭터 필드를 추가하지 않는다. 전용 `/api/v2/home/recommendations/ai-characters` 흐름을 보존한다.
- EVENT 배너의 적격 조건은 연결 이벤트 존재, 활성, `startDate <= eventNow <= endDate`, 회원 해석 국가의 언어, 성인 대상 정책이다.
- 인증 대상은 `AuthRepository.getAuthIdByMemberId(memberId) != null`과 같다. 익명은 미인증이다. `isAdult == null`은 모두, `true`는 인증, `false`는 미인증만 적격이다.
- ADMIN은 이벤트 audience 조건만 우회하며 존재·활성·시간·언어 조건과 배너 자체 조건은 우회하지 않는다.
- 기존 banner-own 활성·tab·language·reservation·성인 노출 가능 여부·creator-block 조건은 이벤트 조건과 AND로 유지한다. 기존 정렬, 동순위 random tie, 적격 후보에 대한 limit 20을 유지한다.
- 기존 공개 service/port 서명은 보존한다. per-event `EventDetailService.getEvent` 호출, 신규 abstraction, N+1 또는 별도 application query를 만들지 않는다.
- 양 repository의 별도 clock 의존성은 `eventNowProvider: () -> LocalDateTime = { LocalDateTime.now() }`를 기존 `nowProvider` 바로 앞에 추가한다. event clock은 query당 한 번 캡처하고, 기존 trailing-lambda가 주입하는 banner `nowProvider`는 UTC 예약 판정 전용으로 보존한다.
- 이벤트 비교는 `EventDetailService`처럼 system-default `LocalDateTime.now()` 의미와 sub-second 정밀도를 사용한다. 기존 banner reservation의 UTC/초 정밀도, 전역 timezone 및 formatter는 바꾸지 않는다.
- 구현 Task는 각자 RED → RED 확인 → GREEN → GREEN 확인 → REFACTOR 순서다. Task마다 실패 재현, 최소 구현, focused 검증 증거를 남긴다.
- 전체 회귀는 공통 인증·보안·예외·설정 경계 변경, 여러 domain 변경, release/final 전수 증거 요구, 또는 targeted test로 영향 범위를 판정할 수 없는 실패 때만 수행한다. 그 외에는 생략 사유와 focused 대체 검증을 Progress에 기록한다.
## Review Focus
- 인증 기록과 `canViewAdultContent`가 서로 다른 조회자: 이벤트는 인증 기록, 배너 자체는 기존 성인 노출 가능 여부를 각각 적용한다. `P1-T2`, `P1-T3`에서 인증된 `canViewAdultContent=false` 및 미인증 `canViewAdultContent=true` 조합을 고정한다.
- 이벤트 경계 시각의 clock/정밀도 차이: 두 clock을 서로 다르게 고정하고 nanos를 포함하여 정확한 양끝은 포함, 직전·직후는 제외한다. 기존 예약 UTC clock 값과 이벤트 clock 값을 다르게 설정한다. `P1-T2`, `P1-T3`에서 확인한다.
- 대상 없는 EVENT, 부적격 우선순위 후보, 전부 제외: 기존 다른 배너는 실패 없이 유지되고 필터가 limit 전에 실행되며 전부 제외 시 `[]`인지 각각 `P1-T2`, `P1-T3`에서 확인한다.
- ADMIN 권한 범위: 인증 audience만 우회하고 잘못된 언어·비활성·기간 밖 이벤트와 배너 자체 성인/활성 조건은 통과시키지 않는지 `P1-T2`, `P1-T3`에서 확인한다.
- request language와 국가 판정 불일치 및 오디오 schema: 홈·오디오 endpoint가 `resolveCountryCode`로 결정된 이벤트 언어를 적용하고 오디오 응답에 `aiCharacters`가 없음을 `P1-GATE`에서 확인한다.
## 파일 책임 및 작업 범위
| 파일 | 책임 |
|---|---|
| `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacade.kt` | 홈 aggregate의 AI 목록을 빈 목록으로 고정하고 aggregate AI 조회 호출 제거 |
| `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacadeTest.kt` | facade가 AI recommendation 경로를 호출하지 않으며 응답은 빈 목록임을 검증 |
| `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/HomeRecommendationControllerTest.kt` | 홈 API AI 목록/전용 endpoint 유지 검증 및 홈 배너 정책 endpoint 회귀 검증 |
| `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt` | 홈 배너 EVENT 조건과 별도 상세 정책 clock을 기존 QueryDSL 필터에 반영 |
| `src/test/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepositoryTest.kt` | 홈 배너 QueryDSL의 audience·시간·언어·교집합·정렬/limit 검증 |
| `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepository.kt` | 콘텐츠 추천 배너 EVENT 조건과 별도 상세 정책 clock을 기존 QueryDSL 필터에 반영 |
| `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepositoryTest.kt` | 오디오 배너 QueryDSL의 audience·시간·언어·교집합·정렬/limit 검증 |
| `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/content/recommendation/adapter/in/web/AudioRecommendationEndToEndTest.kt` | 오디오 추천 응답에 AI 필드가 없고 배너 API 계약이 유지됨을 검증 |
## Phase 1: 추천 응답 노출 정책 일치
**Phase 결과:** 기존 응답 schema와 일반 배너 정책을 보존하면서 홈 aggregate AI 노출을 끄고 양쪽 추천 이벤트 배너의 상세 조회 노출 적격성을 일치시킨다.
**선행조건:** PRD 요구사항 확정 및 이 계획에 대한 별도 구현 실행 승인.
**Phase 완료 조건:** `P1-T1`, `P1-T2`, `P1-T3` 및 `P1-GATE` 완료와 실제 검증 결과 기록.
### Task 1: 홈 aggregate AI 빈 배열
- [x] **Task 1.1: 홈 aggregate AI 빈 배열**
**Goal 실행 `P1-T1`:** 홈 aggregate에서 AI recommendation 조회를 제거하고 응답의 기존 `aiCharacters` 필드를 모든 viewer에게 빈 배열로 유지한다.
- **시작 조건:** 사용자의 구현 실행 승인, `REC-AI-001~002` 확인.
- **완료 증거:** facade 단위 테스트에서 빈 배열과 query 비호출 확인, HTTP 테스트에서 seeded AI 대상에도 aggregate `[]`, 전용 AI 목록은 기존 식별자를 계속 반환.
- **범위 밖:** 전용 AI endpoint, snapshot/scheduler/data, 오디오 응답 schema.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacade.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacadeTest.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/HomeRecommendationControllerTest.kt`
**Interfaces:**
- Consumes: 기존 `HomeRecommendationFacade.getHomeRecommendations(member: Member?, lang: Lang): HomeRecommendationResponse` 및 `HomeRecommendationResponse.aiCharacters: List<HomeAiCharacterItem>`.
- Produces: 동일한 외부 서명과 DTO schema. aggregate constructor에 `aiCharacters = emptyList()`; 전용 AI paging은 기존 `queryService.findAiCharacterRecommendations(...)` 호출을 보존.
- [x] **RED:** facade test `shouldReturnEmptyAiCharactersWithoutQueryingAiRecommendations`를 추가한다. fake query port의 snapshot/detail/random AI 호출을 계수 또는 fail-fast로 계측하고 응답의 `aiCharacters`가 비었으며 호출이 0회임을 assert한다. Controller test의 기존 `shouldReturnTwentyAiCharactersOnHomeRecommendations`도 aggregate가 seeded AI 22개에도 `[]`인지, 필드가 존재하는지 확인하도록 바꾼다. `shouldExposeCreatorIdOnAiCharacterRecommendations`는 aggregate의 빈 배열을 확인하고 `characterId`/`creatorId` 검증을 dedicated endpoint 호출로 옮긴다. seeded 데이터와 dedicated 검증은 유지한다.
- [x] **RED 확인:** 두 기존 assertion 변경과 새 facade test가 구현 전 의도대로 실패하는지 두 focused class를 실행한다.
```bash
./gradlew test --tests "kr.co.vividnext.sodalive.v2.api.home.application.HomeRecommendationFacadeTest" --tests "kr.co.vividnext.sodalive.v2.api.home.HomeRecommendationControllerTest"
```
- [x] **GREEN:** facade aggregate에서 `aiCharacters = emptyList()`를 설정하고 aggregate의 `findAiCharacterRecommendations` 호출만 제거한다. 이제 쓰이지 않는 `HOME_AI_CHARACTER_LIMIT`만 제거한다.
- [x] **GREEN 확인:** 같은 두 focused class를 다시 실행해 facade와 controller test가 통과하는지 확인한다. Controller 응답은 익명, 미인증 회원, 인증 회원, ADMIN 각각 `aiCharacters: []`이며 KO/JA 변형에서도 동일하고, dedicated endpoint는 식별자를 반환한다.
```bash
./gradlew test --tests "kr.co.vividnext.sodalive.v2.api.home.application.HomeRecommendationFacadeTest" --tests "kr.co.vividnext.sodalive.v2.api.home.HomeRecommendationControllerTest"
```
- [x] **REFACTOR:** 이번 Task가 만든 중복만 정리하고 위 두 focused class를 재실행해 결과를 기록한다.
#### P1-T1 검증 기록 — 2026-10-31
- 공통 명령은 위 두 focused class 명령을 그대로 사용했다. 각 실행에서 `TMPDIR=/var/folders/yh/8xsbvpsj5wg2qnxzxdp11_gm0000gn/T/opencode/recommendation-ulw.nT00w2/p1-t1.UhWqcw`, `NODE_COMPILE_CACHE=$TMPDIR/node-compile-cache`, `BUN_RUNTIME_TRANSPILER_CACHE_PATH=$TMPDIR/bun-transpiler`를 export하고 `set -o pipefail` 및 `tee`로 로그를 보존했다.
- Java는 기본 OpenJDK `17.0.15`를 사용했다. `/usr/libexec/java_home -v17`은 등록 런타임을 찾지 못했지만 기본 Java가 이미 17이어서 변경하지 않았다.
- BASELINE: 제품/테스트 수정 전 facade 6개 + controller 28개 = 34개 통과, failures/errors/skipped 0, 종료 코드 0, `BUILD SUCCESSFUL in 50s`. 원문 `baseline.log`.
- RED: 제품 코드 변경 전에 동일 명령으로 42개 실행, 10개 실패, errors/skipped 0, 종료 코드 1, `BUILD FAILED in 46s`. facade 7개 중 신규 1개 실패, controller 35개 중 정책 변경 대상 9개만 실패했다. 원문 `red.log`.
- RED 원인: facade의 빈 응답 자체는 통과하지만 AI 최신 snapshot 조회·snapshot 존재 확인·상세 조회·fallback이 각각 1회여서 0회 assertion 4개가 실패했다. 기존 22개 seeded fixture의 익명/미인증/인증/ADMIN × KO/JA 8개와 기존 단일 fixture 집계는 비어 있지 않은 AI 배열 때문에 실패했다. dedicated `characterId`/`creatorId` assertion과 나머지 기존 검증은 삭제하지 않았다.
- GREEN: 집계의 AI query/map을 `emptyList()`로 교체하고 고아 `HOME_AI_CHARACTER_LIMIT`만 제거했다. 같은 focused 명령에서 facade 7개 + controller 35개 = 42개 통과, failures/errors/skipped 0, 종료 코드 0, `BUILD SUCCESSFUL in 44s`. `compileKotlin` 및 `compileTestKotlin`이 실제 실행되어 통과했다. 원문 `green.log`, 결과 XML/HTML은 기존 `build/test-results/test/`, `build/reports/tests/test/`에 남긴다.
- GREEN 확인 범위: fake의 AI snapshot/존재 확인/detail/random/fallback 호출은 모두 0회다. MockMvc에서 실제 seeded AI 22개에도 익명/미인증/인증/ADMIN × Accept-Language KO/JA 8개가 존재하는 빈 배열을 반환하고, 별도 단일 seeded AI는 dedicated endpoint에서 기존 `characterId`/`creatorId`를 반환했다. 기존 dedicated paging 및 익명 접근 거부 테스트도 통과했다. 인증 fixture는 실제 Auth row를 persist하고 flush/clear했다.
- REFACTOR/자체 검토: 수정한 facade·두 테스트를 다시 읽고 호출 경로와 assertion을 대조했다. 제품 변경은 집계 할당 및 고아 상수에만 한정되며 shared mapper, dedicated paging, DTO, snapshot/scheduler, 배너는 그대로다. 이번 변경으로 정리할 추가 중복이 없어 별도 코드 수정이나 추가 재실행은 하지 않고 위 GREEN 실행을 최종 focused 증거로 사용한다. scoped 자체 검토의 차단 이슈는 없다.
- 검증 제한: P1-T1 위임 범위와 중단 조건에 따라 전체 suite/build, `ktlintCheck`, 실제 서버 HTTP QA 및 P1-T2 이후 작업은 수행하지 않았다. 공유 경계 변경이 없는 단일 aggregate 변경이므로 두 focused class로 대체했고 최종 Gate 검증은 상위 실행자가 소유한다. `lsp_diagnostics` 도구는 없으며 실행했다고 주장하지 않는다. BASELINE부터 있던 Gradle deprecation과 embedded Redis 종료 reconnect 경고는 GREEN에도 존재하지만 실패는 아니다. commit/add/push 및 임시 증거 삭제는 하지 않았다.
### Task 2: 홈 추천 EVENT 배너 SQL 적격성
- [x] **Task 1.2: 홈 추천 EVENT 배너 SQL 적격성**
**Goal 실행 `P1-T2`:** 기존 홈 배너 DB 조회에 이벤트 상세 적격 조건을 limit 전 적용하고 기존 banner-own 필터·정렬 계약을 보존한다.
- **시작 조건:** `P1-T1` 완료, `REC-EVT-001~007` 확인.
- **완료 증거:** repository integration test에서 QueryDSL `EXISTS` 정책과 clock 경계를 검증하고 controller integration test에서 정책에 맞는 응답 확인.
- **범위 밖:** 오디오 repository, per-event service 조회, public port 변경, 일반 배너 조건 변경.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepositoryTest.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/HomeRecommendationControllerTest.kt`
**Interfaces:**
- Consumes: 기존 `findHomeBanners(limit: Int, memberId: Long?, includeAdultBanners: Boolean, lang: Lang)` 및 기존 회원의 resolved banner `lang`.
- Produces: 공개 메서드 서명 불변. 생성자에 기본값 clock `eventNowProvider`를 `nowProvider` 바로 앞에 추가하고 EVENT predicates에서만 query당 한 번 사용한다. 기존 최종 `nowProvider` parameter/trailing lambda는 reservation 검증에 그대로 쓴다.
- [x] **RED:** `shouldApplyHomeEventVisibilityPolicyBeforeLimit` parameterized DB integration test와 경계 테스트를 추가한다. 익명·미인증·인증·ADMIN × `isAdult=null/false/true`, active/hidden/future/expired/wrong-language, EVENT 대상 없음, 비-EVENT 불변을 검증한다. Auth/Member fixture를 저장하고 flush/clear한다. 교차 검증으로 인증+`includeAdultBanners=false`, 미인증+`includeAdultBanners=true`를 포함한다. 후보 1이 숨겨지고 후보 2가 limit=1로 반환되는 경우 및 전체 후보 숨김 시 `[]`를 확인한다. 기존 positive EVENT fixtures도 고정 event clock에서 적격인 값으로 정렬하되 검증 강도는 유지한다. `HomeRecommendationControllerTest.shouldApplyEventBannerDetailPolicyForHomeAggregate`는 네 조회자와 KO/JA 국가, Accept-Language 불일치까지 확인한다.
- [x] **RED 확인:** repository와 새 controller endpoint 테스트를 함께 실행해 현 구현에서 기간·언어·대상·limit assertion이 실패함을 확인한다.
```bash
./gradlew test --tests "kr.co.vividnext.sodalive.v2.recommendation.adapter.out.persistence.DefaultHomeRecommendationQueryRepositoryTest" --tests "kr.co.vividnext.sodalive.v2.api.home.HomeRecommendationControllerTest"
```
- [x] **GREEN:** `DefaultHomeRecommendationQueryRepository`의 홈 배너 query에만 EVENT 분기 predicate를 추가한다. `QMember` alias와 `JPAExpressions`로 audience를 `isAdult == null || viewer is ADMIN || (isAdult == true && matching Auth exists) || (isAdult == false && matching Auth absent)`로 판정한다. 익명은 Auth 없음으로 본다. event 존재/활성·시간·resolved banner language 조건 및 audience는 기존 predicate와 함께 order/limit 전에 적용한다.
- [x] **GREEN 확인:** 같은 두 focused class를 다시 실행해 repository 및 endpoint assertion의 성공을 확인한다. `eventNowProvider`와 기존 `nowProvider`를 서로 다른 시간으로 주입하여 event 시간의 포함 양끝·직전/직후, non-zero nanos 및 기존 UTC reservation 필터가 각각 독립됨을 검증한다.
```bash
./gradlew test --tests "kr.co.vividnext.sodalive.v2.recommendation.adapter.out.persistence.DefaultHomeRecommendationQueryRepositoryTest" --tests "kr.co.vividnext.sodalive.v2.api.home.HomeRecommendationControllerTest"
```
- [x] **REFACTOR:** 이번 Task가 만든 중복만 정리하고 동순위 random 순서에 의존하지 않게 집합과 orders로 확인한다. 기존 positive/negative 배너 및 API 테스트를 다시 실행한다. 기존 두 홈 repository 직접 생성 위치의 기본 인자와 trailing-lambda 호환성도 유지한다.
#### P1-T2 검증 기록 — 2026-10-31
- 상태: 구현·두 focused class 전체 통과·작성자 자체 검토 완료. 상위 실행자의 독립 리뷰·commit·최종 Gate는 대기하며 `P1-T3`는 착수하지 않았다. 수정 범위는 위 제품 파일 1개·테스트 2개와 본 Task 체크리스트/증거 및 활성 Goal뿐이다.
- 모든 테스트 실행은 아래 동일 명령을 사용했다. `TMPDIR=/var/folders/yh/8xsbvpsj5wg2qnxzxdp11_gm0000gn/T/opencode/recommendation-ulw.nT00w2/p1-t2.Z5xdEM`, `NODE_COMPILE_CACHE=$TMPDIR/node-compile-cache`, `BUN_RUNTIME_TRANSPILER_CACHE_PATH=$TMPDIR/bun-transpiler`, `JAVA_HOME=/Users/klaus/.local/share/mise/installs/java/liberica-17.0.15+10`를 매 shell에서 export했다. `set -o pipefail`과 `tee`로 원문을 보존했으며 확장 RED/GREEN의 화면 출력만 `rg --line-buffered '(^> Task|FAILED|tests completed|BUILD )'`로 요약했다.
```bash
./gradlew test --tests kr.co.vividnext.sodalive.v2.recommendation.adapter.out.persistence.DefaultHomeRecommendationQueryRepositoryTest --tests kr.co.vividnext.sodalive.v2.api.home.HomeRecommendationControllerTest
```
- BASELINE: 수정 전 repository 98개 + controller 35개 = 133개, failures/errors/skipped 0, 종료 코드 0, `BUILD SUCCESSFUL in 36s`. 원문 `baseline.log`.
- 최초 RED: 제품/생성자를 변경하지 않고 2000~2100의 넓은 event window와 실제 Member/Auth fixture로 실행했다. repository 120개 중 14개 + controller 43개 중 8개 = 163개 중 22개 assertion 실패, errors/skipped 0, 종료 코드 1, `BUILD FAILED in 57s`. 기간/언어 부적격 이벤트에 `expected [] / actual [hidden]`, 인증 대상에 `expected [all,false] 또는 [all,true] / actual [all,false,true]`, limit=1에 `expected visible-second / actual hidden-first`, endpoint 배너 수에 `expected 2/3 / actual 6` 등을 확인했다. 원문 `red.log`. 기존 AI 빈 배열·dedicated endpoint assertion은 그대로 유지됐다.
- 추가 RED: 최초 assertion RED 뒤에만 optional clock 인자를 추가하고 repository 테스트에 명시적으로 주입했다. event predicate 구현 전 nanos 경계 15개를 추가해 시작/종료/동일 양끝의 포함과 1ns 밖 제외를 검증했다. 첫 실행은 `compileTestKotlin` 중 shell 제한 120000ms로 중단됐으며 assertion 결과로 세지 않았다(`red-boundaries.log`). 수정 없이 360000ms 제한으로 재실행하여 repository 135개 중 20개 + controller 43개 중 8개 = 178개 중 28개 assertion 실패, errors/skipped 0, 종료 코드 1, `BUILD FAILED in 4m 3s`를 확인했다. BEFORE/AFTER 6개가 추가로 `expected [] / actual [boundary]`였다. 원문 `red-boundaries-retry.log`.
- GREEN: EVENT 분기에만 활성·`startDate <= eventNow <= endDate`·resolved `lang`·audience AND를 추가했다. 익명은 null/false, 회원은 null 또는 `QMember("eventViewer")` ADMIN EXISTS 또는 true/Auth EXISTS 또는 false/Auth NOT EXISTS다. Auth는 `auth.member.id == memberId`로 조회하여 기존 AuthRepository 판정과 같다. query당 event clock을 한 번 캡처하며 `LocalDateTime.now()` 기본값의 system-zone/nanos를 보존한다. 기존 `nowProvider`는 마지막 UTC lambda이고 배너 예약의 초 정밀도 판정은 변경하지 않았다.
- GREEN 결과: 위 동일 명령(600000ms 제한)에서 repository 135개 + controller 43개 = 178개 모두 통과, failures/errors/skipped 0, 종료 코드 0, `BUILD SUCCESSFUL in 1m 27s`. `compileKotlin`·`compileTestKotlin`·`:test`가 실제 실행됐다. 원문 `green.log`; 최종 XML은 `build/test-results/test/TEST-kr.co.vividnext.sodalive.v2.recommendation.adapter.out.persistence.DefaultHomeRecommendationQueryRepositoryTest.xml`과 `TEST-kr.co.vividnext.sodalive.v2.api.home.HomeRecommendationControllerTest.xml`, HTML은 `build/reports/tests/test/`다. 임시 root의 `evidence.md`에도 counts·경계·제한을 보존했다.
- DB 증거: flush/clear한 Member/Auth와 이벤트/배너로 4 viewer × null/false/true × KO/JA, 다른 회원의 Auth가 있는 미인증 조회자, 인증+배너 성인 노출 false / 미인증+true, ADMIN audience만 우회, 배너 자체 활성/탭/언어/예약/성인 조건, 누락·비활성·미래·만료·다른 언어 이벤트, hidden-first/eligible-second limit=1, 전부 제외 `[]`, LINK/CREATOR/SERIES 불변을 검증했다. 생성 SQL에서 EVENT의 시간/언어/audience 조건과 `member.id/role` EXISTS 및 `auth.member_id` EXISTS/NOT EXISTS가 `orders asc, rand() asc limit ?` 앞에 있음을 직접 확인했다. 운영 DB에는 접근하지 않았다.
- clock/저장 정밀도 증거: event clock `2026-10-31T23:59:59`의 nanos 0/123456789/999999999와 banner UTC clock `2026-10-27T23:59:59.999999999`를 별도로 사용했다. H2 테스트의 event start/end만 `timestamp(9)`로 설정해 flush/clear/reload 후 고정 기대 시각과 정확히 같음을 확인했다. event 1ns 비교와 기존 banner 시작=종료의 초 포함 경계가 함께 통과했다. 운영 Event DDL은 저장소에서 찾지 못했으며 이 증거는 query 비교 정밀도 검증이지 운영 MySQL 저장 정밀도 검증이 아니다. 운영 schema·timezone·formatter 변경은 없다. 기존 positive saveEvent도 고정 event clock ±1일로 맞췄다.
- endpoint 증거: 기존 `@SpringBootTest` MockMvc에서 익명/미인증/인증/ADMIN × `CloudFront-Viewer-Country` KR/JP와 반대 `Accept-Language` ja/ko 8개가 성공했고 적격 이벤트 ID의 전체 개수와 정확한 순서를 검증했다. 모두 `aiCharacters`가 존재하는 배열이면서 비었다. 실제 Auth와 preference row를 저장/flush/clear했고 국가 고정 매핑 대상 ID(16/17 등)는 정책 테스트 fixture에서 피했다. 기존 강제 국가 정책 자체는 변경하지 않았다.
- REFACTOR/자체 검토: PRD/Global Constraints·호출자(facade→query service→repository)·AuthRepository 및 EventDetailService와 제품 diff/테스트 전체를 대조했다. 조건은 EVENT OR 분기에만 있고 banner-own 조건·다른 target 분기·creator-block·정렬/limit는 보존됐다. 기존 3인자 기본 생성과 named event clock + trailing banner clock 생성 모두 컴파일됐고 전체 focused 검증을 통과했다. 추가 중복 정리가 필요하지 않아 GREEN 뒤 제품/테스트를 다시 변경하지 않았다. 작성자 자체 검토의 차단 이슈는 없다.
- 검증 제한: 위임 중단 조건에 따라 전체 suite/build·ktlint·실제 서버 HTTP QA·오디오/상세/subBanner 회귀 및 독립 리뷰는 상위 Gate에 남긴다. 이번 검증은 실제 H2 QueryDSL과 SpringBootTest MockMvc endpoint 증거다. `lsp_diagnostics` 도구는 없으며 실행했다고 주장하지 않는다. BASELINE부터의 Gradle deprecation 및 embedded Redis 종료 reconnect 경고는 GREEN에도 있으나 실패는 아니다. `git diff --check` 종료 코드 0; commit/add/push, subagent 호출 및 임시 증거 삭제는 하지 않았다.
#### P1-T2 커밋 훅 포맷 보정 — 2026-10-31
- 상위 실행자가 독립 기능 리뷰 후 시도한 commit은 ktlint 훅에서 실패했고 commit은 생성되지 않았다. `build/reports/ktlint/ktlintTestSourceSetCheck/ktlintTestSourceSetCheck.txt`의 신규 테스트 포맷 오류 17건을 확인했다. 두 테스트의 새 CSV 인자 줄바꿈, multiline if/else 중괄호, persist/apply 괄호 줄바꿈만 `apply_patch`로 수정했다. 제품 동작·fixture 값·assertion·테스트 수는 변경하지 않았으며 전체 formatter는 실행하지 않았다.
- 기존 P1-T2 임시 경로·Java 17·cache 환경 변수를 매 shell에서 동일하게 export하고 `set -o pipefail`/`tee`로 보존했다. `./gradlew ktlintCheck`는 종료 코드 0, `BUILD SUCCESSFUL in 29s`; main/test source check가 실제 실행됐고 test ktlint 보고서는 0줄이다. 원문 `p1-t2.Z5xdEM/lint-fix-ktlint.log`.
- 이어서 위 P1-T2의 동일한 두 클래스 focused 명령을 실행했다. repository 135개 + controller 43개 = 178개 모두 통과, failures/errors/skipped 0, 종료 코드 0, `BUILD SUCCESSFUL in 1m 8s`; `compileTestKotlin`과 `:test`가 실제 실행됐다. 원문 `p1-t2.Z5xdEM/lint-fix-tests.log`. 최종 XML timestamp는 repository `2026-10-31T11:31:59`, controller `2026-10-31T11:31:46`다.
- 보정 diff를 확인해 신규 테스트 포맷 변경만 있음을 대조했고 `git diff --check` 종료 코드 0을 확인했다. 이번 보정은 formatting-only로 별도 RED/신규 테스트를 추가하지 않고 기존 focused 테스트로 회귀를 확인했다. 전체 suite/build·subagent·git add/commit/amend는 실행하지 않았으며 상위 실행자가 수정분을 stage하고 새 commit을 재시도한다.
### Task 3: 오디오 추천 EVENT 배너 SQL 적격성
- [x] **Task 1.3: 오디오 추천 EVENT 배너 SQL 적격성**
**Goal 실행 `P1-T3`:** 오디오 추천의 기존 `findBanners` 조회에 홈과 같은 이벤트 상세 정책을 limit 전에 적용하고 현재 audio banner 조건과 응답 schema를 보존한다.
- **시작 조건:** `P1-T2` 완료, PRD `REC-EVT-001~007` 확인.
- **완료 증거:** 오디오 repository integration test가 홈과 같은 eligibility matrix를 통과하고 `AudioRecommendationsResponse` schema가 유지됨.
- **범위 밖:** 홈 query 변경, `AudioRecommendationsResponse` 필드 추가, subBanner·LINK 동작 변경.
**Files:**
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepository.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepositoryTest.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/content/recommendation/adapter/in/web/AudioRecommendationEndToEndTest.kt`
**Interfaces:**
- Consumes: 기존 `findBanners(limit: Int, memberId: Long?, canViewAdultContent: Boolean, lang: Lang)` 및 현재 banner language.
- Produces: 공개 repository/facade/DTO 서명 불변. `eventNowProvider`를 `nowProvider` 바로 앞 constructor parameter로 추가하고 EVENT 조건만 사용; 기존 `nowProvider` trailing lambda는 banner reservation 전용 유지.
- [x] **RED:** `shouldApplyAudioEventVisibilityPolicyBeforeLimit` parameterized DB integration test를 추가한다. Task 2와 같은 viewer × audience, 이벤트 active/time/lang, admin 제한, 누락 EVENT, non-EVENT, banner adult 교차 조합을 flush/clear 후 검사한다. 후보 1이 숨겨지고 후보 2가 limit=1로 반환되는 경우와 전부 숨겨져 `[]`인 경우를 검증한다. 기존 positive EVENT fixtures를 고정 event clock에서 적격인 값으로 맞추되 검증 강도는 유지한다. `AudioRecommendationEndToEndTest.shouldApplyEventBannerDetailPolicyAndKeepAudioResponseSchema`를 추가해 KO/JA country와 Accept-Language 불일치 및 조회자별 결과, `aiCharacters` 부재를 확인한다.
- [x] **RED 확인:** repository와 새 end-to-end endpoint 테스트를 함께 실행해 현재 query가 기간·언어·성인 audience를 강제하지 않아 추가한 assertion이 실패함을 확인한다. 기존 audio 필드 부재 assertion은 현재도 통과하는 계약 보존 검사로 구분한다.
```bash
./gradlew test --tests "kr.co.vividnext.sodalive.v2.content.recommendation.adapter.out.persistence.DefaultAudioRecommendationQueryRepositoryTest" --tests "kr.co.vividnext.sodalive.v2.api.content.recommendation.adapter.in.web.AudioRecommendationEndToEndTest"
```
- [x] **GREEN:** 오디오 repository의 기존 EVENT active branch에만 홈과 같은 `QMember`/`JPAExpressions` audience (`null || ADMIN || (true && Auth exists) || (false && Auth absent)`), event time, event language predicate를 추가한다. ADMIN은 audience만 제외한다. 기존 `adultBannerCondition(canViewAdultContent)`, tab/lang/reservation/target predicate 및 order/limit은 보존한다.
- [x] **GREEN 확인:** 같은 두 focused class를 다시 실행해 repository와 endpoint assertion의 성공을 확인한다. 별도 event clock의 system-default 시각 및 nanos 경계와 banner UTC reservation clock을 서로 다르게 설정해 독립성을 검증한다.
```bash
./gradlew test --tests "kr.co.vividnext.sodalive.v2.content.recommendation.adapter.out.persistence.DefaultAudioRecommendationQueryRepositoryTest" --tests "kr.co.vividnext.sodalive.v2.api.content.recommendation.adapter.in.web.AudioRecommendationEndToEndTest"
```
- [x] **REFACTOR:** 이번 Task가 만든 중복만 정리하고 random tie 고정 순서 assertion을 피한다. 아래 두 focused class를 실행하고 기존 DTO field set 및 repository 생성자의 trailing-lambda 호환성을 확인한다.
```bash
./gradlew test --tests "kr.co.vividnext.sodalive.v2.content.recommendation.adapter.out.persistence.DefaultAudioRecommendationQueryRepositoryTest"
./gradlew test --tests "kr.co.vividnext.sodalive.v2.api.content.recommendation.adapter.in.web.AudioRecommendationEndToEndTest"
```
#### P1-T3 검증 기록 — 2026-10-31
- 상태: 오디오 EVENT 정책 구현·두 focused class 전체·`ktlintCheck`·작성자 자체 검토 완료. 상위 실행자의 독립 리뷰·commit·최종 Gate는 대기한다. 변경은 본 Task의 제품 1개·테스트 2개와 본 문서의 활성 Goal/Task3 체크리스트·증거에 한정했다. 홈 구현 `1f24a4b7`은 의미상 기준으로 읽기만 했다.
- 각 shell에서 `TMPDIR=/var/folders/yh/8xsbvpsj5wg2qnxzxdp11_gm0000gn/T/opencode/recommendation-ulw.nT00w2/p1-t3.6bJWqa`, `NODE_COMPILE_CACHE=$TMPDIR/node-compile-cache`, `BUN_RUNTIME_TRANSPILER_CACHE_PATH=$TMPDIR/bun-transpiler`, `JAVA_HOME=/Users/klaus/.local/share/mise/installs/java/liberica-17.0.15+10`를 export했다. 아래 동일 명령을 매번 600000ms 제한으로 실행했고 `set -o pipefail`/`tee`로 원문을 보존했다. 화면만 `rg --line-buffered '(^> Task|FAILED|tests completed|BUILD )'`로 요약했다.
```bash
./gradlew test --tests kr.co.vividnext.sodalive.v2.content.recommendation.adapter.out.persistence.DefaultAudioRecommendationQueryRepositoryTest --tests kr.co.vividnext.sodalive.v2.api.content.recommendation.adapter.in.web.AudioRecommendationEndToEndTest
```
- BASELINE: 제품·테스트 수정 전 repository 29개 + E2E 2개 = 31개 통과, failures/errors/skipped 0, 종료 코드 0, `BUILD SUCCESSFUL in 44s`. 원문 `baseline.log`.
- 최초 RED: 기존 생성자 그대로, 이벤트 기간 2000~2100 및 실제 Member/Auth를 저장·flush/clear한 테스트로 repository 51개 중 14개 + E2E 10개 중 8개 = 61개 중 22개 assertion 실패, errors/skipped 0, 종료 코드 1, `BUILD FAILED in 55s`. `expected all|false 또는 all|true / actual all|false|true`, 숨김 이벤트 `expected [] / actual [hidden]`, limit=1 `expected visible-second / actual hidden-first`, endpoint 배너 `expected 2 또는 3 / actual 6`을 확인했다. AI 필드 부재 assertion은 배너 수 assertion보다 먼저 통과했다. 원문 `red.log`.
- 경계 RED: 최초 assertion RED 이후에만 optional `eventNowProvider`를 추가하고 주입했다. predicate 구현 전 고정 event clock ±1일 fixture 및 nanos 경계 15개를 추가해 repository 66개 중 20개 + E2E 10개 중 8개 = 76개 중 28개 assertion 실패, errors/skipped 0, 종료 코드 1, `BUILD FAILED in 2m`. BEFORE/AFTER 6개가 추가로 `expected [] / actual [boundary]`였고 DB 시각의 정확한 왕복·포함 경계 9개는 통과했다. 원문 `red-boundaries.log`.
- GREEN: 홈과 같은 EVENT 활성·포함 기간·resolved `lang`·audience 조건을 추가했다. 익명은 null/false, 로그인 회원은 null 또는 `QMember("eventViewer")` ADMIN EXISTS 또는 true/Auth EXISTS 또는 false/Auth NOT EXISTS이며 Auth는 `auth.member.id == memberId`를 따른다. repository 66개 + E2E 10개 = 76개 모두 통과, failures/errors/skipped 0, 종료 코드 0, `BUILD SUCCESSFUL in 54s`. `compileKotlin`·`compileTestKotlin`·`:test`가 실제 실행됐다. 원문 `green.log`; XML timestamp는 E2E `2026-10-31T11:42:37`, repository `2026-10-31T11:42:45`다. 최종 결과는 `build/test-results/test/`의 두 클래스 XML 및 `build/reports/tests/test/`에 있고 임시 root의 `evidence.md`에도 요약했다.
- DB 검증: 4 viewer × KO/JA × null/false/true audience, 인증+`canViewAdultContent=false` / 미인증+true, 다른 회원의 인증 row, ADMIN audience만 우회, 누락·비활성·미래·만료·잘못된 언어 이벤트, hidden-first/eligible-second limit=1, 모두 숨김 `[]`, LINK/CREATOR/SERIES 불변과 배너 자체 활성·tab2·언어·UTC 예약·성인 조건을 확인했다. 생성 SQL에서도 EVENT 조건 및 `member.id/role` EXISTS와 `auth.member_id` EXISTS/NOT EXISTS가 `orders asc, rand() asc limit ?` 앞에 있음을 직접 읽었다.
- clock/저장 정밀도: event clock `2026-10-31T23:59:59`의 nanos 0/123456789/999999999와 banner UTC clock `2026-10-27T23:59:59.999999999`를 다르게 주입했다. H2 event start/end만 `timestamp(9)`로 설정하고 flush/clear/reload 값과 고정 시각을 정확히 비교했다. 이벤트 시작·종료·양끝 동일 포함, 1ns 직전/직후 제외 및 배너 예약 시작=종료의 기존 초 경계를 함께 검증했다. 이 H2 설정은 predicate 나노초 비교 증거이지 운영 저장 정밀도 증거가 아니다. 운영 Event DDL은 저장소에서 찾지 못했으며 운영 schema·timezone·formatter는 변경하지 않았다.
- endpoint 검증: 기존 `@SpringBootTest`/MockMvc와 별도 `TransactionTemplate` fixture로 실제 persistence를 거쳐 익명/미인증/인증/ADMIN × KR/JP 및 반대 Accept-Language ja/ko 8개가 적격 이벤트의 정확한 ID·개수·순서를 반환하고 `aiCharacters`는 필드 자체가 없음을 확인했다. Auth/preference row를 저장·flush/clear·commit하고 강제 국가 매핑 ID는 피했다. 새 fixture는 이 클래스 전용 H2 DB의 기존 배너를 정리해 parameterized 실행을 격리한다. 기존 추천 섹션·번역 테스트는 약화하지 않았다.
- lint/자체 검토: `./gradlew ktlintCheck` 종료 코드 0, `BUILD SUCCESSFUL in 24s`이며 test/main lint 실행이 성공했다. 원문 `ktlint.log`. 제품·테스트 diff와 facade→query service→repository의 memberId/resolved lang 흐름, 상세 서비스/AuthRepository, 기존 DTO를 대조했다. 공개 port 인자·DTO·홈·상세·subBanner·설정·schema는 불변이고 event clock은 query당 한 번, 절삭 없이 사용한다. 마지막 UTC `nowProvider` trailing lambda와 Spring 기본 인자 생성 모두 컴파일·실행됐다. 추가 중복 정리가 필요하지 않아 GREEN 후 제품·테스트를 다시 변경하지 않았으며 위 GREEN을 최종 focused 증거로 사용한다. 자체 검토 차단 이슈 없음, `git diff --check` 종료 코드 0.
- 검증 제한: 위임 중단 조건과 단일 오디오 조회 변경 범위에 따라 전체 suite/build·실제 서버 HTTP QA·홈/상세/subBanner 직접 회귀·독립 리뷰는 상위 Gate에 남긴다. 실행 증거는 H2 QueryDSL과 MockMvc이며 운영 MySQL 또는 실제 HTTP 검증으로 주장하지 않는다. LSP 도구는 없고 실행하지 않았다. BASELINE부터의 Gradle deprecation 및 embedded Redis 종료 reconnect 경고는 GREEN에도 있으며 테스트 실패는 없다. GREEN XML에는 오디오 변경과 무관한 H2 `chat_character_value` DDL 및 scheduler `skip locked` 로그도 있으나 suite errors/failures는 0이다. commit/add/push·subagent·임시 증거 삭제는 하지 않았다.
### Phase 1 Gate: 양 endpoint 정책 및 회귀 판정
**Goal 실행 `P1-GATE`:** 모든 확정 요구사항이 두 추천 endpoint의 응답과 repository 정책에서 일치하고 범위 밖 응답이 보존되는지 판정한다.
- **시작 조건:** `P1-T1`, `P1-T2`, `P1-T3` 완료 및 각 focused evidence 기록.
- **완료 증거:** 아래 회귀 테스트와 `ktlintCheck` 통과, 정책 매트릭스·AI 미호출·schema 유지 증거 Progress 기입.
- **범위 밖:** API 계약, 전용 AI endpoint, event detail 정책 자체 변경; 테스트 삭제·skip·완화.
- **TDD 예외 사유:** Gate는 새 동작을 구현하지 않는 validation-only 판정 goal이다. Gate에서 처음 발견된 요구사항 assertion은 소유 Task (`P1-T1`의 홈 테스트, `P1-T2`의 홈 테스트, `P1-T3`의 오디오 테스트)의 RED cycle에 추가한 뒤 gate를 재실행한다.
- **대체 검증 방법:** 아래 focused·직접 영향 회귀 명령 및 수용 기준 대조 결과를 Progress에 기록한다.
**수행 검증 명령:**
```bash
./gradlew test --tests "kr.co.vividnext.sodalive.v2.recommendation.adapter.out.persistence.DefaultHomeRecommendationQueryRepositoryTest" --tests "kr.co.vividnext.sodalive.v2.content.recommendation.adapter.out.persistence.DefaultAudioRecommendationQueryRepositoryTest"
./gradlew test --tests "kr.co.vividnext.sodalive.v2.api.home.HomeRecommendationControllerTest" --tests "kr.co.vividnext.sodalive.v2.api.content.recommendation.adapter.in.web.AudioRecommendationEndToEndTest"
./gradlew test --tests "kr.co.vividnext.sodalive.v2.api.event.EventDetailControllerIntegrationTest" --tests "kr.co.vividnext.sodalive.v2.subbanner.adapter.in.web.RecommendationSubBannerIntegrationTest"
./gradlew test --tests "kr.co.vividnext.sodalive.v2.recommendation.application.HomeRecommendationQueryServiceTest" --tests "kr.co.vividnext.sodalive.v2.content.recommendation.application.AudioRecommendationQueryServiceTest"
./gradlew ktlintCheck
```
Event detail regression은 기존 상세 endpoint가 바뀌지 않았음을 검증한다. subBanner regression은 두 추천 API의 기존 subBanner 동작을 검증한다. API test는 익명·미인증·인증·ADMIN, KO/JA와 country/request-language 불일치, 배너 자체 성인/활성 조건, audio에 AI 필드 없음 및 dedicated AI paging 존속을 확인한다. 전체 suite/build는 위 변경으로 공통 경계까지 영향받거나 targeted 회귀로 실패 원인을 판정할 수 없을 때만 실행하고 생략 근거를 기록한다. 이 문서 작성에서는 어떤 명령도 실행하지 않는다.
- [x] 위 focused repository/API 및 직접 영향 회귀 범위를 최종 전체 테스트에서도 확인했다.
- [x] 두 endpoint의 이벤트 정책 매트릭스, 시간 clock 독립성, limit 전 필터, 빈 결과 동작을 기록했다.
- [x] 홈 aggregate AI empty/query 미호출과 dedicated AI endpoint 보존을 검증했다.
- [x] 오디오 schema 및 양쪽 `subBanners`가 변하지 않았음을 검증했다.
- [x] `ktlintCheck`와 전체 빌드 결과를 기록했다. 전체 회귀를 생략하지 않았으며 기본 환경 실패 및 UTC 재검증 조건을 구분했다.
## Dependency Order
| 순서 | Goal | 의존성 | 상태 |
|---:|---|---|---|
| 1 | `P1-T1` 홈 aggregate AI empty | 구현 승인 | 완료 · `4a6b2ee9` |
| 2 | `P1-T2` 홈 EVENT query | `P1-T1` | 완료 · `1f24a4b7` |
| 3 | `P1-T3` 오디오 EVENT query | `P1-T2` | 완료 · `969f999a` |
| 4 | `P1-GATE` endpoint parity/regression | `P1-T1`~`P1-T3` | 완료 · UTC 전체 빌드 및 실제 HTTP PASS |
## Progress
### 구현 실행 승인 — 2026-10-31
- 사용자 `문서대로 진행` 및 `ulw` 지시에 따라 `P1-T1`부터 순서대로 실행한다. 아래 기존 문서 작성 기록은 당시 증거로 보존한다.
- 현재 `test` 브랜치에서 진행하며 새 worktree를 자동 생성하지 않는다. 구현 전 tracked 파일 변경은 없고 기존 문서 두 개만 untracked였다.
- 최종 Gate는 사용자 요청에 따라 전체 테스트·빌드·실제 HTTP QA를 포함한다. `lsp_diagnostics`는 현재 도구에 없으므로 실행했다고 보고하지 않고 Kotlin 컴파일·ktlint 결과로 가능한 진단을 기록한다.
### 초기 문서 작성 당시 기록 (구현 승인 전)
- 문서 작성: PRD와 plan-task를 정합시켰고 sample plan, EventDetailService, 두 repository, DTO 및 관련 테스트 경로를 확인했다.
- 구현 상태: 미착수. 제품 코드·테스트·설정 변경 없음.
- 검증 상태: PRD 독립 검토, 계획 자체 검토 및 두 문서 공백 검사를 완료했다. Gradle test, `ktlintCheck`, build는 실행하지 않았다.
- 다음 조건: 사용자의 별도 구현 실행 승인 후 `P1-T1`부터 하나씩 활성화한다.
## Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 Goal/문서 |
|---|---|---|---|---|---|
| 2026-10-31 | `PLAN-001` | 범위 확정 | 기존 public service/port signature를 유지하고 두 repository의 기존 QueryDSL EVENT 조건에만 SQL predicate를 적용한다. | 기존 repository 구조를 따른 구현 계획 선택 | `P1-T2`, `P1-T3` |
| 2026-10-31 | `PLAN-002` | 범위 확정 | 이벤트 시간용 system-default clock을 각 repository에 분리 주입하며 기존 UTC `nowProvider`는 예약 필터에 유지한다. 시간은 query당 한 번 캡처하고 nano를 절삭하지 않는다. | `EventDetailService`의 local `LocalDateTime.now()`와 repository의 UTC reservation clock 사용처 대조 | `P1-T2`, `P1-T3` |
| 2026-10-31 | `PLAN-003` | 보존 | 인증은 `AuthRepository.getAuthIdByMemberId`와 같은 `Auth.member.id` 존재 subquery로 판단하며 ADMIN은 이벤트 audience predicate만 우회한다. | AuthRepository의 inner join 및 member ID 필터와 제품 결정 | `P1-T2`, `P1-T3` |
## 문서 검증 기록
### P1-GATE 실행 기록 — 2026-10-31
- 세 구현 Task의 독립 리뷰가 모두 명세·품질 승인으로 종료됐다. T2 포맷만 보정한 후 178개 회귀와 ktlint를 재검증했고 커밋 훅도 통과했다.
- 실제 HTTP 검증: `http-qa.md`에 기록한 테스트 서버 요청 104건·판정 216건 모두 PASS. 임시 harness의 Redis 설정 호출 오류를 고친 후 제품 코드 수정 없이 30초에 통과했다.
- 최초 `./gradlew build`는 bootJar 생성 및 lint 단계를 거친 뒤 `:test` 중 도구 제한 600초로 종료됐다. 테스트 assertion 실패나 성공으로 기록하지 않는다. 남은 test executor가 없음을 확인하고 1800초 제한의 전체 빌드로 재실행 중이다.
- 최종 Oracle 리뷰 및 전체 빌드 결과, 자원 정리 확인은 완료 후 아래에 누적한다.
#### 전체 실행 실패 분리 및 최종 구현 리뷰
- 1800초 제한의 기본 환경 전체 `./gradlew build`는 18분 20초에 종료 코드 1로 끝났다. XML 336개, 테스트 2892개 중 2890개 통과·2개 실패·오류/skip 0이다.
- 실패 1: `LegacyCurrentNameReadIntegrationTest.shouldLocalizeCreatorDonorsIndependentlyOfTheChannelOwner`의 `totalCount`는 기대 2, 실제 0이었다. 해당 기존 테스트와 후원 서비스는 이번 변경 대상이 아니다. `ChannelDonationService`는 KST 월 범위를 UTC 값으로 비교하지만 fixture는 기본 시간대 `LocalDateTime`으로 생성한다. 월말 KST 늦은 시각에 나타나는 환경 의존성을 확인했다.
- 실패 2: init script 없이 일반 빌드에서 발견된 임시 `RecommendationSocketQaTest` 컴파일 잔존물이었다. QA 전용 system property가 없어 HTTP 실행 전 NPE가 났다. 작업 소유 `RecommendationSocketQaTest*.class`만 삭제하고 `build/classes`·`build/tmp/kapt3`에서 해당 클래스가 남지 않았음을 확인했다. 테스트 제외 옵션이나 skip을 추가하지 않았다.
- 후원 테스트 한 개를 기본 환경에서 분리 실행해 동일한 기대 2/실제 0을 재현했다. 같은 코드·assertion을 `JAVA_TOOL_OPTIONS=-Duser.timezone=UTC ./gradlew test --rerun --tests 'kr.co.vividnext.sodalive.v2.creatorname.application.LegacyCurrentNameReadIntegrationTest.shouldLocalizeCreatorDonorsIndependentlyOfTheChannelOwner'`로 실행하면 42초, 종료 코드 0이다. 범위 밖 테스트나 서비스 코드를 고치지 않았다.
- Ruling: 운영·저장소 시간대 설정은 보존하고 최종 전체 검증 명령에만 UTC JVM 환경을 명시한다. 근거는 위 단일 실패의 환경 분리 결과다. 한계는 기본 KST 환경의 월말 기존 테스트 결함이 해결되는 것은 아니라는 점이며 최종 보고에 남긴다.
- Oracle 작업은 완료 알림 후 결과 조회가 두 번 실패하고 세션도 조회되지 않아 승인 근거로 사용할 수 없었다. 사용 가능한 고성능 reviewer로 한 번 대체한 최종 읽기 전용 리뷰는 세 커밋 전체 제품 3개·테스트 5개를 검토해 명세·품질을 무조건 승인했고 구현 차단 사항은 없었다. 변경된 테스트 261개 및 인접 회귀 94개, 총 355개가 직전 전체 실행에서 통과했음을 XML로 대조했다.
- QA 판정과 기본 환경 전체 실행의 실패 사실은 보존한다. UTC 환경의 전체 재검증은 별도 결과로 아래에 누적하며 기본 환경의 전체 성공으로 바꾸어 기록하지 않는다.
#### 최종 UTC 검증 완료
- 명령: `JAVA_TOOL_OPTIONS=-Duser.timezone=UTC ./gradlew build`. init script·테스트 skip/filter·rerun 옵션 없이 실행했다. 실행 후 환경 변수가 후속 셸에 남지 않았음을 확인했다.
- 결과: `BUILD SUCCESSFUL in 16m 34s`, 종료 코드 0. XML 335개·테스트 2891개 모두 이번 실행에서 갱신됐고 failures/errors/skipped 0이다. 임시 QA 클래스는 실행 대상에 없다.
- `LegacyCurrentNameReadIntegrationTest`도 UTC에서 8개 전부 통과했다. 기본 KST 월말 환경의 기존 실패는 별도 후속 사항으로 남긴다.
- main ktlint 검사 완료·위반 0. test 및 Kotlin script 검사는 변경 없는 입력으로 UP-TO-DATE이며 해당 보고서도 위반 0이다. 앞선 Task3의 명시적 `ktlintCheck` 역시 통과했다.
- bootJar: `build/libs/sodalive-0.0.1-SNAPSHOT.jar`, 148263078 bytes, SHA-256 `627ae298d255d00586b217b00e481f419484426bcfd4728e2de119ff13d44366`. 최초 기본 빌드에서 생성한 동일 제품 산출물이며 마지막 빌드에서는 UP-TO-DATE였다.
- 실제 HTTP 104건·216판정 PASS, 개별 및 최종 구현 리뷰 승인으로 요청 범위의 Gate를 완료한다. LSP 도구 없음 및 운영 MySQL Event 저장 정밀도 미확인은 그대로 명시한다.
- 마지막 빌드의 runner 76003·Gradle client 76012·test executor 76029가 모두 종료됐음을 확인했다. 공유 Gradle/Kotlin daemon은 건드리지 않았다. 임시 디렉터리 정리 영수증은 아래에 이어 기록한다.
- 정리 완료: 작업 소유 `recommendation-ulw.nT00w2`와 그 아래 6개 Task/QA 디렉터리 및 notepad를 삭제하고 부재를 확인했다. 임시 QA 컴파일 클래스도 제거됐다. 마지막 프로세스 조회에서 Gradle wrapper·test executor·Redis 서버는 남지 않았다. 공유 캐시·daemon 및 기존 다른 작업 디렉터리는 변경하지 않았다.
- 원문 임시 로그를 정리하기 전에 실행 명령·집계·실패 원인·재검증 조건은 본 계획에, 실제 HTTP 응답 발췌는 `http-qa.md`에 보존했다. 영구 테스트 XML/HTML과 bootJar는 기존 `build/` 산출물로 유지한다.
### 초기 문서 전용 검증 기록 (구현 승인 전)
- 2026-10-31 문서 전용 검증: `REC-AI-001`은 `P1-T1`, `REC-AI-002`는 `P1-T3` 및 Gate, `REC-EVT-001~007`은 `P1-T2`·`P1-T3` 및 Gate로 추적함을 확인했다. 파일 책임표·검증 명령·기존 API 계약도 대조했다.
- PRD 독립 builder check는 중요한 미결정 사항 및 소스 모순이 없다고 판정했다. 계획은 자체 검토로 RED/GREEN 순서, 기존 테스트 보존, 시각 기준 분리 및 요구사항 추적을 확인했다. 최종 계획에 대한 별도 독립 리뷰나 구현 동작 검증으로 확대 해석하지 않는다.
- TDD 예외 사유: 현재 산출물은 문서 두 개뿐이다. 대체 검증은 정합성 대조와 신규 파일 각각의 공백 검사다.
- 아래 명령에서 공백 오류 출력은 없었다. 최종 재확인한 `--no-index` 종료 코드는 신규 파일 차이를 뜻하는 1이며, 이전의 종료 코드 0 기록은 정정한다. 신규 파일은 일반 `git diff --check`만으로 검사되지 않으므로 `/dev/null`과 직접 비교했고, staging 후 `git diff --cached --check`로 다시 검증한다.
```bash
GIT_MASTER=1 git diff --no-index --check /dev/null docs/20261031_추천화면AI캐릭터및이벤트배너노출정책/prd.md
GIT_MASTER=1 git diff --no-index --check /dev/null docs/20261031_추천화면AI캐릭터및이벤트배너노출정책/plan-task.md
```
- 문서 전용 지침에 따라 Gradle test/build/lint와 실행 QA를 생략했다. 위 Phase 명령은 향후 구현 검증 계획일 뿐 실행 결과가 아니다. 구현 체크박스와 기능 수용 기준은 미완료다.

Some files were not shown because too many files have changed in this diff Show More