first

2026-03-31 18:41:52 +08:00
commit 3c62cc1cd1
527 changed files with 96725 additions and 0 deletions
--- a/docs/佣金和钱包.md
+++ b/docs/佣金和钱包.md
@@ -0,0 +1,391 @@
+# 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	备注