# 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 사용자 초대
- **상태**: ✅ 완료
- **분석 결과**:

**React 분석 (UserInviteDialog.tsx):**
- Request: `{ email, role, message }` (role: 'admin' | 'manager' | 'user' 문자열)

**API 분석 (POST /v1/users/invite):**
- 기존: `{ email, role_id, message, expires_days }` (role_id: integer FK)

**차이점 및 조치:**
| 항목 | React | API | 조치 |
|------|-------|-----|------|
| role | `role` (문자열) | `role_id` (integer) | ✅ API에서 role 문자열도 지원하도록 수정 |

**수정된 파일:**
- `app/Http/Requests/UserInvitation/InviteUserRequest.php` - role 필드 추가
- `app/Services/UserInvitationService.php` - role → role_id 변환 로직 추가
- `app/Swagger/v1/UserInvitationApi.php` - Swagger 문서 업데이트

#### 5.1-2 초대 목록
- **상태**: ⏭️ 스킵
- **분석 결과**: React에 초대 목록 페이지 미구현 (API는 준비됨: `GET /v1/users/invitations`)

#### 5.2 알림 설정
- **상태**: ✅ 완료
- **분석 결과**:

**React 분석 (SettingsNotificationsPage.tsx):**
- 그룹 기반 계층 구조 사용
- Request/Response 구조:
```typescript
{
  notice: { enabled: boolean, notice: { enabled, email }, event: { enabled, email } },
  schedule: { enabled: boolean, vatReport: { enabled, email }, ... },
  vendor: { enabled: boolean, newVendor: { enabled, email }, ... },
  attendance: { enabled: boolean, annualLeave: { enabled, email }, ... },
  order: { enabled: boolean, salesOrder: { enabled, email }, ... },
  approval: { enabled: boolean, approvalRequest: { enabled, email }, ... },
  production: { enabled: boolean, safetyStock: { enabled, email }, ... }
}
```

**API 분석 (기존):**
- 플랫 구조: 각 알림 타입별 개별 설정 (push_enabled, email_enabled, sms_enabled 등)

**차이점 및 조치:**
| 항목 | React | API | 조치 |
|------|-------|-----|------|
| 구조 | 그룹 기반 계층 | 플랫 | ✅ API에서 React 구조 직접 지원 |
| 엔드포인트 | `/settings/notifications` | `/users/me/notification-settings` | ✅ 새 엔드포인트 추가 |

**구현 방식:**
- API가 React 구조를 직접 반환 (변환 로직 불필요)
- 그룹 정의를 DB로 관리 (테넌트별 커스터마이징 가능)

**신규 생성 파일:**
- `database/migrations/2025_12_22_171959_create_notification_setting_groups_tables.php`
- `app/Models/NotificationSettingGroup.php`
- `app/Models/NotificationSettingGroupItem.php`
- `app/Models/NotificationSettingGroupState.php`
- `app/Http/Requests/NotificationSetting/UpdateGroupedSettingRequest.php`

**수정된 파일:**
- `app/Services/NotificationSettingService.php` - getGroupedSettings(), updateGroupedSettings() 추가
- `app/Http/Controllers/Api/V1/NotificationSettingController.php` - indexGrouped(), updateGrouped() 추가
- `routes/api.php` - 새 라우트 추가
- `app/Swagger/v1/NotificationSettingApi.php` - 스키마 및 엔드포인트 문서 추가

**새 API 엔드포인트:**
- `GET /api/v1/settings/notifications` - 그룹 기반 알림 설정 조회
- `PUT /api/v1/settings/notifications` - 그룹 기반 알림 설정 수정

#### 5.3-1 회원 탈퇴
- **상태**: ✅ 완료 (API 수정 불필요)
- **분석 결과**:

**React 분석 (AccountInfoManagement/index.tsx):**
- `handleConfirmWithdraw()`: 확인 다이얼로그 후 로그아웃 처리
- 조건: `canWithdraw = !accountInfo.isTenantMaster` (테넌트 마스터가 아닌 경우만)
- 현재 API 연동: `// TODO: 탈퇴 API 연동`

**API 분석 (POST /v1/account/withdraw):**
- Request: `{ password(필수), reason?, detail? }`
- Response: `{ withdrawn_at }`
- 로직: 비밀번호 확인 → 모든 테넌트 연결 해제 → 탈퇴 사유 저장 → 사용자 soft delete → 토큰 삭제

**차이점 및 조치:**
| 항목 | React | API | 조치 |
|------|-------|-----|------|
| 비밀번호 확인 | UI 없음 | `password` 필수 | ⚠️ React에서 비밀번호 입력 UI 추가 필요 |
| 탈퇴 사유 | UI 없음 | `reason`, `detail` 옵션 | React에서 선택적 추가 가능 |

**결정**: API 유지 (보안상 권장) - React 담당자에게 비밀번호 입력 UI 추가 요청

#### 5.3-2 사용 중지
- **상태**: ✅ 완료 (호환됨)
- **분석 결과**:

**React 분석:**
- `handleConfirmSuspend()`: 확인 다이얼로그 후 처리
- 조건: `canSuspend = accountInfo.isTenantMaster` (테넌트 마스터인 경우만)
- 현재 API 연동: `// TODO: 사용중지 API 연동`

**API 분석 (POST /v1/account/suspend):**
- Request: 없음 (현재 로그인된 사용자/테넌트 기준)
- Response: `{ suspended, new_default_tenant_id }`
- 로직: 현재 테넌트에서 비활성화 → 다른 활성 테넌트가 있으면 기본 테넌트 변경

**차이점 및 조치:** 없음 - API 호환됨 ✅

