97 lines
3.3 KiB
Markdown
97 lines
3.3 KiB
Markdown
# 커뮤니티 댓글 직접 답글 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는 이번 기능에서 변경하지 않는다.
|