sam-docs/plans/archive/process-management-plan.md

공정관리 (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 구현 함수 (완료)

// 목록/조회
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 (공정)

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 (자동 분류 규칙)

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 추가

// 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)

// 패턴 규칙과 개별 품목 분리
{
  classification_rules: [  // 패턴 규칙만
    { rule_type, matching_type, condition_value, ... }
  ],
  item_ids: [123, 456, 789]  // 개별 품목 ID 배열
}

응답 (API → Frontend)

// 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)

// 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)

// 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 테스트

# 목록 조회
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	모호한 표현이 없는가?	✅	구체적 경로 명시

---

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