sam-docs/dev/dev_plans/archive/document-system-product-inspection.md

Phase 5.2: 제품검사(FQC) 폼 구현 계획

작성일: 2026-02-10 마스터 문서: document-system-master.md 상태: 🔄 진행 중 선행 조건: Phase 5.0 (공통: 검사기준서↔컬럼 연동) 완료 필요, Phase 5.1과 병렬 진행 가능 최종 분석일: 2026-02-12

---

1. 개요

1.1 목적

mng에서 제품검사(FQC) 양식 템플릿을 관리하고, React 품질관리 화면(/quality/inspections)에서 수주건의 개소별 제품검사 문서를 생성/입력/결재할 수 있도록 한다.

1.2 제품검사 = 품질검사

• 동일 개념. "제품검사(FQC: Final Quality Control)"로 통일
• 수주건(Order) + 개소(OrderItem) 단위로 관리
• 전수검사: 수주 50개소 → 제품검사 문서 50건 생성

1.3 현재 상태 (2026-02-12 분석)

항목	상태	비고
React InspectionManagement	✅	components/quality/InspectionManagement/ - 요청관리 CRUD (목록/등록/상세/캘린더)
React ProductInspectionDocument	✅	quality/qms/components/documents/ - 하드코딩 11개 항목
React 제품검사 모달	✅	InspectionReportModal, ProductInspectionInputModal
React 문서시스템 뷰어	✅	components/document-system/ - DocumentViewer, TemplateInspectionContent
API Inspection 모델	✅	/api/v1/inspections - JSON 기반, 단순 status (waiting→completed)
API Document 모델	✅	EAV 정규화, 결재 워크플로우 (DRAFT→APPROVED)
mng 양식 템플릿	❌	미존재 (신규 생성 필요)
개소별 문서 자동생성	❌	미구현

1.4 핵심 발견 사항

두 개의 독립적 검사 시스템 존재:

시스템	데이터 모델	특징
InspectionManagement	inspections 테이블 (JSON)	요청관리, 단순 상태, 결재 없음
Document System	documents 테이블 (EAV)	양식 기반, 결재 워크플로우, 이력 관리

세 가지 검사항목 세트 발견:

출처	항목	용도
types.ts ProductInspectionData	겉모양(가공/재봉/조립/연기차단재/하단마감재), 모터, 재질/치수, 시험	공장출하검사
계획문서 (이 문서)	외관, 작동, 개폐속도, 방연/차연/내화, 안전, 비상개방, 전기배선, 설치, 부속	설치 후 최종검사 ← 채택
QMS ProductInspectionDocument	가공상태, 외관검사, 절단면, 도포상태, 조립, 슬릿, 규격치수, 마감처리, 내벽/마감/배색시트	제조품질검사

1.5 통합 전략 (확정)

InspectionManagement의 요청관리 흐름(목록/등록/상세/캘린더)은 유지하고, 검사 성적서 생성/입력/결재만 documents 시스템으로 전환한다.

• inspections 테이블: 검사 요청/일정/상태 관리 (meta 정보) → 유지
• documents 테이블: 검사 성적서 (양식 기반 상세 데이터, 결재) → 신규 연동
• 연결: documents.linkable_type = 'order_item', document_links로 Order/Inspection 연결
• 기존 InspectionReportModal/ProductInspectionInputModal → TemplateInspectionContent 기반 전환

1.6 성공 기준

1. mng에서 제품검사 양식 편집/미리보기 정상 동작
2. 수주 1건 선택 시 개소(OrderItem) 수만큼 Document 자동생성
3. 각 Document에 해당 개소의 정보(층-부호, 규격, 수량) 자동매핑
4. 개소별 검사 데이터 입력/저장/조회 가능
5. 결재 워크플로우 정상 동작
6. 기존 InspectionManagement 요청관리 기능 정상 유지

---

2. 데이터 흐름

Order (수주)
├─ order_no: "KD-TS-260210-01"
├─ client_name: "발주처명"
├─ site_name: "현장명"
├─ quantity: 50 (총 개소 수)
└─ items: OrderItem[] (50건)
   ├─ [0] floor_code="1F", symbol_code="A", specification="W7400×H2950"
   ├─ [1] floor_code="1F", symbol_code="B", specification="W5200×H3100"
   └─ [49] ...

