Procurement Backend

조달 시스템 백엔드 API 서버입니다. 공급사(Vendor) 관리와 발주서(PO) 도메인을 제공합니다.

기술 스택

분류	기술
Language / Framework	Java 25 / Spring Boot 4
ORM	Spring Data JPA + PostgreSQL
API 문서	Springdoc OpenAPI (Swagger UI)
입력 검증	Bean Validation (@Valid, @Validated)
에러 응답	ProblemDetail 기반 (RFC 9457)

---

API 목록 요약

Vendor (공급사 관리)

#	Method	Endpoint	기능	응답 코드
1	GET	/api/vendors/stats	공급사 전체 통계 조회	200
2	GET	/api/vendors/{vendorCode}/stats	공급사 상세 통계 조회	200, 404
3	GET	/api/vendors	공급사 목록 조회 (검색·필터·정렬·페이징)	200, 400
4	POST	/api/vendors	공급사 등록	201, 400
5	GET	/api/vendors/{vendorCode}	공급사 상세 조회	200, 404
6	PUT	/api/vendors/{vendorCode}	공급사 정보 수정	204, 400, 404, 422
7	PATCH	/api/vendors/{vendorCode}/active	공급사 활성 여부 변경	204, 400, 404, 422

PO (발주서 관리)

#	Method	Endpoint	기능	응답 코드
1	POST	/api/purchase-orders	발주 등록 (DRAFT 또는 CONFIRMED)	201, 400, 401, 403, 404, 422
2	PUT	/api/purchase-orders/{poNumber}	발주 수정 (DRAFT 전용)	204, 400, 401, 403, 404, 422
3	DELETE	/api/purchase-orders/{poNumber}	발주 삭제 (DRAFT 전용, 물리 삭제)	204, 400, 401, 403, 404, 422

---

공통 에러 응답 형식

모든 에러는 ProblemDetail 형식으로 반환됩니다. code 와 timestamp 필드가 항상 포함됩니다.

{
  "status": 404,
  "detail": "공급사를 찾을 수 없습니다: VD-999",
  "code": "VENDOR_NOT_FOUND",
  "timestamp": "2026-06-05T10:30:00+09:00"
}

에러 코드 목록

code	HTTP	발생 조건
VENDOR_NOT_FOUND	404	해당 코드의 공급사가 존재하지 않을 때
VENDOR_INACTIVE	422	비활성 공급사를 수정하려 할 때
VENDOR_HAS_ACTIVE_PO	422	진행 중 PO(DRAFT/CONFIRMED)가 있는 공급사를 비활성화하려 할 때
VENDOR_DUPLICATE	409	공급사 코드 UNIQUE 제약 위반
PO_NOT_FOUND	404	해당 번호의 발주서가 존재하지 않을 때
PO_INVALID_STATUS	422	허용되지 않는 PO 상태에서 수정·삭제를 시도할 때 (DRAFT 아님)
PO_VENDOR_INACTIVE	422	비활성 공급사에 발주하려 할 때
PO_ITEM_NOT_FOUND	422	주문 라인의 SKU에 해당하는 부품이 존재하지 않을 때
PO_ITEM_INACTIVE	422	비활성 부품으로 발주하려 할 때
PO_WAREHOUSE_INVALID	422	납품 창고 코드가 존재하지 않을 때
PO_DUPLICATE_SKU	422	한 발주의 주문 라인에 동일 SKU가 중복될 때
PO_DUPLICATE	409	발주 번호 UNIQUE 제약 위반
COMMON_INVALID_INPUT	400	필드·파라미터 검증 실패 (@Valid 바디 / @Validated Path·Query)
COMMON_BAD_REQUEST	400	그 외 잘못된 요청 (405·415·깨진 JSON 등 미분류)
COMMON_INTERNAL_ERROR	500	처리되지 않은 서버 내부 오류

---

API 상세

1. GET /api/vendors/stats — 공급사 전체 통계 조회

공급사 대시보드 상단 카드 영역에 표시할 집계 수치를 반환합니다.

