sam-docs/plans/react-api-integration-plan.md

# 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`