# 공정관리 (Process Management) API 연동 계획

> **작성일**: 2025-01-08
> **목적**: 공정관리 기능 검증 및 테스트
> **상태**: ✅ 검증 완료

---

## 📍 현재 진행 상태

| 항목 | 내용 |
|------|------|
| **마지막 완료 작업** | Phase 3: 개별 품목 연결 기능 (process_items) |
| **다음 작업** | 완료 (Phase 2는 선택사항) |
| **진행률** | 5/5 (100%) - Phase 1 + Phase 3 완료 |
| **마지막 업데이트** | 2026-01-08 |

---

## 1. 개요

### 1.1 기능 설명
공정관리는 MES 시스템의 기초 데이터로, 생산 공정을 정의하고 관리하는 기능입니다.
작업지시 생성 시 공정 유형(process_type)으로 연결되며, 자동 분류 규칙을 통해 품목별 공정 배정을 자동화합니다.

### 1.2 현재 구현 상태 분석

#### API (Laravel) - ✅ 완료
| 구성요소 | 파일 경로 | 상태 |
|---------|----------|:----:|
| Model | `api/app/Models/Process.php` | ✅ |
| Model | `api/app/Models/ProcessClassificationRule.php` | ✅ |
| Model | `api/app/Models/ProcessItem.php` | ✅ (Phase 3) |
| Migration | `api/database/migrations/2026_01_08_180607_create_process_items_table.php` | ✅ |
| Service | `api/app/Services/ProcessService.php` | ✅ |
| Controller | `api/app/Http/Controllers/V1/ProcessController.php` | ✅ |
| FormRequest | `api/app/Http/Requests/V1/Process/StoreProcessRequest.php` | ✅ |
| FormRequest | `api/app/Http/Requests/V1/Process/UpdateProcessRequest.php` | ✅ |
| Swagger | `api/app/Swagger/v1/ProcessApi.php` | ✅ |
| Route | `/api/v1/processes` | ✅ |

#### Frontend (React/Next.js) - ✅ API 연동 완료
| 구성요소 | 파일 경로 | 상태 |
|---------|----------|:----:|
| 목록 페이지 | `react/src/app/[locale]/(protected)/master-data/process-management/page.tsx` | ✅ |
| 등록 페이지 | `react/src/app/[locale]/(protected)/master-data/process-management/new/page.tsx` | ✅ |
| 상세 페이지 | `react/src/app/[locale]/(protected)/master-data/process-management/[id]/page.tsx` | ✅ |
| 수정 페이지 | `react/src/app/[locale]/(protected)/master-data/process-management/[id]/edit/page.tsx` | ✅ |
| 목록 컴포넌트 | `react/src/components/process-management/ProcessListClient.tsx` | ✅ |
| 폼 컴포넌트 | `react/src/components/process-management/ProcessForm.tsx` | ✅ |
| 상세 컴포넌트 | `react/src/components/process-management/ProcessDetail.tsx` | ✅ |
| 규칙 모달 | `react/src/components/process-management/RuleModal.tsx` | ✅ |
| **actions.ts** | `react/src/components/process-management/actions.ts` | ✅ |

### 1.3 관련 URL
| 화면 | URL | 설명 |
|------|-----|------|
| 공정목록 | `/master-data/process-management` | 토글 기능 포함 |
| 공정등록 | `/master-data/process-management/new` | 모달 - 규칙추가 |
| 공정상세 | `/master-data/process-management/{id}` | 상세 정보 |
| 공정수정 | `/master-data/process-management/{id}/edit` | 수정 폼 |

### 1.4 연관관계
```
┌─────────────────┐      process_type      ┌─────────────────┐
│    Process      │ ───────────────────────│   WorkOrder     │
│   (공정관리)     │   screen/slat/bending  │  (작업지시)      │
└─────────────────┘                        └─────────────────┘
        │
        ├── classificationRules (패턴 규칙)
        │   ▼
        │   ┌─────────────────────────┐
        │   │ ProcessClassificationRule│
        │   │   (자동 분류 규칙)        │
        │   └─────────────────────────┘
        │
        └── processItems (개별 품목) ← Phase 3
            ▼
        ┌─────────────────────────┐        ┌─────────────────┐
        │     ProcessItem         │────────│      Item       │
        │   (공정-품목 연결)       │        │    (품목)        │
        └─────────────────────────┘        └─────────────────┘
```

---

## 2. API 엔드포인트

### 2.1 REST API (구현 완료)
| Method | Endpoint | 설명 | 상태 |
|--------|----------|------|:----:|
| GET | `/api/v1/processes` | 공정 목록 조회 (검색/페이징) | ✅ |
| GET | `/api/v1/processes/{id}` | 공정 상세 조회 | ✅ |
| POST | `/api/v1/processes` | 공정 생성 | ✅ |
| PUT | `/api/v1/processes/{id}` | 공정 수정 | ✅ |
| DELETE | `/api/v1/processes/{id}` | 공정 삭제 | ✅ |
| DELETE | `/api/v1/processes` | 공정 일괄 삭제 | ✅ |
| PATCH | `/api/v1/processes/{id}/toggle` | 공정 상태 토글 | ✅ |
| GET | `/api/v1/processes/options` | 드롭다운용 옵션 목록 | ✅ |
| GET | `/api/v1/processes/stats` | 공정 통계 | ✅ |

