# Admin 파트너 상세 화면 — 재설계 기능 정의서

> **작성일**: 2026-04-05
> **대상**: admin-api + Admin Console 프론트엔드
> **화면 ID**: SCR-2200 (파트너 상세보기)

## 현재 문제점

1. **수수료 관리 부재**: 4개 수수료 필드(parentFeeRate, minFeeRate, maxFeeCap, depositFeeRate)가 UI에 노출/수정 불가
2. **기본정보 탭 과부하**: 연락처, 로그인, 기타 정보가 섹션 구분 없이 나열
3. **하위 파트너 탭 미구현**: DISTRIBUTOR인 경우 하위 파트너 목록 표시 필요
4. **수정 기능 미흡**: 이름/이메일 외 수정 가능한 필드가 누락

## 탭 구성 (7개)

```
[기본정보] [수수료] [지갑] [체인/통화] [출금정책] [하위파트너*] [활동로그]
                                          (* DISTRIBUTOR만)
```

---

## TAB 1: 기본정보

### 1-1. 기본 정보 섹션

| 필드 | 표시명 | 수정 | 비고 |
|------|--------|------|------|
| partnerCode | 파트너 코드 | ✕ | 읽기 전용 |
| name | 파트너명 | ✅ | 인라인 편집 |
| partnerType | 유형 | ✕ | DISTRIBUTOR / MERCHANT 뱃지 |
| status | 상태 | ✅ | 상태변경 버튼 (별도 동작) |
| parentPartnerName | 상위 파트너 | ✕ | 클릭 시 상위 상세로 이동 |
| createdAt | 등록일 | ✕ | |
| updatedAt | 수정일 | ✕ | |

**상태변경 버튼**: 현재 상태에 따라 가능한 전이만 표시
- PENDING → [활성화]
- ACTIVE → [정지] [해지]
- SUSPENDED → [활성화] [해지]
- TERMINATED → 변경 불가 (전체 화면 비활성화)

정지/해지 시 사유 입력 모달.

**API**: `PATCH /api/admin/partners/{id}/status`

### 1-2. 계정 정보 섹션

| 필드 | 표시명 | 수정 | 비고 |
|------|--------|------|------|
| loginEmail | 로그인 이메일 | ✅ | 중복 검사 서버 처리 |
| twoFactorEnabled | 2FA | ✕ | ON/OFF 뱃지 + [초기화] 버튼 |
| lastLoginAt | 마지막 로그인 | ✕ | |
| lastLoginIp | 마지막 로그인 IP | ✕ | |

**2FA 초기화**: `POST /api/admin/partners/{id}/2fa/reset` — 확인 모달 필요

### 1-3. 연동 정보 섹션

| 필드 | 표시명 | 수정 | 비고 |
|------|--------|------|------|
| apiKey | API Key | ✕ | 마스킹 표시 + [재발급] 버튼 |
| webhookUrl | Webhook URL | ✅ | |
| timezone | 타임존 | ✅ | 드롭다운 |
| locale | 언어 | ✅ | ko / en 드롭다운 |

**API Key 재발급**: `POST /api/admin/partners/{id}/api-key/regenerate`
- 확인 모달 + 결과를 1회만 표시하는 시크릿 모달

**기본정보 저장 API**: `PUT /api/admin/partners/{id}`
```json
{
  "name": "파트너명",
  "webhookUrl": "https://...",
  "timezone": "Asia/Seoul",
  "locale": "ko"
}
```

---

## TAB 2: 수수료 (신규)

### 2-1. 수수료 구조 표시

| 필드 | 표시명 | 수정 | 설명 |
|------|--------|------|------|
| parentFeeRate | 상위 수수료율 | ✅ | 상위 파트너에게 지급하는 수수료 (%) |
| minFeeRate | 최소 수수료율 | ✕ | 누적 최소 (자동 계산 = 부모 minFeeRate + parentFeeRate) |
| maxFeeCap | 최대 수수료 상한 | ✅ | 하위 파트너에게 설정 가능한 최대 수수료 (%) |
| depositFeeRate | 실제 수수료율 | ✅ | 입금 시 적용되는 수수료 (MERCHANT만) |

### 2-2. 수수료 시각화

