docs: Phase 6.1 악성채권 체크리스트 완료 상태 반영

- erp-api-development-plan-d1.0-changes.md: 악성채권 추심관리 구현 완료 체크 - quotation/PROGRESS.md: 견적 프로젝트 진행상황 업데이트 - phase-4-integration/README.md: API 통합 문서 수정 - react-api-integration-plan.md: React API 통합 계획 추가
2025-12-22 15:53:31 +09:00
parent 2055524e19
commit 80bff661fc
4 changed files with 508 additions and 76 deletions
--- a/plans/erp-api-development-plan-d1.0-changes.md
+++ b/plans/erp-api-development-plan-d1.0-changes.md
@@ -171,64 +171,48 @@

 > 신규 테이블 + API 전체 신규 구현

-### 6.1 악성채권 추심관리 🆕
+### 6.1 악성채권 추심관리 ✅
 > 슬라이드: 10-13 | 경로: 회계관리 > 악성채권 추심관리
+> **완료일: 2025-12-19** (commit: c0af888)

- [ ] **테이블 생성** (3개)
-  - [ ] `bad_debts` 마이그레이션
-    ```sql
-    -- bad_debts (악성채권)
-    id, tenant_id, client_id, debt_amount, status,
-    overdue_days, assigned_user_id, occurred_at, closed_at,
-    is_active, options(json),
-    created_by, updated_by, deleted_by,
-    created_at, updated_at, deleted_at
-    ```
-  - [ ] `bad_debt_documents` 마이그레이션
-    ```sql
-    -- bad_debt_documents (필요 서류)
-    id, bad_debt_id, document_type, file_id,
-    created_at
-    ```
-  - [ ] `bad_debt_memos` 마이그레이션
-    ```sql
-    -- bad_debt_memos (메모)
-    id, bad_debt_id, content, created_by, created_at
-    ```
-  - [ ] 마이그레이션 실행 및 검증
+- [x] **테이블 생성** (3개)
+  - [x] `bad_debts` 마이그레이션 (2025_12_19_160001)
+  - [x] `bad_debt_documents` 마이그레이션 (2025_12_19_160002)
+  - [x] `bad_debt_memos` 마이그레이션 (2025_12_19_160003)
+  - [x] 마이그레이션 실행 및 검증

- [ ] **모델 생성** (3개)
-  - [ ] `BadDebt` 모델 (BelongsToTenant, SoftDeletes)
-    - 상태 상수: COLLECTING, LEGAL_ACTION, RECOVERED, BAD_DEBT
-    - 관계: client, assignedUser, documents, memos
-  - [ ] `BadDebtDocument` 모델
+- [x] **모델 생성** (3개)
+  - [x] `BadDebt` 모델 (BelongsToTenant, SoftDeletes)
+    - 상태 상수: collecting, legal_action, recovered, bad_debt
+    - 관계: client, assignedUser, creator, documents, memos
+  - [x] `BadDebtDocument` 모델
    - 문서 유형: business_license, tax_invoice, additional
-  - [ ] `BadDebtMemo` 모델
+  - [x] `BadDebtMemo` 모델

- [ ] **서비스 구현**
-  - [ ] `BadDebtService` 생성
-  - [ ] 악성채권 등록/수정/삭제 로직
-  - [ ] 상태 전이 로직 (추심중→법적조치→회수완료/대손처리)
-  - [ ] 요약 통계 (총 채권, 상태별 금액)
-  - [ ] 서류 첨부/삭제 로직
-  - [ ] 메모 추가/삭제 로직
+- [x] **서비스 구현**
+  - [x] `BadDebtService` 생성 (307줄)
+  - [x] 악성채권 등록/수정/삭제 로직
+  - [x] 상태 전이 로직 (추심중→법적조치→회수완료/대손처리)
+  - [x] 요약 통계 (총 채권, 상태별 금액)
+  - [x] 서류 첨부/삭제 로직
+  - [x] 메모 추가/삭제 로직

