Story: 원가 히스토리 CRUD API

메타

항목	값
Story ID	E-03-S-03
Epic	E-03 원가 히스토리
상태	draft
우선순위	P0
규모	M
담당 개발자	BE (희선님)

---

사용자 스토리

As a 셀러, I want 원가 히스토리를 조회/추가/수정하는 API, So that 과거 원가 변동을 관리하고 정확한 순이익을 확인할 수 있다.

---

수락 기준 (Acceptance Criteria)

AC-01: 원가 히스토리 목록 조회

항목	내용
Given	셀러가 특정 상품 선택
When	원가 히스토리 조회 요청
Then	시간순 원가 이력 목록 반환

응답 필드:

{
  "productId": "8479697209",
  "productName": "오뚜_그로스2",
  "currentPrice": 25800,
  "currentStartDate": "2026-01-12",
  "history": [
    {
      "id": 78938,
      "purchasePrice": 25800,
      "startDate": "2026-01-12",
      "endDate": null,
      "isCurrent": true
    },
    {
      "id": 78936,
      "purchasePrice": 14520,
      "startDate": "2025-12-15",
      "endDate": "2026-01-11",
      "isCurrent": false
    }
  ]
}

AC-02: 원가 히스토리 추가

항목	내용
Given	셀러가 새 원가 정보 입력 (원가, 시작일)
When	원가 추가 요청
Then	새 원가 이력 생성, 이전 이력 종료일 자동 설정

요청 필드:

{
  "productId": "8479697209",
  "purchasePrice": 28000,
  "startDate": "2026-01-27"
}

상세 스펙:

• 시작일이 기존 이력과 겹치면 기존 이력 종료일 자동 조정
• Product.purchasePrice도 함께 업데이트 (최신 원가인 경우)

AC-03: 원가 히스토리 수정

항목	내용
Given	기존 원가 이력 선택
When	원가 또는 기간 수정 요청
Then	해당 이력 업데이트, 인접 이력 기간 자동 조정

요청 필드:

{
  "id": 78936,
  "purchasePrice": 15000,
  "startDate": "2025-12-10",
  "endDate": "2026-01-11"
}

AC-04: 테이블 직접 수정 (간편 모드)

항목	내용
Given	셀러가 매입원가 테이블에서 직접 원가 수정
When	원가 변경 저장
Then	오늘 날짜 기준 새 이력 생성

요청 필드:

{
  "productId": "8479697209",
  "purchasePrice": 26000
}

상세 스펙:

• startDate 미입력 시 오늘 날짜 자동 적용
• 기존 Product 원가 수정 API와 호환

---

태스크 분해

Task 1: 원가 히스토리 조회 API AC-01

• [ ] 1.1: GET /products/:productId/purchase-history 엔드포인트 생성
• [ ] 1.2: PurchasePrice 테이블 조회 + 기간 계산 로직
• [ ] 1.3: 현재 적용 원가 표시 로직

Task 2: 원가 히스토리 추가 API AC-02

• [ ] 2.1: POST /products/:productId/purchase-history 엔드포인트 생성
• [ ] 2.2: 기존 이력 종료일 자동 조정 로직
• [ ] 2.3: Product.purchasePrice 동기화

Task 3: 원가 히스토리 수정 API AC-03

• [ ] 3.1: PATCH /products/:productId/purchase-history/:id 엔드포인트 생성
• [ ] 3.2: 인접 이력 기간 자동 조정 로직
• [ ] 3.3: 검증 로직 (기간 중복, 유효성)

Task 4: 간편 수정 API 연동 AC-04

• [ ] 4.1: 기존 Product 원가 수정 API 확장
• [ ] 4.2: 자동 히스토리 생성 로직 추가

Task 5: 테스트 작성

• [ ] 5.1: 각 API 단위 테스트
• [ ] 5.2: 기간 조정 로직 테스트
• [ ] 5.3: 동시성 테스트

---

Dev Notes (AI Agent 최적화)

영향 받는 소스 트리

src/
├── products/
│   ├── products.controller.ts         # 🔧 수정 (엔드포인트 추가)
│   ├── products.service.ts            # 🔧 수정 (히스토리 로직)
│   └── dto/
│       └── purchase-history.dto.ts    # 🆕 신규 생성
├── purchase/
│   └── purchase-price.service.ts      # 🔧 수정 (CRUD 로직)
└── tests/
    └── products/
        └── purchase-history.spec.ts   # 🆕 신규 생성

API 설계

Endpoint	Method	설명
/products/:productId/purchase-history	GET	히스토리 목록 조회
/products/:productId/purchase-history	POST	새 원가 추가
/products/:productId/purchase-history/:id	PATCH	기존 이력 수정
/products/:productId/purchase-price	PATCH	간편 수정 (기존 API 확장)

기간 자동 조정 로직

[새 원가 추가 시]
기존: A(1/1~1/15), B(1/16~현재)
추가: C(1/10~)
결과: A(1/1~1/9), C(1/10~1/15), B(1/16~현재)

→ 시작일 기준 이전 이력 종료일 자동 조정

충돌 감지

항목	상태	설명
기존 코드 충돌	🟡 주의	products.controller.ts 수정
DB 스키마 변경	🟡 검토	PurchasePrice에 endDate 컬럼 필요할 수 있음

---

의존성

의존	설명	상태
E-03-S-01	원가 히스토리 조회 로직	선행 필요

---

Dev Agent Record

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

---

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

---

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