```
┌─────────────────────────────────────────────┐
│ 수수료 구조                          [수정]  │
│                                              │
│  상위 수수료율 (parentFeeRate)    0.00 %     │
│  최소 수수료율 (minFeeRate)       0.00 %  ← 자동 계산, 수정 불가  │
│  최대 상한 (maxFeeCap)            5.00 %     │
│  ─────────────────────────────────           │
│  실제 수수료율 (depositFeeRate)   0.30 %  ← MERCHANT만 표시      │
│                                              │
│  ┌──────────────────────────────┐            │
│  │ 0%  ▎■■■ 0.3%        5% ▎   │ ← 시각적 범위 바  │
│  │     min              max     │            │
│  └──────────────────────────────┘            │
│                                              │
│  ⓘ 하위 파트너는 0.00% ~ 5.00% 범위에서     │
│    수수료를 설정할 수 있습니다.               │
└─────────────────────────────────────────────┘
```

### 2-3. 수정 규칙

- **parentFeeRate 변경**: 하위 파트너의 minFeeRate에 연쇄 영향 → 확인 모달로 경고
- **maxFeeCap 변경**: 상위의 maxFeeCap 이하만 허용. 하위 중 이미 초과하는 파트너 있으면 경고
- **depositFeeRate 변경**: minFeeRate ≤ 값 ≤ maxFeeCap 범위 검증
- **minFeeRate**: 자동 계산 → 수정 불가 (읽기 전용)
- **DISTRIBUTOR**: depositFeeRate 필드 숨김 (직접 거래 안 함)

**API**: `PUT /api/admin/partners/{id}/fees`
```json
{
  "parentFeeRate": 0.15,
  "maxFeeCap": 5.0,
  "depositFeeRate": 0.3
}
```

---

## TAB 3: 지갑

현재 구현과 동일. 네트워크별 MASTER/HOT 지갑 표시.

**API**: `GET /api/admin/partners/{id}/wallets`

추가: 이전 세션에서 구현한 **ledgerBalance** (출금 가능 잔액) 표시.

---

## TAB 4: 체인/통화 설정

현재 구현과 동일. 네트워크 × 통화 매트릭스 그리드.

**조회**: `GET /api/admin/partners/{id}/chain-configs`
**수정**: `PUT /api/admin/partners/{id}/chain-configs`

---

## TAB 5: 출금정책

### 5-1. 출금 정책 설정

| 필드 | 표시명 | 수정 | 비고 |
|------|--------|------|------|
| autoApproveThreshold | 자동 승인 한도 | ✅ | USD 기준, 초과 시 수동 승인 |
| dailyLimit | 일일 출금 한도 | ✅ | USD 기준 |
| singleLimit | 건당 출금 한도 | ✅ | USD 기준 |
| addressWhitelistEnabled | 화이트리스트 사용 | ✅ | 토글 |

**API**: `PUT /api/admin/partners/{id}/withdrawal-policy`

### 5-2. 출금 주소 화이트리스트

화이트리스트 활성화 시 표시. 테이블로 관리.

| 컬럼 | 설명 |
|------|------|
| 네트워크 | BSC / TRON / POLYGON |
| 주소 | 출금 허용 주소 |
| 라벨 | 별칭 |
| 등록일 | |
| 삭제 | [삭제] 버튼 |

**조회**: `GET /api/admin/partners/{id}/whitelist`
**추가**: `POST /api/admin/partners/{id}/whitelist`
**삭제**: `DELETE /api/admin/partners/{id}/whitelist/{wid}`

---

## TAB 6: 하위 파트너 (DISTRIBUTOR만)

MERCHANT인 경우 이 탭 자체를 숨김.

### 6-1. 하위 파트너 목록

| 컬럼 | 설명 |
|------|------|
| 파트너 코드 | 클릭 시 해당 파트너 상세로 이동 |
| 파트너명 | |
| 유형 | DISTRIBUTOR / MERCHANT |
| 상태 | 뱃지 |
| 수수료율 | depositFeeRate |
| 등록일 | |

페이지네이션 적용.

**API**: `GET /api/admin/partners/{id}/children`

---

## TAB 7: 활동 로그

기존과 동일. audit_logs에서 targetType=PARTNER, targetId={id} 필터.

---

## 상단 액션 버튼

```
[파트너 상세보기]                    [상태변경 ▾] [수정] [더보기 ▾]
                                                        ├ API Key 재발급
                                                        ├ 2FA 초기화
                                                        ├ 비밀번호 초기화
                                                        └ 파트너 삭제
```

