From 32e761773dc7930c1bae71b77c9faaec8a346fb9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Thu, 19 Mar 2026 08:29:51 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[material]=20=EB=B6=80=EC=A0=81?= =?UTF-8?q?=ED=95=A9=EA=B4=80=EB=A6=AC=20=EA=B8=B0=ED=9A=8D=EC=84=9C=20API?= =?UTF-8?q?/FE=20=EB=B6=84=EB=A6=AC=20=EB=8B=A8=EA=B3=84=EB=B3=84=20?= =?UTF-8?q?=EA=B3=84=ED=9A=8D=20=EC=9E=AC=EA=B5=AC=EC=84=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Phase별 API 선행 → FE 후행 구조로 분리 - 각 Phase마다 API 산출물, FE 전달자료 명시 - API 엔드포인트를 Phase별로 분류 - 병행 개발 일정 다이어그램 추가 --- .../nonconforming-management-plan.md | 169 ++++++++++++++++-- 1 file changed, 152 insertions(+), 17 deletions(-) diff --git a/dev/dev_plans/nonconforming-management-plan.md b/dev/dev_plans/nonconforming-management-plan.md index 7a58ab3..948376b 100644 --- a/dev/dev_plans/nonconforming-management-plan.md +++ b/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를 병행할 수 있다. ---