전 저장소 리팩터링과 SSOT 정비

docs/ops/handoff-avatar-seoyeon-2026-06-27.md

@@ -3,20 +3,17 @@
 > 다른 세션에서 이어서 작업하기 위한 인계. imagegen(gpt-image-2)+BiRefNet+파츠 분리 리깅 파이프라인 전체를 여기서 참조.
 > 상세 원칙은 `AGENTS.md` §4.
 
-> 2026-06-27 19:45 추가: 사용자 제공 PSD `라투디 여캐_ver2.psd`를 기준으로 새 파츠 세트 `seoyeon-live2d-psd-v2`를 만들고 P1 실제 세션 기본값으로 연결했다. 이 세트는 컨셉 보드 크롭이 아니라 PSD 레이어 기반이며, `sad` 표정에서 울상 눈썹·우는 입·눈물 파츠를 별도로 합성한다. `p1-concept`는 기본값으로 쓰지 않는다.
+> **2026-07-13 상태 변경 — PAUSED:** 사용자 피드백에 따라 서연을 포함한 생성 이미지/PSD 래스터 파츠 리그는 실제 화면에서 전부 비활성화했다. 현재 `ClientAvatar`는 모든 페르소나에서 기존 SVG 도형 기반 파라미터 리그만 렌더링한다. 래스터 렌더러·원본·파츠 자산은 재검토 가능하도록 보존하지만 앱 배선에는 연결하지 않는다.
 
 ---
 
 ## 0. 한 줄 요약
