# 품질인정심사(QMS) API 연동 계획

> **작성일**: 2026-03-09
> **상태**: 계획 수립
> **URL**: `/quality/qms`
> **스토리보드**: 슬라이드 19~20
> **관련 문서**: `docs/features/quality-management/quality-certification-audit.md`

---

## 1. 현황 분석

### 1.1 프론트엔드 현황

| 항목 | 상태 | 비고 |
|------|------|------|
| `page.tsx` | ✅ 구현됨 | 14KB, 전체 페이지 레이아웃 |
| `types.ts` | ✅ 구현됨 | 95줄, 타입 정의 완료 |
| `mockData.ts` | ✅ 구현됨 | 543줄, 완전한 목업 데이터 |
| `components/` | ✅ 구현됨 | 12개 컴포넌트 + documents/ 7개 |
| `actions.ts` | ❌ 없음 | API 연동 0% |

프론트엔드는 UI가 완성되어 있으나 **100% 목업 데이터**로 동작 중.

### 1.2 백엔드 현황

| 영역 | 기존 API | 신규 필요 |
|------|----------|-----------|
| **1일차 (기준/매뉴얼 심사)** | ❌ 없음 | 모델, 마이그레이션, 서비스, 컨트롤러 전체 |
| **2일차 (로트 추적 심사)** | ⚠️ 부분 존재 | 기존 API 조합 + 서류 연결 API 신규 |

**기존 활용 가능 API:**
- `GET /quality/documents` — 품질관리서 목록 (2일차 1단계)
- `GET /quality/documents/{id}` — 품질관리서 상세 + 수주/개소 (2일차 2단계)
- `GET /quality/performance-reports` — 실적신고 (분기 필터 활용)
- `GET /inspections` — 수입검사/중간검사 성적서
- 출하/출고/납품 관련 기존 API

---

## 2. 작업 범위

### Phase 1: 2일차 (로트 추적 심사) API 연동

> **우선순위 높음** — 기존 API 활용 가능하여 빠르게 연동 가능

#### 2.1 Frontend — `actions.ts` 생성

```
react/src/app/[locale]/(protected)/quality/qms/actions.ts
```

| 액션 | 호출 API | 설명 |
|------|----------|------|
| `getQualityReports()` | `GET /quality/documents` | 품질관리서 목록 (분기 필터) |
| `getReportRoutes(reportId)` | `GET /quality/documents/{id}` | 수주코드 + 개소 목록 |
| `getRouteDocuments(routeId)` | 복합 조회 (아래 참조) | 개소별 관련 서류 8종 |
| `confirmUnitInspection(unitId)` | `PATCH /qms/lot-audit/confirm` | 개소 확인 완료 처리 |

#### 2.2 관련 서류 조회 로직

2일차 3단계 "관련 서류"는 개소(Location)에 연결된 8종 서류를 조합 조회:

| 서류 타입 | 데이터 소스 | 조회 방식 |
|-----------|-------------|-----------|
| 수입검사 성적서 | `inspections` (type=IQC) | 수주의 BOM 원자재 LOT 추적 |
| 수주서 | `orders` | 수주코드로 직접 조회 |
| 작업일지 | `work_orders` + 작업일지 | 수주 → 작업지시 → 작업일지 |
| 중간검사 성적서 | `inspections` (type=PQC) | 작업지시별 중간검사 |
| 납품확인서 | `shipments` | 출하 → 납품확인서 |
| 출고증 | `shipments` | 출하 → 출고증 |
| 제품검사 성적서 | `quality_document_locations` | 개소별 검사 문서 (EAV) |
| 품질관리서 | `quality_documents` | 품질관리서 원본 |

#### 2.3 Backend — 신규 API (최소)

```
GET  /api/v1/qms/lot-audit/reports          — 분기별 품질관리서 목록 (전용 뷰)
GET  /api/v1/qms/lot-audit/reports/{id}     — 수주코드 + 개소 + 완료 상태
GET  /api/v1/qms/lot-audit/routes/{id}/documents — 개소별 8종 서류 조합 조회
PATCH /api/v1/qms/lot-audit/units/{id}/confirm   — 확인 완료 처리
```

> 기존 `quality/documents` API를 래핑하여 QMS 전용 응답 형태로 가공하는 방식 권장.
> 8종 서류 조합 로직이 복잡하므로 **전용 서비스 메서드** 필요.

#### 2.4 DB 변경

| 변경 | 테이블 | 설명 |
|------|--------|------|
| 컬럼 추가 | `quality_document_locations` | `options` JSON에 `lot_audit_confirmed`, `lot_audit_confirmed_at` 추가 |

> 별도 테이블 없이 기존 개소(Location) 테이블의 `options` 활용 (컬럼 추가 정책 준수)

---

### Phase 2: 1일차 (기준/매뉴얼 심사) 백엔드 구축