• 전체 / 활성 / 비활성 공급사 수
• 진행 중 PO(DRAFT + CONFIRMED) 건수 및 총 금액

Request — 파라미터 없음

Response 200

{
  "totalCount": 20,
  "activeCount": 18,
  "inactiveCount": 2,
  "activePoCount": 5,
  "activePoAmount": 150000000
}

필드	타입	설명
totalCount	long	전체 공급사 수
activeCount	long	활성 공급사 수
inactiveCount	long	비활성 공급사 수 (total - active)
activePoCount	long	진행 중 PO 건수 (DRAFT + CONFIRMED)
activePoAmount	long	진행 중 PO 총 금액 (원 단위)

---

2. GET /api/vendors/{vendorCode}/stats — 공급사 상세 통계 조회

특정 공급사의 거래 현황을 요약한 통계를 반환합니다. 공급사 상세 페이지의 통계 카드 영역에서 사용합니다.

Path Parameter

파라미터	타입	예시	설명
vendorCode	String	VD-014	공급사 코드 (필수, 공백 불가)

Response 200

{
  "activePo": 3,
  "tradeAmount30d": 92400000,
  "avgLeadTimeDays": 5.2
}

필드	타입	설명
activePo	long	해당 공급사의 진행 중 PO 수 (DRAFT + CONFIRMED)
tradeAmount30d	long	최근 30일 거래액. CONFIRMED + RECEIVED 상태 PO만 집계 (DRAFT, CANCELED 제외)
avgLeadTimeDays	Double (nullable)	평균 리드타임(일). RECEIVED 상태 PO의 orderedAt → receivedAt 기준. RECEIVED PO가 없으면 null 반환

Error

상태	code	설명
404	VENDOR_NOT_FOUND	해당 코드의 공급사가 존재하지 않음

---

3. GET /api/vendors — 공급사 목록 조회 (검색·필터·정렬·페이징)

등록된 공급사를 검색·필터·정렬과 함께 offset 페이지 단위로 조회합니다.

Query Parameters

파라미터	타입	기본값	설명
page	int	0	페이지 번호 (0-based, 0 이상)
size	int	10	페이지당 항목 수 (1~100)
search	String	—	공급사명·코드 부분 검색 (미입력 시 전체)
active	Boolean	—	활성 여부 필터 (미입력 시 전체)
sort	String	recentTrade	정렬 기준. recentTrade(최근 거래순) 또는 code(코드 오름차순)

recentTrade는 각 공급사의 가장 최근 발주(orderedAt) 기준 내림차순이며, 거래 이력이 없는 공급사는 뒤로 정렬됩니다(NULLS LAST).

Response 200

{
  "content": [
    {
      "id": 1,
      "code": "VD-001",
      "name": "(주)동성정밀",
      "contactPerson": "김상호",
      "phone": "02-1234-5678",
      "address": "경기 안산시 단원구 별망로 178",
      "active": true,
      "createdAt": "2026-05-01T09:00:00+09:00"
    }
  ],
  "page": 0,
  "size": 10,
  "totalElements": 20,
  "totalPages": 2
}

Error

상태	code	설명
400	COMMON_INVALID_INPUT	size 범위(1~100) 초과, sort 미정의 값, page 음수

---

4. POST /api/vendors — 공급사 등록

새로운 공급사를 등록합니다. 공급사 코드(code)는 서버에서 자동 채번되며 (VD-001, VD-002, … 형식), 클라이언트가 지정할 수 없습니다. 신규 등록된 공급사의 active 기본값은 true입니다.

Request Body

{
  "name": "(주)동성정밀",
  "contactPerson": "김상호",
  "phone": "02-1234-5678",
  "address": "경기 안산시 단원구 별망로 178"
}

필드	타입	필수	검증 규칙
name	String	✅	공백 불가
contactPerson	String	✅	공백 불가
phone	String	✅	0XX-XXXX-XXXX 또는 0X-XXX-XXXX 형식
address	String	✅	공백 불가

Response 201 — 생성된 공급사 정보 (VendorResponse)

Error

상태	code	설명
400	COMMON_INVALID_INPUT	필드 검증 실패 (상세 메시지 포함)

