# Partner UI V2 — 폼/등록/수정 화면 전수조사 결과

> 작성일: 2026-03-24
> 대상: http://localhost:5173/partner/* (V2 파트너 콘솔)

---

## 1. 핵심 문제: "통화 ID / 네트워크 ID" 숫자 직접 입력

**4개 폼에서 동일한 문제 반복 발견:**

| # | 화면 | URL | 문제 필드 |
|---|------|-----|---------|
| 1 | **출금 요청** | `/partner/withdrawals/new` | 통화 ID = `1`, 네트워크 ID = `1` |
| 2 | **입금 세션 생성** | `/partner/deposit-sessions/new` | 통화 ID = `1`, 네트워크 ID = `1` |
| 3 | **쉐어 출금** | `/partner/settlement/withdraw` | 통화 ID = `1`, 네트워크 ID = `1` |
| 4 | **화이트리스트 추가** | `/partner/withdrawals/whitelist` | 네트워크 ID = `1` |

### 현재 동작
```
통화 ID *        네트워크 ID *
[  1  ]          [  1  ]
```
사용자가 내부 DB primary key를 알아야 하는 구조. 사용 불가.

### 수정 방향

**방안: 네트워크 → 통화 2단계 선택 드롭다운**

```
네트워크 *                    통화 *
[ ▾ BSC (BNB Smart Chain) ]  [ ▾ USDT ]
                              [ ▾ USDC ]
```

**구현 방법:**
1. 파트너에게 할당된 네트워크 목록 API 호출 → 네트워크 드롭다운 렌더링
2. 네트워크 선택 시 → 해당 네트워크의 통화 목록 API 호출 → 통화 드롭다운 렌더링
3. 선택된 값에서 내부적으로 `currencyId`, `networkId` 추출하여 API 요청에 사용

**필요 API (이미 partner-api에 존재하는지 확인 필요):**
- `GET /api/partner/networks` → 파트너에게 활성화된 네트워크 목록
- `GET /api/partner/networks/{networkId}/currencies` → 네트워크별 통화 목록

**참고 — 하위 파트너 등록 폼은 올바른 패턴:**
```
파트너 유형 *
[ ▾ 가맹점 ]      ← 드롭다운으로 사용자 친화적
```

---

## 2. 화면별 상세 리뷰

### 2.1 출금 요청 (`/partner/withdrawals/new`)

| 필드 | 현재 | 문제 | 수정안 |
|------|------|------|--------|
| 통화 ID | 숫자 입력 `1` | ❌ 내부 PK | 드롭다운 (네트워크 선택 후 연동) |
| 네트워크 ID | 숫자 입력 `1` | ❌ 내부 PK | 드롭다운 (네트워크명 표시) |
| 수신 주소 | 텍스트 `0x...` | ⚠️ 화이트리스트 선택 옵션 추가 권장 | 화이트리스트 드롭다운 + 직접 입력 토글 |
| 출금 금액 | 숫자 `0` | ✅ OK | — |
| 사용자 ID | 텍스트 (선택) | ✅ OK | — |

### 2.2 입금 세션 생성 (`/partner/deposit-sessions/new`)

| 필드 | 현재 | 문제 | 수정안 |
|------|------|------|--------|
| 통화 ID | 숫자 입력 `1` | ❌ 내부 PK | 드롭다운 |
| 네트워크 ID | 숫자 입력 `1` | ❌ 내부 PK | 드롭다운 |
| 입금 방식 | 드롭다운 `소수점 매칭` | ✅ 좋음 | — |
| 요청 금액 | 숫자 `100` | ✅ OK | — |
| 금액 통화 | 텍스트 `KRW` | ⚠️ 드롭다운 권장 | `KRW` / `USD` / `토큰 기준` 선택 |
| 고객 ID | 텍스트 (선택) | ✅ OK | — |
| 세션 만료 | 드롭다운 `30분` | ✅ 좋음 | — |

### 2.3 화이트리스트 추가 (`/partner/withdrawals/whitelist`)

| 필드 | 현재 | 문제 | 수정안 |
|------|------|------|--------|
| 라벨 | 텍스트 `메인 지갑` | ✅ OK | — |
| 주소 | 텍스트 `0x...` | ✅ OK | — |
| 네트워크 ID | 숫자 입력 `1` | ❌ 내부 PK | 드롭다운 |

### 2.4 쉐어 출금 (`/partner/settlement/withdraw`)

| 필드 | 현재 | 문제 | 수정안 |
|------|------|------|--------|
| 통화 ID | 숫자 입력 `1` | ❌ 내부 PK | 드롭다운 |
| 네트워크 ID | 숫자 입력 `1` | ❌ 내부 PK | 드롭다운 |
| 수신 주소 | 텍스트 (직접 입력) | ⚠️ 화이트리스트 연동 권장 | — |
| 출금 금액 | 숫자 `0` | ✅ OK | — |

### 2.5 하위 파트너 등록 (`/partner/sub-partners/new`) — ✅ 양호

