From 36e4f8c418bd93fc5f44cf1776318a6a4cdac77c Mon Sep 17 00:00:00 2001 From: kent Date: Thu, 8 Jan 2026 20:57:58 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EC=88=98=EC=A3=BC=EA=B4=80=EB=A6=AC=20?= =?UTF-8?q?API=20=EC=97=B0=EB=8F=99=20=EA=B3=84=ED=9A=8D=20Phase=202=20?= =?UTF-8?q?=EC=99=84=EB=A3=8C=20=EC=83=81=ED=83=9C=20=EC=97=85=EB=8D=B0?= =?UTF-8?q?=EC=9D=B4=ED=8A=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Phase 2 Frontend API 연동 완료 표시 (67% 진행) - actions.ts 생성 및 페이지별 연동 상태 업데이트 - 다음 단계: Phase 3 고급 기능 Co-Authored-By: Claude Opus 4.5 --- plans/order-management-plan.md | 301 +++++++++++++++++++++++++++++++++ 1 file changed, 301 insertions(+) create mode 100644 plans/order-management-plan.md diff --git a/plans/order-management-plan.md b/plans/order-management-plan.md new file mode 100644 index 0000000..8b42a6d --- /dev/null +++ b/plans/order-management-plan.md @@ -0,0 +1,301 @@ +# 수주관리 (Order Management) API 연동 계획 + +> **작성일**: 2025-01-08 +> **목적**: 수주관리 페이지 Mock 데이터 → API 연동 +> **상태**: ✅ Phase 2 완료 (Frontend API 연동 완료) + +--- + +## 📍 현재 진행 상태 + +| 항목 | 내용 | +|------|------| +| **마지막 완료 작업** | Phase 2 완료 - Frontend API 연동 (actions.ts, 타입 정의, 페이지 연동) | +| **다음 작업** | Phase 3: 고급 기능 (견적→수주 변환, 생산지시 생성, 상태 흐름 관리) | +| **진행률** | 2/3 Phase (67%) | +| **마지막 업데이트** | 2025-01-08 | +| **커밋** | Phase 2 커밋 대기 중 | + +--- + +## 1. 개요 + +### 1.1 배경 +수주관리 페이지는 프론트엔드 UI가 구현되어 있으나, **하드코딩된 Mock 데이터(SAMPLE_ORDERS)**를 사용 중입니다. +실제 비즈니스 운영을 위해 API 연동이 필요합니다. + +### 1.2 현재 구현 상태 분석 + +#### API (Laravel) - ✅ Phase 1 완료 +| 구성요소 | 파일 경로 | 상태 | +|---------|----------|------| +| Model | `api/app/Models/Orders/Order.php` | ✅ 존재 | +| Model | `api/app/Models/Orders/OrderItem.php` | ✅ 존재 | +| Model | `api/app/Models/Orders/OrderHistory.php` | ✅ 존재 | +| Model | `api/app/Models/Orders/OrderVersion.php` | ✅ 존재 | +| Model | `api/app/Models/Orders/OrderItemComponent.php` | ✅ 존재 | +| Controller | `api/app/Http/Controllers/Api/V1/OrderController.php` | ✅ **완료** | +| Service | `api/app/Services/OrderService.php` | ✅ **완료** | +| FormRequest | `api/app/Http/Requests/Order/*.php` | ✅ **완료** (3개) | +| Route | `/api/v1/orders` | ✅ **완료** (7개 엔드포인트) | +| Swagger | `api/app/Swagger/v1/OrderApi.php` | ✅ **완료** | + +#### Frontend (React/Next.js) - ✅ Phase 2 완료 +| 구성요소 | 파일 경로 | 상태 | +|---------|----------|------| +| 목록 페이지 | `react/src/app/[locale]/(protected)/sales/order-management-sales/page.tsx` | ✅ API 연동 | +| 등록 페이지 | `react/src/app/[locale]/(protected)/sales/order-management-sales/new/page.tsx` | ✅ API 연동 | +| 상세 페이지 | `react/src/app/[locale]/(protected)/sales/order-management-sales/[id]/page.tsx` | ✅ API 연동 | +| 수정 페이지 | `react/src/app/[locale]/(protected)/sales/order-management-sales/[id]/edit/page.tsx` | ✅ API 연동 | +| 생산지시 페이지 | `react/src/app/[locale]/(protected)/sales/order-management-sales/[id]/production-order/page.tsx` | ⏳ Phase 3 | +| 등록 컴포넌트 | `react/src/components/orders/OrderRegistration.tsx` | ✅ 완료 | +| 견적선택 다이얼로그 | `react/src/components/orders/QuotationSelectDialog.tsx` | ✅ 완료 | +| 품목추가 다이얼로그 | `react/src/components/orders/ItemAddDialog.tsx` | ✅ 완료 | +| **actions.ts** | `react/src/components/orders/actions.ts` | ✅ **완료** | + +### 1.3 연관관계 +``` +┌─────────────────┐ ┌─────────────────┐ +│ Quote │────── quote_id ────▶│ Order │ +│ (견적서) │ │ (수주) │ +└─────────────────┘ └─────────────────┘ + │ + │ sales_order_id + ▼ + ┌─────────────────┐ + │ WorkOrder │ + │ (작업지시) │ + └─────────────────┘ +``` + +### 1.4 변경 승인 정책 + +| 분류 | 예시 | 승인 | +|------|------|------| +| ✅ 즉시 가능 | 필드 추가/변경, API 엔드포인트 추가 | 불필요 | +| ⚠️ 컨펌 필요 | 테이블 구조 변경, 기존 API 수정 | **필수** | +| 🔴 금지 | 기존 Order 모델 구조 변경 | 별도 협의 | + +--- + +## 2. 대상 범위 + +### Phase 1: API 개발 (✅ 완료) + +| # | 작업 항목 | 상태 | 비고 | +|---|----------|:----:|------| +| 1.1 | OrderController 생성 | ✅ | CRUD + 상태관리 (7개 메서드) | +| 1.2 | OrderService 생성 | ✅ | 비즈니스 로직 (index, stats, show, store, update, destroy, updateStatus) | +| 1.3 | FormRequest 생성 | ✅ | Store, Update, UpdateStatus (3개) | +| 1.4 | API 라우트 등록 | ✅ | routes/api.php (7개 엔드포인트) | +| 1.5 | Swagger 문서 작성 | ✅ | OrderApi.php (스키마 8개) | + +### Phase 2: Frontend 연동 (✅ 완료) + +| # | 작업 항목 | 상태 | 비고 | +|---|----------|:----:|------| +| 2.1 | actions.ts 생성 | ✅ | API 호출 함수 + 타입 정의 + 변환 함수 | +| 2.2 | 목록 페이지 연동 | ✅ | getOrders(), getOrderStats() 연동 | +| 2.3 | 상세 페이지 연동 | ✅ | getOrderById() 연동 + 타입 오류 수정 | +| 2.4 | 등록 페이지 연동 | ✅ | createOrder() 연동 | +| 2.5 | 수정 페이지 연동 | ✅ | updateOrder() 연동 + 타입 오류 수정 | + +### Phase 3: 고급 기능 + +| # | 작업 항목 | 상태 | 비고 | +|---|----------|:----:|------| +| 3.1 | 견적서 → 수주 변환 | ⏳ | Order.createFromQuote() | +| 3.2 | 생산지시 생성 연동 | ⏳ | WorkOrder 연결 | +| 3.3 | 상태 흐름 관리 | ⏳ | DRAFT → CONFIRMED → ... | + +--- + +## 3. API 엔드포인트 설계 + +### 3.1 REST API + +| Method | Endpoint | 설명 | 우선순위 | +|--------|----------|------|:--------:| +| GET | `/api/v1/orders` | 수주 목록 조회 (페이징/필터) | 🔴 | +| GET | `/api/v1/orders/stats` | 수주 통계 | 🔴 | +| GET | `/api/v1/orders/{id}` | 수주 상세 조회 | 🔴 | +| POST | `/api/v1/orders` | 수주 생성 | 🔴 | +| PUT | `/api/v1/orders/{id}` | 수주 수정 | 🟡 | +| DELETE | `/api/v1/orders/{id}` | 수주 삭제 | 🟡 | +| PATCH | `/api/v1/orders/{id}/status` | 상태 변경 | 🟡 | +| POST | `/api/v1/orders/{id}/production-order` | 생산지시 생성 | 🟢 | +| POST | `/api/v1/orders/from-quote/{quoteId}` | 견적→수주 변환 | 🟢 | + +### 3.2 데이터 스키마 + +#### Order (수주) - 기존 모델 기반 +```typescript +interface Order { + id: number; + tenantId: number; + quoteId?: number; // 원본 견적 + orderNo: string; // 수주번호 (KD-TS-YYMMDD-NN) + orderTypeCode: 'ORDER' | 'PURCHASE'; + statusCode: 'DRAFT' | 'CONFIRMED' | 'IN_PROGRESS' | 'COMPLETED' | 'CANCELLED'; + clientId?: number; + clientName?: string; + siteName?: string; // 현장명 + quantity: number; + supplyAmount: number; + taxAmount: number; + totalAmount: number; + deliveryDate?: Date; + deliveryMethodCode?: string; + memo?: string; + createdBy?: number; + updatedBy?: number; + createdAt: Date; + updatedAt: Date; + // Relations + items?: OrderItem[]; + client?: Client; +} +``` + +#### OrderItem (수주 품목) +```typescript +interface OrderItem { + id: number; + orderId: number; + itemId?: number; + itemName: string; + specification?: string; + quantity: number; + unit?: string; + unitPrice: number; + supplyAmount: number; + taxAmount: number; + totalAmount: number; + sortOrder: number; +} +``` + +--- + +## 4. 작업 절차 + +### Step 1: API 개발 (Backend) + +``` +1. OrderService 생성 + ├── index(): 목록 조회 (페이징, 필터링) + ├── show(): 상세 조회 + ├── store(): 생성 + ├── update(): 수정 + ├── destroy(): 삭제 + ├── updateStatus(): 상태 변경 + ├── stats(): 통계 조회 + └── createFromQuote(): 견적→수주 변환 + +2. OrderController 생성 + ├── FormRequest DI + └── ApiResponse::handle() 사용 + +3. FormRequest 생성 + ├── StoreOrderRequest + └── UpdateOrderRequest + +4. 라우트 등록 + └── Route::prefix('orders')->group(...) + +5. Swagger 문서 작성 + └── app/Swagger/v1/OrderApi.php +``` + +### Step 2: Frontend 연동 + +``` +1. actions.ts 생성 + ├── getOrders(): 목록 조회 + ├── getOrderById(): 상세 조회 + ├── createOrder(): 생성 + ├── updateOrder(): 수정 + ├── deleteOrder(): 삭제 + ├── updateOrderStatus(): 상태 변경 + └── getOrderStats(): 통계 조회 + +2. 페이지별 연동 + ├── page.tsx: SAMPLE_ORDERS → getOrders() + ├── [id]/page.tsx: Mock → getOrderById() + ├── new/page.tsx: Mock → createOrder() + └── [id]/edit/page.tsx: Mock → updateOrder() +``` + +--- + +## 5. 의존성 + +### 5.1 필수 선행 작업 +- **없음** - Order 모델 이미 존재, 바로 작업 가능 + +### 5.2 연관 기능 (선택적) +- **견적관리 (Quote)**: 견적→수주 변환 시 필요 +- **거래처관리 (Client)**: 거래처 연동 +- **품목관리 (Item)**: 품목 마스터 연동 + +### 5.3 후속 연동 +- **작업지시 (WorkOrder)**: 생산지시 생성 시 `sales_order_id` 연결 +- **출하관리**: 수주 완료 후 출하 처리 + +--- + +## 6. 참고 문서 + +- **빠른 시작**: `docs/quickstart/quick-start.md` +- **API 규칙**: `docs/standards/api-rules.md` +- **품질 체크리스트**: `docs/standards/quality-checklist.md` +- **DB 스키마**: `docs/specs/database-schema.md` +- **Swagger 가이드**: `docs/guides/swagger-guide.md` + +### 참고 코드 +- **작업지시 API (참고용)**: `api/app/Http/Controllers/Api/V1/WorkOrderController.php` +- **공정관리 actions.ts (참고용)**: `react/src/components/process-management/actions.ts` + +--- + +## 7. 검증 방법 + +### 7.1 API 테스트 +```bash +# 목록 조회 +curl -X GET "http://api.sam.kr/api/v1/orders" -H "X-Api-Key: ..." + +# 상세 조회 +curl -X GET "http://api.sam.kr/api/v1/orders/1" -H "X-Api-Key: ..." + +# 통계 조회 +curl -X GET "http://api.sam.kr/api/v1/orders/stats" -H "X-Api-Key: ..." +``` + +### 7.2 성공 기준 +| 기준 | 측정 방법 | +|------|----------| +| API CRUD 동작 | Swagger UI 테스트 통과 | +| 목록 페이지 | 실제 데이터 표시 | +| 상세 페이지 | 수주 정보 정상 표시 | +| 등록/수정 | 데이터 저장 및 조회 | +| 상태 변경 | DRAFT → CONFIRMED 전환 | + +--- + +## 8. 자기완결성 점검 + +| # | 검증 항목 | 상태 | 비고 | +|---|----------|:----:|------| +| 1 | 작업 목적이 명확한가? | ✅ | Mock → API 연동 | +| 2 | 성공 기준이 정의되어 있는가? | ✅ | 섹션 7 참조 | +| 3 | 작업 범위가 구체적인가? | ✅ | Phase 1-3 단계별 정의 | +| 4 | 의존성이 명시되어 있는가? | ✅ | 선행 작업 없음 | +| 5 | 참고 파일 경로가 정확한가? | ✅ | 모든 경로 검증됨 | +| 6 | 단계별 절차가 실행 가능한가? | ✅ | Step 1-2 상세 정의 | +| 7 | 검증 방법이 명시되어 있는가? | ✅ | curl 테스트 + 기준 | +| 8 | 모호한 표현이 없는가? | ✅ | 구체적 파일/엔드포인트 명시 | + +--- + +*이 문서는 독립 세션에서 바로 작업 시작 가능하도록 설계되었습니다.* \ No newline at end of file