---

5. GET /api/vendors/{vendorCode} — 공급사 상세 조회

공급사 기본 정보와 함께 해당 공급사의 최근 PO 최대 6건을 반환합니다. PO 목록은 createdAt 기준 내림차순 정렬입니다.

Path Parameter

파라미터	타입	예시
vendorCode	String	VD-014

Response 200

{
  "id": 1,
  "code": "VD-001",
  "name": "(주)동성정밀",
  "contactPerson": "김상호",
  "phone": "02-1234-5678",
  "address": "경기 안산시 단원구 별망로 178",
  "active": true,
  "recentPos": [
    {
      "poNumber": "PO-2026-0421",
      "status": "CONFIRMED",
      "totalAmount": 5000000,
      "orderedAt": "2026-05-20T14:32:00+09:00"
    }
  ],
  "createdAt": "2026-05-01T09:00:00+09:00",
  "updatedAt": "2026-05-20T15:00:00+09:00"
}

필드	설명
recentPos	최근 PO 최대 6건. poNumber, status, totalAmount, orderedAt 포함
updatedAt	마지막 수정 일시 (KST, ISO-8601)

Error

상태	code	설명
404	VENDOR_NOT_FOUND	해당 코드의 공급사가 존재하지 않음

---

6. PUT /api/vendors/{vendorCode} — 공급사 정보 수정

공급사의 기본 정보(이름, 대표자, 전화번호, 주소)를 수정합니다.

• 공급사 코드(code)는 수정 불가입니다. 코드는 Path Variable로만 사용됩니다.
• 비활성(active: false) 상태의 공급사는 수정할 수 없습니다. 먼저 활성화 후 수정해야 합니다.
• 성공 시 응답 본문 없이 204 No Content를 반환합니다.

Path Parameter

파라미터	타입	예시
code	String	VD-003

Request Body — POST /api/vendors의 Request Body와 동일한 필드 및 검증 규칙 적용

Response 204 No Content

Error

상태	code	설명
400	COMMON_INVALID_INPUT	필드 검증 실패
404	VENDOR_NOT_FOUND	해당 코드의 공급사가 존재하지 않음
422	VENDOR_INACTIVE	비활성 공급사는 수정 불가

---

7. PATCH /api/vendors/{vendorCode}/active — 공급사 활성 여부 변경

공급사를 활성화하거나 비활성화합니다.

• 비활성화 시 해당 공급사에 진행 중 PO(DRAFT 또는 CONFIRMED 상태)가 1건이라도 존재하면 422를 반환합니다. 이는 진행 중인 발주 처리를 보호하기 위한 비즈니스 규칙입니다.
• 활성화 시에는 별도 제약 없이 즉시 적용됩니다.
• 성공 시 응답 본문 없이 204 No Content를 반환합니다.

Path Parameter

파라미터	타입	예시
vendorCode	String	VD-014

Request Body

{ "active": false }

필드	타입	필수	설명
active	Boolean	✅	true (활성화) / false (비활성화)

Response 204 No Content

Error

상태	code	설명
400	COMMON_INVALID_INPUT	active 필드 누락
404	VENDOR_NOT_FOUND	해당 코드의 공급사가 존재하지 않음
422	VENDOR_HAS_ACTIVE_PO	진행 중 PO가 존재하여 비활성화 불가 (에러 메시지에 건수 포함)

---

PO API 상세

모든 PO API의 기본 경로는 /api/purchase-orders 입니다. 발주 시각 필드는 시간 컨벤션에 따라 offset이 명시된 OffsetDateTime(KST, ISO-8601)으로 주고받습니다.

1. POST /api/purchase-orders — 발주 등록

신규 발주를 등록합니다.

• confirm 값에 따라 생성 상태가 결정됩니다. false면 DRAFT, true면 CONFIRMED(승인자·발주일시 기록)로 생성됩니다.
• 발주 번호(poNumber)는 서버에서 자동 채번됩니다. 형식은 PO-{년}-{4자리 일련번호} (예: PO-2026-0005)이며, 9999 초과 시 자릿수가 자동 확장됩니다.
• 등록 과정에서 공급사·납품 창고·부품(SKU)의 존재 및 활성 여부를 검증하고, 부품의 이름·단가를 스냅샷으로 저장합니다.