### 2.2 actions.ts 구현 함수 (완료)
```typescript
// 목록/조회
getProcessList(params)      // 목록 조회
getProcessById(id)          // 상세 조회
getProcessOptions()         // 드롭다운 옵션
getProcessStats()           // 통계 조회

// CRUD
createProcess(data)         // 생성
updateProcess(id, data)     // 수정
deleteProcess(id)           // 삭제
deleteProcesses(ids)        // 일괄 삭제
toggleProcessActive(id)     // 상태 토글

// 보조
getDepartmentOptions()      // 부서 옵션 (분류 규칙용)
getItemList(params)         // 품목 목록 (분류 규칙용)
```

---

## 3. 데이터 스키마

### 3.1 Process (공정)
```typescript
interface Process {
  id: string;
  processCode: string;       // P-001, P-002
  processName: string;       // 공정명
  description?: string;      // 공정 설명
  processType: '생산' | '검사' | '포장' | '조립';
  department: string;        // 담당 부서
  workLogTemplate?: string;  // 작업일지 양식
  classificationRules: ClassificationRule[];
  requiredWorkers: number;   // 필요 작업자 수
  equipmentInfo?: string;    // 설비 정보
  workSteps: string[];       // 작업 단계
  note?: string;
  status: '사용중' | '미사용';
  createdAt: string;
  updatedAt: string;
}
```

### 3.2 ClassificationRule (자동 분류 규칙)
```typescript
interface ClassificationRule {
  id: string;
  registrationType: 'pattern' | 'individual';  // 패턴 규칙 vs 개별 품목
  ruleType: '품목코드' | '품목명' | '품목구분';
  matchingType: 'startsWith' | 'endsWith' | 'contains' | 'equals';
  conditionValue: string;
  priority: number;
  description?: string;
  isActive: boolean;
  createdAt: string;
}
```

### 3.3 ProcessItem (공정-품목 연결) - Phase 3 추가
```typescript
// API 응답 스키마
interface ApiProcessItem {
  id: number;
  process_id: number;
  item_id: number;
  priority: number;
  is_active: boolean;
  item?: {
    id: number;
    code: string;
    name: string;
  };
}

// DB 테이블: process_items
// - id (PK)
// - process_id (FK → processes)
// - item_id (FK → items)
// - priority (정렬 순서)
// - is_active (사용 여부)
// - created_at, updated_at
```

### 3.4 API 요청/응답 변환

#### 요청 (Frontend → API)
```typescript
// 패턴 규칙과 개별 품목 분리
{
  classification_rules: [  // 패턴 규칙만
    { rule_type, matching_type, condition_value, ... }
  ],
  item_ids: [123, 456, 789]  // 개별 품목 ID 배열
}
```

#### 응답 (API → Frontend)
```typescript
// process_items를 individual 규칙으로 변환
{
  classification_rules: [...],  // 패턴 규칙
  process_items: [              // 개별 품목 연결
    { id, process_id, item_id, priority, is_active, item: {...} }
  ]
}
```

---

## 4. 작업 범위

### Phase 1: 검증 및 테스트 (완료 - 2026-01-08)

| # | 작업 항목 | 상태 | 비고 |
|---|----------|:----:|------|
| 1.1 | 목록 조회 테스트 | ✅ | 검색, 탭 필터 정상 |
| 1.2 | 등록 기능 테스트 | ✅ | 정상 (담당부서는 DB 데이터 의존) |
| 1.3 | 수정 기능 테스트 | ✅ | 필요인원 변경/저장 정상 |
| 1.4 | 삭제 기능 테스트 | ⏭️ | 데이터 보존으로 생략 |
| 1.5 | 토글 기능 테스트 | ✅ | 사용중↔미사용 전환 정상 |

### 📋 참고사항

- **담당부서 드롭다운**: departments 테이블 데이터에 의존. 데이터 없으면 빈 드롭다운 (정상 동작)

### Phase 2: 개선 사항 (선택)

| # | 작업 항목 | 상태 | 비고 |
|---|----------|:----:|------|
| 2.1 | 공정 순서 드래그앤드롭 | ⏭️ | 후순위 |
| 2.2 | 작업 지침서 PDF 업로드 | ⏭️ | 후순위 |
| 2.3 | 공정 흐름도 시각화 | ⏭️ | 후순위 |

### Phase 3: 개별 품목 연결 기능 (완료 - 2026-01-08)

