# Wallet Service API 文档

## 概述

本文档描述 Wallet Service 的所有 HTTP API 接口。服务基础路径: `/api/v1`

## 认证

除标注为 `公开` 的接口外，所有接口都需要 JWT Bearer Token 认证：

```http
Authorization: Bearer <jwt_token>
```

JWT Payload 结构：
```json
{
  "sub": "用户ID",
  "seq": 1001,
  "exp": 1700000000
}
```

## 响应格式

### 成功响应

```json
{
  "success": true,
  "data": { ... },
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

### 错误响应

```json
{
  "success": false,
  "code": "ERROR_CODE",
  "message": "错误描述",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

---

## 1. 健康检查

### GET /api/v1/health

检查服务健康状态。

**认证**: 公开

**响应示例**:
```json
{
  "success": true,
  "data": {
    "status": "ok",
    "service": "wallet-service",
    "timestamp": "2024-01-01T00:00:00.000Z"
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

---

## 2. 钱包接口

### GET /api/v1/wallet/my-wallet

查询当前用户的钱包信息。

**认证**: 需要

**响应示例**:
```json
{
  "success": true,
  "data": {
    "walletId": "1",
    "userId": "12345",
    "balances": {
      "usdt": { "available": 1000.5, "frozen": 0 },
      "dst": { "available": 0, "frozen": 0 },
      "bnb": { "available": 0.1, "frozen": 0 },
      "og": { "available": 0, "frozen": 0 },
      "rwad": { "available": 100, "frozen": 0 }
    },
    "hashpower": 500,
    "rewards": {
      "pendingUsdt": 50,
      "pendingHashpower": 100,
      "pendingExpireAt": "2024-01-02T00:00:00.000Z",
      "settleableUsdt": 200,
      "settleableHashpower": 400,
      "settledTotalUsdt": 1000,
      "settledTotalHashpower": 2000,
      "expiredTotalUsdt": 50,
      "expiredTotalHashpower": 100
    },
    "status": "ACTIVE"
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

**字段说明**:

| 字段 | 类型 | 描述 |
|-----|------|-----|
| walletId | string | 钱包ID |
| userId | string | 用户ID |
| balances.{coin}.available | number | 可用余额 |
| balances.{coin}.frozen | number | 冻结余额 |
| hashpower | number | 当前算力 |
| rewards.pendingUsdt | number | 待领取USDT奖励 |
| rewards.pendingHashpower | number | 待领取算力奖励 |
| rewards.pendingExpireAt | string | 待领取奖励过期时间 |
| rewards.settleableUsdt | number | 可结算USDT |
| rewards.settleableHashpower | number | 可结算算力 |
| rewards.settledTotalUsdt | number | 已结算USDT累计 |
| rewards.settledTotalHashpower | number | 已结算算力累计 |
| rewards.expiredTotalUsdt | number | 已过期USDT累计 |
| rewards.expiredTotalHashpower | number | 已过期算力累计 |
| status | string | 钱包状态: ACTIVE, FROZEN |

---

### POST /api/v1/wallet/claim-rewards

领取待领取的奖励，将其转为可结算状态。

**认证**: 需要

**请求体**: 无

**响应示例**:
```json
{
  "success": true,
  "data": {
    "message": "Rewards claimed successfully"
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

**错误码**:

| 错误码 | HTTP状态 | 描述 |
|-------|---------|------|
| NO_PENDING_REWARDS | 400 | 没有待领取的奖励 |
| WALLET_FROZEN | 403 | 钱包已冻结 |

---

### POST /api/v1/wallet/settle

结算可结算的USDT奖励为指定币种。

**认证**: 需要

**请求体**:
```json
{
  "usdtAmount": 100,
  "settleCurrency": "BNB"
}
```

| 字段 | 类型 | 必填 | 描述 |
|-----|------|-----|------|
| usdtAmount | number | 是 | 结算USDT金额 (>0) |
| settleCurrency | string | 是 | 结算目标币种: BNB, USDT, DST, OG, RWAD |

**响应示例**:
```json
{
  "success": true,
  "data": {
    "settlementOrderId": "12345"
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

**错误码**:

| 错误码 | HTTP状态 | 描述 |
|-------|---------|------|
| INSUFFICIENT_BALANCE | 400 | 可结算余额不足 |
| WALLET_FROZEN | 403 | 钱包已冻结 |
| VALIDATION_ERROR | 400 | 参数验证失败 |

---

## 3. 流水接口

### GET /api/v1/wallet/ledger/my-ledger

查询当前用户的账本流水记录。

**认证**: 需要

**查询参数**:

| 参数 | 类型 | 必填 | 默认值 | 描述 |
|-----|------|-----|-------|------|
| page | number | 否 | 1 | 页码 (>=1) |
| pageSize | number | 否 | 20 | 每页数量 (1-100) |
| entryType | string | 否 | - | 流水类型过滤 |
| assetType | string | 否 | - | 资产类型过滤 |
| startDate | string | 否 | - | 开始日期 (ISO8601) |
| endDate | string | 否 | - | 结束日期 (ISO8601) |

**entryType 可选值**:
- `DEPOSIT_KAVA` - KAVA链充值
- `DEPOSIT_BSC` - BSC链充值
- `PLANT_PAYMENT` - 认种支付
- `REWARD_PENDING` - 奖励待领取
- `REWARD_TO_SETTLEABLE` - 奖励转可结算
- `REWARD_SETTLED` - 奖励已结算
- `REWARD_EXPIRED` - 奖励已过期
- `WITHDRAWAL` - 提现
- `ADMIN_ADJUST` - 管理员调整

**assetType 可选值**:
- `USDT`, `DST`, `BNB`, `OG`, `RWAD`, `HASHPOWER`

**响应示例**:
```json
{
  "success": true,
  "data": {
    "data": [
      {
        "id": "1001",
        "entryType": "DEPOSIT_KAVA",
        "amount": 100,
        "assetType": "USDT",
        "balanceAfter": 1100,
        "refOrderId": null,
        "refTxHash": "0x1234...5678",
        "memo": "Deposit from KAVA",
        "createdAt": "2024-01-01T10:00:00.000Z"
      },
      {
        "id": "1002",
        "entryType": "PLANT_PAYMENT",
        "amount": -50,
        "assetType": "USDT",
        "balanceAfter": 1050,
        "refOrderId": "order_123",
        "refTxHash": null,
        "memo": "Plant payment",
        "createdAt": "2024-01-01T11:00:00.000Z"
      }
    ],
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "totalPages": 5
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

**字段说明**:

| 字段 | 类型 | 描述 |
|-----|------|-----|
| id | string | 流水ID |
| entryType | string | 流水类型 |
| amount | number | 金额 (正入账/负支出) |
| assetType | string | 资产类型 |
| balanceAfter | number | 操作后余额 |
| refOrderId | string | 关联订单号 |
| refTxHash | string | 关联交易哈希 |
| memo | string | 备注 |
| createdAt | string | 创建时间 |

---

## 4. 充值接口 (内部服务)

### POST /api/v1/wallet/deposit

处理链上充值确认后的入账。

**认证**: 公开 (仅限内部服务调用)

**请求体**:
```json
{
  "userId": "12345",
  "amount": 100,
  "chainType": "KAVA",
  "txHash": "0x1234567890abcdef..."
}
```

| 字段 | 类型 | 必填 | 描述 |
|-----|------|-----|------|
| userId | string | 是 | 用户ID |
| amount | number | 是 | 充值金额 (>0) |
| chainType | string | 是 | 链类型: KAVA, BSC |
| txHash | string | 是 | 交易哈希 (唯一) |

**响应示例**:
```json
{
  "success": true,
  "data": {
    "message": "Deposit processed successfully"
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

**错误码**:

| 错误码 | HTTP状态 | 描述 |
|-------|---------|------|
| DUPLICATE_TRANSACTION | 409 | 重复交易 (txHash已存在) |
| VALIDATION_ERROR | 400 | 参数验证失败 |

---

## 错误码汇总

| 错误码 | HTTP状态 | 描述 |
|-------|---------|------|
| VALIDATION_ERROR | 400 | 参数验证失败 |
| UNAUTHORIZED | 401 | 未认证 |
| FORBIDDEN | 403 | 无权限 |
| NOT_FOUND | 404 | 资源不存在 |
| DUPLICATE_TRANSACTION | 409 | 重复交易 |
| INSUFFICIENT_BALANCE | 400 | 余额不足 |
| WALLET_FROZEN | 403 | 钱包已冻结 |
| WALLET_NOT_FOUND | 404 | 钱包不存在 |
| NO_PENDING_REWARDS | 400 | 没有待领取的奖励 |
| INTERNAL_ERROR | 500 | 内部错误 |

---

## Swagger 文档

启动服务后访问: `http://localhost:3000/api-docs`

---

## 调用示例

### cURL

```bash
# 获取钱包信息
curl -X GET "http://localhost:3000/api/v1/wallet/my-wallet" \
  -H "Authorization: Bearer <token>"

# 领取奖励
curl -X POST "http://localhost:3000/api/v1/wallet/claim-rewards" \
  -H "Authorization: Bearer <token>"

# 结算奖励
curl -X POST "http://localhost:3000/api/v1/wallet/settle" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"usdtAmount": 100, "settleCurrency": "BNB"}'

# 查询流水
curl -X GET "http://localhost:3000/api/v1/wallet/ledger/my-ledger?page=1&pageSize=10" \
  -H "Authorization: Bearer <token>"

# 充值入账 (内部服务)
curl -X POST "http://localhost:3000/api/v1/wallet/deposit" \
  -H "Content-Type: application/json" \
  -d '{"userId": "12345", "amount": 100, "chainType": "KAVA", "txHash": "0x..."}'
```

### JavaScript (Fetch)

```javascript
// 获取钱包信息
const response = await fetch('/api/v1/wallet/my-wallet', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});
const data = await response.json();

// 结算奖励
const settleResponse = await fetch('/api/v1/wallet/settle', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    usdtAmount: 100,
    settleCurrency: 'BNB'
  })
});
```