제품검사 요청 시:
   ↓
Document (50건 자동생성)
├─ Document[0]
│  ├─ template_id → 제품검사 양식
│  ├─ linkable_type = 'App\Models\OrderItem'
│  ├─ linkable_id = OrderItem[0].id
│  ├─ document_no = "FQC-260210-01"
│  ├─ title = "제품검사 - 1F-A (W7400×H2950)"
│  └─ document_data (EAV)
│     ├─ 기본필드: 납품명, 제품명, 발주처, LOT NO, 로트크기, 검사일자, 검사자
│     ├─ 검사데이터: 11개 항목별 적합/부적합
│     └─ Footer: 종합판정(합격/불합격)
├─ Document[1] → OrderItem[1]
└─ Document[49] → OrderItem[49]

+ document_links 연결:
  ├─ link_key="order" → Order.id
  └─ link_key="inspection" → Inspection.id (있는 경우)

2.1 linkable 다형성 연결

필드	값	설명
linkable_type	App\Models\OrderItem	OrderItem 모델
linkable_id	OrderItem.id	개소 PK

추가로 document_links 테이블을 통해:

• Order(수주) 연결: link_key="order"
• Inspection(검사요청) 연결: link_key="inspection" (InspectionManagement에서 연결 시)
• Process(공정) 연결: link_key="process" (해당되는 경우)

---

3. 작업 항목

#	작업	상태	완료 기준	비고
5.2.1	mng 제품검사 양식 시더 생성	✅	ProductInspectionTemplateSeeder 작성 (template_id: 65). 결재3+기본필드7+섹션2+항목11+section_fields	2026-02-12
5.2.2	mng 양식 편집/미리보기 검증	✅	양식 edit → 미리보기 → 저장 정상 동작 확인	2026-02-12
5.2.3	API 개소별 문서 일괄생성	✅	POST /api/v1/documents/bulk-create-fqc + GET /api/v1/documents/fqc-status. DocumentService에 bulkCreateFqc/fqcStatus 추가	2026-02-12
5.2.4	React 제품검사 모달 → 양식 기반 전환	✅	fqcActions.ts + FqcDocumentContent.tsx 신규. InspectionReportModal/ProductInspectionInputModal 듀얼모드(FQC/legacy)	2026-02-12
5.2.5	개소 목록/진행현황 UI	✅	InspectionDetail에 FQC 진행현황 통계 바 + 개소별 상태 뱃지(합격/불합격/진행중/미생성) + 조회 버튼	2026-02-12

---

4. 제품검사 항목 (설치 후 최종검사 11항목 - 확정)

#	카테고리	검사항목	검사기준	검사방식	측정유형
1	외관	외관검사	사용상 결함이 없을 것	visual	checkbox
2	기능	작동상태	정상 작동	visual	checkbox
3	기능	개폐속도	규정 속도 범위 이내	visual	checkbox
4	성능	방연성능	기준 적합	visual	checkbox
5	성능	차연성능	기준 적합	visual	checkbox
6	성능	내화성능	기준 적합	visual	checkbox
7	안전	안전장치	정상 작동	visual	checkbox
8	안전	비상개방	정상 작동	visual	checkbox
9	설치	전기배선	규정 적합	visual	checkbox
10	설치	설치상태	규정 적합	visual	checkbox
11	부속	부속품	누락 없음	visual	checkbox

특성:

• 모든 항목이 visual/checkbox (적합/부적합)
• numeric 측정값 없음 → columns 구조가 중간검사보다 훨씬 단순
• columns 자동 파생(방안1): checkbox → 판정(select) 컬럼

결재라인: 작성(품질) → 검토(품질QC) → 승인(경영) Footer: 부적합 내용 + 종합판정(합격/불합격) 자동판정: 모든 항목 적합 → 합격, 1개라도 부적합 → 불합격

4.1 양식 시더 구조 (MidInspectionTemplateSeeder 패턴)