-파이프라인·렌더러·dev 미리보기까지 **완성**됐으나, 서연 아트가 **잘못된 참조(Image #1=긴 머리)**로 만들어져, **진짜 목표 Image #2(짧은 갈색 보브, 정면)**로 **재생성**이 남았다.
+래스터 파츠 파이프라인은 보존 상태로 중단했고, 현재 제품과 dev 미리보기는 기존 SVG 도형 기반 파라미터 리그만 사용한다.
 
 ---
 
-## 1. ⚠️ 다음 세션이 가장 먼저 할 일 (핵심)
-1. **목표 재확인**: 진짜 타겟은 **Image #2** = `D:\workspace\GLM\.claude-glm\image-cache\73cbbea0-5c27-4ced-91db-16d7a8df602f\2.png`
-   (단일 캐릭터, **짧은 갈색 보브**, 정면 — 현재 서연의 긴 머리와 다름. 사용자가 "잉??" 한 원인).
-   - 비전(analyze_image) 도구가 다중 패널/캐릭터를 자주 혼동했으므로, **재생성 전 사용자에게 Image #2 해석(짧은 보브, 의상 색 등)을 한 번 확인**할 것.
-2. **Image #2를 `-i` 참조로 재생성**하면 gpt-image-2가 캐릭터를 그대로 따라함(텍스트 묘사 의존 X). 아트 디렉션은 2.png에 맡긴다.
+## 1. 재개 조건
+소유자가 래스터 아바타 재도입을 명시적으로 결정하기 전에는 Image #2 재생성, 파츠 보정, 앱 재연결을 진행하지 않는다. 재개 시에도 먼저 별도 미리보기에서 시각 수용 확인을 받아야 한다.
 
 ## 2. 완료된 것 (재사용 가능)
 - **이미지 생성**: `~/.codex/imagegen-headless/codex_imagegen.sh`(gpt-image-2, ChatGPT 구독). 검증 완료.
@@ -30,17 +27,16 @@
 - **렌더러**: `apps/web/src/components/avatar/RasterBust.tsx`
   - 파츠 분리: `base` + `upperface-<표정>`(눈썹+눈) + `eyelid-closed`(깜빡임, 1-blink) + `mouth-<표정>` + `mouth-open`(립싱크, RMS).
   - 28표정→클러스터 매핑(`VARIANT_FOR_EXPRESSION`) 내장.
-- **연결 배선**:
-  - `persona.ts`: `AvatarPersona.rasterArtSet?: string` 추가됨.
-  - `Session.tsx`: 현재 실제 세션 기본값은 `PERSONA_AVATAR_LOOKS.P1 = { rasterArtSet: "seoyeon-live2d-psd-v2", expressionBias: "sad", ... }` + avatar 객체에 `rasterArtSet` 전달.
-  - `ClientAvatar.tsx`: `useRaster` 분기(rasterArtSet 있으면 `RasterBust`, 없으면 기존 SVG). `data-render-mode` 속성 추가.
-  - `App.tsx`: `/dev/avatar-preview` 라우트(인증 없음).
-- **dev 미리보기**: `apps/web/src/pages/AvatarPreview.tsx` 기본값은 `seoyeon-live2d-psd-v2`. `?rig=psb`, `?rig=v3`, `?rig=safe`로 과거 세트 비교 가능.
+- **현재 연결 상태**:
+  - `persona.ts`: `AvatarPersona.rasterArtSet` 계약 제거.
+  - `Session.tsx`·`LearnerHome.tsx`: P1/P4~P7 래스터 아트셋 배선 제거.
+  - `ClientAvatar.tsx`: 항상 SVG 파라미터 리그 렌더, `data-render-mode="svg"` 고정.
+  - `App.tsx`: `/dev/avatar-preview`는 SVG 파라미터 리그 점검 페이지로 유지.
+- **dev 미리보기**: `apps/web/src/pages/AvatarPreview.tsx`는 서연 SVG 도형 리그의 대표 표정과 모션만 표시한다.
 - **스크린샷 도구**: `apps/web/scripts/avatar-shot.mjs` (`BASE_URL=http://localhost:<port> node ...`).
-- **현재 실제 세션 에셋**: `apps/web/public/avatar/seoyeon-live2d-psd-v2/parts/*.png`. 소스/재현 스크립트는 `docs/avatar-art/seoyeon/live2d-psd-v2/`.
-- **보존 에셋(Image #1=긴 머리 버전)**: `apps/web/public/avatar/seoyeon/{neutral,sad,tired,anxious,warm,startled,eyes-closed,speaking}.png` + `parts/`, `seoyeon-live2d-psb`. 비교용으로 남기되 P1 기본값은 새 PSD v2다.
+- **보존 에셋**: `apps/web/public/avatar/seoyeon-live2d-psd-v2/parts/*.png`, `apps/web/public/avatar/seoyeon/`, `seoyeon-live2d-psb`. 소스/재현 스크립트는 `docs/avatar-art/seoyeon/live2d-psd-v2/`. 현재 제품에서는 로드하지 않는다.
 
-## 3. 남은 작업 (순서대로)
+## 3. 보류된 작업 (래스터 재도입 결정 전 실행 금지)
 1. Image #2(2.png) 해석 사용자 확인 → ASCII 이름으로 복사: `cp "<2.png 경로>" docs/avatar-art/seoyeon/ref-image2.png`.
 2. **base 재생성**(검증용 1장):
    `codex_imagegen.sh --out base-v2.png --size 1024x1280 --quality high -i ref-image2.png "Use the supplied reference as the exact character. Same character, head-and-shoulders bust, perfectly front-facing, symmetrical, neutral calm expression, flat solid light gray #C9CDD2 background, no gradient/shadow/scenery, semi-realistic soft anime. No text/watermark/hands. Bangs above eyes."`
@@ -52,9 +48,9 @@
 ## 4. 환경 메모
 - **dev 서버**: 5173 단일 인스턴스로 띄움(백그라운드). 끊기면 `cd apps/web && npm run dev -- --port 5173 --strictPort`. (5173/5174 중복 인스턴스가 "깨진 화면" 원인이었음 — 항상 5173 단일로.)
 - codex CLI 0.142.2, auth_mode=chatgpt(구독). object-separation venv: `~/.venvs/object-separation` (CPU-only BiRefNet).
-- 서연=P1은 API 시드(`apps/api/app/services/persona.py`). 웹엔 P1이 `PERSONA_AVATAR_LOOKS`에 있고 현재 실제 세션 기본값은 rasterArtSet="seoyeon-live2d-psd-v2"다.
+- 서연=P1은 API 시드(`apps/api/app/services/persona.py`). 웹의 P1 외형/기본 정서값은 유지하지만 래스터 아트셋은 전달하지 않는다.
 
 ## 5. 미해결/결정 필요
 - Image #2 캐릭터의 **의상 색/추가 디테일** (비전 도구 불안정 → 사용자 확인 필요).
-- 파츠 분리 리깅 vs 통째 변주 크로스페이드 — 사용자가 "파츠 분리"를 원했으므로 현행(파츠 분리) 유지하되, 결과가 어색하면 통째 변주 방식(`RasterBust` 이전 버전, git 히스토리 참조)으로 롤백 검토.
+- 래스터 아바타 재도입 여부와 방식은 현재 보류다. 현행 제품 기준은 SVG 도형 기반 파라미터 리그다.
 - 실제 Live2D Cubism(.moc3) 도입 여부는 소유자 결정(편집기 저작 필요).