| 필드 | 현재 | 평가 |
|------|------|------|
| 파트너 유형 | 드롭다운 `가맹점` | ✅ 좋음 |
| 파트너명 | 텍스트 | ✅ OK |
| 담당자명/이메일/전화 | 텍스트 | ✅ OK |
| 로그인 이메일 | 텍스트 (기본값) | ✅ OK |
| 비밀번호 | 패스워드 | ✅ OK |
| 입금 수수료율 | 숫자 `0.01` | ✅ OK |

---

## 3. 설정/연동 화면 리뷰

### 3.1 API 키 (`/partner/settings/api`) — ⚠️ 부분 미흡

| 항목 | 현재 | 문제 |
|------|------|------|
| API Key | 마스킹 표시 `pk_8···3e1f` | ✅ OK |
| API Secret | **표시 안 됨** | ⚠️ V1은 Secret 표시 — 복사 기능 필요 |
| Webhook URL | `-` (읽기 전용) | ⚠️ 여기서 수정 불가, Webhook 페이지에서만 가능 |
| 재발급 | "API Key 재발급" 버튼 | ✅ OK |

### 3.2 Webhook (`/partner/settings/webhook`) — ✅ 양호

| 항목 | 현재 | 평가 |
|------|------|------|
| Callback URL | 입력 + 저장 | ✅ V1 대비 통합 (입금/출금 분리 → 단일) |
| 테스트 전송 | 버튼 | ✅ 신규 기능, 좋음 |
| 전달 로그 | 테이블 (일시/이벤트/응답코드/결과) | ✅ V1 콜백 이력 관리 대체 |

### 3.3 Telegram (`/partner/settings/telegram`) — ✅ V1 대비 대폭 개선

| 항목 | 현재 | 평가 |
|------|------|------|
| Bot Token | 입력 (마스킹) | ✅ 좋음 |
| Chat ID | 입력 | ✅ 좋음 |
| 테스트 전송 | 버튼 | ✅ 신규 |
| 이벤트 구독 | 6개 체크박스 | ✅ V1 ON/OFF만 있던 것 대비 대폭 개선 |

### 3.4 Axim Pay (`/partner/settings/axim`) — ❌ 개발자 디버그 뷰

| 항목 | 현재 | 문제 |
|------|------|------|
| 표시 | JSON raw 필드 (id, partnerId, isEnabled, apiKey, createdAt, updatedAt) | ❌ 사용자 친화적이지 않음 |
| 수정 기능 | 없음 | ❌ V1은 Api Key/Secret 입력 + ON/OFF 토글 |

**수정안:** V1처럼 Api Key / Api Secret 입력 폼 + 활성화 ON/OFF 토글 + 저장 버튼

### 3.5 프로필 (`/partner/account/profile`) — ✅ 양호

| 항목 | 현재 | 평가 |
|------|------|------|
| 읽기 전용 | 파트너코드, 유형, 이메일, 상태 | ✅ 깔끔 |
| 편집 가능 | 담당자명, 담당자 이메일, 담당자 전화 | ✅ OK |
| 저장 | 버튼 | ✅ OK |

---

## 4. 리스트 화면 데이터 현황

### 데이터 있는 화면

| 화면 | URL | 상태 |
|------|-----|------|
| **입금 주소** | `/partner/deposit-addresses` | ⚠️ 데이터 있으나 네트워크/통화 컬럼이 모두 `-` 표시 |

### 데이터 없는 화면 (빈 테이블)

| 화면 | URL | 비고 |
|------|-----|------|
| 입금 내역 | `/partner/deposits` | 빈 데이터 |
| 입금 세션 | `/partner/deposit-sessions` | 빈 데이터 |
| 결제 링크 | `/partner/payment-links` | 501 에러 (API 미구현) |
| 집금 현황 | `/partner/collections` | 빈 데이터 |
| 출금 내역 | `/partner/withdrawals` | 빈 데이터 |
| 화이트리스트 | `/partner/withdrawals/whitelist` | 빈 데이터 |
| 잔액 현황 | `/partner/balances` | 빈 데이터 |
| 원장 조회 | `/partner/ledger` | (미확인) |
| 가스비 기록 | `/partner/gas-costs` | 빈 데이터 |
| Axim Pay 결제 | `/partner/axim-payments` | 501 에러 (API 미구현) |
| 매출 리포트 | `/partner/reports/revenue` | 빈 데이터 |

### 빈 화면 (렌더링 안 됨)

| 화면 | URL | 상태 |
|------|-----|------|
| `/partner/whitelist` | 구 URL | 완전 빈 화면 (사이드바 없음) — 라우팅 오류 |
| `/partner/settings/api-keys` | 구 URL | 완전 빈 화면 — 올바른 URL: `/partner/settings/api` |

---

## 5. 입금 주소 특이 사항

`/partner/deposit-addresses` 화면에서:
- 주소 데이터는 표시됨 (TRON: `TZ...`, `TR...` / EVM: `0x...`)
- **네트워크 컬럼 = `-`** (전부)
- **통화 컬럼 = `-`** (전부)
- **활성 = `비활성`** (전부)

