klaus/sodalive-backend-spring-boot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(ai-character): legacy API 매핑을 보강한다

Browse Source
This commit is contained in:
Klaus
2026-07-21 11:31:36 +09:00
parent 3d409dc108
commit 5b700892c3
1 changed files with 111 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
docs/20260720_AI캐릭터_관리자기능/prd.md
View File

@@ -4511,3 +4511,114 @@ CHANNEL-PROFILE-02 PUT /admin/ai-characters/{characterId}/channel-profile
- 원작 추가 Operation: `ORIGINAL-WORK-01`~`ORIGINAL-WORK-08`
- 기존 stack, 환경별 `VITE_API_BASE_URL`, Jenkins 명령, 인증·세션, noindex, UTC/KST와 feedback 규칙은 변경하지 않는다.
- 27.8 fenced prompt의 변경 전 SHA-256은 `5956ddc152c026937728381d625859bdea65b9a2f16a39b200f0d6b3660a73e1`이며 문서 보강 후에도 같아야 한다.
## 29. PRD-Plan Synchronization and Legacy API Mapping
### 29.1 Synchronization Check
- 이 PRD와 `plan-task.md`는 신규 관리자 Operation 66개를 같은 범위로 추적한다.
- `plan-task.md`의 Task 1.1~11.4는 PRD의 인증, 메뉴, 원작, 캐릭터, 콘텐츠, 댓글, 카테고리, 시리즈, 커뮤니티, FanTalk, 채널 설정, 삭제 cascade, legacy 호환, callback 유지 및 경계 검증을 모두 포함한다.
- 기존 `AUTH-01`, legacy `/admin/chat/**`, 기존 `/audio-content/upload-complete`는 신규 Operation 수에 포함하지 않는다는 점도 두 문서가 일치한다.
- Frontend baseline 58개와 원작 8개 추가로 브라우저용 신규 관리자 Operation 66개가 된다는 설명도 두 문서가 일치한다.
### 29.2 Mapping Rule
- 아래 표는 신규 v2 관리자 API가 이관·대체·참고하는 legacy HTTP API를 추적하기 위한 문서다.
- `없음`은 기존에 같은 목적의 HTTP API가 없거나, 기존 서비스 내부 기능만 있었음을 의미한다.
- `부분 대응`은 legacy API가 데이터 조회나 일부 동작의 근거만 제공하며 신규 v2 계약을 그대로 대체하지 못한다는 의미다.
- 이 표는 구현 의존성 허용 목록이 아니다. v2 신규 비즈니스 로직은 PRD 7.6과 21장의 경계대로 legacy Controller, Service, Repository, Request/Response DTO를 호출하지 않는다.
### 29.3 Authentication, Character, Original Work
| Operation ID | 신규 API | 대응 legacy API | 매핑 판단 |
|---|---|---|---|
| `AUTH-01` | `POST /admin/member/login` | 동일 | 기존 로그인 재사용 |
| `CHAR-01` | `GET /admin/ai-characters` | `GET /admin/chat/character/list`, `GET /admin/chat/character/search` | 목록·검색 통합 |
| `CHAR-02` | `GET /admin/ai-characters/{characterId}` | `GET /admin/chat/character/{characterId}` | 상세 이관 |
| `CHAR-03` | `POST /admin/ai-characters` | `POST /admin/chat/character/register` | 등록 이관, legacy 성공 응답은 유지 |
| `CHAR-04` | `PUT /admin/ai-characters/{characterId}` | `PUT /admin/chat/character/update` | 수정 이관, legacy nullable patch 의미는 adapter에서 보존 |
| `CHAR-05` | `DELETE /admin/ai-characters/{characterId}` | `PUT /admin/chat/character/update` with `isActive=false` | 명시 DELETE 없음, 비활성화 경로를 v2 delete cascade로 수렴 |
| `ORIGINAL-WORK-01` | `GET /admin/ai-characters/original-works` | `GET /admin/chat/original/list`, `GET /admin/chat/original/search` | 목록·검색 통합 |
| `ORIGINAL-WORK-02` | `GET /admin/ai-characters/original-works/{originalWorkId}` | `GET /admin/chat/original/{id}` | 상세 이관 |
| `ORIGINAL-WORK-03` | `POST /admin/ai-characters/original-works` | `POST /admin/chat/original/register` | 등록 이관, legacy 성공 응답은 유지 |
| `ORIGINAL-WORK-04` | `PUT /admin/ai-characters/original-works/{originalWorkId}` | `PUT /admin/chat/original/update` | 수정 이관, legacy nullable patch 의미는 adapter에서 보존 |
| `ORIGINAL-WORK-05` | `DELETE /admin/ai-characters/original-works/{originalWorkId}` | `DELETE /admin/chat/original/{id}` | 삭제 이관, 연결 존재 시 신규 정책 적용 |
| `ORIGINAL-WORK-06` | `GET /admin/ai-characters/original-works/{originalWorkId}/characters` | `GET /admin/chat/original/{id}/characters` | 연결 캐릭터 목록 이관 |
| `ORIGINAL-WORK-07` | `POST /admin/ai-characters/original-works/{originalWorkId}/characters` | `POST /admin/chat/original/{id}/assign-characters` | 배정 이관, 부분 성공 금지 |
| `ORIGINAL-WORK-08` | `DELETE /admin/ai-characters/original-works/{originalWorkId}/characters` | `POST /admin/chat/original/{id}/unassign-characters` | 해제 이관, 신규 API는 DELETE body 사용 |
### 29.4 Content and Content Comment
| Operation ID | 신규 API | 대응 legacy API | 매핑 판단 |
|---|---|---|---|
| `CONTENT-01` | `GET /admin/ai-characters/{characterId}/contents` | `GET /creator-admin/audio-content/list`, `GET /creator-admin/audio-content/search` | 목록·검색과 관리자 projection 재구성 |
| `CONTENT-02` | `GET /admin/ai-characters/{characterId}/contents/{contentId}` | `GET /audio-content/{id}` | 부분 대응, 관리자 상세·Signed URL 계약은 v2에서 새로 정의 |
| `CONTENT-03` | `POST /admin/ai-characters/{characterId}/contents` | `POST /audio-content` | 생성 이관, 기존 callback 계약 유지 |
| `CONTENT-04` | `PUT /admin/ai-characters/{characterId}/contents/{contentId}` | `PUT /creator-admin/audio-content`, `PUT /audio-content` | 부분 대응, 수정 가능 field를 v2에서 제한 |
| `CONTENT-05` | `DELETE /admin/ai-characters/{characterId}/contents/{contentId}` | `DELETE /audio-content/{id}` | 논리 삭제 이관 |
| `CONTENT-06` | `PUT /admin/ai-characters/{characterId}/contents/{contentId}/pin` | `POST /audio-content/pin-to-the-top/{id}`, `PUT /audio-content/unpin-at-the-top/{id}` | 고정·해제 통합 |
| `CONTENT-07` | `GET /admin/ai-characters/metadata/content-themes` | `GET /audio-content/theme`, `GET /audio-content/theme/active` | 기준정보 조회 이관 |
| `CONTENT-COMMENT-01` | `GET /admin/ai-characters/{characterId}/contents/{contentId}/comments` | `GET /audio-content/{id}/comment` | 루트 댓글 목록 이관 |
| `CONTENT-COMMENT-02` | `GET /admin/ai-characters/{characterId}/contents/{contentId}/comments/{commentId}/replies` | `GET /audio-content/comment/{id}` | 답글 목록 이관 |
| `CONTENT-COMMENT-03` | `POST /admin/ai-characters/{characterId}/contents/{contentId}/comments` | `POST /audio-content/comment` | 작성 이관, writer는 AI creator로 고정 |
| `CONTENT-COMMENT-04` | `PUT /admin/ai-characters/{characterId}/contents/{contentId}/comments/{commentId}` | `PUT /audio-content/comment` | 수정 이관, AI 작성자만 허용 |
| `CONTENT-COMMENT-05` | `DELETE /admin/ai-characters/{characterId}/contents/{contentId}/comments/{commentId}` | `PUT /audio-content/comment` | 명시 DELETE 없음, 논리 삭제 동작만 v2로 분리 |
### 29.5 Category and Series
| Operation ID | 신규 API | 대응 legacy API | 매핑 판단 |
|---|---|---|---|
| `CATEGORY-01` | `GET /admin/ai-characters/{characterId}/content-categories` | `GET /category` | 목록 이관 |
| `CATEGORY-02` | `POST /admin/ai-characters/{characterId}/content-categories` | `POST /category` | 생성 이관 |
| `CATEGORY-03` | `PUT /admin/ai-characters/{characterId}/content-categories/{categoryId}` | `PUT /category` | 수정 이관 |
| `CATEGORY-04` | `DELETE /admin/ai-characters/{characterId}/content-categories/{categoryId}` | `DELETE /category/{id}` | 논리 삭제 이관 |
| `CATEGORY-05` | `PUT /admin/ai-characters/{characterId}/content-categories/orders` | `PUT /category/orders` | 순서 변경 이관, 소유자 전체 집합 검증 추가 |
| `CATEGORY-06` | `GET /admin/ai-characters/{characterId}/content-categories/{categoryId}/contents` | `GET /creator-admin/content-category` | 포함 콘텐츠 목록 이관 |
| `CATEGORY-07` | `GET /admin/ai-characters/{characterId}/content-categories/{categoryId}/available-contents` | `GET /creator-admin/content-category/search` | 추가 가능 콘텐츠 검색 이관 |
| `CATEGORY-08` | `POST /admin/ai-characters/{characterId}/content-categories/{categoryId}/contents` | 없음 | 카테고리 생성·수정 내부 구성 기능을 명시 API로 분리 |
| `CATEGORY-09` | `DELETE /admin/ai-characters/{characterId}/content-categories/{categoryId}/contents/{contentId}` | 없음 | 카테고리-콘텐츠 연결 해제를 명시 API로 신설 |
| `SERIES-01` | `GET /admin/ai-characters/{characterId}/series` | `GET /creator-admin/audio-content/series` | 목록 이관 |
| `SERIES-02` | `GET /admin/ai-characters/{characterId}/series/{seriesId}` | `GET /creator-admin/audio-content/series/{id}` | 상세 이관 |
| `SERIES-03` | `POST /admin/ai-characters/{characterId}/series` | `POST /creator-admin/audio-content/series` | 등록 이관 |
| `SERIES-04` | `PUT /admin/ai-characters/{characterId}/series/{seriesId}` | `PUT /creator-admin/audio-content/series` | 수정 이관 |
| `SERIES-05` | `DELETE /admin/ai-characters/{characterId}/series/{seriesId}` | 없음 | 명시 삭제 API 신설 |
| `SERIES-06` | `GET /admin/ai-characters/{characterId}/series/{seriesId}/contents` | `GET /creator-admin/audio-content/series/{id}/content` | 포함 콘텐츠 목록 이관 |
| `SERIES-07` | `GET /admin/ai-characters/{characterId}/series/{seriesId}/available-contents` | `GET /creator-admin/audio-content/series/content/search` | 추가 가능 콘텐츠 검색 이관 |
| `SERIES-08` | `POST /admin/ai-characters/{characterId}/series/{seriesId}/contents` | `POST /creator-admin/audio-content/series/add/content` | 콘텐츠 추가 이관 |
| `SERIES-09` | `DELETE /admin/ai-characters/{characterId}/series/{seriesId}/contents/{contentId}` | `PUT /creator-admin/audio-content/series/remove/content` | 신규 API는 DELETE로 관계 해제 표현 |
| `SERIES-10` | `PUT /admin/ai-characters/{characterId}/series/orders` | `PUT /creator-admin/audio-content/series/orders` | 순서 변경 이관, 소유자 전체 집합 검증 추가 |
| `SERIES-11` | `GET /admin/ai-characters/metadata/series-genres` | `GET /creator-admin/audio-content/series/genre` | 기준정보 조회 이관 |
### 29.6 Community, FanTalk, Channel Settings
| Operation ID | 신규 API | 대응 legacy API | 매핑 판단 |
|---|---|---|---|
| `COMMUNITY-POST-01` | `GET /admin/ai-characters/{characterId}/community-posts` | `GET /creator-community` | 목록 이관, 관리자 projection 사용 |
| `COMMUNITY-POST-02` | `GET /admin/ai-characters/{characterId}/community-posts/{postId}` | `GET /creator-community/{id}` | 상세 이관 |
| `COMMUNITY-POST-03` | `POST /admin/ai-characters/{characterId}/community-posts` | `POST /creator-community` | 등록 이관 |
| `COMMUNITY-POST-04` | `PUT /admin/ai-characters/{characterId}/community-posts/{postId}` | `PUT /creator-community` | 수정 이관 |
| `COMMUNITY-POST-05` | `DELETE /admin/ai-characters/{characterId}/community-posts/{postId}` | 없음 | 명시 삭제 API 신설 |
| `COMMUNITY-POST-06` | `PUT /admin/ai-characters/{characterId}/community-posts/{postId}/fixed` | `PUT /creator-community/fixed` | 고정 상태 변경 이관 |
| `COMMUNITY-COMMENT-01` | `GET /admin/ai-characters/{characterId}/community-posts/{postId}/comments` | `GET /creator-community/{id}/comment` | 루트 댓글 목록 이관 |
| `COMMUNITY-COMMENT-02` | `GET /admin/ai-characters/{characterId}/community-posts/{postId}/comments/{commentId}/replies` | `GET /creator-community/comment/{id}` | 답글 목록 이관 |
| `COMMUNITY-COMMENT-03` | `POST /admin/ai-characters/{characterId}/community-posts/{postId}/comments` | `POST /creator-community/comment` | 작성 이관, writer는 AI creator로 고정 |
| `COMMUNITY-COMMENT-04` | `PUT /admin/ai-characters/{characterId}/community-posts/{postId}/comments/{commentId}` | `PUT /creator-community/comment` | 수정 이관, AI 작성자만 허용 |
| `COMMUNITY-COMMENT-05` | `DELETE /admin/ai-characters/{characterId}/community-posts/{postId}/comments/{commentId}` | `PUT /creator-community/comment` | 명시 DELETE 없음, 논리 삭제 동작만 v2로 분리 |
| `FAN-TALK-01` | `GET /admin/ai-characters/{characterId}/fan-talks` | `GET /api/v2/creator-channels/{creatorId}/fan-talks`, `GET /explorer/profile/{id}/cheers` | 기존 v2 query와 legacy FanTalk 조회를 관리자 projection으로 확장 |
| `FAN-TALK-02` | `POST /admin/ai-characters/{characterId}/fan-talks/{fanTalkId}/replies` | `POST /explorer/profile/cheers` | 부분 대응, AI 답글 생성 정책을 v2에서 분리 |
| `FAN-TALK-03` | `PUT /admin/ai-characters/{characterId}/fan-talks/{fanTalkId}/replies/{replyId}` | `PUT /explorer/profile/cheers` | 부분 대응, AI 답글 수정만 허용 |
| `FAN-TALK-04` | `DELETE /admin/ai-characters/{characterId}/fan-talks/{fanTalkId}/replies/{replyId}` | `PUT /explorer/profile/cheers` | 명시 DELETE 없음, AI 답글 논리 삭제를 v2로 분리 |
| `FAN-TALK-05` | `DELETE /admin/ai-characters/{characterId}/fan-talks/{fanTalkId}` | `PUT /explorer/profile/cheers` | 명시 DELETE 없음, 루트 moderation을 v2로 분리 |
| `NOTICE-01` | `GET /admin/ai-characters/{characterId}/channel-notice` | `GET /explorer/profile/{id}/detail` | 부분 대응, 공지 전용 조회 API 신설 |
| `NOTICE-02` | `PUT /admin/ai-characters/{characterId}/channel-notice` | `POST /explorer/profile/notice` | 공지 저장 이관, 신규 API는 PUT upsert |
| `CREATOR-TAG-01` | `GET /admin/ai-characters/metadata/creator-tags` | `GET /member/tag` | 기준정보 조회 이관 |
| `CHANNEL-PROFILE-01` | `GET /admin/ai-characters/{characterId}/channel-profile` | `GET /member/info`, `GET /explorer/profile/{id}/detail` | 부분 대응, 관리자 설정 projection 신설 |
| `CHANNEL-PROFILE-02` | `PUT /admin/ai-characters/{characterId}/channel-profile` | `PUT /member` | 채널 SNS·태그·후원 랭킹 설정 이관 |
### 29.7 Existing API Kept Outside New Operation Count
| Existing API | 신규 Operation 포함 여부 | 처리 |
|---|---:|---|
| `GET /menu` | No | v2 AI 캐릭터 관리자는 호출하지 않음, 메뉴는 클라이언트 정적 설정 |
| `PUT /audio-content/upload-complete` | No | 기존 AWS worker callback 계약 유지, v2 콘텐츠도 같은 row·S3 metadata 계약으로 처리 |
| `GET /api/chat/original/**` | No | 일반 사용자용 원작 조회 계약 유지 |