#### 배경
- 기존 분류 규칙에서 400개 이상의 품목 코드를 `,` 구분자로 저장 시도
- `condition_value` VARCHAR(255) 필드 초과 → API 422 에러 발생
- 해결: 개별 품목은 별도 테이블(`process_items`)로 관계형 저장

#### 완료 작업

| # | 작업 항목 | 상태 | 파일/위치 |
|---|----------|:----:|----------|
| 3.1 | ProcessItem 모델 생성 | ✅ | `api/app/Models/ProcessItem.php` |
| 3.2 | process_items 마이그레이션 | ✅ | `api/database/migrations/2026_01_08_180607_*` |
| 3.3 | Process 모델 관계 추가 | ✅ | `processItems()` HasMany |
| 3.4 | ProcessService 수정 | ✅ | `syncProcessItems()` 메서드 추가 |
| 3.5 | Validation 업데이트 | ✅ | `item_ids` 배열 검증 추가 |
| 3.6 | Swagger 문서 업데이트 | ✅ | `ProcessItem` 스키마 추가 |
| 3.7 | Frontend actions.ts 수정 | ✅ | 요청/응답 변환 로직 |

#### 핵심 변경 사항

**API 측 (Laravel)**
```php
// ProcessService.php
private function syncProcessItems(Process $process, array $itemIds): void
{
    $process->processItems()->delete();
    foreach ($itemIds as $index => $itemId) {
        ProcessItem::create([
            'process_id' => $process->id,
            'item_id' => $itemId,
            'priority' => $index,
            'is_active' => true,
        ]);
    }
}
```

**Frontend 측 (Next.js)**
```typescript
// actions.ts
// 패턴 규칙과 개별 품목 분리
const patternRules = data.classificationRules.filter(
  (rule) => rule.registrationType === 'pattern'
);
const individualRules = data.classificationRules.filter(
  (rule) => rule.registrationType === 'individual'
);
// item_ids 추출
const itemIds = individualRules.flatMap((rule) =>
  rule.conditionValue.split(',').map((id) => parseInt(id.trim(), 10))
);
```

---

## 5. 주요 기능 상세

### 5.1 토글 기능
- 목록에서 각 공정의 사용/미사용 상태를 토글
- `PATCH /api/v1/processes/{id}/toggle` 호출
- 미사용 공정은 작업지시 생성 시 선택 불가

### 5.2 규칙 추가 (모달)
- 자동 분류 규칙을 통해 품목별 공정 자동 배정
- 우선순위(priority)에 따라 규칙 적용 순서 결정
- include/exclude로 포함/제외 규칙 설정

### 5.3 양식 보기 (모달)
- 작업일지 템플릿 미리보기
- HTML/마크다운 형식 지원

---

## 6. 의존성

### 6.1 필수 선행 작업
- **없음** (기초 데이터)

### 6.2 후속 연동
- **작업지시 (WorkOrder)**: 공정 유형 선택 (process_type: screen/slat/bending)
- **품목관리 (Item)**: 자동 분류 규칙 적용

---

## 7. 검증 방법

### 7.1 테스트 체크리스트

| 기능 | 테스트 항목 | 예상 결과 |
|------|-----------|----------|
| 목록 조회 | 페이지 로드 | 공정 목록 표시 |
| 검색 | "생산" 검색 | 필터링된 결과 |
| 탭 필터 | "사용중" 탭 클릭 | 사용중 공정만 표시 |
| 등록 | 새 공정 등록 | 목록에 추가됨 |
| 수정 | 공정명 변경 | 변경 반영됨 |
| 삭제 | 공정 삭제 | 목록에서 제거됨 |
| 토글 | 상태 토글 | 사용중↔미사용 전환 |
| 규칙 추가 | 분류 규칙 추가 | 규칙 저장됨 |

### 7.2 API 테스트
```bash
# 목록 조회
curl -X GET "http://api.sam.kr/api/v1/processes" -H "X-Api-Key: ..."

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

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

# 토글
curl -X PATCH "http://api.sam.kr/api/v1/processes/1/toggle" -H "X-Api-Key: ..."
```

---

## 8. 참고 사항

### 8.1 공정 유형 (process_type)
현재 작업지시에서 사용하는 공정 유형:
- `screen`: 스크린 공정
- `slat`: 슬랫 공정
- `bending`: 절곡 공정

### 8.2 Process vs WorkOrder.process_type
- `Process` 모델: 공정의 메타데이터 (이름, 설명, 규칙 등)
- `WorkOrder.process_type`: 실제 작업지시에 적용된 공정 유형
- 향후 FK 연결로 확장성 확보 가능

---

## 9. 참고 문서

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

### 참고 코드
- **Controller**: `api/app/Http/Controllers/V1/ProcessController.php`
- **Service**: `api/app/Services/ProcessService.php`
- **actions.ts**: `react/src/components/process-management/actions.ts`

---

## 10. 자기완결성 점검

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

---

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