# 공정 작업기준 컴포넌트 (v2-process-work-standard) 구현 계획

> **작성일**: 2026-02-24
> **컴포넌트 ID**: `v2-process-work-standard`
> **성격**: 도메인 특화 컴포넌트 (v2-rack-structure와 동일 패턴)

---

## 1. 현황 분석

### 1.1 기존 DB 테이블 (참조용, 이미 존재)

| 테이블 | 역할 | 핵심 컬럼 |
|--------|------|----------|
| `item_info` | 품목 마스터 | id, item_name, item_number, company_code |
| `item_routing_version` | 라우팅 버전 | id, item_code, version_name, company_code |
| `item_routing_detail` | 라우팅 상세 (공정 배정) | id, routing_version_id, seq_no, process_code, company_code |
| `process_mng` | 공정 마스터 | id, process_code, process_name, company_code |

### 1.2 신규 생성 필요 테이블

**`process_work_item`** - 작업 항목 (검사 장비 준비, 외관 검사 등)

| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | VARCHAR PK | UUID |
| company_code | VARCHAR NOT NULL | 멀티테넌시 |
| routing_detail_id | VARCHAR NOT NULL | item_routing_detail.id FK |
| work_phase | VARCHAR NOT NULL | Config의 phases[].key 값 (예: 'PRE', 'IN', 'POST' 또는 사용자 정의) |
| title | VARCHAR NOT NULL | 항목 제목 (예: 검사 장비 준비) |
| is_required | VARCHAR | 'Y' / 'N' |
| sort_order | INTEGER | 표시 순서 |
| description | TEXT | 비고/설명 |
| created_date | TIMESTAMP | 생성일 |
| updated_date | TIMESTAMP | 수정일 |
| writer | VARCHAR | 작성자 |

**`process_work_item_detail`** - 작업 항목 상세 (버니어 캘리퍼스 상태 소정 등)

| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | VARCHAR PK | UUID |
| company_code | VARCHAR NOT NULL | 멀티테넌시 |
| work_item_id | VARCHAR NOT NULL | process_work_item.id FK |
| detail_type | VARCHAR | 'CHECK' / 'INSPECTION' / 'MEASUREMENT' 등 |
| content | VARCHAR NOT NULL | 상세 내용 |
| is_required | VARCHAR | 'Y' / 'N' |
| sort_order | INTEGER | 표시 순서 |
| remark | TEXT | 비고 |
| created_date | TIMESTAMP | 생성일 |
| updated_date | TIMESTAMP | 수정일 |
| writer | VARCHAR | 작성자 |

### 1.3 데이터 흐름 (5단계 연쇄)

```
item_info (품목)
  └─→ item_routing_version (라우팅 버전)
        └─→ item_routing_detail (공정 배정)  ← JOIN → process_mng (공정명)
              └─→ process_work_item (작업 항목, phase별)
                    └─→ process_work_item_detail (상세)
```

---

## 2. 파일 구조 계획

### 2.1 프론트엔드 (컴포넌트 등록)

```
frontend/lib/registry/components/v2-process-work-standard/
├── index.ts                              # createComponentDefinition
├── types.ts                              # 타입 정의
├── config.ts                             # 기본 설정
├── ProcessWorkStandardRenderer.tsx       # AutoRegisteringComponentRenderer
├── ProcessWorkStandardConfigPanel.tsx    # 설정 패널
├── ProcessWorkStandardComponent.tsx      # 메인 UI (좌우 분할)
├── components/
│   ├── ItemProcessSelector.tsx           # 좌측: 품목/라우팅/공정 아코디언 트리
│   ├── WorkStandardEditor.tsx            # 우측: 작업기준 편집 영역 전체
│   ├── WorkPhaseSection.tsx              # Pre/In/Post 섹션 (3회 재사용)
│   ├── WorkItemCard.tsx                  # 작업 항목 카드
│   ├── WorkItemDetailList.tsx            # 상세 리스트
│   └── WorkItemAddModal.tsx              # 작업 항목 추가/수정 모달
├── hooks/
│   ├── useProcessWorkStandard.ts         # 전체 데이터 관리 훅
│   ├── useItemProcessTree.ts            # 좌측 트리 데이터 훅
│   └── useWorkItems.ts                   # 작업 항목 CRUD 훅
└── README.md
```

