sam-docs/plans/integrated-master-plan.md

# 통합 개선 계획 — 제품코드 추적성 + 검사 단위 구조 정비

> **작성일**: 2026-02-27
> **목적**: 두 개선 계획(제품코드 추적성, 검사 단위 구조)을 하나의 순차적 실행 계획으로 통합
> **상태**: 🔄 통합 계획 수립 완료, Phase 0 실행 대기
> **원본 문서**:
> - [`product-code-traceability-plan.md`](./product-code-traceability-plan.md) (아카이브 참조)
> - [`document-system-improvement-plan.md`](./document-system-improvement-plan.md) (아카이브 참조)
> - [`document-system-improvement-review.md`](./document-system-improvement-review.md) (정책 결정 16건)
> **테스트**: [`integrated-test-scenarios.md`](./integrated-test-scenarios.md) (기능 단위 11개 FU)

---

## 📍 현재 진행 상태

| 항목 | 내용 |
|------|------|
| **마지막 완료 작업** | 통합 계획 수립 + 원본 2개 문서 분석 |
| **다음 작업** | Phase 0 - 사전 데이터 조사 |
| **진행률** | 0/7 Phase (0%) |
| **마지막 업데이트** | 2026-02-27 |

---

## 1. 왜 통합이 필요한가

두 계획은 **의존성이 교차**한다:

- 검사 단위 구조 정비(절곡 동적화)는 `work_order_items.options`에 `product_code`가 있어야 동작
- `product_code` 전파 버그를 먼저 수정하지 않으면 검사 API(`inspection-config`)가 불완전
- 별도로 작업하면 순서 혼선, 중복 작업, 회귀 위험 발생

**통합 효과**:
- 의존성 순서를 강제하여 작업 꼬임 방지
- 병렬 가능 작업 식별으로 효율 극대화
- 진행 상태를 한 곳에서 관리

---

## 2. 통합 Phase 총괄

| Phase | 명칭 | 원본 | 의존성 | 상태 | 상세 |
|:-----:|------|------|--------|:----:|------|
| **0** | 사전 데이터 조사 | product-code P0 | 없음 | ⏳ | [Phase 0-1 상세](./integrated-phase-0-1.md) |
| **1** | product_code 전파 버그 수정 | product-code P1 | Phase 0 | ⏳ | [Phase 0-1 상세](./integrated-phase-0-1.md) |
| **2A** | 절곡 검사 분석/설계 | document-system P1 | 없음 (**Phase 1과 병렬**) | ⏳ | [Phase 2 상세](./integrated-phase-2.md) |
| **2B** | 견적/수주 정합성 + 품질 FK | product-code P2+P3 | Phase 1 | ⏳ | [Phase 2 상세](./integrated-phase-2.md) |
| **3** | 절곡 검사 동적 구현 | document-system P2 | Phase 1 + 2A | ⏳ | [Phase 3 상세](./integrated-phase-3.md) |
| **4** | 절곡 재공품 + 결재 워크플로우 | document-system P3 | Phase 3 | ⏭️ | 마스터 요약만 |
| **5** | 완제품 마스터 + 출하 연결 | product-code P4 | Phase 2B | ⏭️ | 마스터 요약만 |
| **6** | 3관점 검사 + 수주별 뷰 | document-system P4 | Phase 3 + 기획자 | ⏭️ | 마스터 요약만 |

---

## 3. 의존성 다이어그램

```
                    ┌─────────────────────────────────────────────┐
                    │              실행 타임라인                     │
                    └─────────────────────────────────────────────┘

Phase 0 ─── Phase 1 ──┬── Phase 2B ──── Phase 5
  (조사)    (P/C 수정)  │   (견적/품질)    (FG 마스터)
                       │
Phase 2A ──────────────┼── Phase 3 ──── Phase 4 ──── Phase 6
  (절곡 분석)           │   (절곡 구현)    (재공품)      (3관점)
                       │
       ※ Phase 1 + 2A 병렬 가능
       ※ Phase 2B + 3 준비 부분 병렬 가능
       ※ Phase 4 + 5 독립 (부분 병렬 가능)

크리티컬 패스: Phase 0 → 1 → 3 → 4 → 6
```

### 병렬 실행 가능 조합

| 조합 | 설명 | 조건 |
|------|------|------|
| Phase 1 + 2A | product_code 수정 + 절곡 분석 동시 진행 | 2A는 코드 변경 없음 (분석만) |
| Phase 2B + 3 시작 | 견적/품질 + 절곡 구현 | Phase 1 완료 필수 |
| Phase 4 + 5 | 절곡 재공품 + FG 마스터 | 각각 Phase 3, 2B 완료 |

