# 자재관리 - 부적합관리 기획서

> **작성일**: 2026-03-19
> **상태**: 기획 중
> **담당**: R&D실
> **라우트**: `/material/nonconforming-management`

---

## 1. 개요

### 1.1 목적

제조 공정 및 자재 입고 과정에서 발생하는 품질 부적합(불량)을 체계적으로 기록하고, 원인 분석 → 시정 조치 → 비용 산정까지 일괄 관리하는 기능을 제공한다.

### 1.2 핵심 컨셉

SAM 수주서의 화면 구조(FormSection 기반 섹션 레이아웃 + 하단 품목 테이블)를 그대로 따르되, **3가지 핵심 데이터**에 집중한다:

```
┌─────────────────────────────────────────────┐
│  1. 불량 내역 — 무엇이, 언제, 어디서 발생   │
│  2. 처리 방법 — 원인 분석 + 시정/개선 조치   │
│  3. 자재 내역과 비용 — 손실 비용 산정         │
└─────────────────────────────────────────────┘
```

### 1.3 참고

- 타사 양식: "품질불량(부적합) 원인분석 및 개선 대책 보고서"
- SAM 내부: 수주 등록(`OrderRegistration.tsx`) 구조 준용

---

## 2. 화면 구성

> SAM 수주서처럼 `IntegratedDetailTemplate` + `FormSection` 패턴을 따른다.
> 목록 → 등록/상세 → 수정 모드를 `?mode=new|edit` 쿼리파라미터로 분기한다.

### 2.1 목록 페이지

`/material/nonconforming-management`

| 필터 | 타입 | 설명 |
|------|------|------|
| 기간 | DateRangePicker | 발생일 기준 |
| 상태 | Select | 전체/접수/분석중/조치완료/종결 |
| 부적합 유형 | Select | 자재불량/공정불량/시공불량/기타 |
| 검색 | Input | 부적합번호, 현장명, 품목명 |

| 순서 | 컬럼 | 설명 |
|------|------|------|
| 1 | 체크박스 | 행 선택 |
| 2 | No. | 자동 번호 |
| 3 | 부적합번호 | `NC-YYYYMMDD-NNN` |
| 4 | 부적합 유형 | 자재불량/공정불량/시공불량/기타 |
| 5 | 현장명 | 발생 현장 |
| 6 | 품목명 | 관련 품목 |
| 7 | 발생일 | 불량 발생 날짜 |
| 8 | 비용 합계 | 자재+운송+시공+기타 |
| 9 | 상태 | Badge (접수/분석중/조치완료/종결) |
| 10 | 등록자 | 작성자명 |

### 2.2 등록/상세 페이지 — 섹션 구성

`/material/nonconforming-management?mode=new`
`/material/nonconforming-management/{id}`
`/material/nonconforming-management/{id}?mode=edit`

수주서와 동일한 패턴으로 5개 FormSection을 배치한다:

```
┌─ IntegratedDetailTemplate ──────────────────────────────────┐
│                                                             │
│  [섹션 1] 기본 정보                                         │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ 부적합번호  │ 상태(Badge)                            │    │
│  │ 발생일      │ 확인일       │ 부적합 유형             │    │
│  │ 현장명 (🔍 수주 연결)      │ 부서                    │    │
│  │ 등록자      │ 관련 직원    │ 관련 수주번호           │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                             │
│  [섹션 2] 불량 내역 ★핵심                                   │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ 관련 품목 (🔍 품목 검색)    │ 불량 수량  │ 단위      │    │
│  │ 불량 상세 설명 (Textarea)                            │    │
│  │ 첨부파일 (이미지/문서 다중 업로드)                   │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                             │
│  [섹션 3] 원인 분석 및 처리 방안 ★핵심                      │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ 불량 발생 원인 및 분석 (Textarea)                    │    │
│  │ 처리 방안 및 개선 사항 (Textarea)                    │    │
│  │ 시정 조치 완료일  │ 조치 담당자                      │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                             │
│  [섹션 4] 자재 내역 및 비용 ★핵심                           │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ 원자재 및 자재 소요량 설명 (Textarea)                │    │
│  │ ┌─ 자재 상세 테이블 ───────────────────────────┐    │    │
│  │ │ No │ 품목명 │ 규격 │ 수량│단가│금액│비고    │    │    │
│  │ │ 1  │ ...    │ ...  │    │    │    │        │    │    │
│  │ │    │        │      │    │    │    │ [+추가] │    │    │
│  │ └──────────────────────────────────────────────┘    │    │
│  │ ┌─ 비용 요약 ─────────────────────────────────┐    │    │
│  │ │ 자재비용 │ 운송비용 │ 시공비용 │ 기타 │ 합계 │    │    │
│  │ └──────────────────────────────────────────────┘    │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                             │
│  [섹션 5] 비고                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ 비고 (Textarea)                                      │    │
│  │ 도면 저장 위치 (Input)                                │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                             │
│  ── sticky bottom bar ──────────────────────────────────    │
│  │ [취소]                        [저장] / [결재상신]    │    │
│  ────────────────────────────────────────────────────────   │
└─────────────────────────────────────────────────────────────┘
```