**원인 추정:** `wallet_addresses` 테이블에 `network_id`는 있지만, API 응답에서 네트워크명/통화명을 JOIN 하지 않거나, 프론트에서 ID→이름 매핑이 안 되어 있을 수 있음.

---

## 6. 우선순위 정리

### P0 — 즉시 수정 (사용 불가)

| # | 항목 | 영향 범위 |
|---|------|---------|
| 1 | **통화 ID / 네트워크 ID → 드롭다운 전환** | 4개 폼 (출금요청, 입금세션, 쉐어출금, 화이트리스트) |
| 2 | **입금 주소 네트워크/통화 `-` 수정** | 입금 주소 리스트 |

### P1 — 단기 개선

| # | 항목 | 설명 |
|---|------|------|
| 3 | Axim Pay 설정 화면 리디자인 | JSON raw → 입력 폼 + ON/OFF 토글 |
| 4 | 출금 요청의 수신 주소에 화이트리스트 선택 옵션 | 화이트리스트 드롭다운 + 직접 입력 토글 |
| 5 | API 키 화면에 Secret 표시 추가 | V1에서는 표시됨 |
| 6 | 결제 링크 생성 폼 구현 | 현재 501 에러 |
| 7 | Axim Pay 결제 요청 폼 구현 | 현재 501 에러 |

### P2 — 중기 개선

| # | 항목 | 설명 |
|---|------|------|
| 8 | 금액 통화 필드 드롭다운 | 입금 세션 생성의 `KRW` 텍스트 입력 → 선택 |
| 9 | 리스트 화면에 더미/샘플 데이터 | 개발 중 UX 검증용 |

---

## 7. 전체 사이드바 구조 (V2 최신)

```
📊 대시보드
📥 입금 관리
  ├─ 입금 내역
  ├─ 입금 세션        ← 세션 생성 폼 있음 (V1 입금 예약 관리)
  ├─ 결제 링크        ← 501 에러
  ├─ 입금 주소        ← 데이터 있으나 네트워크/통화 `-`
  ├─ 집금 현황
  └─ Axim Pay        ← 501 에러
📤 출금 관리
  ├─ 출금 내역
  ├─ 출금 요청        ← 폼 있음 (ID 직접 입력 문제)
  └─ 화이트리스트     ← 추가 폼 있음 (ID 직접 입력 문제)
💰 잔액/원장
  ├─ 잔액 현황
  └─ 원장 조회
📋 정산
  ├─ 일별 수수료
  ├─ 실현 내역
  ├─ 정산 잔액
  └─ 쉐어 출금        ← 폼 있음 (ID 직접 입력 문제)
⛽ 가스비
  ├─ 가스비 기록
  └─ 인보이스
👥 하위 파트너
  ├─ 파트너 목록
  ├─ 파트너 등록      ← 폼 있음 (✅ 양호)
  └─ 거래 현황
📊 총판 리포트
  ├─ 매출 리포트
  ├─ 수수료 수익
  └─ 성과 비교
⚙️ 연동 설정
  ├─ API 키           ← API Key 표시 + 재발급
  ├─ Webhook          ← ✅ URL 설정 + 테스트 + 로그
  ├─ Telegram         ← ✅ V1 대비 대폭 개선
  └─ Axim Pay         ← ❌ JSON raw 표시
👤 내 계정
  ├─ 프로필           ← ✅ 양호
  ├─ 비밀번호
  ├─ 2FA 설정
  └─ 로그인 이력
```

---

## 8. V1 대비 이전 비교 문서에서 업데이트

이전 비교(PARTNER_UI_V1_V2_COMPARISON.md)에서 **"미구현"으로 표시했던 항목 중 실제 구현되어 있는 것**:

| V1 기능 | 이전 판단 | 실제 상태 |
|---------|---------|---------|
| 입금 예약 관리 | ❌ 미구현 | ✅ **입금 세션** 메뉴로 구현됨 (세션 생성 폼 있음) |
| 결제 링크 관리 | ❌ 미구현 | ⚠️ **결제 링크** 메뉴 존재하나 API 501 |
| 콜백 URL 설정 | ❌ 미구현 | ✅ **Webhook** 설정에서 구현됨 |
| 텔레그램 챗봇 | ❌ 미구현 | ✅ **Telegram** 설정으로 대폭 개선 구현 |
| 액심 결제 내역 | ❌ 미구현 | ⚠️ **Axim Pay** 메뉴 존재하나 API 501 |
| 액심 설정 | ❌ 미구현 | ⚠️ 존재하나 JSON raw 뷰 (리디자인 필요) |
| 사용자 지갑 관리 | ❌ 미구현 | ⚠️ **입금 주소** 메뉴가 유사 역할 (네트워크/통화 표시 안 됨) |

**결론: V2가 이전 세션 때보다 상당히 많이 구현되어 있었으며, 사이드바 구조도 크게 확장됨. 핵심 문제는 "ID 직접 입력" UX 하나로 수렴.**