Files

hskwon 80bff661fc 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

21 KiB

Raw Blame History

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 형식:

{
  "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 분석 템플릿

### [페이지 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
개발 공통 정책: ../guides/PROJECT_DEVELOPMENT_POLICY.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

21 KiB Raw Blame History Unescape Escape

React-API 연동 테스트 계획

1. 개요

1.1 배경

1.2 기준 원칙

1.3 변경 승인 정책

1.4 준수 규칙

1.5 Flow Test 병행

2. 대상 페이지 목록

2.1 Phase 5: 기본 확장

2.2 Phase 6: 핵심 신규 ✅

2.3 Phase 7: 게시판 연동 ✅

2.4 Phase 8: SaaS 확장

3. 연동 테스트 절차

3.1 단일 페이지 테스트 절차

3.2 Flow Test 작성 가이드

🔴 핵심 원칙: 화면의 모든 분기 상황을 Flow로 작성

Flow로 잡아야 하는 모든 분기 상황

조합 계산 공식

실용적 접근: 분기 우선순위

Flow 작성 체크리스트

3.3 분석 템플릿

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. 컨펌 대기 목록

6. 변경 이력

7. 참고 문서

21 KiB

Raw Blame History