### 2.3 상태 워크플로우

```
접수(RECEIVED) → 분석중(ANALYZING) → 조치완료(RESOLVED) → 종결(CLOSED)
                                                          ↗
                                  → 결재상신 → 승인 시 종결
```

| 상태 | 설명 | 액션 |
|------|------|------|
| `RECEIVED` | 부적합 접수 (초기 상태) | 등록 시 자동 |
| `ANALYZING` | 원인 분석 중 | 분석 시작 클릭 |
| `RESOLVED` | 시정 조치 완료 | 조치 완료 클릭 |
| `CLOSED` | 종결 (결재 승인 후) | 결재 승인 시 자동 |

---

## 3. 데이터 모델

### 3.1 nonconforming_reports (부적합 보고서)

> `api` 프로젝트에서 마이그레이션 관리 (공용 테이블)

| 컬럼 | 타입 | 설명 |
|------|------|------|
| `id` | bigint PK | |
| `tenant_id` | bigint FK | 테넌트 |
| `nc_number` | varchar(30) | 부적합번호 `NC-YYYYMMDD-NNN` |
| `status` | varchar(20) | RECEIVED/ANALYZING/RESOLVED/CLOSED |
| `nc_type` | varchar(20) | 부적합 유형 (material/process/construction/other) |
| `occurred_at` | date | 발생일 |
| `confirmed_at` | date | 불량 확인일 |
| `site_name` | varchar(100) | 현장명 |
| `department_id` | bigint FK nullable | 부서 |
| `order_id` | bigint FK nullable | 관련 수주 |
| `item_id` | bigint FK nullable | 관련 품목 |
| `defect_quantity` | decimal(10,2) nullable | 불량 수량 |
| `unit` | varchar(20) nullable | 단위 |
| `defect_description` | text nullable | 불량 상세 설명 |
| `cause_analysis` | text nullable | 원인 분석 |
| `corrective_action` | text nullable | 처리 방안 및 개선 사항 |
| `action_completed_at` | date nullable | 조치 완료일 |
| `action_manager_id` | bigint FK nullable | 조치 담당자 |
| `related_employee_id` | bigint FK nullable | 관련 직원 |
| `material_cost` | decimal(12,0) default 0 | 자재 비용 |
| `shipping_cost` | decimal(12,0) default 0 | 운송 비용 |
| `construction_cost` | decimal(12,0) default 0 | 시공 비용 |
| `other_cost` | decimal(12,0) default 0 | 기타 비용 |
| `total_cost` | decimal(12,0) default 0 | 비용 합계 (자동 계산) |
| `remarks` | text nullable | 비고 |
| `drawing_location` | varchar(255) nullable | 도면 저장 위치 |
| `options` | json nullable | 확장 속성 |
| `created_by` | bigint FK | 등록자 |
| `updated_by` | bigint FK nullable | |
| `deleted_by` | bigint FK nullable | |
| `created_at` | timestamp | |
| `updated_at` | timestamp | |
| `deleted_at` | timestamp nullable | 소프트 삭제 |

### 3.2 nonconforming_report_items (부적합 자재 상세)

> 수주의 `order_items`처럼 부적합 보고서에 연결된 자재 내역

