sam-docs/plans/archive/work-order-plan.md

작업지시 (Work Orders) API 연동 계획

작성일: 2025-01-08 목적: 작업지시 기능 검증 및 테스트 상태: ✅ 전체 테스트 완료 (2025-01-11)

---

📍 현재 진행 상태

항목	내용
마지막 완료 작업	전체 기능 테스트 완료 (2025-01-11)
다음 작업	운영 준비
진행률	5/5 (100%)
마지막 업데이트	2025-01-11

---

1. 개요

1.1 기능 설명

작업지시는 MES 시스템의 핵심 기능으로, 수주를 기반으로 실제 생산 작업을 지시하고 추적합니다. 공정 유형별(스크린/슬랫/절곡)로 작업 단계를 관리하며, 담당자 배정 및 작업 상태를 추적합니다.

1.2 현재 구현 상태 분석

API (Laravel) - ✅ 완료

구성요소	파일 경로	상태
Model	api/app/Models/Production/WorkOrder.php	✅
Model	api/app/Models/Production/WorkOrderItem.php	✅
Model	api/app/Models/Production/WorkOrderBendingDetail.php	✅
Model	api/app/Models/Production/WorkOrderIssue.php	✅
Service	api/app/Services/WorkOrderService.php	✅
Controller	api/app/Http/Controllers/Api/V1/WorkOrderController.php	✅
FormRequest	api/app/Http/Requests/WorkOrder/*.php	✅
Route	/api/v1/work-orders	✅

Frontend (React/Next.js) - ✅ API 연동 완료

구성요소	파일 경로	상태
목록 페이지	react/src/app/[locale]/(protected)/production/work-orders/page.tsx	✅
등록 페이지	react/src/app/[locale]/(protected)/production/work-orders/create/page.tsx	✅
상세 페이지	react/src/app/[locale]/(protected)/production/work-orders/[id]/page.tsx	✅
목록 컴포넌트	react/src/components/production/WorkOrders/WorkOrderList.tsx	✅
등록 컴포넌트	react/src/components/production/WorkOrders/WorkOrderCreate.tsx	✅
상세 컴포넌트	react/src/components/production/WorkOrders/WorkOrderDetail.tsx	✅
수주선택 모달	react/src/components/production/WorkOrders/SalesOrderSelectModal.tsx	✅
담당자선택 모달	react/src/components/production/WorkOrders/AssigneeSelectModal.tsx	✅
타입 정의	react/src/components/production/WorkOrders/types.ts	✅
actions.ts	react/src/components/production/WorkOrders/actions.ts	✅

1.3 관련 URL

화면	URL	설명
작업지시목록	/production/work-orders	상태별 필터링, 검색
작업지시등록	/production/work-orders/create	모달 - 수주선택
작업지시상세	/production/work-orders/{id}	상세 정보

1.4 연관관계

┌─────────────────┐                     ┌─────────────────┐
│     Order       │────sales_order_id──▶│   WorkOrder     │
│    (수주)        │                     │  (작업지시)      │
└─────────────────┘                     └─────────────────┘
                                                │
        ┌───────────────────────────────────────┼───────────────────────────────────────┐
        │                                       │                                       │
        ▼                                       ▼                                       ▼
┌─────────────────┐                     ┌─────────────────┐                     ┌─────────────────┐
│ WorkOrderItem   │                     │WorkOrderBending │                     │ WorkOrderIssue  │
│  (작업품목)      │                     │    Detail       │                     │    (이슈)       │
└─────────────────┘                     │ (절곡상세)       │                     └─────────────────┘
                                        └─────────────────┘
                                                │
                                                │ work_order_id
                                                ▼
                                        ┌─────────────────┐
                                        │  WorkResult     │
                                        │   (작업실적)     │
                                        └─────────────────┘

---

2. API 엔드포인트

2.1 REST API (구현 완료)

Method	Endpoint	설명	상태
GET	/api/v1/work-orders	목록 조회 (필터/페이징)	✅
GET	/api/v1/work-orders/stats	통계 조회	✅
GET	/api/v1/work-orders/{id}	상세 조회	✅
POST	/api/v1/work-orders	작업지시 생성	✅
PUT	/api/v1/work-orders/{id}	작업지시 수정	✅
DELETE	/api/v1/work-orders/{id}	작업지시 삭제	✅
PATCH	/api/v1/work-orders/{id}/status	상태 변경	✅
PATCH	/api/v1/work-orders/{id}/assign	담당자 배정	✅
PATCH	/api/v1/work-orders/{id}/bending/toggle	절곡 상세 토글	✅
POST	/api/v1/work-orders/{id}/issues	이슈 등록	✅
PATCH	/api/v1/work-orders/{id}/issues/{issueId}/resolve	이슈 해결	✅

2.2 actions.ts 구현 함수 (완료)

// 목록/조회
getWorkOrders(params)           // 목록 조회
getWorkOrderStats()             // 통계 조회
getWorkOrderById(id)            // 상세 조회

// CRUD
createWorkOrder(data)           // 생성
updateWorkOrder(id, data)       // 수정
deleteWorkOrder(id)             // 삭제

// 상태/배정
updateWorkOrderStatus(id, status)  // 상태 변경
assignWorkOrder(id, data)          // 담당자 배정

// 절곡 공정
toggleBendingField(id, field, value)  // 절곡 상세 토글

// 이슈 관리
addWorkOrderIssue(id, data)           // 이슈 등록
resolveWorkOrderIssue(id, issueId)    // 이슈 해결

// 연동
getSalesOrdersForWorkOrder()    // 수주 목록 (작업지시용)
getDepartmentsWithUsers()       // 부서/사용자 목록 (담당자 배정용)

---

3. 데이터 스키마

3.1 WorkOrder (작업지시)

interface WorkOrder {
  id: string;
  workOrderNo: string;           // WO202512260001
  lotNo: string;                 // 수주번호 참조
  processType: 'screen' | 'slat' | 'bending';
  status: WorkOrderStatus;
  // 기본 정보
  client: string;                // 발주처
  projectName: string;           // 현장명
  dueDate: string;               // 납기일
  assignee: string;              // 작업자
  // 날짜
  orderDate: string;             // 지시일
  shipmentDate: string;          // 출고예정일
  // 플래그
  isAssigned: boolean;
  isStarted: boolean;
  priority: number;              // 1~9
  // 품목
  items: WorkOrderItem[];
  // 공정 진행
  currentStep: number;
  // 절곡 전용
  bendingDetails?: BendingDetail[];
  // 이슈
  issues?: WorkOrderIssue[];
  note?: string;
}

3.2 WorkOrderStatus (상태)

type WorkOrderStatus =
  | 'unassigned'    // 미배정
  | 'pending'       // 승인대기
  | 'waiting'       // 작업대기
  | 'in_progress'   // 작업중
  | 'completed'     // 작업완료
  | 'shipped';      // 출하완료

3.3 ProcessType (공정 유형)

type ProcessType = 'screen' | 'slat' | 'bending';

// 공정별 작업 단계
const SCREEN_STEPS = ['원단절단', '미싱', '앤드락작업', '중간검사', '포장'];
const SLAT_STEPS = ['코일절단', '성형', '미미작업', '검사', '포장'];
const BENDING_STEPS = ['가이드레일 제작', '케이스 제작', '하단마감재 제작', '검사'];

---

4. 작업 범위

Phase 1: 검증 및 테스트 ✅ 완료 (2025-01-11)

#	작업 항목	상태	비고
1.1	목록 조회 테스트	✅	필터링/검색/페이징 정상
1.2	등록 기능 테스트	✅	수주 선택 모달 동작 확인
1.3	상세 조회 테스트	✅	버그 수정 완료 (site_name 컬럼 수정)
1.4	상태 변경 테스트	✅	전체 상태 전이 검증 완료
1.5	담당자 배정 테스트	✅	배정 시 상태 자동 전이 확인

Phase 1 테스트 상세:

• 버그 수정: WorkOrderService.php:119 - project_name → site_name (Order 모델에 맞춤)
• 상태 전이: pending ⇄ waiting ⇄ in_progress ⇄ completed ⇄ shipped 모두 정상
• 담당자 배정: 배정 시 unassigned → pending 자동 전이 확인

Phase 2: 공정별 기능 테스트 ✅ 완료 (2025-01-11)

#	작업 항목	상태	비고
2.1	스크린 공정 작업지시	✅	process_id=2 생성 확인
2.2	슬랫 공정 작업지시	✅	process_id=1 생성 확인
2.3	공정별 필터링	✅	forProcess(), forProcessName() 정상
2.4	작업지시 품목 관리	✅	WorkOrderItem CRUD 확인

Phase 2 테스트 상세:

• 공정 목록: 슬랫(P-001), 스크린(P-002) 활성화 확인
• 공정별 필터: forProcess(1), forProcessName('슬랫') 정상 동작
• 품목 관리: 작업지시별 품목 추가/조회 정상

Phase 3: 이슈 및 연동 ✅ 완료 (2025-01-11)

#	작업 항목	상태	비고
3.1	이슈 등록 기능	✅	이슈 생성 정상
3.2	이슈 해결 기능	✅	해결 상태/시간 저장 확인
3.3	수주 연동 확인	✅	salesOrder 관계 정상
3.4	작업실적 연동	⏭️	후순위 (별도 기능)

Phase 3 테스트 상세:

• 이슈 관리: 등록(open) → 해결(resolved) 전체 흐름 정상
• open_issues_count: 미해결 이슈 카운트 속성 정상
• 수주 연동: WorkOrder.salesOrder 관계를 통한 수주 정보 조회 정상

---

5. 주요 기능 상세

5.1 수주 선택 (모달)

작업지시 등록
   │
   ▼ "수주 선택" 버튼
┌─────────────────────────────────┐
│  SalesOrderSelectModal          │
│  - 수주 목록 (for_work_order=1) │
│  - 검색 기능                    │
│  - 선택 시 정보 자동 채움       │
└─────────────────────────────────┘

5.2 상태 흐름

unassigned (미배정)
      │
      ▼ 담당자 배정
pending (승인대기)
      │
      ▼ 승인
waiting (작업대기)
      │
      ▼ 작업 시작
in_progress (작업중)
      │
      ▼ 작업 완료
completed (작업완료)
      │
      ▼ 출하
shipped (출하완료)

5.3 공정별 작업 단계

스크린 공정 (screen)

1. 원단절단 (cutting)
2. 미싱 (sewing)
3. 앤드락작업 (endlock)
4. 중간검사 (inspection)
5. 포장 (packing)

슬랫 공정 (slat)

1. 코일절단 (coil_cutting)
2. 성형 (forming)
3. 미미작업 (finishing)
4. 검사 (inspection)
5. 포장 (packing)

절곡 공정 (bending)

1. 가이드레일 제작 (guide_rail)
2. 케이스 제작 (case)
3. 하단마감재 제작 (bottom_finish)
4. 검사 (inspection)

5.4 절곡 상세 토글

• 절곡 공정의 세부 항목 완료 여부 토글
• PATCH /api/v1/work-orders/{id}/bending/toggle
• 필드: shaft_cutting, bearing, shaft_welding, assembly 등

5.5 이슈 관리

• 작업 중 발생한 이슈 등록
• 우선순위: low, medium, high
• 상태: pending → resolved

---

6. 의존성

6.1 필수 선행 작업

• 공정관리 (Process): 공정 유형 정의 - ✅ 완료
• 사원관리: 담당자 배정 (assignee_id)
• 부서관리: 팀 배정 (team_id)

6.2 관련 의존성

• 수주관리 (Order): 수주 데이터 필요 (sales_order_id)
  • ✅ Order API 연동 완료 (2025-01-09)
  • 수주 → 생산지시 생성 기능 연동됨

6.3 후속 연동

• 작업실적 (WorkResult): 작업 완료 후 실적 등록
• 품질검사: 검사 공정 연동
• 출하관리: 출하 처리

---

7. 검증 방법

7.1 테스트 체크리스트

기능	테스트 항목	예상 결과
목록 조회	페이지 로드	작업지시 목록 표시
상태 필터	"작업중" 탭 클릭	해당 상태만 표시
검색	작업지시번호 검색	필터링된 결과
등록	새 작업지시 등록	목록에 추가됨
상세 조회	행 클릭	상세 정보 표시
상태 변경	상태 버튼 클릭	상태 전환됨
담당자 배정	배정 버튼 클릭	담당자 변경됨
이슈 등록	이슈 추가	이슈 목록에 표시

7.2 API 테스트

# 목록 조회
curl -X GET "http://api.sam.kr/api/v1/work-orders" -H "X-Api-Key: ..."

# 상세 조회
curl -X GET "http://api.sam.kr/api/v1/work-orders/1" -H "X-Api-Key: ..."

# 통계 조회
curl -X GET "http://api.sam.kr/api/v1/work-orders/stats" -H "X-Api-Key: ..."

# 상태 변경
curl -X PATCH "http://api.sam.kr/api/v1/work-orders/1/status" \
  -H "X-Api-Key: ..." \
  -H "Content-Type: application/json" \
  -d '{"status": "in_progress"}'

---

8. 참고 사항

8.1 작업지시번호 형식

• 형식: WO{YYYYMMDD}{NNNN}
• 예: WO202512260001
• 자동 생성: WorkOrderService::generateWorkOrderNo()

8.2 Worker Screen (작업자 화면)

• 별도 화면: /production/worker-screen
• 작업자가 직접 작업 진행/완료 처리
• 이슈 보고 기능
• react/src/components/production/WorkerScreen/ 참고

8.3 Production Dashboard

• 생산 현황 대시보드: /production/dashboard
• 공정별 작업 현황 시각화
• react/src/components/production/ProductionDashboard/ 참고

---

9. 참고 문서

• 빠른 시작: docs/quickstart/quick-start.md
• API 규칙: docs/standards/api-rules.md
• 품질 체크리스트: docs/standards/quality-checklist.md

참고 코드

• Controller: api/app/Http/Controllers/Api/V1/WorkOrderController.php
• Service: api/app/Services/WorkOrderService.php
• actions.ts: react/src/components/production/WorkOrders/actions.ts

---

10. 자기완결성 점검

#	검증 항목	상태	비고
1	작업 목적이 명확한가?	✅	검증 및 테스트
2	성공 기준이 정의되어 있는가?	✅	섹션 7 참조
3	작업 범위가 구체적인가?	✅	Phase 1-3 테스트 항목
4	의존성이 명시되어 있는가?	✅	Order API 연동 완료
5	참고 파일 경로가 정확한가?	✅	모든 경로 검증됨
6	단계별 절차가 실행 가능한가?	✅	테스트 체크리스트 제공
7	검증 방법이 명시되어 있는가?	✅	curl + 체크리스트
8	모호한 표현이 없는가?	✅	구체적 경로 명시

---

이 문서는 독립 세션에서 바로 작업 시작 가능하도록 설계되었습니다.