> **작업량 많음** — 완전 신규 백엔드 구축 필요

#### 2.1 DB 설계 (신규 테이블)

```
audit_checklists (심사 점검표 마스터)
├── id, tenant_id
├── year, quarter
├── type: 'standard_manual'  (1일차)
├── status: draft/in_progress/completed
├── options: JSON
├── created_by, timestamps, soft_delete

audit_checklist_categories (점검표 카테고리)
├── id, tenant_id
├── checklist_id (FK → audit_checklists)
├── title: '원재료 품질관리 기준'
├── sort_order
├── options: JSON

audit_checklist_items (점검표 세부 항목)
├── id, tenant_id
├── category_id (FK → audit_checklist_categories)
├── name: '수입검사 기준 확인'
├── description
├── is_completed: boolean
├── completed_at, completed_by
├── sort_order
├── options: JSON

audit_standard_documents (기준 문서)
├── id, tenant_id
├── checklist_item_id (FK → audit_checklist_items)
├── title, version, date
├── document_id (FK → documents, EAV)
├── options: JSON
```

#### 2.2 Backend 구현

| 파일 | 역할 |
|------|------|
| `api/app/Models/Qualitys/AuditChecklist.php` | 심사 점검표 모델 |
| `api/app/Models/Qualitys/AuditChecklistCategory.php` | 카테고리 모델 |
| `api/app/Models/Qualitys/AuditChecklistItem.php` | 세부 항목 모델 |
| `api/app/Models/Qualitys/AuditStandardDocument.php` | 기준 문서 모델 |
| `api/app/Services/AuditChecklistService.php` | 서비스 |
| `api/app/Http/Controllers/Api/V1/AuditChecklistController.php` | 컨트롤러 |
| `api/database/migrations/XXXX_create_audit_checklists_table.php` | 마이그레이션 (4테이블) |

#### 2.3 API 엔드포인트

```
GET    /api/v1/qms/checklists                          — 점검표 목록 (연도/분기 필터)
POST   /api/v1/qms/checklists                          — 점검표 생성
GET    /api/v1/qms/checklists/{id}                     — 점검표 상세 (카테고리+항목+문서)
PUT    /api/v1/qms/checklists/{id}                     — 점검표 수정
PATCH  /api/v1/qms/checklists/{id}/complete            — 점검표 완료 처리

PATCH  /api/v1/qms/checklist-items/{id}/toggle         — 항목 완료/미완료 토글
GET    /api/v1/qms/checklist-items/{id}/documents      — 항목별 기준 문서 조회
POST   /api/v1/qms/checklist-items/{id}/documents      — 기준 문서 연결
DELETE /api/v1/qms/checklist-items/{id}/documents/{docId} — 기준 문서 연결 해제
```

#### 2.4 Frontend — actions.ts 확장

| 액션 | 설명 |
|------|------|
| `getChecklists(year, quarter)` | 점검표 목록 |
| `getChecklistDetail(id)` | 점검표 상세 (카테고리+항목+문서) |
| `toggleChecklistItem(itemId)` | 항목 완료/미완료 토글 |
| `getCheckItemDocuments(itemId)` | 기준 문서 조회 |
| `confirmCheckItem(itemId)` | 기준/매뉴얼 확인 완료 |

---

### Phase 3: 프론트엔드 목업 → API 전환

#### 3.1 page.tsx 수정

- `mockData.ts` import 제거
- `actions.ts` import로 교체
- `useEffect`에서 API 호출
- 로딩/에러 상태 추가

#### 3.2 컴포넌트 수정

| 컴포넌트 | 변경 내용 |
|----------|-----------|
| `ReportList.tsx` | API 데이터 바인딩 |
| `RouteList.tsx` | API 데이터 바인딩 |
| `DocumentList.tsx` | 8종 서류 실제 조회 |
| `InspectionModal.tsx` | 실제 검사 문서 렌더링 |
| `Day1ChecklistPanel.tsx` | API 데이터 바인딩 |
| `Day1DocumentSection.tsx` | 기준 문서 API 조회 |
| `Day1DocumentViewer.tsx` | 실제 파일 미리보기 |
| `AuditProgressBar.tsx` | 실시간 진행률 계산 |
| `Filters.tsx` | 연도/분기 필터 API 연동 |

#### 3.3 mockData.ts 처리

- Phase 3 완료 후 `mockData.ts` 삭제
- 또는 `USE_MOCK` 플래그 패턴 적용 (개발 편의)

---

## 3. 데이터 매핑

### 3.1 InspectionReport ↔ QualityDocument

