Henglianshutong/docs/partner-api-contract.md

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

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

profile GET user.user/profile 增补字段

{
  "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 上增补

{
  "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:

{
  "month_income": "0.00",
  "skip_count": 0,
  "active_30d": true
}

rewards 列表项:

{
  "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:

{
  "madow": "0.00000000",
  "madow_rate": "0.00000075",
  "madow_value": "0.00",
  "list": []
}

voucher:

{
  "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（必填，整数）
• 返回：

{
  "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）
• 特点：纯只读模拟试算，不入账、不写表，返回预计支出与综合现金拨比率。
• 返回：

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