Story: 제안 적용 & 성과 추적 API

메타

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

---

사용자 스토리

As a 장사왕 시스템, I want AI 제안의 적용 여부와 이후 성과를 추적, So that 셀러 컨텍스트를 업데이트하고 개인화에 활용할 수 있다.

---

수락 기준 (Acceptance Criteria)

AC-01: 제안 적용 기록

항목	내용
Given	AI 진단 제안이 업무노트에 기록됨
When	셀러가 [적용했어요] 클릭
Then	제안 상태 "applied"로 업데이트, 적용일 기록

API 스펙:

POST /api/v1/ai-suggestions/:suggestionId/apply

Response:
{
  "suggestionId": "sug_001",
  "status": "applied",
  "appliedAt": "2026-01-27T10:00:00Z",
  "measurementScheduledAt": "2026-02-03T10:00:00Z"  // 7일 후
}

AC-02: 제안 거절/무시 기록

항목	내용
Given	AI 진단 제안
When	셀러가 [맞지 않아요] 클릭 또는 무시
Then	제안 상태 "rejected" 또는 "ignored"로 기록

API 스펙:

POST /api/v1/ai-suggestions/:suggestionId/reject
Body: { "reason": "optional feedback" }

// 무시는 별도 API 없이, 일정 기간 후 자동 "ignored" 처리

AC-03: 성과 자동 측정 (7일 후)

항목	내용
Given	[적용했어요] 후 7일 경과
When	스케줄러 실행
Then	적용 전후 성과 비교 → outcome 기록

측정 항목:

interface SuggestionOutcome {
  measuredAt: Date;
  roasBefore: number;      // 적용 전 7일 평균
  roasAfter: number;       // 적용 후 7일 평균
  profitBefore: number;
  profitAfter: number;
  profitDelta: number;     // 순이익 변화량
  verdict: "positive" | "neutral" | "negative";
}

판정 로직:

if (roasAfter > roasBefore * 1.1 AND profitDelta > 0) → "positive"
else if (profitDelta < profitBefore * -0.1) → "negative"
else → "neutral"

AC-04: 셀러 컨텍스트 업데이트

항목	내용
Given	성과 측정 완료
When	outcome 기록
Then	셀러 컨텍스트의 patterns 업데이트

업데이트 항목:

• applyRate: 전체 적용률 재계산
• positiveOutcomeRate: 긍정 성과율 재계산
• preferredActions: 적용+긍정 많은 액션 타입
• avoidedActions: 거절 많은 액션 타입

---

태스크 분해

Task 1: 제안 저장 스키마 AC-01 AC-02

• [ ] 1.1: AISuggestion 테이블 생성
• [ ] 1.2: 제안 생성 시 저장 로직 (진단 API 연동)

Task 2: 적용/거절 API AC-01 AC-02

• [ ] 2.1: POST /ai-suggestions/:id/apply 엔드포인트
• [ ] 2.2: POST /ai-suggestions/:id/reject 엔드포인트
• [ ] 2.3: 상태 업데이트 로직

Task 3: 성과 측정 스케줄러 AC-03

• [ ] 3.1: 측정 대상 조회 (적용 후 7일 경과)
• [ ] 3.2: 성과 데이터 조회 (ROAS, 순이익)
• [ ] 3.3: 판정 로직
• [ ] 3.4: outcome 저장

Task 4: 컨텍스트 업데이트 AC-04

• [ ] 4.1: SellerAIContext 테이블/모델 생성
• [ ] 4.2: patterns 계산 로직
• [ ] 4.3: 업데이트 트리거

Task 5: 테스트

• [ ] 5.1: 적용/거절 API 테스트
• [ ] 5.2: 성과 측정 로직 테스트
• [ ] 5.3: 컨텍스트 업데이트 테스트

---

Dev Notes (AI Agent 최적화)

영향 받는 소스 트리

src/
├── ai/
│   ├── suggestions/
│   │   ├── suggestion.controller.ts   # 🆕 적용/거절 API
│   │   ├── suggestion.service.ts      # 🆕 제안 관리
│   │   └── suggestion.entity.ts       # 🆕 엔티티
│   ├── context/
│   │   ├── seller-context.service.ts  # 🆕 컨텍스트 관리
│   │   └── seller-context.entity.ts   # 🆕 엔티티
│   └── jobs/
│       └── measure-outcome.job.ts     # 🆕 성과 측정 스케줄러
└── tests/
    └── ai/
        └── suggestions.spec.ts        # 🆕 테스트

테이블 스키마

-- AI 제안 테이블
CREATE TABLE AISuggestion (
  id VARCHAR(50) PRIMARY KEY,
  vendorId VARCHAR(50) NOT NULL,
  campaignId VARCHAR(50) NOT NULL,
  suggestionType VARCHAR(50) NOT NULL,
  suggestionAction TEXT NOT NULL,
  expectedEffect TEXT,

  status ENUM('pending', 'applied', 'rejected', 'ignored') DEFAULT 'pending',
  appliedAt TIMESTAMP NULL,
  rejectedAt TIMESTAMP NULL,
  rejectReason TEXT NULL,

  -- 성과 측정
  outcomeMeasuredAt TIMESTAMP NULL,
  roasBefore DECIMAL(10,2) NULL,
  roasAfter DECIMAL(10,2) NULL,
  profitBefore DECIMAL(15,2) NULL,
  profitAfter DECIMAL(15,2) NULL,
  profitDelta DECIMAL(15,2) NULL,
  outcomeVerdict ENUM('positive', 'neutral', 'negative') NULL,

  createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

  INDEX idx_vendor (vendorId),
  INDEX idx_status_created (status, createdAt),
  INDEX idx_measure_pending (status, appliedAt)  -- 측정 대상 조회용
);

-- 셀러 AI 컨텍스트 테이블
CREATE TABLE SellerAIContext (
  vendorId VARCHAR(50) PRIMARY KEY,

  -- 패턴 (JSON)
  applyRate DECIMAL(5,4) DEFAULT 0,
  positiveOutcomeRate DECIMAL(5,4) DEFAULT 0,
  preferredActions JSON,  -- ["bid_adjust", "budget_realloc"]
  avoidedActions JSON,    -- ["campaign_pause"]

  -- 세그먼트 (추론)
  riskTolerance ENUM('conservative', 'moderate', 'aggressive') NULL,
  responsiveness ENUM('low', 'medium', 'high') NULL,

  totalSuggestions INT DEFAULT 0,
  totalApplied INT DEFAULT 0,
  totalPositive INT DEFAULT 0,

  updatedAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

충돌 감지

항목	상태	설명
기존 코드 충돌	✅ 없음	신규 모듈
DB 스키마 변경	🟡 추가	2개 테이블 생성 필요

---

의존성

의존	설명	상태
E-04-S-02	AI 진단 API (제안 생성 시점)	선행 필요
S52 E-11	업무노트 (적용/거절 버튼 트리거)	병행

---

Dev Agent Record

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

---

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

---

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