# 작업지시 (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 구현 함수 (완료)
```typescript
// 목록/조회
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 (작업지시)
```typescript
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 (상태)
```typescript
type WorkOrderStatus =
  | 'unassigned'    // 미배정
  | 'pending'       // 승인대기
  | 'waiting'       // 작업대기
  | 'in_progress'   // 작업중
  | 'completed'     // 작업완료
  | 'shipped';      // 출하완료
```

### 3.3 ProcessType (공정 유형)
```typescript
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 테스트
```bash
# 목록 조회
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 | 모호한 표현이 없는가? | ✅ | 구체적 경로 명시 |

---

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