# Admin-UI ↔ Admin-API 동기화 감사 보고서 + 수정 지침

> **작성일**: 2026-03-30
> **범위**: Admin-UI (Vue 3) ↔ Admin-API (Spring Boot) ↔ Partner-API ↔ DDL v1.6
> **목적**: UI API 호출 경로 불일치, 누락 필드, 미구현 기능 식별 및 수정 지침 제공

---

## 1. 감사 요약

### 규모

| 항목 | 수량 |
|------|------|
| Admin-API 컨트롤러 | 25개 |
| Admin-API 엔드포인트 | 147개 |
| Partner-API 컨트롤러 | 19개 |
| Partner-API 엔드포인트 | 158개 |
| Admin-UI 서비스 파일 | 11개 |
| Admin-UI API 함수 | ~85개 |
| Admin-UI 뷰 컴포넌트 | 40개 |

### 심각도 분류

- **🔴 Critical**: API 경로 불일치 — 호출 자체가 실패 (404)
- **🟠 Major**: 기능 누락 — API는 있는데 UI에서 호출 안 함
- **🟡 Minor**: 타입 불일치 — 동작하지만 데이터 매핑 오류 가능
- **⚪ Info**: 개선 권장

---

## 2. 🔴 Critical — API 경로 불일치 (404 발생)

### 2.1 시스템 설정

| UI 호출 경로 | 실제 Admin-API 경로 | 비고 |
|---|---|---|
| `GET /admin/system-settings` | `GET /api/admin/settings` | 경로 자체가 다름 |
| `PUT /admin/system-settings/{key}` | `PUT /api/admin/settings/{key}` | 경로 자체가 다름 |

**수정**: `system.service.ts`의 URL을 `/admin/settings`로 변경

### 2.2 감사 로그

| UI 호출 경로 | 실제 Admin-API 경로 | 비고 |
|---|---|---|
| `GET /admin/audit-logs` | `GET /api/admin/audit-logs` | ✅ 일치 |

### 2.3 유지보수 모드

| UI 호출 경로 | 실제 Admin-API 경로 | 비고 |
|---|---|---|
| `GET /admin/maintenance` | ❌ 엔드포인트 없음 | 상태 조회 API 미구현 |
| `POST /admin/maintenance/enable` | `POST /api/admin/maintenance/enable` | ✅ 일치 |
| `POST /admin/maintenance/disable` | `POST /api/admin/maintenance/disable` | ✅ 일치 |

**수정**: Admin-API에 `GET /api/admin/maintenance` 상태 조회 엔드포인트 추가

### 2.4 관리자 관리

| UI 호출 경로 | 실제 Admin-API 경로 | 비고 |
|---|---|---|
| `POST /admin/admins/{id}/reset-password` | ❌ 없음 | Admin-API에 비밀번호 리셋 없음 |
| `POST /admin/admins/{id}/reset-2fa` | `POST /api/admin/admins/{id}/2fa/reset` | 경로 다름 |

**수정**:
- `system.service.ts` `reset2fa` URL을 `/admin/admins/{id}/2fa/reset`으로 변경
- 비밀번호 리셋 엔드포인트를 Admin-API에 추가하거나 UI에서 제거

### 2.5 CS 도구 — 미식별 입금

| UI 호출 경로 | 실제 Admin-API 경로 | 비고 |
|---|---|---|
| `GET /admin/cs/unidentified-deposits` | `GET /api/admin/cs/unidentified` | 경로 다름 |
| `POST /admin/cs/unidentified-deposits/{id}/match` | `POST /api/admin/cs/unidentified/{id}/match` | 경로 다름 |
| `POST /admin/cs/unidentified-deposits/{id}/refund` | `POST /api/admin/cs/unidentified/{id}/refund` | 경로 다름 |

**수정**: `cs.service.ts`의 `unidentified-deposits` → `unidentified`로 모두 변경

### 2.6 집금 관리

| UI 호출 경로 | 실제 Admin-API 경로 | 비고 |
|---|---|---|
| `POST /admin/collections/{id}/retry` | ❌ 없음 | Admin-API에 retry 없음 |
| `POST /admin/collections/{id}/cancel` | ❌ 없음 | Admin-API에 cancel 없음 |