---

## 4. 공통 원칙

```
┌─────────────────────────────────────────────────────────────────┐
│  🎯 통합 핵심 원칙                                                │
├─────────────────────────────────────────────────────────────────┤
│  1. 컬럼 추가 정책: FK/조인키만 컬럼, 나머지는 options JSON       │
│  2. 기존 데이터 보존: 파괴적 변경 없이 점진적 개선                 │
│  3. 역추적 가능: 어떤 단계에서든 원래 제품코드로 돌아갈 수 있어야 함│
│  4. 네이밍 통일: Backend JSON=snake_case, Frontend=camelCase      │
│  5. 기존 동작 보존: 스크린/슬랫/조인트바 검사는 건드리지 않음      │
│  6. TemplateInspectionContent 통합: 신규 개발은 여기서 (C3)       │
│  7. BendingInspectionContent 레거시 동결: 유지만, 신규 기능 X      │
│  8. row_index = 개소 통일: 구성품은 field_key 인코딩 (C1)         │
│  9. EAV + options 병행: 두 데이터 경로 독립 운용 (C2)             │
│ 10. 롤백 = 템플릿 유무: document_template_id NULL → 레거시 (I4)   │
└─────────────────────────────────────────────────────────────────┘
```

### 변경 승인 정책

| 분류 | 예시 | 승인 |
|------|------|------|
| ✅ 즉시 가능 | options JSON 필드 추가, React 컴포넌트 내부 리팩토링, 프론트 표시 변경 | 불필요 |
| ⚠️ 컨펌 필요 | 서비스 로직 변경, 마이그레이션, API 엔드포인트 추가, 양식 시더 수정 | **필수** |
| 🔴 금지 | 기존 테이블 컬럼 삭제, 기존 스크린/슬랫 검사 로직 변경 | 별도 협의 |

---

## 5. 핵심 데이터 흐름 (통합 TO-BE)

```
견적(quotes)
 └─ product_code 컬럼 ✅ (Phase 2B)
 └─ calculation_inputs → items[].productCode
    │
    ▼ (createFromQuote)
수주(orders)
 └─ order_nodes.options → ✅ product_code, product_name
    │
    ▼ (createProductionOrder)
작업지시(work_orders)
 ├─ work_order_items.options → ✅ product_code (Phase 1 수정)
 ├─ inspection-config API → ✅ 공정 자동 판별 + BOM 기반 구성품 (Phase 3)
 ├─ TemplateInspectionContent → ✅ 동적 절곡 검사 (Phase 3)
 └─ document_data EAV → ✅ C1 field_key 인코딩
    │
    ▼
품질검사(inspections)
 └─ ✅ work_order_id FK (Phase 2B)
    │
    ▼
출하(shipments)
 └─ ✅ product_code 포함 (Phase 5)
```

---

## 6. Phase별 요약

### Phase 0: 사전 데이터 조사 ⏳

**목표**: 마이그레이션 영향 범위 파악 (읽기 전용, 위험 없음)

- SQL 4개 실행: order_nodes product_code 보유율, work_order_items source 비율, soft delete 건수, lot_no 중복
- 결과에 따라 Phase 1 보정 전략 조정

→ [상세: integrated-phase-0-1.md](./integrated-phase-0-1.md)

---

### Phase 1: product_code 전파 버그 수정 ⏳

**목표**: 모든 work_order_items 생성/수정 경로에서 product_code, product_name 전달

- 백엔드 5개 코드 경로 수정 (OrderService, WorkOrderService)
- 기존 데이터 보정 마이그레이션 (스냅샷 백업 후)
- 프론트 WorkerScreen/ProductionDashboard에 제품코드 표시
- **배포 순서**: 백엔드 → 마이그레이션 → 프론트

→ [상세: integrated-phase-0-1.md](./integrated-phase-0-1.md)

---

### Phase 2A: 절곡 검사 분석/설계 ⏳ (**Phase 1과 병렬 가능**)

**목표**: 절곡 구성품(검사 항목) 정보를 API에서 제공하는 구조 설계

- items/BOM 테이블에서 KWE01/KSS01/KSS02 구성품 확인
- 마감유형(S1/S2/S3)별 차이 분석
- DEFAULT_GAP_PROFILES 기준치 5130 대조
- inspection-config 범용 API 설계

→ [상세: integrated-phase-2.md](./integrated-phase-2.md)

---

### Phase 2B: 견적/수주 정합성 + 품질 FK ⏳

**목표**: quotes.product_code 활용 + inspections ↔ work_orders FK 연결