### 2.2 백엔드 (API)

```
backend-node/src/
├── routes/processWorkStandardRoutes.ts   # 라우트 정의
└── controllers/processWorkStandardController.ts  # 컨트롤러
```

### 2.3 DB 마이그레이션

```
db/migrations/XXX_create_process_work_standard_tables.sql
```

---

## 3. API 설계

| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/api/process-work-standard/items` | 품목 목록 (라우팅 있는 품목만) |
| GET | `/api/process-work-standard/items/:itemCode/routings` | 품목별 라우팅 버전 + 공정 목록 |
| GET | `/api/process-work-standard/routing-detail/:routingDetailId/work-items` | 공정별 작업 항목 목록 (phase별 그룹) |
| POST | `/api/process-work-standard/work-items` | 작업 항목 추가 |
| PUT | `/api/process-work-standard/work-items/:id` | 작업 항목 수정 |
| DELETE | `/api/process-work-standard/work-items/:id` | 작업 항목 삭제 |
| GET | `/api/process-work-standard/work-items/:workItemId/details` | 작업 항목 상세 목록 |
| POST | `/api/process-work-standard/work-item-details` | 상세 추가 |
| PUT | `/api/process-work-standard/work-item-details/:id` | 상세 수정 |
| DELETE | `/api/process-work-standard/work-item-details/:id` | 상세 삭제 |
| PUT | `/api/process-work-standard/save-all` | 전체 저장 (작업 항목 + 상세 일괄) |

---

## 4. 구현 단계 (TDD 기반)

### Phase 1: DB + API 기반

- [ ] 1-1. 마이그레이션 SQL 작성 (process_work_item, process_work_item_detail)
- [ ] 1-2. 마이그레이션 실행 및 테이블 생성 확인
- [ ] 1-3. 백엔드 라우트/컨트롤러 작성 (CRUD API)
- [ ] 1-4. API 테스트 (품목 목록, 라우팅 조회, 작업항목 CRUD)

### Phase 2: 컴포넌트 기본 구조

- [ ] 2-1. types.ts, config.ts, index.ts 작성 (컴포넌트 정의)
- [ ] 2-2. Renderer, ConfigPanel 작성 (V2 시스템 등록)
- [ ] 2-3. components/index.ts에 import 추가
- [ ] 2-4. getComponentConfigPanel.tsx에 매핑 추가
- [ ] 2-5. 화면 디자이너에서 컴포넌트 배치 가능 확인

### Phase 3: 좌측 패널 (품목/공정 선택)

- [ ] 3-1. useItemProcessTree 훅 구현 (품목 목록 + 라우팅 조회)
- [ ] 3-2. ItemProcessSelector 컴포넌트 (아코디언 + 공정 리스트)
- [ ] 3-3. 검색 기능 (품목명/공정명 검색)
- [ ] 3-4. 선택 상태 관리 + 우측 패널 연동

### Phase 4: 우측 패널 (작업기준 편집)

- [ ] 4-1. WorkStandardEditor 기본 레이아웃 (Pre/In/Post 3단 섹션)
- [ ] 4-2. useWorkItems 훅 (작업 항목 + 상세 CRUD)
- [ ] 4-3. WorkPhaseSection 컴포넌트 (섹션 헤더 + 카드 영역 + 상세 영역)
- [ ] 4-4. WorkItemCard 컴포넌트 (카드 UI + 카운트 배지)
- [ ] 4-5. WorkItemDetailList 컴포넌트 (상세 목록 + 인라인 편집)
- [ ] 4-6. WorkItemAddModal (작업 항목 추가/수정 모달 + 상세 추가)

### Phase 5: 통합 + 전체 저장

- [ ] 5-1. 전체 저장 기능 (변경사항 일괄 저장 API 연동)
- [ ] 5-2. 공정 선택 시 데이터 로딩/전환 처리
- [ ] 5-3. Empty State 처리 (데이터 없을 때 안내 UI)
- [ ] 5-4. 로딩/에러 상태 처리

### Phase 6: 마무리

- [ ] 6-1. 멀티테넌시 검증 (company_code 필터링)
- [ ] 6-2. 반응형 디자인 점검
- [ ] 6-3. README.md 작성

---

## 5. 핵심 UI 설계

### 5.1 전체 레이아웃

```
┌─────────────────────────────────────────────────────────────────────┐
│ v2-process-work-standard                                           │
├────────────────────┬────────────────────────────────────────────────┤
│ 품목 및 공정 선택    │ [품목명] - [공정명]              [전체 저장]   │
│                    │                                               │
│ [검색 입력]         │ ── 작업 전 (Pre-Work)  N개 항목 ── [+항목추가] │
│                    │ ┌────────┐ ┌─────────────────────────────┐    │
│ ▼ 볼트 M8x20       │ │카드    │ │ 상세 리스트 (선택 시 표시)    │    │
│   ★ 기본 라우팅     │ │       │ │                             │    │
│   ◉ 재단           │ └────────┘ └─────────────────────────────┘    │
│   ◉ 검사 ← 선택    │                                               │
│   ★ 버전2          │ ── 작업 중 (In-Work)  N개 항목 ── [+항목추가]  │
│                    │ ┌────────┐ ┌────────┐                        │
│ ▶ 기어 50T         │ │카드1   │ │카드2   │  (상세: 우측 표시)      │
│ ▶ 샤프트 D30       │ └────────┘ └────────┘                        │
│                    │                                               │
│                    │ ── 작업 후 (Post-Work)  N개 항목 ── [+항목추가] │
│                    │ (동일 구조)                                    │
├────────────────────┴────────────────────────────────────────────────┤
│ 30%               │                 70%                            │
└─────────────────────────────────────────────────────────────────────┘
```

### 5.2 WorkPhaseSection 내부 구조

```
── 작업 전 (Pre-Work)  4개 항목  ────────────────── [+ 작업항목 추가]
┌──────────────────────────────┬──────────────────────────────────────┐
│ 작업 항목 카드 목록            │ 선택된 항목 상세                       │
│                              │                                      │
│ ┌──────────────────────┐    │ [항목 제목]                 [+ 상세추가]│
│ │ ≡ 검사 장비 준비   ✏️ 🗑 │    │ ───────────────────────────────────  │
│ │   4개  필수          │    │ 순서│유형  │내용              │필수│관리│
│ └──────────────────────┘    │  1 │체크  │버니어 캘리퍼스... │필수│✏️🗑│
│                              │  2 │체크  │마이크로미터...   │선택│✏️🗑│
│ ┌──────────────────────┐    │  3 │체크  │검사대 청소       │선택│✏️🗑│
│ │ ≡ 측정 도구 확인   ✏️ 🗑 │    │  4 │체크  │검사 기록지 준비  │필수│✏️🗑│
│ │   2개  선택          │    │                                      │
│ └──────────────────────┘    │                                      │
└──────────────────────────────┴──────────────────────────────────────┘
```

### 5.3 작업 항목 추가 모달

```
┌─────────────────────────────────────────────┐
│ 작업 항목 추가                          ✕    │
├─────────────────────────────────────────────┤
│ 기본 정보                                    │
│                                             │
│ 항목 제목 *           필수 여부               │
│ [                 ]   [필수      ▼]          │
│                                             │
│ 비고                                        │
│ [                                         ] │
│                                             │
│ 상세 항목                       [+ 상세 추가] │
│ ┌───┬──────┬──────────────┬────┬────┐      │
│ │순서│유형  │내용           │필수│관리│      │
│ ├───┼──────┼──────────────┼────┼────┤      │
│ │ 1 │체크  │              │필수│ 🗑 │      │
│ └───┴──────┴──────────────┴────┴────┘      │
│                                             │
│              [취소]  [저장]                   │
└─────────────────────────────────────────────┘
```

---

## 6. 컴포넌트 Config 설계

### 6.1 설정 패널 UI 구조

```
┌─────────────────────────────────────────────────┐
│ 공정 작업기준 설정                                 │
├─────────────────────────────────────────────────┤
│                                                 │
│ ── 데이터 소스 설정 ──────────────────────────    │
│                                                 │
│ 품목 테이블                                      │
│ [item_info                              ▼]     │
│ 품목명 컬럼            품목코드 컬럼               │
│ [item_name         ▼]  [item_number    ▼]      │
│                                                 │
│ 라우팅 버전 테이블                                │
│ [item_routing_version                   ▼]     │
│ 품목 연결 컬럼 (FK)                               │
│ [item_code                              ▼]     │
│                                                 │
│ 라우팅 상세 테이블                                │
│ [item_routing_detail                    ▼]     │
│                                                 │
│ 공정 마스터 테이블                                │
│ [process_mng                            ▼]     │
│                                                 │
│ ── 작업 단계 설정 ──────────────────────────     │
│                                                 │
│ ┌────┬────────────────────┬─────────────┬───┐  │
│ │순서│ 단계 키(DB저장용)    │ 표시 이름    │관리│  │
│ ├────┼────────────────────┼─────────────┼───┤  │
│ │ 1  │ PRE                │ 작업 전      │ 🗑 │  │
│ │ 2  │ IN                 │ 작업 중      │ 🗑 │  │
│ │ 3  │ POST               │ 작업 후      │ 🗑 │  │
│ └────┴────────────────────┴─────────────┴───┘  │
│                         [+ 단계 추가]            │
│                                                 │
│ ── 상세 유형 옵션 ──────────────────────────     │
│                                                 │
│ ┌────────────────────┬─────────────┬───┐       │
│ │ 유형 값(DB저장용)    │ 표시 이름    │관리│       │
│ ├────────────────────┼─────────────┼───┤       │
│ │ CHECK              │ 체크        │ 🗑 │       │
│ │ INSPECTION         │ 검사        │ 🗑 │       │
│ │ MEASUREMENT        │ 측정        │ 🗑 │       │
│ └────────────────────┴─────────────┴───┘       │
│                        [+ 유형 추가]             │
│                                                 │
│ ── UI 설정 ──────────────────────────           │
│                                                 │
│ 좌우 분할 비율                                   │
│ [30        ] %                                  │
│                                                 │
│ 좌측 패널 제목                                   │
│ [품목 및 공정 선택                        ]      │
│                                                 │
│ 읽기 전용 모드                                   │
│ [ ] 활성화                                      │
│                                                 │
└─────────────────────────────────────────────────┘
```

### 6.2 Config 타입 정의

```typescript
// 작업 단계 정의 (사용자가 추가/삭제/이름변경 가능)
interface WorkPhaseDefinition {
  key: string;       // DB 저장용 키 (예: "PRE", "IN", "POST", "QC")
  label: string;     // 화면 표시명 (예: "작업 전 (Pre-Work)")
  sortOrder: number; // 표시 순서
}

