# 지갑 UI 설계

> 작성일: 2026-03-23
> 상태: 승인됨

---

## 개요

웹 클라이언트(`a301_client`)에 블록체인 지갑 UI를 추가한다. 단일 `/wallet` 페이지에 4개 탭(지갑, 자산, 인벤토리, 마켓)으로 구성하고, HomePage에 잔액 요약 카드를 배치한다.

---

## 페이지 구조

### 라우팅

| 경로 | 컴포넌트 | 인증 |
|------|----------|------|
| `/wallet` | WalletPage | 로그인 필수 |

`/wallet` 라우트 보호: 기존 `AdminRoute` 패턴을 참고하여 `PrivateRoute` 컴포넌트를 새로 만든다. 로그인하지 않은 유저는 `/login`으로 리다이렉트.

기존 라우트는 변경하지 않는다.

### HomePage 변경

1. **헤더**: "지갑" 링크 추가 → `/wallet`로 이동
2. **지갑 요약 카드**: DownloadSection 위에 배치
   - TOL 잔액 (큰 글씨)
   - 보유 자산 수, 장착 아이템 수
   - 클릭 시 `/wallet`로 이동
   - 로그인하지 않은 상태에서는 숨김
   - 3개 API (`/balance`, `/assets`, `/inventory`) `Promise.all`로 병렬 호출
   - 일부 API 실패 시: 실패한 항목만 "--"로 표시, 카드 자체는 숨기지 않음

---

## 탭 1: 지갑

잔액, 지갑 주소, 키 내보내기.

### 잔액 카드
- TOL 잔액을 크게 표시
- API: `GET /api/chain/balance`

### 지갑 정보
- 공개키: 축약 표시 (`a3b4...e1f2`) + 복사 버튼
- 주소: 축약 표시 (`a3b4c5d6...e9f0a1b2`) + 복사 버튼
- 클릭 시 클립보드에 전체 값 복사, 토스트로 "복사됨" 알림
- API: `GET /api/chain/wallet`

### 키 내보내기
- 비밀번호 입력 필드 + "내보내기" 버튼
- 성공 시: 개인키 hex를 화면에 표시 (복사 버튼 포함)
- 경고 텍스트: "개인키를 안전하게 보관하세요"
- 탭 이탈 시(다른 탭 클릭): 개인키 표시 상태 초기화 (보안)
- 에러 처리:
  - HTTP 401 → "비밀번호가 올바르지 않습니다"
  - 기타 에러 → 토스트로 서버 에러 메시지 표시
- API: `POST /api/chain/wallet/export` (body: `{"password": "..."}`)

---

## 탭 2: 자산

보유 NFT 목록 + 상세 정보.

### 자산 목록
- 아이템 이름, 템플릿 이름, 자산 ID 표시
- 거래 가능 여부 표시 ("거래 가능" / "거래 불가")
- API 호출 전략:
  1. `GET /api/chain/assets` → 자산 ID 배열 반환
  2. 각 ID에 대해 `GET /api/chain/asset/:id`를 `Promise.all`로 **병렬 호출**
  3. 개별 자산 로드 실패 시: 해당 자산만 "로드 실패" 표시, 나머지는 정상 표시
- 로딩 중: 스피너 표시

### 자산 상세 (클릭 시 펼치기)
- 속성(properties) 키-값 표시
- 거래 가능 여부
- 마켓 등록 상태 (등록됨 / 미등록)
- **마켓 등록 버튼**: 미등록 + 거래 가능한 자산에만 표시
  - 클릭 시: 가격 입력 인라인 UI (펼쳐진 상세 영역 내 숫자 input + "등록" 버튼)
  - `POST /api/chain/market/list` (body: `{"asset_id": "...", "price": N}`)
  - Idempotency-Key 헤더 필요
  - 성공 시: 토스트 알림 + 해당 자산 상태 갱신 (마켓 등록됨으로 변경)

---

## 탭 3: 인벤토리

장착 슬롯 현황 (조회 전용).

### 슬롯 목록
- 슬롯 이름 + 장착된 아이템 이름/ID 표시
- 빈 슬롯은 "비어있음"으로 표시 (점선 테두리)
- 장착/해제 버튼 없음 (게임 내에서만 조작)
- API: `GET /api/chain/inventory`

---

## 탭 4: 마켓

NFT 마켓플레이스. 구매, 판매(자산 탭에서 연결), 취소.

