테마
Story: 원가 히스토리 관리 모달 UI
메타
| 항목 | 값 |
|---|---|
| Story ID | E-03-S-04 |
| Epic | E-03 원가 히스토리 |
| 상태 | draft |
| 우선순위 | P0 |
| 규모 | L |
| 담당 개발자 | FE (수민님) |
사용자 스토리
As a 셀러, I want 원가 히스토리를 관리하는 모달 UI, So that 기간별 원가를 손쉽게 조회/추가/수정할 수 있다.
수락 기준 (Acceptance Criteria)
AC-01: 모달 기본 표시
| 항목 | 내용 |
|---|---|
| Given | 매입원가 테이블에서 히스토리 아이콘 클릭 |
| When | 모달 오픈 |
| Then | 상품명, 현재 원가, 원가 이력 목록 표시 |
UI 요소:
┌─────────────────────────────────────────────────────────────────────┐
│ 원가 관리 [X] │
│ 오뚜_그로스2 (8479697209) │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 현재 적용 원가: 25,800원 (2026-01-12 ~) │
│ │
│ ─── 원가 이력 ─── │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 적용 기간 │ 원가 │ │ │
│ ├────────────────────────┼───────────┼────────────────────────┤ │
│ │ 2026-01-12 ~ 현재 │ 25,800원 │ [수정] │ │
│ │ 2025-12-15 ~ 01-11 │ 14,520원 │ [수정] │ │
│ │ 2025-11-01 ~ 12-14 │ 12,000원 │ [수정] │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ─── 새 원가 추가 ─── │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 적용 시작일 [2026-01-27 📅] │ │
│ │ 원가 [28,000 ] 원 │ │
│ │ [추가하기] │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ℹ️ 해당 기간의 주문은 이 원가로 순이익이 계산됩니다 │
│ │
└─────────────────────────────────────────────────────────────────────┘AC-02: 원가 이력 목록 표시
| 항목 | 내용 |
|---|---|
| Given | 모달 오픈 |
| When | 원가 이력 데이터 로드 완료 |
| Then | 최신순으로 이력 목록 표시 (적용 기간, 원가, 수정 버튼) |
상세 스펙:
- 최신 이력 상단 표시 (역순)
- 현재 적용 중인 이력 강조 표시
- 적용 기간: "YYYY-MM-DD ~ MM-DD" 또는 "~ 현재"
AC-03: 새 원가 추가
| 항목 | 내용 |
|---|---|
| Given | 새 원가 폼 입력 (시작일, 원가) |
| When | [추가하기] 클릭 |
| Then | API 호출 → 성공 시 이력 목록 갱신 |
상세 스펙:
- 시작일: DatePicker, 기본값 오늘
- 원가: 숫자 입력, 양수 검증
- 로딩 상태 표시
- 성공/실패 토스트 메시지
AC-04: 기존 이력 수정
| 항목 | 내용 |
|---|---|
| Given | 이력 목록에서 [수정] 클릭 |
| When | 인라인 편집 모드 전환 |
| Then | 원가, 시작일, 종료일 수정 가능 |
UI 요소 (인라인 편집 모드):
│ │ [2025-12-15 📅] ~ [01-11 📅] │ [15,000 ] 원 │ [저장][취소] │ │상세 스펙:
- 현재 적용 중인 이력: 종료일 수정 불가 (~ 현재 고정)
- 수정 완료 시 인접 이력 기간 자동 조정 (API 응답 반영)
AC-05: 에러 처리 및 검증
| 항목 | 내용 |
|---|---|
| Given | 잘못된 입력 (음수, 기간 역전 등) |
| When | 저장 시도 |
| Then | 에러 메시지 표시, 저장 차단 |
검증 항목:
- 원가: 양수 필수
- 시작일: 종료일보다 이전
- 기간 중복: 경고 + 자동 조정 안내
태스크 분해
Task 1: 모달 기본 구조 AC-01
- [ ] 1.1: PurchaseHistoryModal 컴포넌트 생성
- [ ] 1.2: 상품 정보 헤더 영역
- [ ] 1.3: 현재 적용 원가 표시
Task 2: 원가 이력 목록 AC-02
- [ ] 2.1: 이력 테이블 컴포넌트
- [ ] 2.2: API 연동 (useQuery)
- [ ] 2.3: 로딩/빈 상태 처리
Task 3: 새 원가 추가 폼 AC-03
- [ ] 3.1: 시작일 DatePicker
- [ ] 3.2: 원가 입력 필드
- [ ] 3.3: 추가 API 연동 (useMutation)
- [ ] 3.4: 성공/실패 처리
Task 4: 기존 이력 수정 AC-04
- [ ] 4.1: 인라인 편집 모드 토글
- [ ] 4.2: 날짜/원가 편집 필드
- [ ] 4.3: 수정 API 연동
- [ ] 4.4: 낙관적 업데이트 또는 refetch
Task 5: 검증 및 에러 처리 AC-05
- [ ] 5.1: 입력 검증 로직 (Zod/Yup)
- [ ] 5.2: 에러 메시지 UI
- [ ] 5.3: 기간 중복 경고
Task 6: 마무리
- [ ] 6.1: 접근성 (키보드 네비게이션, aria)
- [ ] 6.2: PR 생성
Dev Notes (AI Agent 최적화)
영향 받는 소스 트리
src/
├── app/
│ └── dashboard/
│ └── purchase/
│ └── components/
│ └── PurchaseHistoryModal.tsx # 🆕 신규 생성
├── components/
│ └── ui/
│ └── DateRangePicker.tsx # 재사용 또는 신규
├── hooks/
│ └── usePurchaseHistory.ts # 🆕 신규 생성
└── types/
└── purchase.ts # 🔧 타입 추가사용 라이브러리 (기존 프로젝트 확인 필요)
- DatePicker: react-datepicker 또는 shadcn/ui
- Form 검증: react-hook-form + zod
- API: @tanstack/react-query
충돌 감지
| 항목 | 상태 | 설명 |
|---|---|---|
| 기존 코드 충돌 | ✅ 없음 | 신규 컴포넌트 |
| 스타일 충돌 | 🟡 확인필요 | 기존 모달 스타일과 일관성 |
의존성
| 의존 | 설명 | 상태 |
|---|---|---|
| E-03-S-03 | 원가 히스토리 CRUD API | 선행 필요 |
Dev Agent Record
| 항목 | 값 |
|---|---|
| 생성 Agent | Claude Opus 4.5 |
| 생성일 | 2026-01-27 |
| 마지막 수정 | 2026-01-27 |
| 검증자 | - |
검증 결과: 🔄 PENDING (PO 승인 대기) 검증일: -
생성일: 2026-01-27마지막 수정: 2026-01-27