klaus/voiceon-character-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(ai-character): 리소스 관리 문서 정리

Browse Source
This commit is contained in:
Yu Sung
2026-08-01 01:30:10 +09:00
parent 00e3221035
commit 55ba0df77a
31 changed files with 10021 additions and 390 deletions
Download Patch File Download Diff File Expand all files Collapse all files

186
docs/20260725_AI캐릭터관리자웹/prd.md
View File

@@ -6,7 +6,7 @@
|---|---|
| 문서 상태 | OpenAPI 반영 구현 기준 |
| 작성일 | 2026-07-25 |
| 최종 수정일 | 2026-07-28 |
| 최종 수정일 | 2026-07-30 |
| 대상 제품 | AI 캐릭터 전용 독립 관리자 웹 |
| 구현 대상 | React + TypeScript + Vite SPA |
| UI 기반 | Tailwind CSS + shadcn/ui |
@@ -38,7 +38,7 @@ AI 캐릭터를 생성하고, AI 캐릭터가 사람 크리에이터처럼 콘
관리자는 ADMIN 권한으로 로그인한 뒤 AI 캐릭터를 선택한다. 이후의 모든 생성·수정·비활성화 작업은 선택한 `characterId`와 연결된 AI 캐릭터 크리에이터의 활동으로 저장된다. 관리자가 AI 캐릭터 계정으로 직접 로그인하거나 토큰을 교환하는 방식은 사용하지 않는다.
이번 문서는 요구사항과 구현 계획만 정의한다. 애플리케이션 코드는 이번 단계에서 수정하지 않는다.
이번 문서는 요구사항, 구현 계획, 완료된 후속 계약 반영 상태를 정의한다.
## 2. Problem Statement
@@ -59,7 +59,7 @@ AI 캐릭터를 생성하고, AI 캐릭터가 사람 크리에이터처럼 콘
- AI 캐릭터 목록 검색, 상세 조회, 생성, 수정, 비활성화를 제공한다.
- 선택한 캐릭터 문맥에서 오디오 콘텐츠, 시리즈, 커뮤니티 게시글을 관리한다.
- 선택한 캐릭터로 FanTalk에 한 번 답변할 수 있게 한다. 기존 답변 수정은 OpenAPI에 수정 endpoint가 추가된 뒤 활성화한다.
- 선택한 캐릭터로 FanTalk에 한 번 답변하고 기존 답변을 수정할 수 있게 한다.
- 오디오 콘텐츠와 커뮤니티 첨부 오디오를 관리자 화면에서 재생할 수 있게 한다.
- 오디오 콘텐츠와 커뮤니티 게시글의 댓글·답글을 캐릭터 명의로 관리한다.
- 비활성 리소스와 권한 오류를 안전하게 처리하고 의도하지 않은 변경을 방지한다.
@@ -88,6 +88,7 @@ AI 캐릭터를 생성하고, AI 캐릭터가 사람 크리에이터처럼 콘
- 정식 WCAG 2.2 AA 인증 또는 외부 접근성 감사
- 백엔드가 담당할 creator 생성·프로필 동기화의 조건부 정책 변경
- 비활성 ID에 대한 상세 GET 반환 여부와 오류 status 등 백엔드 조회 정책 결정
- 감사 로그 조회 UI
- 실제 API의 404를 감지해 mock 응답으로 자동 전환하는 production fallback
## 5. Target Users
@@ -112,7 +113,7 @@ AI 캐릭터를 생성하고, AI 캐릭터가 사람 크리에이터처럼 콘
3. 캐릭터 워크스페이스의 기본 정보, 오디오, 시리즈, 커뮤니티, FanTalk 탭을 이동한다.
4. 활성 캐릭터라면 데스크톱·태블릿에서 리소스를 생성·수정·비활성화한다.
5. 오디오 플레이어로 캐릭터가 올린 오디오를 검수한다.
6. FanTalk 목록 item에서 답변이 없을 때 한 번 답변한다. 기존 답변 수정은 수정 계약이 제공된 뒤 추가한다.
6. FanTalk 목록 item에서 답변이 없을 때 한 번 답변하고, 답변이 있으면 기존 답변을 수정한다.
7. 오디오 또는 커뮤니티 댓글에 캐릭터 명의로 댓글·답글을 작성하거나 운영 정책에 따라 삭제한다.
8. 모바일에서는 리소스를 조회하고 오디오를 재생하며 댓글과 FanTalk 답변을 관리한다.
9. JWT가 만료되거나 폐기되면 인증 정보를 지우고 로그인 화면으로 이동한다.
@@ -193,9 +194,9 @@ AI 캐릭터를 생성하고, AI 캐릭터가 사람 크리에이터처럼 콘
| CHAR-009 | 확정 | 캐릭터 이름·설명·이미지 변경 시 creator의 nickname·introduce·profile image 동기화는 현재 백엔드가 수행한다. |
| CHAR-010 | 확정 | creator 상황에 따른 조건부 생성·동기화는 다음 백엔드 범위이며 현재 UI 범위가 아니다. |
| CHAR-011 | 제외 | 현 OpenAPI의 Character 목록·상세 응답에는 `creatorMemberId`, `creatorNickname`이 없다. 계약에 추가되기 전에는 creator 정보 UI와 DTO를 만들지 않는다. |
| CHAR-012 | 외부 의존 | OpenAPI는 `searchTerm`을 생략하면 활성 목록을 반환한다고 명시하지만, `searchTerm` 지정 시에는 “레거시 검색”만 명시해 active-only 여부가 불명확하다. 검색 결과 보장이 추가되기 전에도 client 활성 filter는 만들지 않고 서버 반환값을 표시한다. |
| CHAR-013 | 외부 의존 | `originalWorkId`는 생성·수정 request에서 optional nullable이므로 미선택 시 key 생략과 `null`이 모두 계약상 가능하다. 원작 검색 선택기에 필요한 lookup API는 OpenAPI에 없으므로 제공 전에는 원작 선택 network integration을 구현하지 않는다. |
| CHAR-014 | 확정 | 캐릭터 soft delete 성공 시 캐릭터 목록으로 이동해 재조회하고 성공 알림을 표시한다. 현재 상세 화면에 머물지 않는다. 비활성 항목 제외는 active-only 계약 제공 후 검증한다. |
| CHAR-012 | 확정 | 이름 검색 여부와 관계없이 캐릭터 목록 API는 `isActive=true`인 항목만 반환한다. 프론트엔드는 활성 상태 query나 client-side filter를 추가하지 않고 서버 반환값을 사용한다. |
| CHAR-013 | 확정 | 원작 검색은 필수 `searchTerm` query를 사용하는 `GET /api/v2/admin/ai-characters/original-works/search`를 호출하고 `data[]`의 `id`, `title`, `contentType`, `category`, `isAdult`, `description`, `originalWork`, `originalLink`, `writer`, `studio`, `originalLinks`, `tags`, `imageUrl`을 사용한다. `originalWorkId` 미선택은 serializer의 canonical 생략으로 고정한다. |
| CHAR-014 | 확정 | 캐릭터 soft delete 성공 시 캐릭터 목록으로 이동해 재조회하고 성공 알림을 표시한다. 현재 상세 화면에 머물지 않으며 서버의 active-only 목록에서 비활성 항목이 제외돼야 한다. |
| CHAR-015 | 확정 | 목록은 `searchTerm`, `page`, `size`를 사용하고 `data.totalCount`, `data.content[]`를 소비한다. 목록 ID field는 `id`다. |
| CHAR-016 | 확정 | 생성·수정 성공은 `data=null`이므로 생성 후 목록을 무효화해 이동하고, 수정 후 기존 `characterId` 상세와 목록을 다시 조회한다. 생성 응답에서 새 ID나 상세 DTO를 추정하지 않는다. |
| CHAR-017 | 확정 | 상세의 `characterUUID`는 OpenAPI에 존재하는 읽기 전용 값이며, 제거된 `externalCharacterId`와 다른 field다. |
@@ -204,10 +205,10 @@ AI 캐릭터를 생성하고, AI 캐릭터가 사람 크리에이터처럼 콘
#### 캐릭터 생성·수정 폼
- 이름, system prompt와 설명은 명시적인 레이블과 필드 오류 영역을 가진다.
- OpenAPI의 optional scalar(`age`, `gender`, `mbti`, `speechPattern`, `speechStyle`, `appearance`, `region`, `originalTitle`, `originalLink`, `characterType`)와 배열(`tags`, `hobbies`, `values`, `goals`, `relationships`, `personalities`, `backgrounds`, `memories`)을 생성 form에서 편집할 수 있게 한다. `originalWorkId`는 lookup 계약 제공 후 선택기로 편집하고, 수정 request에 없는 `region`은 수정 화면에서 읽기 전용이다.
- OpenAPI의 optional scalar(`age`, `gender`, `mbti`, `speechPattern`, `speechStyle`, `appearance`, `region`, `originalTitle`, `originalLink`, `characterType`)와 배열(`tags`, `hobbies`, `values`, `goals`, `relationships`, `personalities`, `backgrounds`, `memories`)을 생성 form에서 편집할 수 있게 한다. `originalWorkId`는 원작 검색 선택기로 편집하고, 수정 request에 없는 `region`은 수정 화면에서 읽기 전용이다.
- 이미지는 미리보기, 교체, 새로 선택한 파일의 선택 취소를 제공한다. 기존 이미지 자체를 제거하는 기능은 contract가 없어 현재 범위가 아니다.
- 생성 이미지는 필수다. 수정 이미지는 선택이며 미전송하면 기존 이미지를 유지한다.
- 원작 lookup 계약이 제공되면 이름 검색형 Combobox로 선택한다. 미선택은 허용하고 serializer는 key 생략 또는 `null` 중 한 가지 canonical form을 contract test로 고정한다.
- 원작은 제목·콘텐츠 타입·카테고리 부분 검색을 지원하는 Combobox로 선택한다. 미선택은 허용하고 serializer는 `originalWorkId` key 생략을 canonical form으로 사용한다.
- 비활성화는 폼 Switch가 아니라 영향 범위를 설명하는 확인 Dialog로 실행한다.
- 저장 중 중복 제출을 막고 성공 후 상세 데이터를 다시 동기화한다.
@@ -217,15 +218,15 @@ AI 캐릭터를 생성하고, AI 캐릭터가 사람 크리에이터처럼 콘
|---|---|---|
| AUDIO-001 | 확정 | 선택한 캐릭터의 오디오 목록·제목 검색·상세·생성·수정·비활성화를 제공한다. |
| AUDIO-002 | 제외 | 현 OpenAPI 목록·상세에는 `OPEN`, `SCHEDULED` status field가 없고 목록 status query도 없다. 상태 badge와 server status filter는 계약에 추가되기 전에는 제공하지 않는다. |
| AUDIO-003 | 확정 | 공개 예약은 생성 request의 nullable `releaseDate`와 `timezone`으로 표현한다. 목록·상세에서는 OpenAPI가 반환한 `releaseDate` 문자열을 그대로 표시하고 별도 status enum을 만들지 않는다. |
| AUDIO-003 | 확정 | 공개 예약은 생성 request의 nullable `releaseDate`로 표현한다. 예약 값은 클라이언트가 UTC로 변환한 ISO-8601 `Z` 문자열이며 `timezone` field는 보내지 않는다. 목록·상세의 `releaseDate`도 UTC `Z` 문자열 또는 `null`로 소비하고 별도 status enum을 만들지 않는다. |
| AUDIO-004 | 확정 | 프론트엔드는 `releaseDate`로 `OPEN`·`SCHEDULED` 같은 API status를 재계산하거나 DTO에 추가하지 않는다. |
| AUDIO-005 | 제외 | 현 OpenAPI에 status filter가 없으므로 status query를 보내거나 현재 page를 client에서 status별로 거르지 않는다. |
| AUDIO-006 | 확정 | 생성 요청에는 `isActive`를 보내지 않는다. |
| AUDIO-007 | 확정 | 일반 수정 요청에서는 `isActive`를 생략하고 soft delete 요청에만 `isActive=false`를 보낸다. `isActive=true`는 전송하지 않는다. |
| AUDIO-008 | 확정 | 공개 방식은 “지금 즉시 공개”와 “예약 공개” 두 선택 버튼으로 제공한다. |
| AUDIO-009 | 확정 | 생성 시 즉시 공개가 기본값이며 `releaseDate=null`과 `timezone="Asia/Seoul"`을 보낸다. 예약 날짜 입력은 비활성화하고 기존 값을 지운다. |
| AUDIO-009 | 확정 | 생성 시 즉시 공개가 기본값이며 `releaseDate=null`을 보내고 `timezone`은 보내지 않는다. 예약 날짜 입력은 비활성화하고 기존 값을 지운다. |
| AUDIO-010 | 확정 | 예약 공개를 선택한 경우에만 날짜·시간을 입력할 수 있고 미래 시각이 필수다. |
| AUDIO-011 | 확정 | 예약 시각은 Asia/Seoul로 입력·표시하고 생성 API에는 `yyyy-MM-dd HH:mm` 형식의 `releaseDate`와 `timezone="Asia/Seoul"`을 보낸다. UTC `Z` 값으로 변환하지 않는다. |
| AUDIO-011 | 확정 | 예약 시각은 Asia/Seoul로 입력·표시하되, 생성 API에는 해당 시각을 클라이언트에서 UTC로 변환한 ISO-8601 `Z` 형식의 `releaseDate`를 보낸다. 예를 들어 `2026-07-29 18:00` Asia/Seoul은 `2026-07-29T09:00:00Z`로 전송한다. |
| AUDIO-012 | 확정 | 생성 multipart의 `contentFile`, `coverImage`, `request`는 필수다. 수정은 `coverImage`와 `request`만 허용하므로 오디오 원본 파일 교체 UI를 제공하지 않는다. |
| AUDIO-013 | 확정 | 오디오 확장자는 `.mp3`, `.aac`, `.m4a`를 허용한다. WAV는 허용하지 않는다. |
| AUDIO-014 | 확정 | canonical MIME은 `audio/mpeg`, `audio/aac`, `audio/mp4`다. |
@@ -233,23 +234,23 @@ AI 캐릭터를 생성하고, AI 캐릭터가 사람 크리에이터처럼 콘
| AUDIO-016 | 확정 | 확장자와 MIME만 신뢰하지 않고 실제 컨테이너·코덱 검증은 백엔드가 수행해야 한다. |
| AUDIO-017 | 확정 | 업로드 진행률, 취소, 전체 재시도를 제공하고 resumable upload는 제공하지 않는다. |
| AUDIO-018 | 확정 | 업로드 실패 후 입력한 폼 값과 선택 가능한 파일 상태를 최대한 유지한다. |
| AUDIO-019 | 확정 | 가격 단위는 “캔”이고 0 이상의 정수다. 0은 무료이며 UI는 예: `1,000캔`으로 표시한다. |
| AUDIO-019 | 확정 | 가격 단위는 “캔”이고 `0..99999` 정수다. 0은 무료이며 UI는 예: `1,000캔`으로 표시한다. |
| AUDIO-020 | 확정 | Audio 생성·수정 request에는 `seriesIds`가 없다. 시리즈 연결은 Audio form이 아니라 Series 콘텐츠 연결 endpoint와 Phase 5 UI에서 관리한다. |
| AUDIO-021 | 확정 | 목록과 상세에서 오디오를 재생할 수 있다. |
| AUDIO-022 | 외부 의존 | 오디오 목록 request에는 활성 상태 query와 status query가 없고 응답에도 `isActive`가 없다. active-only 반환 보장은 OpenAPI에 명시돼야 하며 client-side 활성 filter는 만들지 않는다. |
| AUDIO-022 | 확정 | 오디오 목록 API는 `isActive=true`인 항목만 반환한다. request에는 활성 상태 query를 추가하지 않고 응답에도 client-side 활성 filter를 적용하지 않는다. status query는 여전히 제공하지 않는다. |
| AUDIO-023 | 확정 | 최대 크기는 decimal 1,024MB인 `1,024,000,000 bytes` 이하이며 `1,024,000,001 bytes`부터 거부한다. 오디오 콘텐츠와 커뮤니티 첨부 audio에 동일하게 적용한다. |
| AUDIO-024 | 확정 | `audio/x-m4a`는 `.m4a` 파일에 한해 호환 MIME으로 허용한다. 실제 MP4/M4A 컨테이너·코덱 검증을 통과해야 하며 다른 확장자와의 조합은 거부한다. |
| AUDIO-025 | 확정 | 오디오 soft delete 성공 시 선택 캐릭터의 오디오 목록으로 이동해 재조회하고 성공 알림을 표시한다. 현재 상세 화면에 머물지 않는다. 비활성 항목 제외는 active-only 계약 제공 후 검증한다. |
| AUDIO-025 | 확정 | 오디오 soft delete 성공 시 선택 캐릭터의 오디오 목록으로 이동해 재조회하고 성공 알림을 표시한다. 현재 상세 화면에 머물지 않으며 서버의 active-only 목록에서 비활성 항목이 제외돼야 한다. |
| AUDIO-026 | 확정 | 재생 오류를 signed URL 만료로 구분하거나 추정하지 않는다. media error만으로 상세·목록을 자동 재조회하거나 자동 재생하지 않고, 일반 오류와 수동 재시도·페이지 새로고침 안내를 제공한다. |
| AUDIO-027 | 확정 | 오디오 콘텐츠 생성 시 유효한 `themeId`가 필수다. OpenAPI의 기본값 `0`은 binding 기본값일 뿐 domain에서 유효하지 않으므로 프론트엔드는 테마 선택을 강제한다. |
| AUDIO-028 | 확정 | 오디오 콘텐츠 테마 목록 조회는 query/body 없이 호출하며 응답 `data[]`의 `id`, `theme`, `image`를 사용한다. |
| AUDIO-029 | 확정 | 목록 검색 query는 `search_word`이며 검색어가 2자 이상일 때만 보낸다. 목록 응답은 `data.totalCount`, `data.items[]`를 사용한다. |
| AUDIO-030 | 확정 | 상세 GET은 필수 `timezone=Asia/Seoul` query를 보낸다. |
| AUDIO-030 | 확정 | 상세 GET에는 `timezone` query를 보내지 않는다. 응답의 nullable `releaseDate`는 ISO-8601 UTC `Z` 값으로 소비하고 화면 표시 시 Asia/Seoul로 변환한다. |
| AUDIO-031 | 확정 | 생성 성공은 `data.contentId`를 사용해 상세로 이동할 수 있다. 수정·soft delete 성공은 `data=null`이므로 기존 ID 기준 cache를 무효화한다. |
| AUDIO-032 | 확정 | 생성 `request`는 필수 `title`, `detail`, `tags`, `price`와 OpenAPI의 optional field만 보낸다. 수정은 `title`, `detail`, `tags`, `price`, `isAdult`, `isActive`, `isPointAvailable`, `isCommentAvailable`만 변경할 수 있다. |
| AUDIO-033 | 확정 | 생성 form은 OpenAPI의 `purchaseOption`, `limited`, `isAdult`, `isGeneratePreview`, `isOnlyRental`, `isPointAvailable`, `isCommentAvailable`, `isFullDetailVisible`, `previewStartTime`, `previewEndTime`, `languageCode`를 계약 enum·type과 default에 맞춰 제공한다. 계약에 없는 추가 상관관계 validation은 만들지 않는다. |
현 수정 계약에는 `releaseDate`, `timezone`, `themeId`, `contentFile`이 없다. 따라서 공개 예약·테마·오디오 원본 변경은 생성 화면에서만 제공하고 수정 화면에서는 읽기 전용으로 표시한다.
현 수정 계약에는 `releaseDate`, `themeId`, `contentFile`이 없다. 따라서 공개 예약·테마·오디오 원본 변경은 생성 화면에서만 제공하고 수정 화면에서는 읽기 전용으로 표시한다.
#### 관리자 오디오 플레이어
@@ -271,18 +272,18 @@ AI 캐릭터를 생성하고, AI 캐릭터가 사람 크리에이터처럼 콘
| SERIES-004 | 확정 | 수정 시 state를 선택할 수 있으며 선택하지 않으면 필드를 생략해 이전 상태를 유지한다. |
| SERIES-005 | 확정 | 연재 요일 enum은 `SUN`, `MON`, `TUE`, `WED`, `THU`, `FRI`, `SAT`, `RANDOM`이다. |
| SERIES-006 | 확정 | `RANDOM`은 다른 요일과 함께 보낼 수 없다. 값은 RANDOM 단독 또는 하나 이상의 실제 요일 목록이어야 한다. |
| SERIES-007 | 외부 의존 | 생성 시 유효한 `genreId`가 필요하고 OpenAPI 기본값 `0`은 domain에서 유효하지 않다. 장르 이름 검색 API는 OpenAPI에 없으므로 제공 전에는 장르 선택 network integration과 Series 생성을 완료할 수 없다. |
| SERIES-007 | 확정 | 생성 시 유효한 `genreId`가 필요하고 OpenAPI 기본값 `0`은 domain에서 유효하지 않다. 장르 선택지는 query/body 없는 `GET /api/v2/admin/ai-characters/series-genres`의 `data[]`에서 `id`, `genre`, `isAdult`를 사용한다. |
| SERIES-008 | 확정 | `data.totalCount`, `data.items[]`를 page별로 읽어 서버가 반환한 시리즈 전체를 별도 순서 변경 모드에 표시하고 최종 순서의 모든 ID를 `{ "ids": [...] }`로 전송한다. active-only 여부는 `SERIES-012` 계약 제공 후 검증한다. |
| SERIES-009 | 확정 | drag-and-drop 외에 키보드와 위/아래 버튼으로 순서를 바꿀 수 있어야 한다. |
| SERIES-010 | 확정 | 일반 수정 요청에서는 `isActive`를 생략하고 soft delete 요청에만 `isActive=false`를 보낸다. `isActive=true`, 복원과 hard delete는 제공하지 않는다. |
| SERIES-011 | 외부 의존 | 장르 이름 검색 endpoint·DTO는 백엔드가 제공해야 한다. 제공 전에는 장르 선택 network integration을 구현하지 않는다. 생성 초기 state의 정확한 기본값은 프론트엔드 의존사항이 아니다. |
| SERIES-012 | 외부 의존 | 시리즈 목록 request에는 활성 상태 query가 없다. active-only 반환 보장은 OpenAPI에 명시돼야 하며 list item의 `isActive`를 client에서 숨기는 방식으로 대체하지 않는다. |
| SERIES-013 | 확정 | 시리즈 soft delete 성공 시 선택 캐릭터의 시리즈 목록으로 이동해 재조회하고 성공 알림을 표시한다. 현재 상세 화면에 머물지 않는다. 비활성 항목 제외는 active-only 계약 제공 후 검증한다. |
| SERIES-011 | 확정 | 장르 목록 endpoint는 검색·페이지 query 없이 활성 장르 전체를 반환한다. 생성 초기 state의 정확한 기본값은 프론트엔드 의존사항이 아니다. |
| SERIES-012 | 확정 | 시리즈 목록 API는 `isActive=true`인 항목만 반환한다. 프론트엔드는 활성 상태 query나 client-side filter를 추가하지 않는다. |
| SERIES-013 | 확정 | 시리즈 soft delete 성공 시 선택 캐릭터의 시리즈 목록으로 이동해 재조회하고 성공 알림을 표시한다. 현재 상세 화면에 머물지 않으며 서버의 active-only 목록에서 비활성 항목이 제외돼야 한다. |
| SERIES-014 | 확정 | 생성 multipart의 `image`와 `request`는 필수다. 생성 request는 `keyword` 단일 문자열을 사용하며 `keywords` 배열을 보내지 않는다. |
| SERIES-015 | 확정 | 목록은 enum `publishedDaysOfWeek`, `genreId`, enum `state`를 사용하지만 상세는 표시용 문자열 `publishedDaysOfWeek`, `genre`, `keywords`, 한국어 `state`를 사용한다. 상세 표시 문자열을 update enum으로 재사용하지 않는다. |
| SERIES-015 | 확정 | 목록과 상세는 동일한 `SeriesListItem` schema를 사용하고 `genreId`, enum 배열 `publishedDaysOfWeek`, enum `state`를 반환한다. 화면 label은 클라이언트에서 표시용으로 변환하되 원본 enum과 ID를 수정 payload에 사용한다. |
| SERIES-016 | 확정 | 연결 후보는 `GET .../contents/search?search_word=...`, 연결은 `{ "contentIdList": [...] }`, 해제는 body 없는 DELETE를 사용한다. |
| SERIES-017 | 외부 의존 | 상세 응답에는 update에 필요한 `genreId`, enum `publishedDaysOfWeek`, enum `state`가 없다. 직접 링크에서도 안전하게 수정 form을 초기화할 edit DTO 또는 별도 mapping 계약이 제공되기 전에는 상세 표시 문자열을 역변환하지 않고 수정 network integration을 완료하지 않는다. |
| SERIES-018 | 확정 | 생성 request의 `keyword`는 수정 request에 없다. 수정 화면에서 상세의 `keywords`를 읽기 전용으로 표시하고 update payload에 보내지 않는다. |
| SERIES-017 | 확정 | 시리즈 상세 응답은 목록 item과 동일한 수정용 원본값 `genreId`, enum `publishedDaysOfWeek`, enum `state`를 제공하므로 별도 edit DTO가 필요 없다. 수정 화면은 상세 응답으로 기존 선택값을 초기화하고, 장르 API는 option 목록 표시용으로 호출한다. |
| SERIES-018 | 확정 | 생성 request의 `keyword`는 수정 request와 상세 응답에 없다. 수정 화면에서 keyword 편집·표시를 추가하거나 update payload에 보내지 않는다. |
#### 시리즈 콘텐츠 연결
@@ -302,12 +303,12 @@ AI 캐릭터를 생성하고, AI 캐릭터가 사람 크리에이터처럼 콘
| COMMUNITY-004 | 확정 | 첨부 오디오가 있으면 목록 행/카드와 게시글 Sheet에서 재생할 수 있다. |
| COMMUNITY-005 | 확정 | 일반 수정 요청에서는 `isActive`를 생략하고 soft delete 요청에만 `isActive=false`를 보낸다. `isActive=true`는 전송하지 않는다. |
| COMMUNITY-006 | 확정 | soft delete request에는 `isActive=false`와 `isFixed=false`를 함께 보낸다. 현 목록 응답에는 `fixedAtUtc`가 없으므로 해당 field를 DTO·UI에 만들지 않는다. |
| COMMUNITY-007 | 확정 | 가격은 오디오와 동일하게 0 이상의 정수 “캔” 단위를 사용한다. |
| COMMUNITY-008 | 외부 의존 | 커뮤니티 목록 request에는 활성 상태 query가 없고 item에도 `isActive`가 없다. active-only 반환 보장은 OpenAPI에 명시돼야 하며 client-side filter는 만들지 않는다. |
| COMMUNITY-007 | 확정 | 가격은 오디오와 동일하게 `0..99999` 정수 “캔” 단위를 사용한다. |
| COMMUNITY-008 | 확정 | 커뮤니티 목록 API는 `isActive=true`인 게시글만 반환한다. request에는 활성 상태 query를 추가하지 않고 item에도 client-side 활성 filter를 적용하지 않는다. |
| COMMUNITY-009 | 확정 | 커뮤니티 전용 상세 GET과 상세·수정 직접 route를 추가하지 않는다. 목록 응답으로 행/카드의 Sheet를 열어 조회·수정·고정·비활성화·댓글 진입을 제공한다. |
| COMMUNITY-010 | 확정 | 커뮤니티 게시글 soft delete 성공 시 열린 Sheet를 닫고 목록을 무효화·재조회하며 성공 알림을 표시한다. 해당 항목 제외는 active-only 계약 제공 후 검증한다. |
| COMMUNITY-010 | 확정 | 커뮤니티 게시글 soft delete 성공 시 열린 Sheet를 닫고 목록을 무효화·재조회하며 성공 알림을 표시한다. 서버의 active-only 목록에서 해당 게시글이 제외돼야 한다. |
| COMMUNITY-011 | 확정 | 첨부 audio URL 갱신만을 위한 자동 요청은 하지 않으며 media error도 refetch trigger로 사용하지 않는다. 사용자 페이지 새로고침이나 mutation 후 cache 무효화 등 일반 목록 재조회가 발생하면 새 응답의 `audioUrl`을 사용한다. |
| COMMUNITY-012 | 확정 | 목록 GET은 필수 `timezone=Asia/Seoul`, `page`, `size`를 사용하고 `data`의 게시글 배열을 소비한다. 응답에 `totalCount`, `page`, `hasNext`가 없으므로 전체 건수·마지막 page를 추정하지 않는다. |
| COMMUNITY-012 | 확정 | 목록 GET은 `timezone` 없이 `page`, `size`를 사용하고 `data.totalCount`, `data.page`, `data.size`, `data.hasNext`, `data.items[]`를 소비한다. 전체 건수와 다음 page 여부는 서버 metadata를 그대로 사용한다. |
| COMMUNITY-013 | 확정 | 생성 multipart는 optional `audioFile`, optional `postImage`, 필수 `request`를 사용하고 request에 필수 `content`, `isCommentAvailable`, `isAdult`와 optional `price`만 보낸다. |
| COMMUNITY-014 | 확정 | 수정 multipart는 optional `postImage`와 필수 `request`만 허용한다. 수정에서 가격·첨부 audio 교체는 제공하지 않고, 고정은 `isFixed`, soft delete는 `isActive=false`로 처리한다. |
| COMMUNITY-015 | 확정 | 생성·수정·고정·soft delete 성공은 `data=null`이므로 목록을 무효화·재조회하고 mutation 응답에 게시글 DTO가 있다고 가정하지 않는다. |
@@ -317,16 +318,17 @@ AI 캐릭터를 생성하고, AI 캐릭터가 사람 크리에이터처럼 콘
| ID | 상태 | 요구사항 |
|---|---|---|
| FANTALK-001 | 확정 | 기본 목록은 backend가 반환한 순서를 유지한다. 현 계약에 sort query가 없으므로 client가 page 사이의 최신순을 재정렬하지 않는다. |
| FANTALK-002 | 외부 의존 | 전체·미답변·답변 완료 server filter query가 OpenAPI에 없다. 전체 결과 filter 계약이 제공되기 전에는 현재 page만 거르는 filter를 완성 기능으로 제공하지 않는다. |
| FANTALK-002 | 제외 | 현재 UI에는 전체·미답변·답변 완료 filter control을 제공하지 않는다. 현재 page만 client에서 거르는 불완전한 filter도 만들지 않는다. 후속 제품 범위에서 전체 결과 filter가 필요해지면 server query 계약과 함께 별도 요구사항으로 다시 포함한다. |
| FANTALK-003 | 확정 | 하나의 FanTalk에는 답변을 한 번만 작성할 수 있다. |
| FANTALK-004 | 외부 의존 | 답변이 있으면 추가 작성은 UI에서 차단한다. 기존 답변 수정 endpoint는 OpenAPI에 없으므로 계약 제공 전에는 수정 network integration을 구현하지 않는다. |
| FANTALK-004 | 확정 | `creatorReplies`가 비어 있으면 답변 작성 UI를, 비어 있지 않으면 기존 답변 수정 UI를 제공한다. 수정은 `PUT /api/v2/admin/ai-characters/{characterId}/fan-talks/{fanTalkId}/replies/{replyId}`에 `{ "content": string }`만 보내며 path의 `replyId`에는 `creatorReplies[].fanTalkId`를 사용한다. 백엔드 구현 완료 확인에 따라 OpenAPI operation도 `implemented`로 정정했으므로 mock/client와 실제 server integration을 모두 구현·검증한다. |
| FANTALK-005 | 확정 | 답변 삭제는 현재 범위가 아니다. |
| FANTALK-006 | 확정 | 데스크톱·태블릿·모바일 모두 목록 조회와 답변 작성을 지원한다. 답변 수정은 수정 계약이 제공된 뒤 같은 viewport 범위에 추가한다. |
| FANTALK-007 | 외부 의존 | 목록 GET과 답변 POST는 제공됐다. 별도 상세 GET, 답변 수정 endpoint·DTO, 답변 상태 filter와 sort 계약은 백엔드가 제공해야 하며 제공 전에는 해당 network integration을 구현하지 않는다. |
| FANTALK-008 | 외부 의존 | 답변 1개 불변식의 원자적 강제와 중복 생성의 정확한 비2xx status/message key는 백엔드가 결정·제공해야 한다. |
| FANTALK-009 | 확정 | 목록은 `page`, `size`를 사용하고 `data.fanTalkCount`, `data.fanTalks`, `data.page`, `data.size`, `data.hasNext`를 소비한다. 각 item의 `creatorReplies[]`로 답변 유무를 판단한다. |
| FANTALK-006 | 확정 | 데스크톱·태블릿·모바일 모두 목록 조회, 답변 작성과 기존 답변 수정을 지원한다. |
| FANTALK-007 | 확정 | 별도 상세 GET·직접 route, 답변 상태 filter, sort control은 현재 UI 범위가 아니다. 목록 item을 source로 Sheet/panel을 열고 backend 반환 순서를 유지하므로 추가 network 계약 없이 목록·작성·수정·팬 원글 삭제를 구현한다. |
| FANTALK-008 | 제외 | 중복 생성의 정확한 비2xx status/message key를 사용하는 도메인별 오류 분기는 만들지 않는다. 답변 1개 불변식 자체는 `FANTALK-003`의 backend 수용 기준이며, client는 한 화면의 중복 submit을 막고 일반 오류 후 현재 목록을 재조회한다. 동시 POST 후에도 답변이 하나인지 실제 server integration에서 검증하며 위반 시 backend 결함으로 기록한다. |
| FANTALK-009 | 확정 | 목록은 `page`, `size`를 사용하고 `data.fanTalkCount`, `data.fanTalks`, `data.page`, `data.size`, `data.hasNext`를 소비한다. `creatorReplies.length === 0`이면 미답변, 하나 이상이면 답변 완료로 판단하며 기존 답변 수정 시 첫 답변의 `fanTalkId`를 `replyId`로 사용한다. |
| FANTALK-010 | 확정 | 답변 작성은 `{ "content": string }`을 보내고 성공 응답의 `fanTalkId`, `replyId`, `creatorMemberId`, `content`, `createdAtUtc`를 사용한다. |
| FANTALK-011 | 확정 | 별도 상세 endpoint가 없으므로 목록 item을 source로 collection Sheet 또는 panel을 열며 `/fan-talks/:fanTalkId` 직접 route를 만들지 않는다. |
| FANTALK-012 | 확정 | 관리자는 팬 작성 FanTalk 원글을 `DELETE /api/v2/admin/ai-characters/{characterId}/fan-talks/{fanTalkId}`로 soft delete할 수 있다. 성공 후 현재 목록을 재조회하고 해당 원글을 닫으며, 연결된 creator reply를 별도 삭제했다고 가정하지 않는다. |
### 8.7 댓글과 답글
@@ -334,10 +336,12 @@ AI 캐릭터를 생성하고, AI 캐릭터가 사람 크리에이터처럼 콘
|---|---|---|
| COMMENT-001 | 확정 | 오디오 콘텐츠와 커뮤니티 게시글에 댓글 영역을 제공한다. |
| COMMENT-002 | 확정 | 구조는 루트 댓글과 그 댓글의 직접 답글까지 정확히 2단계다. 답글의 답글은 허용하지 않는다. |
| COMMENT-003 | 확정 | AI 캐릭터는 루트 댓글과 답글을 작성하고 자신이 작성한 내용을 수정·soft delete할 수 있다. |
| COMMENT-004 | 확정 | 팬이 작성한 루트 댓글과 답글은 수정할 수 없고 운영 목적의 soft delete만 가능하다. |
| COMMENT-003 | 확정 | AI 캐릭터는 루트 댓글과 답글을 작성하고 자신이 작성한 내용을 수정할 수 있다. 댓글의 `writerId`와 대상 오디오·커뮤니티 게시글의 `creatorId`가 같으면 AI 캐릭터 작성으로 판단한다. |
| COMMENT-004 | 확정 | `writerId !== creatorId`인 팬 작성 루트 댓글과 답글에는 수정 UI를 제공하지 않는다. 관리자는 작성자와 관계없이 운영 목적으로 해당 row만 soft delete할 수 있으며 하위 답글을 함께 삭제했다고 가정하지 않는다. |
| COMMENT-005 | 확정 | 모바일에서도 조회·작성·수정·soft delete를 모두 지원한다. |
| COMMENT-006 | 외부 의존 | 댓글 목록·작성·수정·soft delete API와 팬 댓글 삭제 권한 오류 계약은 백엔드가 결정·제공해야 한다. 제공 전에는 댓글 network integration을 구현하지 않는다. |
| COMMENT-006 | 확정 | 오디오 콘텐츠와 커뮤니티 게시글은 각각 루트 댓글 목록 GET, 댓글·답글 POST, AI 캐릭터 작성 댓글 PUT, 작성자 무관 DELETE, 루트별 답글 목록 GET을 제공한다. 모든 mutation 성공 `data=null`을 처리하고 목록·답글 cache를 재조회한다. |
| COMMENT-007 | 확정 | 루트 댓글은 `.../comments`, 직접 답글은 `.../comments/{commentId}/replies`에서 조회한다. 작성 POST의 `parentId`를 생략하거나 `null`로 보내면 루트, 같은 target의 활성 루트 ID를 보내면 직접 답글이며 답글의 답글은 UI에서 허용하지 않는다. |
| COMMENT-008 | 확정 | 댓글 날짜는 ISO-8601 UTC `Z` 값으로 소비해 Asia/Seoul로 표시한다. 오디오 댓글 작성 request는 `comment`, optional `parentId`, `isSecret`, `languageCode`를 사용하고 커뮤니티 댓글 작성 request는 `comment`, optional `parentId`, `isSecret`을 사용한다. 수정 request는 공통 `{ "comment": string }`이다. |
### 8.8 공통 파일 정책
@@ -401,7 +405,7 @@ AI 캐릭터를 생성하고, AI 캐릭터가 사람 크리에이터처럼 콘
| 커뮤니티 등록·수정·고정·비활성화 | 전체 | 전체 | 미지원 |
| 댓글·답글 관리 | 전체 | 전체 | 전체 |
| FanTalk 조회·답변 작성 | 전체 | 전체 | 전체 |
| FanTalk 답변 수정 | 계약 제공 후 전체 | 계약 제공 후 전체 | 계약 제공 후 전체 |
| FanTalk 답변 수정·팬 원글 soft delete | 전체 | 전체 | 전체 |
모바일에서 미지원인 기능은 좁은 화면에 데스크톱 폼을 억지로 노출하지 않는다. 화면에는 읽기 전용임을 알리고 전체 관리가 필요하면 데스크톱·태블릿 사용을 안내한다.
@@ -527,7 +531,7 @@ AI 캐릭터를 생성하고, AI 캐릭터가 사람 크리에이터처럼 콘
- 오류: 서버의 한국어 message, 재시도, 필요한 경우 목록으로 이동
- 저장 중: 제출 버튼 비활성화와 진행 표시
- 저장 성공: toast와 최신 서버 응답 반영
- soft delete 성공: 해당 resource 목록을 무효화·재조회하고 필요한 화면 이동과 성공 toast 표시. 비활성 항목 제외는 active-only 계약 제공 후 검증
- soft delete 성공: 해당 resource 목록을 무효화·재조회하고 필요한 화면 이동과 성공 toast 표시. 서버 active-only 목록에서 비활성 항목 제외를 확인하며 client filter로 보정하지 않음
- 필드 오류: 로컬 validation은 해당 필드 아래에 표시하고 `aria-invalid`, 오류와 입력 연결, 첫 오류 focus를 제공한다. 서버 오류는 `errorProperty`가 실제 필드명을 제공하는 계약일 때만 inline으로 연결한다.
- 업로드: 파일별 진행률, 취소, 재시도
@@ -590,8 +594,8 @@ python3 .codex/skills/ui-ux-pro-max/scripts/search.py \
## 11. API 계약
현재 기준은 OpenAPI `3.1.0`, 문서 version `2.0.0`인
`api-contract.openapi.json`의 15개 path·23개 operation이다.
현재 기준은 OpenAPI `3.1.0`, 문서 version `2.3.0`인
`api-contract.openapi.json`의 25개 path·37개 operation이다.
OpenAPI에 아직 포함되지 않은 기존 로그인·로그아웃은 `EXT-006 현재 구현
기준 계약`에 별도로 기록하며, 정식 OpenAPI가 제공될 때까지 구현과 회귀
검증의 임시 기준으로 사용한다.
@@ -630,7 +634,7 @@ response schema를 따르며 공통 client가 임의의 상세 응답으로 정
- OpenAPI의 `Accept-Language`는 optional이고 기본값은 `ko`다. `ko|en|ja` 이외 값과 header 누락은 KO로 fallback하며, 프론트엔드는 일관되게 `ko`를 보낸다.
- OpenAPI operation은 전역 `bearerAuth`를 사용한다. 로그인 이외의 관리자 API에는 `Authorization: Bearer {jwt-token}`을 보낸다.
- 공통 `page`는 기본 `0`, 최소 `0`이고 공통 `size`는 기본 `20`, 최소 `1`이다. 전역 최대 `50`은 없다. FanTalk `size`만 설명에 따라 `20..50`으로 보정된다.
- Audio 상세와 Community 목록은 필수 `timezone=Asia/Seoul` query를 보낸다.
- AI 캐릭터 관리자 API의 날짜·시간 request/response는 OpenAPI가 별도로 명시한 nullable 조건을 제외하고 ISO-8601 UTC `Z`를 사용하며 `timezone` query/body field를 보내지 않는다.
- `characterId`는 선택된 대상 캐릭터가 필요한 하위 resource endpoint에만 사용한다.
- 캐릭터 목록·검색과 캐릭터 생성에는 path `characterId`가 없다.
- `/admin/member/login`, `/member/logout`은 현 OpenAPI 범위 밖의 기존 인증 계약이다. 두 endpoint의 현재 구현 기준은 `11.5 EXT-006`에 기록하고 Phase 1 구현과 회귀 검증을 유지하되, 정식 OpenAPI operation으로 표기하지 않는다.
@@ -665,10 +669,15 @@ AI 캐릭터 관리자 domain의 query, multipart part, request/response field
| 인증 | POST | `/admin/member/login` | 현재 구현·test 기준, OpenAPI 미포함(`EXT-006`) |
| 인증 | POST | `/member/logout` | 현재 구현·test 기준, OpenAPI 미포함(`EXT-006`) |
| 캐릭터 | GET, POST | `/api/v2/admin/ai-characters` | 제공됨 |
| 원작 검색 | GET | `/api/v2/admin/ai-characters/original-works/search` | 제공됨, 필수 `searchTerm` |
| 캐릭터 | GET, PUT | `/api/v2/admin/ai-characters/{characterId}` | 제공됨 |
| 오디오 테마 | GET | `/api/v2/admin/ai-characters/audio-content-themes` | 제공됨, query/body 없음 |
| 오디오 | GET, POST | `/api/v2/admin/ai-characters/{characterId}/audio-contents` | 제공됨 |
| 오디오 | GET, PUT | `.../audio-contents/{contentId}` | 제공됨 |
| 오디오 댓글 | GET, POST | `.../audio-contents/{contentId}/comments` | 제공됨 |
| 오디오 댓글 | PUT, DELETE | `.../audio-contents/{contentId}/comments/{commentId}` | 제공됨 |
| 오디오 댓글 답글 | GET | `.../audio-contents/{contentId}/comments/{commentId}/replies` | 제공됨 |
| 시리즈 장르 | GET | `/api/v2/admin/ai-characters/series-genres` | 제공됨, query/body 없음 |
| 시리즈 | GET, POST | `/api/v2/admin/ai-characters/{characterId}/series` | 제공됨 |
| 시리즈 순서 | PUT | `.../series/orders` | 제공됨 |
| 시리즈 | GET, PUT | `.../series/{seriesId}` | 제공됨 |
@@ -677,8 +686,13 @@ AI 캐릭터 관리자 domain의 query, multipart part, request/response field
| 시리즈 콘텐츠 | DELETE | `.../series/{seriesId}/contents/{contentId}` | 제공됨 |
| 커뮤니티 | GET, POST | `.../{characterId}/community-posts` | 제공됨 |
| 커뮤니티 | PUT | `.../community-posts/{postId}` | 제공됨 |
| 커뮤니티 댓글 | GET, POST | `.../community-posts/{postId}/comments` | 제공됨 |
| 커뮤니티 댓글 | PUT, DELETE | `.../community-posts/{postId}/comments/{commentId}` | 제공됨 |
| 커뮤니티 댓글 답글 | GET | `.../community-posts/{postId}/comments/{commentId}/replies` | 제공됨 |
| FanTalk 목록 | GET | `.../{characterId}/fan-talks` | 제공됨 |
| FanTalk 팬 원글 | DELETE | `.../{characterId}/fan-talks/{fanTalkId}` | 제공됨 |
| FanTalk 답변 | POST | `.../{characterId}/fan-talks/{fanTalkId}/replies` | 제공됨 |
| FanTalk 답변 | PUT | `.../{characterId}/fan-talks/{fanTalkId}/replies/{replyId}` | 제공됨, backend 구현 완료 |
### 11.4 OpenAPI 소비 시 주의사항
@@ -689,40 +703,45 @@ OpenAPI로 전환할 때 반드시 반영할 차이다. 제품 정책이 OpenAPI
| 영역 | OpenAPI 계약 | 프론트엔드 처리 |
|---|---|---|
| Character 목록 | query `searchTerm`; `data={totalCount,content}`; item ID `id` | `search`·`items`·`hasNext`로 바꾸지 않는다. |
| Character 원작 검색 | 필수 `searchTerm`; `data`는 `OriginalWorkSearchItem[]` | legacy lookup을 호출하지 않고 반환 `id`를 `originalWorkId`로 사용한다. |
| Character 생성 | 필수 multipart `image`, `request`; request의 필수 `name`, `systemPrompt`, `description`; 성공 `data=null` | 생성 후 목록을 재조회하고 새 ID를 응답에서 추정하지 않는다. |
| Character 상세 | `characterUUID`, `originalWork`를 포함하고 creator field는 없음 | `characterUUID`를 `externalCharacterId`로 취급하지 않고 creator UI는 만들지 않는다. |
| Audio 목록 | query `search_word`; `data={totalCount,items}`; status query/field 없음 | 2자 이상 제목 검색만 보내고 status filter·badge를 만들지 않는다. |
| Audio 테마 | `data=[{id,theme,image}]` | `themeId`·`themeName`·`imageUrl`로 역직렬화하지 않는다. |
| Audio 생성 | multipart `contentFile`, `coverImage`, `request`; `releaseDate`는 `yyyy-MM-dd HH:mm`; 성공 `data.contentId` | `audioFile`, `releaseDateUtc`, `seriesIds`를 보내지 않는다. |
| Audio 생성 | multipart `contentFile`, `coverImage`, `request`; `releaseDate`는 nullable ISO-8601 UTC `Z`; `timezone` field 없음; 성공 `data.contentId` | 예약 입력을 client에서 UTC로 변환하고 `audioFile`, `releaseDateUtc`, `timezone`, `seriesIds`를 보내지 않는다. |
| Audio 상세 | `timezone` query 없음; nullable `releaseDate`는 ISO-8601 UTC `Z` | UTC 값을 Asia/Seoul 표시로 변환하되 API status를 재계산하지 않는다. |
| Audio 수정 | optional `coverImage`와 제한된 request field만 제공 | content file, 공개 예약, theme, series 연결 수정 UI를 제공하지 않는다. |
| 가격 | Audio 생성·수정과 Community 생성 request의 `price`는 `0..99999` 정수 | `-1`, `100000`, 소수는 제출 전에 거부하고 `0`, `99999`는 허용한다. |
| Series 생성 | 필수 `image`; request의 `keyword`는 문자열; 성공 `data=null` | `keywords` 배열을 보내지 않고 목록으로 이동해 재조회한다. |
| Series 상세 | 요일·장르·keywords·state가 표시용 문자열 | 목록 enum 또는 update payload 값으로 재사용하지 않는다. |
| Series 장르 | query/body 없는 활성 장르 목록; `data=[{id,genre,isAdult}]` | `id`를 `genreId` 선택값으로 사용하고 `0`을 유효값으로 허용하지 않는다. |
| Series 상세 | 목록과 같은 `SeriesListItem`; `genreId`, enum `publishedDaysOfWeek`, enum `state` | 직접 수정 form을 원본값으로 초기화하고 create-only `keyword`를 상세·수정 field로 만들지 않는다. |
| Series 연결·순서 | 후보 `contents/search`; 연결 `{contentIdList}`; 순서 `{ids}` | `{contentIds}`, `{seriesIds}`를 보내지 않는다. |
| Community 목록 | 필수 `timezone`; `data`는 배열이고 pagination metadata 없음 | `audioUrl`을 사용하고 total/hasNext를 추정하지 않는다. |
| Community 목록 | `timezone` query 없음; `data={totalCount,page,size,hasNext,items}` | `audioUrl`과 서버 pagination metadata를 그대로 사용한다. |
| Community 생성·수정 | 생성 part `postImage`/`audioFile`; 수정은 `postImage`만 교체 가능; mutation `data=null` | `image`, `audioSignedUrl`, 수정 audio/price field를 만들지 않는다. |
| FanTalk | 목록 GET과 답변 POST만 제공 | 목록 item 기반 UI와 답변 생성만 구현하고 상세·수정·filter/sort는 외부 의존으로 둔다. |
| FanTalk | 목록 GET, 답변 POST, 팬 원글 DELETE, 답변 PUT이 모두 구현됨 | `creatorReplies`의 빈 배열 여부로 작성/수정을 나누고 `creatorReplies[].fanTalkId`를 PUT의 `replyId`로 사용한다. 별도 상세·filter/sort와 중복 오류 key 분기는 현재 UI 범위에서 제외한다. |
| 댓글 | Audio·Community 각각 루트 목록/작성, AI 작성 댓글 수정, 작성자 무관 soft delete, 루트별 답글 목록 제공 | `writerId === creatorId`일 때만 수정 UI를 노출하고 삭제는 작성자와 관계없이 제공한다. |
### 11.5 백엔드 제공 대기 계약
### 11.5 백엔드 계약 제공·대기 상태
아래 항목은 프론트엔드 인터뷰로 결정할 Open Question이 아니라 **외부
의존**이다. P0 계약을 제공받기 전에는 영향을 받는 network integration을
구현하지 않는다. UI shell과 계약에 의존하지 않는 표현 작업은 병행할 수
있다. 단, `EXT-006`은 이미 구현·검증된 기존 인증 endpoint의 정식 문서화
의존이므로 Phase 3~9 진행을 차단하지 않는다.
아래 항목은 프론트엔드 인터뷰로 결정할 Open Question이 아니라 backend
계약의 제공·해결 상태를 추적한다. `해결`된 항목은 완료된 Phase를
묵시적으로 다시 열지 않고 `plan-task.md`의 완료된 Phase 10 후속
vertical slice와 남은 수동 QA에서 검증한다. `EXT-006`은 현재 확정 기능 구현을 차단하지
않으며 정식 OpenAPI 추적성만 후속으로 관리한다.
| ID | 우선순위 | 백엔드 제공 필요 계약 | 프론트엔드 영향 |
|---|---:|---|---|
| EXT-001 | P0 | 원작 검색 lookup | Character 원작 선택기 network integration 대기 |
| EXT-002 | P0 | 장르 검색 lookup | 유효한 `genreId` 선택이 필요한 Series 생성 integration 대기 |
| EXT-003 | P0 | Series 수정 form 초기화용 edit DTO 또는 표시 문자열 mapping | 직접 링크에서 genreId·요일 enum·state enum을 안전하게 복원하는 수정 integration 대기 |
| EXT-004 | P0 | FanTalk 상세·답변 수정·답변 상태 filter·sort·유일성 오류 | 목록 item 밖의 상세·수정, 전체 결과 filter와 동시 중복 답변 처리 대기 |
| EXT-005 | P0 | 오디오·커뮤니티 댓글 CRUD와 팬 댓글 삭제 권한 오류 | 댓글·답글 연동과 권한별 오류 처리 대기 |
| EXT-006 | P0 비차단 | 현재 구현된 `POST /admin/member/login`, `POST /member/logout`의 정식 OpenAPI 포함 또는 별도 버전 고정 계약 | 현재 구현과 Phase 1 회귀는 유지하며 Phase 3~9를 차단하지 않는다. 신규 인증 변경과 전체 계약의 단일 추적성만 정식 계약 제공 대기다. |
| EXT-007 | P0 | Character 검색 결과와 Audio·Series·Community 목록의 active-only 반환 보장 | soft delete 뒤 비활성 항목이 서버 목록에서 제외된다는 수용 기준 검증 대기 |
| EXT-008 | P1 | Community pagination의 total/hasNext 또는 종료 규칙 | 신뢰할 수 있는 전체 건수와 마지막 page UI 대기 |
| EXT-009 | P1 | price 최대값 | 현재 0 이상 정수 규칙만 적용하며 상한 계약 제공 시 Audio·Community schema와 경계값 test 갱신 |
| EXT-010 | P1 | 파일 크기·MIME·crop·container/codec의 backend 검증 계약 | PRD의 client 사전 검증은 유지하되 server와 동일 경계라는 완료 주장은 계약 제공 후 검증 |
| EXT-011 | P0 | 도메인별 오류 | 기능별 정확한 비2xx status와 message key 분기가 필요한 흐름 대기 |
| ID | 우선순위 | 백엔드 제공 필요 계약 | 사용하는 화면 | 관련 API 흐름 | 현재 프론트엔드 영향 |
|---|---:|---|---|---|---|
| EXT-001 | 해결 | `GET /api/v2/admin/ai-characters/original-works/search?searchTerm=...`와 `OriginalWorkSearchItem[]`가 OpenAPI에 `implemented`로 추가됐다. | 캐릭터 생성 `/ai-characters/new`, 캐릭터 수정 `/ai-characters/:characterId/profile` | 원작 검색 GET과 Character create/update의 `originalWorkId` | legacy 후보 대신 v2 lookup을 사용하는 선택기·contract test를 Phase 10에서 구현 완료했다. |
| EXT-002 | 해결 | query/body 없는 `GET /api/v2/admin/ai-characters/series-genres`와 `{id,genre,isAdult}[]`가 OpenAPI에 `implemented`로 추가됐다. | 시리즈 생성 `/ai-characters/:characterId/series/new`, 수정 `/ai-characters/:characterId/series/:seriesId/edit` | 장르 목록 GET과 Series create/update의 `genreId` | 장르 선택과 Series 생성·수정 후속 구현을 Phase 10에서 완료했다. |
| EXT-003 | 필요 없음 | 별도 Series 수정 DTO 또는 표시 문자열 mapping 계약 | 시리즈 수정 `/ai-characters/:characterId/series/:seriesId/edit`, 시리즈 상세 직접 진입 | `GET /api/v2/admin/ai-characters/{characterId}/series/{seriesId}`가 `SeriesListItem`과 같은 `genreId`, enum `publishedDaysOfWeek`, enum `state`를 내려주면 충분하다. | 별도 외부 의존으로 추적하지 않는다. 수정 화면은 상세 응답으로 기존 값을 초기화하고 장르 API는 option 목록 표시용으로만 사용한다. |
| EXT-004 | 해결 | 답변 유무는 `creatorReplies`의 빈 배열 여부로 판정한다. 답변 PUT과 팬 원글 DELETE가 `implemented`이며 PUT path의 `replyId`는 `creatorReplies[].fanTalkId`를 사용한다. 별도 상세·filter·sort와 중복 오류 key는 현재 UI에 필요하지 않아 `FANTALK-002`, `FANTALK-008`에서 제외했다. | FanTalk 목록 `/ai-characters/:characterId/fan-talks`, FanTalk item Sheet/panel | 목록 GET, 답변 POST, 팬 원글 DELETE, 답변 PUT을 사용한다. 목록 item이 Sheet source이고 backend 반환 순서를 유지하므로 별도 상세 GET·filter·sort query를 요청하지 않는다. | Phase 10에서 답변 수정·팬 원글 삭제의 mock/client integration을 구현 완료했다. 실제 개발 API 수동 QA에서 동시 POST 후 활성 답변 1개 유지 등 server 수용 기준을 분리 확인한다. |
| EXT-005 | 해결 | Audio·Community 각각 루트 목록/작성, AI 작성 댓글 수정, 작성자 무관 soft delete, 루트별 답글 목록 operation과 DTO가 OpenAPI에 `implemented`로 추가됐다. `writerId === creatorId`이면 AI 작성 댓글로 판정한다. | 오디오 상세 `/ai-characters/:characterId/audio-contents/:contentId`, 커뮤니티 Sheet `/ai-characters/:characterId/community-posts` | 두 target의 `comments`, `comments/{commentId}`, `comments/{commentId}/replies` | Phase 10에서 2단계 thread, 작성·수정·삭제, Comments mock/client integration을 구현 완료했다. 팬 작성 댓글은 수정하지 않고 관리자 DELETE만 제공한다. |
| EXT-006 | P0 비차단 | 현재 구현된 `POST /admin/member/login`, `POST /member/logout`의 정식 OpenAPI 포함 또는 별도 버전 고정 계약 | 로그인 `/login`, 보호 shell 로그아웃 | `POST /admin/member/login`, `POST /member/logout` | 현재 구현과 Phase 1 회귀는 유지한다. 정식 OpenAPI 추적성만 대기하며 Phase 3~9를 차단하지 않는다. |
| EXT-007 | 해결 | Character 검색 결과와 Audio·Series·Community 목록 API는 `isActive=true`인 항목만 반환한다. | 캐릭터 목록, 오디오 목록, 시리즈 목록, 커뮤니티 목록 | 각 목록 GET: `/ai-characters`, `/audio-contents`, `/series`, `/community-posts` | 프론트엔드 변경 없음. 활성 query·client-side filter를 만들지 않고 soft delete 후 목록 재조회 결과를 server integration에서 확인한다. |
| EXT-008 | 해결 | Community 목록 응답이 `data={totalCount,page,size,hasNext,items}`로 보완됐다. | 커뮤니티 목록 `/ai-characters/:characterId/community-posts` | `GET /api/v2/admin/ai-characters/{characterId}/community-posts` | Phase 10에서 기존 배열 parser와 `timezone` query 제거, 서버 pagination metadata 기반 UI·test 갱신을 완료했다. |
| EXT-009 | 해결 | price 최대값은 `99999` 캔이며 관련 OpenAPI request schema에도 `minimum=0`, `maximum=99999`를 명시했다. | 오디오 생성·수정, 커뮤니티 생성 | Audio `POST/PUT .../audio-contents`, Community `POST .../community-posts` | Phase 10에서 schema·form과 경계값 test를 `0..99999` 정수로 갱신 완료했다. |
| EXT-010 | 해결 | 파일 정책은 `FILE-001~015`로 확정됐다. 이미지 비율·crop 결과는 client가 보장하고 backend는 검증하지 않는다. 파일 용량, MIME 등 서버에서 확인 가능한 항목은 backend가 동일하게 검증한다. | 캐릭터 생성·수정, 오디오 생성·수정, 시리즈 생성, 커뮤니티 생성·수정 | 각 multipart 생성·수정 API의 image/audio file part | 외부 의존에서 제외한다. client는 기존 사전 검증을 유지하고, server integration에서는 용량·MIME reject만 확인한다. |
| EXT-011 | 해결 | OpenAPI에 명시된 공통 오류 envelope/status만 도메인 화면에서 사용한다. OpenAPI 밖의 도메인별 오류 key는 추정하지 않고, 미정의 오류는 `알 수 없는 오류가 발생했습니다.`로 표시한다. | Character, Audio, Series, Community, FanTalk의 form·list·detail·mutation 화면 | 각 도메인 API의 비2xx 응답 `status`, `message`, `errorProperty` | 기능별 정확한 message key 분기가 필요한 inline 오류·충돌·중복·missing-id 처리는 후속 계약 전까지 만들지 않는다. |
#### EXT-006 현재 구현 기준 계약
@@ -773,19 +792,19 @@ OpenAPI로 전환할 때 반드시 반영할 차이다. 제품 정책이 OpenAPI
### 감사 로그 미결 사항과 권고
현재 감사 로그 정책은 **미결**이다.
감사 로그 조회 UI는 현재 릴리스에서 **제외**한다.
**권고:** 이번 범위에서는 백엔드가 관리자 ID, 대상 캐릭터 ID, resource 종류와 ID, action, 성공/실패, 서버 시각, request ID, 민감정보를 제거한 변경 요약을 기록한다. 관리자 UI의 감사 로그 조회 화면은 후속 범위로 둔다. JWT, 비밀번호, signed URL, 파일 본문은 기록하지 않는다.
**처리:** 이번 범위에서는 백엔드 감사 기록을 우선한다. 조회 화면이 필요해지면 조회 endpoint, 권한, 필터 계약을 포함한 별도 Phase로 다시 계획한다. JWT, 비밀번호, signed URL, 파일 본문은 기록하지 않는다.
## 13. 성능과 품질 요구사항
- 목록은 계약에 있는 서버 page/size를 사용하고 무제한 전체 로드를 피한다. 시리즈 순서 변경 모드는 `totalCount`를 기준으로 모든 page를 읽는다. Community는 종료 metadata 계약이 제공되기 전까지 전체 건수·마지막 page를 표시하지 않는다.
- 목록은 계약에 있는 서버 page/size를 사용하고 무제한 전체 로드를 피한다. 시리즈 순서 변경 모드는 `totalCount`를 기준으로 모든 page를 읽는다. Community는 서버가 제공하는 `totalCount`, `page`, `size`, `hasNext` metadata로 전체 건수와 다음 page 여부를 표시한다.
- 이미지에는 고정 aspect ratio와 크기를 예약해 layout shift를 줄이고 목록 이미지는 lazy load한다.
- 필터 변경 중 기존 데이터를 유지해 화면 깜빡임을 줄인다.
- 파일 업로드 외의 일반 mutation은 중복 제출을 막는다.
- 목록 검색 debounce 시간은 구현 시 300ms 전후로 일관되게 적용한다.
- 날짜, 가격, 상태 label은 중앙 formatter로 일관되게 표시한다.
- 브라우저 지원 범위는 데스크톱 Chrome/Edge/Safari 최신 2개 주요 버전과 모바일 Chrome/Safari 최신 2개 주요 버전이다.
- 브라우저 지원 범위는 데스크톱 Chrome과 모바일 Chrome이다. 로컬 자동 Gate는 Chromium/mobile Chrome project로 검증한다.
- mock/server mode는 build-time 환경 설정으로 명시적으로 선택하며 runtime 404 fallback을 사용하지 않는다.
- domain fixture와 browser handler는 `api-contract.openapi.json`의 제공 계약에서 파생하고 contract test와 함께 변경한다.
@@ -800,10 +819,10 @@ OpenAPI로 전환할 때 반드시 반영할 차이다. 제품 정책이 OpenAPI
- 로그아웃 API가 성공하거나 네트워크·비2xx 오류로 실패해도 로컬 session이 제거되고 로그인 화면으로 이동하며, 실패한 경우 경고가 표시되고 session이 복원되지 않는다.
- 캐릭터 생성 multipart가 필수 `image`와 `request`를 보내고 request에 `name`, `systemPrompt`, `description`이 포함되며 `isActive`와 `externalCharacterId`는 포함되지 않는다.
- Character, Audio, Series, Community의 일반 수정은 `isActive`를 생략하고 soft delete에만 `isActive=false`를 보내며 `true`는 전송하지 않는다.
- Character, Audio, Series의 soft delete가 성공하면 목록 cache를 무효화·재조회하고 목록으로 이동하며 성공 알림을 표시한다. Community는 열린 Sheet를 닫고 목록을 재조회한다. 서버 목록에서 비활성 항목이 제외되는지는 active-only 계약 제공 후 검증한다.
- Character, Audio, Series의 soft delete가 성공하면 목록 cache를 무효화·재조회하고 목록으로 이동하며 성공 알림을 표시한다. Community는 열린 Sheet를 닫고 목록을 재조회한다. 재조회된 각 서버 목록에는 `isActive=false`인 항목이 없어야 하며 클라이언트 필터로 이 결과를 만들지 않는다.
- 캐릭터 수정이 creator profile 동기화 결과와 함께 다시 조회된다.
- 워크스페이스 진입·복원용 상세 성공 응답으로 `isActive=false`인 캐릭터를 받은 경우 프론트엔드가 모든 하위 mutation 진입점을 차단한다. soft delete 성공 직후에는 목록 이동·재조회를 우선하고, 상세 요청의 비2xx 응답은 공통 오류 처리로 표시한다.
- 오디오 생성에서 즉시 공개는 `releaseDate=null`, 예약 공개는 미래 Asia/Seoul 시각을 `yyyy-MM-dd HH:mm`로 보내고 `timezone="Asia/Seoul"`을 포함한다.
- 오디오 생성에서 즉시 공개는 `releaseDate=null`을 보내고, 예약 공개는 미래 Asia/Seoul 입력을 클라이언트에서 ISO-8601 UTC `Z`로 변환해 보낸다. 생성·상세·커뮤니티 목록 요청에는 `timezone` field/query가 없어야 한다.
- MP3, AAC, M4A 업로드의 진행률·취소·재시도와 `1,024,000,000 bytes` 허용·`1,024,000,001 bytes` 거부 경계 검증이 동작한다.
- 오디오 콘텐츠와 커뮤니티 첨부 audio가 동일한 확장자·MIME·최대 크기·재생 길이 정책을 사용한다.
- `.m4a`는 `audio/mp4`와 `audio/x-m4a`를 허용하되 호환 MIME도 실제 MP4/M4A container·codec 검증을 통과해야 한다.
@@ -816,14 +835,19 @@ OpenAPI로 전환할 때 반드시 반영할 차이다. 제품 정책이 OpenAPI
- crop Dialog에서 이동·확대/축소·초기화·미리보기·취소/적용을 keyboard와 pointer로 완료할 수 있다.
- 오디오 목록·상세와 커뮤니티 목록 항목의 첨부 오디오가 재생된다.
- 오디오 콘텐츠 생성 시 테마 목록 `data[]`의 `id`, `theme`, `image`를 query/body 없이 조회하고 선택한 `id`를 request의 `themeId`에 포함한다.
- 캐릭터 원작 선택기는 필수 `searchTerm`으로 v2 원작 검색 API를 호출하고 선택한 `OriginalWorkSearchItem.id`를 create/update의 `originalWorkId`로 보낸다.
- media error를 signed URL 만료로 구분하지 않고 일반 재생 오류를 표시한다. 오류만으로 API를 자동 재조회하거나 자동 재생하지 않으며 사용자가 수동 재시도하거나 페이지를 새로고침할 수 있다.
- 커뮤니티는 전용 상세 GET이나 상세·수정 route 없이 목록 응답 기반 Sheet에서 조회·수정·고정·비활성화·댓글 진입을 제공한다.
- 오디오 생성·수정과 커뮤니티 생성의 가격은 `0`, `99999`를 허용하고 `-1`, `100000`, 소수를 제출 전에 거부한다.
- Series에 `OPEN`이나 `MONDAY` 같은 잘못된 값을 보내지 않는다.
- Series 생성에는 state를 보내지 않고 `keyword` 문자열을 사용하며, 수정에서 state를 바꾸지 않으면 field를 생략한다.
- RANDOM과 실제 요일을 동시에 선택할 수 없다.
- FanTalk 목록 item의 `creatorReplies`에 답변이 있으면 두 번째 POST를 UI에서 차단한다. 답변 수정·전체 결과 filter·직접 또는 동시 중복 요청 거부는 외부 계약이 제공된 뒤 수용 기준을 활성화한다.
- 댓글 계약이 제공된 뒤 댓글은 2단계를 넘지 않고 작성자에 따른 수정·삭제 권한이 구분된다.
- 모바일에서 조회·오디오 재생과 FanTalk 답변 작성이 가능하다. 댓글 관리와 FanTalk 답변 수정은 각 외부 계약 제공 후 같은 capability로 활성화한다.
- 시리즈 장르 목록을 query/body 없이 조회하고 선택한 `SeriesGenreItem.id`를 create/update의 `genreId`로 보내며, 상세의 `genreId`·요일 enum·state enum으로 수정 form을 초기화한다.
- 커뮤니티 목록은 `timezone` 없이 `page`, `size`를 보내고 서버의 `totalCount`, `page`, `size`, `hasNext`, `items`를 사용한다.
- FanTalk 목록 item의 `creatorReplies`가 비어 있으면 답변 작성, 비어 있지 않으면 답변 수정 UI를 제공한다. 수정 path의 `replyId`에는 첫 답변의 `fanTalkId`를 사용하고 client의 두 번째 POST를 차단한다. 실제 server에서는 동일 root에 대한 동시 POST 후 재조회해도 활성 creator reply가 하나만 존재해야 하며, 정확한 충돌 status/message key를 client에서 분기하지 않는다.
- 팬 작성 FanTalk 원글 soft delete가 성공하면 목록을 재조회하고 열린 Sheet를 닫는다. 연결된 creator reply가 함께 삭제됐다고 가정하지 않는다.
- 댓글은 루트와 직접 답글의 2단계를 넘지 않는다. `writerId === creatorId`인 댓글에만 수정 UI를 제공하고, soft delete는 작성자와 관계없이 해당 row에 제공한다.
- 모바일에서 조회·오디오 재생, 댓글 전체 관리, FanTalk 답변 작성·수정과 팬 원글 soft delete가 가능하다.
- `npm run dev:mock`에서 실제 backend 요청 없이 제공 계약 범위의 최종 UI happy path를 확인할 수 있고 mock mode 안내가 표시된다.
- 기본 `npm run dev`에서는 실제 개발 API를 사용하며 404·network error가 mock 응답으로 바뀌지 않는다.
- production build에는 browser mock이 활성화되지 않고 mock mode 설정을 허용하지 않는다.
@@ -848,7 +872,7 @@ OpenAPI로 전환할 때 반드시 반영할 차이다. 제품 정책이 OpenAPI
| ID | 상태 | 결정 필요 사항 | 현재 권고 |
|---|---|---|---|
| OQ-009 | 확정 | 각 페이지의 문자열 최대 길이와 배열 최대 개수 | 초기 UI를 구현한 뒤 실제 페이지에서 문자열 입력 공간과 반복 항목 사용성을 검토해 최대 길이·최대 개수의 권고값을 정한다. backend 호환 확인 후 PRD·OpenAPI 계약·schema·경계값 test를 같은 변경에서 갱신한다. 그전에는 계약에 없는 임의의 최대값을 추가하지 않는다. |
| OQ-010 | 미결 | 감사 로그 UI 제공 여부 | backend 기록 우선, 조회 UI는 후속 범위 |
| OQ-010 | 제외 | 감사 로그 UI 제공 여부 | 현재 릴리스에서는 조회 UI를 만들지 않고 backend 기록을 우선한다. 포함 시 backend 조회 계약을 포함한 별도 Phase로 계획한다. |
## 16. 결정 기록
@@ -890,7 +914,17 @@ OpenAPI로 전환할 때 반드시 반영할 차이다. 제품 정책이 OpenAPI
| 2026-07-27 | backend endpoint 구현 전에도 제공된 API Contract 범위의 최종 UI를 확인할 수 있도록 명시적 개발 전용 browser MSW mode를 제공한다. 실제 404 자동 fallback은 금지하고 mock UI 완료와 실제 server 연동 완료를 분리한다. |
| 2026-07-28 | 삭제된 `api-contract.md`를 `api-contract.openapi.json`으로 대체하고, endpoint·query·multipart·request/response·오류는 OpenAPI를 단일 진실 원천으로 사용한다. OpenAPI에 없는 제품·UI 정책만 PRD가 소유한다. |
| 2026-07-28 | 새 OpenAPI에 맞춰 Character 생성 image/systemPrompt 필수, Audio의 `search_word`·`contentFile`·`releaseDate`·테마 field, Series의 `keyword`·`contentIdList`·`ids`, Community의 `timezone`·`postImage`·`audioUrl`, FanTalk 목록 GET을 구현 기준으로 정정한다. |
| 2026-07-28 | OpenAPI에 없는 인증 정식 명세, 원작·장르 lookup, Series 수정 form의 edit DTO, 목록 active-only 보장, FanTalk 상세·답변 수정·filter/sort·유일성 오류, 댓글 CRUD와 도메인별 오류 key는 외부 의존으로 관리하며 추정 구현하지 않는다. |
| 2026-07-28 | OpenAPI에 없는 인증 정식 명세, 원작·장르 lookup, 목록 active-only 보장, FanTalk 상세·답변 수정·filter/sort·유일성 오류, 댓글 CRUD와 도메인별 오류 key는 외부 의존으로 관리하며 추정 구현하지 않는다. Series 수정 form은 상세 응답이 list item과 같은 `genreId`, enum 요일 배열, enum state를 제공하면 별도 edit DTO 없이 초기화한다. |
| 2026-07-28 | `EXT-003`은 별도 backend 계약 항목에서 제외한다. 시리즈 상세 API가 `SeriesListItem`과 같은 수정용 원본값을 내려주고, 장르 API는 선택 option 목록 표시용으로 호출하는 방식으로 처리한다. |
| 2026-07-28 | OQ-009는 초기 UI를 먼저 구현하고 실제 페이지를 보며 문자열 최대 길이와 배열 최대 개수를 제안한 뒤 backend 호환을 확인해 확정하는 절차로 종결한다. 실제 최대값 확정 전에는 임의 상한을 추가하지 않는다. |
| 2026-07-28 | `EXT-006`에 현재 구현된 `POST /admin/member/login`과 `POST /member/logout`의 request·response·인증·client 처리 기준을 기록한다. 정식 OpenAPI 포함은 비차단 외부 의존이며 기존 인증 구현과 Phase 3~9 진행을 유지한다. |
| 2026-07-28 | Phase 3부터는 OpenAPI 제공 범위를 먼저 구현해 Phase 9 활성 범위 Gate까지 진행한다. 미제공 계약은 영향을 받는 기능만 후속 범위로 남기고, 계약 도착 후 별도 vertical slice와 관련 Phase Gate·Phase 9를 다시 실행한다. |
| 2026-07-28 | 감사 로그 조회 UI는 현재 릴리스에서 제외한다. backend 감사 기록을 우선하고, 조회 UI가 필요해지면 조회 endpoint·권한·필터 계약을 포함한 후속 Phase로 다시 계획한다. |
| 2026-07-29 | `EXT-010`은 해결로 정정한다. 이미지 비율·crop 결과는 backend가 검증하지 않고 client가 보장하며, 파일 용량·MIME 등 서버에서 확인 가능한 항목은 backend가 `FILE-001~015`와 동일하게 검증한다. |
| 2026-07-29 | OpenAPI 2.3.0에 추가된 원작 검색, 활성 장르 목록, Audio·Community 댓글, Community pagination, FanTalk 팬 원글 DELETE와 답변 PUT을 후속 구현 계약으로 채택한다. 목록 API는 서버가 `isActive=true` 항목만 반환하므로 client 활성 filter를 추가하지 않는다. |
| 2026-07-29 | 오디오 예약 공개는 Asia/Seoul 입력을 client에서 ISO-8601 UTC `Z`로 변환해 `releaseDate`에 보내고 `timezone` field/query를 제거한다. 즉시 공개는 `releaseDate=null`을 유지한다. |
| 2026-07-29 | FanTalk 답변 여부는 `creatorReplies`의 빈 배열 여부로 판단하고 수정 path의 `replyId`에는 `creatorReplies[].fanTalkId`를 사용한다. 댓글은 `writerId === creatorId`일 때 AI 캐릭터 작성으로 판단하며 팬 작성 FanTalk 원글 soft delete를 이번 후속 구현 범위에 포함한다. |
| 2026-07-29 | 백엔드에서 FanTalk 답변 수정 API가 이미 구현됐고 OpenAPI status만 누락됐음을 확인했다. 해당 operation을 `implemented`로 정정하고 Phase 10에서 mock/client뿐 아니라 실제 server integration까지 구현·검증한다. |
| 2026-07-29 | `EXT-009`의 가격 범위 `0..99999`를 Audio 생성·수정과 Community 생성 OpenAPI request schema, 요구사항, Phase 10 경계 test에 동일하게 적용한다. |
| 2026-07-29 | 현재 FanTalk UI는 목록 item 기반 Sheet와 backend 반환 순서만 사용하므로 별도 상세 GET·답변 상태 filter·sort query가 필요하지 않다고 확정했다. 중복 생성 전용 오류 key 분기도 제외하고 일반 오류 후 목록을 재조회한다. 답변 1개 불변식은 `FANTALK-003`의 backend 수용 기준으로 server integration에서 검증하므로 `EXT-004`를 해결로 종결한다. |
| 2026-07-31 | 사용자 직접 지시에 따라 로컬 자동 Gate와 지원 browser 범위는 데스크톱 Chrome·모바일 Chrome의 Chrome 2종으로 한정한다. Playwright는 Chromium/mobile Chrome project만 유지하고, 현재 제품 지원 대상이 아닌 WebKit·Mobile Safari 자동 실행과 수동 QA는 테스트 시간을 크게 늘리므로 현재 릴리스 범위에서 제외한다. |