# 부적합관리 API 구현 (Phase 1-A + 결재 연동)

**날짜:** 2026-03-19
**작업자:** Claude Code

## 변경 개요

자재관리 - 부적합관리 기능의 API를 구현했다. 부적합 보고서 CRUD + 자재 내역/비용 관리 + 결재 시스템 연동까지 완료.

---

## 수정된 파일

### 신규 생성

| 파일 | 변경 내용 |
|------|----------|
| `database/migrations/2026_03_19_100000_create_nonconforming_reports_table.php` | `nonconforming_reports` + `nonconforming_report_items` 테이블 |
| `database/migrations/2026_03_19_110000_add_approval_id_to_nonconforming_reports_table.php` | `approval_id` FK 추가 |
| `app/Models/Materials/NonconformingReport.php` | 부적합 보고서 모델 (관계, cast, 상수, 헬퍼) |
| `app/Models/Materials/NonconformingReportItem.php` | 자재 상세 내역 모델 |
| `app/Services/NonconformingReportService.php` | CRUD + 채번 + 비용 계산 + 상태 전이 + 결재상신 |
| `app/Http/Controllers/Api/V1/NonconformingReportController.php` | REST 8개 엔드포인트 |
| `app/Http/Requests/Material/StoreNonconformingReportRequest.php` | 등록 검증 |
| `app/Http/Requests/Material/UpdateNonconformingReportRequest.php` | 수정 검증 |

### 수정

| 파일 | 변경 내용 |
|------|----------|
| `routes/api/v1/inventory.php` | 부적합관리 라우트 8개 등록 |
| `lang/ko/error.php` | 부적합관리 에러 메시지 7개 추가 |
| `app/Services/ApprovalService.php` | 부적합 결재 콜백 3개 추가 (승인/반려/회수) |

---

## API 엔드포인트 (8개)

| Method | Path | 설명 |
|--------|------|------|
| GET | `/api/v1/material/nonconforming-reports` | 목록 (필터/검색/페이지네이션) |
| GET | `/api/v1/material/nonconforming-reports/stats` | 상태별 통계 |
| POST | `/api/v1/material/nonconforming-reports` | 등록 (items 일괄) |
| GET | `/api/v1/material/nonconforming-reports/{id}` | 단건 조회 |
| PUT | `/api/v1/material/nonconforming-reports/{id}` | 수정 (items sync) |
| DELETE | `/api/v1/material/nonconforming-reports/{id}` | 소프트 삭제 |
| PATCH | `/api/v1/material/nonconforming-reports/{id}/status` | 상태 변경 |
| POST | `/api/v1/material/nonconforming-reports/{id}/submit-approval` | 결재상신 |

---

## 주요 기능

### 채번

- 형식: `NC-YYYYMMDD-NNN` (테넌트별, 일자별 리셋)

### 비용 자동 계산

- `material_cost` = 자재 상세 테이블 금액 합계
- `total_cost` = 자재 + 운송 + 시공 + 기타

### 상태 워크플로우

```
RECEIVED → ANALYZING → RESOLVED → (결재상신) → 승인 → CLOSED
                                              → 반려/회수 → RESOLVED (재상신 가능)
```

### 결재 연동

- `linkable_type` = `NonconformingReport::class` 으로 Approval과 polymorphic 연결
- 승인 시 자동 CLOSED, 반려/회수 시 approval_id 해제

---

## 프론트엔드 전달 문서

- `docs/frontend/api-specs/nonconforming-api.md` — 8개 엔드포인트 + 화면 가이드 + Server Actions 예시
- `docs/dev/dev_plans/nonconforming-management-plan.md` — 기획서 (API/FE 분리 단계별 계획)

---

## 관련 문서

- `dev/dev_plans/nonconforming-management-plan.md` — 기획서
- `frontend/api-specs/nonconforming-api.md` — FE API 명세
- `dev/guides/approval-module-integration-guide.md` — 결재 모듈 통합 가이드

---

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