| 컬럼 | 타입 | 설명 |
|------|------|------|
| `id` | bigint PK | |
| `tenant_id` | bigint FK | 테넌트 |
| `nonconforming_report_id` | bigint FK | 부적합 보고서 |
| `item_id` | bigint FK nullable | 품목 마스터 연결 |
| `item_name` | varchar(100) | 품목명 (수동 입력 허용) |
| `specification` | varchar(100) nullable | 규격/사양 |
| `quantity` | decimal(10,2) default 0 | 수량 |
| `unit_price` | decimal(12,0) default 0 | 단가 |
| `amount` | decimal(12,0) default 0 | 금액 (수량 x 단가) |
| `sort_order` | int default 0 | 정렬 순서 |
| `remarks` | varchar(255) nullable | 비고 |
| `options` | json nullable | 확장 속성 |
| `created_at` | timestamp | |
| `updated_at` | timestamp | |

### 3.3 첨부파일

기존 SAM 파일 시스템(`files` 테이블 polymorphic) 활용:

```php
// NonconformingReport 모델
public function files(): MorphMany
{
    return $this->morphMany(File::class, 'fileable');
}
```

---

## 4. API 엔드포인트

> prefix: `/api/v1/material/nonconforming-reports`

| Method | Path | 설명 |
|--------|------|------|
| GET | `/` | 목록 조회 (필터/검색/페이지네이션) |
| GET | `/stats` | 상태별 통계 |
| GET | `/{id}` | 단건 조회 (items, files 포함) |
| POST | `/` | 등록 (items 포함 일괄 저장) |
| PUT | `/{id}` | 수정 (items sync) |
| DELETE | `/{id}` | 소프트 삭제 |
| PATCH | `/{id}/status` | 상태 변경 |
| POST | `/{id}/files` | 첨부파일 업로드 |
| DELETE | `/{id}/files/{fileId}` | 첨부파일 삭제 |

### 4.1 등록 요청 예시

```json
{
  "nc_type": "material",
  "occurred_at": "2026-03-19",
  "confirmed_at": "2026-03-19",
  "site_name": "강남 현장",
  "department_id": 3,
  "order_id": 152,
  "item_id": 45,
  "defect_quantity": 10,
  "unit": "EA",
  "defect_description": "V-CUT 불량 - 절단면 틀어짐",
  "cause_analysis": "절단기 날 마모로 인한 정밀도 저하",
  "corrective_action": "절단기 날 교체 및 정밀도 재검증",
  "material_cost": 150000,
  "shipping_cost": 30000,
  "construction_cost": 0,
  "other_cost": 0,
  "drawing_location": "nas2dual/도면/2026/03",
  "related_employee_id": 12,
  "remarks": "",
  "items": [
    {
      "item_id": 45,
      "item_name": "알루미늄 프레임 50T",
      "specification": "50 x 3000mm",
      "quantity": 10,
      "unit_price": 15000,
      "remarks": "전량 폐기"
    }
  ]
}
```

### 4.2 목록 응답 예시

```json
{
  "data": [
    {
      "id": 1,
      "nc_number": "NC-20260319-001",
      "nc_type": "material",
      "nc_type_label": "자재불량",
      "site_name": "강남 현장",
      "item_name": "알루미늄 프레임 50T",
      "occurred_at": "2026-03-19",
      "total_cost": 180000,
      "status": "RECEIVED",
      "status_label": "접수",
      "creator_name": "김보곤"
    }
  ],
  "meta": { "current_page": 1, "total": 15 }
}
```

---

## 5. 비즈니스 규칙

### 5.1 채번 규칙

| 항목 | 규칙 |
|------|------|
| 형식 | `NC-YYYYMMDD-NNN` |
| 예시 | `NC-20260319-001` |
| 리셋 | 일자별 순번 리셋 |
| 테넌트 | 테넌트별 독립 채번 |

### 5.2 비용 자동 계산

```
total_cost = material_cost + shipping_cost + construction_cost + other_cost
material_cost = SUM(items[].amount) (자재 상세 테이블 합계로 자동 산정)
```

- 자재 상세 테이블의 금액 합계가 변경되면 `material_cost` 자동 갱신
- `total_cost`는 4개 비용 항목의 합계로 자동 계산 (프론트/백엔드 양쪽)

### 5.3 상태 전이 규칙

| 현재 상태 | 가능한 전이 | 조건 |
|----------|-----------|------|
| RECEIVED | → ANALYZING | — |
| ANALYZING | → RESOLVED | `cause_analysis` + `corrective_action` 필수 |
| RESOLVED | → CLOSED | 결재 승인 시 |
| CLOSED | (변경 불가) | 종결 후 수정 불가 (열람만) |

