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

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

> **작성일**: 2026-02-10
> **마스터 문서**: [`document-system-master.md`](./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 패턴)

```php
// 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 생성 로직

```php
// 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 스킬로 생성되었습니다.*