**수정**: UI에서 retry/cancel 버튼 제거하거나 Admin-API에 엔드포인트 추가. 현재 Admin-API는 `POST /collections/batches/{batchId}/fail`만 존재.

### 2.7 Relayer 관리

| UI 호출 경로 | 실제 Admin-API 경로 | 비고 |
|---|---|---|
| `GET /admin/relayer-wallets` | `GET /api/admin/relayers` | 경로 다름 |
| `POST /admin/relayer-wallets` | `POST /api/admin/relayers` | 경로 다름 |
| `GET /admin/relayer-wallets/{id}` | `GET /api/admin/relayers/{id}` | 경로 다름 |
| `POST /admin/relayer-wallets/{id}/deactivate` | `POST /api/admin/relayers/{id}/deactivate` | 경로 다름 |
| `PATCH /admin/relayer-wallets/{id}/status` | `PATCH /api/admin/relayers/{id}/status` | 경로 다름 |
| `GET /admin/relayer-wallets/live` | `GET /api/admin/relayers/live` | 경로 다름 |
| `GET /admin/relayer-wallets/health` | `GET /api/admin/relayers/health` | 경로 다름 |

**수정**: `infra.service.ts` relayerService의 모든 URL을 `/admin/relayer-wallets` → `/admin/relayers`로 변경

### 2.8 논스 관리

| UI 호출 경로 | 실제 Admin-API 경로 | 비고 |
|---|---|---|
| `POST /admin/nonce-trackers/{id}/reset` | ❌ 없음 | Admin-API에는 reset 없음 |

**수정**: Admin-API에 `POST /api/admin/nonce-trackers/{id}/reset`은 `unlock`으로 매핑. UI의 reset → unlock으로 변경하거나 Admin-API에 reset 추가.

### 2.9 가스 인보이스

| UI 호출 경로 | 실제 Admin-API 경로 | 비고 |
|---|---|---|
| `POST /admin/gas-invoices` | `POST /api/admin/gas-invoices/generate` | 경로 다름 |
| `PATCH /admin/gas-invoices/{id}/confirm-payment` | `POST /api/admin/gas-invoices/{id}/confirm-payment` | HTTP 메서드 다름 (PATCH vs POST) |

**수정**:
- `gas.service.ts` createInvoice URL을 `/admin/gas-invoices/generate`로 변경
- confirmPayment을 `PATCH` → `POST`로 변경

### 2.10 원장/환율

| UI 호출 경로 | 실제 Admin-API 경로 | 비고 |
|---|---|---|
| `GET /admin/ledger-entries` | `GET /api/admin/ledgers` | 경로 다름 |
| `GET /admin/exchange-rates/current` | `GET /api/admin/prices/current` | 경로 다름 |
| `GET /admin/exchange-rates/history` | `GET /api/admin/prices/history` | 경로 다름 |

**수정**: `gas.service.ts`에서 경로 수정

### 2.11 정산 실현

| UI 호출 경로 | 실제 Admin-API 경로 | 비고 |
|---|---|---|
| `POST /admin/settlements/realize` | ❌ 없음 | Admin-API에 realize 없음, `POST /withdraw`만 있음 |

**수정**: UI realize → withdraw로 변경하거나 Admin-API에 realize 추가

---

## 3. 🟠 Major — 기능 누락 (API는 있지만 UI 미연결)

### 3.1 Admin-API에 있고 UI에 없는 기능

