feat(cody): ② Analysis 화면 (cody_analysis mock + style_formula UI)

[thxforall]

목적

코디 재현 엔진의 분석 단계(P2·P3)를 시각화하는 화면 구현. 업로드된 코디 이미지의 VLM 분석 결과(아이템 분해, 스타일 공식)를 유저에게 명확히 제시하고, 분석 품질 평가(AnalysisQuality) 를 badge로 표시하여 낮은 신뢰도 시 재분석 유도. 유저가 공식에 동의하면 ③ Conditions로 진행하거나, 거절하면 ① Upload로 복귀.

범위

• 화면: packages/web/app/cody/analysis/page.tsx
• 컴포넌트: lib/components/cody/* (분해 아이템 카드, 스타일 공식 UI, AnalysisQuality 배지)
• 상태 관리: codyStore.ts 에서 F1이 저장한 cody_analysis 데이터 읽기 (+ 분석 진행 중 상태)
• mock 데이터: cody_analysis 의 full schema (style.mood·season·color_palette·silhouette, style_formula 전체) → real analyze_image 는 F1에서 호출하며, 여기서는 mock 보강 적용
• API: F1 adapter (lib/api/adapters/cody-match.ts) import only — entry fn 호출 아님 (F1이 미리 codyStore에 넣은 결과만 사용)

화면 명세

레이아웃 (wireframes §2 ② 기준)

┌────────────────────────────┐
│ ← Upload     confidence ●●●○│  ← AnalysisQuality 배지 (low/mid/high/excellent)
│                            │
│ ┌──────┐  무드: 모던 가을    │
│ │ 원본  │  미니멀            │
│ │ 썸네일 │  시즌: 가을        │
│ └──────┘  컬러: ▪ ▪ ▪      │
│                            │
│ 분해된 아이템        ▸ 스크롤 │
│ [블레이저][미디스커트][로퍼]▸ │
│ ────────────────────────── │
│ 스타일 공식                  │
│  must-keep  ☑ 블레이저 실루엣 │
│             ☑ 뉴트럴 톤       │
│  replaceable · 브랜드 · 소재   │
│                            │
│ [ 조건 설정하고 추천받기 → ③ ]│
│ [ 다른 사진으로 다시 → ① ]    │
└────────────────────────────┘

컴포넌트 상세

요소	데이터 소스	설명
원본 썸네일	codyStore.analysisImageUrl	F1에서 업로드한 원본 이미지
AnalysisQuality 배지	FE mock state (●●●○ 레벨)	분석 신뢰도를 4단계 시각 표기. 수치 아님 — confidence % 아님
무드/시즌/컬러/실루엣	cody_analysis.style.*	리스트 태그 형태로 표시
아이템 카드 (가로 스크롤)	cody_analysis.items[]	각 item: category·color·fit·role. 카드 hover 시 확대
must-keep (체크)	style_formula.must_keep[]	보존해야 할 정체성 요소 (문자열 리스트)
replaceable (읽기)	style_formula.replaceable[]	대체 가능한 축 (문자열 리스트)
[조건 설정하고 추천받기]	→ app/cody/conditions	③으로 이동
[다른 사진으로 다시]	→ app/cody	① Upload로 복귀 (codyStore 리셋)

상태 & 로딩

• loading (5~15초): skeleton + "AI가 룩을 분해하는 중 ⟳"
• low-confidence 실패 상태: badge 낮게(●○○○) + "분석 신뢰도가 낮습니다. 다른 사진을 올려주세요." + [다시 분석] 유도 → ① 복귀
• 정상: 아이템·공식 전체 표시 + CTA 활성화
• 비로그인: 가능 (단, 저장 CTA 없음)

Acceptance Criteria

• packages/web/app/cody/analysis/page.tsx 생성 및 라우팅 동작 (← Upload에서 이동 시 codyStore.cody_analysis 존재 확인)
• cody_analysis 전체 필드 표시: style.mood/season/color_palette/silhouette, items[], style_formula.must_keep/replaceable 모두 UI 반영
• AnalysisQuality 배지 (FE mock state): 4단계 레벨(low/mid/high/excellent) 시각 표기 (●●○○ 스타일). 명시: confidence %가 아니며, cody_analysis 객체에 없는 필드 (FE 전용 상태)
• 아이템 카드 수평 스크롤 컴포넌트: cody_analysis.items[] 리스트 → 각 카드 (category/color/fit/role 표시)
• 스타일 공식 UI: must_keep[] (체크마크 + 텍스트) / replaceable[] (읽기 텍스트) 구분 표현
• low-confidence 실패 상태 소유: confidence 임계 미만 시 badge 낮게 + "다시 분석/다른 사진" 재진입 경로 제공 (→ ① Upload)
• 로딩 상태: skeleton + "AI가 룩을 분해하는 중" + 5~15초 대기 메시지
• 네비게이션: [조건 설정하고 추천받기] → app/cody/conditions (codyStore state pass) / [다른 사진으로 다시] → app/cody (codyStore reset)
• 비로그인 접근 가능 (저장 기능은 ⑤에서 gated)
• (선택) core_combination / substitute_axis 필드 표시 (cody-match-stage2 §2.1의 optional 확장; 없으면 F7 reconcile gap 표기)

핵심 파일

경로	역할	소유
packages/web/app/cody/analysis/page.tsx	Analysis 화면 진입점	F3 (신규)
packages/web/lib/components/cody/AnalysisCard.tsx (예)	아이템 카드 컴포넌트	F3 (신규)
packages/web/lib/components/cody/StyleFormulaUI.tsx (예)	must-keep/replaceable 표시	F3 (신규)
packages/web/lib/components/cody/AnalysisQualityBadge.tsx (예)	confidence 배지 (FE mock)	F3 (신규)
packages/web/lib/stores/codyStore.ts	흐름 상태 관리 (F1 생성)	F1 (읽기)
packages/web/lib/api/adapters/cody-match.ts	단일 adapter (F1 생성, 타입 정의)	F1 (import만)

경로 준칙:

• ❌ 금지: app/cody/screens, app/cody/detail, app/(request), /recreate, codyAnalysisAdapter.ts, useCodyMatch.ts
• ✅ 허용: app/cody/analysis/page.tsx, lib/components/cody/*, lib/stores/codyStore.ts

mock·real 경계

Real (F1에서 호출, F3에서 사용)

• analyze_image(image_url, { subject?: string }) → { items, detected_text }
  • 출처: VLM 분석 (cody-match-stage2 Stage 1, mvp-scope §1 P2)
  • F1이 먼저 호출 후 codyStore.analysisItems 저장
  • F3는 읽기만

Mock 보강 (F3)

• style 필드: mood[], season[], color_palette[], silhouette[] (문자열 배열)

  • 실제로는 cody_analysis에서 오지만, F1 spike 중엔 mock 객체로 대체 가능
  • 출처: cody-match-stage2 §2.1 CodyAnalysis.style 정의 + mvp-scope §3 예시 schema

• style_formula 필드: must_keep[], replaceable[], optional core_combination, substitute_axis[]

  • 출처: cody-match-stage2 §2.1, mvp-scope §3 (예시)
  • 선택사항: core_combination, substitute_axis 는 stage2 §2.1 full 정의에 있으나, mvp-scope §3 예시엔 must_keep/replaceable 만. F3 AC는 필수 두 필드만 요구; 나머지는 F7 reconcile 체크리스트에 기록.

• AnalysisQuality (FE 전용): confidence level (low/mid/high/excellent) — mock state, backend cody_analysis 스키마에 없음

  • 단순 계산: codyStore.confidenceScore >= 0.8 → "excellent" 등 (FE 로직)
  • 명시: cody_analysis.confidence 필드는 존재하지 않음. CandidateSKU.confidence (stage2 §2.2, ④의 매칭점수)와 혼동 금지.

계약 출처

• cody-match-stage2 §2.1, §2.2: CodyAnalysis 타입 정의 (style, items, style_formula 전체 필드)
• mvp-scope §3: 스키마 예시 JSON + must_keep/replaceable 설명
• wireframes §2 ②: 화면 구성 + must-keep/replaceable 분리 표현
• CONTEXT.md Cody glossary: AnalysisQuality 정의 ("FE mock state", cody_analysis와 분리)

의존성

의존	이유	순서
F1 (Upload & codyStore 초기화)	codyStore.cody_analysis + analysisImageUrl 필수	F1 선행 필수
codyStore.ts	분석 결과 읽기 + low-confidence 상태 관리	F1이 제공
lib/api/adapters/cody-match.ts (F1 생성)	타입 import: CodyAnalysis, CandidateSKU 등	import만 (구현 아님)
라우팅 (app router)	/cody → /cody/analysis 진입	F1과 동시 가능

제약·주의

경로 엄격 준칙

• 신규 파일은 모두 packages/web/app/cody/ 또는 packages/web/lib/ 내:
  • app/cody/analysis/page.tsx (진입점)
  • lib/components/cody/* (UI 컴포넌트)
  • lib/stores/codyStore.ts (F1 생성)
• 금지 경로: /recreate, app/cody/screens, app/cody/detail, app/(request), codyAnalysisAdapter.ts, useCodyMatch.ts

단일 adapter seam

• lib/api/adapters/cody-match.ts 는 F1이 유일하게 생성
• F3는 이 파일에서 import only — new adapter/hook 파일 절대 금지
• 타입: CodyAnalysis, CandidateSKU, ShopperPreference 등을 adapter에서 가져가기

AnalysisQuality ≠ confidence

• AnalysisQuality (FE mock): 배지 레벨 (●●○○ 형태), 분석 신뢰도를 주관적으로 표시
• confidence (backend): 두 곳 존재하고 혼동 금지
  • cody_analysis 스키마엔 confidence 필드 없음 (mvp-scope §3, cody-match-stage2 §2.1 확인)
  • CandidateSKU.confidence (stage2 §2.2)는 ④·⑤에서만 쓰는 매칭점수
• 저 신뢰도 처리: 배지를 낮게 표시 + 재분석 유도 (F3 실패상태 소유)

fit 분리

• F3 범위 아님: fit ("over"|"slim"|"any") 은 ③ Conditions (F4)의 client-side-only 필터
• ShopperPreference (backend, cody-match-stage2 §2.1) 엔 fit 필드 없음
• F3는 cody_analysis.items[].fit (아이템 핏 설명)만 표시

VTON 무관

• lib/components/vton, lib/stores/vtonStore, /api/v1/vton 에서 import 0건
• ① Upload도 동일 — 기존 useImageUpload (requestStore + detection flow 트리거) 재사용 금지 → F1이 새 hook/store 제공

실패상태 전담

• F3는 low-confidence 실패상태를 완전히 소유:
  • badge 낮게 + "분석 신뢰도 낮음" 메시지 + [다시 분석/다른 사진] 복귀 경로
  • F8은 이 상태가 F2~F6 모두에서 coverage 됐는지만 검증 (구현 아님)

페르소나 (구현 AC 제외)

• Primary=가설(raf/6-11) — wireframes §0 주석 참조
• 골격(파이프라인·entry·실패)은 페르소나 무관 안정
• geo-wedge ICP(동남아+일본 K-pop/J-pop)는 docs(product): sync cody-engine direction from seed deck v0.3 #617 디자인 반영, 코드 스펙엔 제외

참조

문서	섹션	용도
wireframes.md	§2 ②	화면 레이아웃·컴포넌트·상태 명세
mvp-scope.md	§3	cody_analysis 스키마 + must-keep/replaceable 설명
user-scenarios.md	§2·§4	P2·P3 워크플로우 + low-confidence 실패 루프
cody-match-stage2.md	§2.1·§2.2	CodyAnalysis/CandidateSKU 타입 정의 + style_formula 전체
CONTEXT.md	Cody 섹션	AnalysisQuality 정의, Style Formula, Composition/Preference Variant 용어

---

관련 이슈:

• F1 — Upload & codyStore (선행)
• F2 — 실패: 비패션·저해상도 (Upload 화면 소유)
• ③ Conditions (F4) — 조건 설정 (다음 단계)
• ④ Recommended (F5) — 추천 룩 (최종)
• F8 — 통합 QA: 8종 실패상태(① nonFashion·② low-confidence·④ budgetExceeded/emptyResult/outOfStock·⑤ linkBroken·Saved unregistered) 전부 커버 검증