# Partner UI — v1 화면 → v2 API 통합 매핑

> **버전**: v1.0
> **작성일**: 2026-03-22
> **목적**: 기존 partner-ui (Vue 3, mock 데이터) → v2 partner-api 실 연동 가이드
> **서버**: partner-api (port 8081), `/api/partner/` prefix

---

## 1. 인증 체계 변경 사항

### v1 (기존 mock)
```
- Bearer JWT (Access 15min / Refresh 7day)
- localStorage에 token 저장
- ApiResponse<T> = { success, data, pagination }
```

### v2 (실제 서버)
```
- Axim Session Token (HMAC-SHA256, 7일 만료)
- 응답: 직접 객체 반환 (wrapper 없음)
- XPage<T>: { items: T[], page, size, totalCount, totalPage }
- 에러: { code, message, errors? }
```

### 주요 차이점 — 반드시 수정
| 항목 | v1 (mock) | v2 (실제) | 수정 내용 |
|------|-----------|-----------|-----------|
| 응답 래퍼 | `{ success, data }` | 객체 직접 반환 | `api.get()` → `response.data` 직접 사용 |
| 페이지네이션 | `{ pagination: { page, limit, total } }` | `XPage { items, page, size, totalCount, totalPage }` | `items` 필드에서 목록 추출, `totalCount`로 총 건수 |
| 로그인 응답 | `{ accessToken, refreshToken }` | `LoginResponse { requires2fa, accessToken, tempToken, partner }` | 2FA 분기 처리 |
| 토큰 헤더 | `Authorization: Bearer {jwt}` | `Authorization: {axiom-token}` | Bearer prefix 유지 여부 서버 설정 확인 필요 |
| 토큰 갱신 | `POST /auth/refresh` | 서버측 token-expire-days: 7 (자동 연장) | refresh 불필요, 만료 시 재로그인 |
| 날짜 형식 | 미정의 | `yyyy-MM-dd HH:mm:ss` (UTC) | 프론트에서 KST 변환 표시 |

---

## 2. 화면별 API 매핑 (v1 View → v2 Endpoint)

### 2.1 대시보드

| v1 View | v1 Route | v2 API | HTTP | 응답 DTO | 비고 |
|---------|----------|--------|------|----------|------|
| DashboardView.vue | `/dashboard` | `/api/partner/dashboard/summary` | GET | DashboardSummaryResponse | `?includeSubPartners=true` (DISTRIBUTOR) |
| (차트) | `/dashboard` | `/api/partner/dashboard/chart` | GET | List\<DailyChartResponse\> | `?days=7` (기본 7, 최대 30) |

**DashboardSummaryResponse 필드**:
- `todayDepositCount`, `todayDepositAmount`
- `todayWithdrawalCount`, `todayWithdrawalAmount`
- `pendingWithdrawalCount`

### 2.2 입금 관리

| v1 View | v1 Route | v2 API | HTTP | 응답 | 비고 |
|---------|----------|--------|------|------|------|
| DepositListView | `/deposits/list` | `/api/partner/deposits` | GET | XPage\<DepositResponse\> | status, from/to, currencyId, networkId |
| (상세 모달) | — | `/api/partner/deposits/{id}` | GET | DepositResponse | |
| DepositSessionsView | `/deposits/sessions` | `/api/partner/deposit-sessions` | GET | XPage | |
| DepositSessionNewView | `/deposits/sessions/new` | `/api/partner/deposit-sessions` | POST | — | 세션 생성 |
| (세션 상세) | — | `/api/partner/deposit-sessions/{id}` | GET | DepositSessionResponse | |
| PaymentLinksView | `/deposits/payment-links` | `/api/partner/payment-links` | GET | XPage | |
| (결제 링크 생성) | — | `/api/partner/payment-links` | POST | — | ⚠️ P2 스텁 (501 반환) |
| DepositAddressesView | `/deposits/addresses` | `/api/partner/deposit-addresses` | GET | XPage | |
| (주소 상세) | — | `/api/partner/deposit-addresses/{id}` | GET | — | |
| CollectionsView | `/deposits/collections` | `/api/partner/collections` | GET | XPage | |
| (집금 상세) | — | `/api/partner/collections/{id}` | GET | — | |
| AximPaymentsView | `/deposits/axim` | `/api/partner/axim-payments` | GET | XPage | |
| (Axim 요청) | — | `/api/partner/axim-payments/request` | POST | — | ⚠️ P2 스텁 |

