From bfcd6178ea28e9455d22f2b51e95c1ab4f17d60a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B6=8C=ED=98=81=EC=84=B1?= Date: Mon, 9 Mar 2026 20:43:56 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[quality]=20=ED=92=88=EC=A7=88=EA=B4=80?= =?UTF-8?q?=EB=A6=AC=20=EC=8B=9C=EC=8A=A4=ED=85=9C=20=EA=B8=B0=EB=8A=A5=20?= =?UTF-8?q?=EB=AC=B8=EC=84=9C=20=EC=9E=91=EC=84=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: 전체 개요, 역할별 프로세스 플로우, 메뉴 구조, 데이터 구조, API, 스토리보드 참조 - inspection-management.md: 제품검사 관리 (15개 검사항목, 상태판정, 캘린더뷰, 요청서/성적서 양식) - performance-reports.md: 생산실적신고 (자동생성, 확정, 누락체크, 건기원 프로세스) - quality-certification-audit.md: 품질인정심사 (기준/매뉴얼 심사 + 로트 추적 심사) - INDEX.md에 품질관리 문서 등록 --- INDEX.md | 1 + features/quality-management/README.md | 362 ++++++++++++++++++ .../inspection-management.md | 317 +++++++++++++++ .../quality-management/performance-reports.md | 268 +++++++++++++ .../quality-certification-audit.md | 169 ++++++++ 5 files changed, 1117 insertions(+) create mode 100644 features/quality-management/README.md create mode 100644 features/quality-management/inspection-management.md create mode 100644 features/quality-management/performance-reports.md create mode 100644 features/quality-management/quality-certification-audit.md diff --git a/INDEX.md b/INDEX.md index 580176b..f3b933c 100644 --- a/INDEX.md +++ b/INDEX.md @@ -141,6 +141,7 @@ DB 도메인별: | [card-vehicle/README.md](features/card-vehicle/README.md) | 법인카드·차량 | | [settlement/README.md](features/settlement/README.md) | 정산 | | [barobill-kakaotalk/README.md](features/barobill-kakaotalk/README.md) | 바로빌 카카오톡 | +| [quality-management/README.md](features/quality-management/README.md) | 품질관리 (제품검사, 실적신고) | --- diff --git a/features/quality-management/README.md b/features/quality-management/README.md new file mode 100644 index 0000000..d2a5391 --- /dev/null +++ b/features/quality-management/README.md @@ -0,0 +1,362 @@ +# 품질관리 시스템 + +> **작성일**: 2026-03-09 +> **상태**: 운영 중 + +--- + +## 1. 개요 + +### 1.1 목적 + +SAM 품질관리 시스템은 **방화문 제품검사 → 실적신고 → 건기원 제출**의 전체 흐름을 자동화한다. +건축자재 품질관리 법규(건설기술진흥법)에 따른 제품검사 수행 및 분기별 실적신고를 관리한다. + +### 1.2 역할별 프로세스 플로우 + +> 스토리보드 슬라이드 3 기준 + +``` +매출거래처 견적/수주 담당자 생산 담당자 출고 담당자 품질 담당자 +─────────── ────────────── ────────── ────────── ────────── +주문 견적 작성 생산 부서 할당 출고 대기 제품검사 신청 +(전화/카톡/메일) │ │ │ (거래처 요청) + │ 수주 전환?──No──→ 재고 소요량 출고 완료 │ + │ │ Yes 충분? 검사원 일정 관리 +주문 확인 및 수주서 작성 │ │ +내역 확정 (견적서 선택) 원자재 투입 체크 검사원 현장 방문 + │ │ 및 검사 진행 + 생산지시 생성 공정 작업 진행 │ + │ │ 합격? ──No──→ + 재고 소요량 중간검사 │ Yes + 충분?──No──→ │ 실적 신고 관리 + │ 생산 완료 │ + (자재 담당자 품질 인증 심사 + 입고 등록 + 수입검사) + +* 분할 수주/생산/출고는 1차 이후 반복 가능 +``` + +### 1.3 핵심 흐름 (시스템) + +``` +품질관리서 생성 → 수주 연결 → 개소별 검사 → 검사완료 + ↓ + 실적신고 자동생성 (분기별) + ↓ + 필수정보 확인 → 확정 → 건기원 신고 + ↓ + 품질인정심사 + (기준/매뉴얼 + 로트추적) +``` + +### 1.4 메뉴 구조 + +| 메뉴 | URL | 설명 | 상태 | +|------|-----|------|------| +| 제품검사관리 | `/quality/inspections` | 품질관리서 목록/생성/상세 | 운영 중 | +| 실적신고관리 | `/quality/performance-reports` | 분기별 실적신고 관리 | 운영 중 | +| 품질인정심사 | `/quality/qms` | 기준/매뉴얼 심사 + 로트 추적 심사 | 개발 예정 | + +--- + +## 2. 제품검사 (QualityDocument) + +> 상세 문서: [inspection-management.md](./inspection-management.md) + +### 2.1 품질관리서 생성 + +- **채번**: `KD-QD-YYYYMM-0001` (자동) +- **필수 입력**: 현장명, 접수일, 검사자 +- **선택 입력**: 수주처(client_id), 관련자 정보(options JSON) + +### 2.2 수주 연결 + +- 품질관리서에 수주(Order)를 연결하면 **개소(Location)가 자동 생성** +- 개소 = 수주의 root node (층/부호 단위) +- 시공규격(post_width, post_height)은 발주규격과 다를 수 있음 + +### 2.3 검사 수행 + +각 개소에 대해 **15개 검사항목** + **제품 사진**을 입력: + +| 분류 | 검사항목 | 판정 | +|------|---------|------| +| 외관 | 가공, 봉제, 조립, 차연재, 하부마감 | pass/fail | +| 기능 | 모터, 소재 | pass/fail | +| 치수 | 가로, 세로, 가이드레일 간격, 하부마감 간격 | OK/NG | +| 시험 | 내화, 차연, 개폐, 충격 | pass/fail | + +### 2.4 상태 전이 + +``` +received (접수) → in_progress (검사 중) → completed (검사 완료) +``` + +**개소별 상태 자동 판정**: +- `pending`: 검사 데이터 없음 +- `in_progress`: 일부 항목 입력 또는 사진 미등록 +- `completed`: 15개 항목 전부 + 사진 등록 + +--- + +## 3. 생산실적신고 (PerformanceReport) + +> 상세 문서: [performance-reports.md](./performance-reports.md) + +### 3.1 자동 생성 + +- **트리거**: 품질관리서 검사완료(`complete()`) 시 +- **생성 기준**: 현재 연도 + 분기 (`year`, `quarter`) +- **초기 상태**: `unconfirmed` + +### 3.2 확정 프로세스 + +``` +unconfirmed (미확정) + ↓ confirm() — 필수정보 검증 통과 시 +confirmed (확정) + ↓ distribute() — 건기원 신고 시 (미구현) +reported (신고완료) +``` + +**확정 해제**: `confirmed` → `unconfirmed` (unconfirm) + +### 3.3 필수정보 검증 + +확정 전 4가지 섹션의 필수필드가 모두 입력되어야 함: + +| 섹션 | 필수필드 | +|------|---------| +| 건축공사장 | 현장명, 대지위치, 지번 | +| 자재유통업자 | 업체명, 주소, 대표자, 전화번호 | +| 공사시공자 | 업체명, 주소, 담당자, 연락처 | +| 공사감리자 | 사무소명, 주소, 담당자, 연락처 | + +### 3.4 누락체크 + +- 출고완료(배송 완료)된 수주 중 품질관리서가 미등록된 건 탐지 +- 별도 탭에서 조회 가능 + +### 3.5 건기원 실적신고 비즈니스 컨텍스트 + +**건기원(한국건설기술연구원)** 실적신고는 법적 의무: + +- **주기**: 분기별 (1~3월, 4~6월, 7~9월, 10~12월) +- **대상**: 해당 분기에 검사 완료된 모든 건 +- **내용**: 품질관리서 번호, LOT 번호, 현장 정보, 검사 결과 +- **제출처**: 건기원 온라인 시스템 (수기 입력 또는 엑셀 업로드) + +**SAM 시스템 역할**: +1. 제품검사 완료 시 실적신고 데이터 자동 수집 +2. 필수정보 누락 여부 사전 검증 +3. 확정 후 건기원 제출 양식으로 데이터 정리 +4. (향후) 건기원 시스템 연동 자동 배포 + +--- + +## 4. 데이터 구조 + +### 4.1 테이블 관계 + +``` +quality_documents (품질관리서) +├── quality_document_orders (수주 연결, M:N) +│ └── orders +├── quality_document_locations (개소별 검사) +│ ├── order_items (대표 품목) +│ └── documents (EAV 성적서) +└── performance_reports (실적신고, 1:1) +``` + +### 4.2 주요 테이블 + +| 테이블 | 설명 | 주요 컬럼 | +|--------|------|----------| +| `quality_documents` | 품질관리서 | quality_doc_number, status, client_id, options(JSON) | +| `quality_document_orders` | 품질-수주 연결 | quality_document_id, order_id | +| `quality_document_locations` | 개소별 검사 | inspection_data(JSON), inspection_status, post_width/height | +| `performance_reports` | 실적신고 | year, quarter, confirmation_status, confirmed_date | + +### 4.3 options JSON 구조 (quality_documents) + +```json +{ + "construction_site": { + "name": "현장명", + "land_location": "대지위치", + "lot_no": "지번" + }, + "material_distributor": { + "company": "업체명", + "address": "주소", + "ceo": "대표자", + "tel": "전화번호" + }, + "contractor": { + "company": "업체명", + "address": "주소", + "name": "담당자", + "phone": "연락처" + }, + "supervisor": { + "office": "사무소명", + "address": "주소", + "name": "담당자", + "phone": "연락처" + } +} +``` + +--- + +## 5. API 엔드포인트 + +### 5.1 제품검사 (`/api/v1/quality/documents`) + +| Method | Path | 설명 | +|--------|------|------| +| GET | `/quality/documents` | 목록 (상태/날짜 필터) | +| GET | `/quality/documents/stats` | 상태별 통계 | +| GET | `/quality/documents/calendar` | 캘린더 스케줄 | +| GET | `/quality/documents/available-orders` | 미등록 수주 조회 | +| POST | `/quality/documents` | 생성 | +| GET | `/quality/documents/{id}` | 상세 | +| PUT | `/quality/documents/{id}` | 수정 | +| DELETE | `/quality/documents/{id}` | 삭제 | +| PATCH | `/quality/documents/{id}/complete` | 검사완료 (→ 실적신고 자동생성) | +| POST | `/quality/documents/{id}/orders` | 수주 연결 | +| DELETE | `/quality/documents/{id}/orders/{orderId}` | 수주 해제 | +| POST | `/quality/documents/{id}/locations/{locId}/inspect` | 개소별 검사 저장 | + +### 5.2 실적신고 (`/api/v1/quality/performance-reports`) + +| Method | Path | 설명 | +|--------|------|------| +| GET | `/quality/performance-reports` | 목록 (연도/분기/상태 필터) | +| GET | `/quality/performance-reports/stats` | 확정/미확정 통계 | +| GET | `/quality/performance-reports/missing` | 누락체크 | +| PATCH | `/quality/performance-reports/confirm` | 일괄 확정 | +| PATCH | `/quality/performance-reports/unconfirm` | 확정 해제 | +| PATCH | `/quality/performance-reports/memo` | 메모 일괄 업데이트 | + +--- + +## 6. 프론트엔드 구조 + +### 6.1 페이지 + +``` +react/src/app/[locale]/(protected)/quality/ +├── page.tsx # 대시보드 +├── inspections/ +│ ├── page.tsx # 검사 목록 +│ ├── new/page.tsx # 검사 생성 +│ └── [id]/page.tsx # 검사 상세/수정 +└── performance-reports/ + └── page.tsx # 실적신고 목록 +``` + +### 6.2 컴포넌트 + +``` +react/src/components/quality/ +├── InspectionManagement/ +│ ├── InspectionList.tsx # 검사 목록 +│ ├── InspectionCreate.tsx # 검사 생성 +│ ├── InspectionDetail.tsx # 검사 상세 (수정 포함) +│ ├── OrderSelectModal.tsx # 수주 선택 모달 +│ ├── ProductInspectionInputModal.tsx # 검사 입력 모달 +│ ├── actions.ts # Server Actions +│ ├── types.ts # TypeScript 타입 +│ └── documents/ # 요청서/성적서 문서 +└── PerformanceReportManagement/ + ├── PerformanceReportList.tsx # 실적신고 목록 (2탭) + ├── MemoModal.tsx # 메모 모달 + └── actions.ts # Server Actions +``` + +### 6.3 실적신고 화면 기능 + +**탭 1: 분기별 실적신고** +- 연도/분기 필터 +- 통계: 전체, 확정, 미확정, 총 개소 +- 테이블: 품질관리서번호, 작성일, 현장명, 수주처, 개소수, 필수정보 상태, 확정상태, 확정일, 메모 +- 액션: 선택 확정, 확정 해제, 메모 일괄 작성 + +**탭 2: 누락체크** +- 출고완료 수주 중 품질관리서 미등록 건 조회 +- 빠른 누락 확인으로 법규 준수 지원 + +--- + +## 7. 품질인정심사 (QMS) + +> 상세 문서: [quality-certification-audit.md](./quality-certification-audit.md) + +### 7.1 개요 + +품질 인정 심사 자료를 관리하는 기능. 두 가지 심사 영역으로 구성: + +| 심사 영역 | 설명 | 진행률 추적 | +|----------|------|-----------| +| 기준/매뉴얼 심사 | 품질 기준 문서 및 매뉴얼 점검표 체크 | 완료 항목 / 전체 항목 | +| 로트 추적 심사 | 품질관리서 → 수주코드 → 개소별 제품로트 → 관련 서류 추적 확인 | 확인 개소 / 전체 개소 | + +### 7.2 로트 추적 심사 구조 + +``` +품질관리서 목록 → 수주코드 목록 → 관련 서류 +(1단계 선택) (2단계 선택) (3단계 확인) +``` + +- 해당 분기 실적신고 확정 건 기준 +- 수입검사, 중간검사, 납품확인서, 출고증, 제품검사 성적서, 품질관리서 등 서류 연결 확인 + +### 7.3 구현 상태 + +**개발 예정** — 현재 페이지 구조만 존재 + +--- + +## 8. 미구현 기능 요약 + +| 기능 | 상태 | 설명 | +|------|------|------| +| 배포(distribute) API | 미구현 | 건기원 시스템 연동 자동 배포 | +| 확정건 엑셀 다운로드 | 미구현 | 확정된 실적 건기원 양식 엑셀 내보내기 | +| 품질인정심사 | 미구현 | 기준/매뉴얼 심사 + 로트 추적 심사 | + +--- + +## 9. 스토리보드 참조 + +> **출처**: `SAM_MES_경동기업_품질관리_Storyboard_D1.9_260224` + +| 슬라이드 | 화면 | 기능 영역 | +|---------|------|----------| +| 3 | 프로젝트 진행 플로우차트 | 전체 프로세스 | +| 5~6 | 제품검사 목록 + 캘린더 | 제품검사관리 | +| 7~9 | 제품검사 상세 | 제품검사관리 | +| 10 | 수주 선택 팝업 | 제품검사관리 | +| 11 | 제품검사 팝업 (검사 입력) | 제품검사관리 | +| 12~13 | 제품검사요청서 | 문서 출력 | +| 14~15 | 제품검사성적서 | 문서 출력 | +| 16 | 실적신고 목록 | 실적신고관리 | +| 17 | 메모 팝업 | 실적신고관리 | +| 18 | 누락체크 | 실적신고관리 | +| 19 | 품질인정심사 (기준/매뉴얼) | 품질인정심사 | +| 20 | 품질인정심사 (로트 추적) | 품질인정심사 | + +--- + +## 관련 문서 + +- [DB 스키마 — 생산/품질](../../system/database/production.md) +- [API 규칙](../../dev/standards/api-rules.md) +- [채번 규칙](../../rules/numbering-rules.md) + +--- + +**최종 업데이트**: 2026-03-09 diff --git a/features/quality-management/inspection-management.md b/features/quality-management/inspection-management.md new file mode 100644 index 0000000..f55c560 --- /dev/null +++ b/features/quality-management/inspection-management.md @@ -0,0 +1,317 @@ +# 제품검사 관리 (Inspection Management) + +> **작성일**: 2026-03-09 +> **상태**: 운영 중 +> **URL**: `/quality/inspections` + +--- + +## 1. 개요 + +### 1.1 목적 + +방화문 제품의 현장 출고 전 품질검사를 수행하고 검사성적서를 발행한다. +검사 완료 시 실적신고(PerformanceReport)를 자동 생성한다. + +### 1.2 품질관리서 구조 + +``` +품질관리서 (QualityDocument) +├── 기본정보: 채번, 현장명, 접수일, 검사자, 수주처 +├── 관련자 정보 (options JSON): +│ ├── 건축공사장 정보 +│ ├── 자재유통업자 정보 +│ ├── 공사시공자 정보 +│ └── 공사감리자 정보 +├── 수주 연결 (QualityDocumentOrder, 1:N) +│ └── 개소 (QualityDocumentLocation, 1:N) +│ ├── 시공규격 (post_width, post_height) +│ ├── 검사 데이터 (inspection_data JSON) +│ └── 검사성적서 (Document EAV) +└── 실적신고 (PerformanceReport, 1:1) +``` + +### 1.3 화면 구성 + +**목록 페이지** (슬라이드 5~6): +- 상단: 날짜 필터 (전체/전전월/전월/금월/어제/오늘) + 검색 +- 통계 카드: 접수, 진행중, 완료 건수 +- 테이블: 품질관리서번호, 번호, 수주처, 개소, 실적신고 필수정보, 검사시기, 검사자, 상태, 작성자, 접수일 +- 하단: **캘린더 스케줄** (월간 뷰) + +**캘린더 뷰**: +- 월 단위 표시, 상태 필터(전체/진행중/완료) +- 색상 구분: 완료(초록 배지), 진행중(파란 바) +- 검사 완료 건: `홍길동 - 현장명 / 완료` 형태 +- 검사 진행 건: `홍길동 - 현장명 / 진행중` 형태 (날짜 범위 바) +- 클릭 시 해당 제품검사 상세 화면으로 이동 + +**상세 페이지** (슬라이드 7~9): +- 기본 정보: 품질관리서번호, 현장명, 수주처, 접수일, 담당자, 연락처, 상태, 작성자 +- 관련자 정보 4개 섹션 (실적 신고 시 필수 정보) +- 검사 정보: 검사방문요청일, 검사시작일, 검사종료일, 검사자 +- 현장 주소: 우편번호 찾기 + 상세주소 +- 수주 설정 정보: 수주 선택 버튼 → 수주별 개소 목록 (층수/부호/수주규격/시공규격/변경사유) +- 하단 버튼: 검사제품요청서 보기, 제품검사성적서 보기, **검사 완료**, 수정 + +--- + +## 2. 상태 관리 + +### 2.1 품질관리서 상태 + +| 상태 | 코드 | 조건 | +|------|------|------| +| 접수 | `received` | 생성 직후, 수주 미연결 | +| 진행중 | `in_progress` | 수주 연결됨 또는 일부 검사 진행 | +| 완료 | `completed` | 모든 개소 검사 완료 후 `complete()` 호출 | + +### 2.2 개소별 검사 상태 (자동 판정) + +| 상태 | 코드 | 판정 기준 | +|------|------|----------| +| 대기 | `pending` | 검사 데이터 없음 (15개 항목 0개 + 사진 없음) | +| 진행중 | `in_progress` | 일부 항목 입력 또는 사진 미등록 | +| 완료 | `completed` | 15개 항목 전부 입력 + 사진 1장 이상 | + +### 2.3 상태 자동 재계산 + +개소별 검사 저장 시 → 개소 상태 자동 판정 → 품질관리서 상태 재계산: +- 전부 `pending` → `received` +- 하나라도 `completed` 또는 `in_progress` → `in_progress` +- 전부 `completed` → `in_progress` (수동 `complete()` 필요) + +--- + +## 3. 검사 항목 + +### 3.1 15개 검사 항목 + +| # | 키 | 분류 | 설명 | 판정값 | +|---|-----|------|------|--------| +| 1 | `appearanceProcessing` | 외관 | 가공 상태 | pass/fail | +| 2 | `appearanceSewing` | 외관 | 봉제 상태 | pass/fail | +| 3 | `appearanceAssembly` | 외관 | 조립 상태 | pass/fail | +| 4 | `appearanceSmokeBarrier` | 외관 | 차연재 상태 | pass/fail | +| 5 | `appearanceBottomFinish` | 외관 | 하부마감 상태 | pass/fail | +| 6 | `motor` | 기능 | 모터 작동 | pass/fail | +| 7 | `material` | 기능 | 소재 적합성 | pass/fail | +| 8 | `lengthJudgment` | 치수 | 가로 치수 | OK/NG | +| 9 | `heightJudgment` | 치수 | 세로 치수 | OK/NG | +| 10 | `guideRailGap` | 치수 | 가이드레일 간격 | OK/NG | +| 11 | `bottomFinishGap` | 치수 | 하부마감 간격 | OK/NG | +| 12 | `fireResistanceTest` | 시험 | 내화 시험 | pass/fail | +| 13 | `smokeLeakageTest` | 시험 | 차연 시험 | pass/fail | +| 14 | `openCloseTest` | 시험 | 개폐 시험 | pass/fail | +| 15 | `impactTest` | 시험 | 충격 시험 | pass/fail | + +### 3.2 추가 데이터 + +| 키 | 설명 | 필수 | +|----|------|------| +| `productImages` | 제품 사진 URL 배열 | 완료 판정에 필수 | + +--- + +## 4. 수주 연결 + +### 4.1 수주 선택 + +- `availableOrders()`: 해당 수주처(client_id)의 미등록 수주 조회 +- 모달에서 복수 수주 선택 가능 + +### 4.2 개소 자동생성 + +수주 연결 시 각 수주의 root node(층/부호)마다 개소(Location) 자동생성: + +``` +수주 A (3개 root node) +├── 1F A호 → Location 1 +├── 2F B호 → Location 2 +└── 3F C호 → Location 3 + +수주 B (2개 root node) +├── 지하1F → Location 4 +└── 1F → Location 5 +``` + +### 4.3 개소 데이터 + +| 필드 | 설명 | 출처 | +|------|------|------| +| `order_item_id` | 대표 OrderItem | root node의 첫 번째 품목 | +| `post_width` | 시공 가로 | 발주 규격에서 복사 (수정 가능) | +| `post_height` | 시공 세로 | 발주 규격에서 복사 (수정 가능) | +| `change_reason` | 변경 사유 | 규격 변경 시 입력 | + +--- + +## 5. 문서 자동생성 (EAV) + +### 5.1 제품검사요청서 (슬라이드 12~13) + +- **Template ID**: 66 (제품검사 요청서) +- **트리거**: 품질관리서 생성/수정 시 `syncRequestDocument()` 호출 +- **인쇄용 페이지 형태로 구분**되어 표시 (인쇄, 공유, 닫기 버튼) + +**문서 구성**: + +``` +┌─────────────────────────────────────────┐ +│ 제품검사요청서 │ +│ 문서번호: ABC123 | 작성일자: 2025.11.11 │ +│ │ +│ 승인라인: 작성 → 승인 → 승인 → 승인 │ +│ 홍길동 이름 이름 이름 │ +│ │ +│ ── 기본정보 ── │ +│ 수주처, 수주번호, 담당자, 연락처 │ +│ 현장명, 납품일, 총 개소, 접수일 │ +│ │ +│ ── 입력사항 (실적신고 필수 정보) ── │ +│ 건축공사장: 현장명, 대지위치, 지번 │ +│ 자재유통업자: 회사명, 회사주소, 대표자명, │ +│ 전화번호 │ +│ 공사시공자: 회사명, 회사주소, 성명, 전화번호 │ +│ 공사감리자: 사무소명, 사무소주소, 성명, │ +│ 전화번호 │ +│ │ +│ ── 검사대상 사전 고지 정보 ── │ +│ No. 층수 부호 발주규격(가로/세로) │ +│ 시공후규격(가로/세로) 변경사유 │ +└─────────────────────────────────────────┘ +``` + +**주의 문구** (빨간색): +- 발주 사이즈와 시공 완료된 사이즈가 다를 시 **실질 범위를 넣어야 한다** +- 변경사유를 고지하여야 인정마을을 부착할 수 있다 +- 사전고지를 하지 않음으로 발생하는 문제의 귀책은 신청업체에 있다 + +### 5.2 제품검사성적서 (슬라이드 14~15) + +- 각 개소별 `document_id`로 EAV Document 참조 +- 검사 결과(inspection_data)를 EAV 필드로 저장 +- **개소별 페이지 단위**: 1/50 형태의 페이지 네비게이션 (이전/이동/다음 버튼) + +**문서 구성**: + +``` +┌─────────────────────────────────────────┐ +│ 제품검사성적서 │ +│ 문서번호: ABC123 | 작성일자: 2025.11.11 │ +│ │ +│ 제품명, 제품 LOT NO, 로트크기 │ +│ 제품코드, 검사일자 │ +│ 수주처, 검사자 │ +│ 현장명 │ +│ │ +│ ── 제품 사진 ── │ +│ [IMG] [IMG] │ +│ │ +│ ── 검사 항목 ── │ +│ No. 검사항목 검사기준 검사 특정값 판정│ +│ 1 외모양 │ +│ 가공상태 사용상 해로운 결함이 없을 것 │ +│ 재봉상태 내화심에 의해 견고하게 접합 │ +│ 조립상태 핸드바 견고하게 조립되어야 함 │ +│ 연기차단재 연기차단재 가이드레일 W60, │ +│ 가이드레일 W50 (분체 설치) │ +│ 하단마감재 내부 부재형상 설치 유무 │ +│ 2 모터 인정제품과 동일사양 │ +│ 3 재질 WY-SC780 인쇄상태 확인 │ +│ 4 치수 │ +│ 길이 수주 치수 ± 30mm │ +│ 높이 수주 치수 ± 30mm │ +│ 가이드레일 10 ± 5mm (측정부위 길이 100 이내)│ +│ 간격 가이드레일갑과 하단마감재 25mm 이내│ +│ 5 작동테스트 6mm 관절게이지 관통 여 150mm │ +│ 6 내화시험 25mm 관절게이지 관통 유무 │ +│ 7 차연시험 10초 이상 자속되는 화염 발생 유무 │ +│ 8 개폐시험 전도/개폐 2.5~6.5m/min 등 │ +│ │ +│ 특이사항: │ +│ 종합판정: 합격 │ +│ │ +│ [이전] [1] /50 [이동] [다음] │ +└─────────────────────────────────────────┘ +``` + +--- + +## 6. API + +### 6.1 주요 엔드포인트 + +| Method | Path | 설명 | +|--------|------|------| +| GET | `/quality/documents` | 목록 | +| POST | `/quality/documents` | 생성 | +| GET | `/quality/documents/{id}` | 상세 | +| PUT | `/quality/documents/{id}` | 수정 (개소/규격 포함) | +| PATCH | `/quality/documents/{id}/complete` | 검사완료 | +| POST | `/quality/documents/{id}/orders` | 수주 연결 | +| DELETE | `/quality/documents/{id}/orders/{orderId}` | 수주 해제 | +| POST | `/quality/documents/{id}/locations/{locId}/inspect` | 개소별 검사 저장 | + +### 6.2 검사 저장 요청 예시 + +```json +POST /quality/documents/1/locations/5/inspect +{ + "inspection_data": { + "appearanceProcessing": "pass", + "appearanceSewing": "pass", + "appearanceAssembly": "pass", + "appearanceSmokeBarrier": "pass", + "appearanceBottomFinish": "pass", + "motor": "pass", + "material": "pass", + "lengthJudgment": "OK", + "heightJudgment": "OK", + "guideRailGap": "OK", + "bottomFinishGap": "OK", + "fireResistanceTest": "pass", + "smokeLeakageTest": "pass", + "openCloseTest": "pass", + "impactTest": "pass", + "productImages": ["https://..."] + } +} +``` + +--- + +## 7. 소스 파일 + +### 7.1 Backend + +| 파일 | 역할 | +|------|------| +| `api/app/Models/Qualitys/QualityDocument.php` | 품질관리서 모델 | +| `api/app/Models/Qualitys/QualityDocumentLocation.php` | 개소 모델 | +| `api/app/Models/Qualitys/QualityDocumentOrder.php` | 수주 연결 모델 | +| `api/app/Services/QualityDocumentService.php` | 서비스 (770줄) | +| `api/app/Http/Controllers/Api/V1/QualityDocumentController.php` | 컨트롤러 | + +### 7.2 Frontend + +| 파일 | 역할 | +|------|------| +| `react/src/components/quality/InspectionManagement/InspectionList.tsx` | 목록 | +| `react/src/components/quality/InspectionManagement/InspectionCreate.tsx` | 생성 | +| `react/src/components/quality/InspectionManagement/InspectionDetail.tsx` | 상세/수정 | +| `react/src/components/quality/InspectionManagement/OrderSelectModal.tsx` | 수주 선택 | +| `react/src/components/quality/InspectionManagement/ProductInspectionInputModal.tsx` | 검사 입력 | +| `react/src/components/quality/InspectionManagement/actions.ts` | Server Actions | +| `react/src/components/quality/InspectionManagement/types.ts` | 타입 정의 | + +--- + +## 관련 문서 + +- [품질관리 시스템 개요](./README.md) +- [생산실적신고](./performance-reports.md) + +--- + +**최종 업데이트**: 2026-03-09 diff --git a/features/quality-management/performance-reports.md b/features/quality-management/performance-reports.md new file mode 100644 index 0000000..a34f55d --- /dev/null +++ b/features/quality-management/performance-reports.md @@ -0,0 +1,268 @@ +# 생산실적신고 (Performance Reports) + +> **작성일**: 2026-03-09 +> **상태**: 운영 중 +> **URL**: `/quality/performance-reports` + +--- + +## 1. 개요 + +### 1.1 목적 + +건설기술진흥법에 따라 방화문 제품검사 완료 건에 대해 **분기별 실적신고**를 관리한다. +건기원(한국건설기술연구원) 온라인 시스템에 제출할 데이터를 자동 수집하고, 필수정보 검증 후 확정 처리한다. + +### 1.2 비즈니스 배경 + +- **법적 의무**: 방화문은 건축자재 품질관리 대상으로, 제품검사 후 실적을 건기원에 신고해야 함 +- **신고 주기**: 분기별 (Q1: 1~3월, Q2: 4~6월, Q3: 7~9월, Q4: 10~12월) +- **신고 내용**: 품질관리서 번호, 현장정보, LOT, 규격, 검사결과 +- **제출 방식**: 건기원 온라인 시스템 수기 입력 또는 엑셀 업로드 + +### 1.3 SAM에서의 역할 + +``` +제품검사 완료 → 실적신고 자동생성 → 필수정보 검증 → 확정 → 건기원 제출 + (SAM 자동) (SAM 자동) (담당자) (수동/향후 자동) +``` + +--- + +## 2. 상태 흐름 + +### 2.1 상태 정의 + +| 상태 | 코드 | 설명 | +|------|------|------| +| 미확정 | `unconfirmed` | 자동생성 직후, 필수정보 미완료 가능 | +| 확정 | `confirmed` | 필수정보 완료 후 담당자가 확정 | +| 신고완료 | `reported` | 건기원에 신고 완료 (미구현) | + +### 2.2 상태 전이 + +``` + confirm() +unconfirmed ─────────────────→ confirmed + ↑ │ + │ unconfirm() │ + └──────────────────────────────┘ + │ + distribute() + ↓ + reported (미구현) +``` + +### 2.3 확정 조건 + +확정(`confirm`) 시 **필수정보 4개 섹션** 검증: + +``` +✅ 건축공사장: name, land_location, lot_no +✅ 자재유통업자: company, address, ceo, tel +✅ 공사시공자: company, address, name, phone +✅ 공사감리자: office, address, name, phone +``` + +하나라도 누락되면 확정 불가 → `cannotConfirmWithMissingInfo` 에러 반환 + +--- + +## 3. 자동 생성 로직 + +### 3.1 트리거 + +`QualityDocumentService::complete()` 호출 시: + +```php +PerformanceReport::firstOrCreate( + [ + 'tenant_id' => $tenantId, + 'quality_document_id' => $qualityDocument->id, + ], + [ + 'year' => now()->year, // 현재 연도 + 'quarter' => ceil(now()->month / 3), // 현재 분기 + 'confirmation_status' => 'unconfirmed', + 'created_by' => $userId, + ] +); +``` + +### 3.2 특징 + +- `firstOrCreate`: 동일 품질관리서에 대해 중복 생성 방지 +- 검사완료 시점의 연도/분기로 자동 배정 +- Unique 제약: `(tenant_id, quality_document_id)` + +--- + +## 4. 화면 구성 + +### 4.1 탭 구조 + +| 탭 | 내용 | +|----|------| +| **분기별 실적신고** | 기본 탭. 연도/분기별 실적 목록 | +| **누락체크** | 출고완료 수주 중 품질관리서 미등록 건 | + +### 4.2 통계 카드 + +``` +┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ +│ 전체 │ │ 확정 │ │ 미확정 │ │ 총 개소 │ +│ 12건 │ │ 8건 │ │ 4건 │ │ 48개소 │ +└──────────┘ └──────────┘ └──────────┘ └──────────┘ +``` + +### 4.3 테이블 컬럼 (분기별 실적신고) + +| 컬럼 | 설명 | +|------|------| +| 선택 | 체크박스 (일괄 처리용) | +| 번호 | 순번 | +| 품질관리서번호 | KD-QD-YYYYMM-NNNN | +| 작성일 | 품질관리서 접수일 | +| 현장명 | 시공 현장명 | +| 수주처 | 거래처 | +| 개소 | 검사 개소 수 | +| 필수정보 | "완료" 또는 "N건 누락" | +| 확정상태 | 미확정/확정/신고완료 | +| 확정일 | 확정 처리일 | +| 메모 | 메모 내용 | + +### 4.4 액션 버튼 + +| 버튼 | 조건 | 설명 | +|------|------|------| +| 선택 확정 | 미확정 건 선택 시 | 필수정보 완료된 건만 일괄 확정 | +| 확정 해제 | 확정 건 선택 시 | 확정 → 미확정 되돌리기 | +| 배포 | 확정 건 선택 시 | 건기원 신고 (미구현) | +| 메모 | 건 선택 시 | 메모 일괄 작성 | + +--- + +## 5. 누락체크 (슬라이드 18) + +### 5.1 목적 + +실적신고 기간이 지났지만 확정이 안된 목록을 확인한다. +출고(배송)가 완료되었지만 품질관리서가 등록되지 않은 수주를 탐지한다. + +### 5.2 누락 발생 원인 + +| 원인 | 설명 | +|------|------| +| 품질관리서 발행일 기준 분기 불일치 | 품질관리서가 해당 분기에 포함되어야 하나, 공사 미완료로 다음 분기로 이월 | +| 수주 중복 등록 | 수주통 시 다른 현장명으로 등록되어 제품검사 발행 시 누락 | +| 납품 후 미등록 | 납품 후 제품검사 등록이 누락된 경우 | + +### 5.3 누락체크 목록 표시 + +| 컬럼 | 설명 | +|------|------| +| 품질관리서 번호 | 관련 품질관리서 (있는 경우) | +| 현장명 | 수주 현장명 | +| 수주처 | 거래처 | +| 개소 | 수주 개소 수 | +| 제품검사완료일 | 검사 완료 일자 | +| 메모 | 누락 사유 메모 | + +### 5.4 로직 + +```sql +-- 출고완료 수주 중 quality_document_orders에 미등록된 건 +SELECT orders.* +FROM orders +WHERE delivery_status = 'completed' + AND NOT EXISTS ( + SELECT 1 FROM quality_document_orders + WHERE order_id = orders.id + ) +``` + +--- + +## 6. API + +### 6.1 엔드포인트 + +| Method | Path | 설명 | +|--------|------|------| +| GET | `/quality/performance-reports` | 목록 (year, quarter, status 필터) | +| GET | `/quality/performance-reports/stats` | 확정/미확정 통계 | +| GET | `/quality/performance-reports/missing` | 누락체크 | +| PATCH | `/quality/performance-reports/confirm` | 일괄 확정 | +| PATCH | `/quality/performance-reports/unconfirm` | 확정 해제 | +| PATCH | `/quality/performance-reports/memo` | 메모 일괄 업데이트 | + +### 6.2 요청/응답 예시 + +**목록 조회**: +``` +GET /quality/performance-reports?year=2026&quarter=1&status=unconfirmed +``` + +**일괄 확정**: +```json +PATCH /quality/performance-reports/confirm +{ + "ids": [1, 2, 3] +} +``` + +**응답**: +```json +{ + "success": true, + "message": "message.performance_report.confirmed", + "data": { + "confirmed_count": 2, + "skipped_count": 1, + "skipped_ids": [3] + } +} +``` + +--- + +## 7. 소스 파일 + +### 7.1 Backend + +| 파일 | 역할 | +|------|------| +| `api/app/Models/Qualitys/PerformanceReport.php` | 모델 | +| `api/app/Services/PerformanceReportService.php` | 서비스 (280줄) | +| `api/app/Http/Controllers/Api/V1/PerformanceReportController.php` | 컨트롤러 | +| `api/routes/api/v1/quality.php` | 라우트 | + +### 7.2 Frontend + +| 파일 | 역할 | +|------|------| +| `react/src/app/[locale]/(protected)/quality/performance-reports/page.tsx` | 페이지 | +| `react/src/components/quality/PerformanceReportManagement/PerformanceReportList.tsx` | 목록 컴포넌트 | +| `react/src/components/quality/PerformanceReportManagement/MemoModal.tsx` | 메모 모달 | +| `react/src/components/quality/PerformanceReportManagement/actions.ts` | Server Actions | + +--- + +## 8. 미구현 기능 + +| 기능 | 설명 | 우선순위 | +|------|------|---------| +| 배포(distribute) API | 건기원 시스템 연동 자동 신고 | 중 | +| 엑셀 다운로드 | 확정건 건기원 양식 엑셀 내보내기 | 높음 | +| 분기 마감 알림 | 분기 종료 전 미확정건 알림 | 낮음 | + +--- + +## 관련 문서 + +- [품질관리 시스템 개요](./README.md) +- [제품검사 관리](./inspection-management.md) + +--- + +**최종 업데이트**: 2026-03-09 diff --git a/features/quality-management/quality-certification-audit.md b/features/quality-management/quality-certification-audit.md new file mode 100644 index 0000000..f64936b --- /dev/null +++ b/features/quality-management/quality-certification-audit.md @@ -0,0 +1,169 @@ +# 품질인정심사 (Quality Certification Audit) + +> **작성일**: 2026-03-09 +> **상태**: 개발 예정 +> **URL**: `/quality/qms` +> **스토리보드**: 슬라이드 19~20 + +--- + +## 1. 개요 + +### 1.1 목적 + +품질인정심사 자료를 조회하고 관리한다. 기준/매뉴얼 심사와 로트 추적 심사 두 가지 영역으로 구성된다. + +### 1.2 탭 구조 + +| 탭 | 설명 | 진행률 예시 | +|----|------|-----------| +| 기준/매뉴얼 심사 | 품질 기준 문서 및 매뉴얼 점검 | 2/15 | +| 로트 추적 심사 | 개소별 제품로트 추적 및 서류 확인 | 7/12 | + +**전체 심사 진행률**: 기준/매뉴얼 + 로트추적 합산 (예: 9/27) + +--- + +## 2. 기준/매뉴얼 심사 + +### 2.1 화면 구성 + +``` +┌─────────────────────────────────────────────────────┐ +│ 필터: 연도, 분기(전체/1~4), 검색 │ +├──────────────────┬──────────────────────────────────┤ +│ 점검표 항목 │ 기준 문서화 │ +│ │ │ +│ ▼ 1. 제목 │ 항목명 ─────────── │ +│ ☑ 1. 항목 [완료] │ 소개 ─────────── │ +│ ☑ 2. 항목 [완료] │ │ +│ □ 3. 항목 │ 관련 기준 문서 │ +│ │ 📄 문서명 R025 2025-01-01 │ +│ ▼ 2. 제목 │ 📄 문서명 R025 2025-01-01 │ +│ ☑ 1. 항목 │ │ +│ ☑ 2. 항목 │ 📎 기준/매뉴얼 확인 │ +│ □ 3. 항목 │ │ +│ │ 문서 미리보기 영역 │ +│ 완료 체크 박스 │ (PDF 등) │ +│ □ 완료 │ 파일명: 파일명.pdf 1/1 페이지 │ +└──────────────────┴──────────────────────────────────┘ +``` + +### 2.2 점검표 항목 + +- 계층 구조: 대분류(제목) → 세부 항목 +- 각 항목에 완료/미완료 체크 +- 항목 클릭 시 우측에 해당 항목의 기준 문서 정보 표시 + +### 2.3 기준 문서화 + +| 영역 | 설명 | +|------|------| +| 항목명 및 소개 | 선택한 점검표 항목의 상세 정보 | +| 관련 기준 문서 | 해당 항목에 연결된 기준 문서 목록 (문서명, 문서번호, 날짜) | +| 문서 미리보기 | PDF 등 첨부 문서 미리보기 | +| 완료 체크 박스 | 기본값: 완료 해제 상태 | + +### 2.4 기준/매뉴얼 확인 버튼 + +- 클릭 시 확인 완료 스티커로 변경 +- 전체 항목 확인 완료 시 탭 진행률 갱신 + +--- + +## 3. 로트 추적 심사 + +### 3.1 화면 구성 + +``` +┌───────────────────────────────────────────────────────────┐ +│ 필터: 연도, 분기(전체/1~4), 검색 │ +├─────────────────┬─────────────────┬───────────────────────┤ +│ 품질관리서 목록 │ 수주코드 목록 │ 관련 서류 │ +│ │ │ │ +│ KD-SS-2024- │ KD-SS-240921-19 │ 수입검사 성적서 │ +│ 2025년 3분기 │ 수주: 2024-09-24│ ┌──────────────────┐ │ +│ 현장명 │ 7개소 / 완료 │ │ 전반 수입검사 성적서│ │ +│ 인정특성, 실리카 │ │ │ 절반 수입검사 성적서│ │ +│ 수주코드 2건 │ 개소별 제품로트 │ └──────────────────┘ │ +│ 14개소 │ KD-SS-240921-19 │ │ +│ │ -01 │ 개소별 제품로트 목록 │ +│ KD-SS-2024- │ 보조 │ 수주코드번호 │ +│ 현장명 │ │ 가로, 세로 │ +│ 수주코드 2건 │ KD-SS-240921-19 │ 3건의 서류 │ +│ 7개소 │ -19 [확인] │ │ +│ │ 보조 │ 확인 서류 목록 │ +│ │ │ 수입검사, 일반전표, │ +│ │ │ 중간검사, 납품확인서, │ +│ │ │ 출고증, 제품검사, │ +│ │ │ 검사 성적서, 품질관리서│ +├─────────────────┴─────────────────┤ │ +│ 문서 정보 영역 │ 확인 버튼 │ +│ 품질: 해당 문서 열람/닫힘 토글 │ [확인] [완료] │ +└────────────────────────────────────┴───────────────────────┘ +``` + +### 3.2 3단 드릴다운 구조 + +| 단계 | 영역 | 표시 내용 | +|------|------|---------| +| 1단계 | 품질관리서 목록 | 해당 분기 확정된 품질관리서, 인정특성, 수주코드 건수, 개소수 | +| 2단계 | 수주코드 목록 | 선택한 품질관리서의 수주코드, 수주일, 개소수, 완료 상태 | +| 3단계 | 관련 서류 | 해당 수주코드의 개소별 제품로트, 확인 서류 목록 | + +### 3.3 품질관리서 목록 (1단계) + +- 해당 분기로 실적신고 확정된 품질관리서 +- 표시: 품질관리서 번호, 해당 분기, 현장명, 인정특성, 수주코드 건수, 개소수 +- 클릭 시 2단계(수주코드 목록) 표시 + +### 3.4 수주코드 목록 (2단계) + +- 해당 품질관리서에 연결된 수주코드 목록 +- 품질관리서는 제품검사 시 수주코드 연결 +- 표시: 수주코드 번호, 개소 수, 수주일, 현장, 개소수, 개소별 제품로트 확인 여부 +- 클릭 시 5단계 영역에 해당 수주코드의 관련 서류 표시 + +### 3.5 관련 서류 (3단계) + +개소별 제품로트에 연결된 서류: + +| 서류 종류 | 설명 | +|---------|------| +| 수입검사 성적서 | 원자재 수입검사 결과 | +| 일반전표 | 회계 전표 | +| 중간검사 성적서 | 공정 중간검사 | +| 납품확인서 | 납품 확인 | +| 출고증 | 출고 기록 | +| 제품검사 성적서 | 완제품 검사 | +| 품질관리서 | 품질관리서 원본 | + +### 3.6 확인 프로세스 + +1. 품질관리서 선택 → 수주코드 선택 → 관련 서류 조회 +2. 각 서류를 열람하고 **확인** 버튼 클릭 +3. 모든 서류 확인 완료 시 해당 로트 **완료** 처리 +4. 전체 로트 완료 시 로트 추적 심사 진행률 갱신 + +--- + +## 4. 구현 상태 + +| 기능 | 상태 | 비고 | +|------|------|------| +| 기준/매뉴얼 심사 점검표 | 미구현 | 페이지만 존재 | +| 기준 문서 관리 | 미구현 | | +| 로트 추적 심사 | 미구현 | | +| 서류 연결/확인 | 미구현 | | + +--- + +## 관련 문서 + +- [품질관리 시스템 개요](./README.md) +- [제품검사 관리](./inspection-management.md) +- [생산실적신고](./performance-reports.md) + +--- + +**최종 업데이트**: 2026-03-09