docs(ai-character): Phase 1 검증 기록 정리

docs/20260725_AI캐릭터관리자웹/api-contract.md

@@ -12,6 +12,8 @@
 
 이 문서는 대화로 제공된 API Contract를 저장소에 영속적으로 보존하고 인터뷰에서 확정된 보정사항을 적용한 프론트엔드 기준 계약이다. 실제 백엔드 구현을 다른 저장소에서 추정하지 않는다. “백엔드 제공 대기”로 표시한 endpoint와 세부 규칙은 프론트엔드 Open Question이 아니며, 백엔드 계약이 제공되기 전에는 해당 network integration을 구현하지 않는다.
 
+goal 실행 시 계약 입력은 해당 Task의 `시작 조건`이 가리키는 이 문서 section을 사용한다. 제공 대기 계약을 추정해 goal을 완료하지 않으며, 계약이 새로 제공되거나 제외 결정이 나면 PRD 결정 기록 → 이 문서 → `plan-task.md` 순서로 갱신한다.
+
 ## 1. 공통 규칙
 
 ### 1.1 성공 응답
@@ -114,7 +116,7 @@ type SeriesPublishedDay =
 
 ### 2.1 이미지 업로드와 crop
 
-모든 image part의 원본 파일 크기는 최대 10MB다. 확장자 문자열만 신뢰하지 않고 실제 MIME을 함께 검증한다.
+모든 image part의 원본 파일 크기는 최대 `10,485,760 bytes`다. `10,485,760 bytes`는 허용하고 `10,485,761 bytes`부터 거부한다. 확장자 문자열만 신뢰하지 않고 실제 MIME을 함께 검증한다.
 
 | resource | 허용 확장자 | 허용 MIME | crop aspect ratio | 등록 결과 최대 가로 폭 | 결과 세로 |
 |---|---|---|---:|---:|---|
@@ -333,6 +335,28 @@ Content-Type: `multipart/form-data`
 
 ## 5. 오디오 콘텐츠
 
+### 5.0 오디오 콘텐츠 테마 목록
+
+`GET /api/v2/admin/ai-characters/audio-content-themes`
+
+- Query 없음
+- Request body 없음
+
+Response `data`:
+
+```json
+[
+  {
+    "themeId": 11,
+    "themeName": "ASMR",
+    "imageUrl": "https://cdn.example.com/audio-content-theme/asmr.png"
+  }
+]
+```
+
+- 오디오 콘텐츠 생성 UI는 이 목록에서 테마를 선택하게 하고, 선택한 `themeId`를 생성 request JSON에 포함한다.
+- 테마 목록은 선택 캐릭터 path를 포함하지 않는 공통 관리자 조회다.
+
 ### 5.1 목록·검색
 
 `GET /api/v2/admin/ai-characters/{characterId}/audio-contents?search=밤&status=OPEN&page=0&size=20`
@@ -418,6 +442,7 @@ Content-Type: `multipart/form-data`
 {
   title: string
   description: string
+  themeId: number
   price: number
   isAdult: boolean
   releaseDateUtc: string | null
@@ -426,6 +451,7 @@ Content-Type: `multipart/form-data`
 ```
 
 - `isActive`와 `status`를 보내지 않는다.
+- `themeId`는 필수이며 `GET /api/v2/admin/ai-characters/audio-content-themes` 응답에서 선택한 값이다.
 - 즉시 공개는 `releaseDateUtc=null`이다.
 - 예약 공개는 Asia/Seoul 미래 시각을 UTC `Z` 문자열로 변환해 보낸다.
 - Response `data`는 오디오 상세와 같다.