sam-docs/features/quality-management/README.md

품질관리 시스템

작성일: 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

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

3.1 자동 생성

• 트리거: 품질관리서 검사완료(complete()) 시
• 생성 기준: 현재 연도 + 분기 (year, quarter)
• 초기 상태: unconfirmed

3.2 확정 프로세스

unconfirmed (미확정)
    ↓ confirm() — 필수정보 검증 통과 시
confirmed (확정)
    ↓ distribute() — 건기원 신고 시 (미구현)
reported (신고완료)

확정 해제: confirmed → unconfirmed (unconfirm)

3.3 필수정보 검증

확정 전 4가지 섹션의 필수필드가 모두 입력되어야 함:

섹션	필수필드
건축공사장	현장명, 대지위치, 지번
자재유통업자	업체명, 주소, 대표자, 전화번호
공사시공자	업체명, 주소, 담당자, 연락처
공사감리자	사무소명, 주소, 담당자, 연락처

3.4 누락체크

• 출고완료(배송 완료)된 수주 중 품질관리서가 미등록된 건 탐지
• 별도 탭에서 조회 가능

3.5 건기원 실적신고 비즈니스 컨텍스트

건기원(한국건설기술연구원) 실적신고는 법적 의무:

• 주기: 분기별 (13월, 46월, 79월, 1012월)
• 대상: 해당 분기에 검사 완료된 모든 건
• 내용: 품질관리서 번호, 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)

{
  "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

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 스키마 — 생산/품질
• API 규칙
• 채번 규칙

---

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