SamProject/sam-docs
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cf0c128764f5171456cd7ff740e2e9ae85b94c4e
sam-docs/dev/dev_plans/qms-api-integration-plan.md
권혁성 7a969b9d57 refactor: [structure] sam/ 하위 문서를 docs 루트로 재배치 
- .gitignore를 sam/ 기반에서 루트 기반으로 변경
- sam/docs/ 하위 문서를 루트로 이동 (contracts, features, guides, plans 등)
- sam/ 폴더 삭제 (docker, coocon 포함)
2026-03-09 22:53:07 +09:00

317 lines
12 KiB
Markdown
Raw Blame History

# 품질인정심사(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
Reference in New Issue View Git Blame Copy Permalink