커뮤니티 댓글 직접 답글 API Contract

문서 정보

항목	내용
상태	기존 계약 재사용 확정
작성일	2026-08-06
원본 계약	프로젝트 OpenAPI
관련 PRD	prd.md
관련 계획	plan-task.md

계약 변경 여부

백엔드 API 변경은 없다. 이 문서는 이번 기능이 소비하는 기존 OpenAPI 범위와 프론트엔드 전송값만 좁게 기록한다. 충돌하면 원본 OpenAPI가 우선한다.

댓글 구조 불변식

parentId=null 또는 생략: 원댓글
parentId=원댓글 ID: 해당 원댓글의 직접 답글
하나의 원댓글 ID를 여러 POST의 parentId로 사용할 수 있으며 각 응답은 별도 직접 답글 row가 된다.
parentId=답글 ID인 3단계 작성은 허용하지 않는다.
parent는 같은 characterId·postId의 활성 원댓글이어야 한다.

Endpoint

직접 답글 목록

GET /api/v2/admin/ai-characters/{characterId}/community-posts/{postId}/comments/{commentId}/replies?page=0&size=20
Authorization: Bearer {jwt-token}
Accept-Language: ko

commentId: 답글 영역을 연 원댓글 ID
성공: data={ totalCount, items }
답글 0개도 totalCount=0, items=[]인 정상 성공이다.
여러 직접 답글은 items의 독립 row로 반환되며 기존 pagination을 사용한다.

댓글 또는 직접 답글 작성

POST /api/v2/admin/ai-characters/{characterId}/community-posts/{postId}/comments
Authorization: Bearer {jwt-token}
Accept-Language: ko
Content-Type: application/json

직접 답글 request:

{
  "comment": "답글 내용",
  "parentId": 2102,
  "isSecret": false
}

field	형식	이번 기능의 값
`comment`	string, required	trim 후 빈 문자열이 아닌 입력값
`parentId`	nullable int64, optional	답글 대상 활성 원댓글 ID
`isSecret`	boolean, optional	`false`

Community request에는 Audio 전용 languageCode를 보내지 않는다.
같은 원댓글에 추가 답글을 쓸 때도 같은 endpoint와 원댓글 parentId를 사용한다.
성공 envelope의 data는 null이다.
성공 후 원댓글 목록과 열린 원댓글의 현재 답글 page를 재조회한다.

오류 응답

원본 OpenAPI의 공통 오류 envelope와 다음 status를 그대로 사용한다.

Status	처리
400	invalid target·parent 또는 binding 오류를 화면 alert로 표시
401	공통 session 만료 처리
403	공통 접근 거부 처리
404	target 또는 root를 찾을 수 없음 표시
405, 406, 415, 500	서버 message를 우선 표시하고 기존 재시도 정책 적용

도메인별 message key와 validation 상한을 새로 추정하지 않는다.

프론트엔드 연결

역할	기존 구현
target path 선택	`commentCollectionPath()`의 `community` branch
답글 조회	`getReplies()`
답글 작성	`createComment()`의 Community overload
request schema	`communityCommentCreateRequestSchema`
답글 상태·pagination	`CommentThread`의 `replies`, `loadReplies()`
성공 후 재조회	`CommentThread.runMutation()`

API, schema, mock handler와 store는 이번 기능에서 변경하지 않는다.

3.3 KiB Raw Blame History