docs: [material] 부적합관리 기획서 API/FE 분리 단계별 계획 재구성

- Phase별 API 선행 → FE 후행 구조로 분리
- 각 Phase마다 API 산출물, FE 전달자료 명시
- API 엔드포인트를 Phase별로 분류
- 병행 개발 일정 다이어그램 추가

dev/dev_plans/nonconforming-management-plan.md

@@ -334,30 +334,165 @@ material_cost = SUM(items[].amount) (자재 상세 테이블 합계로 자동
 
 ---
 
-## 6. 구현 범위 (Phase)
+## 6. 단계별 구현 계획
+
+> **원칙**: 각 Phase에서 API를 먼저 완성한 후 프론트엔드 개발을 시작한다.
+> API 완료 시점에 프론트엔드 개발자에게 API 명세를 전달한다.
+
+```
+Phase 1: API 완성 → FE 개발 (병행 가능)
+Phase 2: API 완성 → FE 개발 (병행 가능)
+Phase 3: API 완성 → FE 개발 (병행 가능)
+```
+
+---
 
 ### Phase 1 — 기본 CRUD + 비용 산정
 
-- [ ] DB 마이그레이션 (`nonconforming_reports`, `nonconforming_report_items`)
-- [ ] API: Controller, Service, Model, FormRequest
-- [ ] React: 목록 페이지 (필터, 검색, 페이지네이션)
-- [ ] React: 등록/수정 페이지 (5개 섹션)
-- [ ] React: 자재 상세 테이블 (추가/삭제/금액 자동 계산)
-- [ ] React: 비용 요약 (4항목 + 합계)
-- [ ] 첨부파일 업로드 (기존 File 시스템 활용)
+> 목표: 부적합 보고서 등록/조회/수정/삭제 + 자재 내역 + 비용 계산
 
-### Phase 2 — 워크플로우 + 결재
+#### Phase 1-A: API (sam/api)
 
-- [ ] 상태 워크플로우 (RECEIVED → ANALYZING → RESOLVED → CLOSED)
-- [ ] 결재 시스템 연동 (결재상신 → 승인 시 종결)
-- [ ] 상태별 수정 제한 (CLOSED 시 읽기 전용)
+| 순서 | 작업 | 산출물 |
+|------|------|--------|
+| 1 | DB 마이그레이션 | `nonconforming_reports`, `nonconforming_report_items` 테이블 |
+| 2 | Model 생성 | `NonconformingReport`, `NonconformingReportItem` (관계, cast, scope) |
+| 3 | FormRequest 생성 | `StoreNonconformingReportRequest`, `UpdateNonconformingReportRequest` |
+| 4 | Service 생성 | `NonconformingReportService` — CRUD + 채번 + 비용 자동 계산 |
+| 5 | Controller 생성 | `NonconformingReportController` — REST 9개 엔드포인트 |
+| 6 | Route 등록 | `routes/api/v1/material.php` |
+| 7 | 첨부파일 연동 | 기존 `File` polymorphic 연결 |
+| 8 | 채번 로직 | `NC-YYYYMMDD-NNN` (테넌트별, 일자별 리셋) |
 
-### Phase 3 — 통계 + 연동
+**완료 기준**: Postman/Swagger로 전체 CRUD 동작 확인
 
-- [ ] 대시보드 통계 카드 (월별 부적합 건수, 비용 추이)
-- [ ] 수주 연결 강화 (수주 상세에서 부적합 이력 조회)
-- [ ] 엑셀 Export
-- [ ] 인쇄용 보고서 (DomPDF)
+**API 엔드포인트 (Phase 1 범위)**:
+
+| Method | Path | 설명 |
+|--------|------|------|
+| GET | `/api/v1/material/nonconforming-reports` | 목록 (필터/검색/페이지네이션) |
+| GET | `/api/v1/material/nonconforming-reports/{id}` | 단건 (items, files 포함) |
+| POST | `/api/v1/material/nonconforming-reports` | 등록 (items 일괄 저장) |
+| PUT | `/api/v1/material/nonconforming-reports/{id}` | 수정 (items sync) |
+| DELETE | `/api/v1/material/nonconforming-reports/{id}` | 소프트 삭제 |
+| POST | `/api/v1/material/nonconforming-reports/{id}/files` | 첨부파일 업로드 |
+| DELETE | `/api/v1/material/nonconforming-reports/{id}/files/{fileId}` | 첨부파일 삭제 |
+
+#### Phase 1-B: 프론트엔드 (sam/react)
+
+> **선행 조건**: Phase 1-A API 완료 + API 명세 전달
+
+| 순서 | 작업 | 산출물 |
+|------|------|--------|
+| 1 | Server Actions 작성 | `actions.ts` — API 호출 함수 (목록/상세/등록/수정/삭제) |
+| 2 | 목록 페이지 | `NonconformingList.tsx` — 필터, 검색, 페이지네이션, 상태 Badge |
+| 3 | 등록/수정 폼 | `NonconformingForm.tsx` — 5개 FormSection (수주서 구조 준용) |
+| 4 | 자재 상세 테이블 | `NonconformingItemTable.tsx` — 행 추가/삭제, 금액 자동 계산 |
+| 5 | 비용 요약 | `CostSummary.tsx` — 자재/운송/시공/기타/합계, 자재비 자동 산정 |
+| 6 | 상세 뷰 | `NonconformingDetail.tsx` — 읽기 전용 상세 화면 |
+| 7 | 첨부파일 | 기존 파일 업로드 컴포넌트 재사용 |
+| 8 | 라우트 등록 | `page.tsx` + `[id]/page.tsx` (mode=new/edit/view 분기) |
+
+**전달 자료 (API → FE)**:
+- API 엔드포인트 목록 (이 문서 4장)
+- 요청/응답 JSON 예시 (이 문서 4.1, 4.2)
+- 부적합 유형 코드 목록: `material`, `process`, `construction`, `other`
+- 상태 코드 목록: `RECEIVED`, `ANALYZING`, `RESOLVED`, `CLOSED`
+
+---
+
+### Phase 2 — 상태 워크플로우 + 결재
+
+> 목표: 상태 전이 로직 + 결재 시스템 연동 + 수정 제한
+
+#### Phase 2-A: API (sam/api)
+
+| 순서 | 작업 | 산출물 |
+|------|------|--------|
+| 1 | 상태 전이 로직 | Service에 `changeStatus()` — 전이 규칙 검증 포함 |
+| 2 | 상태 변경 API | `PATCH /{id}/status` — body: `{ "status": "ANALYZING" }` |
+| 3 | 통계 API | `GET /stats` — 상태별 건수, 월별 비용 합계 |
+| 4 | 수정 제한 | CLOSED 상태에서 update/delete 요청 시 `403` 반환 |
+| 5 | 결재 연동 | 기존 `approval_requests` 테이블과 연결, 승인 시 자동 CLOSED |
+
+**추가 API 엔드포인트 (Phase 2)**:
+
+| Method | Path | 설명 |
+|--------|------|------|
+| PATCH | `/{id}/status` | 상태 변경 (전이 규칙 검증) |
+| GET | `/stats` | 상태별 통계 |
+
+**상태 전이 검증 규칙**:
+
+```
+RECEIVED → ANALYZING     : 조건 없음
+ANALYZING → RESOLVED     : cause_analysis + corrective_action 필수
+RESOLVED → CLOSED        : 결재 승인 시 자동 (수동 전이 불가)
+```
+
+#### Phase 2-B: 프론트엔드 (sam/react)
+
+> **선행 조건**: Phase 2-A API 완료
+
+| 순서 | 작업 | 산출물 |
+|------|------|--------|
+| 1 | 상태 변경 버튼 | 상세 화면 상단에 상태별 액션 버튼 표시 |
+| 2 | 수정 제한 UI | CLOSED 상태 시 폼 전체 disabled + 수정 버튼 숨김 |
+| 3 | 결재상신 버튼 | RESOLVED 상태에서 "결재상신" 버튼 → 결재 다이얼로그 |
+| 4 | 목록 통계 카드 | 상단에 상태별 건수 카드 (접수/분석중/조치완료/종결) |
+
+**전달 자료 (API → FE)**:
+- 상태 전이 규칙 (이 문서 5.3)
+- 상태별 허용 액션 매핑
+- 결재 API 연동 방식 (기존 결재 시스템 패턴 참고)
+
+---
+
+### Phase 3 — 통계 + 연동 + 출력
+
+> 목표: 대시보드, 수주 연결 강화, 엑셀/PDF 출력
+
+#### Phase 3-A: API (sam/api)
+
+| 순서 | 작업 | 산출물 |
+|------|------|--------|
+| 1 | 대시보드 통계 API | 월별 부적합 건수/비용 추이, 유형별 분포 |
+| 2 | 수주 연동 API | `GET /api/v1/orders/{id}/nonconforming-reports` — 수주별 부적합 이력 |
+| 3 | 엑셀 Export | `GET /{id}/export/excel` — 부적합 보고서 엑셀 다운로드 |
+| 4 | PDF 출력 | `GET /{id}/export/pdf` — 인쇄용 보고서 (DomPDF, Pretendard 폰트) |
+| 5 | 일괄 삭제 | `PATCH /bulk-delete` — 체크박스 선택 일괄 삭제 |
+
+**추가 API 엔드포인트 (Phase 3)**:
+
+| Method | Path | 설명 |
+|--------|------|------|
+| GET | `/dashboard` | 대시보드 통계 (월별 건수/비용, 유형별 분포) |
+| GET | `/{id}/export/excel` | 엑셀 다운로드 |
+| GET | `/{id}/export/pdf` | PDF 다운로드 |
+| PATCH | `/bulk-delete` | 일괄 삭제 |
+
+#### Phase 3-B: 프론트엔드 (sam/react)
+
+> **선행 조건**: Phase 3-A API 완료
+
+| 순서 | 작업 | 산출물 |
+|------|------|--------|
+| 1 | 대시보드 차트 | 월별 부적합 건수/비용 추이 차트, 유형별 도넛 차트 |
+| 2 | 수주 상세 연동 | 수주 상세 화면에 "부적합 이력" 탭 추가 |
+| 3 | 엑셀/PDF 버튼 | 상세 화면 + 목록 화면에 다운로드 버튼 |
+| 4 | 일괄 삭제 | 목록 체크박스 → "선택 삭제" 버튼 |
+
+---
+
+### 전체 일정 요약
+
+```
+Phase 1-A (API)  ■■■■□□□□□□□□  → Phase 1-B (FE)  □□□□■■■■□□□□
+Phase 2-A (API)  □□□□□□■■□□□□  → Phase 2-B (FE)  □□□□□□□□■■□□
+Phase 3-A (API)  □□□□□□□□□■■□  → Phase 3-B (FE)  □□□□□□□□□□■■
+```
+
+> Phase 1-A 완료 후 FE 개발이 시작되면, API 개발자는 Phase 2-A를 병행할 수 있다.
 
 ---