From 054d5d23f71213a92f8cab581683660779a1c94d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Mon, 16 Mar 2026 21:27:17 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[order]=20=EC=9E=AC=EA=B3=A0=EC=83=9D?= =?UTF-8?q?=EC=82=B0=EA=B4=80=EB=A6=AC=20API=20=EB=AA=85=EC=84=B8=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - frontend/api-specs/stock-production-api.md 신규 작성 - INDEX.md에 재고생산관리 API 문서 등록 --- INDEX.md | 2 + frontend/api-specs/stock-production-api.md | 349 +++++++++++++++++++++ 2 files changed, 351 insertions(+) create mode 100644 frontend/api-specs/stock-production-api.md diff --git a/INDEX.md b/INDEX.md index 46bab30..c9fe3be 100644 --- a/INDEX.md +++ b/INDEX.md @@ -24,6 +24,7 @@ | 견적관리 | `features/quotes/README.md` | 견적 시스템, BOM 계산 | | 급여관리 API | `frontend/api-specs/payroll-api.md` | 급여관리 API 전체 명세 (18개 엔드포인트) | | 바로빌 회계 API | `frontend/api-specs/barobill-api.md` | 카드/은행/홈택스 REST API (42개 엔드포인트) | +| 재고생산관리 API | `frontend/api-specs/stock-production-api.md` | 재고생산 API 명세 (기존 수주 API + STOCK 타입) | | 결재관리 | `dev/dev_plans/approval-system-unification-plan.md` | MNG→API 결재 통합 계획 | | API 품질 | `system/api-code-quality-audit.md` | 정석 패턴 R1~R6, 안티패턴, 보안, 체크리스트 | | API 학습 | `dev/guides/api-request-lifecycle.md` | Client API로 배우는 요청 생명주기 8단계 | @@ -262,6 +263,7 @@ DB 도메인별: | [barobill-api.md](frontend/api-specs/barobill-api.md) | 바로빌 회계 데이터 API 명세 (42개 엔드포인트) | | [equipment-api.md](requests/equipment-frontend-request.md) | 설비관리 React 프론트엔드 구현 요청 (26개 엔드포인트 + 화면 가이드) | | [vehicle-api.md](frontend/api-specs/vehicle-api.md) | 차량관리 API 명세 (20개 엔드포인트: 차량목록, 차량일지, 정비이력, 사진) | +| [stock-production-api.md](frontend/api-specs/stock-production-api.md) | 재고생산관리 API 명세 (기존 수주 API + STOCK 타입) | | [vehicle-react-implementation.md](plans/vehicle-react-implementation.md) | 차량관리 React 구현 요청서 (3개 메뉴, 컴포넌트 구조, 타입 정의) | ### frontend/integration/ — 프론트엔드 개발 가이드 diff --git a/frontend/api-specs/stock-production-api.md b/frontend/api-specs/stock-production-api.md new file mode 100644 index 0000000..c793928 --- /dev/null +++ b/frontend/api-specs/stock-production-api.md @@ -0,0 +1,349 @@ +# 재고생산관리 API 명세 + +> **작성일**: 2026-03-16 +> **상태**: 설계 확정 +> **대상**: React 프론트엔드 개발자 + +--- + +## 1. 개요 + +### 1.1 목적 + +재고생산관리는 **수주 없이 재고 목적으로 생산**하는 경우를 위한 기능이다. +기존 수주관리(Order) API를 **그대로 사용**하되, `order_type_code: 'STOCK'`으로 구분한다. + +### 1.2 핵심 원칙 + +- 별도 API 엔드포인트 없음 — 기존 `/api/v1/orders` 사용 +- `order_type_code` 필터로 수주(`ORDER`)와 재고생산(`STOCK`)을 분리 +- 화면은 수주관리를 **단순화**한 형태 (거래처, 견적, 배송, 할인 등 불필요) +- 하류 시스템(작업지시, 생산, 출하)은 **동일하게 동작** + +--- + +## 2. API 엔드포인트 + +> **기본 URL**: `/api/v1/orders` +> **인증**: `Bearer Token` (Sanctum) + `API Key` + +### 2.1 목록 조회 + +``` +GET /api/v1/orders?order_type=STOCK +``` + +| 파라미터 | 타입 | 필수 | 설명 | +|----------|------|:----:|------| +| `order_type` | string | ✅ | `STOCK` 고정 | +| `page` | int | - | 페이지 (기본: 1) | +| `size` | int | - | 페이지 크기 (기본: 20) | +| `q` | string | - | 검색어 (생산번호, 메모) | +| `status` | string | - | 상태 필터 (`DRAFT`, `CONFIRMED` 등) | +| `date_from` | date | - | 등록일 시작 | +| `date_to` | date | - | 등록일 종료 | + +**응답 예시**: + +```json +{ + "success": true, + "message": "message.order.fetched", + "data": { + "data": [ + { + "id": 42, + "order_no": "STK202603160001", + "order_type_code": "STOCK", + "status_code": "DRAFT", + "quantity": "100.0000", + "memo": "봄 시즌 대비 재고 확보", + "options": { + "production_reason": "시즌 대비", + "target_stock_qty": 500 + }, + "items": [ + { + "id": 1, + "item_name": "25mm 알루미늄 블라인드", + "specification": "W1000 x H2000", + "quantity": "100.0000", + "unit_price": "15000.00" + } + ], + "created_at": "2026-03-16T10:30:00Z" + } + ], + "current_page": 1, + "last_page": 1, + "total": 1 + } +} +``` + +--- + +### 2.2 통계 조회 + +``` +GET /api/v1/orders/stats?order_type=STOCK +``` + +| 파라미터 | 타입 | 필수 | 설명 | +|----------|------|:----:|------| +| `order_type` | string | ✅ | `STOCK` 고정 | + +**응답 예시**: + +```json +{ + "success": true, + "data": { + "total": 15, + "draft": 3, + "confirmed": 5, + "in_progress": 4, + "completed": 2, + "cancelled": 1, + "total_amount": 0, + "confirmed_amount": 0 + } +} +``` + +--- + +### 2.3 생성 + +``` +POST /api/v1/orders +``` + +**요청 본문**: + +```json +{ + "order_type_code": "STOCK", + "memo": "봄 시즌 대비 재고 확보", + "options": { + "production_reason": "시즌 대비", + "target_stock_qty": 500 + }, + "items": [ + { + "item_id": 10, + "item_name": "25mm 알루미늄 블라인드", + "specification": "W1000 x H2000", + "quantity": 100, + "unit_price": 0, + "unit": "EA" + } + ] +} +``` + +**필수 필드**: + +| 필드 | 타입 | 필수 | 설명 | +|------|------|:----:|------| +| `order_type_code` | string | ✅ | `STOCK` 고정 | +| `items` | array | ✅ | 생산할 품목 목록 | +| `items[].item_name` | string | ✅ | 품목명 | +| `items[].quantity` | number | ✅ | 수량 | +| `items[].unit_price` | number | ✅ | 단가 (재고생산은 `0` 가능) | + +**선택 필드**: + +| 필드 | 타입 | 설명 | +|------|------|------| +| `memo` | string | 비고 | +| `options.production_reason` | string | 생산 사유 | +| `options.target_stock_qty` | number | 목표 재고 수량 | +| `items[].item_id` | int | 품목 마스터 ID | +| `items[].specification` | string | 규격 | +| `items[].unit` | string | 단위 | + +**사용하지 않는 필드** (수주 전용): + +``` +❌ client_id, client_name, client_contact → 거래처 없음 +❌ site_name → 현장 없음 +❌ quote_id → 견적 없음 +❌ delivery_date, delivery_method_code → 납기/배송 불필요 +❌ discount_rate, discount_amount → 할인 없음 +❌ sales_recognition → 매출 인식 불필요 +❌ options.shipping_cost_code → 운임비용 불필요 +❌ options.receiver, receiver_contact → 수신자 불필요 +❌ options.shipping_address → 배송지 불필요 +``` + +> **자동 생성**: `order_no`는 `STK{YYYYMMDD}{NNNN}` 형식으로 서버에서 자동 생성 + +--- + +### 2.4 단건 조회 + +``` +GET /api/v1/orders/{id} +``` + +기존 수주 조회와 동일. `order_type_code`가 `STOCK`인지 프론트에서 확인. + +--- + +### 2.5 수정 + +``` +PUT /api/v1/orders/{id} +``` + +생성과 동일한 필드 사용. `order_type_code`는 변경하지 않는다. + +--- + +### 2.6 삭제 + +``` +DELETE /api/v1/orders/{id} +``` + +기존 수주 삭제와 동일. + +--- + +### 2.7 상태 변경 + +``` +PATCH /api/v1/orders/{id}/status +``` + +```json +{ + "status": "CONFIRMED" +} +``` + +**상태 흐름** (수주와 동일): + +``` +DRAFT → CONFIRMED → IN_PROGRESS → COMPLETED + └─────→ CANCELLED ──→ DRAFT (복구) +``` + +> **재고생산 특수**: `CONFIRMED` 상태 진입 시 매출 자동 생성이 **발생하지 않음** + +--- + +### 2.8 생산지시 생성 + +``` +POST /api/v1/orders/{id}/production-order +``` + +수주와 동일하게 작업지시(WorkOrder)를 생성한다. + +```json +{ + "process_ids": [1, 2, 3], + "priority": "normal", + "scheduled_date": "2026-03-20", + "memo": "재고생산 작업" +} +``` + +--- + +## 3. 채번 규칙 + +| 주문 유형 | 접두사 | 예시 | +|----------|--------|------| +| 수주 (ORDER) | `ORD` | `ORD202603160001` | +| 재고생산 (STOCK) | `STK` | `STK202603160001` | + +--- + +## 4. 화면 설계 가이드 + +### 4.1 수주관리 화면 vs 재고생산관리 화면 + +``` +┌─ 수주관리 ──────────────────┐ ┌─ 재고생산관리 ───────────────┐ +│ │ │ │ +│ [거래처 정보] │ │ [생산 정보] │ +│ - 거래처 선택 │ │ - 생산 사유 (텍스트) │ +│ - 현장명 │ │ - 목표 재고 수량 │ +│ - 배송/납기일 │ │ - 비고 │ +│ - 운임비용 │ │ │ +│ - 견적 연결 │ ├──────────────────────────────┤ +│ - 할인 │ │ [품목 목록] │ +│ - 매출 인식 방식 │ │ - 품목 선택 │ +│ │ │ - 수량 │ +│ [개소/구역 (OrderNode)] │ │ - 규격 │ +│ - N-depth 트리 구조 │ │ │ +│ │ │ (단가/금액/할인 불필요) │ +│ [품목 목록] │ │ (개소/구역 불필요) │ +│ - 품목, 수량, 단가, 할인 │ │ │ +│ - floor_code, symbol_code │ └──────────────────────────────┘ +│ - 금액 계산 │ +│ │ +└──────────────────────────────┘ +``` + +### 4.2 목록 페이지 표시 컬럼 + +| 컬럼 | 설명 | +|------|------| +| 생산번호 | `order_no` (STK...) | +| 상태 | `status_code` (상태 배지) | +| 품목 | 대표 품목명 + (외 N건) | +| 수량 | 총 수량 | +| 생산 사유 | `options.production_reason` | +| 등록일 | `created_at` | + +### 4.3 상태 배지 색상 (수주와 동일) + +| 상태 | 라벨 | 색상 | +|------|------|------| +| `DRAFT` | 등록 | gray | +| `CONFIRMED` | 확정 | blue | +| `IN_PROGRESS` | 진행중 | yellow | +| `IN_PRODUCTION` | 생산중 | orange | +| `PRODUCED` | 생산완료 | green | +| `COMPLETED` | 완료 | green | +| `CANCELLED` | 취소 | red | + +--- + +## 5. 구현 체크리스트 + +### 프론트엔드 (React) + +- [ ] 재고생산관리 메뉴/라우트 추가 +- [ ] 목록 페이지: `GET /api/v1/orders?order_type=STOCK` +- [ ] 통계 카드: `GET /api/v1/orders/stats?order_type=STOCK` +- [ ] 생성 폼: `order_type_code: 'STOCK'` 필수 전송 +- [ ] 상세/수정 페이지: 수주 화면 단순화 (거래처/견적/배송/할인 제거) +- [ ] 생산지시 생성 버튼: `POST /api/v1/orders/{id}/production-order` +- [ ] 상태 변경: `PATCH /api/v1/orders/{id}/status` + +### 백엔드 (API) — 완료 + +- [x] `Order::TYPE_STOCK = 'STOCK'` 상수 추가 +- [x] StoreOrderRequest에 `STOCK` validation 추가 +- [x] UpdateOrderRequest에 `STOCK` validation 추가 +- [x] 재고생산 채번: `STK{YYYYMMDD}{NNNN}` +- [x] stats()에 `order_type` 필터 추가 +- [x] STOCK 타입 확정 시 매출 자동 생성 스킵 +- [x] options에 `production_reason`, `target_stock_qty` 필드 추가 + +--- + +## 관련 문서 + +- 수주관리: 기존 수주 API는 동일 엔드포인트 (`/api/v1/orders`) +- 작업지시: `POST /api/v1/orders/{id}/production-order` +- 품목관리: `rules/item-policy.md` + +--- + +**최종 업데이트**: 2026-03-16