221 行
5.0 KiB
Markdown
221 行
5.0 KiB
Markdown
# 收益中心前后端接口约定（身份标签与收益资产）
|
||
|
||
> 注：本模块为「收益中心」。「合伙股东」为独立角色身份之一，创客、酒道馆、区县代理各属于独立角色身份，绝不隶属于合伙股东。
|
||
|
||
## profile `GET user.user/profile` 增补字段
|
||
|
||
```json
|
||
{
|
||
"identity_text": "品酒师",
|
||
"identities": ["taster"],
|
||
"is_partner": false,
|
||
"maker_level_name": "",
|
||
"madow": "0.00000000",
|
||
"madow_rate": "0.00000075",
|
||
"madow_value": "0.00",
|
||
"voucher_available": "0.00",
|
||
"active_30d": true
|
||
}
|
||
```
|
||
|
||
identities 取值：`taster` | `maker` | `venue` | `county` | `partner`
|
||
各身份平行独立：
|
||
- 品酒师：`taster`
|
||
- 创客：`maker`（对应等级如创客V1~V6）
|
||
- 酒道馆：`venue`
|
||
- 区县代理：`county`
|
||
- 合伙股东：`partner`（独立角色身份）
|
||
identity_text 拼接示例：`品酒师` / `创客V5 · 酒道馆` / `合伙股东 · 区县代理`
|
||
|
||
## agent `GET commission.agent` 在原 agent 上增补
|
||
|
||
```json
|
||
{
|
||
"is_venue": 0,
|
||
"is_county": 0,
|
||
"county_code": "",
|
||
"direct_order_seq": 0,
|
||
"madow": "0.00000000",
|
||
"madow_rate": "0.00000075",
|
||
"madow_value": "0.00",
|
||
"voucher_total": "0.00",
|
||
"voucher_released": "0.00",
|
||
"voucher_used": "0.00",
|
||
"voucher_available": "0.00",
|
||
"active_30d": true,
|
||
"last_self_order_time": 0,
|
||
"identities": ["taster"],
|
||
"identity_text": "品酒师",
|
||
"is_partner": false,
|
||
"maker_level_name": ""
|
||
}
|
||
```
|
||
|
||
team 列表里每个 user.agent 同样带 is_venue / is_county / level_info
|
||
|
||
## 新接口前缀 `/addons/shopro/partner.index`
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| GET | partner.index | overview |
|
||
| GET | partner.index/rewards | 分页流水 tab=all\|push3\|maker\|venue\|county\|share |
|
||
| GET | partner.index/madow | dmepa+汇率+日流水 |
|
||
| GET | partner.index/voucher | 券账户+计划列表 |
|
||
|
||
overview:
|
||
|
||
```json
|
||
{
|
||
"month_income": "0.00",
|
||
"skip_count": 0,
|
||
"active_30d": true
|
||
}
|
||
```
|
||
|
||
rewards 列表项:
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"reward_type": "push3",
|
||
"reward_type_text": "推三返一",
|
||
"amount": "398.00",
|
||
"madow": "0.00000000",
|
||
"status": 1,
|
||
"status_text": "已入账",
|
||
"skip_reason": "",
|
||
"skip_reason_text": "",
|
||
"buyer_nickname": "",
|
||
"order_id": 1,
|
||
"createtime": "2026-09-16 10:00:00",
|
||
"formula": ""
|
||
}
|
||
```
|
||
|
||
madow:
|
||
|
||
```json
|
||
{
|
||
"madow": "0.00000000",
|
||
"madow_rate": "0.00000075",
|
||
"madow_value": "0.00",
|
||
"list": []
|
||
}
|
||
```
|
||
|
||
voucher:
|
||
|
||
```json
|
||
{
|
||
"voucher_total": "0.00",
|
||
"voucher_released": "0.00",
|
||
"voucher_used": "0.00",
|
||
"voucher_available": "0.00",
|
||
"plans": []
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 后台财务管理与对账接口 (Admin)
|
||
|
||
### 1. 订单分润透视 `GET shopro/partner/reward/orderTree`
|
||
- **参数**：`order_id`（必填，整数）
|
||
- **返回**：
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"msg": "获取成功",
|
||
"data": {
|
||
"order": {
|
||
"id": 100,
|
||
"order_sn": "202609170001",
|
||
"pay_fee": "1398.00",
|
||
"status_text": "已支付",
|
||
"paid_time": "2026-09-17 12:00:00",
|
||
"buyer_nickname": "测试买家"
|
||
},
|
||
"rewards": [
|
||
{
|
||
"id": 1,
|
||
"reward_type": "push3",
|
||
"reward_type_text": "推三返一",
|
||
"user_id": 10,
|
||
"user_nickname": "推荐人A",
|
||
"role_text": "品酒师",
|
||
"amount": "398.00",
|
||
"madow": "0.00000000",
|
||
"status": 1,
|
||
"status_text": "已入账",
|
||
"formula": "推三返一第1单: 398.00元",
|
||
"createtime": "2026-09-17 12:00:05"
|
||
}
|
||
],
|
||
"summary": {
|
||
"total_cash": "398.00",
|
||
"total_madow": "1398.00000000",
|
||
"payout_ratio": "28.47%"
|
||
},
|
||
"voucher_plan": {
|
||
"total_amount": "2097.00",
|
||
"released_amount": "5.75",
|
||
"released_days": 1,
|
||
"status_text": "释放中"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 日结预跑试算（Dry Run）`GET shopro/partner/daily/preview`
|
||
- **参数**：`settle_date`（可选，默认昨日 `Y-m-d`）
|
||
- **特点**：纯只读模拟试算，不入账、不写表，返回预计支出与综合现金拨比率。
|
||
- **返回**：
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"msg": "试算成功",
|
||
"data": {
|
||
"settle_date": "2026-09-16",
|
||
"is_settled": true,
|
||
"order_count": 10,
|
||
"order_count_n": 100,
|
||
"gmv": "13980.00",
|
||
"rate": "0.00007500",
|
||
"madow": {
|
||
"pool": "13980.00",
|
||
"user_count": 50,
|
||
"each": "279.60000000"
|
||
},
|
||
"venue": {
|
||
"pool": "1000.00",
|
||
"user_count": 5,
|
||
"each": "200.00",
|
||
"saved": "0.00"
|
||
},
|
||
"county": {
|
||
"pool": "500.00",
|
||
"user_count": 2,
|
||
"each": "250.00",
|
||
"saved": "0.00"
|
||
},
|
||
"voucher": {
|
||
"release_estimate": "230.50"
|
||
},
|
||
"financial": {
|
||
"instant_cash": "3980.00",
|
||
"daily_cash": "1500.00",
|
||
"total_cash": "5480.00",
|
||
"saved_cash": "0.00",
|
||
"payout_ratio": "39.2%",
|
||
"payout_ratio_val": 39.2,
|
||
"is_alert": false
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 手工补发带风控上限 `POST shopro/partner/reward/reissue`
|
||
- **参数**：`user_id`, `reward_type`, `amount`, `order_id`, `memo`（必填）
|
||
- **风控硬上限**：单笔补发金额必须 `≤ 10,000` 元。超出报错拦截。
|
||
|