| Admin-API 엔드포인트 | 기능 | UI 상태 |
|---|---|---|
| `POST /wallets/{id}/monitor/register` | 단건 모니터 등록 | ❌ 미구현 (오늘 추가됨) |
| `POST /wallets/monitor/register-unregistered` | 일괄 모니터 등록 | ❌ 미구현 |
| `GET /wallets/{id}` (상세) | 지갑 상세 | ❌ GlobalWalletView에 상세 페이지 없음 |
| `POST /wallets/{id}/sync-balance` | 단일 잔액 동기화 | ❌ 미구현 |
| `POST /wallets/sync-balances` | 일괄 잔액 동기화 | ❌ 미구현 |
| `GET /tx/status/{txHash}` | TX 온체인 상태 | ❌ 미구현 (DepositDetail/WithdrawalDetail에서 사용 가능) |
| `GET /wallet-index` | 인덱스 관리 | ❌ 미구현 |
| `GET /deposits/{id}/history` | 입금 상태 이력 | ❌ 미구현 |
| `GET /withdrawals/{id}/history` | 출금 상태 이력 | ❌ 미구현 |
| `POST /withdrawals/{id}/retry` | 출금 재시도 | ❌ 미구현 |
| `POST /withdrawals/{id}/cancel` | 출금 취소 | ❌ 미구현 |
| `GET /withdrawals/pending-approval` | 승인 대기 목록 | ❌ 미구현 |
| `POST /partners/{id}/api-key/regenerate` | API 키 재발급 | ❌ partner.service.ts URL 불일치 |
| `GET /gas-costs/{id}` | 가스비 상세 | ❌ 미구현 |
| `PATCH /gas-costs/{id}/waive` | 가스비 면제 | ❌ 미구현 |
| `PATCH /gas-invoices/{id}/overdue` | 인보이스 연체 | ❌ 미구현 |
| `GET /gas-invoices/{id}` | 인보이스 상세 | ❌ 미구현 |
| `POST /collections/batches/{batchId}/fail` | STALE 배치 실패 처리 | ❌ 미구현 |
| `POST /admin/admins/me/2fa/setup` | 본인 2FA 설정 | ❌ 미구현 |
| `POST /admin/admins/me/2fa/verify` | 본인 2FA 검증 | ❌ 미구현 |
| `GET /payment-links` | 결제 링크 목록 | ❌ 미구현 |
| `POST /settlements/withdraw` | 시스템 쉐어 출금 | ❌ 미구현 |
| `GET /ledgers/balance` | 파트너 원장 잔액 | ❌ 미구현 |

### 3.2 UI에 있고 Admin-API에 없는 기능

| UI 함수 | 호출 경로 | Admin-API 상태 |
|---|---|---|
| `collectionService.retry()` | `POST /admin/collections/{id}/retry` | ❌ 없음 |
| `collectionService.cancel()` | `POST /admin/collections/{id}/cancel` | ❌ 없음 |
| `systemService.getMaintenanceStatus()` | `GET /admin/maintenance` | ❌ 없음 |
| `adminService.resetPassword()` | `POST /admin/admins/{id}/reset-password` | ❌ 없음 |
| `settlementService.realize()` | `POST /admin/settlements/realize` | ❌ 없음 |
| `nonceService.reset()` | `POST /admin/nonce-trackers/{id}/reset` | unlock만 있음 |

---

## 4. 🟡 Minor — 타입/필드 불일치

### 4.1 Partner 타입

| UI 필드 | Admin-API 필드 | 비고 |
|---|---|---|
| `PartnerDetail.businessName` | DDL에 없음 | DDL v1.6에서 삭제됨 (SYNC_GUIDE 참조) |
| `PartnerDetail.loginEmail` | `Admin.loginId` | 필드명 불일치 |
| `PartnerCreateRequest.password` | Admin-API에서 처리 | 파트너 비밀번호는 Admin 테이블 |

### 4.2 Relayer 타입

| UI 필드 | Admin-API 응답 | 비고 |
|---|---|---|
| `RelayerItem.relayerRole` | `RelayerDetailResponse` | UI에서 `COLLECTION|WITHDRAWAL`만 정의, API에는 `APPROVE|GAS_SUPPORT`도 있음 |
| `RelayerItem.registrationStatus` | `PENDING|REGISTERING|REGISTERED|DEREGISTERING|REVOKED` | API 응답과 일치 여부 확인 필요 |

### 4.3 Nonce Tracker 타입

| UI 필드 | Admin-API 응답 | 비고 |
|---|---|---|
| `NonceTrackerItem.status: AVAILABLE|LOCKED` | `NonceTracker.isLocked: boolean` | 상태 표현 방식 다름 |

### 4.4 GasInvoice 타입

| UI 필드 | Admin-API 응답 | 비고 |
|---|---|---|
| `GasInvoiceItem.confirmedByName` | `GasInvoice` entity | 필드 존재 여부 확인 필요 |

---

## 5. 수정 지침 (우선순위별)

