feat(ai-character): 오디오 댓글 첫 답글 작성 지원

docs/20260805_오디오콘텐츠댓글답글/api-contract.md

@@ -0,0 +1,88 @@
+# 오디오 콘텐츠 댓글 첫 답글 API Contract
+
+## 문서 정보
+
+| 항목 | 내용 |
+|---|---|
+| 상태 | 기존 계약 재사용 확정 |
+| 작성일 | 2026-08-05 |
+| 원본 계약 | [프로젝트 OpenAPI](../20260725_AI캐릭터관리자웹/api-contract.openapi.json) |
+| 관련 PRD | [prd.md](./prd.md) |
+| 관련 계획 | [plan-task.md](./plan-task.md) |
+
+## 계약 변경 여부
+
+백엔드 API 변경은 없다. 이 문서는 이번 기능이 소비하는 기존 OpenAPI 범위와
+프론트엔드 전송값만 좁게 기록한다. 충돌하면 원본 OpenAPI가 우선한다.
+
+## Endpoint
+
+### 직접 답글 목록
+
+```http
+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=[]`인 정상 성공이다.
+
+### 댓글 또는 답글 작성
+
+```http
+POST /api/v2/admin/ai-characters/{characterId}/audio-contents/{contentId}/comments
+Authorization: Bearer {jwt-token}
+Accept-Language: ko
+Content-Type: application/json
+```
+
+첫 답글 request:
+
+```json
+{
+  "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는 이번 기능에서 변경하지 않는다.