SamProject/sam-docs
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ee1aaf183de326628bf02372e71c0c6681b4417f
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

12 KiB
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일차)는 독립적인 신규 개발이므로 나중에 진행 가능

관련 문서

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