### P0 — 🔴 Critical (즉시 수정, 현재 404 발생)

#### 5.1 `src/api/services/cs.service.ts`
```typescript
// ❌ Before
'/admin/cs/unidentified-deposits'
'/admin/cs/unidentified-deposits/{id}/match'
'/admin/cs/unidentified-deposits/{id}/refund'

// ✅ After
'/admin/cs/unidentified'
'/admin/cs/unidentified/{id}/match'
'/admin/cs/unidentified/{id}/refund'
```

#### 5.2 `src/api/services/infra.service.ts` — Relayer
```typescript
// ❌ Before: 모든 relayerService URL
'/admin/relayer-wallets'
'/admin/relayer-wallets/{id}'
'/admin/relayer-wallets/{id}/deactivate'
'/admin/relayer-wallets/{id}/status'
'/admin/relayer-wallets/live'
'/admin/relayer-wallets/health'

// ✅ After
'/admin/relayers'
'/admin/relayers/{id}'
'/admin/relayers/{id}/deactivate'
'/admin/relayers/{id}/status'
'/admin/relayers/live'
'/admin/relayers/health'
```

#### 5.3 `src/api/services/system.service.ts`
```typescript
// ❌ Before
'/admin/system-settings'
'/admin/system-settings/{key}'
'/admin/admins/{id}/reset-2fa'

// ✅ After
'/admin/settings'
'/admin/settings/{key}'
'/admin/admins/{id}/2fa/reset'
```

#### 5.4 `src/api/services/gas.service.ts`
```typescript
// ❌ Before
post('/admin/gas-invoices', data)          // createInvoice
patch('/admin/gas-invoices/{id}/confirm-payment')  // confirmPayment
get('/admin/ledger-entries')               // getLedger
get('/admin/exchange-rates/current')       // getCurrentRates
get('/admin/exchange-rates/history')       // getRateHistory

// ✅ After
post('/admin/gas-invoices/generate', data)         // createInvoice
post(`/admin/gas-invoices/${id}/confirm-payment`)  // confirmPayment (PATCH→POST)
get('/admin/ledgers')                              // getLedger
get('/admin/prices/current')                       // getCurrentRates
get('/admin/prices/history')                       // getRateHistory
```

#### 5.5 `src/api/services/partner.service.ts`
```typescript
// ❌ Before
post(`/admin/partners/${id}/regenerate-api-key`)
get(`/admin/partners/${id}/axim-settings`)
put(`/admin/partners/${id}/axim-settings`)
get(`/admin/partners/${id}/telegram/config`)
patch(`/admin/partners/${id}/telegram/config`)

// ✅ After
post(`/admin/partners/${id}/api-key/regenerate`)
get(`/admin/partners/${id}/axim`)
put(`/admin/partners/${id}/axim`)
get(`/admin/partners/${id}/telegram`)
put(`/admin/partners/${id}/telegram`)    // PATCH→PUT
```

### P1 — 🟠 Major (기능 추가)

#### 5.6 지갑 상세 + 모니터 등록 (이미 지침서 작성됨)
→ `v2-docs/WALLET_MONITOR_REGISTRATION_UI_GUIDE.md` 참조

#### 5.7 `src/api/services/infra.service.ts` — 누락 함수 추가
```typescript
// 지갑 상세
getDetail: (id: number) => client.get(`/admin/wallets/${id}`),
// 단일 잔액 동기화
syncBalance: (id: number) => client.post(`/admin/wallets/${id}/sync-balance`),
// 일괄 잔액 동기화
syncAllBalances: () => client.post('/admin/wallets/sync-balances'),
// 단건 모니터 등록
registerMonitor: (id: number) => client.post(`/admin/wallets/${id}/monitor/register`),
// 미등록 일괄 등록
registerUnregistered: () => client.post('/admin/wallets/monitor/register-unregistered'),
// TX 상태 조회
getTxStatus: (txHash: string, networkId: number) =>
  client.get(`/admin/tx/status/${txHash}`, { params: { networkId } }),
```