#### 5.4-1 거래명세서
- **상태**: ✅ 완료 (API 이미 구현됨)
- **분석 결과**:

**React 분석 (SalesManagement/SalesDetail.tsx):**
- `거래명세서 조회` 버튼: `// TODO: 거래명세서 조회 기능 연결` (line 527)
- `거래명세서 발행하기` 버튼: Mock 이메일 발송 (`handleSendTransactionStatement`)

**API 분석 (이미 완전히 구현됨):**
| 엔드포인트 | 설명 | Response |
|-----------|------|----------|
| `GET /v1/sales/{id}/statement` | 조회 | `{ statement_number, issued_at, sale, seller, buyer, items, summary }` |
| `POST /v1/sales/{id}/statement/issue` | 발행 | `{ statement_number, issued_at }` |
| `POST /v1/sales/{id}/statement/send` | 발송 | `{ sent_to, sent_at, statement_number }` |

**차이점 및 조치:** API 수정 불필요 - React에서 API 연동만 하면 됨 ✅

<!-- 이하 페이지별 상세 추가 -->

### 4.2 Phase 6: 핵심 신규

#### 6.1 악성채권 추심관리
- **상태**: ✅ 완료 (API 이미 완전 구현됨)
- **분석 결과**:

**React 분석 (BadDebtCollection/types.ts):**
```typescript
interface BadDebtRecord {
  vendorId, vendorName, businessNumber, // 거래처 정보
  debtAmount, status, overdueDays,      // 악성채권 정보
  files: AttachedFile[],                // 첨부 파일
  memos: BadDebtMemo[]                  // 메모
}
```

**API 분석 (완전 구현됨):**
| 엔드포인트 | 설명 | Response |
|-----------|------|----------|
| `GET /v1/bad-debts` | 목록 | 페이지네이션 + client 관계 |
| `GET /v1/bad-debts/summary` | 요약 | 상태별 금액 합계 |
| `GET /v1/bad-debts/{id}` | 상세 | client, documents, memos 관계 포함 |
| `POST /v1/bad-debts` | 등록 | `{ client_id, debt_amount, status, ... }` |
| `PUT /v1/bad-debts/{id}` | 수정 | 부분 업데이트 지원 |
| `DELETE /v1/bad-debts/{id}` | 삭제 | Soft Delete |
| `PATCH /v1/bad-debts/{id}/toggle` | 토글 | is_active 토글 |
| `POST /v1/bad-debts/{id}/documents` | 서류 첨부 | document_type, file_id |
| `POST /v1/bad-debts/{id}/memos` | 메모 추가 | content |

**차이점 및 조치:** API 수정 불필요 - React에서 연동만 필요 ✅

#### 6.2 팝업관리
- **상태**: ✅ 완료 (API 이미 완전 구현됨)
- **분석 결과**:

**React 분석 (PopupManagement/types.ts):**
```typescript
interface Popup {
  target: 'all' | 'department',
  targetName, title, content, status,
  startDate, endDate, author
}
```

**API 분석 (완전 구현됨):**
| 엔드포인트 | 설명 | Response |
|-----------|------|----------|
| `GET /v1/popups` | 목록 (관리자용) | 페이지네이션 + creator, department 관계 |
| `GET /v1/popups/active` | 활성 팝업 (사용자용) | 현재 활성화된 팝업만 |
| `GET /v1/popups/{id}` | 상세 | creator, department 관계 포함 |
| `POST /v1/popups` | 등록 | `{ target_type, target_id, title, content, status, started_at, ended_at }` |
| `PUT /v1/popups/{id}` | 수정 | 부분 업데이트 지원 |
| `DELETE /v1/popups/{id}` | 삭제 | Soft Delete |

**필드 매핑:**
| React | API |
|-------|-----|
| `target` | `target_type` |
| `targetDepartmentId` | `target_id` |
| `startDate` | `started_at` |
| `endDate` | `ended_at` |

**차이점 및 조치:** API 수정 불필요 - React에서 필드명 매핑하여 연동 ✅

### 4.3 Phase 7: 게시판 연동

(테스트 후 작성)

### 4.4 Phase 8: SaaS 확장

(테스트 후 작성)

---

## 5. 컨펌 대기 목록

> API 내부 로직 변경이 필요한 항목 (승인 필요)

| # | 페이지 | 변경 내용 | 영향 범위 | 상태 |
|---|--------|----------|----------|------|
| - | - | - | - | - |

---

## 6. 변경 이력

| 날짜 | 페이지 | 변경 내용 | 파일 | 승인 |
|------|--------|----------|------|------|
| 2025-12-22 | 6.1 | 악성채권 API 분석 - 완전 구현됨, React 연동만 필요 | - | ✅ |
| 2025-12-22 | 6.2 | 팝업관리 API 분석 - 완전 구현됨, 필드명 매핑 필요 | - | ✅ |
| 2025-12-22 | 5.3-1 | 회원 탈퇴 API 분석 - API 유지, React에서 비밀번호 UI 추가 필요 | - | ✅ |
| 2025-12-22 | 5.3-2 | 사용 중지 API 분석 - 호환됨, 수정 불필요 | - | ✅ |
| 2025-12-22 | 5.4-1 | 거래명세서 API 분석 - 이미 완전 구현됨, React 연동만 필요 | - | ✅ |
| 2025-12-22 | 5.2 | 알림 설정 API - React 호환 그룹 구조 구현 | 마이그레이션, 모델, 서비스, 컨트롤러, Swagger | ✅ |
| 2025-12-22 | 5.1-1 | 사용자 초대 API - role 문자열 지원 추가 | Request, Service, Swagger | ✅ |
| 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`