391 lines
8.8 KiB
Markdown
391 lines
8.8 KiB
Markdown
# 1. 资产钱包概况 (需要新增我的钱包页面, 放到我的钱包里面)
|
||
|
||
## 接口说明
|
||
获取**某个资产（卡 / 设备）的钱包余额信息**。
|
||
⚠️ 企业账号不可调用。
|
||
|
||
- 请求方式：GET
|
||
- 接口地址：`/api/admin/assets/{asset_type}/{id}/wallet`
|
||
- 认证方式：Bearer Token
|
||
|
||
---
|
||
|
||
## 请求参数
|
||
|
||
### Path 参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| asset_type | string | 是 | 资产类型：card / device |
|
||
| id | integer | 是 | 资产ID |
|
||
|
||
---
|
||
|
||
## 返回结构
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"wallet_id": 1,
|
||
"balance": 10000,
|
||
"available_balance": 8000,
|
||
"frozen_balance": 2000,
|
||
"currency": "CNY",
|
||
"status": 1,
|
||
"status_text": "正常",
|
||
"resource_id": 123,
|
||
"resource_type": "iot_card",
|
||
"created_at": "2026-03-31T12:00:00Z",
|
||
"updated_at": "2026-03-31T12:00:00Z"
|
||
},
|
||
"timestamp": "2026-03-31T12:00:00Z"
|
||
}
|
||
```
|
||
|
||
字段说明
|
||
字段 类型 说明
|
||
wallet_id integer 钱包ID
|
||
balance integer 总余额（分）
|
||
available_balance integer 可用余额（分）= 总余额 - 冻结余额
|
||
frozen_balance integer 冻结金额（分）
|
||
currency string 币种（固定 CNY）
|
||
status integer 钱包状态
|
||
status_text string 状态说明
|
||
resource_id integer 资产ID
|
||
resource_type string 资产类型（iot_card / device）
|
||
created_at string 创建时间
|
||
updated_at string 更新时间
|
||
|
||
|
||
# 2. 我的佣金概览 (放到首页)
|
||
|
||
## 接口说明
|
||
获取当前账号的**佣金整体情况**（可提现、冻结、累计等）。
|
||
|
||
- 请求方式：GET
|
||
- 接口地址：`/api/admin/my/commission-summary`
|
||
- 认证方式：Bearer Token
|
||
|
||
---
|
||
|
||
## 请求参数
|
||
无
|
||
|
||
---
|
||
|
||
## 返回结构
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"shop_id": 1,
|
||
"shop_name": "测试店铺",
|
||
"total_commission": 100000,
|
||
"available_commission": 50000,
|
||
"frozen_commission": 10000,
|
||
"unwithdraw_commission": 30000,
|
||
"withdrawing_commission": 10000,
|
||
"withdrawn_commission": 40000
|
||
},
|
||
"timestamp": "2026-03-31T12:00:00Z"
|
||
}
|
||
|
||
```
|
||
|
||
字段说明
|
||
字段 类型 说明
|
||
shop_id integer 店铺ID
|
||
shop_name string 店铺名称
|
||
total_commission integer 累计佣金（分）
|
||
available_commission integer 可提现佣金（分）
|
||
frozen_commission integer 冻结佣金（分）
|
||
unwithdraw_commission integer 未提现佣金（分）
|
||
withdrawing_commission integer 提现中金额（分）
|
||
withdrawn_commission integer 已提现佣金（分）
|
||
|
||
# 3. 我的佣金明细 (放到佣金中心里面)
|
||
|
||
## 接口说明
|
||
获取当前账号的**佣金流水记录**（每一笔赚的钱）。
|
||
|
||
- 请求方式：GET
|
||
- 接口地址：`/api/admin/my/commission-records`
|
||
- 认证方式：Bearer Token
|
||
|
||
---
|
||
|
||
## 请求参数（Query）
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| page | integer | 否 | 页码（默认1） |
|
||
| page_size | integer | 否 | 每页数量（最大100） |
|
||
| commission_source | string | 否 | 佣金来源 |
|
||
| iccid | string | 否 | ICCID（模糊查询） |
|
||
| virtual_no | string | 否 | 设备虚拟号（模糊查询） |
|
||
| order_no | string | 否 | 订单号（模糊查询） |
|
||
|
||
---
|
||
|
||
## 返回结构
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"items": [],
|
||
"page": 1,
|
||
"size": 10,
|
||
"total": 100
|
||
},
|
||
"timestamp": "2026-03-31T12:00:00Z"
|
||
}
|
||
|
||
```
|
||
items 字段说明（佣金记录）
|
||
字段 类型 说明
|
||
id integer 记录ID
|
||
amount integer 佣金金额（分）
|
||
commission_source string 佣金来源
|
||
status integer 状态
|
||
status_name string 状态名称
|
||
order_id integer 订单ID
|
||
shop_id integer 店铺ID
|
||
created_at string 创建时间
|
||
佣金来源说明
|
||
值 含义
|
||
cost_diff 成本价差（赚差价）
|
||
one_time 一次性佣金
|
||
tier_bonus 梯度奖励（已废弃）
|
||
状态说明
|
||
状态 含义
|
||
1 已入账（有效收入）
|
||
2 已失效（不算钱）
|
||
|
||
# 4. 我的佣金统计(放到佣金中心里面)
|
||
|
||
## 接口说明
|
||
按时间范围统计**佣金收入情况**（总收入 + 分类占比）。
|
||
|
||
- 请求方式：GET
|
||
- 接口地址：`/api/admin/my/commission-stats`
|
||
- 认证方式：Bearer Token
|
||
|
||
---
|
||
|
||
## 请求参数（Query）
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| shop_id | integer | 否 | 店铺ID |
|
||
| start_time | string | 否 | 开始时间 |
|
||
| end_time | string | 否 | 结束时间 |
|
||
|
||
---
|
||
|
||
## 返回结构
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"total_amount": 100000,
|
||
"total_count": 50,
|
||
"cost_diff_amount": 60000,
|
||
"cost_diff_count": 30,
|
||
"cost_diff_percent": 600,
|
||
"one_time_amount": 40000,
|
||
"one_time_count": 20,
|
||
"one_time_percent": 400
|
||
},
|
||
"timestamp": "2026-03-31T12:00:00Z"
|
||
}
|
||
```
|
||
|
||
字段说明
|
||
字段 类型 说明
|
||
total_amount integer 总佣金（分）
|
||
total_count integer 总笔数
|
||
cost_diff_amount integer 成本价差收入（分）
|
||
cost_diff_count integer 成本价差笔数
|
||
cost_diff_percent integer 成本价差占比（千分比）
|
||
one_time_amount integer 一次性佣金（分）
|
||
one_time_count integer 一次性佣金笔数
|
||
one_time_percent integer 一次性佣金占比（千分比）
|
||
特别说明
|
||
占比是千分比
|
||
600 = 60%
|
||
400 = 40%
|
||
|
||
# 5. 我的每日佣金统计 (放到首页)
|
||
|
||
## 接口说明
|
||
按天查看**佣金收入趋势**（每天赚了多少）。
|
||
|
||
- 请求方式：GET
|
||
- 接口地址：`/api/admin/my/commission-daily-stats`
|
||
- 认证方式：Bearer Token
|
||
|
||
---
|
||
|
||
## 请求参数（Query）
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| shop_id | integer | 否 | 店铺ID |
|
||
| start_date | string | 否 | 开始日期（YYYY-MM-DD） |
|
||
| end_date | string | 否 | 结束日期（YYYY-MM-DD） |
|
||
| days | integer | 否 | 查询天数（默认30，最大365） |
|
||
|
||
---
|
||
|
||
## 返回结构
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": [
|
||
{
|
||
"date": "2026-03-01",
|
||
"total_amount": 1000,
|
||
"total_count": 5
|
||
},
|
||
{
|
||
"date": "2026-03-02",
|
||
"total_amount": 2000,
|
||
"total_count": 8
|
||
}
|
||
],
|
||
"timestamp": "2026-03-31T12:00:00Z"
|
||
}
|
||
```
|
||
字段说明
|
||
字段 类型 说明
|
||
date string 日期
|
||
total_amount integer 当日佣金（分）
|
||
total_count integer 当日笔数
|
||
使用场景
|
||
做折线图（收入趋势）
|
||
看哪天赚钱最多
|
||
分析增长情况
|
||
|
||
# 6. 发起提现申请 (放到提现管理里面)
|
||
|
||
## 接口说明
|
||
提交**佣金提现申请**（目前只支持支付宝）。
|
||
|
||
- 请求方式：POST
|
||
- 接口地址：`/api/admin/my/withdrawal-requests`
|
||
- 认证方式：Bearer Token
|
||
|
||
---
|
||
|
||
## 请求参数（Body）
|
||
|
||
```json
|
||
{
|
||
"account_name": "张三",
|
||
"account_number": "1234567890",
|
||
"amount": 10000,
|
||
"withdrawal_method": "alipay"
|
||
}
|
||
参数说明
|
||
参数名 类型 必填 说明
|
||
account_name string 是 收款人姓名
|
||
account_number string 是 收款账号（支付宝）
|
||
amount integer 是 提现金额（分）
|
||
withdrawal_method string 是 提现方式（固定：alipay）
|
||
返回结构
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": 1,
|
||
"withdrawal_no": "WD202603310001",
|
||
"amount": 10000,
|
||
"actual_amount": 9800,
|
||
"fee": 200,
|
||
"fee_rate": 200,
|
||
"status": 1,
|
||
"status_name": "审核中",
|
||
"created_at": "2026-03-31T12:00:00Z"
|
||
},
|
||
"timestamp": "2026-03-31T12:00:00Z"
|
||
}
|
||
```
|
||
字段说明
|
||
字段 类型 说明
|
||
id integer 提现申请ID
|
||
withdrawal_no string 提现单号
|
||
amount integer 申请金额（分）
|
||
actual_amount integer 实际到账金额（分）
|
||
fee integer 手续费（分）
|
||
fee_rate integer 手续费率（基点）
|
||
status integer 状态
|
||
status_name string 状态名称
|
||
created_at string 申请时间
|
||
状态说明（常见）
|
||
状态 含义
|
||
1 审核中
|
||
2 已打款
|
||
3 已拒绝
|
||
计算说明
|
||
实际到账 = 提现金额 - 手续费
|
||
手续费 = amount × fee_rate
|
||
|
||
# 7. 我的提现记录(放到提现管理里面)
|
||
接口信息
|
||
接口地址：GET /api/admin/my/withdrawal-requests
|
||
接口说明：获取当前用户的提现记录列表
|
||
认证方式：Bearer Token
|
||
请求参数
|
||
参数名 类型 必填 说明
|
||
page integer 否 页码（>=1）
|
||
page_size integer 否 每页数量（1-100）
|
||
status integer 否 状态（1=待审批，2=已通过，3=已拒绝）
|
||
start_time string 否 开始时间
|
||
end_time string 否 结束时间
|
||
响应结构
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2024-01-01T00:00:00Z",
|
||
"data": {
|
||
"items": [],
|
||
"page": 1,
|
||
"size": 10,
|
||
"total": 100
|
||
}
|
||
}
|
||
data 字段说明
|
||
字段 类型 说明
|
||
items array 提现列表
|
||
page integer 当前页
|
||
size integer 每页数量
|
||
total integer 总数
|
||
items 字段说明
|
||
字段 说明
|
||
id 提现ID
|
||
withdrawal_no 提现单号
|
||
applicant_name 申请人
|
||
amount 提现金额（分）
|
||
actual_amount 实际到账（分）
|
||
fee 手续费
|
||
fee_rate 手续费率
|
||
status 状态（1待审 2通过 3拒绝 4到账）
|
||
status_name 状态名称
|
||
withdrawal_method 提现方式（支付宝/微信/银行卡）
|
||
account_name 收款人
|
||
account_number 收款账号
|
||
bank_name 银行
|
||
created_at 申请时间
|
||
processed_at 处理时间
|
||
reject_reason 拒绝原因
|
||
remark 备注 |