docs(ai-character): Mock Preview 계획 추가

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

@@ -86,6 +86,7 @@ AI 캐릭터를 생성하고, AI 캐릭터가 사람 크리에이터처럼 콘
 - 정식 WCAG 2.2 AA 인증 또는 외부 접근성 감사
 - 백엔드가 담당할 creator 생성·프로필 동기화의 조건부 정책 변경
 - 비활성 ID에 대한 상세 GET 반환 여부와 오류 status 등 백엔드 조회 정책 결정
+- 실제 API의 404를 감지해 mock 응답으로 자동 전환하는 production fallback
 
 ## 5. Target Users
 
@@ -333,6 +334,20 @@ AI 캐릭터를 생성하고, AI 캐릭터가 사람 크리에이터처럼 콘
 | FILE-014 | 확정 | 커뮤니티 GIF의 원본 가로가 800px을 초과하면 등록을 거부한다. client에서 제출 전에 차단하고 server도 같은 제한을 검증한다. GIF를 축소·crop·재인코딩하지 않는다. |
 | FILE-015 | 확정 | Series crop 결과의 세로 pixel은 `round(width × 297 ÷ 210)`으로 계산한다. 최대 폭에서는 1,000×1,414px이며 비율 검증은 계산된 세로값 기준 1px 이내 오차를 허용한다. |
 
+### 8.9 개발 전용 Mock Preview
+
+| ID | 상태 | 요구사항 |
+|---|---|---|
+| MOCK-001 | 확정 | 개발 환경은 명시적인 `server`와 `mock` API mode를 제공한다. 기본 `npm run dev`는 실제 개발 API를 사용하고 `npm run dev:mock`만 browser MSW를 활성화한다. |
+| MOCK-002 | 확정 | mock mode도 production과 같은 Page, Query, API client, endpoint path, request serializer와 response DTO를 사용한다. 별도 화면이나 mock 전용 API adapter를 만들지 않는다. |
+| MOCK-003 | 확정 | 실제 API의 404·network error를 감지해 mock으로 자동 fallback하지 않는다. `server` mode의 오류는 실제 오류 UI로 처리한다. |
+| MOCK-004 | 확정 | production build에서는 mock mode를 거부하고 browser worker·fixture가 활성화되지 않는다. |
+| MOCK-005 | 확정 | 계약이 제공됐지만 backend endpoint가 아직 구현되지 않은 기능은 정규화 API Contract 기반 fixture와 browser handler로 최종 UI의 happy path를 확인할 수 있다. |
+| MOCK-006 | 확정 | endpoint·DTO·오류 계약 자체가 미제공인 기능은 fixture를 추정하지 않는다. 계약과 무관한 shell·상태 inventory만 구현하고 최종 network UI 완료를 주장하지 않는다. |
+| MOCK-007 | 확정 | 각 도메인 mock은 deterministic seed와 새로고침 시 초기화되는 in-memory store를 사용해 목록·상세·생성·수정·soft delete의 연결된 흐름을 재현한다. |
+| MOCK-008 | 확정 | mock mode 화면에는 실제 서버가 아니라는 지속적으로 보이는 안내를 제공하고, JWT·password·signed URL·업로드 파일 본문을 log나 영구 저장소에 기록하지 않는다. |
+| MOCK-009 | 확정 | 도메인 완료 상태는 `UI 확인 완료(mock)`와 `실제 서버 연동 완료(server)`를 분리한다. mock Gate만 통과한 경우 Phase 전체와 network integration을 완료로 표시하지 않는다. |
+
 “가로 800/1,000”은 이 문서에서 등록 결과의 **최대 출력 폭**으로 해석한다. JPEG/PNG crop 결과에는 이 제한을 적용하되 선택한 원본 crop 영역이 더 작으면 확대하지 않는다. 커뮤니티 GIF는 원본 가로가 800px 이하일 때만 등록할 수 있다.
 
 #### Image crop UI 흐름
@@ -678,6 +693,8 @@ Phase 2~6에서 추가되는 오류는 구현 전에 정확한 비2xx status와
 - 목록 검색 debounce 시간은 구현 시 300ms 전후로 일관되게 적용한다.
 - 날짜, 가격, 상태 label은 중앙 formatter로 일관되게 표시한다.
 - 브라우저 지원 범위는 데스크톱 Chrome/Edge/Safari 최신 2개 주요 버전과 모바일 Chrome/Safari 최신 2개 주요 버전이다.
+- mock/server mode는 build-time 환경 설정으로 명시적으로 선택하며 runtime 404 fallback을 사용하지 않는다.
+- domain fixture와 browser handler는 `api-contract.md`의 제공 계약에서 파생하고 contract test와 함께 변경한다.
 
 ## 14. 성공 기준
 
@@ -714,6 +731,10 @@ Phase 2~6에서 추가되는 오류는 구현 전에 정확한 비2xx status와
 - FanTalk 답변이 있으면 두 번째 POST가 UI에서 차단되고 수정 동작만 제공되며, 직접·동시 요청도 백엔드가 원자적으로 거부한다.
 - 댓글은 2단계를 넘지 않고 작성자에 따른 수정·삭제 권한이 구분된다.
 - 모바일에서 조회·오디오 재생·댓글 관리·FanTalk 답변 작성/수정이 가능하다.
+- `npm run dev:mock`에서 실제 backend 요청 없이 제공 계약 범위의 최종 UI happy path를 확인할 수 있고 mock mode 안내가 표시된다.
+- 기본 `npm run dev`에서는 실제 개발 API를 사용하며 404·network error가 mock 응답으로 바뀌지 않는다.
+- production build에는 browser mock이 활성화되지 않고 mock mode 설정을 허용하지 않는다.
+- 각 도메인의 Progress와 Phase Gate는 `UI 확인 완료(mock)`와 `실제 서버 연동 완료(server)` 증거를 별도로 기록한다.
 
 ### 14.2 UI/UX 수용 기준
 
@@ -773,3 +794,4 @@ Phase 2~6에서 추가되는 오류는 구현 전에 정확한 비2xx status와
 | 2026-07-26 | 문자열 최대 길이와 배열 최대 개수는 초기 UI 작성 후 각 페이지에서 권고값을 정하고 백엔드 호환 확인 후 확정한다. 그 전에는 제공 계약에 없는 최대값을 추정하지 않는다. |
 | 2026-07-26 | 댓글 API·팬 댓글 삭제 권한 오류와 FanTalk 목록·상세·답변 수정·중복 답변 계약은 백엔드 제공 대기 사항으로 분류하고 프론트엔드 Open Questions에서 제외한다. |
 | 2026-07-27 | 오디오 콘텐츠 생성에는 `themeId`가 필수이며, 테마 선택지는 `GET /api/v2/admin/ai-characters/audio-content-themes`에서 query/body 없이 조회한다. |
+| 2026-07-27 | backend endpoint 구현 전에도 제공된 API Contract 범위의 최종 UI를 확인할 수 있도록 명시적 개발 전용 browser MSW mode를 제공한다. 실제 404 자동 fallback은 금지하고 mock UI 완료와 실제 server 연동 완료를 분리한다. |