// ProductInspectionTemplateSeeder
[
    'name' => '제품검사 성적서',
    'category' => '품질/제품검사',
    'title' => '제 품 검 사 성 적 서',
    'company_name' => '케이디산업',
    'footer_remark_label' => '부적합 내용',
    'footer_judgement_label' => '종합판정',
    'footer_judgement_options' => ['합격', '불합격'],

    'approval_lines' => [
        ['name' => '작성', 'dept' => '품질', 'role' => '담당자', 'sort_order' => 1],
        ['name' => '검토', 'dept' => '품질', 'role' => 'QC', 'sort_order' => 2],
        ['name' => '승인', 'dept' => '경영', 'role' => '대표', 'sort_order' => 3],
    ],

    'basic_fields' => [
        ['label' => '납품명', 'field_type' => 'text'],
        ['label' => '제품명', 'field_type' => 'text'],
        ['label' => '발주처', 'field_type' => 'text'],
        ['label' => 'LOT NO', 'field_type' => 'text'],
        ['label' => '로트크기', 'field_type' => 'text'],
        ['label' => '검사일자', 'field_type' => 'date'],
        ['label' => '검사자', 'field_type' => 'text'],
    ],

    'sections' => [
        [
            'title' => '제품검사 기준서',
            'items' => [],  // 기준서 섹션 (빈 섹션, 향후 확장)
        ],
        [
            'title' => '제품검사 DATA',
            'items' => [
                ['category' => '외관', 'item' => '외관검사', ...],
                // ... 11개 항목 (모두 visual/checkbox)
            ],
        ],
    ],

    // columns는 자동 파생 (Phase 5.0 방안1)
    // checkbox → [NO, 검사항목, 검사기준, 판정(select)]
]

---

5. 개소별 문서 일괄생성 로직

5.1 API 엔드포인트 (계획)

POST /api/v1/orders/{orderId}/create-fqc
Request: { template_id: number }
Response: { documents: Document[], created_count: number }

5.2 생성 로직

// 1. Order + OrderItems 조회
$order = Order::with('items')->findOrFail($orderId);

// 2. 개소별 Document 생성
foreach ($order->items as $index => $orderItem) {
    $document = Document::create([
        'template_id' => $templateId,
        'document_no' => "FQC-" . date('ymd') . "-" . str_pad($index + 1, 2, '0', STR_PAD_LEFT),
        'title' => "제품검사 - {$orderItem->floor_code}-{$orderItem->symbol_code} ({$orderItem->specification})",
        'status' => DocumentStatus::DRAFT,
        'linkable_type' => OrderItem::class,
        'linkable_id' => $orderItem->id,
    ]);

    // 3. 기본필드 자동매핑
    $autoFillData = [
        '납품명' => $order->title,
        '제품명' => $orderItem->item_name,
        '발주처' => $order->client_name,
        'LOT NO' => $order->order_no,
        '로트크기' => "1 EA",
    ];

    // 4. document_data에 기본필드 저장
    foreach ($autoFillData as $key => $value) {
        DocumentData::create([
            'document_id' => $document->id,
            'field_key' => Str::slug($key),
            'field_value' => $value,
        ]);
    }

    // 5. document_links 연결
    DocumentLink::create([
        'document_id' => $document->id,
        'link_key' => 'order',
        'linkable_type' => Order::class,
        'linkable_id' => $order->id,
    ]);

    // 6. 결재라인 초기화
    // ... (기존 패턴 재사용)
}

5.3 개소 진행현황 조회

GET /api/v1/orders/{orderId}/fqc-status
Response: {
    total: 50,
    inspected: 30,
    passed: 28,
    failed: 2,
    pending: 20,
    items: [
        { order_item_id: 1, floor_code: "1F", symbol_code: "A", document_id: 101, status: "APPROVED", result: "합격" },
        { order_item_id: 2, floor_code: "1F", symbol_code: "B", document_id: 102, status: "DRAFT", result: null },
        ...
    ]
}

---

6. 핵심 파일 경로

mng

파일	용도	상태
mng/database/seeders/ProductInspectionTemplateSeeder.php	제품검사 양식 시더	🔄 작성 중
mng/database/seeders/MidInspectionTemplateSeeder.php	참조 패턴 (중간검사)	✅

