# Admin Console UI 핸드오프 — 변경 사항 (v2 최종)

**작성일**: 2026-03-16
**기준 문서**:
- `CRYPTOMENTS_SUPER_ADMIN_IA.md` (v6.2, 2026-03-03)
- `CRYPTOMENTS_V2_API_DESIGN.md` (v1.1, 2026-03-03)
- `CRYPTOMENTS_SCREEN_DESIGN_V1.md` (v3.0, 2026-03-03)

**이 문서의 목적**: 위 3개 기존 UI 설계서에서 **변경/추가된 부분만** 정리.
기존 문서의 나머지 내용은 그대로 유효합니다.

---

## 1. 신규 화면 — 컨트랙트 관리 (SCR-5800)

> **기존 문서에 없음**. admin-api에 `ContractManagementController` 신규 추가됨.

**경로**: `/admin/contracts`
**메뉴 위치**: `5. 인프라 관리 > 5.8 컨트랙트 관리`

### 1.1 컨트랙트 목록

| # | Method | Endpoint | 용도 |
|---|--------|----------|------|
| 1 | GET | `/api/admin/contracts` | 전체 ACTIVE 컨트랙트 목록 |
| 2 | GET | `/api/admin/contracts/{networkId}/status` | 온체인 + DB 상태 조회 |

**목록 컬럼**:

| # | 헤더 | 필드 | 비고 |
|---|------|------|------|
| 1 | 네트워크 | network_id → JOIN | 네트워크명 |
| 2 | 컨트랙트 주소 | contract_address | 주소 표기 규칙 적용 |
| 3 | Owner | owner_address_id → JOIN | ADMIN 지갑 주소 |
| 4 | ABI 버전 | abi_version | |
| 5 | 상태 | status | ACTIVE=초록, PAUSED=주황, DEPRECATED=회색 |
| 6 | 정지 사유 | paused_reason | PAUSED 상태일 때만 표시 |
| 7 | 등록일 | created_at | |

### 1.2 컨트랙트 상세 (네트워크별)

`GET /contracts/{networkId}/status` 응답으로 온체인 실시간 정보 표시:

| # | 항목 | 출처 | 비고 |
|---|------|------|------|
| 1 | 컨트랙트 주소 | DB + 온체인 | |
| 2 | Owner 주소 | 온체인 | `contract.owner()` 결과 |
| 3 | Paused 상태 | 온체인 | `contract.paused()` 결과 |
| 4 | 등록된 Relayer 수 | 온체인 | |
| 5 | Relayer 주소 목록 | 온체인 | 리스트 표시 |
| 6 | DB 상태 | DB | |

### 1.3 컨트랙트 액션

| 액션 | API | 비고 |
|------|-----|------|
| 등록 | `POST /contracts/register` | 수동 배포 후 등록 (contractAddress, deployTxHash, ownerAddressId 필수) |
| Relayer 추가 | `POST /contracts/add-relayer` | networkId, relayerWalletId |
| Relayer 제거 | `POST /contracts/remove-relayer` | networkId, relayerWalletId |
| **긴급 정지** | `POST /contracts/pause` | ⚠️ reason 필수, 확인 모달(이중) |
| 정지 해제 | `POST /contracts/{networkId}/unpause` | 확인 모달 |

> **⚠️ 모든 액션은 온체인 TX 포함** — 응답 5~60초.
> 프로그레스 바 + 버튼 비활성화 + HTTP 타임아웃 60초 이상 필수.

### 1.4 컨트랙트 등록 폼

| # | 필드 | 컴포넌트 | 필수 | 유효성 |
|---|------|----------|------|--------|
| 1 | 네트워크 | Select | ★ | blockchain_networks 목록 |
| 2 | 컨트랙트 주소 | Text | ★ | 0x... 형식 (EVM) 또는 T... 형식 (TRON) |
| 3 | 배포 TX Hash | Text | ★ | |
| 4 | ADMIN 지갑 | Select | ★ | 해당 네트워크의 ADMIN 지갑 목록 |
| 5 | ABI 버전 | Text | | 기본값 "1.0" |

> **기존 API 설계서**: `POST /api/admin/contract/deploy`로 Node.js가 직접 배포
> **변경**: 수동 배포(Hardhat/Tronbox) → `transferOwnership(ADMIN)` → `POST /contracts/register`로 등록

---

## 2. Relayer 관리 변경 (SCR-5500)

