落地合伙股东收益体系,并纳入 sheep 用户端源码。

Co-authored-by: Cursor <cursoragent@cursor.com>
这个提交包含在:
chen
2026-09-17 07:47:35 +08:00
父节点 7747dfaa82
当前提交 251d62296e
共有 595 个文件被更改,包括 90234 次插入 和 105 次删除

109
docs/partner-api-contract.md 普通文件
查看文件

@@ -0,0 +1,109 @@
# 合伙股东前后端接口约定(两代理必须遵守)
## 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`
is_partner = 含 maker 或 venue 或 county
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 | 马豆+汇率+日流水 |
| 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": []
}
```

查看文件

@@ -0,0 +1,727 @@
# 合伙股东 · 后台与用户端功能规格
> 版本:V1.0
> 对应技术方案:`docs/合伙股东收益体系二次开发文档.md` V2.1
> 角色视角:产品经理(页面 / 字段 / 状态 / 文案)+ 全栈(改哪些现有页、接口怎么扩)
> 原则:能改现有页就改,不新造第二套会员中心;用户能看懂「我是谁、我拿了什么、为什么没拿到」
---
## 1. 产品目标与角色
### 1.1 后台服务谁
| 角色 | 他要完成的事 |
|---|---|
| 运营 | 开通酒道馆/区县、改创客等级、查一笔订单钱分给了谁 |
| 财务 | 按日对账:GMV、发放合计、均分、马豆、兑换券;导出 |
| 客服 | 用户说「我没收到钱」时,3 分钟内看到原因(不活跃 / 无上级 / 已退款) |
| 超管 | 改规则数字(级差 20、均分 100),改完只影响新单 |
### 1.2 用户端服务谁
| 身份 | 他打开 App 要立刻看到 |
|---|---|
| 品酒师 | 我是品酒师;直推满 3 单返一圈钱;我的兑换券还剩多少天 |
| 创客 V1–V6 | 合伙股东徽章 + 等级;极差/平级进佣金 |
| 酒道馆 / 区县 | 多一枚身份标;团队奖和平台均分能分开看 |
| 所有人 | 30 天没下单时,收益页明确写「本月无自购,暂停发放」 |
### 1.3 本期不做(避免范围膨胀)
- 不重做装修编辑器,个人中心继续走现有 `userCard` / `walletCard` 组件。
- 不把马豆做成可交易市场。
- 不给用户自助申请酒道馆/区县(先后台开通)。
- 不改原生三级分销订单的百分比展示逻辑到「完全删除」,只停发新百分比。
---
## 2. 后台信息架构
在现有「商城 → 分销中心」下扩展,不另起顶级菜单(运营已经认这条路径)。
```
商城
└─ 分销中心 已有,保留
├─ 分销商 改:身份列、筛选、编辑弹窗
├─ 分销商等级 改:文案 + 级差基数
├─ 分销订单 保留(业绩/升级仍用)
├─ 佣金 保留(旧百分比历史)
├─ 分销动态 保留
├─ 分销商品 改:说明「是否参与合伙股东计奖」
├─ 收益流水 【新】
├─ 日结对账 【新】
└─ 兑换券计划 【新】
商城 → 配置 → 分销设置
└─ 增加 Tab「合伙股东规则」
```
权限节点(写入 `addons/shopro/config/menu.php`,升级菜单):
| 节点 | 谁用 |
|---|---|
| `shopro/partner/reward/index` `export` `reissue` `back` | 运营/财务 |
| `shopro/partner/daily/index` `rerun` | 财务 |
| `shopro/partner/voucher/index` | 客服 |
| `shopro/config/commission`(已有,扩字段) | 超管 |
| `shopro/commission/agent/edit`(已有,扩字段) | 运营 |
---
## 3. 后台:改现有页
### 3.1 分销设置 · 新增 Tab「合伙股东」
**现有:** `application/admin/view/shopro/config/index.html` + `public/assets/js/backend/shopro/config.js` 已有分销 Tab。
**处理:** 同一页加第三个分组,保存进 `shop.commission.partner.*`,不要新菜单。
| 区块 | 字段 | 控件 | 默认 | 校验 / 说明文案 |
|---|---|---|---|---|
| 总控 | 启用合伙股东结算 | 开关 | 开 | 关闭后新单不再记即时奖,旧流水不动 |
| 总控 | 关闭旧百分比分佣 | 开关 `partner_mode` | 开 | 旁注:不要把「分销层级」改成 0,否则用户端收益中心打不开 |
| 计单 | 合格订单口径 | 单选 | 订单头 | 选项:订单头 / 商品件数 |
| 活跃 | 领取窗口天数 | 数字 | 30 | ≥1 |
| 推三返一 | 循环金额 | 三个数字框 | 398 / 400 / 600 | 旁注:三者之和建议等于主售价 |
| 马豆 | 发放模式 | 单选 | 马豆 | 马豆 / 现金(现金需二次确认弹窗:将发放当日 GMV) |
| 马豆 | 基础汇率 | 数字 | 0.00000075 | 最多 10 位小数 |
| 马豆 | 步进订单数 n | 数字 | 1 | 每增加 n 单,汇率 = 基数 × floor(N/n) |
| 兑换券 | 倍数 | 数字 | 1.5 | |
| 兑换券 | 释放天数 | 数字 | 365 | |
| 创客 | V1–V6 单笔基数 | 6 个数字 | 20…120 | 必须递增 |
| 创客 | 平级比例 | 数字 | 10% | |
| 创客 | 被超越比例 | 数字 | 5% | |
| 团队拆分 | 总额 / 酒道馆份额 / 无馆区县全额 | 数字 | 100 / 50 / 100 | 酒道馆份额 ≤ 总额 |
| 均分 | 酒道馆每单奖池 | 数字 | 100 | |
| 均分 | 区县每单奖池 | 数字 | 50 | |
| 平级 | 酒道馆/区县平级比例 | 数字 | 10% / 10% | |
保存成功 Toast:「规则已更新,仅对之后的新订单生效。」
保存失败:字段红字,不整页刷新。
### 3.2 分销商列表(运营每天打开的页)
**现有文件:**
`application/admin/view/shopro/commission/agent/index.html`
`public/assets/js/backend/shopro/commission/agent.js`
**现有列:** ID、用户、等级、累计佣金、消费、自购业绩、上级、一级人数、创建时间、状态。
**要加的列(插在「等级」后):**
| 列 | 展示 |
|---|---|
| 身份 | `品酒师` 或 `创客V5`;后面小标签 `酒道馆` `区县`(可多个) |
| 30 日活跃 | 绿点「有自购」/ 灰点「已暂停」 |
| 马豆 | 数量,副文案约合 ¥xx(按最新汇率) |
| 可用兑换券 | `released - used` |
**要加的筛选(现有 filter drawer):**
- 身份:品酒师 / 创客 / 酒道馆 / 区县(可多选)
- 创客等级:V1–V6
- 30 日活跃:是 / 否
- 区县编码
**行操作(在现有「详情 / 团队」旁):**
- 开通身份(弹窗,见 3.4)
- 无需新「删除」
列表接口:现有 `shopro/commission/agent/index` 的 with 里带出新字段即可,前端 `el-table-column` 加列。
### 3.3 分销商详情(客服查人)
**现有:** `agent/detail.html` 已有等级、升级锁、一二三级比例、团队统计。
**改:**
1. 「等级佣金比例」三块(commission_1/2/3)在 `partner_mode` 下改成展示文案:「已切换为合伙股东固定金额,旧百分比不再生效。」仍可折叠看历史配置。
2. 新增卡片「合伙股东资产」:
| 字段 | 只读 |
|---|---|
| 身份组合 | 创客V5 · 酒道馆 |
| 最近自购时间 | 2026-09-10 12:00 / 从未下单 |
| 活跃状态 | 正常领取 / 已暂停(距今天数) |
| 直推计奖序号 | 第 14 单,下一单将返 400 |
| 马豆 / 约合 | |
| 兑换券 总额 / 已释放 / 已使用 / 可用 | |
| 累计合伙股东现金收益 | 从 `partner_reward` 已入账求和 |
3. 新增 Tab 或按钮「TA 的收益流水」:跳到收益流水页并带 `user_id`。
4. 新增按钮「手工补发 / 扣回」(权限 `reissue`),打开 4.1 的弹窗并预填用户。
### 3.4 开通 / 调整身份(核心运营动作)
挂在现有 `shopro/commission/agent/edit` 上扩展 POST 字段,不要新控制器。
弹窗字段:
| 字段 | 控件 | 规则 |
|---|---|---|
| 创客等级 | 下拉:品酒师(1) / V1(2)…V6(7) | 选品酒师则 `is_taster` 逻辑自动成立;选 Vn 则不再是品酒师 |
| 酒道馆 | 开关 | 可与创客同时开 |
| 区县代理 | 开关 | 开时必选区县(复用 `shopro/data/area`) |
| 升级锁定 | 沿用现有 `upgrade_lock` | 打开后自动升级不跑 |
| 备注 | 文本 | 写入分销动态 |
提交校验:
- 不能出现「无 agent 行」——没有则先 `createNewAgent` 再改级。
- 改等级写 `shopro_commission_log` event=`level`。
- 改酒道馆/区县写 log event=`identity`(`Log.php` 补一种文案)。
二次确认文案:
> 将「张三」从 品酒师 调整为 创客V3 + 酒道馆。已入账收益不追溯。确定?
### 3.5 分销商等级页
**现有:** 权重、名称、徽章、百分比、升级条件。
**改:**
- 页面顶警告改为:「等级 1 固定为品酒师;2–7 对应创客 V1–V6。百分比佣金在合伙股东模式下不使用。」
- 增加只读映射表:level → 单笔极差基数(读配置 `maker_bonus`,点「去规则里改」跳设置 Tab)。
- 升级条件原样保留:运营可配「直推满 N 人升 V2」等,走现成 `agentUpgrade` 队列。
- 初始化数据:上线脚本插入 7 条等级(若库里已有旧等级,提供「迁移说明」:把旧 level=1 改名为品酒师,新增 2–7)。
### 3.6 分销商品
**现有:** 是否参与分销。
**改文案:** 「参与分销 / 合伙股东计奖」。
关闭的商品:不计入推三返一、极差、拆分、均分、马豆 N、兑换券。
不改表结构。
### 3.7 会员详情(`shopro/user/user`)
用户详情若已展示 `commission` 钱包,加三个只读:马豆、可用兑换券、身份文本。
入口:从用户跳到分销商详情(已有 agent 关联则跳,没有则提示「尚未生成分销身份」)。
---
## 4. 后台:三张新页
三页都复制 `commission/reward` 的骨架:顶筛 + 表 + 导出 + 分页。
### 4.1 收益流水 `shopro/partner/reward`
**谁用:** 客服 / 财务每天。
**筛选项:**
- 用户(ID/昵称/手机,复用 `sa-filter` tinputprepend)
- 买家
- 订单号
- 奖项类型(下拉,中文)
- 角色(品酒师/创客/酒道馆/区县)
- 状态:待入账 / 已入账 / 已取消 / 已退回
- 时间范围
- 日结日期(查均分/马豆)
**表列:**
ID、入账时间、受益人、买家、订单、奖项、角色、金额、马豆、基数、状态、公式摘要(`ext.formula`)、操作
**奖项中文:**
| code | 后台 / 用户端统一文案 |
|---|---|
| push3 | 推三返一 |
| maker_diff | 创客极差奖 |
| maker_peer | 创客平级奖 |
| maker_overtaken | 创客超越奖 |
| team_venue | 酒道馆团队奖 |
| team_county | 区县团队奖 |
| venue_peer | 酒道馆平级奖 |
| county_peer | 区县平级奖 |
| venue_share | 酒道馆平台均分 |
| county_share | 区县平台均分 |
| madow_share | 每日分红马豆 |
| voucher_grant | 兑换券发放 |
| voucher_release | 兑换券释放 |
**行操作:**
- 查看公式:弹窗展示 `ext`(链上有谁、为什么跳过谁、水位 seen)。
- 退回:仅 `status=1` 且非日结;走 `Wallet reward_back`;填原因。
- 整单退回:按 `order_id` 批量(售后已自动退的禁用此按钮)。
**顶栏按钮「手工补发」:**
- 选用户、奖项、金额、关联订单(可选)、备注。
- `reward_type` 用 `manual_*`,写入流水,进佣金钱包。
- 必填备注,导出打标「手工」。
**导出:** 与现有佣金导出同一套 `sheepFilter + export`,最后一行合计金额、马豆。
**空态:** 「没有符合条件的流水」。
**客服标准问法对应筛法:** 用户手机号 + 昨天 → 看有没有 `push3` 以及 `ext.skip_reason`。
`ext.skip_reason` 枚举(后台和用户端同一套):
| code | 对内 | 对用户(收益明细旁注) |
|---|---|---|
| no_parent | 无直推上级 | 暂无推荐人,不产生推三返一 |
| self_buy | 自购 | 自己下单不产生推三返一 |
| inactive_30d | 受益人 30 日无自购 | 需 30 日内有本人订单才能领取 |
| not_maker | 不是创客 | — |
| not_venue | 不是酒道馆 | — |
| cap_not_higher | 等级未超过水位 | 平级不发极差,走平级奖 |
| already_settled | 幂等跳过 | — |
| partner_goods_off | 商品未参与 | — |
跳过记录也要落库(`status=-1`,金额 0),否则客服查不到「为什么没有」。
**产品决策:每笔订单对每个「候选受益人」写一条,包含 skip。** 列表默认过滤金额=0,勾选「显示未发放原因」才出现。
### 4.2 日结对账 `shopro/partner/daily`
**一行 = 一个自然日。**
列:日期、合格单数、GMV、汇率 N、汇率、马豆池、马豆人数、酒道馆奖池、酒道馆人数、区县奖池、区县人数、兑换券释放总额、状态(成功/失败/重跑中)、操作。
操作:
- 明细:下钻到当天 `venue_share` / `county_share` / `madow_share` / `voucher_release`。
- 重跑:权限 `rerun`,二次确认「将删除当天日结流水后重算」。即时奖(推三返一等)不重跑。
- 失败行红字,展示 `error_msg`(锁冲突、分母为 0 已进平台账户 不算失败)。
页顶 KPI 卡(今日/昨日):单数、GMV、现金发放合计、马豆发放、暂停领取人数。
### 4.3 兑换券计划 `shopro/partner/voucher`
列:用户、订单、总额、每天释放、已释放天数、已释放金额、已使用、可用、开始日、状态(释放中/完成/已关闭)。
操作:查看按日释放日志;关闭计划(退款时自动关,后台也可手工关,未释放清零)。
---
## 5. 后台操作手册(给运营的任务流)
### 5.1 上线当天
1. 跑 SQL,插入 7 条等级。
2. 分销设置:成为分销商 = 注册即是;关掉申请表单;打开合伙股东结算。
3. 用测试号 A 推荐 B,B 下一单,A 应到账 398。
4. 后台把 A 调成创客 V5 + 酒道馆,再让 C 在 B 下面下单,核对拆账。
### 5.2 开通一个酒道馆
分销商列表搜手机号 → 开通身份 → 开酒道馆 → 写备注「2026-09 签约」→ 保存。
用户端下次进收益中心即多一枚「酒道馆」。无需用户申请。
### 5.3 「我怎么没收到均分」
日结对账看昨天分母是否包含该用户 → 详情看 `last_self_order_time` → 超过 30 天则告知「先下一单,明天恢复」。
不要手工补均分,除非财务签字走「手工补发」。
### 5.4 改级差金额
规则 Tab 改 V5=120。已产生的流水不改。新订单按 120。
页面必须写死这句,防止运营以为能追溯。
---
## 6. 用户端信息架构
```
我的(装修页,改两个组件即可全站生效)
├─ 用户卡片 身份徽章
└─ 钱包卡片 余额 / 佣金 / 马豆 / 兑换券
收益中心(原分销中心改名)
├─ 身份条
├─ 资产四宫格(佣金、马豆价值、可用券、本月是否可领)
├─ 功能:团队、佣金明细、收益明细、马豆、兑换券、分享、(资料按配置藏)
└─ 实时动态(沿用 commission.log,补新文案)
佣金钱包(已有) 只承载现金,含新 event 中文
确认订单(后期) 加兑换券抵扣
```
底部 Tab、装修页路径都不改。收益中心入口继续用装修「菜单」指到 `/pages/commission/index`,只改页内标题。
---
## 7. 用户端:改现有组件 / 页面
### 7.1 我的 · 用户卡片
**文件:** `uniapp/sheep/components/s-user-card/s-user-card.vue`
**数据:** `userInfo.identity_text` / `userInfo.identities`(来自 `profile`,见技术方案 9.2)
**未登录:** 保持「请先登录」,无徽章。
**登录后,昵称下方:**
```
张三
[品酒师]
```
或
```
张三
[合伙股东] [创客V5] [酒道馆]
```
规则:
- 仅品酒师:一枚灰/棕标签「品酒师」。
- `is_partner`:先一枚主标「合伙股东」,再跟创客等级、酒道馆、区县。
- 最多一行,超出换行不撑破头像区。
- 点击徽章 → `/pages/commission/index`(未登录走登录)。
**空 / 接口还没扩字段:** 不显示徽章,不能白屏。
### 7.2 我的 · 钱包卡片
**文件:** `uniapp/sheep/components/s-wallet-card/s-wallet-card.vue`
**现状:** 余额、积分、优惠券、我的钱包;佣金 DOM 被注释。
**改成 5 项(可滑动或两行,避免挤爆):**
| 项 | 数字 | 跳转 |
|---|---|---|
| 余额 | `userInfo.money` | 已有 `/pages/user/wallet/money` |
| 收益 | `userInfo.commission` | `/pages/user/wallet/commission` |
| 马豆 | `userInfo.madow` 副文案约 ¥ | `/pages/commission/madow` |
| 兑换券 | `userInfo.voucher_available` 元 | `/pages/commission/voucher` |
| 优惠券 | `numData.coupons_num` 张 | 已有领券(Shopro 券,保留) |
文案用「收益」不写「佣金」,和业务口吻一致;佣金页标题可改为「我的收益」。
积分可收到第二行或保持,由视觉定,功能不能删。
### 7.3 收益中心首页
**文件:** `uniapp/pages/commission/index.vue`
标题:`分销中心` → `收益中心`(`pages.json` 同步)。
组件改动:
| 组件 | 处理 |
|---|---|
| `commission-info` | 多徽章,见 7.4 |
| `account-info` | 四指标,见 7.5 |
| `commission-menu` | 菜单改写,见 7.6 |
| `commission-log` | 继续拉 `commission.log`;后端把新收益写成 remark |
| `commission-auth` | 不动。注册即分销商后不应再 100 |
| `commission-condition` | 不动。作为兜底 |
顶栏若 30 日未自购,在账户卡上方插一条警示:
> 近 30 日暂无本人订单,推广与分红已暂停。下单后次日恢复领取。
按钮:「去选购」→ 首页或指定分类。
### 7.4 身份条 `commission-info.vue`
现有只渲染一个 `level_info`。改为:
```
头像 昵称
[创客V5图+名] [酒道馆] [区县代理]
```
`level_info` 继续用后台等级徽章图(品酒师/创客)。
酒道馆、区县用纯色小标即可,不必新切图(可后续换)。
右侧箭头可去「我的信息」,或取消点击。
### 7.5 账户卡 `account-info.vue`
现有三列:总收益 / 我的佣金 / 我的消费。
改为四列(两行也行):
| 指标 | 字段 | 点进去 |
|---|---|---|
| 累计收益 | `agentInfo.total_income` | 佣金钱包 |
| 可提现 | `userInfo.commission` | 佣金钱包 |
| 马豆价值 | `agentInfo.madow_value` | 马豆页 |
| 可用兑换券 | `agentInfo.voucher_available` | 兑换券页 |
「查看明细」继续去佣金钱包。
眼睛按钮沿用。
### 7.6 功能菜单 `commission-menu.vue`
重排(8 宫格内):
| 项 | 路径 | 显示条件 |
|---|---|---|
| 我的团队 | `/pages/commission/team` | 始终 |
| 收益明细 | `/pages/commission/rewards` | 始终 |
| 我的收益 | `/pages/user/wallet/commission` | 始终(原「佣金明细」改名) |
| 我的马豆 | `/pages/commission/madow` | 始终 |
| 兑换券 | `/pages/commission/voucher` | 始终 |
| 推广订单 | `/pages/commission/order` | 始终(原分销订单,看团队单数) |
| 邀请海报 | `action:showShareModal` | 始终 |
| 分享记录 | `/pages/commission/share-log` | 始终 |
| 我的资料 | `/pages/commission/apply` | 仅 `agent_form` 开启时 |
| 推广商品 | `/pages/commission/goods` | 可隐藏;partner 模式建议菜单去掉,避免再讲百分比 |
### 7.7 我的团队 `team.vue`
列表右侧现有 `level_info.name`。追加:
```
[创客V3] [馆] [县]
直推 3 人
```
`filterUserNum` 文案「直推 x 人」可保留。
顶上「团队分销商人数」改文案为「团队合伙股东人数」可选,避免一次改太多;若改,一级/二级同步改「一级成员」。
数据:`GET commission.agent/team` 已 with agent,后端 agent 加 `is_venue` `is_county` 即可,前端加两个 `v-if`。
### 7.8 佣金钱包 `wallet/commission.vue`
- 导航标题改为「我的收益」。
- 卡片「我的佣金」改为「可提现收益」。
- 流水 `event_text` 由后端 WalletLog 新枚举提供,前端不用映射表。
- 提现、转余额流程不动。
- 页底加一句:「马豆与兑换券不在本页,请到收益中心查看。」避免用户以为没到账。
### 7.9 推广订单 `order.vue`
仍展示团队单数、金额(升级业绩)。
每条上的 `rewards[0].commission` 在停百分比后可能为 0。
处理:若 `item.partner_amount` 有值则显示「本单收益 ¥xx」,否则隐藏佣金数字,只保留订单状态。
后端 `commission.order` 列表附带该订单当前用户的 `partner_reward` 合计。
---
## 8. 用户端:三张新页
都放在 `pages/commission` 分包,`pages.json` 的 commission root 下加 path。
视觉跟 `wallet/commission.vue`:顶卡 + sticky 筛选 + 列表。
### 8.1 收益明细 `/pages/commission/rewards`
**顶卡:** 本月已入账现金、本月未发放(skip)笔数。
**Tab:** 全部 / 推三返一 / 创客 / 酒道馆 / 区县 / 均分。
**列表行:**
```
推三返一 +398.00
来自 李四 · 订单 20260916xxxx
2026-09-16 10:21
```
点行出半屏:公式(第几单、循环第几档)、若未发放则显示用户文案(见 4.1 表)。
**空态:** 「暂无收益记录,邀请好友下单后将在此展示。」
**下拉刷新 + 上拉分页**,对齐现有 `commission-log`。
接口:`GET partner.index/rewards?tab=&page=`
### 8.2 我的马豆 `/pages/commission/madow`
**顶卡:**
- 大号:马豆数量
- 副文案:当前汇率 `1 马豆 = 0.00000075 元`;约合 ¥x.xx
- 说明折叠:「汇率随全平台订单增加而上浮,仅作价值展示,不可提现。」
**列表:** 每日 `madow_share`(日期、获得马豆、当日人数、当日 GMV)。
**空态:** 「完成一笔订单后,次日 00:30 起参与分红。」
接口:`GET partner.index/madow`
### 8.3 兑换券 `/pages/commission/voucher`
**顶卡四格:** 累计获得 / 已释放 / 已使用 / 可用。
**进度:** 「第 28 / 365 天」按进行中计划的最大进度,或多计划列表。
**计划列表每条:**
```
订单 2026xxxx 总额 2097
已释放 161.00 · 可用 80.00 · 已用 81.00
████░░░░ 28/365
```
**按钮「去兑换」:** 跳商品列表(可带 `?voucher=1` 或装修指定页)。P4 前可先跳首页。
**空态:** 「下单后将获得 1.5 倍兑换券,分 365 天释放。」
接口:`GET partner.index/voucher`
---
## 9. 用户端 · 下单抵扣(P4)
**页:** `uniapp/pages/order/confirm.vue`
在优惠券行下面加一行:
```
兑换券 可用 ¥209.00 抵扣 ¥50 >
```
半屏:数字输入,最大 = min(可用兑换券, 商品应付-其他优惠)。
`orderPayload.voucher_fee` 传给 `order.order/calc` 与 `create`。
后端 `OrderCreate`:
- 校验 `voucher_available >= voucher_fee`
- 实付减少
- 支付成功再扣 `voucher_used`(防下单失败先扣)
- 与 Shopro 优惠券可叠加,顺序:先商城券,再兑换券(写进 calc 说明,避免客服争议)
失败提示:「兑换券可用额度不足」。
---
## 10. 用户端文案与状态机
### 10.1 收益中心进入
```
打开 /pages/commission/index
→ getInfo + getAgentInfo
→ code=1:正常
→ code=100:还不是分销商(注册即品酒师后不应出现)
→ code=101:分销关闭(配置错误,研发处理)
→ code=102/107:禁用/冻结,沿用现有弹窗
```
### 10.2 30 日暂停
全收益页共用一条 `userInfo.active_30d === false`。
不隐藏菜单,只是顶警示 + 明细里新单显示「未发放」。
用户下单支付成功后,`last_self_order_time` 更新,当次领取资格立即恢复(即时奖按支付时刻判断,不是按日切)。
### 10.3 通知(可 P5)
复用 Shopro 通知,钱包变动已有 `user_wallet_change`。
新 event 进 WalletLog 后,若已订阅佣金到账模板,会自动带「推三返一」文案。
马豆、兑换券释放默认不推送(避免每天 00:30 骚扰),收益中心自己看。
---
## 11. 接口与字段对照(前后台同一份)
### 11.1 `GET user.user/profile` 增补
给「我的」用,必须有,否则徽章出不来。
```json
{
"identity_text": "合伙股东 · 创客V5 · 酒道馆",
"identities": ["maker", "venue"],
"is_partner": true,
"maker_level_name": "创客V5",
"madow": "12.50000000",
"madow_rate": "0.00000750",
"madow_value": "0.00",
"voucher_available": "80.00",
"active_30d": true
}
```
`uniapp/sheep/store/user.js` 的 `defaultUserInfo` 同步这些键,默认空字符串 / false,避免 undefined。
### 11.2 `GET commission.agent` 增补
给收益中心用,字段比 profile 更全:`direct_order_seq`、`last_self_order_time`、`voucher_total/released/used`、`is_venue`、`is_county`。
### 11.3 新 API `sheep/api/partner.js`
```js
export default {
overview: () => request({ url: 'partner.index' }),
rewards: (params) => request({ url: 'partner.index/rewards', params }),
madow: (params) => request({ url: 'partner.index/madow', params }),
voucher: (params) => request({ url: 'partner.index/voucher', params }),
};
```
在 `sheep/api/index.js` 挂上 `partner`。
---
## 12. 装修与入口(产品要交代运营)
个人中心是装修出来的。上线后运营在 **店铺装修 → 用户中心**:
1. 确认有「用户卡片」「钱包卡片」(改组件后自动变)。
2. 菜单组加一项「收益中心」→ `/pages/commission/index`(若还没有)。
3. 不要再放「申请分销商」当主入口。
首页分享海报沿用现有,分享仍写 `share` 记录,关系链不改。
---
## 13. 开发任务拆分(可直接排期)
### 后台(本仓库 admin)
| ID | 任务 | 改动文件 | 验收 |
|---|---|---|---|
| A1 | 规则 Tab | `config/index.html` `config.js` | 保存后 `sheep_config` 能读到 |
| A2 | 分销商列表列+筛 | `agent/index.html` `agent.js` | 能筛酒道馆、看活跃点 |
| A3 | 身份编辑弹窗 | `Agent.php::edit` + detail | 品酒师↔创客互斥,馆/县可叠 |
| A4 | 详情资产卡 | `agent/detail.html` | 客服能看到序号和下次返现金额 |
| A5 | 等级页文案+种子数据 | `level/add.html` + SQL | 7 条等级 |
| A6 | 收益流水页 | 新 controller/view/js | 导出、补发、看 skip |
| A7 | 日结页 | 新 | 重跑昨天 |
| A8 | 兑换券计划页 | 新 | 看 365 进度 |
| A9 | 菜单权限 | `menu.php` + 升级 | 角色能分开赋权 |
| A10 | 商品文案 | `commission/goods` | 运营理解「关了不计奖」 |
### 用户端(`uniapp/`)
| ID | 任务 | 文件 | 验收 |
|---|---|---|---|
| U1 | store + api | `user.js` `api/partner.js` `api/index.js` | profile 有徽章字段不报错 |
| U2 | 用户卡片徽章 | `s-user-card.vue` | 我的页能看到品酒师/合伙股东 |
| U3 | 钱包五项 | `s-wallet-card.vue` | 能进收益/马豆/券 |
| U4 | 收益中心改名与警示 | `commission/index.vue` `pages.json` | 30 日无单有黄条 |
| U5 | 身份条/账户卡/菜单 | 三个 components | 馆/县标、四指标、新菜单 |
| U6 | 团队标 | `team.vue` | 直推能看出身份 |
| U7 | 收益明细页 | `rewards.vue` + pages.json | 分页、skip 文案 |
| U8 | 马豆页 | `madow.vue` | 汇率+约合 |
| U9 | 兑换券页 | `voucher.vue` | 进度条 |
| U10 | 佣金钱包文案 | `wallet/commission.vue` | 标题「我的收益」 |
| U11 | 推广订单附带本单收益 | `order.vue` + 后端 order 列表 | 停百分比后不是处处 0 |
| U12 | 下单抵扣 | `confirm.vue` + OrderCreate | 可用券能减实付 |
| U13 | 隐藏申请/推广商品 | menu 条件 | 配置关申请后不露入口 |
建议顺序:A1→A3→后端 P0 接口→U1 U2 U3(用户先看见身份)→A6 U7(能对账)→其余。
---
## 14. 联调验收剧本(产品和测试共用)
准备账号:平台、品酒师 A、创客V5 B、创客V5 C、酒道馆+V6 D、区县 E。关系 A←B←C←买家X,D、E 在更上。
| 步骤 | 后台看 | 用户端看 |
|---|---|---|
| 1 注册 X,A 分享 | X 为品酒师,上级 A | X「我的」徽章品酒师 |
| 2 X 下首单 1398 | A 流水 push3=398;X 有券计划 2097 | A 收益 +398;X 兑换券总额 2097、已释放 0 |
| 3 把 B 调成 V5 | 身份列变化 | B 徽章变合伙股东·创客V5 |
| 4 再下一单(链上有两个 V5) | B 极差 100,C 平级 10 | 两人收益明细对应文案 |
| 5 开通 D 酒道馆、E 区县 | 拆分 50+50 | D/E 多标,明细有团队奖 |
| 6 把 A 的自购时间改到 31 天前(测) | A 灰点;新单 A 一条 skip | A 顶栏黄条;明细「未发放」 |
| 7 退款第 2 步订单 | 流水退回,序号回退 | 钱包减少;券计划关闭 |
| 8 跑日结 | 日结页一行成功 | 马豆页多一条;券释放天数 +1 |
| 9 日结再跑一次 | 不加倍 | 数字不变 |
---
## 15. 产品待办(和业务对齐的话术)
给运营的一页纸:
1. 用户默认都是品酒师,不用申请。
2. 创客/酒道馆/区县你在后台开通,用户端只展示。
3. 钱进「收益」可提现;马豆只能看值;兑换券只能兑货,365 天慢慢出来。
4. 30 天自己不买,推广费停发,不是封号。
5. 改规则只影响以后的单。
6. 客服查账:分销商详情 → 收益流水,勾选「显示未发放原因」。
---
## 16. 和主技术方案的关系
- 表结构、钩子、算法:只看 `合伙股东收益体系二次开发文档.md`。
- 页面、字段、文案、验收剧本:只看本文。
- 两边冲突时,以算法文档的「建议默认」为准,本文跟默认走。

查看文件

@@ -1,10 +1,11 @@
# 恒连数通 · 合伙股东收益体系完整技术方案
> 版本:V2.0(基于现有前后端代码重写)
> 版本:V2.1(对齐本仓库 `uniapp/` 用户端)
> 日期:2026-09-16
> 代码基线:本仓库 Shopro Plus **3.2.0** + FastAdmin
> 用户端基线:官方 **sheep uni-app**(`SHOPRO_API_PATH=/addons/shopro/`)
> 状态:可排期实施方案(业务未拍板项见第 16 节,开发按建议默认)
> 用户端:本仓库 `uniapp/`(Shopro sheep **3.1.0**,`sheepjs/shop`)
> 状态:可排期实施方案(业务未拍板项见第 16 节,开发按建议默认)
> 后台 / 用户端页面级规格:`docs/合伙股东-后台与用户端功能规格.md`
---
@@ -12,19 +13,20 @@
| 部分 | 位置 | 结论 |
|---|---|---|
| 商城后端 | 本仓库 `addons/shopro`、`application/admin` | 完整,Shopro Plus 3.2.0 |
| 管理后台前端 | 本仓库 `application/admin/view/shopro` + `public/assets/js/backend/shopro` | 完整,Element Plus + RequireJS |
| 用户端 uni-app | **不在本仓库** | 官方 sheep 结构,接口已备好;本地未找到恒连数通前端工程 |
| 现有分销 | 三级百分比佣金 + 分销商等级升级 | 能复用关系链 / 支付钩子 / 钱包 / 团队统计,**不能直接算**固定金额奖、均分、马豆、释放券 |
| 商城后端 | `addons/shopro`、`application/admin` | 完整,Shopro Plus 3.2.0 |
| 管理后台前端 | `application/admin/view/shopro` + `public/assets/js/backend/shopro` | 完整,Element Plus + RequireJS |
| 用户端 | **`uniapp/`** | Shopro sheep 3.1.0,接口前缀 `/addons/shopro/`,与后端完全对齐 |
| 现有分销 UI | `uniapp/pages/commission/*` | 只有等级名徽章 + 百分比分销中心,没有品酒师/合伙股东/马豆/释放券 |
用户端若已上线,一般是独立 sheep 工程,请求前缀:
用户端请求:
```
{SHOPRO_BASE_URL}/addons/shopro/{controller.action}
{SHOPRO_BASE_URL}{SHOPRO_API_PATH}{controller.action}
例:https://域名/addons/shopro/commission.agent
Header: token + platform
```
对照本地另一套 Shopro Plus 前端(`/Users/chen/Desktop/xbiuld/理发店`),页面和接口命名与本后端完全对得上。本方案用户端改动按这套 sheep 写。**开工前请把恒连数通 uni-app 放进工作区。**
配置在 `uniapp/sheep/config/index.js`,读 `.env` 的 `SHOPRO_BASE_URL` / `SHOPRO_API_PATH` / `SHOPRO_STATIC_URL`。
---
@@ -689,38 +691,110 @@ CREATE TABLE `fa_shopro_partner_voucher_plan` (
---
## 11. 用户端 uni-app(sheep,工程不在本仓库)
## 11. 用户端 `uniapp/`(已在本仓库,按文件改)
对照官方页面,改这些文件即可,不必重做分销中心。
这是官方 sheep 3.1.0,**不要重做分销中心**,在现有页面上长身份和三种资产。
### 11.1 必改
### 11.1 现有页面清单(已对过 `uniapp/pages.json`)
| 现有页 | 文件 | 现在干什么 | 本需求怎么用 |
|---|---|---|---|
| 个人中心 | `pages/index/user.vue` | 装修驱动,只渲染 `template.user` | 不直接改这页;改装修组件 |
| 用户卡片 | `sheep/components/s-user-card/s-user-card.vue` | 头像+昵称,**无等级徽章** | 昵称下加身份徽章 |
| 钱包卡片 | `sheep/components/s-wallet-card/s-wallet-card.vue` | 余额/积分/优惠券;**佣金入口被注释掉** | 加佣金、马豆、可用兑换券 |
| 分销中心 | `pages/commission/index.vue` | 标题「分销中心」,依赖 agent 接口 | 改标题「收益中心」 |
| 身份条 | `pages/commission/components/commission-info.vue` | 只显示 `agentInfo.level_info.name` | 多徽章:等级 + 酒道馆 + 区县 |
| 账户卡 | `pages/commission/components/account-info.vue` | 总收益 / 佣金 / 消费 | 加马豆价值、可用兑换券 |
| 功能菜单 | `pages/commission/components/commission-menu.vue` | 团队/佣金明细/订单/推广/资料/海报/分享 | 加收益明细、马豆、兑换券 |
| 未成为分销商 | `commission-condition.vue` | code=100 弹出买货/消费条件 | 注册即品酒师后这条不再出现 |
| 审核/冻结 | `commission-auth.vue` | 101–107 弹窗 | 保持;`level=0` 会 101,所以不能关分销 |
| 我的团队 | `pages/commission/team.vue` | 只列直推,右侧 `level_info` | 加酒道馆/区县小标 |
| 分销订单 | `pages/commission/order.vue` | 读 `rewards[0].commission` 百分比佣金 | 可继续展示团队单数;明细改走新页 |
| 佣金钱包 | `pages/user/wallet/commission.vue` | `user.wallet_log?type=commission` + 提现/转余额 | 现金收益继续走这里 |
| 确认订单 | `pages/order/confirm.vue` | 只用 Shopro `coupon_id` | 后期加兑换券抵扣行 |
| 申请分销商 | `pages/commission/apply.vue` | 资料表单 | partner 模式关掉申请后可隐藏菜单项 |
已对接接口(`uniapp/sheep/api/commission.js`)与后端完全一致,**URL 不用改**:
- `GET commission.agent`
- `GET commission.agent/team`
- `GET commission.order` / `log` / `goods`
- `POST commission.agent/transfer` / `apply`
个人中心装修组件在 `sheep/components/s-block-item/s-block-item.vue`:`userCard` / `walletCard`。后台装修拖的就是这两块,改组件即可全站生效。
### 11.2 必改文件
| 文件 | 改动 |
|---|---|
| `sheep/store/user.js` | `defaultUserInfo` 加 madow / voucher / identities |
| `sheep/api/commission.js` | 已有 agent,不用改 URL |
| `sheep/api/partner.js` | **新建**,对 9.3 |
| `pages/index/user.vue` | 头像下展示身份徽章(品酒师 / 合伙股东) |
| `pages/commission/components/commission-info.vue` | 多徽章:创客等级 + 酒道馆 + 区县 |
| `pages/commission/components/commission-menu.vue` | 增加:收益明细、马豆、兑换券 |
| `pages/commission/index.vue` | 标题可改为「收益中心」 |
| `pages.json` | 注册新页 |
| `uniapp/sheep/store/user.js` | `defaultUserInfo` 增加 `identities` `identity_text` `madow` `madow_value` `voucher_available`;`getInfo()` 后即可画徽章,不必等 agent |
| `uniapp/sheep/api/partner.js` | **新建**,见 9.3;在 `sheep/api/index.js` 注册 `partner` |
| `uniapp/sheep/components/s-user-card/s-user-card.vue` | 昵称下方:`品酒师` 或 `合伙股东 · 创客Vx`,可叠加酒道馆/区县 |
| `uniapp/sheep/components/s-wallet-card/s-wallet-card.vue` | 恢复佣金入口;加「马豆」「兑换券」两项(点进新页) |
| `uniapp/pages/commission/index.vue` | `title` 改为「收益中心」 |
| `uniapp/pages/commission/components/commission-info.vue` | `level_info` 一枚 + `is_venue`/`is_county` 两枚 |
| `uniapp/pages/commission/components/account-info.vue` | 四列:总收益 / 佣金 / 马豆价值 / 可用兑换券 |
| `uniapp/pages/commission/components/commission-menu.vue` | `menuList` 增加三项,路径见下表;「我的资料」在关闭申请表单后去掉 |
| `uniapp/pages/commission/team.vue` | 列表右侧除 `level_info.name` 外显示酒道馆/区县 |
| `uniapp/pages.json` | `pages/commission` 分包增加 rewards/madow/voucher;或新建 `pages/partner` 分包 |
### 11.2 新页
### 11.3 新页面(放 `uniapp/pages/commission/` 分包,少改 tab/分包)
| 路径 | 内容 |
|---|---|
| `/pages/partner/rewards` | 按奖项流水,复用 commission-log 列表样式 |
| `/pages/partner/madow` | 马豆数、汇率、约合人民币、说明 |
| `/pages/partner/voucher` | 总额/已释放/可用、365 进度 |
| `/pages/commission/team` | 直推列表加身份(后端 team 接口 with agent 已有 level,再加 is_venue/is_county) |
| 路径 | 文件 | 内容 | 接口 |
|---|---|---|---|
| `/pages/commission/rewards` | `pages/commission/rewards.vue` | 按奖项筛选流水 | `GET partner.index/rewards` |
| `/pages/commission/madow` | `pages/commission/madow.vue` | 马豆数、当前汇率、约合人民币、汇率说明 | `GET partner.index/madow` |
| `/pages/commission/voucher` | `pages/commission/voucher.vue` | 总额/已释放/可用、365 进度条 | `GET partner.index/voucher` |
### 11.3 可后做
样式对齐 `pages/user/wallet/commission.vue` 和 `pages/commission/components/commission-log.vue`,不要新视觉体系。
- 兑换专区:下单页勾兑换券,走 `OrderCreate` 的 `voucher_fee`
- 分销商品页:百分比改展示「推三返一 / 极差说明」,或隐藏
`commission-menu.vue` 追加:
团队接口今天只返回直推。伞下业绩继续看 agent 上已有的 `child_*`,不必一次拉整棵树。
```js
{ title: '收益明细', path: '/pages/commission/rewards', img: '.../commission_icon2.png' },
{ title: '我的马豆', path: '/pages/commission/madow', img: '.../commission_icon3.png' },
{ title: '兑换券', path: '/pages/commission/voucher', img: '.../commission_icon4.png' },
```
### 11.4 下单抵扣兑换券(P4 后半)
`pages/order/confirm.vue` 现在只有:
- `state.orderPayload.coupon_id`
- `sheep.$api.order.coupons`
加一行「兑换券」:选可用额度 → `orderPayload.voucher_fee` → 后端 `OrderCreate` 扣 `voucher_used`。
**不要复用 `s-coupon-select`**,那是 Shopro 一次性优惠券。
### 11.5 关键交互约束(对着现有代码)
1. `commission-auth.vue` 在 code∈{101…107} 时锁死页面。`partner_mode` 只关百分比,**必须保持 `shop.commission.level >= 1`**。
2. `commission-condition.vue` 处理 code=100(还不是分销商)。注册即品酒师后,`getAgentInfo` 应 code=1,这层不再出现。
3. 个人中心 `user.vue` **不会**调 `getAgentInfo`,只调 `updateUserData()` → `profile`。身份徽章必须做在 `profile` 返回值 + `s-user-card`,否则「我的」看不到身份。
4. 钱包卡片佣金被注释,用户现在从「我的」进不去佣金;本需求要恢复,并明确文案「收益/佣金」。
5. 团队页只拉直推。伞下人数继续用已有 `child_user_count_*`,不必新接口。
---
## 11.6 用户端改动文件一览
```
uniapp/pages.json
uniapp/sheep/store/user.js
uniapp/sheep/api/index.js
uniapp/sheep/api/partner.js 新建
uniapp/sheep/components/s-user-card/s-user-card.vue
uniapp/sheep/components/s-wallet-card/s-wallet-card.vue
uniapp/pages/commission/index.vue
uniapp/pages/commission/components/commission-info.vue
uniapp/pages/commission/components/account-info.vue
uniapp/pages/commission/components/commission-menu.vue
uniapp/pages/commission/team.vue
uniapp/pages/commission/rewards.vue 新建
uniapp/pages/commission/madow.vue 新建
uniapp/pages/commission/voucher.vue 新建
uniapp/pages/order/confirm.vue P4 抵扣
```
---
@@ -786,9 +860,12 @@ php think queue:work --queue shopro
- 汇率快照
- agent 接口带价值
### P4 · 用户端 sheep(另仓,约 4 天,依赖 P0 接口)
### P4 · 用户端 `uniapp/`(约 4 天,依赖 P0 的 profile / agent 字段)
- 徽章、菜单、三页、下单抵扣券
- `s-user-card` 身份徽章、`s-wallet-card` 恢复佣金并加马豆/兑换券
- 收益中心改标题、菜单三项、团队身份标
- 新建 rewards / madow / voucher 三页
- 确认订单兑换券抵扣(可压到 P4 后半)
### P5 · 对账与售后(约 2 天)
@@ -824,7 +901,7 @@ php think queue:work --queue shopro
| 按 item 计奖翻倍 | `orderPaidAfter` 循环 items | 即时奖按 `order_id` 幂等一次 |
| 现金 1:1 GMV | 会把当日销售额再发一遍 | 默认马豆 |
| 无 cron | 项目里没有日结命令 | 必须配 crontab,上线检查清单写死 |
| uni-app 不在本仓 | 改完接口用户看不见 | 先交付 API,并行要前端工程 |
| 个人中心看不到身份 | `user.vue` 只调 profile,不调 agent | 身份字段必须挂在 profile + `s-user-card` |
| 旧分销数据 | 已有百分比佣金 | 只影响新单;旧单不重算 |
| 队列没开 | 支付钩子已是异步 | 服务器确认 `queue:work` 两个队列都在 |
@@ -851,10 +928,10 @@ php think queue:work --queue shopro
## 17. 建议开工顺序(确认第 16 节后)
1. 把恒连数通 sheep 工程放进工作区或给仓库地址。
2. 执行 `upgrade/partner_v2.sql`,改分销配置(become=user、partner_mode=1、七条等级)。
3. 做 P0:钩子 + 推三返一 + 券计划 + agent 返回值。
4. 用一笔真实支付单对流水(不要只看代码)。
5. 再铺 P1–P3,最后对接 uni-app。
1. 执行 `addons/shopro/upgrade/partner_v2.sql`,改分销配置(become=user、partner_mode=1、七条等级)。
2. 做 P0:钩子 + 推三返一 + 券计划 + `profile` / `commission.agent` 返回值。
3. 用一笔真实支付单对佣金流水。
4. 铺 P1–P3 后台规则。
5. 同步改 `uniapp/`:先 `s-user-card` + `s-wallet-card` + 收益中心三页,再做下单抵扣。
本仓库当前就能做完 **P0–P3 + 后台**。用户端页面必须有 sheep 工程才能改。
前后端都在本仓库,可以同一迭代交付。