Story: Surface Layer AI 진단 UI

메타

항목	값
Story ID	E-04-S-05
Epic	E-04 AI 진단 엔진
상태	draft
우선순위	P0
규모	M
담당 개발자	FE (수민님)

---

사용자 스토리

As a Pro10+ 셀러, I want Surface Layer에서 AI 진단 결과를 확인, So that 복잡한 광고 상황을 쉽게 이해하고 다음 행동을 알 수 있다.

---

수락 기준 (Acceptance Criteria)

AC-01: AI 진단 카드 표시 (Pro10+)

항목	내용
Given	Pro10+ 셀러가 Surface Layer 진입
When	페이지 로드
Then	AI 진단 카드 표시 (Badge + 진단 + 제안)

UI 요소:

┌────────────────────────────────────────┐
│ 🟡 주의가 필요합니다           🤖 Beta │
│                                        │
│ 최근 7일간 ROAS가 180% → 150%로        │
│ 하락했어요. 비검색 광고비가 65%를       │
│ 차지하고 있어서, 입찰가를 15% 낮추면    │
│ 순이익이 개선될 수 있어요.              │
│                                        │
│ 💡 제안: 비검색 입찰가 15% 인하         │
│    예상 효과: 순이익 +12%               │
│                                        │
│        [업무노트에서 확인하기]          │
└────────────────────────────────────────┘

상세 스펙:

• 🤖 Beta 라벨: 우상단에 표시
• Badge: 🟢/🟡/🔴 + 한 줄 요약
• 진단: 2-3문장, 맥락 설명
• 제안: 구체적 액션 + 예상 효과 (있을 경우)
• CTA: "업무노트에서 확인하기" → 업무노트로 이동

AC-02: 규칙 기반 카드 + 업그레이드 유도 (Basic/Pro)

항목	내용
Given	Basic/Pro 셀러가 Surface Layer 진입
When	페이지 로드
Then	규칙 기반 카드 + AI 업그레이드 배너

UI 요소:

┌────────────────────────────────────────┐
│ 🟡 ROAS 150% - 효율 개선이 필요해요     │
│                                        │
│ ┌────────────────────────────────────┐ │
│ │ 🔒 AI 진단으로 업그레이드            │ │
│ │    Pro10 이상에서 맞춤 분석 제공     │ │
│ │              [자세히 보기]          │ │
│ └────────────────────────────────────┘ │
└────────────────────────────────────────┘

AC-03: 로딩 상태

항목	내용
Given	AI 진단 API 호출 중 (캐시 미스)
When	응답 대기
Then	스켈레톤 로딩 + "AI가 분석 중..." 메시지

UI 요소:

┌────────────────────────────────────────┐
│ 🤖 AI가 분석 중...                      │
│                                        │
│ ████████████████████████               │
│ ██████████████                         │
│ ████████████████████                   │
└────────────────────────────────────────┘

AC-04: 에러/폴백 상태

항목	내용
Given	AI API 실패 → 규칙 기반 폴백
When	source: "rule" 응답
Then	규칙 기반 카드 표시 (Beta 라벨 없음)

---

태스크 분해

Task 1: AI 진단 카드 컴포넌트 AC-01

• [ ] 1.1: DiagnosisCard 컴포넌트 생성
• [ ] 1.2: Badge + 진단 텍스트 영역
• [ ] 1.3: 제안 영역 (suggestion 있을 때만)
• [ ] 1.4: Beta 라벨
• [ ] 1.5: CTA 버튼 (업무노트 이동)

Task 2: 업그레이드 배너 AC-02

• [ ] 2.1: UpgradeBanner 컴포넌트
• [ ] 2.2: aiDiagnosisEnabled 플래그 기반 조건부 렌더링
• [ ] 2.3: "자세히 보기" 링크 (요금제 페이지)

Task 3: 로딩 상태 AC-03

• [ ] 3.1: DiagnosisCardSkeleton 컴포넌트
• [ ] 3.2: 로딩 메시지

Task 4: API 연동

• [ ] 4.1: useDiagnosis 훅 생성
• [ ] 4.2: 캐시/에러 상태 처리
• [ ] 4.3: source 필드 기반 분기

Task 5: 마무리

• [ ] 5.1: 반응형 처리
• [ ] 5.2: PR 생성

---

Dev Notes (AI Agent 최적화)

영향 받는 소스 트리

src/
├── app/
│   └── dashboard/
│       └── ads/
│           └── components/
│               ├── DiagnosisCard.tsx        # 🆕 AI 진단 카드
│               ├── DiagnosisCardSkeleton.tsx # 🆕 로딩 상태
│               └── UpgradeBanner.tsx        # 🆕 업그레이드 유도
├── hooks/
│   └── useDiagnosis.ts                      # 🆕 진단 API 훅
└── types/
    └── diagnosis.ts                         # 🆕 타입 정의

컴포넌트 Props

interface DiagnosisCardProps {
  campaignId: string;
  badge: "🟢" | "🟡" | "🔴";
  diagnosis: string;
  suggestion?: {
    type: string;
    action: string;
    expectedEffect: string;
  };
  source: "ai" | "rule";
  suggestionId?: string;  // 업무노트 연동용
}

interface UpgradeBannerProps {
  currentPlan: string;
}

충돌 감지

항목	상태	설명
기존 코드 충돌	🟡 주의	Surface Layer 컴포넌트 수정/교체
스타일 충돌	🟡 확인필요	기존 카드 스타일과 일관성

---

의존성

의존	설명	상태
E-04-S-02	AI 진단 API	선행 필요
E-04-S-03	요금제 분기 (aiDiagnosisEnabled)	선행 필요

---

Dev Agent Record

항목	값
생성 Agent	Claude Opus 4.5
생성일	2026-01-27
마지막 수정	2026-01-27
검증자	-

---

검증 결과: 🔄 PENDING (PO 승인 대기) 검증일: -

---

생성일: 2026-01-27마지막 수정: 2026-01-27