docs(creator-admin): 댓글 관리 API 계약과 검증 기록을 정리한다

This commit is contained in:
2026-11-20 14:10:36 +09:00
parent 837823104a
commit a8c96776b4
8 changed files with 1225 additions and 0 deletions
@@ -0,0 +1,106 @@
# 크리에이터 관리자 댓글 관리 API 계약
구현 기준: `src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/admin/commentmanagement/`. 명세와 예시는 현재 서버 DTO·컨트롤러 동작을 따른다.
## 공통 계약
- Base path: `/api/v2/creator-admin/comment-management`. 모든 요청은 `Authorization: Bearer $ACCESS_TOKEN`을 사용한다. 활성 `CREATOR`만 접근할 수 있으며 인증 principal의 크리에이터 소유 범위로 처리한다. owner/creator ID를 요청에 싣지 않는다.
- 모든 성공은 HTTP 200과 `ApiResponse`다. 조회는 `success:true`, `message:null`, `data`에 결과를 담는다. 변경은 `success:true`, `message:null`, `data:null`을 반환한다. 응답 필드가 nullable이면 값이 없을 때 `null`이다. `counts`는 지원하지 않는 FanTalk 및 게시글 목록에서는 null 대신 생략된다.
- 기본 query는 `page=0`, `size=10`, `order=latest`; `page`는 0 이상 정수, `size`는 1..100 정수다. 서버 page는 0-based다. 정렬은 `latest` 또는 `oldest`, `createdAt`과 ID를 같은 방향으로 함께 정렬한다. 큰 page도 보정하지 않으며 범위를 벗어나면 `items:[]`, 현재 total/count를 반환한다.
- 댓글·후원 visibility query는 `all`(기본), `public`, `secret`만 허용한다. `counts.all/public/secret`은 선택 필터 적용 전 해당 API의 전체 조회 범위 건수이고, `totalCount`는 선택 필터 결과다. `page`, `size`, `hasNext`도 함께 반환한다. 답글은 부모 댓글 조회와 개수에서 제외된다.
- path ID는 양수 Long JSON number다. 프런트엔드가 JavaScript 안전 정수 범위를 넘을 수 있는 ID를 받으면 lossless JSON 처리 또는 정밀도를 잃지 않는 문자열 변환이 필요하다. 경로의 부모 ID가 서로 다른 자원을 가리키면 조회/변경하지 않는다.
- 답글 POST/PUT은 `Content-Type: application/json`과 정확히 `{"content":"본문"}` 형태를 사용한다. 추가 속성, 비문자열·누락·null content, 잘못된 JSON, 후행 토큰은 400이다. 앞뒤 공백을 trim하고 빈 값은 거부한다. trim 결과의 UTF-8 크기가 65,535 bytes를 넘으면 400이며 자르지 않는다. 한글·이모지·줄바꿈은 정규화 후 보존한다. 정규화된 기존 내용과 같은 PUT도 200 성공이다.
- 오류는 `ApiResponse` 오류 wrapper다. `success:false`, 번역된 `message`, `data:null`을 반환한다. `errorProperty`는 제공되지 않으며 응답에서 생략되거나 null일 수 있다. 상태는 400 잘못된 입력, 401 인증 없음/잘못된 자격, 403 활성 CREATOR 역할 또는 소유권 부족, 404 자원 없음·비활성/불일치 부모·답글, 409 비활성 부모에 답글 등록 또는 이미 활성화된 크리에이터 답글이다. 존재하지 않는 API path도 404다. 지원하지 않는 method/media type/Accept는 각각 405/415/406, 처리되지 않은 서버 오류는 500이다. 오류의 문구는 언어 헤더에 따라 달라질 수 있다.
- 시각은 서버 `toUtcIso()`가 반환한 UTC ISO-8601 문자열이다. 화면 표시 시간대로 변환해 사용한다. 변경 응답은 null이므로 변경 후 목록 재조회로 서버 상태를 갱신한다.
## 엔드포인트 (구현된 19 operations)
| 화면/동작 | Method | Base 상대 path | Query / body |
|---|---|---|---|
| 콘텐츠 댓글 목록 | GET | `/content/comments` | `page`, `size`, `order`, `visibility` |
| 콘텐츠 부모 댓글 삭제 | DELETE | `/content/{contentId}/comments/{commentId}` | 없음 |
| 콘텐츠 답글 등록 | POST | `/content/{contentId}/comments/{commentId}/replies` | `{"content":"..."}` |
| 콘텐츠 답글 수정 | PUT | `/content/{contentId}/comments/{commentId}/replies/{replyId}` | `{"content":"..."}` |
| 콘텐츠 답글 삭제 | DELETE | `/content/{contentId}/comments/{commentId}/replies/{replyId}` | 없음 |
| FanTalk(기존 팬레터) 목록 | GET | `/fantalks` | `page`, `size`, `order` |
| FanTalk 부모 글 삭제 | DELETE | `/fantalks/{fanTalkId}` | 없음 |
| FanTalk 답글 등록 | POST | `/fantalks/{fanTalkId}/replies` | `{"content":"..."}` |
| FanTalk 답글 수정 | PUT | `/fantalks/{fanTalkId}/replies/{replyId}` | `{"content":"..."}` |
| FanTalk 답글 삭제 | DELETE | `/fantalks/{fanTalkId}/replies/{replyId}` | 없음 |
| 커뮤니티 게시글 목록 | GET | `/community/posts` | `page`, `size`, `order` |
| 커뮤니티 게시글 상세 | GET | `/community/posts/{postId}` | 없음 |
| 게시글 댓글 목록 | GET | `/community/posts/{postId}/comments` | `page`, `size`, `order`, `visibility` |
| 게시글 부모 댓글 삭제 | DELETE | `/community/posts/{postId}/comments/{commentId}` | 없음 |
| 게시글 답글 등록 | POST | `/community/posts/{postId}/comments/{commentId}/replies` | `{"content":"..."}` |
| 게시글 답글 수정 | PUT | `/community/posts/{postId}/comments/{commentId}/replies/{replyId}` | `{"content":"..."}` |
| 게시글 답글 삭제 | DELETE | `/community/posts/{postId}/comments/{commentId}/replies/{replyId}` | 없음 |
| 후원 메시지 목록 | GET | `/donations` | `page`, `size`, `order`, `visibility` |
| 후원 메시지 숨김 | DELETE | `/donations/{donationId}` | 없음 |
모든 ID path parameter는 필수 양수 Long이다. `order`와 pagination은 모든 목록에서 지원한다. visibility는 콘텐츠 댓글·게시글 댓글·후원 목록에만 지원하고 FanTalk 및 게시글 목록에는 없다. 알 수 없는 query 파라미터는 API가 사용하지 않는다.
## 응답 스키마와 조회 의미
공통 writer는 `{memberId, nickname, profileImageUrl}`이다. `memberId`는 Long, `nickname`은 탈퇴 회원 접두부가 제거된 문자열이다. `profileImageUrl`은 커뮤니티 댓글에서 nullable이고, 콘텐츠/FanTalk/후원 writer는 이미지가 없을 때 기본 프로필 URL을 사용한다. 댓글·팬톡·후원 항목은 `{writer, content, createdAtUtc}`를 포함한다. 게시글 항목에는 writer가 없다.
| 조회 | 항목 필드 | 실제 범위와 null 의미 |
|---|---|---|
| 콘텐츠 댓글 | `commentId`, `writer`, `content`, `createdAtUtc`, `isSecret`, `creatorReply`, `contentId`, `contentTitle`, `contentType`, `series` | 본인 소유 AudioContent 중 `duration != null`이며 `isActive` 또는 `releaseDate != null`인 항목의 활성 팬 원댓글. 크리에이터가 쓴 부모 댓글은 제외한다. `contentType`은 theme이 `다시듣기`면 `LIVE_REPLAY`, 아니면 series 연결이 있으면 `SERIES`, 아니면 `AUDIO`. `series`는 `{seriesId,title}` 배열이며 없으면 `[]`. |
| FanTalk | `fanTalkId`, `writer`, `content`, `createdAtUtc`, `creatorReply`, `isSecret` | 기존 `CreatorCheers`의 소유 채널 활성 root 중 채널 소유자 본인이 작성하지 않은 글. 다른 크리에이터가 팬으로 남긴 글도 포함한다. 별도 secret 정책이 없고 `isSecret:false`. 활성 소유자 답글 중 `createdAt DESC, id DESC` 최신 하나만 `creatorReply`로 표시한다. |
| 커뮤니티 게시글 | `postId`, `content`, `price`, `imageUrl`, `audioUrl`, `isFixed`, `isCommentAvailable`, `createdAtUtc`, `commentCount` | 본인 소유 활성 게시글. 제목 필드는 없다. 화면에서 `content`를 제목/미리보기로 표시하고 `isFixed`를 공지 배지로 사용한다. `imageUrl`과 `audioUrl`은 nullable이며 audio URL은 기존 서명 URL helper를 쓴다. `commentCount`는 활성 부모 댓글만 센다. |
| 커뮤니티 댓글 | `commentId`, `writer`, `content`, `createdAtUtc`, `isSecret`, `creatorReply` | 해당 활성 게시글의 활성 부모 댓글. 작성자와 무관하게 크리에이터가 작성한 부모 댓글도 포함한다. 활성 소유자 답글 중 `createdAt DESC, id DESC` 최신 하나를 표시한다. |
| 후원 메시지 | `donationId`, `writer`, `content`, `can`, `isSecret`, `createdAtUtc` | 본인 소유 채널의 미숨김 메시지 전체 기간 조회. `content`는 원문이 없으면 null이다. `can`은 정수 금액 단위 그대로다. |
`creatorReply`는 활성 소유자 답글이 없으면 null이다. 답글에는 `{replyId, writer, content, createdAtUtc, isSecret}`가 포함된다. 새 콘텐츠/커뮤니티 답글의 `isSecret`은 부모 비밀 여부를 상속한다. 부모 댓글 삭제는 기존 row를 soft delete하며 답글 row를 지우지 않는다. 부모가 비활성화되면 관리자 답글 수정·삭제는 404, 등록은 409다. 기존 앱의 직접 답글 목록은 삭제 부모의 답글을 빈 목록/count 0으로 반환한다(V2 상세 context는 기존 오류 규약 유지). 답글 삭제는 답글만 soft delete하며 이전 활성 답글이 다시 표시된다. 기존 활성 소유자 답글이 하나라도 남아 있으면 새 답글 POST는 409이고, 모두 삭제된 뒤에만 재등록할 수 있다. 기존 앱의 다중 답글 데이터/조회는 그대로 유지한다.
비밀 콘텐츠/커뮤니티 스레드는 원댓글 작성자와 소유 크리에이터만 읽을 수 있다. 조회 및 count에서 비밀 접근 규칙을 적용하고 새 답글은 부모 공개 범위를 상속한다. 후원 visibility는 비밀 메시지도 소유 크리에이터에게 보여주는 필터일 뿐 별도 공개 접근 정책이 아니다.
일반 부모에 이미 존재하는 비밀 답글은 기존 작성자·소유 크리에이터 접근을 유지한다. 크리에이터가 쓴 비밀 답글이면 원댓글 팬도 볼 수 있지만, 다른 팬의 비밀 답글을 원댓글 팬에게 새로 공개하지 않는다.
## 요청 예시
토큰은 쉘 환경 변수에서 읽는다. 실제 토큰이나 계정 정보를 문서에 넣지 않는다.
```sh
: "${ACCESS_TOKEN:?Set ACCESS_TOKEN in your shell}"
API_BASE="${API_BASE:?Set API_BASE to the current API origin}"
curl -sS -H "Authorization: Bearer $ACCESS_TOKEN" \
"$API_BASE/api/v2/creator-admin/comment-management/content/comments?page=0&size=10&order=latest&visibility=all"
curl -sS -X POST \
-H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
--data-binary '{"content":"확인했습니다.\n감사합니다."}' \
"$API_BASE/api/v2/creator-admin/comment-management/community/posts/42/comments/314/replies"
curl -sS -X DELETE -H "Authorization: Bearer $ACCESS_TOKEN" \
"$API_BASE/api/v2/creator-admin/comment-management/donations/27"
```
응답 예시의 숫자 ID는 형식 예시다. 서버가 발급한 실제 ID를 사용한다.
```json
{
"success": true,
"message": null,
"data": {
"items": [],
"totalCount": 0,
"page": 0,
"size": 10,
"hasNext": false,
"counts": {"all": 0, "public": 0, "secret": 0}
},
"errorProperty": null
}
```
FanTalk/게시글 목록에서는 `counts` 필드가 생략된다. 오류 예시의 `message`는 요청 언어에 따른 서버 번역이다.
```json
{
"success": false,
"message": "잘못된 요청입니다.",
"data": null,
"errorProperty": null
}
```
@@ -0,0 +1,46 @@
# 프런트엔드 적용 메모
## 분석과 재사용
기준 구현은 `v2/creator/admin/commentmanagement/` 아래 네 controller/service/repository/DTO와 공통 parser/auth/error 경계다. 인증은 기존 Bearer principal에서 활성 `CREATOR`를 확인한다. 콘텐츠 댓글, `CreatorCheers` FanTalk, 커뮤니티 댓글, 후원 메시지 및 `ApiResponse`를 재사용하며 새 저장 테이블이나 title 필드는 없다. `v2/commentthread`의 부모 잠금은 답글 등록/삭제 경쟁을 직렬화한다.
관리자 목록 범위는 도메인별로 다르다. 콘텐츠와 FanTalk은 채널 소유자 본인이 작성한 부모만 제외하며 다른 크리에이터가 팬으로 남긴 글은 포함한다. 커뮤니티는 소유 활성 게시글 아래 모든 활성 부모 댓글을 포함한다. 답글은 부모 항목/개수에서 제외한다. 관리자 응답은 탈퇴 닉네임 접두부를 제거하고 도메인별 null/기본 프로필 규칙을 유지한다. 최신 활성 소유자 답글 하나만 반환하고 삭제하면 이전 활성 답글이 나타난다. 부모 soft delete 후 답글 row는 보존하지만 관리자 수정/삭제는 404, 등록은 409이며 레거시 앱 목록은 빈 배열/count 0이다.
콘텐츠 type은 실제 `theme == "다시듣기"` 판정이 우선이고 다음이 series 연결 여부다. FanTalk은 기존 공개 기능으로 `isSecret:false`이며 비밀 필드/정책을 추가하지 않는다. 커뮤니티는 별도 제목이 없으므로 `content`를 제목 자리에 표시하고 `isFixed`를 공지 배지로 쓴다. 게시글 `imageUrl`은 nullable 기존 CDN 경로, `audioUrl`은 기존 서명 URL helper 결과다. 후원 `content`도 원문이 없는 경우 null이다. 오류 메시지는 기존 번역 응답이라 프런트에서 문구 대신 HTTP 상태와 `success`를 처리한다.
## 스키마와 선행 조건
새 테이블이나 새 컬럼은 없다. 후원 숨김은 기존 `channel_donation_message.is_hidden`과 기존 숨김 서비스에 연결한다. 적용 전 `docs/20261105_채널후원메시지숨김/channel_donation_message_is_hidden_ddl.sql` 적용 여부를 확인한다. 숨겨진 후원은 관리자 조회와 레거시 앱 목록/count에서 제외되며 메시지/금액/정산 데이터는 바꾸지 않는다.
`schema-preflight.sql`은 읽기 전용 사전 확인용이며 이번 작업에서 실행하지 않았다. 운영 MySQL의 댓글 본문 컬럼 타입·문자셋(utf8mb4), timestamp 정밀도 및 필요한 인덱스는 미확인이다. 격리 수준도 구현 검증 환경과 운영 MySQL 사이에서 확인되지 않았다. 65,535 UTF-8 bytes 입력 한도와 실제 컬럼 용량 호환성은 배포 전에 확인해야 한다.
## 프런트엔드 영향과 적용 순서
1. 기존 common client가 `success/message/data/errorProperty` `ApiResponse`를 읽으면 공통 클라이언트 변경 없이 base path와 endpoint만 연결한다. 오류 응답도 같은 wrapper이며 `errorProperty`는 null이다.
2. Bearer active-CREATOR 세션을 사용하고 ID를 요청 본문에 복제하지 않는다. Long ID를 JS `number`로 손실 없이 처리할 수 있는지 확인한다.
3. 1-based 화면 page에서 1을 빼 서버에 보내며 size 10(최대 100), lowercase `latest/oldest`, `all/public/secret`을 사용한다. `counts`는 필터 전 전체 수, `totalCount`는 선택 필터 수다. FanTalk 및 게시글 목록에는 counts가 없다. 범위 초과 페이지는 빈 배열이므로 UI가 `max(0, ceil(totalCount / size) - 1)` 서버 페이지로 재조회한다.
4. 새 답글은 content만 보내고 성공 뒤 관련 목록을 재조회한다. 동일 내용 PUT도 성공이다. UI는 활성 답글 유무에 따라 답글 등록/수정/삭제 동작을 전환한다. 부모/답글 soft delete와 비밀 댓글의 노출 허용은 서버가 판정한다.
5. 커뮤니티 목록/상세 화면은 본문 미리보기와 `isFixed` 배지를 표시하고 nullable 첨부/후원 원문을 처리한다. 오디오 `audioUrl`은 기존 signed URL이라 별도 서명이나 URL 조립을 하지 않는다.
## 요청 예시와 검증 순서
쉘에서 토큰을 공급하고 실제 상대 endpoint를 사용한다. 예시 ID는 설명용이며 실제 API 응답의 ID로 대체한다.
```sh
: "${ACCESS_TOKEN:?Set ACCESS_TOKEN in your shell}"
API_BASE="${API_BASE:?Set API_BASE to the current API origin}/api/v2/creator-admin/comment-management"
curl -sS -H "Authorization: Bearer $ACCESS_TOKEN" \
"$API_BASE/fantalks?page=0&size=10&order=latest"
curl -sS -X PUT -H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' --data-binary '{"content":"답글 수정"}' \
"$API_BASE/content/123/comments/456/replies/789"
curl -sS -H "Authorization: Bearer $ACCESS_TOKEN" \
"$API_BASE/community/posts/42/comments?page=0&size=10&order=latest&visibility=secret"
```
화면 연결은 목록 조회 → 댓글/게시글 상세 → 답글 등록·수정·삭제 → 부모 삭제 및 후원 숨김 순으로 적용한다. 실제 JWT HTTP 12개, 앱 회귀 수정 집합 105개, 팬톡 포함 최종 집합 108개가 통과했다(집합 간 중복 있음). `bootJar`와 `ktlintCheck`도 성공했다. 실패 발견·수정 이력과 미검증 범위는 `verification.md`를 참고한다. 전체 테스트는 사용자 실행용 `./gradlew test`로 남겼다.
최종 리뷰에서 확인한 일반 팬 비밀 답글 저장 회귀도 수정했다. 실제 구매·서비스 저장 테스트를 포함한 최종 120개 및 빌드·포맷 검사가 통과했고 독립 재리뷰는 APPROVE다. 관리자 답글은 부모 범위를 상속하지만, 기존 앱 일반 팬의 비밀 설정과 구매 검증은 유지한다.
@@ -0,0 +1,670 @@
openapi: 3.1.0
info:
title: 크리에이터 관리자 댓글 관리 API
version: 1.0.0
description: >-
구현된 Creator Admin 댓글·FanTalk·커뮤니티·후원 관리 API. 응답은 ApiResponse wrapper를 따른다.
servers:
- url: /
description: 현재 호스트
security:
- bearerAuth: []
tags:
- name: ContentComments
description: 콘텐츠 댓글과 소유자 답글
- name: FanTalk
description: 기존 팬톡 기반 팬레터 및 소유자 답글
- name: Community
description: 커뮤니티 게시글과 댓글
- name: Donations
description: 후원 메시지 조회 및 숨김
paths:
/api/v2/creator-admin/comment-management/content/comments:
get:
tags: [ContentComments]
summary: 콘텐츠 댓글 목록
operationId: listCreatorContentComments
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
- $ref: '#/components/parameters/Order'
- $ref: '#/components/parameters/Visibility'
responses:
'200':
description: 콘텐츠 부모 댓글 페이지
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- properties:
data:
$ref: '#/components/schemas/ContentCommentPage'
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'500': {$ref: '#/components/responses/InternalServerError'}
/api/v2/creator-admin/comment-management/content/{contentId}/comments/{commentId}:
parameters:
- $ref: '#/components/parameters/ContentId'
- $ref: '#/components/parameters/CommentId'
delete:
tags: [ContentComments]
summary: 콘텐츠 부모 댓글 soft delete
operationId: deleteCreatorContentComment
responses:
'200': {$ref: '#/components/responses/NullSuccess'}
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'500': {$ref: '#/components/responses/InternalServerError'}
/api/v2/creator-admin/comment-management/content/{contentId}/comments/{commentId}/replies:
parameters:
- $ref: '#/components/parameters/ContentId'
- $ref: '#/components/parameters/CommentId'
post:
tags: [ContentComments]
summary: 콘텐츠 댓글에 크리에이터 답글 등록
operationId: createCreatorContentCommentReply
requestBody: {$ref: '#/components/requestBodies/Reply'}
responses:
'200': {$ref: '#/components/responses/NullSuccess'}
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'409': {$ref: '#/components/responses/Conflict'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'500': {$ref: '#/components/responses/InternalServerError'}
/api/v2/creator-admin/comment-management/content/{contentId}/comments/{commentId}/replies/{replyId}:
parameters:
- $ref: '#/components/parameters/ContentId'
- $ref: '#/components/parameters/CommentId'
- $ref: '#/components/parameters/ReplyId'
put:
tags: [ContentComments]
summary: 콘텐츠 크리에이터 답글 수정
operationId: updateCreatorContentCommentReply
requestBody: {$ref: '#/components/requestBodies/Reply'}
responses:
'200': {$ref: '#/components/responses/NullSuccess'}
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'500': {$ref: '#/components/responses/InternalServerError'}
delete:
tags: [ContentComments]
summary: 콘텐츠 크리에이터 답글 soft delete
operationId: deleteCreatorContentCommentReply
responses:
'200': {$ref: '#/components/responses/NullSuccess'}
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'500': {$ref: '#/components/responses/InternalServerError'}
/api/v2/creator-admin/comment-management/fantalks:
get:
tags: [FanTalk]
summary: FanTalk 기반 팬레터 목록
operationId: listCreatorFanTalks
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
- $ref: '#/components/parameters/Order'
responses:
'200':
description: FanTalk 페이지
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- properties:
data:
$ref: '#/components/schemas/FanTalkPage'
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'500': {$ref: '#/components/responses/InternalServerError'}
/api/v2/creator-admin/comment-management/fantalks/{fanTalkId}:
parameters:
- $ref: '#/components/parameters/FanTalkId'
delete:
tags: [FanTalk]
summary: FanTalk 부모 글 soft delete
operationId: deleteCreatorFanTalk
responses:
'200': {$ref: '#/components/responses/NullSuccess'}
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'500': {$ref: '#/components/responses/InternalServerError'}
/api/v2/creator-admin/comment-management/fantalks/{fanTalkId}/replies:
parameters:
- $ref: '#/components/parameters/FanTalkId'
post:
tags: [FanTalk]
summary: FanTalk 크리에이터 답글 등록
operationId: createCreatorFanTalkReply
requestBody: {$ref: '#/components/requestBodies/Reply'}
responses:
'200': {$ref: '#/components/responses/NullSuccess'}
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'409': {$ref: '#/components/responses/Conflict'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'415': {$ref: '#/components/responses/UnsupportedMediaType'}
'500': {$ref: '#/components/responses/InternalServerError'}
/api/v2/creator-admin/comment-management/fantalks/{fanTalkId}/replies/{replyId}:
parameters:
- $ref: '#/components/parameters/FanTalkId'
- $ref: '#/components/parameters/ReplyId'
put:
tags: [FanTalk]
summary: FanTalk 크리에이터 답글 수정
operationId: updateCreatorFanTalkReply
requestBody: {$ref: '#/components/requestBodies/Reply'}
responses:
'200': {$ref: '#/components/responses/NullSuccess'}
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'415': {$ref: '#/components/responses/UnsupportedMediaType'}
'500': {$ref: '#/components/responses/InternalServerError'}
delete:
tags: [FanTalk]
summary: FanTalk 크리에이터 답글 soft delete
operationId: deleteCreatorFanTalkReply
responses:
'200': {$ref: '#/components/responses/NullSuccess'}
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'500': {$ref: '#/components/responses/InternalServerError'}
/api/v2/creator-admin/comment-management/community/posts:
get:
tags: [Community]
summary: 커뮤니티 게시글 목록
operationId: listCreatorCommunityPosts
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
- $ref: '#/components/parameters/Order'
responses:
'200':
description: 게시글 페이지
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- properties:
data:
$ref: '#/components/schemas/CommunityPostPage'
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'500': {$ref: '#/components/responses/InternalServerError'}
/api/v2/creator-admin/comment-management/community/posts/{postId}:
parameters:
- $ref: '#/components/parameters/PostId'
get:
tags: [Community]
summary: 커뮤니티 게시글 상세
operationId: getCreatorCommunityPost
responses:
'200':
description: 게시글 상세
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- properties:
data:
$ref: '#/components/schemas/CommunityPost'
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'500': {$ref: '#/components/responses/InternalServerError'}
/api/v2/creator-admin/comment-management/community/posts/{postId}/comments:
parameters:
- $ref: '#/components/parameters/PostId'
get:
tags: [Community]
summary: 커뮤니티 게시글 댓글 목록
operationId: listCreatorCommunityComments
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
- $ref: '#/components/parameters/Order'
- $ref: '#/components/parameters/Visibility'
responses:
'200':
description: 댓글 페이지
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- properties:
data:
$ref: '#/components/schemas/CommunityCommentPage'
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'500': {$ref: '#/components/responses/InternalServerError'}
/api/v2/creator-admin/comment-management/community/posts/{postId}/comments/{commentId}:
parameters:
- $ref: '#/components/parameters/PostId'
- $ref: '#/components/parameters/CommentId'
delete:
tags: [Community]
summary: 커뮤니티 부모 댓글 soft delete
operationId: deleteCreatorCommunityComment
responses:
'200': {$ref: '#/components/responses/NullSuccess'}
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'500': {$ref: '#/components/responses/InternalServerError'}
/api/v2/creator-admin/comment-management/community/posts/{postId}/comments/{commentId}/replies:
parameters:
- $ref: '#/components/parameters/PostId'
- $ref: '#/components/parameters/CommentId'
post:
tags: [Community]
summary: 커뮤니티 댓글에 크리에이터 답글 등록
operationId: createCreatorCommunityReply
requestBody: {$ref: '#/components/requestBodies/Reply'}
responses:
'200': {$ref: '#/components/responses/NullSuccess'}
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'409': {$ref: '#/components/responses/Conflict'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'415': {$ref: '#/components/responses/UnsupportedMediaType'}
'500': {$ref: '#/components/responses/InternalServerError'}
/api/v2/creator-admin/comment-management/community/posts/{postId}/comments/{commentId}/replies/{replyId}:
parameters:
- $ref: '#/components/parameters/PostId'
- $ref: '#/components/parameters/CommentId'
- $ref: '#/components/parameters/ReplyId'
put:
tags: [Community]
summary: 커뮤니티 크리에이터 답글 수정
operationId: updateCreatorCommunityReply
requestBody: {$ref: '#/components/requestBodies/Reply'}
responses:
'200': {$ref: '#/components/responses/NullSuccess'}
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'415': {$ref: '#/components/responses/UnsupportedMediaType'}
'500': {$ref: '#/components/responses/InternalServerError'}
delete:
tags: [Community]
summary: 커뮤니티 크리에이터 답글 soft delete
operationId: deleteCreatorCommunityReply
responses:
'200': {$ref: '#/components/responses/NullSuccess'}
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'500': {$ref: '#/components/responses/InternalServerError'}
/api/v2/creator-admin/comment-management/donations:
get:
tags: [Donations]
summary: 채널 후원 메시지 목록
operationId: listCreatorDonations
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
- $ref: '#/components/parameters/Order'
- $ref: '#/components/parameters/Visibility'
responses:
'200':
description: 후원 메시지 페이지
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- properties:
data:
$ref: '#/components/schemas/DonationPage'
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'500': {$ref: '#/components/responses/InternalServerError'}
/api/v2/creator-admin/comment-management/donations/{donationId}:
parameters:
- $ref: '#/components/parameters/DonationId'
delete:
tags: [Donations]
summary: 후원 메시지 숨김
operationId: hideCreatorDonation
responses:
'200': {$ref: '#/components/responses/NullSuccess'}
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'406': {$ref: '#/components/responses/NotAcceptable'}
'500': {$ref: '#/components/responses/InternalServerError'}
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
parameters:
Page:
name: page
in: query
required: false
description: 0-based page, 기본값 0
schema: {type: integer, minimum: 0, default: 0}
Size:
name: size
in: query
required: false
description: 페이지 크기, 기본값 10, 최대 100
schema: {type: integer, minimum: 1, maximum: 100, default: 10}
Order:
name: order
in: query
required: false
description: createdAt과 ID를 같은 방향으로 정렬
schema: {type: string, enum: [latest, oldest], default: latest}
Visibility:
name: visibility
in: query
required: false
description: 필터 적용 전 범위의 counts와 선택 필터 결과 totalCount를 반환
schema: {type: string, enum: [all, public, secret], default: all}
ContentId:
name: contentId
in: path
required: true
schema: {$ref: '#/components/schemas/PositiveId'}
CommentId:
name: commentId
in: path
required: true
schema: {$ref: '#/components/schemas/PositiveId'}
ReplyId:
name: replyId
in: path
required: true
schema: {$ref: '#/components/schemas/PositiveId'}
FanTalkId:
name: fanTalkId
in: path
required: true
schema: {$ref: '#/components/schemas/PositiveId'}
PostId:
name: postId
in: path
required: true
schema: {$ref: '#/components/schemas/PositiveId'}
DonationId:
name: donationId
in: path
required: true
schema: {$ref: '#/components/schemas/PositiveId'}
requestBodies:
Reply:
required: true
description: >-
JSON object with content only. Server trims outer whitespace, rejects blank text and content over
65,535 UTF-8 bytes; it does not truncate. No author, parent, active, or secret fields are accepted.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [content]
properties:
content: {type: string, minLength: 1}
example: {content: 답변 내용}
responses:
NullSuccess:
description: 변경 성공. 목록을 재조회한다.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- properties:
data: {type: 'null'}
BadRequest:
description: 잘못된 ID, query, JSON 또는 content 입력
content:
application/json:
schema: {$ref: '#/components/schemas/ErrorResponse'}
Unauthorized:
description: 인증 정보 누락 또는 유효하지 않음
content:
application/json:
schema: {$ref: '#/components/schemas/ErrorResponse'}
Forbidden:
description: 활성 CREATOR 역할 또는 자원 소유권 부족
content:
application/json:
schema: {$ref: '#/components/schemas/ErrorResponse'}
NotFound:
description: 자원 없음, 비활성 또는 서로 일치하지 않는 부모 관계
content:
application/json:
schema: {$ref: '#/components/schemas/ErrorResponse'}
Conflict:
description: 부모 비활성 또는 활성 크리에이터 답글이 이미 존재
content:
application/json:
schema: {$ref: '#/components/schemas/ErrorResponse'}
NotAcceptable:
description: 지원하지 않는 Accept 헤더
content:
application/json:
schema: {$ref: '#/components/schemas/ErrorResponse'}
UnsupportedMediaType:
description: 지원하지 않는 Content-Type
content:
application/json:
schema: {$ref: '#/components/schemas/ErrorResponse'}
InternalServerError:
description: 처리되지 않은 서버 오류
content:
application/json:
schema: {$ref: '#/components/schemas/ErrorResponse'}
schemas:
PositiveId:
type: integer
format: int64
minimum: 1
description: Long JSON number. JavaScript callers must preserve values beyond Number.MAX_SAFE_INTEGER.
ApiResponse:
type: object
required: [success, message, data]
properties:
success: {type: boolean}
message: {type: [string, 'null']}
data: {}
errorProperty: {type: [string, 'null']}
ErrorResponse:
type: object
required: [success, message, data]
properties:
success: {const: false}
message: {type: [string, 'null'], description: Localized message}
data: {type: 'null'}
errorProperty: {type: [string, 'null'], description: May be omitted or null; this API does not populate it}
NullSuccessResponse:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- properties:
success: {const: true}
data: {type: 'null'}
Writer:
type: object
required: [memberId, nickname, profileImageUrl]
properties:
memberId: {$ref: '#/components/schemas/PositiveId'}
nickname: {type: string, description: Deleted-member prefix is removed}
profileImageUrl: {type: [string, 'null'], format: uri}
Reply:
type: object
required: [replyId, writer, content, createdAtUtc, isSecret]
properties:
replyId: {$ref: '#/components/schemas/PositiveId'}
writer: {$ref: '#/components/schemas/Writer'}
content: {type: string}
createdAtUtc: {type: string, format: date-time}
isSecret: {type: boolean}
Counts:
type: object
required: [all, public, secret]
properties:
all: {type: integer, format: int64}
public: {type: integer, format: int64}
secret: {type: integer, format: int64}
Page:
type: object
required: [items, totalCount, page, size, hasNext]
properties:
items: {type: array, items: {}}
totalCount: {type: integer, format: int64}
page: {type: integer, minimum: 0}
size: {type: integer, minimum: 1, maximum: 100}
hasNext: {type: boolean}
counts:
oneOf:
- {$ref: '#/components/schemas/Counts'}
- type: 'null'
description: Omitted for FanTalk and community post pages.
ContentComment:
type: object
required: [commentId, writer, content, createdAtUtc, isSecret, creatorReply, contentId, contentTitle, contentType, series]
properties:
commentId: {$ref: '#/components/schemas/PositiveId'}
writer: {$ref: '#/components/schemas/Writer'}
content: {type: string}
createdAtUtc: {type: string, format: date-time}
isSecret: {type: boolean}
creatorReply: {oneOf: [{$ref: '#/components/schemas/Reply'}, {type: 'null'}]}
contentId: {$ref: '#/components/schemas/PositiveId'}
contentTitle: {type: string}
contentType: {type: string, enum: [AUDIO, SERIES, LIVE_REPLAY]}
series:
type: array
items:
type: object
required: [seriesId, title]
properties:
seriesId: {$ref: '#/components/schemas/PositiveId'}
title: {type: string}
FanTalk:
type: object
required: [fanTalkId, writer, content, createdAtUtc, creatorReply, isSecret]
properties:
fanTalkId: {$ref: '#/components/schemas/PositiveId'}
writer: {$ref: '#/components/schemas/Writer'}
content: {type: string}
createdAtUtc: {type: string, format: date-time}
creatorReply: {oneOf: [{$ref: '#/components/schemas/Reply'}, {type: 'null'}]}
isSecret: {type: boolean, const: false}
CommunityPost:
type: object
required: [postId, content, price, imageUrl, audioUrl, isFixed, isCommentAvailable, createdAtUtc, commentCount]
properties:
postId: {$ref: '#/components/schemas/PositiveId'}
content: {type: string, description: Post body. There is no title field.}
price: {type: integer}
imageUrl: {type: [string, 'null'], format: uri}
audioUrl: {type: [string, 'null'], format: uri, description: Existing signed URL helper is used}
isFixed: {type: boolean}
isCommentAvailable: {type: boolean}
createdAtUtc: {type: string, format: date-time}
commentCount: {type: integer, format: int64, description: Active parent comments only}
CommunityComment:
type: object
required: [commentId, writer, content, createdAtUtc, isSecret, creatorReply]
properties:
commentId: {$ref: '#/components/schemas/PositiveId'}
writer: {$ref: '#/components/schemas/Writer'}
content: {type: string}
createdAtUtc: {type: string, format: date-time}
isSecret: {type: boolean}
creatorReply: {oneOf: [{$ref: '#/components/schemas/Reply'}, {type: 'null'}]}
Donation:
type: object
required: [donationId, writer, content, can, isSecret, createdAtUtc]
properties:
donationId: {$ref: '#/components/schemas/PositiveId'}
writer: {$ref: '#/components/schemas/Writer'}
content: {type: [string, 'null']}
can: {type: integer}
isSecret: {type: boolean}
createdAtUtc: {type: string, format: date-time}
ContentCommentPage:
allOf:
- $ref: '#/components/schemas/Page'
- properties:
items: {type: array, items: {$ref: '#/components/schemas/ContentComment'}}
counts: {$ref: '#/components/schemas/Counts'}
FanTalkPage:
allOf:
- $ref: '#/components/schemas/Page'
- properties:
items: {type: array, items: {$ref: '#/components/schemas/FanTalk'}}
CommunityPostPage:
allOf:
- $ref: '#/components/schemas/Page'
- properties:
items: {type: array, items: {$ref: '#/components/schemas/CommunityPost'}}
CommunityCommentPage:
allOf:
- $ref: '#/components/schemas/Page'
- properties:
items: {type: array, items: {$ref: '#/components/schemas/CommunityComment'}}
counts: {$ref: '#/components/schemas/Counts'}
DonationPage:
allOf:
- $ref: '#/components/schemas/Page'
- properties:
items: {type: array, items: {$ref: '#/components/schemas/Donation'}}
counts: {$ref: '#/components/schemas/Counts'}
@@ -0,0 +1,163 @@
# 크리에이터 관리자 댓글 관리 구현 계획
> 실행: subagent-driven-development. 사용자 요청에 따라 독립 파일 작업은 병렬 수행하고 공유 checkout의 Gradle 실행은 직렬화한다. commit/push/운영 반영 금지.
## 목표와 기준
- 기준: `prd.md`, `api-contract.md`.
- 목표: 네 탭의 영속 데이터 조회·관리와 기존 앱의 비밀/삭제 노출 일관성을 제공한다.
- 기술: Kotlin/Spring Boot/JPA/QueryDSL/기존 ApiResponse. 새 테이블·의존성·전역 공개 계약 변경 없음.
- 사용자 추가 지시(2026-11-20): 목표를 충족하는 최소 구현과 빠른 실행을 우선한다. 아래 파일 목록은 책임 경계이며 파일 수를 채우는 요구가 아니다. 실제 경계가 필요하지 않은 단일 용도 port/mapper/wrapper는 생략하고, 독립 기능은 병렬 구현한다. 검증은 위험 동작을 실제로 잡는 테스트로 집중한다.
- 현재 상태: P1/P2/P3 완료. 독립 리뷰 APPROVE. 전체 suite 및 운영 DB 검증은 미실행으로 구분한다.
- 경로 표기: M=`src/main/kotlin/kr/co/vividnext/sodalive`, T=`src/test/kotlin/kr/co/vividnext/sodalive`, P=`v2/creator/admin/commentmanagement`.
- 기존 작업 트리는 시작 시 깨끗했고 현재 branch는 `test`다. 공유 checkout에서 파일 소유권을 분리한다.
## 검증 시나리오
1. 네 탭·게시글 상세가 실제 저장 데이터를 HTTP 200/ApiResponse로 반환한다. page/size, 필터 전체 개수, 동시간 ID 정렬, 빈 결과·범위 초과를 실제 DB/HTTP로 검증한다.
2. 답글 CRUD/재등록·Unicode·공백·TEXT 한계와 기존 다중 답글의 최신 표시를 검증한다. 별도 트랜잭션 경쟁에서 관리자 중복 등록은 하나만 성공한다.
3. 미인증 401, 역할 부족 403, 타 소유자·혼합 ID 거부 및 부모 팬/크리에이터/제3자 비밀 공개 매트릭스를 HTTP와 실제 조회로 검증한다.
4. 부모 삭제 후 기존 앱 답글 목록/count에서도 노출되지 않고 답글 삭제는 부모를 유지한다. 기존 앱 다중 답글 기능은 유지한다.
5. 후원 숨김 후 관리자·레거시·V2 앱 목록에서 제외되고 메시지 원본·금액·금융 레코드가 그대로다.
종료 조건: 요청 동작이 관찰 가능하게 동작하고 위 증거, 테스트·빌드 결과, 계약 문서와 리뷰 판정이 기록되며 임시 자원이 정리되면 즉시 종료한다. 미검증은 성공으로 표시하지 않는다.
## Phase 1: 공통 계약과 데이터 보호 기반
- [x] **Task 1.1 / P1-T1: 공통 DTO·입력·인증 오류 경계**
- Files: M/P/dto/CreatorAdminCommentDtos.kt, M/P/domain/CreatorAdminCommentPolicy.kt, M/P/adapter/in/web/CreatorAdminCommentExceptionHandler.kt 및 필요한 범위 전용 예외/보안 handler; M/configs/SecurityConfig.kt, M/common/ExceptionHandlerFilter.kt는 필요한 경로 한정 변경만 허용.
- Test: T/P/CreatorAdminCommentHttpIntegrationTest.kt 및 정책 테스트.
- 제공: 작성자·답글 DTO, visibility/order/page 정책, HTTP 오류 wrapper, principal 기반 CREATOR 검사. 답글 DTO에는 작성자 및 isSecret을 포함한다.
- [x] RED: 실제 MVC 인증/오류/입력 정책 실패 테스트.
- [x] RED 확인: 초기 HTTP 18개 중 12개가 역할/오류 상태/wrapper 차이로 실패.
- [x] GREEN: 기존 경로 한정 예외 처리 패턴으로 구현.
- [x] GREEN 확인: 공유 계약 95개 통과(HTTP23/정책35/parser24/오류7/DTO6).
- [x] REFACTOR: 기존 AiCharacterAdminErrorContractTest 98개 통과, 전체 193개 실패/오류/skip 0. 명령 `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.admin.commentmanagement.CreatorAdminComment*Test' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.AiCharacterAdminErrorContractTest' --no-parallel --max-workers=1 --console=plain`. 이 HTTP 검증은 테스트 컨트롤러를 사용한 공통 경계 검증이며 실제 기능 endpoint/JWT 검증은 P3에서 별도 수행한다.
- [x] **Task 1.2 / P1-T2: 공유 부모 잠금·앱 공개/삭제 일관성**
- Files: M/v2/commentthread/port/out/CommentThreadLockPort.kt, M/v2/commentthread/adapter/out/persistence/DefaultCommentThreadLockRepository.kt.
- Modify: M/content/comment/AudioContentCommentService.kt, AudioContentCommentRepository.kt; M/explorer/profile/creatorCommunity/CreatorCommunityService.kt, comment/CreatorCommunityCommentRepository.kt; M/explorer/ExplorerService.kt, ExplorerQueryRepository.kt; M/v2/creator/channel/community/adapter/out/persistence/DefaultCreatorChannelCommunityQueryRepository.kt; M/v2/creator/channel/fantalk/adapter/out/persistence/DefaultCreatorChannelFanTalkQueryRepository.kt; M/v2/api/admin/aicharacter/fantalk/AiCharacterAdminFanTalkFacade.kt.
- Test: T/v2/commentthread/CommentThreadPrivacyIntegrationTest.kt, CommentThreadConcurrencyIntegrationTest.kt 및 기존 영향 테스트.
- 제공: lockContentRoot(rootId), lockCommunityRoot(rootId), lockFanTalkRoot(rootId). 기존 트랜잭션 안에서 PESSIMISTIC_WRITE 및 refresh. 관리자/레거시 수정·삭제·재활성화도 부모 먼저 잠근다. 커뮤니티는 post→root 순서.
- 새 관리자 답글 중복 판단은 잠금 후 현재 읽기를 사용한다. 기존 앱에는 단일 답글 제약을 추가하지 않는다.
- 비밀 노출: 활성 부모의 조회 권한과 답글 조회 권한을 모두 검사한다. 비밀 부모는 부모 팬/소유 크리에이터만, 일반 부모의 일반 팬 비밀 답글은 기존 작성자/크리에이터만 접근한다. 크리에이터 답글이면 부모 팬도 접근한다. 목록/count에 같은 정책.
- [x] RED: 비밀 답글/삭제 부모 조회 및 잘못된 부모 연결 실패 재현.
- [x] RED 확인: 257개 RED 실행에서 실제 privacy/count/잘못된 부모·stale insert 실패 확인.
- [x] GREEN: 공유 잠금과 관련 앱 조회/쓰기 최소 보정.
- [x] GREEN 확인: 수정 후 commentthread 80개, 실제 HTTP/경쟁 12개, 기존 community query 13개 모두 통과.
- [x] REFACTOR: 기존 앱 다중 답글·일반 팬 비밀 답글 정책 보존. nullable 프로필 회귀도 기본 이미지 projection으로 수정.
- [x] **P1-GATE:** 공통 계약과 잠금 인터페이스 확인, 기존 공개 계약 유지, 위 focused 테스트 증거 확인.
## Phase 2: 네 탭 API
P1-T1 계약 확정 후 서로 다른 기능 디렉터리를 병렬 작업할 수 있다. P1-T2와의 공유 경계는 lock port뿐이다. 모든 서비스는 읽기/쓰기 트랜잭션을 명시한다.
- [x] **Task 2.1 / P2-T1: 콘텐츠 댓글 관리**
- Files: M/P/content/{adapter/in/web/CreatorAdminContentCommentController.kt,application/CreatorAdminContentCommentService.kt,port/out/CreatorAdminContentCommentPort.kt,adapter/out/persistence/DefaultCreatorAdminContentCommentRepository.kt,dto/CreatorAdminContentCommentDtos.kt}.
- Test: T/P/content/CreatorAdminContentCommentIntegrationTest.kt.
- 소유 콘텐츠의 유효 팬 부모 댓글, 필터 전체 집계, 일괄 최신 답글·시리즈 관계. 기존 관리자 콘텐츠 범위 `duration != null AND (isActive OR releaseDate != null)` 재사용.
- 분류: 기존 theme.title `다시듣기`이면 LIVE_REPLAY, 아니면 시리즈 관계 존재 시 SERIES, 나머지 AUDIO. ID는 contentId 유지하고 시리즈 관계 배열 제공.
- [x] RED → 실패 확인: 목록·필터·소유권·답글 CRUD HTTP 테스트의 404 실패 확인.
- [x] GREEN → 통과 확인: 기존 엔티티와 공유 잠금으로 구현. 364개 통합 실행에서 콘텐츠 패키지 모두 통과.
- [x] REFACTOR: page/집계/최신 답글/시리즈 관계 일괄 조회. 실제 JWT 목록과 동시 POST [200,409] 통과. 레거시 앱 프로필 문제는 P3-R1로 추적.
- [x] **Task 2.2 / P2-T2: 팬톡 관리**
- Files: M/P/fantalk/{adapter/in/web/CreatorAdminFanTalkController.kt,application/CreatorAdminFanTalkService.kt,port/out/CreatorAdminFanTalkPort.kt,adapter/out/persistence/DefaultCreatorAdminFanTalkRepository.kt,dto/CreatorAdminFanTalkDtos.kt}.
- Test: T/P/fantalk/CreatorAdminFanTalkIntegrationTest.kt.
- CreatorCheers 재사용, 비밀 옵션 추가 없음. 최신 답글 삭제 시 이전 답글 표시.
- [x] RED → 실패 확인: 목록·최신 답글·CRUD/재등록·입력/권한 404 실패.
- [x] GREEN → 통과 확인: 소유 채널/원글/direct reply 검사 및 부모 잠금.
- [x] REFACTOR: 팬톡 96개+실제 HTTP/경쟁 12개 통과. 다른 크리에이터 작성 팬톡도 포함하는 회귀 RED→GREEN 완료.
- [x] **Task 2.3 / P2-T3: 커뮤니티 게시글·댓글 관리**
- Files: M/P/community/{adapter/in/web/CreatorAdminCommunityController.kt,application/CreatorAdminCommunityService.kt,port/out/CreatorAdminCommunityPort.kt,adapter/out/persistence/DefaultCreatorAdminCommunityRepository.kt,dto/CreatorAdminCommunityDtos.kt}.
- Test: T/P/community/CreatorAdminCommunityIntegrationTest.kt.
- 소유 활성 게시글·원문·기존 첨부 URL/가격/isFixed, 부모 댓글 수. 커뮤니티는 크리에이터 작성 원댓글도 포함하며 답글만 부모 수에서 제외한다. 별도 title 없음. 관리 목록은 요청 작성시각 정렬, 앱 기존 고정 우선 정렬은 변경하지 않는다.
- [x] RED → 실패 확인: 게시글/상세/댓글·필터·혼합 ID·비밀 답글/CRUD의 404 실패 확인.
- [x] GREEN → 통과 확인: post→root 잠금과 부모 공개 범위 상속. 신규 커뮤니티 패키지 모두 통과.
- [x] REFACTOR: 게시글별 count 일괄 조회. 실제 JWT 목록/상세와 동시 POST 통과. 기존 일반 팬 비밀 답글 회귀는 P3-R1로 추적.
- [x] **Task 2.4 / P2-T4: 후원 메시지 조회·숨김**
- Files: M/P/donation/{adapter/in/web/CreatorAdminDonationController.kt,application/CreatorAdminDonationService.kt,port/out/CreatorAdminDonationQueryPort.kt,adapter/out/persistence/DefaultCreatorAdminDonationQueryRepository.kt,dto/CreatorAdminDonationDtos.kt}.
- Modify: M/explorer/profile/channelDonation/ChannelDonationMessageRepository.kt의 공통 목록/count 조건.
- Test: T/P/donation/CreatorAdminDonationIntegrationTest.kt.
- 기존 HideCreatorChannelDonationService 재사용. 정산 서비스/금융 모델 변경 금지.
- [x] RED → 실패 확인: 새 경로 404와 레거시 숨김 row 포함 실패 재현.
- [x] GREEN → 통과 확인: 소유 채널 전체 기간 목록과 기존 숨김 연결. 신규 후원 패키지 모두 통과.
- [x] REFACTOR: V2 후원·홈·레거시 직접 영향 검증과 금융/메시지 원본 불변 통과. 정산 코드 변경 없음.
- [x] **P2-GATE:** 네 탭 실제 영속성/HTTP 동작과 필터·정렬·개수·답글·금융 불변 테스트 확인. 상세 이력은 verification.md.
## Phase 3: 통합 검증·명세·리뷰
- [x] **Task 3.1 / P3-T1:** 기능별 테스트와 실제 HTTP 서버/경쟁 검증 완료. 최종 `./gradlew bootJar ktlintCheck --no-parallel --max-workers=1 --console=plain` 성공. LSP 미제공이며 Kotlin 컴파일 성공으로 기록. 전체 테스트 미실행.
- [x] **Task 3.2 / P3-T2:** 실제 19 operations와 DTO/오류/null/시간/ID/page/삭제 의미를 api-contract.md/openapi.yaml에 작성하고 화면 대응표·예시·스키마 선행조건을 implementation-notes.md에 기록. YAML/로컬 참조 해석 검증, 전용 OpenAPI validator 미실행. 문서 작업 TDD 예외: 실제 코드/HTTP 대조.
- [x] **P3-GATE:** 독립 reviewer가 PRD·diff·검증 증거를 검토했고 REV-001 수정 후 변경분 재리뷰 APPROVE. 최종 120개 focused 테스트·실제 HTTP/경쟁·bootJar·ktlintCheck 성공. 전체 suite/운영 MySQL 미검증은 verification.md에 명시.
## 검증 명령
```bash
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.admin.commentmanagement.*'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.commentthread.*'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.content.AiCharacterAdminAudioContentCommentTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.community.AiCharacterAdminCommunityPostCommentTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.fantalk.*'
./gradlew test --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.creator.channel.fantalk.*' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.fantalk.*'
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.donation.*' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.donation.*'
./gradlew bootJar
```
전체 테스트는 저장소 규칙상 사용자 실행 `./gradlew test`로 분리한다. 기능별 성공을 전체 성공으로 표시하지 않는다.
## 검증 기록
- 구현 전 기준: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.donation.adapter.out.persistence.DefaultHideCreatorChannelDonationRepositoryTest' --console=plain` 성공. XML 기준 7 tests, 0 failures/errors/skipped. 메시지 금액·본문·작성자·시각 유지 및 반복 숨김 선례 확인.
- 운영 MySQL DDL/문자셋/인덱스는 미확인. 엔티티 TEXT 매핑을 기준으로 UTF-8 65,535 bytes 상한을 검증하고, 배포 전 실제 컬럼 utf8mb4/TEXT 용량 확인 SQL을 문서화한다. 반환 mutation은 data:null, 이후 DB 재조회 시각을 사용하므로 저장 전 시각 응답 불일치를 만들지 않는다.
- P1-T2/P2 RED 실행: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.admin.commentmanagement.content.*' --tests 'kr.co.vividnext.sodalive.v2.creator.admin.commentmanagement.fantalk.*' --tests 'kr.co.vividnext.sodalive.v2.creator.admin.commentmanagement.community.*' --tests 'kr.co.vividnext.sodalive.v2.creator.admin.commentmanagement.donation.*' --tests 'kr.co.vividnext.sodalive.v2.commentthread.*' --no-parallel --max-workers=1 --console=plain`. 1분39초, 257개 실행/185개 실패. 컴파일 성공. 새 endpoint 404, 삭제/비밀 답글 노출, 잘못된 부모 허용, 삭제된 부모의 stale 상태 insert, 레거시 숨김 후원 포함을 실제 assertion으로 재현했다. 전체 출력: `/Users/klaus/.local/share/opencode/tool-output/tool_1f6f3d33e00147185R269DCJap`.
- RED 실행 중 기존 번역 스케줄러의 H2 `FOR UPDATE SKIP LOCKED` SQL 오류와 종료 Redis InterruptedException 로그가 함께 관찰됐다. 댓글 API assertion 실패와 구분하며 관련 없는 스케줄러 제품 코드는 변경하지 않는다.
- 기존 characterization 중 잘못된/비활성 FanTalk 부모 허용 및 숨김 후원 레거시 노출 유지 assertion은 새 사용자 요구와 반대다. 해당 기대를 거부+DB무변경 또는 숨김 제외+금융불변으로 갱신하고 나머지 기존 검증은 유지한다.
- 통합 1차: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.admin.commentmanagement.*' --tests 'kr.co.vividnext.sodalive.v2.commentthread.*' --no-parallel --max-workers=1 --console=plain` 6분43초, 364개 중 360개 통과/4개 실패. 모든 기능 패키지와 privacy 테스트 통과. 실제 HTTP의 레거시 앱 조회에서 H2 DATE_FORMAT 미등록이 발견돼 기존 H2MysqlDateFunctions alias를 E2E fixture에 등록했다.
- 앱/AI관리자 직접 영향 회귀 1차: 위 실제 HTTP 2개 클래스 및 계획의 콘텐츠·팬톡·커뮤니티·후원 관련 기존 테스트 실행, 3분35초, 349개 중 346개 통과/3개 실패. 로그에서 레거시 콘텐츠·커뮤니티 응답의 null profileUrl NPE 2개와 V2 커뮤니티의 일반 팬 비밀 답글 공개범위 확대 1개 확인. 다른 assertion은 유지했다.
### 추가 회귀 수정
- [x] **P3-R1: 기존 앱 nullable 프로필·일반 팬 비밀 답글 정책 보존.** 레거시 댓글 root/reply 이미지 projection에서 기존 기본 이미지를 사용한다. 비밀 부모는 원댓글 팬/소유 크리에이터만 접근한다. 일반 부모의 비밀 답글은 기존 답글 작성자/소유 크리에이터만 접근하되, 크리에이터가 쓴 답글이면 원댓글 팬에게도 허용한다. 다른 팬이 쓴 비밀 답글을 부모 팬에게 새로 공개하지 않는다. 기존 `DefaultCreatorChannelCommunityQueryRepositoryTest.shouldFindVisibleRootCommentsWithLatestReply`는 수정하지 않고 보존했다. 공유 새 privacy matrix를 보강하고 `./gradlew test --tests '*CreatorAdminComment*EndToEndTest' --tests 'kr.co.vividnext.sodalive.v2.commentthread.*' --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.adapter.out.persistence.DefaultCreatorChannelCommunityQueryRepositoryTest' --console=plain` 105/105 통과.
- [x] **P3-R2: 다른 크리에이터의 팬톡 누락 보정.** `CreatorAdminFanTalkIntegrationTest.shouldManageRootWrittenByAnotherCreator` 단독 실행으로 누락 실패를 확인했다. repository/service 두 조건을 작성자 ID 비교로 수정한 뒤 팬톡 전체 96개 및 실제 HTTP/경쟁 12개가 통과했다. 소유 채널 본인 root만 제외하고 다른 크리에이터의 팬 활동은 관리 가능하다.
- 포맷 검증 1차에서 변경 파일의 인자 줄바꿈과 단일 DTO 파일명 오류가 발견됐다. 변경 Kotlin 파일만 대상으로 ktlintFormat을 실행하고 DTO 파일을 클래스명에 맞췄다. 최종 `./gradlew bootJar ktlintCheck --no-parallel --max-workers=1 --console=plain` 성공(1분10초), `git diff --check` 성공. 공유 파일이나 무관한 기존 파일은 포맷하지 않았다.
- [x] **P3-R3 / REV-001: 일반 팬 비밀 답글 작성 보존.** 두 서비스에서 유효 비밀 여부를 한 번 계산하고 크리에이터 답글만 부모 상속/구매 면제한다. 일반 팬의 요청 비밀·구매 조건과 비밀 부모 보호를 유지한다. 실제 Order/UseCan을 사용하는 새 테스트 8개 중 6개 RED 확인 후, 관련 120개 전부 GREEN 및 ktlintCheck/bootJar 성공(1분41초). 독립 변경분 재리뷰 APPROVE. 1차 REJECT 및 수정 증거는 reviews/gate-review.md에 보존했다.
- [x] **P3-R4: MVC slice 보안 빈 구성 회귀 수정.** 사용자 보고의 MainContentAllControllerTest, ContentOverviewControllerTest, AudioRecommendationControllerTest, HomeFollowingControllerTest, HomeOnAirLiveControllerTest 10개가 CreatorAdminCommentSecurityErrorHandler 빈 누락으로 모두 실패함을 재현했다. SecurityConfig에 필수 댓글 보안 handler/resolver/writer 3개를 명시적으로 @Import해 일반 component scan이 없는 MVC slice에서도 동일 구성이 만들어지도록 수정했다. 테스트와 필터/권한 규칙은 수정하지 않았다.
- RED: 아래 명령에서 댓글 HTTP integration과 ktlintCheck를 제외한 5개 클래스 실행, 10/10 빈 누락 실패(33초).
- GREEN: 아래 명령 성공(1분24초). XML 6개 클래스 기준 33 tests, failures/errors/skipped 모두 0. 기존 실패 10개와 full-context 댓글 HTTP 보안 계약 23개 모두 통과, Kotlin main/test 컴파일 및 ktlintCheck 성공.
- 전체 suite는 재실행하지 않았다. 기존 Redis 종료 재연결 경고는 관찰됐고 테스트 실패는 없었다.
```bash
./gradlew test \
--tests '*MainContentAllControllerTest' \
--tests '*ContentOverviewControllerTest' \
--tests '*AudioRecommendationControllerTest' \
--tests '*HomeFollowingControllerTest' \
--tests '*HomeOnAirLiveControllerTest' \
--tests 'kr.co.vividnext.sodalive.v2.creator.admin.commentmanagement.CreatorAdminCommentHttpIntegrationTest' \
ktlintCheck --console=plain --no-parallel --max-workers=1
```
### 커밋 직전 검증 (2026-11-20)
- 사용자 `/commit-with-validation` 요청으로 현재 변경의 커밋을 승인받고 공용 원본 절차를 적용한다.
- 아래 명령 성공(1분51초). XML 13개 클래스의 133 tests, failures/errors/skipped 모두 0.
MVC slice 10개, 댓글 HTTP 보안 23개, 스레드 보호 88개, 실제 HTTP·경쟁 12개를 확인했다.
- `bootJar` 성공, `ktlintCheck` 성공(UP-TO-DATE), `git diff --check` 성공.
- 기존 H2 번역 스케줄러의 `FOR UPDATE SKIP LOCKED` 오류와 Redis 종료 InterruptedException 로그는 다시 관찰됐으며 테스트 실패는 없었다.
- 전체 suite와 운영 MySQL 검증은 미실행이다. 전체 테스트의 사용자 실행 명령은 `./gradlew test`다.
```bash
./gradlew test \
--tests '*MainContentAllControllerTest' \
--tests '*ContentOverviewControllerTest' \
--tests '*AudioRecommendationControllerTest' \
--tests '*HomeFollowingControllerTest' \
--tests '*HomeOnAirLiveControllerTest' \
--tests 'kr.co.vividnext.sodalive.v2.creator.admin.commentmanagement.CreatorAdminCommentHttpIntegrationTest' \
--tests 'kr.co.vividnext.sodalive.v2.commentthread.*' \
--tests '*CreatorAdminComment*EndToEndTest' \
ktlintCheck bootJar --console=plain --no-parallel --max-workers=1
```
@@ -0,0 +1,91 @@
# 크리에이터 관리자 댓글 관리 PRD
## 문서 정보
- 작성일: 2026-11-20
- 상태: 구현·기능 검증·독립 최종 리뷰 완료. 전체 suite 및 운영 MySQL 검증은 verification.md의 미검증 범위로 구분한다.
- 대상: 기존 Creator Admin의 콘텐츠 댓글, 팬레터, 커뮤니티 댓글, 채널 후원 메시지 관리.
- 결정권자: 요청 사용자. 기술 선택은 기존 코드 근거에 따라 구현자가 결정한다.
- 구현 계획: `plan-task.md`. 최종 API 계약: `api-contract.md`, `openapi.yaml`. 검증: `verification.md`, `reviews/gate-review.md`.
## 1. 목표와 제외 범위
Mock을 실제 영속 데이터에 연결하고 크리에이터 본인 소유 데이터만 조회·관리한다. 기존 인증, 응답,
엔티티, 삭제 및 금융 경계를 재사용하며 프론트엔드 저장소에는 접근하지 않는다.
팬 원댓글 작성·수정, 커뮤니티 게시글 작성·수정·삭제, 결제·취소·환불, 초안 저장, 새로운 캐시·검색 시스템은 제외한다.
운영 DB 변경, 운영 배포, commit, push는 사용자 승인 없이 수행하지 않는다.
## 2. 확정 요구사항
| ID | 범위 | 요구사항과 수용 기준 |
|---|---|---|
| CM-001 | 인증 | Bearer 인증 컨텍스트에서 작성자와 관리 주체를 결정한다. 다른 크리에이터 자원과 혼합 부모 ID 요청은 거부한다. 미인증과 권한 부족을 구분한다. |
| CM-002 | 콘텐츠 | 소유 콘텐츠 전체의 부모 댓글을 조회한다. 오디오·시리즈·다시보기의 실제 관계, 제목과 ID를 응답한다. |
| CM-003 | 팬레터 | 기존 팬톡(FanTalk/CreatorCheers)을 사용해 소유 채널의 글과 크리에이터 답글을 조회·관리한다. 비밀 구분 없는 기존 공개 정책을 유지한다. |
| CM-004 | 커뮤니티 | 게시글 목록, 원문 상세, 선택한 게시글의 부모 댓글을 제공한다. 가격·첨부·부모 댓글 수를 제공하고, 프론트는 본문 미리보기를 제목 자리에 표시하며 isFixed를 공지 배지로 사용한다. |
| CM-005 | 후원 | 소유 채널의 후원 메시지와 금액을 조회한다. 삭제는 관리자 및 앱 노출만 제거하고 금융 원장·잔액·매출·정산을 보존한다. |
| CM-006 | 목록 | 기본 size 10, 서버 page 0-based, 최신/오래된순과 작성 시각+고유 ID 보조 정렬을 제공한다. 답글은 페이지 항목과 부모 수에서 제외한다. |
| CM-007 | 필터 | 콘텐츠·커뮤니티 댓글·후원은 전체/일반/비밀 필터를 제공한다. all/public/secret은 필터 적용 전 조회 범위 전체, totalCount는 선택 필터 결과 수다. |
| CM-008 | 답글 | 크리에이터 답글 등록·수정·삭제·재등록을 제공한다. 수정·삭제는 본인 작성 답글만 가능하며 다른 사용자 대댓글을 없애지 않는다. 기존 활성 크리에이터 답글 중 최신 하나를 표시하며 모두 삭제돼야 새 답글을 등록할 수 있다. |
| CM-009 | 입력 | 앞뒤 공백을 제거하고 공백뿐인 입력과 저장 한도 초과를 거부한다. 한글·일본어·이모지·줄바꿈을 보존하고 잘라 저장하지 않는다. |
| CM-010 | 비밀 | 콘텐츠·커뮤니티 답글은 부모 공개 범위를 상속한다. 비밀 스레드는 원댓글 팬과 소유 크리에이터에게만 노출한다. 앱 조회도 동일하게 검증한다. |
| CM-011 | 삭제 | 부모 삭제 후 답글을 직접 조회해도 노출되지 않는다. 답글 삭제는 부모를 보존한다. 기존 soft delete를 유지하고 복구 API를 새로 만들지 않는다. |
| CM-012 | 경쟁 | 관리자 답글 동시 등록, 부모 삭제와 답글 등록 경쟁을 트랜잭션과 DB 잠금/제약으로 보호한다. 기존 다중 답글 지원을 글로벌 제약으로 축소하지 않는다. |
| CM-013 | 계약 | 성공은 HTTP 200과 ApiResponse, 목록은 items/totalCount 기반이다. null·시간·ID·오류·페이지 초과·동일 내용 수정 의미를 최종 계약에 명시한다. |
| CM-014 | 검증 | 실제 영속 계층과 HTTP 경계에서 네 탭, 권한, 비밀글, 동시성, 삭제/개수, 금융 불변과 기존 앱 회귀를 검증한다. |
## 3. 실제 코드 분석과 재사용 근거
아래 경로에서 `src/main/kotlin/kr/co/vividnext/sodalive/`는 생략한다.
| 확인 대상 | 실제 파일 | 재사용 및 주의점 |
|---|---|---|
| 관리자 인증 | `creator/admin/content/CreatorAdminContentController.kt`, `jwt/TokenProvider.kt` | CREATOR 역할 및 principal Member를 사용한다. AI 캐릭터 ADMIN 대리관리와 분리한다. |
| 공통 응답 | `common/ApiResponse.kt`, `common/SodaExceptionHandler.kt` | 성공 wrapper는 호환된다. 일반 SodaException이 HTTP 4xx를 보장하지 않으므로 범위 내 기존 호환 처리 선례를 확인한다. |
| 콘텐츠 댓글 | `content/comment/AudioContentComment.kt`, `AudioContentCommentRepository.kt` | content_comment의 parent/isActive/isSecret을 재사용한다. 답글 쿼리에 부모 활성·비밀 접근 검사가 빠져 있다. |
| 팬레터 | `explorer/profile/CreatorCheers.kt`, `explorer/ExplorerService.kt` | 사용자가 팬레터와 기존 팬톡(FanTalk)이 같은 기능임을 확인했다. 채널 원글과 답글을 재사용하며 isSecret 필드를 추가하지 않는다. |
| 팬톡 조회 | `v2/creator/channel/fantalk/adapter/out/persistence/DefaultCreatorChannelFanTalkQueryRepository.kt` | 부모 페이지와 크리에이터 답글 일괄 조회가 있다. 기존 응답은 크리에이터 답글 여러 개를 지원한다. |
| 커뮤니티 | `explorer/profile/creatorCommunity/CreatorCommunity.kt` | content, price, imagePath, audioPath, isFixed를 재사용한다. 별도 title 필드는 없다. |
| 커뮤니티 앱 | `v2/creator/channel/community/adapter/out/persistence/DefaultCreatorChannelCommunityQueryRepository.kt` | 안정적 정렬·부모 수 집계 선례가 있다. 비밀 답글 조건은 원댓글 팬이 아닌 답글 작성자만 허용해 요구와 차이가 있다. |
| 후원 숨김 | `v2/creator/channel/donation/adapter/out/persistence/DefaultHideCreatorChannelDonationRepository.kt` | 기존 isHidden만 원자적으로 갱신한다. 금액·원문·수정 시각을 유지하며 반복 삭제도 성공한다. |
| 후원 앱 | `explorer/profile/channelDonation/ChannelDonationMessageRepository.kt` | 레거시 목록/count의 isHidden 필터 누락을 보정해야 한다. V2 채널·홈은 이미 숨김을 적용한다. |
| 정산 | `creator/admin/calculate/channelDonation/CreatorAdminChannelDonationCalculateQueryRepository.kt` | UseCan/UseCanCalculate 기반이다. 메시지 관리 API로 대체하거나 금융 필드를 수정하지 않는다. |
| 유사 관리자 기능 | `v2/api/admin/aicharacter/content/`, `community/`, `fantalk/` | 기존 소유권·부모 관계 검사와 댓글 soft delete·입력 검증을 참고한다. ADMIN target resolver를 일반 크리에이터 권한으로 사용하지 않는다. |
신규 기능은 기존 지침대로 v2 아래에 배치하고 기존 엔티티를 재사용한다. 기술 스택은 Kotlin 1.6.21,
Java 17, Spring Boot 2.7.14, JPA/QueryDSL 5, JUnit 5, Gradle 8.1.1이다.
기존 댓글 본문은 엔티티상 TEXT이며 운영 컬럼의 실제 DDL·문자셋·시각 정밀도는 아직 확정하지 못했다.
후원 is_hidden DDL은 `docs/20261105_채널후원메시지숨김/channel_donation_message_is_hidden_ddl.sql`에 있다.
## 4. 미결 정책
| ID | 결정 필요 사항 | 근거와 영향 |
|---|---|---|
| OQ-001 (해결) | 화면의 팬레터는 기존 팬톡(FanTalk/CreatorCheers)을 의미한다. | 사용자 확인. 기존 데이터와 공개 정책을 재사용하고 별도 팬레터 테이블을 만들지 않는다. |
| OQ-002 (해결) | 기존 활성 크리에이터 답글 중 최신 하나를 관리자 화면에 표시한다. 표시된 답글 삭제 시 이전 활성 답글이 나타나며, 활성 크리에이터 답글이 없어야 새로 등록할 수 있다. | 사용자 1안 선택. 기존 답글 데이터와 앱의 다중 답글 표시는 보존한다. 최신 선택은 createdAt DESC, id DESC이며 수정 시각은 사용하지 않는다. 글로벌 유일 제약을 추가하지 않는다. |
| OQ-003 (해결) | 본문 미리보기를 제목 자리에 표시하고 isFixed를 공지 배지로 연결한다. | 사용자 확인. 별도 제목·공지 컬럼이나 게시글 변경 API를 추가하지 않는다. |
콘텐츠 분류·비활성 원본·차단 작성자·입력 상한의 최종 계약은 api-contract.md에 기록했다. 운영 DDL의 실제 문자셋·용량·인덱스는 배포 전 확인한다.
이미 명시된 소유 채널의 비밀 후원 조회, 앱 전체 숨김, 작성자 본인 답글 변경 권한은 반복 질문하지 않는다.
## 5. 완료 증거
- 네 탭과 커뮤니티 상세의 실제 HTTP/영속성 성공 및 실패 시나리오.
- 전체 범위 필터 개수, 동시간 정렬, 빈 목록·범위 초과 페이지 검증.
- 답글 CRUD/재등록·중복/경쟁·입력 한계와 Unicode 검증.
- 다른 크리에이터 및 혼합 ID 거부, 비밀 본문 노출 방지, 앱 삭제/답글 회귀 검증.
- 후원 숨김 전후 금융 레코드 불변 증거.
- 기능별 API 명세, 화면 대응표, 비밀값 없는 사용 예시, 적용 순서와 실행/미실행 검사 기록.
## 6. 결정 기록
| 날짜 | 상태 | 결정 | 근거 |
|---|---|---|---|
| 2026-11-20 | 확정 | Creator Studio는 기존 크리에이터 관리자를 의미한다. | 사용자 명시 |
| 2026-11-20 | 확정 | 기존 모델과 앱 경로를 먼저 분석하고 근거 없는 제품 정책만 인터뷰한다. | 사용자 명시 |
| 2026-11-20 | 미결 | 팬레터 대응·기존 다중 답글·커뮤니티 표시 정책은 위 OQ에 따라 확정한다. | 실제 모델/조회 코드 |
| 2026-11-20 | 확정 | OQ-001 해결: 팬레터는 기존 팬톡(FanTalk/CreatorCheers)이다. | 사용자 답변 “맞다.” |
| 2026-11-20 | 확정 | OQ-002 해결: 관리자에서는 최신 활성 크리에이터 답글 하나를 표시하고, 삭제하면 이전 활성 답글을 표시한다. 활성 답글이 모두 없어야 재등록할 수 있다. | 사용자 1안 선택 |
| 2026-11-20 | 확정 | OQ-003 해결: 커뮤니티 본문 미리보기를 제목 자리에 표시하고 isFixed를 공지 배지로 연결한다. | 사용자 답변 “네” |
| 2026-11-20 | 확정 | 목표를 완전히 충족하는 최소 구현, 기존 코드 재사용, 독립 작업 병렬화로 빠르게 완료한다. 기능·권한·데이터 보존 검증은 유지한다. | 사용자 추가 지시 |
@@ -0,0 +1,38 @@
# 댓글 관리 최종 게이트 리뷰
- 일자: 2026-11-20
- 대상: 현재 uncommitted working tree, PRD CM-001~014와 API 계약.
- 리뷰어: 독립 Oracle 1명. 코드·기존 호출 경로·현재 실제 HTTP XML을 읽고 판정했다.
- 1차 판정: REJECT. 아래 확정 회귀를 수정하고 해당 부분만 재검토한다.
## 확정 발견 사항
| ID | 심각도 | 상태 | 위반 요구 | 내용 |
|---|---|---|---|---|
| REV-001 | High | 수정 검증 완료·재리뷰 대기 | CM-010, CM-014, 기존 일반 답글 정책 보존 | 레거시 콘텐츠·커뮤니티 작성 서비스의 `parent?.isSecret ?: isSecret`가 일반 팬이 공개 부모에 비밀 답글을 요청해도 false로 저장한다. |
근거: `AudioContentCommentService.registerComment`, `CreatorCommunityService.createCommunityPostComment`.
리드가 실제 서비스 코드를 다시 읽고 동일 원인을 확인했다. 직접 비밀 답글 fixture를 저장하는 조회 테스트만으로는
요청의 isSecret이 저장 단계에서 사라지는 회귀를 검출하지 못했다.
최소 수정: 크리에이터 답글만 부모 공개 범위를 상속한다. 일반 팬은 요청의 비밀 설정과 기존 구매 검증을 유지하며
비밀 부모 아래에서는 공개로 넓힐 수 없다. 실제 서비스 쓰기→flush/clear→DB isSecret 및 제3자 목록/count를 검증한다.
추가 차단 사유는 발견되지 않았다. 리뷰어는 현재 XML의 팬톡 96개와 실제 HTTP·경쟁 12개 통과 및 실제 응답을 확인했다.
전체 suite·운영 MySQL 검증은 미검증 상태로 유지한다.
## 1차 수정과 검증
- 두 서비스에서 `isCreatorReply = parent != null && 작성자 == 소유자`, `effectiveSecret = parent?.isSecret == true || (isSecret && !isCreatorReply)`를 계산해 저장한다.
- 구매 검증은 `effectiveSecret && !isCreatorReply && !구매함`에 적용한다. 일반 팬의 기존 구매 조건과 비밀 요청을 보존하고 크리에이터 답글만 상속/면제한다.
- 새 `CommentThreadSecretWriteIntegrationTest`는 실제 Order/UseCan 구매와 서비스 쓰기를 사용한다. 8개 중 6개 RED(비밀 저장값 false 2개, 미구매 저장 허용 4개)를 확인했다.
- 수정 후 해당 8개를 포함한 commentthread·실제 HTTP/경쟁·기존 AI 관리자 댓글 회귀 총 120개 통과. `ktlintCheck`, `bootJar`도 성공(1분41초). 리드가 XML 9개 클래스의 실패/오류/skip 0과 수정 코드를 직접 확인했다.
- 재리뷰는 이 두 서비스와 새 테스트 변경분에 한정하며 최초 전체 검토를 반복하지 않는다.
## 최종 판정
독립 변경분 재리뷰: **APPROVE**. REV-001 해소, 추가 차단 사유 없음.
리뷰어가 두 서비스의 유효 비밀 여부·구매 조건과 실제 서비스 테스트를 확인했으며 현재 XML 9개 클래스의
120개 테스트에서 실패·오류·skip 모두 0임을 직접 확인했다. 테스트 재실행이나 코드 수정은 하지 않았다.
이 판정은 기존 전체 리뷰와 변경분 재리뷰를 합친 최종 gate 통과다.
전체 suite·운영 MySQL 잠금/격리 검증은 별도 미검증 범위로 유지한다.
@@ -0,0 +1,21 @@
-- 배포 담당자용 MySQL 읽기 전용 사전 확인. 이 작업에서는 운영 DB에 실행하지 않았다.
-- 기존 테이블을 재사용한다. TEXT의 UTF-8 65,535 byte 입력 계약을 적용하기 전에
-- 실제 컬럼 타입과 utf8mb4 문자셋, timestamp 정밀도를 확인한다.
SELECT TABLE_NAME, COLUMN_NAME, COLUMN_TYPE, CHARACTER_SET_NAME, COLLATION_NAME,
CHARACTER_MAXIMUM_LENGTH, CHARACTER_OCTET_LENGTH, DATETIME_PRECISION, IS_NULLABLE
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME IN ('content_comment', 'creator_cheers', 'creator_community_comment',
'creator_community', 'channel_donation_message')
AND COLUMN_NAME IN ('comment', 'cheers', 'content', 'additional_message',
'created_at', 'updated_at', 'is_hidden')
ORDER BY TABLE_NAME, ORDINAL_POSITION;
-- 기존 인덱스와 중복되지 않는지 확인한 후 필요한 인덱스만 별도 적용한다.
-- 새 관리자 전용 테이블이나 글로벌 단일 답글 unique key는 만들지 않는다.
SELECT TABLE_NAME, INDEX_NAME, NON_UNIQUE, SEQ_IN_INDEX, COLUMN_NAME
FROM information_schema.STATISTICS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME IN ('content_comment', 'creator_cheers', 'creator_community_comment',
'creator_community', 'channel_donation_message', 'series_content')
ORDER BY TABLE_NAME, INDEX_NAME, SEQ_IN_INDEX;
@@ -0,0 +1,90 @@
# 검증 기록
## 실행 환경과 범위
2026-11-20, Java 17/Gradle 8.1.1, 로컬 H2(MySQL mode), 테스트 전용 embedded Redis.
운영 DB·운영 배포·commit·push는 수행하지 않았다. 전체 테스트는 자동 실행하지 않았다.
LSP 도구가 현재 host에 없어 별도 diagnostics 대신 실제 Kotlin main/test 컴파일 결과를 확인했다.
## 실행 결과
| 단계 | 결과 | 확인한 경계 |
|---|---|---|
| 기존 후원 숨김 기준 | 7/7 통과 | 메시지 원본/금액/시각 불변, 반복 숨김 |
| 공통 계약 RED→GREEN | 신규 95 + 기존 AI 관리자 오류 98 통과 | 경로 한정 인증·역할·오류 wrapper·입력·DTO |
| 기능/앱 RED | 257개 중 185개 실패 | 미구현 404, 실제 삭제/비밀 누출·잘못된 부모 허용 재현 |
| 통합 1차 | 364개 중 360개 통과 | 네 기능 테스트 및 앱 privacy 통과, 실제 HTTP의 H2 날짜 alias 누락 4개 발견 |
| 앱 기존 회귀 | 349개 중 346개 통과 | 실제 HTTP의 nullable 프로필 NPE 2개, 기존 일반 팬 비밀 답글 공개 확대 1개 발견 |
| 앱 회귀 수정 후 | 105/105 통과 | 실제 HTTP 12 + commentthread 80 + 기존 커뮤니티 query 13 |
| 타 크리에이터 팬톡 RED | 1개 의도한 실패 | 작성자 역할 전체 제외로 팬톡 누락 |
| 팬톡 수정 후 | 108/108 통과 | 팬톡 96 + 실제 JWT HTTP·경쟁 12 |
| 최종 빌드/포맷 | 성공, 1분10초 | `./gradlew bootJar ktlintCheck --no-parallel --max-workers=1 --console=plain` |
| 최종 리뷰 REV-001 RED→GREEN | 새 8개 중 6개 RED 후 관련 120/120 통과 | 일반 팬의 비밀 답글 실제 쓰기/구매 검증 보존, 실제 HTTP12 포함 |
| REV-001 이후 빌드/포맷 | 성공, 1분41초 테스트 포함 | 아래 `ktlintCheck bootJar test` 명령 |
실행별 테스트 집합은 겹치므로 위 숫자를 합쳐 고유 테스트 개수로 보고하지 않는다.
전체 suite 명령은 사용자 실행용 `./gradlew test`다. 새 기능 및 직접 영향 경로만 검증했다.
REV-001 최종 수정 검증 명령:
```bash
./gradlew ktlintCheck bootJar test \
--tests 'kr.co.vividnext.sodalive.v2.commentthread.*' \
--tests '*CreatorAdminComment*EndToEndTest' \
--tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.content.AiCharacterAdminAudioContentCommentTest' \
--tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.community.AiCharacterAdminCommunityPostCommentTest' \
--console=plain
```
현재 XML은 이 실행의 120개 결과다. `CommentThreadSecretWriteIntegrationTest`가 실제 작성→flush/clear→DB 비밀값과
제3자 목록/count 비노출, 미구매 거부/insert 없음을 검사한다. 기존 실제 HTTP/경쟁 12개도 최종 코드에서 다시 통과했다.
## 실제 HTTP QA
최종 실제 HTTP 호출은 리드가 다음 명령으로 실행했다. `RANDOM_PORT` 서버에 TestRestTemplate이 실제 소켓 요청을 보내며,
TokenProvider가 발급하고 Redis에 저장한 JWT와 커밋된 JPA fixture를 사용한다. MockMvc가 아니다.
```bash
./gradlew test \
--tests 'kr.co.vividnext.sodalive.v2.creator.admin.commentmanagement.fantalk.*' \
--tests 'kr.co.vividnext.sodalive.v2.creator.admin.commentmanagement.CreatorAdminComment*EndToEndTest' \
bootJar ktlintCheck --no-parallel --max-workers=1 --console=plain
```
이 실행의 테스트 108개와 bootJar는 성공했으며 이후 ktlint에서 인자 줄바꿈/DTO 파일명 오류를 발견했다.
변경 파일만 포맷하고 단일 DTO 파일명을 클래스명에 맞춘 뒤 별도 `bootJar ktlintCheck`가 성공했다. 포맷은 동작을 바꾸지 않았다.
아래 artifact의 기준 디렉터리는 `build/test-results/test/`다. Gradle의 후속 test 실행은 해당 XML을 교체할 수 있다.
| 시나리오 | 기대/관측 | 판정 | Artifact |
|---|---|---|---|
| 네 탭 및 게시글 상세 | 각각 200, 실제 fixture ID/본문/개수 반환 | PASS | `TEST-kr.co.vividnext.sodalive.v2.creator.admin.commentmanagement.CreatorAdminCommentEndToEndTest.xml` |
| 무토큰/USER JWT | 각 목록·상세에서 401/403 및 success:false | PASS | 같은 XML `shouldRejectAnonymousAndUserJwtAtRealHttpBoundary` |
| 세 스레드 등록·재조회·부모 삭제 | 등록 200/data:null, 소유자 답글 재조회, 삭제 후 관리자/앱 totalCount=0 및 빈 목록 | PASS | 같은 XML `shouldCreateReadBackAndHideReplyAfterParentDeletion` |
| 세 종류 동시 답글 등록 | 응답 [200,409], DB 활성 소유자 답글 정확히 1개 | PASS | `TEST-kr.co.vividnext.sodalive.v2.creator.admin.commentmanagement.CreatorAdminCommentConcurrencyEndToEndTest.xml` |
| 부모 삭제와 등록 경쟁 | 선후순서와 관계없이 삭제 뒤 관리자·앱에 스레드 비노출 | PASS | 같은 XML의 삭제/등록 경쟁 케이스 |
| 팬톡 타 크리에이터 작성자 | 소유 채널에 다른 크리에이터가 남긴 글도 조회·삭제 가능 | PASS | `TEST-kr.co.vividnext.sodalive.v2.creator.admin.commentmanagement.fantalk.CreatorAdminFanTalkIntegrationTest.xml` |
실제 응답 발췌(테스트 fixture이며 실제 사용자 정보·토큰 없음):
```text
GET /api/v2/creator-admin/comment-management/content/comments -> 200
data.totalCount=1, page=0, size=10, counts={all:1,public:1,secret:0}
GET /api/v2/creator-admin/comment-management/community/posts/7 -> 200
data={postId:7,content:"P3 community post",price:0,imageUrl:null,audioUrl:null,isFixed:false,commentCount:1,...}
GET /api/v2/creator-admin/comment-management/content/comments (무토큰) -> 401
{"success":false,"message":"로그인 정보를 확인해주세요.","data":null,"errorProperty":null}
POST /api/v2/creator-admin/comment-management/fantalks/2/replies (동시 2회) -> 200 / 409
409: {"success":false,"message":"이미 등록되어 있습니다.","data":null,"errorProperty":null}
```
각 테스트의 AfterEach가 커밋된 소유 fixture와 JWT를 정리한다. 경쟁 테스트는 Future/latch 제한 시간과 executor 종료 확인을 사용한다.
테스트 프로세스 종료 로그에서 EntityManagerFactory/Hikari 종료를 확인했다. 별도 상시 QA 서버는 실행하지 않았다.
## 한계와 기존 로그
- 운영 MySQL의 실제 문자셋·컬럼 용량·인덱스·잠금 격리 수준은 미확인이다. `schema-preflight.sql`과 기존 is_hidden DDL 적용 여부 확인이 배포 선행조건이다.
- H2 테스트는 실제 영속/트랜잭션 경계를 검증하지만 MySQL 운영 부하·다중 프로세스 검증을 대신하지 않는다.
- 기존 번역 스케줄러의 H2 `FOR UPDATE SKIP LOCKED` 문법 오류와 Redis 종료 재연결 로그가 관찰됐다. 댓글 assertion과 분리해 기록했으며 관련 없는 스케줄러 코드는 변경하지 않았다.
- OpenAPI는 YAML 파싱 및 19 operations/로컬 참조 238개 해석을 확인했다. 별도 OpenAPI 전용 validator는 설치되어 있지 않아 실행하지 않았다.
- 최종 독립 리뷰 **APPROVE**. 1차에서 발견한 REV-001을 수정하고 두 서비스·실제 쓰기 테스트·120개 XML 증거를 변경분 재리뷰로 확인했다. 상세 판정은 `reviews/gate-review.md`에 있다.