- [ ] **API 엔드포인트** (11개)
-  - [ ] `GET /v1/bad-debts` - 악성채권 목록
-  - [ ] `POST /v1/bad-debts` - 악성채권 등록
-  - [ ] `GET /v1/bad-debts/summary` - 상단 요약 (총 채권, 상태별 금액)
-  - [ ] `GET /v1/bad-debts/{id}` - 악성채권 상세
-  - [ ] `PUT /v1/bad-debts/{id}` - 악성채권 수정
-  - [ ] `DELETE /v1/bad-debts/{id}` - 악성채권 삭제
-  - [ ] `PATCH /v1/bad-debts/{id}/toggle` - 설정 ON/OFF
-  - [ ] `POST /v1/bad-debts/{id}/documents` - 서류 첨부
-  - [ ] `DELETE /v1/bad-debts/{id}/documents/{docId}` - 서류 삭제
-  - [ ] `POST /v1/bad-debts/{id}/memos` - 메모 추가
-  - [ ] `DELETE /v1/bad-debts/{id}/memos/{memoId}` - 메모 삭제
+- [x] **API 엔드포인트** (11개)
+  - [x] `GET /v1/bad-debts` - 악성채권 목록
+  - [x] `POST /v1/bad-debts` - 악성채권 등록
+  - [x] `GET /v1/bad-debts/summary` - 상단 요약 (총 채권, 상태별 금액)
+  - [x] `GET /v1/bad-debts/{id}` - 악성채권 상세
+  - [x] `PUT /v1/bad-debts/{id}` - 악성채권 수정
+  - [x] `DELETE /v1/bad-debts/{id}` - 악성채권 삭제
+  - [x] `PATCH /v1/bad-debts/{id}/toggle` - 설정 ON/OFF
+  - [x] `POST /v1/bad-debts/{id}/documents` - 서류 첨부
+  - [x] `DELETE /v1/bad-debts/{id}/documents/{docId}` - 서류 삭제
+  - [x] `POST /v1/bad-debts/{id}/memos` - 메모 추가
+  - [x] `DELETE /v1/bad-debts/{id}/memos/{memoId}` - 메모 삭제

- [ ] **Swagger 문서**
-  - [ ] `BadDebtApi.php` 작성
-  - [ ] 스키마 정의 (BadDebt, BadDebtDocument, BadDebtMemo, Summary)
+- [x] **Swagger 문서**
+  - [x] `BadDebtApi.php` 작성 (433줄)
+  - [x] 스키마 정의 (BadDebt, BadDebtDocument, BadDebtMemo, Summary)

 - [ ] **테스트**
  - [ ] Feature 테스트 작성
