sam-docs/changes/20250108_order_management_phase1.md

변경 내용 요약

날짜: 2025-01-08 작업자: Claude Code 이슈: Order Management API Phase 1.1

📋 변경 개요

수주관리(Order Management) API의 기본 CRUD 및 상태 관리 기능을 구현했습니다. WorkOrderService/Controller 패턴을 참고하여 SAM API 규칙을 준수하는 OrderService와 OrderController를 생성했습니다.

📁 수정/추가된 파일

신규 생성 (7개)

• app/Services/OrderService.php - 수주 비즈니스 로직 서비스
• app/Http/Controllers/Api/V1/OrderController.php - 수주 API 컨트롤러
• app/Http/Requests/Order/StoreOrderRequest.php - 생성 요청 검증
• app/Http/Requests/Order/UpdateOrderRequest.php - 수정 요청 검증
• app/Http/Requests/Order/UpdateOrderStatusRequest.php - 상태 변경 요청 검증
• app/Swagger/v1/OrderApi.php - Swagger API 문서

수정 (5개)

• routes/api.php - OrderController import 및 라우트 추가
• lang/ko/message.php - 수주 관련 메시지 키 추가
• lang/en/message.php - 수주 관련 메시지 키 추가
• lang/ko/error.php - 수주 에러 메시지 키 추가
• lang/en/error.php - 수주 에러 메시지 키 추가

🔧 상세 변경 사항

1. OrderService

기능:

• index() - 목록 조회 (검색/필터링/페이징)
• stats() - 통계 조회 (상태별 건수/금액)
• show() - 단건 조회
• store() - 생성 (수주번호 자동생성)
• update() - 수정 (완료/취소 상태 수정 불가)
• destroy() - 삭제 (진행중/완료 상태 삭제 불가)
• updateStatus() - 상태 변경 (전환 규칙 검증)

내부 메서드:

• validateStatusTransition() - 상태 전환 규칙 검증
• calculateItemAmounts() - 품목 금액 계산 (공급가, 세액, 합계)
• generateOrderNo() - 수주번호 자동 생성 (ORD{YYYYMMDD}{0001})

2. OrderController

엔드포인트:

• GET /api/v1/orders - 목록 조회
• GET /api/v1/orders/stats - 통계 조회
• POST /api/v1/orders - 생성
• GET /api/v1/orders/{id} - 단건 조회
• PUT /api/v1/orders/{id} - 수정
• DELETE /api/v1/orders/{id} - 삭제
• PATCH /api/v1/orders/{id}/status - 상태 변경

3. FormRequest 클래스

StoreOrderRequest:

• 주문유형, 카테고리, 거래처 정보, 금액, 배송, 품목 배열 검증

UpdateOrderRequest:

• Store와 유사하나 order_no 제외 (수정 불가)

UpdateOrderStatusRequest:

• status 필드만 검증 (Rule::in 사용)

4. 상태 전환 규칙

DRAFT → CONFIRMED, CANCELLED
CONFIRMED → IN_PROGRESS, CANCELLED
IN_PROGRESS → COMPLETED, CANCELLED
COMPLETED → (변경 불가)
CANCELLED → DRAFT (복구 가능)

5. Swagger 문서

스키마:

• Order, OrderItem, OrderPagination, OrderStats
• OrderCreateRequest, OrderUpdateRequest, OrderItemRequest, OrderStatusRequest

✅ 검증 완료 항목

• Pint 코드 스타일 검사 (6개 파일 자동 수정)
• Swagger 문서 생성 (php artisan l5-swagger:generate)
• Service-First 아키텍처 준수
• FormRequest 검증 패턴 사용
• i18n 메시지 키 사용
• Multi-tenancy (BelongsToTenant) 지원
• 감사 로그 컬럼 (created_by, updated_by, deleted_by)

⚠️ 배포 시 주의사항

• Order 모델은 기존에 이미 존재함 (마이그레이션 불필요)
• Swagger UI에서 API 테스트 가능: http://api.sam.kr/api-docs/index.html

🔗 관련 문서

• 계획 문서: docs/plans/order-management-plan.md
• 참고 패턴: app/Services/WorkOrderService.php, app/Http/Controllers/Api/V1/WorkOrderController.php