#### 5.8 출금 관리 — 누락 함수
```typescript
// src/api/services/withdrawal.service.ts 추가
retry: (id: number) => client.post(`/admin/withdrawals/${id}/retry`),
cancel: (id: number) => client.post(`/admin/withdrawals/${id}/cancel`),
getPendingApproval: (params) => client.get('/admin/withdrawals/pending-approval', { params }),
getHistory: (id: number) => client.get(`/admin/withdrawals/${id}/history`),
```

#### 5.9 입금 관리 — 상태 이력
```typescript
// src/api/services/deposit.service.ts 추가
getHistory: (id: number) => client.get(`/admin/deposits/${id}/history`),
```

#### 5.10 가스비 — 상세/면제/연체
```typescript
// src/api/services/gas.service.ts 추가
getRecordDetail: (id: number) => client.get(`/admin/gas-costs/${id}`),
waiveRecord: (id: number) => client.patch(`/admin/gas-costs/${id}/waive`),
getInvoiceDetail: (id: number) => client.get(`/admin/gas-invoices/${id}`),
markOverdue: (id: number) => client.patch(`/admin/gas-invoices/${id}/overdue`),
```

### P2 — 🟡 Minor (타입 정리)

#### 5.11 `PartnerDetail.businessName` 필드 제거
DDL v1.6에서 삭제됨. `partner.ts`와 `PartnerCreateRequest`에서 제거.

#### 5.12 Relayer relayerRole enum 확장
```typescript
relayerRole: 'COLLECTION' | 'WITHDRAWAL' | 'APPROVE' | 'GAS_SUPPORT'
```

#### 5.13 NonceTracker status 통일
Admin-API가 `isLocked: boolean`을 반환하면 UI에서 변환:
```typescript
status: item.isLocked ? 'LOCKED' : 'AVAILABLE'
```

---

## 6. Admin-API 백엔드 추가 구현 필요 항목

| 항목 | 엔드포인트 | 상태 |
|------|-----------|------|
| 유지보수 상태 조회 | `GET /api/admin/maintenance` | 🔴 UI에서 호출하지만 없음 |
| 관리자 비밀번호 리셋 | `POST /api/admin/admins/{id}/reset-password` | 🔴 UI에서 호출하지만 없음 |
| 집금 재시도/취소 | `POST /collections/{id}/retry`, `cancel` | 🟠 UI에서 호출하지만 없음 |
| 정산 실현 실행 | `POST /settlements/realize` | 🟠 UI에서 호출하지만 없음 |
| 논스 리셋 | `POST /nonce-trackers/{id}/reset` | 🟡 unlock은 있음 |
| 결제 링크 관리 | 목록 조회만 있음 | ⚪ 필요 시 추가 |

---

## 7. 파일 변경 체크리스트

### UI 수정 (P0)

- [ ] `src/api/services/cs.service.ts` — URL 3건 수정
- [ ] `src/api/services/infra.service.ts` — Relayer URL 7건 수정
- [ ] `src/api/services/system.service.ts` — URL 3건 수정
- [ ] `src/api/services/gas.service.ts` — URL 5건 + HTTP 메서드 1건 수정
- [ ] `src/api/services/partner.service.ts` — URL 5건 + HTTP 메서드 1건 수정

### UI 추가 (P1)

- [ ] `src/api/services/infra.service.ts` — 6개 함수 추가 (지갑 상세/동기화/모니터/TX)
- [ ] `src/api/services/withdrawal.service.ts` — 4개 함수 추가
- [ ] `src/api/services/deposit.service.ts` — 1개 함수 추가
- [ ] `src/api/services/gas.service.ts` — 4개 함수 추가
- [ ] `src/views/infra/WalletDetailView.vue` — 신규 (지침서 참조)
- [ ] `src/router/index.ts` — 지갑 상세 라우트 추가

### API 백엔드 추가 (P0~P1)

- [ ] `MaintenanceController` — GET 상태 조회 추가
- [ ] `AdminManagementController` — 비밀번호 리셋 추가
- [ ] `CollectionManagementController` — retry/cancel 추가 (또는 UI 제거)
- [ ] `SettlementController` — realize 추가 (또는 UI 제거)

### 타입 정리 (P2)

- [ ] `src/api/types/partner.ts` — businessName 제거
- [ ] `src/api/types/infra.ts` — RelayerItem.relayerRole enum 확장