feat(cody): 실패·빈 상태 8종 통합 QA (cross-cutting) + VTON 비의존 검증

[thxforall]

목적

코디 재현 엔진 consumer MVP의 실패 상태 8종(wireframes.md §4)이 F2~F6 각 화면에 빠짐없이 구현되었는지 통합 검증하고, VTON 모듈과의 의존성이 없음을 smoke test로 확인한다. F2~F6는 각각 자신의 실패 상태를 소유(구현)하고, F8은 누락된 실패상태를 catch하는 cross-cutting QA 역할만 담당한다.

---

범위

통합 검증 대상 (wireframes.md §4 표)

#	실패 상태	주인공 화면	구현 담당	F8 검증
1	비패션·저해상도 이미지	① Upload	F2	① 에러 메시지 & 재업로드 동선
2	분석 confidence 낮음	② Analysis	F3	② confidence 배지 시각화 & 다른 사진 유도
3	예산 초과	④ Recommended	F5	④ 예산 ±1 단계 제안 + 근접 세트 노출
4	품절·사이즈 없음	④·⑤	F5·F6	④ auto-swap + 유사도% 재표기, ⑤ 다음 후보 제시
5	affiliate 미커버	④·⑤	F5·F6	④ 비제휴 참고표시, ⑤ 제휴 대체 우선 노출
6	"안 비슷함" 👎 피드백	④	F5	④ 좋아요/싫어요 수집 → 인-플레이스 재랭킹
7	빈 결과(0건)	④	F5	④ "조건 과협소" 안내 + ③ 완화 유도
8	미가입 + 저장 시도	⑤	F6	⑤ 가입 모달(gated). (+)Saved 관련 상태는 F9 소유(F8 범위 밖)

---

Acceptance Criteria

화면 경로·라우트 검증

• packages/web/app/cody/ 아래 5개 화면이 정확한 경로에만 존재:
  • ① app/cody/page.tsx (Upload)
  • ② app/cody/analysis/page.tsx
  • ③ app/cody/conditions/page.tsx
  • ④ app/cody/recommended/page.tsx
  • ⑤ app/cody/item/[skuHash]/page.tsx
  • (보조) app/cody/saved/page.tsx, app/cody/looks/[slug]/page.tsx 존재 확인
• 금지 경로 미존재 확인: /recreate, /request, /(request), /(consumer), /cody/screens, /cody/detail 등 절대 금지 경로 스캔 (grep으로 경로 미존재 확인)

단일 adapter 검증

• packages/web/lib/api/adapters/cody-match.ts 유일 존재 확인 (모든 타입 + entry function 포함)
• lib/api/adapters/cody-match-mock.ts 존재 (mock data)
• F3/F5/F6에서 다른 adapter 파일 생성 금지 (codyAnalysisAdapter.ts, recommended/adapter.ts, useCodyMatch.ts, CodyEngineAdapter 등 미존재)
• grep: import.*adapter.*from.*[cC]ody → F3/F5/F6 파일이 cody-match.ts만 import 확인

TS 타입 mirror 검증 (cody-match-stage2 §2.1·§2.2)

• CodyAnalysis 타입이 모든 필드 포함 (items[], style{mood[], season[], color_palette[], silhouette[]}, style_formula{must_keep[], replaceable[], core_combination, substitute_axis[]})
  • 주의: fit 필드 없음 (fit은 client-only), confidence 필드 없음 (분석품질은 FE mock state)
• CandidateSKU 타입이 stage2 §2.2 전 필드 포함 (sku_signature_hash, brand, product, color, category, price_krw, primary_image_url, product_url, source_domain, retailer_scope, confidence, reason, relaxation_level, image_verification)
  • 주의: affiliate_url은 catalog_items(§7.1) 소속, CandidateSKU 아님
• ShopperPreference 타입 (budget_krw, retailer_scope, country, gender, excluded_brands, preferred_retailers)
  • 주의: fit 필드 없음
• AnalysisQuality (FE-only): confidence 배지용, cody_analysis와 분리
• ClientOnlyFitPreference: 'over' | 'slim' | 'any' (ShopperPreference 아님, client-side only)

실패 상태 소유권 검증 (각 화면이 자기 것 구현)

• ① Upload (F2 담당):

  • 비패션·저해상도 감지 & 에러 메시지 "패션 코디 이미지를 올려주세요"
  • 재업로드 동선 ✓

• ② Analysis (F3 담당):

  • AnalysisQuality.confidence 배지 (수치 아님, 시각적 표시만) ✓
  • low-confidence 시 "다시 분석 / 다른 사진" 유도 ✓

• ④ Recommended (F5 담당) — 4가지:

  • 예산 초과: "예산 한 단계 위/아래?" 제안 + 가장 근접 세트 노출 ✓
  • 품절·사이즈 없음: 대체 아이템 auto-swap + "유사도 N%" 재표기 ✓
  • affiliate 미커버: 비제휴 참고표시, 제휴 대체 우선 노출 ✓
  • "안 비슷함" 👎: 좋아요/싫어요 수집 → 인-플레이스 재랭킹 ✓
  • 빈 결과(0건): "조건 과협소" 안내 + ③ 완화 유도 ✓

