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

## 문서 정보

| 항목 | 내용 |
|---|---|
| 상태 | 기존 계약 재사용 확정 |
| 작성일 | 2026-08-06 |
| 원본 계약 | [프로젝트 OpenAPI](../20260725_AI캐릭터관리자웹/api-contract.openapi.json) |
| 관련 PRD | [prd.md](./prd.md) |
| 관련 계획 | [plan-task.md](./plan-task.md) |

## 계약 변경 여부

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

## 댓글 구조 불변식

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

## Endpoint

### 직접 답글 목록

```http
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을 사용한다.

### 댓글 또는 직접 답글 작성

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

직접 답글 request:

```json
{
  "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는 이번 기능에서 변경하지 않는다.