### 2.3 출금 관리

| v1 View | v1 Route | v2 API | HTTP | 응답 | 비고 |
|---------|----------|--------|------|------|------|
| WithdrawalListView | `/withdrawals/list` | `/api/partner/withdrawals` | GET | XPage\<WithdrawalResponse\> | |
| (출금 상세) | — | `/api/partner/withdrawals/{id}` | GET | WithdrawalResponse | |
| WithdrawalNewView | `/withdrawals/new` | `/api/partner/withdrawals` | POST | WithdrawalResponse | networkId, currencyId, toAddress, amount |
| (출금 취소) | — | `/api/partner/withdrawals/{id}/cancel` | POST | — | REQUESTED/PENDING_APPROVAL만 |
| WhitelistView | `/withdrawals/whitelist` | `/api/partner/withdrawals/whitelist` | GET | List | |
| (추가) | — | `/api/partner/withdrawals/whitelist` | POST | — | |
| (수정) | — | `/api/partner/withdrawals/whitelist/{id}` | PUT | — | |

### 2.4 잔액/원장

| v1 View | v1 Route | v2 API | HTTP | 응답 | 비고 |
|---------|----------|--------|------|------|------|
| BalancesView | `/balance/overview` | `/api/partner/balances` | GET | List\<BalanceResponse\> | 통화별 잔액 |
| LedgerView | `/balance/ledger` | `/api/partner/ledger` | GET | XPage | from, to, currencyId, type |

### 2.5 정산

| v1 View | v1 Route | v2 API | HTTP | 응답 | 비고 |
|---------|----------|--------|------|------|------|
| FeesView | `/settlement/fees` | `/api/partner/settlement/daily-fees` | GET | XPage\<SettlementDailyFee\> | from, to, currencyId |
| RealizationsView | `/settlement/realizations` | `/api/partner/settlement/realizations` | GET | XPage\<SettlementRealization\> | from, to, currencyId, status |
| BalanceView | `/settlement/balance` | `/api/partner/settlement/balance` | GET | List\<SettlementBalance\> | |
| WithdrawView | `/settlement/withdraw` | `/api/partner/settlement/withdraw` | POST | WithdrawalResponse | networkId, currencyId, toAddress, amount |

### 2.6 가스비

| v1 View | v1 Route | v2 API | HTTP | 응답 | 비고 |
|---------|----------|--------|------|------|------|
| GasCostsView | `/gas/costs` | `/api/partner/gas-costs` | GET | XPage | from, to, networkId |
| GasInvoicesView | `/gas/invoices` | `/api/partner/gas-invoices` | GET | XPage | |
| (인보이스 상세) | — | `/api/partner/gas-invoices/{id}` | GET | — | |

### 2.7 하위 파트너 (DISTRIBUTOR only)

| v1 View | v1 Route | v2 API | HTTP | 응답 | 비고 |
|---------|----------|--------|------|------|------|
| SubPartnersView | `/subpartners/list` | `/api/partner/sub-partners` | GET | XPage | |
| SubPartnerNewView | `/subpartners/new` | `/api/partner/sub-partners` | POST | SubPartnerCreateResponse | |
| (상세) | — | `/api/partner/sub-partners/{id}` | GET | — | |
| (수정) | — | `/api/partner/sub-partners/{id}` | PATCH | — | |
| (거래 현황) | — | `/api/partner/sub-partners/overview` | GET | List\<SubPartnerOverviewResponse\> | |

### 2.8 총판 리포트 (DISTRIBUTOR only)

| v1 View | v1 Route | v2 API | HTTP | 응답 | 비고 |
|---------|----------|--------|------|------|------|
| RevenueView | `/reports/revenue` | `/api/partner/reports/revenue` | GET | RevenueReportResponse | from, to, currencyId |
| CommissionView | `/reports/commission` | `/api/partner/reports/fees` | GET | FeeReportResponse | from, to |
| PerformanceView | `/reports/performance` | `/api/partner/reports/performance` | GET | PerformanceReportResponse | |

### 2.9 연동 설정