// 상세 유형 정의 (사용자가 추가/삭제 가능)
interface DetailTypeDefinition {
  value: string;     // DB 저장용 값 (예: "CHECK")
  label: string;     // 화면 표시명 (예: "체크")
}

// 데이터 소스 설정 (사용자가 테이블 지정 가능)
interface DataSourceConfig {
  // 품목 테이블
  itemTable: string;             // 기본: "item_info"
  itemNameColumn: string;        // 기본: "item_name"
  itemCodeColumn: string;        // 기본: "item_number"

  // 라우팅 버전 테이블
  routingVersionTable: string;   // 기본: "item_routing_version"
  routingItemFkColumn: string;   // 기본: "item_code" (품목과 연결하는 FK)
  routingVersionNameColumn: string; // 기본: "version_name"

  // 라우팅 상세 테이블
  routingDetailTable: string;    // 기본: "item_routing_detail"

  // 공정 마스터 테이블
  processTable: string;          // 기본: "process_mng"
  processNameColumn: string;     // 기본: "process_name"
  processCodeColumn: string;     // 기본: "process_code"
}

// 전체 Config
interface ProcessWorkStandardConfig {
  // 데이터 소스 설정
  dataSource: DataSourceConfig;

  // 작업 단계 정의 (기본 3개, 사용자가 추가/삭제/수정 가능)
  phases: WorkPhaseDefinition[];
  // 기본값: [
  //   { key: "PRE",  label: "작업 전 (Pre-Work)",  sortOrder: 1 },
  //   { key: "IN",   label: "작업 중 (In-Work)",   sortOrder: 2 },
  //   { key: "POST", label: "작업 후 (Post-Work)",  sortOrder: 3 },
  // ]