--- a/plans/react-api-integration-plan.md
+++ b/plans/react-api-integration-plan.md
@@ -0,0 +1,427 @@
+# React-API 연동 테스트 계획
+
+> **작성일**: 2025-12-22
+> **목적**: React(dev.sam.kr) 프론트엔드와 API 연동 테스트 및 스펙 동기화
+> **기준 문서**: `erp-api-development-plan-d1.0-changes.md`
+> **상태**: 🔄 진행중
+
+---
+
+## 1. 개요
+
+### 1.1 배경
+- React와 API가 동일한 기획서(SAM_ERP_Storyboard_D1.0)로 각각 개발됨
+- 기획서에 API 명세가 없어 React는 목업 데이터로, API는 자체 설계로 구현
+- 두 시스템 간 request/response 스펙 동기화 필요
+
+### 1.2 기준 원칙
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  🎯 React를 기준으로 API를 맞춤                                   │
+├─────────────────────────────────────────────────────────────────┤
+│  - React에서 호출하는 API 경로/파라미터 분석                       │
+│  - API의 request/response를 React 요구사항에 맞게 수정            │
+│  - API 내부 로직 변경이 필요한 경우 → 사용자 컨펌 필수              │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 1.3 변경 승인 정책
+
+| 변경 유형 | 예시 | 승인 |
+|----------|------|------|
+| ✅ **즉시 가능** | Response 필드 추가, Query 파라미터 추가, 필드명 변경 | 불필요 |
+| ⚠️ **컨펌 필요** | Service 로직 변경, DB 쿼리 변경, 새 엔드포인트 추가 | **필수** |
+| 🔴 **금지** | 테이블 구조 변경, 기존 API 삭제 | 별도 협의 |
+
+### 1.4 준수 규칙
+- `docs/guides/PROJECT_DEVELOPMENT_POLICY.md` - 개발 공통 정책
+- `docs/guides/common-workflow-framework.md` - 작업 프레임워크
+
+### 1.5 Flow Test 병행
+
+연동 테스트와 함께 **API Flow Test**를 병행합니다.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  🧪 Flow Tester 병행 테스트                                       │
+├─────────────────────────────────────────────────────────────────┤
+│  - 도구: https://mng.sam.kr/dev-tools/flow-tester               │
+│  - 목적: 각 기능의 모든 경우의 수(TC)를 자동화 테스트             │
+│  - 저장: api/docs/flow-tests/{feature}-flow.json                │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Flow Test JSON 형식:**
+```json
+{
+  "name": "기능명 플로우 테스트",
+  "description": "테스트 설명",
+  "version": "1.0",
+  "config": {
+    "baseUrl": "https://api.sam.kr/api/v1",
+    "apiKey": "{{$env.FLOW_TESTER_API_KEY}}",
+    "timeout": 30000,
+    "stopOnFailure": true
+  },
+  "variables": {
+    "user_id": "{{$env.FLOW_TESTER_USER_ID}}",
+    "user_pwd": "{{$env.FLOW_TESTER_USER_PWD}}"
+  },
+  "steps": [
+    {
+      "id": "step_id",
+      "name": "단계명",
+      "method": "GET|POST|PUT|PATCH|DELETE",
+      "endpoint": "/endpoint",
+      "headers": { "Authorization": "Bearer {{login.token}}" },
+      "body": { },
+      "expect": {
+        "status": [200],
+        "jsonPath": { "$.success": true }
+      },
+      "extract": { "key": "$.data.value" }
+    }
+  ]
+}
+```
+
+---
+
+## 2. 대상 페이지 목록
+
+### 2.1 Phase 5: 기본 확장
+
+| # | React URL (예상) | 기능 | 관련 API | 연동 | Flow Test |
+|---|-----------------|------|----------|:----:|:---------:|
+| 5.1-1 | `/hr/employees/invite` | 사용자 초대 | `POST /v1/users/invite` | ⏳ | ⏳ |
+| 5.1-2 | `/hr/employees/invitations` | 초대 목록 | `GET /v1/users/invitations` | ⏳ | ⏳ |
+| 5.2-1 | `/settings/notifications` | 알림 설정 | `GET /v1/settings/notifications` | ⏳ | ⏳ |
+| 5.2-2 | `/settings/notifications` | 알림 설정 수정 | `PUT /v1/settings/notifications` | ⏳ | ⏳ |
+| 5.3-1 | `/account` | 회원 탈퇴 | `POST /v1/account/withdraw` | ⏳ | ⏳ |
+| 5.3-2 | `/account` | 사용 중지 | `POST /v1/account/suspend` | ⏳ | ⏳ |
+| 5.4-1 | `/accounting/sales/{id}` | 거래명세서 | `GET /v1/sales/{id}/statement` | ⏳ | ⏳ |
+
+**Phase 5 Flow Test 파일:**
+- `user-invitation-flow.json` - 사용자 초대 전체 플로우
+- `notification-settings-flow.json` - 알림 설정 플로우
+- `account-management-flow.json` - 계정관리 (탈퇴/중지) 플로우
+- `sales-statement-flow.json` - 거래명세서 플로우
+
+### 2.2 Phase 6: 핵심 신규 ✅
+
+| # | React URL (예상) | 기능 | 관련 API | 연동 | Flow Test |
+|---|-----------------|------|----------|:----:|:---------:|
+| 6.1-1 | `/accounting/bad-debts` | 악성채권 목록 | `GET /v1/bad-debts` | ⏳ | ⏳ |
+| 6.1-2 | `/accounting/bad-debts` | 악성채권 요약 | `GET /v1/bad-debts/summary` | ⏳ | ⏳ |
+| 6.1-3 | `/accounting/bad-debts/{id}` | 악성채권 상세 | `GET /v1/bad-debts/{id}` | ⏳ | ⏳ |
+| 6.1-4 | `/accounting/bad-debts/new` | 악성채권 등록 | `POST /v1/bad-debts` | ⏳ | ⏳ |
+| 6.2-1 | `/settings/popups` | 팝업 목록 | `GET /v1/popups` | ⏳ | ⏳ |
+| 6.2-2 | `/settings/popups` | 활성 팝업 | `GET /v1/popups/active` | ⏳ | ⏳ |
+| 6.2-3 | `/settings/popups/{id}` | 팝업 상세 | `GET /v1/popups/{id}` | ⏳ | ⏳ |
+
+**Phase 6 Flow Test 파일:**
+- `bad-debt-flow.json` - 악성채권 추심관리 CRUD 플로우
+- `popup-flow.json` - 팝업관리 CRUD 플로우
+
+### 2.3 Phase 7: 게시판 연동 ✅
+
+| # | React URL (예상) | 기능 | 관련 API | 연동 | Flow Test |
+|---|-----------------|------|----------|:----:|:---------:|
+| 7.1-1 | `/settings/boards` | 게시판 관리 목록 | `GET /v1/boards` | ⏳ | ⏳ |
+| 7.1-2 | `/settings/boards/{id}` | 게시판 상세 | `GET /v1/boards/{id}` | ⏳ | ⏳ |
+| 7.2-1 | `/boards` | 게시판 목록 (탭) | `GET /v1/boards` | ⏳ | ⏳ |
+| 7.2-2 | `/boards/{code}` | 게시글 목록 | `GET /v1/boards/{code}/posts` | ⏳ | ⏳ |
+| 7.2-3 | `/boards/{code}/{id}` | 게시글 상세 | `GET /v1/boards/{code}/posts/{id}` | ⏳ | ⏳ |
+| 7.2-4 | `/boards/my` | 나의 게시글 | `GET /v1/posts/my` | ⏳ | ⏳ |
+| 7.2-5 | `/boards/{code}/{id}` | 댓글 목록 | `GET /v1/boards/{code}/posts/{id}/comments` | ⏳ | ⏳ |
+
+**Phase 7 Flow Test 파일:**
+- `board-management-flow.json` - 게시판 관리 CRUD 플로우
+- `post-crud-flow.json` - 게시글 CRUD + 댓글 플로우
+
+### 2.4 Phase 8: SaaS 확장
+
+| # | React URL (예상) | 기능 | 관련 API | 연동 | Flow Test |
+|---|-----------------|------|----------|:----:|:---------:|
+| 8.1-1 | `/subscription` | 현재 구독 정보 | `GET /v1/subscriptions/current` | ⏳ | ⏳ |
+| 8.1-2 | `/subscription` | 사용량 조회 | `GET /v1/subscriptions/usage` | ⏳ | ⏳ |
+| 8.1-3 | `/subscription/export` | 자료 내보내기 | `POST /v1/subscriptions/export` | ⏳ | ⏳ |
+| 8.1-4 | `/subscription` | 서비스 해지 | `POST /v1/subscriptions/{id}/cancel` | ⏳ | ⏳ |
+| 8.2-1 | `/payments` | 결제 내역 | `GET /v1/payments` | ⏳ | ⏳ |
+| 8.2-2 | `/payments/{id}` | 결제 상세 | `GET /v1/payments/{id}` | ⏳ | ⏳ |
+| 8.2-3 | `/payments/{id}/statement` | 거래명세서 | `GET /v1/payments/{id}/statement` | ⏳ | ⏳ |
+| 8.3-1 | `/companies/add` | 회사 추가 | `POST /v1/companies/request` | ⏳ | ⏳ |
+
+**Phase 8 Flow Test 파일:**
+- `subscription-flow.json` - 구독관리 플로우
+- `payment-flow.json` - 결제내역 플로우
+- `company-request-flow.json` - 회사 추가 신청 플로우
+
+---
+
+## 3. 연동 테스트 절차
+
+### 3.1 단일 페이지 테스트 절차
+
+```
+Step 1: React 페이지 분석
+├── dev.sam.kr에서 해당 페이지 접속
+├── 개발자 도구 > Network 탭 열기
+├── 페이지 동작 수행 (조회, 등록, 수정 등)
+└── API 호출 패턴 기록
+    ├── URL 경로
+    ├── HTTP Method
+    ├── Request Headers
+    ├── Request Body/Query
+    └── Expected Response
+
+Step 2: API 현재 상태 확인
+├── Swagger UI 접속 (sam.kr/api-docs)
+├── 해당 엔드포인트 확인
+└── 현재 request/response 스펙 확인
+
+Step 3: 차이점 분석
+├── URL 경로 차이
+├── Request 파라미터 차이
+├── Response 필드 차이
+└── 인증 방식 차이
+
+Step 4: 수정 사항 정리
+├── ✅ 즉시 가능 → 바로 수정
+└── ⚠️ 컨펌 필요 → 문서에 기록 후 승인 요청
+
+Step 5: Flow Test 작성
+├── 해당 기능의 모든 TC(Test Case) 도출
+├── Flow Test JSON 작성
+├── api/docs/flow-tests/{feature}-flow.json 저장
+└── https://mng.sam.kr/dev-tools/flow-tester 에서 실행
+```
+
+### 3.2 Flow Test 작성 가이드
+
+#### 🔴 핵심 원칙: 화면의 모든 분기 상황을 Flow로 작성
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  ❌ 간소화된 단일 플로우 금지 (대표 케이스 1개만 테스트하면 안됨)            │
+│  ✅ 화면에서 발생 가능한 모든 상황/분기를 개별 플로우로 작성                 │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+#### Flow로 잡아야 하는 모든 분기 상황
+
+| 분류 | 분기 유형 | 예시 |
+|------|----------|------|
+| **입력 분기** | Select Box | 카테고리, 상태, 유형 선택 |
+| | Radio Button | 결제방식(카드/계좌/현금), 성별 |
+| | Checkbox | 약관동의, 옵션 선택, 다중 선택 |
+| | Toggle/Switch | 활성화/비활성화, 공개/비공개 |
+| **조건부 UI** | 조건부 필드 표시 | 유형 A 선택 시 추가 필드 노출 |
+| | 조건부 버튼 활성화 | 필수값 입력 시 버튼 활성화 |
+| | 조건부 섹션 표시 | 특정 조건에서만 탭/섹션 노출 |
+| **데이터 상태** | 데이터 유무 | 빈 목록 vs 데이터 있음 |
+| | 데이터 상태값 | 대기/승인/반려/완료 각각 |
+| | 페이징 상태 | 첫 페이지/중간/마지막 |
+| **사용자 상태** | 권한별 | 관리자/일반사용자/게스트 |
+| | 로그인 상태 | 로그인/비로그인 |
+| | 역할별 | 작성자/승인자/조회자 |
+| **액션 분기** | 버튼별 액션 | 저장/임시저장/취소/삭제 |
+| | 모달/다이얼로그 | 확인/취소 선택 |
+| | 네비게이션 | 이전/다음/목록으로 |
+
+#### 조합 계산 공식
+
+```
+총 Flow 수 = (분기1 옵션수) × (분기2 옵션수) × ... × (분기N 옵션수)
+```
+
+**예시 - 등록 화면 분석:**
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  화면: 악성채권 등록                                                      │
+├─────────────────────────────────────────────────────────────────────────┤
+│  [입력 분기]                                                              │
+│  - 채권유형 Select: 매출채권, 대여금, 선급금 → 3개                         │
+│  - 추심상태 Select: 추심중, 법적대응, 포기 → 3개                           │
+│  - 담당자지정 Radio: 자동배정, 직접지정 → 2개                              │
+│  - 알림설정 Checkbox: 이메일, SMS, 푸시 → 2³ = 8개 조합                   │
+│                                                                         │
+│  [조건부 UI]                                                              │
+│  - 담당자지정=직접지정 시: 담당자 Select 노출 (5명) → 5개 추가             │
+│                                                                         │
+│  [액션 분기]                                                              │
+│  - 저장 버튼: 정상저장                                                    │
+│  - 임시저장 버튼: 임시저장                                                 │
+├─────────────────────────────────────────────────────────────────────────┤
+│  기본 Flow: 3 × 3 × 8 = 72개                                             │
+│  조건부 Flow: 직접지정 시 × 5 = 36개 추가                                  │
+│  액션별: × 2 (저장/임시저장)                                               │
+│                                                                         │
+│  ⚠️ 전체 Flow 수 = (72 + 36) × 2 = 216개                                 │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+**예시 - 목록 화면 분석:**
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  화면: 게시글 목록                                                        │
+├─────────────────────────────────────────────────────────────────────────┤
+│  [필터 분기]                                                              │
+│  - 게시판 탭: 공지, 자유, 질문 → 3개                                       │
+│  - 정렬 Select: 최신순, 조회순, 댓글순 → 3개                               │
+│  - 기간 필터: 전체, 1주, 1개월, 3개월 → 4개                               │
+│                                                                         │
+│  [데이터 상태]                                                            │
+│  - 검색결과: 있음, 없음 → 2개                                             │
+│  - 페이징: 첫페이지, 중간, 마지막 → 3개                                    │
+│                                                                         │
+│  [사용자 상태]                                                            │
+│  - 권한: 관리자(수정/삭제 가능), 일반(조회만) → 2개                         │
+├─────────────────────────────────────────────────────────────────────────┤
+│  필터 조합: 3 × 3 × 4 = 36개                                              │
+│  데이터 상태: × 2 × 3 = × 6                                               │
+│  권한별: × 2                                                              │
+│                                                                         │
+│  ⚠️ 전체 Flow 수 = 36 × 6 × 2 = 432개                                    │
+│  (실제로는 의미있는 조합만 선별하여 테스트)                                  │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+#### 실용적 접근: 분기 우선순위
+
+모든 조합이 수백 개가 되면, 우선순위를 정해 단계적으로 테스트:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  🔴 P1 (필수): 비즈니스 핵심 분기                                          │
+│     - 주요 유형/상태 조합                                                  │
+│     - 결제/금액 관련 분기                                                  │
+│     - 권한별 접근 차이                                                     │
+├─────────────────────────────────────────────────────────────────────────┤
+│  🟡 P2 (중요): UI 조건부 분기                                              │
+│     - 조건부 필드 표시/숨김                                                │
+│     - 버튼 활성화/비활성화                                                 │
+│     - 데이터 상태별 표시                                                   │
+├─────────────────────────────────────────────────────────────────────────┤
+│  🟢 P3 (권장): 부가 분기                                                   │
+│     - 정렬/필터 조합                                                       │
+│     - 페이징 상태                                                          │
+│     - 알림 설정 조합                                                       │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+#### Flow 작성 체크리스트
+
+화면 분석 시 반드시 확인:
+```
+□ 입력 분기: Select, Radio, Checkbox, Toggle 개수와 옵션
+□ 조건부 UI: 특정 선택 시 나타나는/사라지는 필드
+□ 데이터 상태: 빈 상태, 로딩, 에러, 정상 데이터
+□ 사용자 상태: 권한별, 역할별 차이
+□ 액션 분기: 각 버튼별 동작
+□ 총 분기 조합 수 계산
+□ 우선순위 분류 (P1/P2/P3)
+□ P1 분기 전체 Flow 작성
+```
+
+**Flow Test 저장 위치:**
+```
+api/docs/flow-tests/
+├── user-invitation-flow.json
+├── notification-settings-flow.json
+├── bad-debt-flow.json
+├── popup-flow.json
+├── board-management-flow.json
+├── post-crud-flow.json
+├── subscription-flow.json
+├── payment-flow.json
+└── company-request-flow.json
+```
+
+### 3.3 분석 템플릿
+
+```markdown
+### [페이지 ID] 페이지명
+
+**React 분석 결과:**
+- URL: `GET /api/xxx`
+- Request: `{ param1, param2 }`
+- Response: `{ field1, field2 }`
+
+**API 현재 상태:**
+- URL: `GET /v1/xxx`
+- Request: `{ paramA, paramB }`
+- Response: `{ fieldA, fieldB }`
+
+**차이점:**
+| 항목 | React | API | 조치 |
+|------|-------|-----|------|
+| URL | /api/xxx | /v1/xxx | 수정 필요 |
+| Response.field1 | 있음 | 없음 | 추가 필요 |
+
+**수정 사항:**
+- [ ] ✅ Response에 field1 추가
+- [ ] ⚠️ Service 로직 변경 필요 (컨펌 요청)
+```
+
+---
+
+## 4. 페이지별 연동 상세
+
+> 각 페이지 테스트 후 이 섹션에 상세 내용 추가
+
+### 4.1 Phase 5: 기본 확장
+
+#### 5.1-1 사용자 초대
+- **상태**: ⏳ 대기
+- **분석 결과**: (테스트 후 작성)
+
+#### 5.1-2 초대 목록
+- **상태**: ⏳ 대기
+- **분석 결과**: (테스트 후 작성)
+
+<!-- 이하 페이지별 상세 추가 -->
+
+### 4.2 Phase 6: 핵심 신규
+
+(테스트 후 작성)
+
+### 4.3 Phase 7: 게시판 연동
+
+(테스트 후 작성)
+
+### 4.4 Phase 8: SaaS 확장
+
+(테스트 후 작성)
+
+---
+
+## 5. 컨펌 대기 목록
+
+> API 내부 로직 변경이 필요한 항목 (승인 필요)
+
+| # | 페이지 | 변경 내용 | 영향 범위 | 상태 |
+|---|--------|----------|----------|------|
+| - | - | - | - | - |
+
+---
+
+## 6. 변경 이력
+
+| 날짜 | 페이지 | 변경 내용 | 파일 | 승인 |
+|------|--------|----------|------|------|
+| 2025-12-22 | 3.2 | 화면 전체 분기 상황 Flow 작성 규칙으로 확장 | - | - |
+| 2025-12-22 | - | Flow Test 병행 절차 추가 | - | - |
+| 2025-12-22 | - | 문서 초안 작성 | - | - |
+
+---
+
+## 7. 참고 문서
+
+- **기준 개발 계획**: [`erp-api-development-plan-d1.0-changes.md`](./erp-api-development-plan-d1.0-changes.md)
+- **개발 공통 정책**: [`../guides/PROJECT_DEVELOPMENT_POLICY.md`](../guides/PROJECT_DEVELOPMENT_POLICY.md)
+- **작업 프레임워크**: [`../guides/common-workflow-framework.md`](../guides/common-workflow-framework.md)
+- **API Swagger UI**: http://sam.kr/api-docs/index.html
+- **React 개발 서버**: http://dev.sam.kr
+- **Flow Tester**: https://mng.sam.kr/dev-tools/flow-tester
+- **Flow Test 예제**: `api/claudedocs/flow-tester-*.json`
--- a/projects/api-integration/phase-4-integration/README.md
+++ b/projects/api-integration/phase-4-integration/README.md
@@ -22,10 +22,10 @@ React 화면과 API 실제 연동 및 오류 해결
 ### API 검증 방법
 ```bash
 # 방법 1: Swagger UI
-http://api.sam.kr/api-docs/index.html
+https://api.sam.kr/api-docs/index.html

 # 방법 2: curl 직접 호출
-curl -X GET "http://api.sam.kr/api/v1/clients" \
+curl -X GET "https://api.sam.kr/api/v1/clients" \
  -H "X-API-KEY: {api_key}" \
  -H "Authorization: Bearer {token}"

--- a/projects/quotation/PROGRESS.md
+++ b/projects/quotation/PROGRESS.md
@@ -2,7 +2,7 @@

 > **마스터 플랜:** [MASTER_PLAN.md](./MASTER_PLAN.md)
 > **공통 정책:** [PROJECT_DEVELOPMENT_POLICY.md](../../guides/PROJECT_DEVELOPMENT_POLICY.md)
-> **최종 업데이트:** 2025-12-19 (Phase 4 prices 연동)
+> **최종 업데이트:** 2025-12-19 (Phase 4 DB 기반 재작성 완료)

 ---

@@ -13,15 +13,15 @@
 | Phase 1: 5130 분석 | ✅ 완료 | 100% | 2025-12-19 | 2025-12-19 |
 | Phase 2: mng 분석 | ✅ 완료 | 100% | 2025-12-19 | 2025-12-19 |
 | Phase 3: 구현 | ✅ 완료 | 100% | 2025-12-19 | 2025-12-19 |
-| Phase 4: API 개발 | 🔄 진행 | 30% | 2025-12-19 | - |
+| Phase 4: API 개발 | 🔄 진행 | 60% | 2025-12-19 | - |

 ---

 ## 🔄 현재 작업

 **현재 Phase:** Phase 4 진행 중
-**완료된 작업:** api 프로젝트 prices 테이블 연동
-**다음 작업:** 견적 API 테스트 및 Swagger 문서화
+**완료된 작업:** mng 패턴 적용 - DB 기반 견적 산출 서비스 재작성
+**다음 작업:** 견적 API 통합 테스트 및 Swagger 문서화

 ---

@@ -146,6 +146,9 @@ php artisan db:seed --class=QuoteFormulaSeeder
 - [x] api 프로젝트 prices 테이블 연동
 - [x] Price 모델에 getCurrentPrice(), getSalesPriceByItemCode() 추가
 - [x] QuoteCalculationService prices 조회로 변경
+- [x] mng 패턴 적용 - Quote 수식 모델 생성
+- [x] FormulaEvaluatorService DB 기반 확장
+- [x] QuoteCalculationService DB 기반 재작성
 - [ ] 견적 API 통합 테스트
 - [ ] Swagger 문서화
 - [ ] React 연동 스펙
@@ -157,7 +160,7 @@ php artisan db:seed --class=QuoteFormulaSeeder

 ### 완료된 작업 (2025-12-19)

-#### api 프로젝트 prices 테이블 연동
+#### 1. api 프로젝트 prices 테이블 연동

 **수정된 파일:**
 - `api/app/Models/Products/Price.php`
@@ -165,27 +168,42 @@ php artisan db:seed --class=QuoteFormulaSeeder
  - getCurrentPrice(): 현재 유효 단가 조회
  - getSalesPriceByItemCode(): 품목 코드로 단가 조회

- `api/app/Services/Quote/QuoteCalculationService.php`
-  - setTenantId(): 테넌트 ID 설정
-  - getUnitPrice(): 단가 조회 헬퍼 (fallback 지원)
-  - 모든 하드코딩 단가 → Price 모델 조회로 변경
-
-**연동된 품목 코드:**
-| 품목 코드 | 설명 | 기존 fallback |
-|----------|------|--------------|
-| SCR-FABRIC-001 | 스크린 원단 | 25,000 |
-| SCR-CASE-001 | 알루미늄 케이스 | 85,000 |
-| SCR-BRACKET-001 | 설치 브라켓 | 15,000 |
-| SCR-MOTOR-50W~300W | 모터 용량별 | 120,000~280,000 |
-| LAB-INSTALL-001 | 설치 인건비 | 50,000 |
-| STL-PLATE-SS304/SS316/GALVANIZED | 철판 재질별 | 3,000~6,500 |
-| STL-WELD-001 | 용접 | 15,000 |
-| STL-FINISH-HAIRLINE/MIRROR/MATTE | 표면처리 | 5,000~15,000 |
-| STL-PROCESS-001 | 가공비 | 50,000 |
-
 **Git 커밋:**
 - `4d3085e` feat: 견적 산출 서비스 prices 테이블 연동

+#### 2. mng 패턴 적용 - DB 기반 견적 산출 재작성
+
+**추가된 파일:**
+- `api/app/Models/Quote/QuoteFormula.php` - 수식 정의 모델
+- `api/app/Models/Quote/QuoteFormulaCategory.php` - 카테고리 모델
+- `api/app/Models/Quote/QuoteFormulaItem.php` - 품목 출력 모델
+- `api/app/Models/Quote/QuoteFormulaRange.php` - 범위별 값 모델
+- `api/app/Models/Quote/QuoteFormulaMapping.php` - 매핑 값 모델
+
+**수정된 파일:**
+- `api/app/Models/Products/Price.php`
+  - items 테이블 연동 (products/materials 대체)
+  - ITEM_TYPE 상수 업데이트 (FG/PT/RM/SM/CS)
+
+- `api/app/Services/Quote/FormulaEvaluatorService.php`
+  - executeAll(): 카테고리별 수식 실행 (mng 패턴)
+  - evaluateRangeFormula(): QuoteFormula 기반 범위 평가
+  - evaluateMappingFormula(): QuoteFormula 기반 매핑 평가
+  - getItemPrice(): prices 테이블 연동
+
+- `api/app/Services/Quote/QuoteCalculationService.php`
+  - 하드코딩된 품목 코드/로직 제거
+  - quote_formulas 테이블 기반 동적 계산
+  - getFormulasByCategory(): DB에서 수식 조회
+  - getInputSchema(): DB 기반 입력 스키마 생성
+
+**핵심 변경:**
+- 기존: 하드코딩된 품목 코드 (SCR-FABRIC-001 등)
+- 변경: quote_formula_items 테이블에서 동적 조회
+
+**Git 커밋:**
+- `0d49e4c` refactor: 견적 산출 서비스 DB 기반으로 재작성
+
 ---

 ## 🏷️ Git 태그
@@ -204,6 +222,9 @@ php artisan db:seed --class=QuoteFormulaSeeder
 | 2025-12-19 | 신규 테이블 정책 | options JSON 적용 | Hybrid EAV 전략 |
 | 2025-12-19 | 견적 유형 | 스크린/슬랫 2가지 | 5130 기존 구조 유지 |
 | 2025-12-19 | 체크박스 옵션 | JSON으로 통합 저장 | 확장성 고려 |
+| 2025-12-19 | 품목 테이블 | items 테이블 사용 | products/materials 통합 완료 |
+| 2025-12-19 | 견적 산출 방식 | mng 패턴 (DB 기반) | 하드코딩 제거, 동적 수식 관리 |
+| 2025-12-19 | tenant_id 없을 때 | 예외 발생 (fallback 금지) | 데이터 무결성 보장 |

 ---