| v1 View | v1 Route | v2 API | HTTP | 응답 | 비고 |
|---------|----------|--------|------|------|------|
| ApiKeyView | `/settings/api-key` | `/api/partner/integration/api-key` | GET | ApiKeyResponse | |
| (재발급) | — | `/api/partner/integration/api-key/regenerate` | POST | ApiKeyResponse | |
| WebhookView | `/settings/webhook` | `/api/partner/integration/webhook` | PUT | — | webhookUrl 설정 |
| (테스트) | — | `/api/partner/integration/webhook/test` | POST | — | |
| (로그) | — | `/api/partner/integration/webhook/logs` | GET | XPage | |
| TelegramView | `/settings/telegram` | `/api/partner/integration/telegram` | GET | TelegramConfigResponse | |
| (설정) | — | `/api/partner/integration/telegram` | PUT | — | |
| (테스트) | — | `/api/partner/integration/telegram/test` | POST | — | |
| AximView | `/settings/axim` | `/api/partner/integration/axim` | GET | — | |

### 2.10 내 계정

| v1 View | v1 Route | v2 API | HTTP | 응답 | 비고 |
|---------|----------|--------|------|------|------|
| ProfileView | `/account/profile` | `/api/partner/account/profile` | GET | Partner(부분) | |
| (수정) | — | `/api/partner/account/profile` | PUT | — | |
| PasswordView | `/account/password` | `/api/partner/account/password` | POST | MessageResponse | currentPassword, newPassword |
| TwoFaView | `/account/2fa` | `/api/partner/account/2fa/setup` | GET | TwoFactorSetupResponse | QR코드 + secret |
| (활성화) | — | `/api/partner/account/2fa/enable` | POST | — | otpCode |
| (비활성화) | — | `/api/partner/account/2fa` | DELETE | — | |
| LoginHistoryView | `/account/login-history` | — | — | — | ❌ API 미존재 — 별도 구현 필요 |

---

## 3. Gap 분석

### v1 화면에 있으나 v2 API 없음 (Front 조정 필요)
| v1 View | 문제 | 해결 방안 |
|---------|------|-----------|
| LoginHistoryView | 로그인 이력 API 없음 | 화면 비활성화 또는 partner-api에 API 추가 |

### v2 API에 있으나 v1 화면에 없음 (화면 추가 고려)
| v2 API | 설명 | 우선순위 |
|--------|------|----------|
| `POST /wallets/hot` | HOT 지갑 생성 | LOW (Admin 도메인) |
| `POST /wallets/master` | MASTER 지갑 생성 | LOW (Admin 도메인) |
| `GET /users/{id}/deposits` | 사용자별 입금 조회 | MEDIUM (각 화면에 필터로 통합) |
| `GET /users/{id}/sessions` | 사용자별 세션 조회 | MEDIUM |
| `GET /users/{id}/payment-links` | 사용자별 결제 링크 | MEDIUM |
| `GET /users/{id}/withdrawals` | 사용자별 출금 조회 | MEDIUM |
| `GET /users/{id}/axim-payments` | 사용자별 Axim 조회 | MEDIUM |

### P2 스텁 (서버 미구현 — 501 반환)
| API | 화면 | 대응 |
|-----|------|------|
| `POST /payment-links` | PaymentLinksView | "준비 중" 상태 표시 + 버튼 비활성화 |
| `POST /axim-payments/request` | AximPaymentsView | "준비 중" 상태 표시 + 버튼 비활성화 |

---

## 4. 구현 우선순위 (Phase 별)

### Phase 1 — 핵심 플로우 (1주)
1. **인증 연동** — Login, 2FA, Logout, 토큰 관리
2. **대시보드** — Summary + Chart
3. **입금 내역** — 목록 + 상세 + 페이지네이션
4. **출금 내역** — 목록 + 상세 + 출금 요청
5. **잔액/원장** — 잔액 현황 + 원장 조회

### Phase 2 — 설정/부가 (1주)
6. **연동 설정** — API 키 + Webhook + Telegram
7. **계정** — 프로필 + 비밀번호 + 2FA
8. **입금 세션** — 목록 + 생성
9. **정산** — 일별 수수료 + 실현 + 잔액 + 출금
10. **가스비** — 기록 + 인보이스

### Phase 3 — 총판/고급 (3일)
11. **하위 파트너** — 목록 + 등록 + 상세
12. **총판 리포트** — 매출 + 수수료 + 성과
13. **집금 현황 / 입금 주소**
14. **화이트리스트**
15. **User Context** (partnerUserId 기반 필터)