### 5.4 수주 연결

- 현장명 입력 시 기존 수주를 검색하여 연결 가능 (선택적)
- 수주 연결 시 현장명, 거래처 등 기본 정보 자동 채움
- 연결 없이도 수동 입력 허용

### 5.5 결재 연동

- SAM 기존 결재 시스템(`approval_requests` 테이블)과 연동
- "결재상신" 버튼으로 결재 요청 생성
- 결재 승인 시 상태가 `CLOSED`로 자동 전환

---

## 6. 구현 범위 (Phase)

### Phase 1 — 기본 CRUD + 비용 산정

- [ ] DB 마이그레이션 (`nonconforming_reports`, `nonconforming_report_items`)
- [ ] API: Controller, Service, Model, FormRequest
- [ ] React: 목록 페이지 (필터, 검색, 페이지네이션)
- [ ] React: 등록/수정 페이지 (5개 섹션)
- [ ] React: 자재 상세 테이블 (추가/삭제/금액 자동 계산)
- [ ] React: 비용 요약 (4항목 + 합계)
- [ ] 첨부파일 업로드 (기존 File 시스템 활용)

### Phase 2 — 워크플로우 + 결재

- [ ] 상태 워크플로우 (RECEIVED → ANALYZING → RESOLVED → CLOSED)
- [ ] 결재 시스템 연동 (결재상신 → 승인 시 종결)
- [ ] 상태별 수정 제한 (CLOSED 시 읽기 전용)

### Phase 3 — 통계 + 연동

- [ ] 대시보드 통계 카드 (월별 부적합 건수, 비용 추이)
- [ ] 수주 연결 강화 (수주 상세에서 부적합 이력 조회)
- [ ] 엑셀 Export
- [ ] 인쇄용 보고서 (DomPDF)

---

## 7. 기술 설계 요약

### 7.1 API 파일 구조

```
api/app/
├── Http/Controllers/Api/V1/Material/
│   └── NonconformingReportController.php
├── Services/Material/
│   └── NonconformingReportService.php
├── Models/Material/
│   ├── NonconformingReport.php
│   └── NonconformingReportItem.php
├── Http/Requests/Material/
│   ├── StoreNonconformingReportRequest.php
│   └── UpdateNonconformingReportRequest.php
└── database/migrations/
    ├── xxxx_create_nonconforming_reports_table.php
    └── xxxx_create_nonconforming_report_items_table.php
```

### 7.2 React 파일 구조

```
react/src/
├── app/[locale]/(protected)/material/
│   └── nonconforming-management/
│       ├── page.tsx                      ← 목록 + mode 분기
│       └── [id]/page.tsx                 ← 상세/수정
├── components/material/nonconforming/
│   ├── NonconformingList.tsx             ← 목록
│   ├── NonconformingForm.tsx             ← 등록/수정 폼 (5개 FormSection)
│   ├── NonconformingDetail.tsx           ← 상세 뷰
│   ├── NonconformingItemTable.tsx        ← 자재 상세 테이블
│   ├── CostSummary.tsx                   ← 비용 요약 (4항목+합계)
│   └── actions.ts                        ← Server Actions
```

### 7.3 모델 주요 설정

```php
// NonconformingReport.php
class NonconformingReport extends Model
{
    use Auditable, BelongsToTenant, ModelTrait, SoftDeletes;

    protected $casts = [
        'options' => 'array',
        'occurred_at' => 'date',
        'confirmed_at' => 'date',
        'action_completed_at' => 'date',
        'material_cost' => 'integer',
        'shipping_cost' => 'integer',
        'construction_cost' => 'integer',
        'other_cost' => 'integer',
        'total_cost' => 'integer',
    ];

    public function items(): HasMany { ... }
    public function order(): BelongsTo { ... }
    public function item(): BelongsTo { ... }
    public function files(): MorphMany { ... }
    public function department(): BelongsTo { ... }
}
```

---

## 관련 문서

- `rules/item-policy.md` — 품목 정책
- `features/quotes/README.md` — 견적/수주 시스템
- `system/database/production.md` — 생산/자재/품질 DB

---

**최종 업데이트**: 2026-03-19