오디오 콘텐츠 댓글 첫 답글 API Contract

문서 정보

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

계약 변경 여부

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

Endpoint

직접 답글 목록

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

commentId: 답글 영역을 연 원댓글 ID
성공: data={ totalCount, items }
답글 0개도 totalCount=0, items=[]인 정상 성공이다.

댓글 또는 답글 작성

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

첫 답글 request:

{
  "comment": "답글 내용",
  "parentId": 1102,
  "isSecret": false,
  "languageCode": null
}

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

parentId가 있으면 같은 Audio target의 활성 원댓글에 대한 직접 답글이다.
답글 ID를 parentId로 보내는 3단계 작성은 허용하지 않는다.
성공 envelope의 data는 null이다.
성공 후 원댓글 목록과 열린 root의 현재 답글 page를 재조회한다.

오류 응답

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

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

도메인별 message key를 새로 추정하지 않는다.

프론트엔드 연결

역할	기존 구현
target path 선택	`commentCollectionPath()`
답글 조회	`getReplies()`
답글 작성	`createComment()`
request schema	`audioCommentCreateRequestSchema`
성공 후 재조회	`CommentThread.runMutation()`

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

2.8 KiB Raw Blame History