Files

hskwon 9b665c0d5a docs: 플로우 테스트 파일 이동 및 계획 문서 추가

- api에서 플로우 테스트 JSON 파일들 이동
- 더미 데이터 시딩 계획 추가
- 견적 자동 계산 개발 계획 추가
- 기존 계획 문서 업데이트

2025-12-24 08:54:52 +09:00

39 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)를 자동화 테스트             │
│  - 저장: docs/plans/flow-tests/{feature}-flow.json              │
└─────────────────────────────────────────────────────────────────┘

Flow Test JSON 형식:

{
  "name": "플로우 이름 (50자 이내)",
  "description": "플로우 상세 설명",
  "version": "1.0",
  "config": {
    "baseUrl": "",
    "timeout": 30000,
    "stopOnFailure": true
  },
  "variables": {
    "user_id": "{{$env.FLOW_TESTER_USER_ID}}",
    "user_pwd": "{{$env.FLOW_TESTER_USER_PWD}}"
  },
  "steps": [
    {
      "id": "login",
      "name": "로그인",
      "method": "POST",
      "endpoint": "/api/v1/login",
      "body": {
        "user_id": "{{user_id}}",
        "user_pwd": "{{user_pwd}}"
      },
      "expect": {
        "status": [200],
        "jsonPath": { "$.access_token": "@isString" }
      },
      "extract": { "token": "$.access_token" }
    },
    {
      "id": "step2",
      "name": "다음 단계",
      "method": "GET",
      "endpoint": "/api/v1/path",
      "headers": {
        "Authorization": "Bearer {{login.token}}"
      },
      "expect": {
        "status": [200],
        "jsonPath": { "$.success": true }
      }
    }
  ]
}

🔴 Flow Test JSON 작성 규칙 (필수 준수)

#	규칙	설명
1	config.baseUrl	빈 문자열 `""` 로 설정 (서버에서 .env 기본값 사용)
2	config.apiKey	❌ JSON에 포함하지 않음 (서버에서 자동 주입)
3	variables	`{{$env.XXX}}` 형식으로 환경변수 참조
4	steps[].body	`{{변수명}}` 형식으로 variables 값 참조
5	headers.Authorization	`Bearer {{login.token}}` 형식으로 추출한 토큰 사용
6	extract	다음 스텝에서 `{{stepId.변수명}}`으로 참조됨
7	endpoint	`/api/v1`을 포함한 전체 경로 필수
8	flows 배열	❌ 사용 금지 - 최상위에 바로 `steps` 배열 사용
9	dependsOn	❌ 사용 금지 - steps 순서대로 실행됨

변수 참조 규칙

┌─────────────────────────────────────────────────────────────────────────┐
│  ✅ 올바른 참조                                                          │
├─────────────────────────────────────────────────────────────────────────┤
│  variables 참조:  "user_id": "{{user_id}}"                              │
│  환경변수 참조:   "user_id": "{{$env.FLOW_TESTER_USER_ID}}"             │
│  추출값 참조:     "Authorization": "Bearer {{login.token}}"             │
│  동적 값:         "email": "test_{{$timestamp}}@example.com"            │
├─────────────────────────────────────────────────────────────────────────┤
│  ❌ 잘못된 참조                                                          │
├─────────────────────────────────────────────────────────────────────────┤
│  ❌ "user_id": "{{variables.user_id}}"  (variables. 접두사 사용 금지)    │
│  ❌ "Authorization": "Bearer {{login.accessToken}}"  (추출 키 불일치)    │
└─────────────────────────────────────────────────────────────────────────┘

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 작성
├── docs/plans/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 저장 위치:

docs/plans/flow-tests/
├── user-invitation-flow.json        ✅ 완료 (6 steps)
├── notification-settings-flow.json  ✅ 완료 (10 steps)
├── account-management-flow.json     ✅ 완료 (6 steps)
├── sales-statement-flow.json        ✅ 완료 (9 steps)
├── bad-debt-flow.json               ✅ 완료 (11 steps)
├── popup-flow.json                  ✅ 완료 (9 steps)
├── subscription-flow.json           ✅ 완료 (13 steps)
├── payment-flow.json                ✅ 완료 (12 steps)
└── company-request-flow.json        ✅ 완료 (9 steps)

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 사용자 초대

