sam-react-prod/claudedocs/sales/[IMPL-2025-12-09] pricing-api-integration-checklist.md

단가관리 API 연동 체크리스트

작성일: 2025-12-09 목표: 백엔드 API 연동 완료 후 수동 검수

---

Phase 1: 목록 페이지 API 연동 ✅

1.1 데이터 조회

• GET /api/v1/pricing 호출로 단가 목록 조회
• API 응답 → PricingListItem 타입 변환
• 품목 정보 표시 (item_type_code, item_id 기반)
• 페이지네이션 적용 (size=100)

1.2 필터/검색

• 품목 유형 필터 (item_type_code) - API 지원됨
• 상태 필터 (status) - API 지원됨
• 검색어 필터 (q) - API 지원됨

---

Phase 2: 등록/수정 페이지 API 연동 ✅

2.1 등록 (POST /api/v1/pricing)

• 폼 데이터 → API 요청 형식 변환 (actions.ts: transformFrontendToApi)
• 성공/실패 토스트 메시지 (PricingFormClient 기존 로직)
• 등록 후 목록으로 리다이렉트

2.2 수정 (PUT /api/v1/pricing/{id})

• 기존 데이터 로드 (GET /api/v1/pricing/{id}) - getPricingById()
• 폼 데이터 → API 요청 형식 변환
• 수정 후 목록으로 리다이렉트

2.3 자동 계산

• 판매단가 자동 계산 (매입단가 + 가공비) × (1 + LOSS) × (1 + 마진율) - 백엔드에서 처리
• 반올림 규칙 적용 - 백엔드에서 처리

생성된 파일:

• src/components/pricing/actions.ts - 서버 액션 모음

---

Phase 3: 삭제/확정 API 연동 ✅

3.1 삭제 (DELETE /api/v1/pricing/{id})

• 삭제 서버 액션 구현 (deletePricing in actions.ts)
• 삭제 확인 다이얼로그 (목록 페이지에서 필요 시 추가)
• 삭제 후 목록 새로고침 (목록 페이지에서 필요 시 추가)

3.2 확정 (POST /api/v1/pricing/{id}/finalize)

• 확정 서버 액션 구현 (finalizePricing in actions.ts)
• 확정 확인 다이얼로그 (PricingFinalizeDialog 기존 UI 활용)
• 확정 후 목록으로 리다이렉트
• PricingFormClient에 onFinalize prop 추가

---

Phase 4: 이력 조회 API 연동 ✅

4.1 리비전 이력 (GET /api/v1/pricing/{id}/revisions)

• 이력 다이얼로그 UI (PricingHistoryDialog 기존 UI 활용)
• 변경 전/후 스냅샷 표시 (revisions 배열의 previousData 사용)
• 별도 API 호출 함수 구현 (getPricingRevisions in actions.ts)
• GET /pricing/{id}에서 revisions 함께 로드 (백엔드에서 with() 사용)

---

테스트 URL

• 목록: http://localhost:3000/sales/pricing-management
• 등록: http://localhost:3000/sales/pricing-management/create
• 수정: http://localhost:3000/sales/pricing-management/{id}/edit

---

Phase 5: 품목 목록 + 단가 병합 ✅

배경: 현재는 단가 등록된 품목만 표시됨. sam-design처럼 품목 전체 목록에 단가 정보를 병합해야 함.

5.1 품목 목록 API 호출

• GET /api/v1/items 통합 품목 목록 호출 (size=500)
• API 응답 → 프론트엔드 타입 변환 (ItemApiData)
• 품목 유형별 필터 지원 (FG, PT, SM, RM, CS) - items API에서 type 파라미터 지원

5.2 데이터 병합 로직

• 품목 목록 + 단가 목록 병합 함수 구현 (mergeItemsWithPricing)
• 품목별 단가 유무 판별 (Map 활용 O(1) 조회)
• 단가 미등록 품목 → status: 'not_registered' 표시

5.3 목록 페이지 수정

• page.tsx - 품목 API + 단가 API 병렬 호출 (Promise.all)
• PricingListClient - 병합된 데이터 표시
• 미등록 품목 → "등록" 버튼 표시 (+ 아이콘)
• 등록된 품목 → "수정" 버튼 표시 (연필 아이콘)
• itemTypeCode 파라미터 추가 (PRODUCT/MATERIAL 구분)

5.4 통계 카드 수정

• 전체 품목 수 (품목 목록 기준) - totalAll
• 단가 등록 수 - registered (status !== 'not_registered')
• 미등록 수 - notRegistered (totalAll - registered)
• 확정 수 - finalized (isFinal === true)

---

진행 상태

Phase	상태	완료일
Phase 1	✅ 완료	2025-12-09
Phase 2	✅ 완료	2025-12-09
Phase 3	✅ 완료	2025-12-09
Phase 4	✅ 완료	2025-12-09
Phase 5	✅ 완료	2025-12-09

---

생성/수정된 파일 요약

신규 생성

• src/components/pricing/actions.ts - 서버 액션 (CRUD + 확정 + 이력 조회)

수정된 파일

• src/app/[locale]/(protected)/sales/pricing-management/page.tsx - API 연동 (목록)
• src/app/[locale]/(protected)/sales/pricing-management/create/page.tsx - API 연동 (등록)
• src/app/[locale]/(protected)/sales/pricing-management/[id]/edit/page.tsx - API 연동 (수정+확정)
• src/components/pricing/PricingFormClient.tsx - onFinalize prop 추가
• src/components/pricing/index.ts - actions export 추가

---

수동 검수 체크리스트

• 목록 페이지에서 데이터 정상 조회
• 품목 클릭 → 수정 페이지 이동 정상
• 단가 수정 후 저장 정상
• 단가 확정 기능 정상
• 이력 조회 다이얼로그 정상
• 신규 단가 등록 정상 (품목 선택 후)