api

파일	용도	상태
api/app/Models/Order.php	수주 모델	✅
api/app/Models/OrderItem.php	수주 상세(개소) 모델	✅
api/app/Models/Documents/Document.php	문서 모델	✅
api/app/Models/Qualitys/Inspection.php	기존 검사 모델 (IQC/PQC/FQC)	✅
api/app/Http/Controllers/Api/V1/OrderController.php	수주 컨트롤러 (createFqc 추가 필요)	⏳
api/app/Services/DocumentService.php	문서 생성 서비스	✅

react

파일	용도	상태
react/src/components/quality/InspectionManagement/	품질검사 요청관리 (15+ 파일)	✅ 유지
react/src/components/quality/InspectionManagement/InspectionList.tsx	검사 목록	✅ 유지
react/src/components/quality/InspectionManagement/InspectionDetail.tsx	검사 상세	🔄 수정 필요
react/src/components/quality/InspectionManagement/modals/InspectionReportModal.tsx	성적서 모달	🔄 전환 필요
react/src/components/quality/InspectionManagement/modals/ProductInspectionInputModal.tsx	입력 모달	🔄 전환 필요
react/src/components/document-system/viewer/DocumentViewer.tsx	문서 뷰어	✅
react/src/components/document-system/content/TemplateInspectionContent.tsx	양식 기반 렌더링	✅
react/src/app/[locale]/(protected)/quality/qms/components/documents/ProductInspectionDocument.tsx	하드코딩 문서	❌ 대체 예정

---

7. 기존 Inspection 모델과의 관계 (통합 전략)

7.1 현재 구조

inspections 테이블 (JSON 기반)
├─ inspection_type: IQC/PQC/FQC
├─ status: waiting → in_progress → completed
├─ meta: { ... } (JSON)
├─ items: { ... } (JSON - 검사 결과)
└─ extra: { ... } (JSON)

documents 테이블 (EAV 정규화)
├─ template_id → document_templates
├─ status: DRAFT → PENDING → APPROVED/REJECTED
├─ linkable_type + linkable_id (다형성)
├─ document_data (EAV - 섹션/컬럼/행 기반)
└─ document_approvals (결재 이력)

7.2 통합 후 구조

InspectionManagement (요청관리 레이어) - 유지
├─ 검사 목록/등록/상세/캘린더
├─ inspections 테이블 (요청/일정/상태)
└─ API: /api/v1/inspections (CRUD)

Document System (성적서 레이어) - 신규 연동
├─ 양식 기반 검사 데이터 입력
├─ documents 테이블 (EAV + 결재)
├─ linkable → OrderItem (개소별)
└─ document_links → Order, Inspection

연결 포인트:
├─ InspectionDetail에서 "성적서 작성/조회" 시 → Document System 호출
├─ InspectionReportModal → TemplateInspectionContent 기반 전환
└─ ProductInspectionInputModal → 양식 기반 입력으로 전환

---

8. 변경 이력

날짜	내용
2026-02-10	Phase 5.2 계획 문서 신규 생성
2026-02-10	방안1 반영: 시더에 section_fields 필수, columns 자동 파생. 선행조건 Phase 5.0 추가
2026-02-12	코드베이스 분석 반영: InspectionManagement 발견, 3개 검사항목 세트 정리, 통합 전략 확정
2026-02-12	설치 후 최종검사 11항목 확정, documents 기반 통합 방향 확정
2026-02-12	5.2.1 ProductInspectionTemplateSeeder 작성 완료 (template_id: 65)
2026-02-12	5.2.2 mng 양식 편집/미리보기 검증 완료
2026-02-12	5.2.3 API bulk-create-fqc + fqc-status 엔드포인트 구현 완료
2026-02-12	5.2.4 React fqcActions.ts + FqcDocumentContent + 모달 듀얼모드 전환 완료
2026-02-12	5.2.5 InspectionDetail FQC 진행현황 통계 바 + 개소별 상태/조회 UI 완료
2026-02-12	Phase 5.2 전체 완료 (5/5)

---

이 문서는 /plan 스킬로 생성되었습니다.