• ⑤ Item Detail (F6 담당):

  • 링크 끊김 감지 & 대체 후보 안내 ✓
  • 미가입 + 저장 시도 → 가입 모달 (gated) ✓

• (+) Saved / Shop-this-look (F9 담당):

  • empty 상태 → 추천 동선(①) 유도 ✓

VTON 비의존 smoke test

• app/cody/* 화면 파일들이 lib/components/vton, lib/stores/vtonStore, /api/v1/vton 에서 import 0건
  • grep: from.*[vV]ton|vtonStore|/api/v1/vton → app/cody 내 매치 0
• /cody 라우트의 smoke test (로드 + 기본 flow) 시 VTON modal/state 미의존 확인

스토어·컴포넌트 구조 검증

• packages/web/lib/stores/codyStore.ts 존재 (flow state 관리)
• packages/web/lib/components/cody/ 아래 화면별 컴포넌트들 (UploadScreen, AnalysisScreen 등)
• useImageUpload 재사용 금지 확인 (F2 새 codyStore + 새 upload hook만)

---

핵심 파일

대상	경로 (packages/web/)
① Upload	app/cody/page.tsx
② Analysis	app/cody/analysis/page.tsx
③ Conditions	app/cody/conditions/page.tsx
④ Recommended	app/cody/recommended/page.tsx
⑤ Item Detail	app/cody/item/[skuHash]/page.tsx
(+) Saved	app/cody/saved/page.tsx
(+) Shop-this-look	app/cody/looks/[slug]/page.tsx
flow store	lib/stores/codyStore.ts
단일 adapter (F1 전담)	lib/api/adapters/cody-match.ts
mock adapter	lib/api/adapters/cody-match-mock.ts
화면 컴포넌트	lib/components/cody/*

---

mock·real 경계 (contract 출처)

• cody_analysis: decoded-docs/Architecture/cody-match-stage2.md §2.1 (VLM 분석 결과 schema)
• CodyMatchResult: cody-match-stage2.md §2.2 (per-role 후보 SKU)
• ShopperPreference: cody-match-stage2.md §2.1 (유저 조건, fit 필드 없음)
• 4-tier preference_variant: cody-match-stage2.md — budget-100k / budget-500k / budget-1M / authentic
• CodyAnalysis에 fit 없음: mvp-scope §3, stage2 §2.1 (fit은 client-only ClientOnlyFitPreference)

---

의존성

• F2 (Upload): 비패션·저해상도 실패 상태
• F3 (Analysis): confidence 배지, low-confidence 처리
• F5 (Recommended): 4가지 실패 상태 (예산초과, 품절swap, affiliate, 👎, 빈결과)
• F6 (Item Detail): 링크 끊김, 미가입 저장

F7 (mock→real reconcile) 는 본 F8과 독립 — F7은 체크리스트만, 구현 아님.

---

제약·주의

경로 절대 규칙

• ✅ packages/web/app/cody/*
• ✅ packages/web/lib/components/cody/*
• ✅ packages/web/lib/stores/codyStore.ts
• ✅ packages/web/lib/api/adapters/cody-match.ts (유일)
• ❌ /recreate, app/request, app/(request), app/(consumer), /screens, /detail 등

타입 mirror 엄격

• fit 분리: ShopperPreference (X) → ClientOnlyFitPreference (O, client-side only)
• confidence 구분: AnalysisQuality (분석품질, FE mock) ≠ CandidateSKU.confidence (매칭점수, per-SKU)
• cody_analysis 에 confidence/fit 필드 없음 (stage2 §2.1 명시)
• core_combination / substitute_axis: optional 확장 (mvp-scope §3 예시와 다를 수 있음, F7 reconcile gap에 명시)

VTON 분리 (testable AC)

• repo에 lib/components/vton/VtonModal.tsx, /lab/vton, /api/v1/vton/* 존재 가능
• app/cody/ 는 vton 관련 import 0건이어야 함*
• /cody/* smoke test 가 VTON modal/state 미의존 확인

Upload 재사용 금지

• useImageUpload 재사용 ❌ (내부 requestStore + startDetection() → 옛 flow)
• F2는 DropZone + compressImage + uploadImage + 새 cody upload hook/store 만 사용

---

참조

• wireframes.md §4 — 8종 실패 상태 표 & UI 처치 & 복구 동선
• mvp-scope.md §2-3 — 5화면 spec & 스키마 (fit 필드 없음)
• cody-match-stage2.md §2.1-2.2 — CodyAnalysis / ShopperPreference / CandidateSKU 타입
• CONTEXT.md "Cody Recreation Engine" — 용어 정의 (Composition Variant vs Preference Variant, fit 분리, confidence 구분)
• user-scenarios.md §4 — 5종 실패 루프 원본 시나리오

---

참고

F8의 역할은 검증(QA)이지 구현이 아님. F2~F6이 각각:

• F2: ① 의 비패션/저해상도 실패 상태 구현
• F3: ② 의 low-confidence 실패 상태 구현
• F5: ④ 의 4가지 실패 상태 구현
• F6: ⑤ 의 실패 상태 구현 ((+)Saved 실패상태는 F9 소유, F8 범위 밖)

F8은 이 8가지가 모두 구현됐는지, 경로/타입/adapter가 spec을 어기지 않는지 통합 검증만 수행한다.