상태: ✅ 완료
분석 결과:

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 구조:

{
  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):

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):

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 확장

8.1 구독관리

상태: ✅ 완료 (API 이미 완전 구현됨)
분석 결과:

React 분석 (SubscriptionManagement):

// types.ts
interface SubscriptionInfo {
  lastPaymentDate: string;
  nextPaymentDate: string;
  subscriptionAmount: number;
  plan: 'free' | 'basic' | 'premium' | 'enterprise';
  userCount: number;
  userLimit: number | null;  // null = 무제한
  storageUsed: number;       // TB 단위
  storageLimit: number;
  apiCallsUsed: number;
  apiCallsLimit: number;
}

handleExportData(): 자료 내보내기 - TODO
handleCancelService(): 서비스 해지 - TODO

API 분석 (완전 구현됨):

엔드포인트	설명	기능
`GET /v1/subscriptions/current`	현재 활성 구독	구독 정보 조회
`GET /v1/subscriptions/usage`	사용량 조회	사용자/저장공간/API 호출 통계
`POST /v1/subscriptions/export`	내보내기 요청	자료 내보내기 생성
`GET /v1/subscriptions/export/{id}`	내보내기 상태	진행 상태 확인
`POST /v1/subscriptions/{id}/cancel`	구독 취소	해지 처리 (reason 옵션)
`POST /v1/subscriptions/{id}/suspend`	일시정지	구독 일시정지
`POST /v1/subscriptions/{id}/resume`	재개	구독 재개

필드 매핑:

React	API
`lastPaymentDate`	`last_payment_at`
`nextPaymentDate`	`next_payment_at`
`subscriptionAmount`	`amount`
`userCount`	`user_count`
`userLimit`	`user_limit`
`storageUsed`	`storage_used`
`storageLimit`	`storage_limit`
`apiCallsUsed`	`api_calls_used`
`apiCallsLimit`	`api_calls_limit`

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

8.2 결제내역

상태: ✅ 완료 (API 이미 완전 구현됨)
분석 결과:

React 분석 (PaymentHistoryManagement):

// types.ts
interface PaymentHistory {
  id: string;
  paymentDate: string;
  subscriptionName: string;
  paymentMethod: string;
  subscriptionPeriod: { start: string; end: string; };
  amount: number;
  canViewInvoice: boolean;
  createdAt: string;
  updatedAt: string;
}

Mock 데이터 사용 (generateMockData())
handleViewInvoice(): 거래명세서 조회 - MES 연동 예정

API 분석 (완전 구현됨):

엔드포인트	설명	기능
`GET /v1/payments`	결제 목록	페이지네이션 지원
`GET /v1/payments/summary`	요약 통계	결제 금액 합계 등
`GET /v1/payments/{id}`	결제 상세	상세 정보 조회
`GET /v1/payments/{id}/statement`	명세서	거래명세서 조회
`POST /v1/payments/{id}/complete`	완료 처리	결제 완료 처리
`POST /v1/payments/{id}/cancel`	취소	결제 취소
`POST /v1/payments/{id}/refund`	환불	환불 처리

필드 매핑:

React	API
`id`	`id`
`paymentDate`	`paid_at`
`subscriptionName`	`subscription_name`
`paymentMethod`	`payment_method`
`subscriptionPeriod.start`	`period_start`
`subscriptionPeriod.end`	`period_end`
`canViewInvoice`	`can_view_statement`

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

8.3 회사 추가

상태: ✅ 완료 (API 이미 완전 구현됨)
분석 결과:

React 분석 (CompanyInfoManagement/AddCompanyDialog.tsx):

// 입력: 사업자등록번호 10자리
// 처리 프로세스:
// 1. 사업자등록번호 조회 (바로빌 API 연동 TODO)
// 2. 휴폐업 상태 확인
// 3. 기존 등록 여부 확인
// 4. 신청 알림 발송