- 견적 저장 시 quotes.product_code 저장
- inspections 테이블에 work_order_id FK 마이그레이션
- 기존 데이터 보정 (lot_no 기반 역추적)
- **Phase 2B 내부에서 견적/품질 작업은 병렬 가능** (독립 경로)

→ [상세: integrated-phase-2.md](./integrated-phase-2.md)

---

### Phase 3: 절곡 검사 동적 구현 ⏳

**목표**: API 기반 동적 구성품 로딩으로 고정 로직 대체

- inspection-config API 구현 (BelongsToTenant 필수)
- TemplateInspectionContent buildBendingProducts → API 연동
- document_data EAV 저장/복원 검증 (C1 field_key)
- createInspectionDocument 트랜잭션 보강 (I2)
- 레거시(Path A) + 신규(Path B) 독립 동작 확인

→ [상세: integrated-phase-3.md](./integrated-phase-3.md)

---

### Phase 4: 절곡 재공품 + 결재 워크플로우 ⏭️

**목표**: BendingWip 양식 추가 + 결재 프론트 연동

| # | 작업 항목 | 비고 |
|---|----------|------|
| 4.1 | 절곡 재공품 mng 양식 시더 추가 | BendingWipInspectionContent 대응 |
| 4.2 | 결재 워크플로우 프론트 연동 | 작성→검토→승인 3단계 |
| 4.3 | React 기존 하드코딩 컴포넌트 전환 결정 | 프론트 담당자 협의 |

> 실행 시점에 상세 문서 별도 작성

---

### Phase 5: 완제품 마스터 + 출하 연결 ⏭️

**목표**: FG 품목 등록 + 출하 시 제품코드 포함 + orders.item_id

| # | 작업 항목 | 비고 |
|---|----------|------|
| 5.1 | 완제품(FG) 품목 자동 등록 방안 설계 | 견적 확정 시 or 수주 확정 시 |
| 5.2 | orders.item_id 설정 | FG 품목 등록 후 가능 |
| 5.3 | shipment_items에 product_code 포함 | 부분 출하 시 개소별 매핑 고려 |
| 5.4 | work_order_items.product_code 컬럼 승격 검토 | 통계 쿼리 성능용 |
| 5.5 | E2E 추적 검증 | 견적→출하→품질 전 구간 |

> 실행 시점에 상세 문서 별도 작성

---

### Phase 6: 3관점 검사 + 수주별 뷰 ⏭️

**목표**: 구성품별/개소별/수주별 3관점 검사 구조 + 수주별 읽기 전용 뷰

| # | 작업 항목 | 비고 |
|---|----------|------|
| 6.1 | 기획자와 3관점 화면 설계 협의 (I3) | 화면 구성·데이터 매핑·UI 설계 |
| 6.2 | 수주별 읽기 전용 뷰 구현 (I7) | 입력=개소별, 출력=수주별 |
| 6.3 | 개소별↔구성품별↔수주별 데이터 매핑 | |
| 6.4 | 5130 recordscreen JSON → EAV 변환 | 이관 설계 |

> 기획자 협의 후 상세 문서 별도 작성

---

## 7. 통합 성공 기준

### Phase 0-1 (product_code)

| 기준 | 수치 목표 |
|------|----------|
| WorkerScreen 제품코드 표시 | 100% |
| 신규 작업지시 product_code 포함 | NOT NULL |
| 기존 데이터 보정율 (source_order_item_id 있는 건) | 90% 이상 |
| 기존 기능 회귀 | 에러 0건 |
| API 성능 영향 | 5% 미만 |

### Phase 2A-2B (분석/견적/품질)

| 기준 | 수치 목표 |
|------|----------|
| KWE01/KSS01/KSS02 구성품 분석 완료 | 3종 이상 |
| DEFAULT_GAP_PROFILES 5130 대조 | 완료 |
| quotes.product_code 저장 | 정상 동작 |
| inspections.work_order_id FK 보정 정확도 | 95% 이상 |

### Phase 3 (절곡 동적 구현)

| 기준 | 수치 목표 |
|------|----------|
| 제품코드별 다른 구성품 표시 | 3종 이상 지원 |
| 마감유형별 구성품 변경 | 정상 동작 |
| 기존 절곡 데이터 호환 (Path A + B) | 100% |
| inspection-config API 응답 시간 | < 200ms |
| 스크린/슬랫 회귀 | 에러 0건 |
| document_data 저장 정합성 | 100% |

---

## 8. 통합 컨펌 대기 목록

