sam-docs/dev/dev_plans/integrated-master-plan.md

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

작성일: 2026-02-27 목적: 두 개선 계획(제품코드 추적성, 검사 단위 구조)을 하나의 순차적 실행 계획으로 통합 상태: 🔄 Phase 0~3 완료, Phase 4 이후 대기 원본 문서:

• product-code-traceability-plan.md (아카이브 참조)
• document-system-improvement-plan.md (아카이브 참조)
• document-system-improvement-review.md (정책 결정 16건) 테스트: integrated-test-scenarios.md (기능 단위 11개 FU)

---

📍 현재 진행 상태

항목	내용
마지막 완료 작업	Phase 3 - 절곡 검사 동적 구현 (inspection-config API + 트랜잭션 보강)
다음 작업	Phase 4 (절곡 재공품 + 결재 워크플로우) — 후순위
진행률	5/7 Phase (Phase 0+1+2A+2B+3 완료)
마지막 업데이트	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 상세
1	product_code 전파 버그 수정	product-code P1	Phase 0	✅	Phase 0-1 상세
2A	절곡 검사 분석/설계	document-system P1	없음 (Phase 1과 병렬)	✅	Phase 2 상세
2B	견적/수주 정합성 + 품질 FK	product-code P2+P3	Phase 1	✅	Phase 2 상세
3	절곡 검사 동적 구현	document-system P2	Phase 1 + 2A	✅	Phase 3 상세
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

---

Phase 1: product_code 전파 버그 수정 ⏳

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

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

→ 상세: 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

---

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

---

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

---

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/dev_plans/product-code-traceability-plan.md	상세 코드/쿼리 참조
원본: 검사 단위 구조	docs/dev_plans/document-system-improvement-plan.md	상세 설계/정책 참조
리뷰 정책 결정	docs/dev_plans/document-system-improvement-review.md	16건 정책 결정
문서 시스템 마스터	docs/dev_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 통합 계획으로 병합
2026-02-27	Phase 2A 완료	절곡 검사 분석/설계 완료. dynamic_bom 발견, 5130 대조 완료, inspection-config API 재설계
2026-02-27	Phase 2B 완료	견적 product_code 자동추출, inspections.work_order_id FK, 데이터 보정 25건
2026-02-27	Phase 3 완료	inspection-config API(3.1), TemplateInspectionContent API 연동(3.2), EAV 호환 확인(3.3+3.4), 트랜잭션 보강(3.5)

---

12. 세션 관리 정책

세션 시작 시

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

작업 중 관리

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

세션 종료 시

• 변경 이력 섹션에 최종 업데이트 기록

---

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