API 분석 (완전 구현됨):

엔드포인트	설명	기능
`POST /v1/companies/check`	사업자번호 검증	유효성/중복 검사
`POST /v1/companies/request`	회사 추가 신청	신청 등록
`GET /v1/companies/my-requests`	내 신청 목록	사용자 신청 이력
`GET /v1/companies/requests`	신청 목록 (관리자)	관리자용 전체 목록
`GET /v1/companies/requests/{id}`	신청 상세	상세 정보
`POST /v1/companies/requests/{id}/approve`	승인	관리자 승인
`POST /v1/companies/requests/{id}/reject`	반려	관리자 반려 (reason 옵션)

React 연동 방식:

// 1단계: 사업자등록번호 검증
const checkResult = await api.post('/v1/companies/check', {
  business_number: '1234567890'
});

// 2단계: 회사 추가 신청
if (checkResult.valid) {
  await api.post('/v1/companies/request', {
    business_number: '1234567890',
    // 추가 정보...
  });
}

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

5. 컨펌 대기 목록

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

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

6. 변경 이력

날짜	페이지	변경 내용	파일	승인
2025-12-22	8.3	회사 가입 신청 Flow Test 작성 (9 steps)	`company-request-flow.json`	✅
2025-12-22	8.2	결제 관리 Flow Test 작성 (12 steps)	`payment-flow.json`	✅
2025-12-22	8.1	구독 관리 Flow Test 작성 (13 steps)	`subscription-flow.json`	✅
2025-12-22	6.2	팝업 관리 Flow Test 작성 (9 steps)	`popup-flow.json`	✅
2025-12-22	6.1	부실채권 관리 Flow Test 작성 (11 steps)	`bad-debt-flow.json`	✅
2025-12-22	5.4	매출 명세서 Flow Test 작성 (9 steps)	`sales-statement-flow.json`	✅
2025-12-22	5.3	계정 관리 Flow Test 작성 (6 steps)	`account-management-flow.json`	✅
2025-12-22	5.2	알림 설정 Flow Test 작성 (10 steps)	`notification-settings-flow.json`	✅
2025-12-22	-	Flow Test JSON 작성 규칙 정리 (9개 필수 규칙 + 변수 참조 규칙)	문서	✅
2025-12-22	-	endpoint 정책 추가 (/api/v1 전체 경로 필수)	문서 + user-invitation-flow.json	✅
2025-12-22	-	Flow Test 파일 통합 (docs/plans/flow-tests/로 이동)	9개 파일 이동	✅
2025-12-22	5.1-1	사용자 초대 Flow Test 작성 (14 flows, P1~P3)	`user-invitation-flow.json`	✅
2025-12-22	8.1	구독관리 API 분석 - 완전 구현됨, 필드명 매핑 필요	-	✅
2025-12-22	8.2	결제내역 API 분석 - 완전 구현됨, 필드명 매핑 필요	-	✅
2025-12-22	8.3	회사 추가 API 분석 - 완전 구현됨, React 연동만 필요	-	✅
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
개발 공통 정책: ../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 파일: docs/plans/flow-tests/*.json

39 KiB Raw Blame History Unescape Escape

React-API 연동 테스트 계획

1. 개요

1.1 배경

1.2 기준 원칙

1.3 변경 승인 정책

1.4 준수 규칙

1.5 Flow Test 병행

🔴 Flow Test JSON 작성 규칙 (필수 준수)

변수 참조 규칙

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 초대 목록

5.2 알림 설정

5.3-1 회원 탈퇴

5.3-2 사용 중지

5.4-1 거래명세서

4.2 Phase 6: 핵심 신규

6.1 악성채권 추심관리

6.2 팝업관리

4.3 Phase 7: 게시판 연동

4.4 Phase 8: SaaS 확장

8.1 구독관리

8.2 결제내역

8.3 회사 추가

5. 컨펌 대기 목록

6. 변경 이력

7. 참고 문서

39 KiB

Raw Blame History