  // 상세 유형 옵션 (사용자가 추가/삭제 가능)
  detailTypes: DetailTypeDefinition[];
  // 기본값: [
  //   { value: "CHECK",       label: "체크" },
  //   { value: "INSPECTION",  label: "검사" },
  //   { value: "MEASUREMENT", label: "측정" },
  // ]

  // UI 설정
  splitRatio?: number;           // 좌우 분할 비율, 기본: 30
  leftPanelTitle?: string;       // 좌측 패널 제목, 기본: "품목 및 공정 선택"
  readonly?: boolean;            // 읽기 전용 모드, 기본: false
}
```

### 6.3 커스터마이징 시나리오 예시

**시나리오 A: 제조업 (기본)**
```
단계: 작업 전 → 작업 중 → 작업 후
유형: 체크, 검사, 측정
```

**시나리오 B: 품질검사 강화 회사**
```
단계: 준비 → 검사 → 판정 → 기록 → 보관
유형: 육안검사, 치수검사, 강도검사, 내구검사, 기능검사
```

**시나리오 C: 단순 2단계 회사**
```
단계: 사전점검 → 사후점검
유형: 확인, 기록
```

**시나리오 D: 다른 테이블 사용 회사**
```
품목 테이블: product_master (item_info 대신)
공정 테이블: operation_mng (process_mng 대신)
```

### 6.4 DB 설계 반영 사항

`work_phase` 컬럼은 고정 ENUM이 아니라 **사용자 정의 키(VARCHAR)** 로 저장합니다.
- Config에서 `phases[].key` 로 정의한 값이 DB에 저장됨
- 예: "PRE", "IN", "POST" 또는 "PREPARE", "INSPECT", "JUDGE", "RECORD", "STORE"
- 회사별 Config에 따라 다른 값이 저장되므로, 조회 시 Config의 phases 정의를 기준으로 섹션을 렌더링

---

## 7. 등록 체크리스트

| 항목 | 파일 | 작업 |
|------|------|------|
| 컴포넌트 정의 | `v2-process-work-standard/index.ts` | createComponentDefinition |
| 렌더러 등록 | `v2-process-work-standard/...Renderer.tsx` | registerSelf() |
| 컴포넌트 로드 | `components/index.ts` | import 추가 |
| 설정 패널 매핑 | `getComponentConfigPanel.tsx` | CONFIG_PANEL_MAP 추가 |
| 라우트 등록 | `backend-node/src/app.ts` | router.use() 추가 |

---

## 8. 의존성

- 외부 라이브러리 추가: 없음 (기존 shadcn/ui + Lucide 아이콘만 사용)
- 기존 API 재사용: dataRoutes의 범용 CRUD는 사용하지 않고 전용 API 개발
  - 이유: 5단계 JOIN + phase별 그룹핑 등 범용 API로는 처리 불가