hailin
/
rwadurian
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
rwadurian/backend/services/wallet-service/docs/API.md

410 lines
9.2 KiB
Markdown
Raw Blame History

# 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'
})
});
```
Reference in New Issue View Git Blame Copy Permalink