- **상태변경**: 드롭다운으로 가능한 상태만 표시
- **수정**: 현재 활성 탭의 편집 모드 진입
- **더보기**: 위험 작업 모음

---

## API 매핑 요약

| 기능 | HTTP | 엔드포인트 | 백엔드 상태 |
|------|------|-----------|------------|
| 상세 조회 | GET | /api/admin/partners/{id} | ✅ 구현됨 |
| 기본정보 수정 | PUT | /api/admin/partners/{id} | ✅ 구현됨 |
| 상태 변경 | PATCH | /api/admin/partners/{id}/status | ✅ 구현됨 |
| 수수료 수정 | PUT | /api/admin/partners/{id}/fees | ✅ 구현됨 |
| 체인 설정 조회 | GET | /api/admin/partners/{id}/chain-configs | ✅ 구현됨 |
| 체인 설정 수정 | PUT | /api/admin/partners/{id}/chain-configs | ✅ 구현됨 |
| 출금 정책 조회 | GET | /api/admin/partners/{id}/withdrawal-policy | ✅ 구현됨 |
| 출금 정책 수정 | PUT | /api/admin/partners/{id}/withdrawal-policy | ✅ 구현됨 |
| 화이트리스트 조회 | GET | /api/admin/partners/{id}/whitelist | ✅ 구현됨 |
| 화이트리스트 추가 | POST | /api/admin/partners/{id}/whitelist | ✅ 구현됨 |
| 화이트리스트 삭제 | DELETE | /api/admin/partners/{id}/whitelist/{wid} | ✅ 구현됨 |
| 텔레그램 조회 | GET | /api/admin/partners/{id}/telegram | ✅ 구현됨 |
| 텔레그램 수정 | PUT | /api/admin/partners/{id}/telegram | ✅ 구현됨 |
| Axim 조회 | GET | /api/admin/partners/{id}/axim | ✅ 구현됨 |
| Axim 수정 | PUT | /api/admin/partners/{id}/axim | ✅ 구현됨 |
| API Key 재발급 | POST | /api/admin/partners/{id}/api-key/regenerate | ✅ 구현됨 |
| 2FA 초기화 | POST | /api/admin/partners/{id}/2fa/reset | ✅ 구현됨 |
| Webhook 로그 | GET | /api/admin/partners/{id}/webhook-logs | ✅ 구현됨 |
| 하위 파트너 | GET | /api/admin/partners/{id}/children | ✅ 구현됨 |
| 지갑 조회 | GET | /api/admin/partners/{id}/wallets | ✅ 구현됨 |
| 지갑 생성 | POST | /api/admin/partners/{id}/wallets | ✅ 구현됨 |
| loginEmail 수정 | — | — | ⚠️ 미구현 (PUT에 추가 필요) |

---

## 백엔드 수정 필요사항

### 1. PartnerUpdateRequest에 loginEmail 추가

현재 PUT /api/admin/partners/{id}는 name, webhookUrl, timezone, locale만 수정 가능.
loginEmail 필드 추가 + 중복 검사 로직 필요.

### 2. PartnerDetailResponse 보완

현재 응답에 없는 필드 추가:
- contactEmail (문의 이메일 — loginEmail과 별도)
- contactPhone (문의 전화번호)

→ Partner 엔티티에 해당 컬럼이 있는지 확인 필요.
  DDL에 없으면 추가하거나, loginEmail로 통합.

### 3. 수수료 변경 시 연쇄 영향 경고 API (선택)

`GET /api/admin/partners/{id}/fees/impact?maxFeeCap=3.0`
→ 영향받는 하위 파트너 수 반환 (프론트에서 확인 모달에 표시)

---

## 프론트엔드 핵심 변경사항

1. **탭 구성 변경**: 기존 6탭 → 7탭 (수수료 탭 추가, 캐스팅 설정 → 연동은 기본정보에 통합)
2. **수수료 탭 신규**: 4개 필드 + 범위 시각화 바 + 수정 폼
3. **하위 파트너 탭**: children API 연동 + 테이블 + 페이지네이션
4. **기본정보 재구성**: 3개 섹션으로 분리 (기본/계정/연동)
5. **상태변경**: 상태 전이 규칙에 따른 동적 버튼 + 사유 입력 모달
6. **위험 작업 분리**: API Key 재발급, 2FA 초기화, 삭제를 "더보기" 메뉴로 이동