# 收益中心前后端接口约定（身份标签与收益资产）

> 注：本模块为「收益中心」。「合伙股东」为独立角色身份之一，创客、酒道馆、区县代理各属于独立角色身份，绝不隶属于合伙股东。

## 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` 元。超出报错拦截。