| # | Phase | 항목 | 변경 내용 | 상태 |
|---|:-----:|------|----------|:----:|
| 1 | 0 | 사전 조사 실행 | SQL 4개 (읽기 전용) | ⚠️ 대기 |
| 2 | 1 | product_code 전파 수정 | 5개 코드 경로 options 복사 변경 | ⚠️ 대기 |
| 3 | 1 | 데이터 보정 마이그레이션 | 기존 work_order_items 역추적 보정 | ⚠️ 대기 |
| 4 | 2A | inspection-config API 설계 | 범용 API 엔드포인트 추가 | ⚠️ 대기 |
| 5 | 2B | inspections.work_order_id FK | 마이그레이션 + 로직 수정 | ⚠️ 대기 |
| 6 | 3 | inspection-config API 구현 | 공정 자동 판별 + BOM 구성품 | ⚠️ 대기 |
| 7 | 5 | 완제품 마스터 자동 등록 | items 테이블에 FG 품목 생성 | ⚠️ 대기 |
| 8 | 6 | 3관점 검사 화면 설계 | 기획자 협의 필요 | ⏭️ |

---

## 9. 롤백 전략 (통합)

| Phase | 위험도 | 롤백 방법 |
|:-----:|:------:|----------|
| 0 | 없음 | 읽기 전용 |
| 1 (options 추가) | 낮음 | options에서 `product_code`, `product_name` 키 제거 스크립트 |
| 1 (데이터 보정) | 중간 | `work_order_items_backup_product_code` 백업 테이블에서 복원 |
| 2B (inspections FK) | 중간 | `work_order_id` 컬럼 drop 마이그레이션 (down 메서드) |
| 3 (절곡 동적화) | 낮음 | document_template_id NULL → 레거시 컴포넌트 자동 복귀 (I4) |
| 5 (FG 품목) | 높음 | `auto_generated` 플래그 기반 식별 후 삭제 |

---

## 10. 참고 파일 (통합)

### 백엔드

| 파일 | 역할 | 관련 Phase |
|------|------|:----------:|
| `api/app/Services/OrderService.php` | 수주→작업지시 변환 (L1410) | 1 |
| `api/app/Services/WorkOrderService.php` | 작업지시 서비스 (L287, L311, L416) | 1, 3 |
| `api/app/Services/Quote/QuoteService.php` | 견적 서비스 | 2B |
| `api/app/Services/InspectionService.php` | 품질검사 서비스 | 2B |
| `api/app/Services/DocumentService.php` | 문서 CRUD | 3 |

### 프론트엔드

| 파일 | 역할 | 관련 Phase |
|------|------|:----------:|
| `react/.../WorkerScreen/actions.ts` | 작업자 화면 서버 액션 | 1 |
| `react/.../WorkerScreen/index.tsx` | 작업자 화면 메인 | 1 |
| `react/.../documents/TemplateInspectionContent.tsx` | 양식 기반 동적 렌더링 (**통합 방향**) | 3 |
| `react/.../documents/BendingInspectionContent.tsx` | 절곡 레거시 (**동결**) | — |
| `react/.../documents/InspectionReportModal.tsx` | 검사 모달 래퍼 | 3 |

### 참고 문서

| 문서 | 경로 | 용도 |
|------|------|------|
| 원본: 제품코드 추적성 | `docs/plans/product-code-traceability-plan.md` | 상세 코드/쿼리 참조 |
| 원본: 검사 단위 구조 | `docs/plans/document-system-improvement-plan.md` | 상세 설계/정책 참조 |
| 리뷰 정책 결정 | `docs/plans/document-system-improvement-review.md` | 16건 정책 결정 |
| 문서 시스템 마스터 | `docs/plans/document-system-master.md` | 전체 Phase 관리 |
| API 규칙 | `API_RULES.md` | Service-First, FormRequest |
| DB 스키마 | `docs/specs/database-schema.md` | 테이블 구조 |

---

## 11. 변경 이력

| 날짜 | 항목 | 변경 내용 |
|------|------|----------|
| 2026-02-27 | 통합 문서 작성 | product-code + document-system 2개 계획을 7 Phase 통합 계획으로 병합 |

---

## 12. 세션 관리 정책

### 세션 시작 시
```
1. 이 문서(integrated-master-plan.md) 읽기
2. 진행 상태 테이블 확인 → 마지막 완료 작업 파악
3. 해당 Phase 상세 문서 읽기
4. 다음 작업 시작
```

### 작업 중 관리
- Phase 완료 시 이 문서의 진행 상태 테이블 업데이트
- 해당 Phase 상세 문서도 업데이트
- 컨펌 필요 사항 발생 시 컨펌 대기 목록에 추가

### 세션 종료 시
- 변경 이력 섹션에 최종 업데이트 기록

---

*이 문서는 `product-code-traceability-plan.md`와 `document-system-improvement-plan.md`를 통합한 마스터 계획입니다.*