# 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	备注