### 2.1 추가 엔드포인트 (기존 3개 → 7개)

| # | Method | Endpoint | 용도 | 상태 |
|---|--------|----------|------|------|
| 1 | GET | `/api/admin/relayer-wallets` | 목록 | 기존 |
| 2 | POST | `/api/admin/relayer-wallets` | 등록 | **변경** (Node.js 연동) |
| 3 | PATCH | `/api/admin/relayer-wallets/{id}/status` | 상태 변경 | 기존 |
| 4 | GET | `/api/admin/relayer-wallets/{id}` | 상세 | **신규** |
| 5 | POST | `/api/admin/relayer-wallets/{id}/deactivate` | 해제 | **신규** |
| 6 | GET | `/api/admin/relayer-wallets/live` | 실시간 목록 | **신규** |
| 7 | GET | `/api/admin/relayer-wallets/health` | 헬스 집계 | **신규** |

### 2.2 등록 Request 변경

```json
// 기존 (API 설계서 v1.1)
{ "networkId": 1, "walletAddressId": 42, "contractAddress": "0x..." }

// 변경 — contractAddress 제거, relayerRole 추가
{ "networkId": 1, "walletAddressId": 42, "relayerRole": "COLLECTION" }
```

`relayerRole` 필드 추가: `COLLECTION` 또는 `WITHDRAWAL` (Select 컴포넌트)

### 2.3 해제 (deactivate) — 신규 기능

`POST /relayer-wallets/{id}/deactivate`

- pending TX가 있으면 `registrationStatus = DEREGISTERING` (온체인 해제 대기)
- pending TX가 없으면 즉시 해제 (온체인 `removeRelayer` TX 포함)
- **확인 모달 필수**: "Relayer를 해제하시겠습니까? 처리 중 TX가 완료될 때까지 대기할 수 있습니다."

### 2.4 실시간 목록 (live) — 신규 기능

`GET /relayer-wallets/live`

Node.js relayer-api에서 실시간 데이터를 가져옴 (pendingTxCount 등 폴러 상태 포함).
기존 목록(`GET /relayer-wallets`)은 DB 기준이라 pendingTxCount가 없음.

**권장 UI**: Relayer 관리 화면에 탭 또는 토글로 "DB 목록" / "실시간 상태" 전환.

### 2.5 헬스 집계 (health) — 신규 기능

`GET /relayer-wallets/health`

상태별/네트워크별 Relayer 집계 — 대시보드 위젯 또는 Relayer 목록 상단에 표시.

---

## 3. 인프라 지갑 변경 (SCR-5400)

### 3.1 ADMIN 지갑 생성 추가

기존: FEE, SETTLEMENT 생성만 있음.
추가: `POST /api/admin/infra-wallets/admin` — ADMIN 지갑 생성 (네트워크당 1개)

| # | Method | Endpoint | 용도 | 상태 |
|---|--------|----------|------|------|
| 1 | GET | `/api/admin/infra-wallets` | 목록 | 기존 |
| 2 | POST | `/api/admin/infra-wallets/admin` | ADMIN 지갑 생성 | **신규** |
| 3 | POST | `/api/admin/infra-wallets/gas` | GAS 지갑 생성 | 기존 |
| 4 | POST | `/api/admin/infra-wallets/settlement` | SETTLEMENT 지갑 생성 | 기존 |

**ADMIN 지갑**: 컨트랙트 Owner 역할. 네트워크당 1개만 허용 (이미 존재 시 기존 지갑 정보 반환).

---

## 4. 지갑 관리 변경 (SCR-5300)

### 4.1 추가 엔드포인트

| # | Method | Endpoint | 용도 | 상태 |
|---|--------|----------|------|------|
| 1~5 | | (기존 지갑 목록/상세/잔액 등) | | 기존 |
| 6 | GET | `/api/admin/tx/status/{txHash}?networkId=` | TX 온체인 상태 조회 | **신규** |
| 7 | GET | `/api/admin/wallet-index` | 지갑 인덱스 관리 목록 | **신규** |

### 4.2 TX 상태 조회 — 범용 도구

모든 TX Hash(입금/출금/집금/approve)의 온체인 상태를 조회할 수 있는 범용 엔드포인트.
blockchain-api 연동으로 실시간 확인.

**응답**:
```json
{
  "txHash": "0xabc...",
  "status": "confirmed",    // "pending" | "confirmed" | "failed"
  "blockNumber": 18000000,
  "confirmations": 15,
  "gasUsed": "65000"
}
```

