sam-docs/features/quality-management/performance-reports.md

생산실적신고 (Performance Reports)

작성일: 2026-03-09 상태: 운영 중 URL: /quality/performance-reports

---

1. 개요

1.1 목적

건설기술진흥법에 따라 방화문 제품검사 완료 건에 대해 분기별 실적신고를 관리한다. 건기원(한국건설기술연구원) 온라인 시스템에 제출할 데이터를 자동 수집하고, 필수정보 검증 후 확정 처리한다.

1.2 비즈니스 배경

• 법적 의무: 방화문은 건축자재 품질관리 대상으로, 제품검사 후 실적을 건기원에 신고해야 함
• 신고 주기: 분기별 (Q1: 13월, Q2: 46월, Q3: 79월, Q4: 1012월)
• 신고 내용: 품질관리서 번호, 현장정보, 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() 호출 시:

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 로직

-- 출고완료 수주 중 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

일괄 확정:

PATCH /quality/performance-reports/confirm
{
  "ids": [1, 2, 3]
}

응답:

{
  "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	건기원 시스템 연동 자동 신고	중
엑셀 다운로드	확정건 건기원 양식 엑셀 내보내기	높음
분기 마감 알림	분기 종료 전 미확정건 알림	낮음

---

관련 문서

• 품질관리 시스템 개요
• 제품검사 관리

---

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