Request Body

{
  "vendorCode": "VD-001",
  "targetWarehouseCode": "WH-01",
  "expectedArrival": "2026-06-20T09:00:00+09:00",
  "note": "긴급 발주 건",
  "confirm": false,
  "lines": [
    { "sku": "SKU-1001", "quantity": 10 },
    { "sku": "SKU-1002", "quantity": 5 }
  ]
}

필드	타입	필수	검증 규칙
vendorCode	String	✅	공백 불가
targetWarehouseCode	String	✅	공백 불가
expectedArrival	OffsetDateTime	✅	오늘 이후(현재 포함)
note	String	—	500자 이하
confirm	Boolean	✅	false=DRAFT / true=CONFIRMED
lines	Array	✅	최소 1건, 최대 100건
lines[].sku	String	✅	공백 불가, 라인 간 중복 불가
lines[].quantity	Integer	✅	1 이상

Response 201

{
  "poNumber": "PO-2026-0005",
  "status": "DRAFT",
  "vendorCode": "VD-001",
  "vendorName": "(주)동성정밀",
  "targetWarehouseCode": "WH-01",
  "expectedArrival": "2026-06-20T09:00:00+09:00",
  "note": "긴급 발주 건",
  "totalAmount": 1500000,
  "lines": [
    {
      "lineNo": 1,
      "sku": "SKU-1001",
      "nameSnapshot": "베어링 6202",
      "unitPriceSnapshot": 100000,
      "quantity": 10
    }
  ],
  "createdAt": "2026-06-09T10:30:00+09:00"
}

필드	설명
status	발주 상태 (DRAFT / CONFIRMED)
vendorName	등록 시점의 공급사명
totalAmount	라인별 단가 스냅샷 × 수량의 합계 (원 단위)
lines[].nameSnapshot / unitPriceSnapshot	등록 시점의 부품 이름·단가 스냅샷

Error

상태	code	설명
400	COMMON_INVALID_INPUT	필드 검증 실패
404	VENDOR_NOT_FOUND	공급사가 존재하지 않음
422	PO_VENDOR_INACTIVE	비활성 공급사에는 발주 불가
422	PO_DUPLICATE_SKU	주문 라인에 동일 SKU 중복
422	PO_WAREHOUSE_INVALID	납품 창고가 존재하지 않음
422	PO_ITEM_NOT_FOUND	부품(SKU)이 존재하지 않음
422	PO_ITEM_INACTIVE	비활성 부품으로는 발주 불가

---

2. PUT /api/purchase-orders/{poNumber} — 발주 수정

DRAFT 상태인 발주의 정보를 수정합니다.

• DRAFT 상태에서만 수정 가능합니다. CONFIRMED 이후 상태에서는 422를 반환합니다. (상태 검증을 입력 자원 검증보다 먼저 수행합니다.)
• 주문 라인은 전체 교체(replace)됩니다. 기존 라인을 모두 제거한 뒤 요청 라인으로 다시 구성합니다.
• 등록과 달리 상태 전이를 하지 않으므로 confirm 필드가 없습니다.
• 성공 시 응답 본문 없이 204 No Content를 반환합니다.

Path Parameter

파라미터	타입	예시	설명
poNumber	String	PO-2026-0005	발주 번호 (필수, 공백 불가)

Request Body — POST /api/purchase-orders의 Request Body에서 confirm 필드를 제외한 동일한 필드 및 검증 규칙 적용

Response 204 No Content

Error

상태	code	설명
400	COMMON_INVALID_INPUT	필드 검증 실패
404	PO_NOT_FOUND	발주가 존재하지 않음
404	VENDOR_NOT_FOUND	공급사가 존재하지 않음
422	PO_INVALID_STATUS	DRAFT 상태가 아니어서 수정 불가
422	PO_VENDOR_INACTIVE	비활성 공급사
422	PO_DUPLICATE_SKU	주문 라인에 동일 SKU 중복
422	PO_WAREHOUSE_INVALID	납품 창고가 존재하지 않음
422	PO_ITEM_NOT_FOUND	부품(SKU)이 존재하지 않음
422	PO_ITEM_INACTIVE	비활성 부품