**UI 적용 위치**: 입금 상세, 출금 상세, 집금 상세 등에서 "온체인 확인" 버튼으로 활용.

---

## 5. 출금 관리 변경 (SCR-3200)

### 5.1 일괄 승인/거부 추가

기존 API 설계서에는 단건 승인/거부만 있음. 일괄 처리 추가:

| # | Method | Endpoint | 용도 | 상태 |
|---|--------|----------|------|------|
| 1 | POST | `/api/admin/withdrawals/batch-approve` | 일괄 승인 | **신규** |
| 2 | POST | `/api/admin/withdrawals/batch-reject` | 일괄 거부 | **신규** |

**Request**:
```json
// batch-approve
{ "ids": [1, 2, 3] }

// batch-reject
{ "ids": [1, 2, 3], "reason": "KYC 미완료" }
```

**UI**: 승인 대기 목록에서 체크박스 선택 → [일괄 승인] / [일괄 거부] 버튼.
⚠️ 일괄 승인은 위험 액션 — 확인 모달에 선택 건수와 총 금액 표시.

---

## 6. 상태값 변경

### 6.1 집금 상태

| 기존 (화면설계서) | 변경 | 비고 |
|------------------|------|------|
| COMPLETED | **CONFIRMED** | DDL v1.5 기준 통일 |

`collection_queue.status`: `QUEUED → COLLECTING → BROADCASTING → CONFIRMED / FAILED`
(화면설계서 부록 B에서 `COMPLETED → CONFIRMED` 으로 수정)

### 6.2 Relayer 상태 분리

기존 (API 설계서 v1.1)에서는 `registrationStatus` + `status` 분리가 반영되어 있지만,
`status` 값 목록이 업데이트됨:

| 필드 | 값 | 비고 |
|------|-----|------|
| status (운영) | `ACTIVE`, `PAUSED` | 기존 `INACTIVE` 제거 |
| registrationStatus (온체인) | `PENDING`, `REGISTERING`, `REGISTERED`, `DEREGISTERING`, `REVOKED` | 기존과 동일 |

### 6.3 출금 상태

| 기존 | 변경 |
|------|------|
| CANCELED | **CANCELLED** | 영문 스펠링 수정 (L 2개) |

---

## 7. 감사 로그 개선 (SCR-8200)

### 7.1 action 필드 — enum 기반 (47개)

기존: 자유 문자열. 변경: `AuditAction` enum 기반 47개 고정 액션.

UI에서 감사 로그 검색 시 `action` 필터를 Select(드롭다운)로 변경 가능:

**카테고리별 액션 목록**:

| 카테고리 | 액션 |
|----------|------|
| 파트너 | CREATE_PARTNER, UPDATE_PARTNER, CHANGE_PARTNER_STATUS, REGENERATE_API_KEY, RESET_PARTNER_2FA, UPDATE_PARTNER_FEES, ADD_WHITELIST_ADDRESS, DELETE_WHITELIST_ADDRESS, UPDATE_CHAIN_CONFIGS, UPDATE_WITHDRAWAL_POLICY, UPDATE_TELEGRAM_CONFIG, UPDATE_TELEGRAM_SUBSCRIPTIONS, UPDATE_AXIM_SETTINGS |
| 입금 | MATCH_UNIDENTIFIED_DEPOSIT, REFUND_UNIDENTIFIED_DEPOSIT |
| 출금 | APPROVE_WITHDRAWAL, REJECT_WITHDRAWAL, RETRY_WITHDRAWAL |
| 집금 | RETRY_COLLECTION, CANCEL_COLLECTION |
| 지갑 | CREATE_ADMIN_WALLET, CREATE_FEE_WALLET, CREATE_SETTLEMENT_WALLET, SYNC_BALANCES, SYNC_WALLET_BALANCE, RETRY_APPROVAL |
| Relayer | CREATE_RELAYER, DEACTIVATE_RELAYER, UPDATE_RELAYER_STATUS |
| 컨트랙트 | REGISTER_CONTRACT, ADD_RELAYER_TO_CONTRACT, REMOVE_RELAYER_FROM_CONTRACT, PAUSE_CONTRACT, UNPAUSE_CONTRACT |
| 시스템 | UPDATE_SYSTEM_SETTING, CREATE_BLOCKCHAIN_NETWORK, UPDATE_BLOCKCHAIN_NETWORK, CREATE_CURRENCY, UPDATE_CURRENCY, ENABLE_MAINTENANCE, DISABLE_MAINTENANCE |
| 논스 | SYNC_NONCE, UNLOCK_NONCE |
| 정산/가스 | SETTLEMENT_WITHDRAW, WAIVE_GAS_COST, GENERATE_GAS_INVOICES, CONFIRM_GAS_INVOICE_PAYMENT, MARK_GAS_INVOICE_OVERDUE |