| 프론트 (InspectionReport) | 백엔드 (QualityDocument) |
|---------------------------|-------------------------|
| `id` | `quality_documents.id` |
| `code` | `quality_documents.code` (채번) |
| `siteName` | `quality_documents.site_name` |
| `item` | `quality_documents.options.product_type` 또는 인정특성 |
| `routeCount` | `quality_document_orders` COUNT |
| `totalRoutes` | `quality_document_locations` COUNT |
| `quarter` | `performance_reports.year` + `quarter` |
| `year` | `performance_reports.year` |
| `quarterNum` | `performance_reports.quarter` |

### 3.2 RouteItem ↔ QualityDocumentOrder

| 프론트 (RouteItem) | 백엔드 (QualityDocumentOrder) |
|--------------------|-------------------------------|
| `id` | `quality_document_orders.id` |
| `code` | `orders.order_code` |
| `date` | `orders.order_date` |
| `site` | `orders.site_name` |
| `locationCount` | `quality_document_locations` COUNT |
| `subItems` | `quality_document_locations` 변환 |

### 3.3 ChecklistCategory ↔ AuditChecklistCategory

| 프론트 (ChecklistCategory) | 백엔드 (AuditChecklistCategory) |
|---------------------------|--------------------------------|
| `id` | `audit_checklist_categories.id` |
| `title` | `audit_checklist_categories.title` |
| `subItems` | `audit_checklist_items` 관계 |

---

## 4. 일정 산정

| Phase | 작업 내용 | 예상 소요 |
|-------|----------|-----------|
| **Phase 1** | 2일차 API 연동 (기존 API 활용) | |
| ├ 1-1 | Backend: 전용 서비스 + 컨트롤러 + 라우트 | 1일 |
| ├ 1-2 | Backend: 8종 서류 조합 조회 로직 | 1일 |
| ├ 1-3 | Frontend: actions.ts 생성 + 목업 교체 | 1일 |
| └ 1-4 | 테스트 및 디버깅 | 0.5일 |
| **Phase 2** | 1일차 백엔드 구축 (완전 신규) | |
| ├ 2-1 | DB 설계 + 마이그레이션 (4테이블) | 0.5일 |
| ├ 2-2 | 모델 4개 + 관계 설정 | 0.5일 |
| ├ 2-3 | 서비스 + 컨트롤러 + 라우트 | 1일 |
| └ 2-4 | 초기 데이터 시딩 (점검표 마스터) | 0.5일 |
| **Phase 3** | 프론트엔드 전환 | |
| ├ 3-1 | 2일차 컴포넌트 API 바인딩 | 1일 |
| ├ 3-2 | 1일차 컴포넌트 API 바인딩 | 1일 |
| └ 3-3 | 통합 테스트 + mockData 정리 | 0.5일 |

**총 예상: ~8일**

---

## 5. 의존성 및 리스크

### 5.1 의존성

| 항목 | 의존 대상 | 상태 |
|------|-----------|------|
| 품질관리서 데이터 | `quality_documents` 실 데이터 | ✅ 운영 중 |
| 실적신고 데이터 | `performance_reports` 실 데이터 | ✅ 운영 중 |
| 수입검사 성적서 | `inspections` (IQC) | ✅ 운영 중 |
| 중간검사 성적서 | `inspections` (PQC) | ⚠️ 구현 중 |
| 작업일지 | `work_orders` 연결 | ✅ 운영 중 |
| 출하/납품 | `shipments` | ✅ 운영 중 |
| 기준 문서 파일 | EAV Document 시스템 | ✅ 운영 중 |

### 5.2 리스크

| 리스크 | 영향 | 완화 방안 |
|--------|------|-----------|
| 8종 서류 추적 로직 복잡 | Phase 1 지연 | 서류별 독립 조회 후 프론트에서 조합 |
| 1일차 점검표 초기 데이터 부재 | Phase 2 테스트 어려움 | 시더로 기본 점검표 생성 |
| 중간검사 미완성 | 2일차 일부 서류 누락 | 빈 상태로 표시, 추후 연동 |

---

## 6. 권장 진행 순서

```
Phase 1 (2일차 API 연동) — 3.5일
    ↓
Phase 2 (1일차 백엔드 구축) — 2.5일
    ↓
Phase 3 (프론트엔드 전환) — 2.5일
```

**Phase 1을 먼저 하는 이유:**
- 기존 API 활용으로 빠르게 실 데이터 확인 가능
- 로트 추적은 실적신고와 직접 연결되어 비즈니스 우선순위 높음
- Phase 2(1일차)는 독립적인 신규 개발이므로 나중에 진행 가능

---

## 관련 문서

- [품질인정심사 기능 문서](../../features/quality-management/quality-certification-audit.md)
- [제품검사 관리](../../features/quality-management/inspection-management.md)
- [생산실적신고](../../features/quality-management/performance-reports.md)
- [통합 개선 마스터 플랜](./integrated-master-plan.md)

---

**최종 업데이트**: 2026-03-09