---

3. DELETE /api/purchase-orders/{poNumber} — 발주 삭제

DRAFT 상태인 발주를 물리 삭제합니다.

• DRAFT 상태에서만 삭제 가능합니다. CONFIRMED 이후 상태에서는 422를 반환하며, 이 경우 취소는 cancel API를 사용합니다.
• DB에서 레코드를 완전히 제거하며 이력이 남지 않습니다. (soft delete인 cancel과 구분)
• 성공 시 응답 본문 없이 204 No Content를 반환합니다.

Path Parameter

파라미터	타입	예시	설명
poNumber	String	PO-2026-0005	발주 번호 (필수, 공백 불가)

Response 204 No Content

Error

상태	code	설명
400	COMMON_INVALID_INPUT	poNumber 누락·공백
404	PO_NOT_FOUND	발주가 존재하지 않음
422	PO_INVALID_STATUS	DRAFT 상태가 아니어서 삭제 불가

---

공급사(Vendor) 상태 머신

공급사는 active 플래그로 활성/비활성 상태를 관리합니다.

활성(active: true) ──비활성화──► 비활성(active: false)
       ▲                                  │
       └─────────활성화───────────────────┘

상태	설명
active: true	발주 생성 가능, 정보 수정 가능
active: false	발주 생성 불가, 정보 수정 불가

전이 규칙

전이	조건	비고
활성 → 비활성	진행 중 PO(DRAFT/CONFIRMED)가 0건일 때만 가능	PO 존재 시 422 VENDOR_HAS_ACTIVE_PO
비활성 → 활성	제약 없음

---

발주서(PO) 상태 머신

등록(POST)·수정(PUT)·삭제(DELETE)와 상태 전이 API(confirm/receive/cancel)가 모두 구현되어 있습니다.

DRAFT ──confirm()──► CONFIRMED ──receive()──► RECEIVED
  │                      │
  │                      └──cancel()──────► CANCELED
  └──delete() ── 물리 삭제 (DB에서 완전 제거)

상태 설명

상태	설명	IN_PROGRESS	TRADE
DRAFT	작성 중. 아직 발주되지 않은 임시 상태	✅	❌
CONFIRMED	발주 확정. 승인자 정보 및 발주일시 기록	✅	✅
RECEIVED	입고 완료. 라인별 수령 수량 기록	❌	✅
CANCELED	취소 처리. DB에 이력으로 남음	❌	❌

IN_PROGRESS (DRAFT + CONFIRMED): 공급사 비활성화 가능 여부 판단 및 진행 중 PO 통계에 사용
TRADE (CONFIRMED + RECEIVED): 거래액 집계(tradeAmount30d) 산출에 사용

전이 규칙

전이	출발 상태	설명
confirm()	DRAFT	CONFIRMED로 전이. 승인자 정보(approvedBy, approvedName)와 발주일시(orderedAt) 기록
receive()	CONFIRMED	RECEIVED로 전이. 입고일시(receivedAt) 기록. 라인별 수령 수량 반영
cancel()	CONFIRMED	CANCELED로 전이. DB에 취소 이력으로 보존됨 (DRAFT는 취소 대상 아님, delete로 물리 삭제)
delete()	DRAFT 전용	DB에서 물리 삭제. 목록에서 완전히 제거. 이력 없음

cancel() vs delete() 차이

구분	cancel	delete
대상 상태	CONFIRMED만 가능	DRAFT만 가능
처리 방식	상태를 CANCELED로 변경 (소프트 삭제)	DB에서 레코드 완전 제거 (하드 삭제)
이력 보존	✅ 취소 이력 남음	❌ 흔적 없이 삭제
사용 시나리오	확정된 발주를 되돌릴 때	실수로 만든 임시 발주서(DRAFT)를 목록에서 완전히 제거할 때