### 7.2 details 필드 — JSON 구조화

기존: 문자열 결합으로 비정형 JSON. 변경: `ObjectMapper` 직렬화로 구조화된 JSON.

```json
// 상태 변경
{ "previousStatus": "PENDING_APPROVAL", "newStatus": "APPROVED" }

// 생성
{ "networkId": 1, "walletType": "ADMIN", "address": "0x..." }

// 설정 변경
{ "settingKey": "maintenance_mode", "previousValue": "false", "newValue": "true" }
```

감사 로그 상세에서 `details` JSON을 key-value 테이블로 렌더링 권장.

---

## 8. 온체인 연동 API — 로딩 처리 필수

다음 API는 **Node.js blockchain-api/relayer-api 경유 + 블록체인 TX 포함**으로 응답이 느림:

| API | 예상 소요 | UI 처리 |
|-----|----------|---------|
| `POST /contracts/register` | 5~15초 | 프로그레스 + 버튼 비활성화 |
| `POST /contracts/add-relayer` | 10~30초 | 프로그레스 + 버튼 비활성화 |
| `POST /contracts/remove-relayer` | 10~30초 | 프로그레스 + 버튼 비활성화 |
| `POST /contracts/pause` | 10~30초 | 프로그레스 + 이중 확인 |
| `POST /contracts/{networkId}/unpause` | 10~30초 | 프로그레스 |
| `POST /relayer-wallets` (등록) | 10~30초 | 프로그레스 |
| `POST /relayer-wallets/{id}/deactivate` | 5~60초 | 프로그레스 |
| `POST /wallets/sync-balances` | 3~15초 | 프로그레스 |
| `POST /infra-wallets/admin` | 3~10초 | 프로그레스 |

> HTTP 타임아웃: 최소 **60초** 설정 필요.
> 이외 API는 일반 DB 조회로 1초 이내.

---

## 9. 메뉴 트리 변경 요약

```diff
 5. 인프라 관리
      5.1 네트워크 설정
      5.2 통화 관리
      5.3 HD Wallet
-     5.4 인프라 지갑 생성/관리 (FEE, Relayer, SETTLEMENT)
+     5.4 인프라 지갑 생성/관리 (ADMIN, FEE, SETTLEMENT)
      5.5 Approve 현황
      5.6 논스 관리
      5.7 전체 지갑/잔액 조회
+     5.8 컨트랙트 관리 ← 신규
```

Relayer 관리(5.5)는 기존과 동일 위치, 엔드포인트만 3개 → 7개 확장.

---

## 10. 변경 사항 체크리스트

| # | 변경 | 영향 화면 | 우선순위 |
|---|------|----------|----------|
| 1 | 컨트랙트 관리 화면 신규 | SCR-5800 (신규) | HIGH |
| 2 | Relayer 해제/실시간/헬스 추가 | SCR-5500 | HIGH |
| 3 | ADMIN 지갑 생성 추가 | SCR-5400 | HIGH |
| 4 | 출금 일괄 승인/거부 | SCR-3200 | HIGH |
| 5 | TX 온체인 상태 조회 | SCR-5300 + 입금/출금 상세 | MEDIUM |
| 6 | 집금 상태 COMPLETED→CONFIRMED | SCR-3400, 부록 B | LOW |
| 7 | 출금 CANCELED→CANCELLED 스펠링 | SCR-3200, 부록 B | LOW |
| 8 | Relayer INACTIVE 제거 | SCR-5500, 부록 B | LOW |
| 9 | 감사 로그 action Select 드롭다운 | SCR-8200 | LOW |
| 10 | 온체인 API 로딩 처리 | 5.4, 5.5, 5.8 | HIGH |

---

## 변경 이력

| 버전 | 날짜 | 변경 내용 |
|------|------|----------|
| v1.0 | 2026-03-16 | 초안 — 기존 3개 UI 설계서 대비 10개 변경사항 정리 |