### 리스팅 목록
- 전체 / 내 리스팅 필터 토글
- 각 리스팅: 아이템 이름, 판매자 (축약 주소), 가격
- "내 리스팅" 필터: 클라이언트에서 `/api/chain/wallet`으로 가져온 내 지갑 주소와 리스팅의 seller 필드를 비교하여 필터링
- API: `GET /api/chain/market` → 활성 리스팅 목록
- 미사용: `GET /api/chain/market/:id` — 리스팅 상세 모달이 없으므로 의도적으로 사용하지 않음

### 구매
- 타인의 리스팅에 "구매" 버튼
- 확인 다이얼로그 (useConfirm 사용): "화염 활을 500 TOL에 구매하시겠습니까?"
- `POST /api/chain/market/buy` (body: `{"listing_id": "..."}`)
- Idempotency-Key 헤더 필요
- 성공 시: 토스트 알림 + 리스팅 목록 새로고침 + 잔액 갱신
- 실패 시: 서버 응답 에러 메시지를 토스트로 표시 (잔액 부족 등 포함)

### 내 리스팅 취소
- 내 리스팅에 "취소" 버튼 (빨간 테두리)
- 확인 다이얼로그: "리스팅을 취소하시겠습니까?"
- `POST /api/chain/market/cancel` (body: `{"listing_id": "..."}`)
- Idempotency-Key 헤더 필요
- 성공 시: 토스트 알림 + 리스팅 목록 새로고침

---

## API 호출 패턴

### 기존 API 클라이언트 활용
- 모든 API 호출은 `src/api/client.js`의 `apiFetch()` 경유
- JWT 토큰 자동 첨부, 401 시 자동 refresh
- 새 파일: `src/api/chain.js` — 체인 관련 API 래퍼 함수 모음

### Idempotency-Key
- 마켓 구매/등록/취소 등 트랜잭션 API에는 `Idempotency-Key` 헤더 필요
- `chain.js` 래퍼 내부에서 `crypto.randomUUID()`로 자동 생성하여 헤더에 추가
- 호출 측(컴포넌트)에서는 Idempotency-Key를 신경 쓸 필요 없음

### 에러 처리
- API 에러 시 토스트로 에러 메시지 표시
- 네트워크 에러 시 기존 retry 로직 적용 (GET만)

### 로딩 상태
- 각 탭 진입 시: 중앙 스피너 표시 (기존 로딩 패턴과 동일)
- WalletSummary: 인라인 스피너 또는 "--" placeholder

---

## 컴포넌트 구조

```
src/
├── api/
│   └── chain.js              # 체인 API 래퍼 (신규)
├── pages/
│   ├── WalletPage.jsx        # /wallet 페이지 (탭 컨테이너) (신규)
│   └── WalletPage.css        # 지갑 페이지 스타일 (신규)
├── components/
│   └── wallet/               # 지갑 관련 컴포넌트 (신규)
│       ├── WalletTab.jsx     # 탭 1: 잔액, 주소, 키 내보내기
│       ├── AssetsTab.jsx     # 탭 2: 자산 목록 + 상세
│       ├── InventoryTab.jsx  # 탭 3: 인벤토리 조회
│       ├── MarketTab.jsx     # 탭 4: 마켓
│       └── WalletSummary.jsx # HomePage 요약 카드
```

---

## 스타일링

- 기존 프로젝트 패턴 그대로: plain CSS, dark 테마
- 색상: 기존 `#BACDB0` (sage green) accent 사용
- 탭 UI: 하단 보더로 활성 탭 표시
- 복사 버튼: 클릭 시 `navigator.clipboard.writeText()` + 토스트
- 반응형: `@media (max-width: 768px)` 대응

---

## 변경 파일 요약

| 파일 | 변경 |
|------|------|
| `src/api/chain.js` | 신규: 체인 API 래퍼 (Idempotency-Key 자동 생성) |
| `src/pages/WalletPage.jsx` | 신규: 지갑 페이지 (탭 컨테이너) |
| `src/pages/WalletPage.css` | 신규: 지갑 페이지 스타일 |
| `src/components/wallet/WalletTab.jsx` | 신규: 잔액/주소/키 내보내기 |
| `src/components/wallet/AssetsTab.jsx` | 신규: 자산 목록 + 상세 + 마켓 등록 |
| `src/components/wallet/InventoryTab.jsx` | 신규: 인벤토리 조회 |
| `src/components/wallet/MarketTab.jsx` | 신규: 마켓 (구매/취소) |
| `src/components/wallet/WalletSummary.jsx` | 신규: 홈 요약 카드 |
| `src/App.jsx` | 수정: `/wallet` 라우트 + PrivateRoute 추가 |
| `src/pages/HomePage.jsx` | 수정: 헤더 링크 + WalletSummary 추가 |