From 12c2431d4e001a4c3c8132d04a874da797e764e6 Mon Sep 17 00:00:00 2001 From: danaisuiyuan Date: Sat, 2 May 2026 01:59:59 +0800 Subject: [PATCH] docs: add shaoyaoju secondary development guide --- docs/project-shaoyaoju/PRD_shaoyaoju_V1.0.md | 787 +++++++++ docs/project-shaoyaoju/prd-require.md | 242 +++ .../secondary-development-guide.md | 1471 +++++++++++++++++ docs/project-shaoyaoju/syj-fsgx-diff.md | 289 ++++ 4 files changed, 2789 insertions(+) create mode 100644 docs/project-shaoyaoju/PRD_shaoyaoju_V1.0.md create mode 100644 docs/project-shaoyaoju/prd-require.md create mode 100644 docs/project-shaoyaoju/secondary-development-guide.md create mode 100644 docs/project-shaoyaoju/syj-fsgx-diff.md diff --git a/docs/project-shaoyaoju/PRD_shaoyaoju_V1.0.md b/docs/project-shaoyaoju/PRD_shaoyaoju_V1.0.md new file mode 100644 index 00000000..907fc87d --- /dev/null +++ b/docs/project-shaoyaoju/PRD_shaoyaoju_V1.0.md @@ -0,0 +1,787 @@ +# 芍药居小程序 · 产品需求文档（PRD）V1.0 + +> 技术底座：CRMEB Pro v3.5 + fsgx 分支二次开发成果 +> 文档日期：2026-05-02 +> 文档状态：当前分支需求草案 +> 核心原则：基于 fsgx 项目代码做最小修改，最大程度复用现有 CRMEB 与 fsgx 能力 +> 业务需求来源：`docs/project-shaoyaoju/prd-require.md` +> 配套差异文档：`docs/project-shaoyaoju/syj-fsgx-diff.md` + +--- + +## 1. 文档说明 + +### 1.1 文档目的 + +本文档基于 `docs/project-shaoyaoju/prd-require.md` 重新梳理后的业务口径，并结合当前 `fsgx-bypass-auth` / `syj-bypass-auth` 分支代码能力重新整理。 + +`prd-require.md` 已将需求拆分为“推四免一主线规则、签到规则、补充等级与积分规则、奖励使用限制、招商合作、待确认问题”。待确认问题已由业务侧补充确认，并追加新的落地反馈：每满 4333 元生成的推广任务，具体指“推四免一的有效推广任务维度”，需等价为当前代码中的 1 个报单商品订单触发基准，用于复用现有分销奖金、积分奖励和分销等级升级任务。 + +本项目不从零开发新商城，而是在 fsgx 现有代码基础上做最小差异改造：商品、订单、支付、推荐关系、分销奖金、积分奖励、分销等级、佣金流水、提现、分销员管理、签到等现有能力继续复用；仅新增或改造芍药居必须具备的“消费累计生成推广任务、任务等价触发现有奖励链路、任务进度、提前兑现、任务审计”能力。 + +### 1.2 设计原则 + +| 原则 | 说明 | +|---|---| +| 最大复用 | 复用 CRMEB 商品、订单、支付、用户、推广关系、佣金、提现、签到、文章、后台权限 | +| 延续 fsgx | 延续 fsgx 对 `is_queue_goods` 报单商品、周期佣金、返佣配置、分销等级、积分奖励、积分日志等已有改造 | +| 主线优先 | 首版只以“4333 元生成任务、推荐 4 单、10/20/30/40、完成 4 单不扣 7%”作为确定口径 | +| 任务等价订单 | 每 1 个推四免一有效推广任务等价当前代码 1 个报单商品订单，用于触发分销奖金、积分奖励和分销等级任务 | +| 最小新增 | 新增代码只覆盖“消费累计与推广任务适配层”不可复用部分 | +| 配置优先 | 能通过现有配置完成的，不新增表单和接口 | +| 首版隔离 | 推三免一、20/30/50、奖励仅消费、招商合作等口径不进入首版 | +| 不破坏旧链路 | 保留 fsgx 分销奖金、积分奖励、分销等级和等级任务配置，只调整触发基准 | +| 可追溯 | 所有任务、推荐订单、奖励、税费、人工调整都有流水 | + +### 1.3 文档范围 + +- 芍药居用户端小程序需求 +- 管理后台需求 +- 推四免一核心业务规则 +- 与 fsgx 当前代码能力的复用关系 +- 最小改造范围 +- 分销奖金、积分奖励、分销等级任务的复用口径 +- 奖励用途、招商合作的首版取舍 +- 数据与接口建议 +- 验收标准 + +### 1.4 不在本期范围 + +- 重写 CRMEB 商品、订单、支付、用户体系 +- 重写 fsgx 已有分销等级、等级任务、分销奖金、积分奖励、佣金流水、提现流程 +- 新建独立于当前代码之外的会员等级/积分体系 +- 公排池/排队退款机制 +- 将补充说明中的“推三免一”或 20%、30%、50% 作为首版结算规则 +- 奖励仅限平台内消费、下单黄金等非现金账户限制能力 +- 代理商招募、19800 元招商包、加权分红、股东权益、字画赠品等招商合作能力 +- 全量视觉改版 +- 独立客服、供应商、ERP 等非核心链路改造 + +### 1.5 首版业务口径取舍 + +| 需求点 | `prd-require.md` 口径 | 首版 PRD 处理 | +|---|---|---| +| 主推广模式 | 推四免一为主线，同时补充内容出现推三免一 | 已确认首版固定推四免一，推三免一作为不进入首版的旧口径 | +| 奖励比例 | 主线 10%、20%、30%、40%；补充内容出现 20%、30%、50% | 首版固定 10%、20%、30%、40% | +| 税费/手续费 | 原整理稿默认奖励结算扣 7% | 已确认：完成 4 单不扣 7%；提前兑现仍按 7% 扣费 | +| 奖励用途 | 主线写发放/提现，补充内容写不能提现、可下单黄金 | 已确认采纳建议：首版按 CRMEB 佣金账户入账并复用提现 | +| 分销奖金和积分奖励 | 新反馈要求推四免一有效推广任务等价当前报单商品订单 | 复用当前代码逻辑，由推四免一有效推广任务触发现有分销奖金和积分奖励 | +| 会员等级 | 新反馈要求复用当前代码分销等级 | 复用当前分销等级；升级条件使用后台配置的分销等级任务 | +| 招商合作 | 补充内容包含 49 名代理商、19800 元产品、分红、股东权益、字画 | 不纳入首版功能，作为独立合规/运营方案 | +| 有效商品/套餐包 | 已确认任意商品订单都是有效订单 | 新增商品默认 `is_queue_goods=1`，订单默认参与待推广金额累计与推荐计数 | + +--- + +## 2. 当前代码基础说明 + +### 2.1 当前分支基础 + +芍药居新分支 `syj-bypass-auth` 基于 `fsgx-bypass-auth` 最新代码创建，当前 fsgx 代码已具备以下能力： + +| 能力 | 当前代码/模块 | 芍药居策略 | +|---|---|---| +| 商品、购物车、订单、支付 | CRMEB 原生模块 | 直接复用 | +| 推荐关系绑定 | `spread_uid`、`spread` 参数 | 直接复用 | +| 分销员/推广员 | CRMEB `agent` 模块 | 直接复用 | +| 分销奖金/周期佣金配置 | `brokerage_cycle_count`、`brokerage_cycle_rates` | 直接复用现有发放逻辑；触发基准由报单商品订单扩展为推广任务 | +| 积分奖励 | fsgx 积分奖励、积分日志、积分释放相关能力 | 直接复用现有逻辑；推四免一有效推广任务等价 1 个报单商品订单作为触发基准 | +| 分销等级 | 当前代码分销等级和后台等级任务配置 | 直接复用；升级任务使用后台配置的分销等级任务 | +| 返佣范围 | `brokerage_scope` | 默认所有新增商品参与，使用 `is_queue_goods` 保留排除能力 | +| 返佣时机 | `brokerage_timing` | 复用当前代码逻辑和后台配置，不为芍药居单独固定节点 | +| 参与规则商品标记 | `is_queue_goods` | 新增商品默认设为 1，继续作为任务消费与推荐有效订单识别字段 | +| 佣金流水 | CRMEB `UserBrokerage` / `UserBill` | 复用为奖励结算流水 | +| 提现 | CRMEB `extract` | 复用提现流程；完成任务不扣 7%，提前兑现扣费在任务结算时处理 | +| 用户资产 | `/api/hjf/assets/overview` | 可复用并改文案/字段 | +| 后台分销管理 | `/admin/agent/*` | 直接复用 | +| 后台积分日志 | `/admin/hjf/points/log` | 直接复用，用于查看推广任务触发的积分奖励 | +| 签到 | CRMEB `sign/*` 接口与 `user_sgin` 页面 | 复用，新增文章浏览 10 秒前置条件 | + +### 2.2 需要最小新增的能力 + +fsgx 当前是“报单商品订单触发分销奖金、积分奖励和分销等级任务”。芍药居新增的核心差异是：用户自己的消费每满 4333 元先生成 1 个推四免一有效推广任务，该任务在系统侧等价当前代码的 1 个报单商品订单，作为现有分销奖金、积分奖励、分销等级任务的触发基准；同时，该任务继续承载推四免一进度、完成结算和提前兑现。 + +新增能力最小集合： + +| 新增能力 | 原因 | +|---|---| +| 待推广金额累计 | fsgx 没有“用户自身消费累计余额”概念 | +| 推广任务 | fsgx 没有按 4333 元消费自动生成的任务实体 | +| 任务等价订单适配 | 需要将 1 个推广任务映射为当前代码 1 个报单商品订单触发基准 | +| 任务推荐进度 | fsgx 只有周期佣金，没有任务维度 | +| 提前兑现 | fsgx 订单佣金即时/确认后发放，不支持任务中途关闭结算 | +| 任务结算流水 | 需要记录任务完成、提前兑现、税费、到账和关联奖励流水 | +| 任务后台 | 运营要按任务排查进度、订单和结算 | + +--- + +## 3. 产品概述 + +### 3.1 产品定位 + +| 维度 | 描述 | +|---|---| +| 产品形态 | 微信小程序 + PC 管理后台 | +| 基础代码 | fsgx 项目代码 + CRMEB Pro v3.5 | +| 核心商品 | 芍药居新增商品默认参与规则，任务基准金额 4333 元 | +| 核心模式 | 消费生成推四免一有效推广任务 + 任务等价报单商品订单触发现有奖励链路 + 推荐 4 单完成任务 | +| 核心体验 | 用户能看到待推广金额、任务进度、可兑现奖励和到账金额 | +| 运营目标 | 在尽量少改代码的前提下，快速上线推四免一规则 | + +### 3.2 用户角色 + +| 角色 | 诉求 | 主要页面/能力 | +|---|---|---| +| 普通会员 | 购买商品并累计任务资格 | 商品、订单、个人中心 | +| 推广会员 | 查看任务、分享、兑现奖励、获得积分/等级成长 | 我的推广任务、任务详情、分享海报、资产/积分记录 | +| 被推荐用户 | 通过分享进入并下单 | 商品详情、下单支付 | +| 运营人员 | 配置规则、查看任务和异常、维护分销等级任务 | 推广任务管理、规则配置、订单管理、分销等级配置 | +| 财务人员 | 核对奖励、税费和提现 | 结算流水、提现审核、导出 | + +补充等级会员、代理商、招商合作方已确认不纳入首版，首版不新增独立页面和结算流程。 + +--- + +## 4. 核心业务规则 + +### 4.0 术语边界 + +本文档中的“推广任务”如无特别说明，均特指“推四免一有效推广任务维度”： + +- 该任务由用户有效消费累计每满 4333 元自动生成。 +- 该任务用于记录推四免一的 4 单推荐进度、完成结算和提前兑现。 +- 该任务在系统侧等价当前代码 1 个报单商品订单，用于触发现有分销奖金、积分奖励和分销等级任务。 +- 该任务不是后台配置的“分销等级任务”。分销等级任务仍复用当前代码后台配置，推广任务只是计入该等级任务统计的业务来源之一。 + +### 4.1 参与规则商品 + +芍药居继续复用 fsgx 的 `is_queue_goods` 字段： + +- `is_queue_goods = 1`：参与规则商品，参与待推广金额累计和推荐有效订单判断。 +- `is_queue_goods = 0`：普通商品，不参与推四免一任务。 +- 新增的所有商品默认设置 `is_queue_goods = 1`，因此新增商品订单默认都是有效订单。 +- 若运营后续需要排除个别商品，可将该商品设置为 `is_queue_goods = 0`。 + +默认规则： + +| 项 | 规则 | +|---|---| +| 任务基准金额 | 4333 元 | +| 任务目标单数 | 4 单 | +| 推荐奖励比例 | 10%、20%、30%、40% | +| 有效订单节点 | 待推广金额累计默认确认收货后；推荐进度计入复用后台 `brokerage_timing`，`on_pay` 支付成功后计入，`on_confirm` 确认收货后计入 | +| 分销奖金触发 | 每 1 个推四免一有效推广任务等价当前代码 1 个报单商品订单，复用现有分销奖金逻辑 | +| 积分奖励触发 | 每 1 个推四免一有效推广任务等价当前代码 1 个报单商品订单，复用现有积分奖励逻辑 | +| 会员等级 | 复用当前分销等级，升级任务由后台分销等级任务配置决定 | +| 税费/手续费 | 完成 4 单不扣 7%；1-3 单提前兑现扣 7% | +| 奖励入账 | 已确认首版进入 CRMEB 佣金账户并复用提现链路 | + +### 4.2 待推广金额累计 + +用户购买参与规则商品后，订单确认收货时，将订单实际支付金额计入该用户的待推广金额。由于新增商品默认 `is_queue_goods = 1`，首版新增商品订单默认都参与累计。 + +计入口径： + +| 金额项 | 是否计入 | +|---|---| +| 微信/支付宝实际支付 | 计入 | +| 余额支付 | 计入，视为实际支付 | +| 积分抵扣 | 不计入 | +| 优惠券抵扣 | 默认不计入，若运营确认不同口径需单独配置 | +| 运费 | 默认不计入，除非运营另行确认 | +| 退款金额 | 需要回滚或进入异常处理 | + +示例： + +| 订单金额 | 优惠/积分抵扣 | 实际支付 | 计入待推广金额 | +|---:|---:|---:|---:| +| 5000 元 | 500 元 | 4500 元 | 4500 元 | +| 4333 元 | 0 元 | 4333 元 | 4333 元 | +| 3000 元 | 3000 元 | 0 元 | 0 元 | + +### 4.3 推四免一有效推广任务生成 + +当用户待推广金额大于或等于 4333 元时，系统自动生成 1 个推四免一有效推广任务。 + +规则： + +1. 每满 4333 元生成 1 个推四免一有效推广任务。 +2. 生成任务后，待推广金额扣除 4333 元。 +3. 剩余金额保留，继续累计。 +4. 一次确认收货金额可生成多个任务。 +5. 多个推四免一有效推广任务可同时进行。 +6. 每生成 1 个推四免一有效推广任务，系统侧按“当前代码 1 个报单商品订单触发基准”处理，用于触发现有分销奖金、积分奖励和分销等级任务。 +7. 推四免一有效推广任务不要求新建真实商城订单；实现上可采用任务实体 + 触发适配服务，确保现有奖励逻辑拿到等价的订单金额、用户、上级关系和来源流水。 + +示例： + +| 待推广金额 | 生成任务数 | 扣除金额 | 剩余待推广金额 | +|---:|---:|---:|---:| +| 4333 元 | 1 | 4333 元 | 0 元 | +| 5200 元 | 1 | 4333 元 | 867 元 | +| 10000 元 | 2 | 8666 元 | 1334 元 | + +任务触发现有奖励链路的建议口径： + +| 触发项 | 口径 | +|---|---| +| 触发金额 | 4333 元/任务 | +| 触发用户 | 推四免一有效推广任务所属用户 | +| 上级关系 | 复用当前 `spread_uid` / `spread` 推荐关系 | +| 触发商品类型 | 等价当前代码的报单商品订单 | +| 分销奖金 | 复用当前分销奖金/佣金计算与流水逻辑 | +| 积分奖励 | 复用当前积分奖励、积分日志、积分释放相关逻辑 | +| 分销等级任务 | 复用后台配置的分销等级升级任务 | +| 追溯来源 | 奖励/积分/等级任务流水需关联推四免一有效推广任务 ID（`syj_promote_task_id`）或任务编号 | + +### 4.4 推荐有效订单 + +推荐有效订单继续复用 CRMEB 推广关系。 + +默认有效条件： + +1. 被推荐用户的 `spread_uid` 为任务所属用户。 +2. 被推荐订单包含参与规则商品；首版新增商品默认都是参与规则商品。 +3. 被推荐订单达到后台返佣设置中的佣金发放时机：`brokerage_timing=on_pay` 时支付成功后计入，`brokerage_timing=on_confirm` 时确认收货后计入。 +4. 订单未退款、未撤单、未被风控标记无效。 + +推荐计入规则： + +- 只计入推荐人当前最早创建的进行中任务。 +- 当前任务满 4 单后，后续推荐订单计入下一个进行中任务。 +- 推荐人没有进行中任务时，推荐订单不产生任务进度；可只保留 CRMEB 原始推荐关系和订单记录。 + +### 4.5 奖励计算 + +单个任务基准金额为 4333 元，推荐成功单数按阶梯比例累计奖励。 + +| 成功单数 | 本档比例 | 本档奖励 | 累计比例 | 累计税前奖励 | +|---:|---:|---:|---:|---:| +| 第 1 单 | 10% | 433.30 元 | 10% | 433.30 元 | +| 第 2 单 | 20% | 866.60 元 | 30% | 1299.90 元 | +| 第 3 单 | 30% | 1299.90 元 | 60% | 2599.80 元 | +| 第 4 单 | 40% | 1733.20 元 | 100% | 4333.00 元 | + +结算规则： + +```text +税前奖励 = 4333 × 累计奖励比例 +完成 4 单：到账金额 = 4333，税费/手续费 = 0 +提前兑现 1-3 单：税费/手续费 = 税前奖励 × 7%，到账金额 = 税前奖励 - 税费/手续费 +``` + +金额精度： + +- 存储使用分。 +- 展示保留 2 位小数。 +- 提前兑现税费和到账金额统一四舍五入到分。 + +### 4.6 任务完成 + +当任务推荐成功达到 4 单： + +1. 任务状态变为已完成。 +2. 生成任务结算记录。 +3. 税前奖励为 4333 元。 +4. 完成 4 单不扣 7%。 +5. 到账金额为 4333 元。 +6. 奖励入账到 CRMEB 佣金账户，并复用现有提现链路。 + +### 4.7 提前兑现 + +用户可在任务未完成 4 单时提前兑现。 + +规则： + +| 条件 | 处理 | +|---|---| +| 0 单成功 | 不允许提前兑现 | +| 1-3 单成功 | 可提交提前兑现申请，按当前累计比例计算税前奖励 | +| 审核方式 | 后台审核，复用当前代码已有审核能力 | +| 审核通过后 | 扣除 7% 税费/手续费后发放 | +| 提前兑现后 | 审核通过并结算后任务关闭，不再接收推荐订单 | +| 已占用 4333 元 | 不退回待推广金额 | + +提前兑现示例： + +| 成功单数 | 税前奖励 | 税费 7% | 到账金额 | +|---:|---:|---:|---:| +| 1 | 433.30 元 | 30.33 元 | 402.97 元 | +| 2 | 1299.90 元 | 90.99 元 | 1208.91 元 | +| 3 | 2599.80 元 | 181.99 元 | 2417.81 元 | + +### 4.8 上级任务联动 + +原始需求提出：“生成推广任务时，系统检查直属上级是否有进行中的任务；如果有，上级推广成功数量 +1。” + +为保持最小改造，建议将该规则落到同一套任务计数服务中： + +1. 用户生成新任务时，读取该用户直属上级。 +2. 若上级存在进行中任务，则为上级最早任务增加 1 个成功来源。 +3. 来源类型标记为 `task_created`，与订单推荐来源 `order_pay` / `order_confirm` 区分；订单推荐来源由后台 `brokerage_timing` 决定。 +4. 若上级任务因此达到 4 单，则触发完成结算。 + +注意：该规则与“推荐有效订单”并存，可能导致上级同时因下级任务创建和下级订单确认获得进度。上线前需运营确认是否二选一。默认按原始需求保留“下级生成任务也可计入上级任务”的能力，但后台配置可关闭。 + +### 4.9 签到规则 + +签到复用 CRMEB 原签到模块，新增“先浏览文章 10 秒”的门槛。 + +规则： + +1. 用户进入签到页时先展示产品功效文章。 +2. 浏览满 10 秒后，签到按钮解锁。 +3. 每个自然日只允许签到一次。 +4. 原 CRMEB 签到奖励继续可配。 +5. 若运营不需要签到奖励，可配置为 0，仅记录签到行为。 + +### 4.10 分销等级与积分奖励复用 + +根据最新反馈，会员等级和积分奖励不再作为后续隔离能力，而是复用当前代码： + +| 能力 | 首版处理 | 说明 | +|---|---|---| +| 会员等级 | 复用当前代码的分销等级 | 不新增独立等级体系 | +| 升级任务 | 复用后台配置的分销等级任务 | 推四免一有效推广任务等价报单商品订单后，进入现有等级任务统计 | +| 积分奖励 | 复用当前积分奖励逻辑 | 每个推四免一有效推广任务按 1 个报单商品订单触发积分奖励 | +| 积分日志 | 复用当前积分日志 | 日志需能追溯到推广任务 | +| 积分释放 | 如当前代码已启用，则复用现有释放逻辑 | 是否释放、释放比例、释放周期以现有配置为准 | +| 平级/级差规则 | 复用当前分销等级和积分奖励规则 | 不单独开发新规则 | +| 奖励不能提现、可下单黄金 | 已确认采纳 CRMEB 佣金账户和提现链路，不实现奖励用途限制 | 如需限制用途，后续另立需求 | +| 49 名代理商与 19800 元招商包 | 已确认不进入首版小程序功能 | 后续需独立招商合同、合规审核和后台管理方案 | + +--- + +## 5. 用户端需求 + +### 5.1 首页与商品 + +| 功能 | 复用/改造 | 说明 | +|---|---|---| +| 首页 DIY | 直接复用 | 后台配置芍药居素材、参与规则商品入口 | +| 商品列表 | 直接复用 | 保留 CRMEB 列表能力 | +| 商品详情 | 小改文案 | 新增商品默认展示“参与推四免一任务”提示 | +| 下单支付 | 直接复用 | 保留 CRMEB 下单、支付、余额、优惠券 | +| 订单确认收货 | 小改后端 | 确认收货后触发待推广金额累计 | + +### 5.2 我的推广任务 + +新增用户端页面，建议路径： + +```text +pro_v3.5.1/view/uniapp/pages/syj/promote_task/index.vue +pro_v3.5.1/view/uniapp/pages/syj/promote_task/detail.vue +``` + +页面能力： + +| 模块 | 字段/行为 | +|---|---| +| 资产摘要 | 待推广金额、已生成任务数、进行中任务数、累计奖励、积分概览、分销等级 | +| 任务列表 | 任务编号、进度、当前税前奖励、预计到账、状态 | +| 任务详情 | 4 档进度、推荐订单来源、结算预览、已触发的分销奖金/积分奖励 | +| 提前兑现 | 1-3 单时可提交申请，0 单置灰，提交后等待后台审核 | +| 分享入口 | 复用 CRMEB 分享参数，生成带 `spread` 的分享链接/海报 | + +### 5.3 个人中心入口 + +在现有个人中心/推广中心增加入口： + +| 入口 | 策略 | +|---|---| +| 我的推广任务 | 新增入口，指向芍药居任务页 | +| 推广中心 | 复用 CRMEB 原推广中心，文案按芍药居调整 | +| 佣金明细 | 复用 CRMEB 佣金明细 | +| 积分明细 | 复用当前积分日志页面或入口 | +| 分销等级 | 复用当前分销等级展示 | +| 提现 | 复用 CRMEB 提现 | + +### 5.4 签到页 + +在现有 `pages/users/user_sgin/index.vue` 基础上改造： + +| 改造点 | 说明 | +|---|---| +| 签到前置文章 | 进入页面先展示指定文章或弹层 | +| 10 秒倒计时 | 倒计时结束前签到按钮禁用 | +| 签到提交 | 倒计时结束后调用原签到接口 | +| 后台配置 | 文章 ID、浏览秒数可配置 | + +--- + +## 6. 管理后台需求 + +### 6.1 复用后台模块 + +| 模块 | 路径/能力 | 芍药居策略 | +|---|---|---| +| 商品管理 | `product` | 新增商品默认 `is_queue_goods=1`；支持运营手动排除个别商品 | +| 订单管理 | `order` | 继续处理订单、发货、确认收货、退款 | +| 分销员管理 | `/admin/agent/agent_manage/index` | 复用推荐关系、分销员数据 | +| 分销等级 | 当前分销等级配置模块 | 复用等级和后台配置的等级任务 | +| 佣金记录 | 财务/佣金相关页面 | 复用奖励结算流水展示 | +| 积分日志 | HJF/fsgx 积分日志页面 | 复用推广任务触发的积分奖励记录 | +| 积分释放 | 当前积分释放配置和定时任务 | 如当前项目启用则复用，不新增释放引擎 | +| 提现审核 | CRMEB 提现模块 | 复用审核流程；避免与任务结算 7% 重复扣费 | +| 签到配置 | CRMEB 签到配置 | 复用，新增文章浏览配置 | +| 内容文章 | CMS/文章 | 复用为签到前置文章 | + +### 6.2 新增后台模块：推四免一任务管理 + +建议新增轻量后台菜单： + +```text +营销 / 芍药居推广 / 推广任务 +营销 / 芍药居推广 / 任务结算 +营销 / 芍药居推广 / 规则配置 +``` + +任务列表字段： + +| 字段 | 说明 | +|---|---| +| 任务编号 | 唯一任务号 | +| 用户 | UID、昵称、手机号 | +| 基准金额 | 默认 4333 元 | +| 任务进度 | 成功数量 / 4 | +| 当前税前奖励 | 按成功数量计算 | +| 税费 | 完成任务为 0；提前兑现为当前奖励 × 7% | +| 到账金额 | 完成任务为 4333 元；提前兑现为税前奖励 - 税费 | +| 状态 | 进行中、已完成、提前兑现待审核、已提前兑现、异常关闭 | +| 创建时间 | 待推广金额达标时间 | + +任务详情： + +- 消费金额来源流水 +- 推荐订单来源 +- 下级任务创建来源 +- 等价报单商品订单触发记录 +- 分销奖金/佣金流水 +- 积分奖励/积分释放流水 +- 分销等级任务进度 +- 结算记录 +- 操作日志 + +后台操作： + +| 操作 | 说明 | +|---|---| +| 查看详情 | 查看任务、订单、结算全链路 | +| 查看奖励触发 | 查看该任务触发的分销奖金、积分奖励、等级任务记录 | +| 审核提前兑现 | 对用户提前兑现申请进行通过/驳回，复用当前审核能力 | +| 标记异常 | 风控或售后场景使用 | +| 重新计算 | 按当前规则重算任务金额，仅管理员 | +| 导出 | 导出任务、结算、税费 | + +### 6.3 规则配置 + +优先复用 fsgx 已有返佣配置字段： + +| 配置项 | 建议字段 | 默认值 | +|---|---|---| +| 任务基准金额 | 新增 `syj_task_base_amount` | 4333 | +| 任务目标单数 | 可复用 `brokerage_cycle_count` | 4 | +| 奖励比例 | 可复用 `brokerage_cycle_rates` | `[10,20,30,40]` | +| 返佣范围 | 复用 `brokerage_scope`，新增商品默认 `is_queue_goods=1` | `queue_only` | +| 生效节点 | 复用当前代码 `brokerage_timing` 配置 | 沿用当前配置 | +| 推四免一有效推广任务等价报单订单 | 新增 `syj_task_as_queue_order_enable` | 1 | +| 任务触发分销奖金 | 新增 `syj_task_trigger_brokerage_enable` 或复用现有开关 | 1 | +| 任务触发积分奖励 | 新增 `syj_task_trigger_points_enable` 或复用现有开关 | 1 | +| 任务触发分销等级任务 | 新增 `syj_task_trigger_agent_level_enable` 或复用现有开关 | 1 | +| 提前兑现税费比例 | 建议新增 `syj_early_cash_tax_rate`，避免与提现手续费混淆 | 7 | +| 完成任务税费比例 | 新增 `syj_complete_tax_rate` 或固定规则 | 0 | +| 下级任务生成是否计入上级 | 新增 `syj_parent_task_on_child_task` | 1 | +| 是否允许提前兑现 | 新增 `syj_early_cash_enable` | 1 | +| 提前兑现是否审核 | 新增 `syj_early_cash_audit_enable` 或复用当前审核配置 | 1 | +| 奖励用途模式 | 可新增 `syj_reward_usage_mode` | `brokerage_withdrawable` | +| 是否启用招商合作 | 可新增 `syj_agent_recruit_enable` | 0 | + +--- + +## 7. 数据模型建议 + +### 7.1 新增表最小集合 + +#### 7.1.1 推广任务表 `eb_syj_promote_task` + +| 字段 | 类型 | 说明 | +|---|---|---| +| id | bigint | 主键 | +| task_no | varchar | 任务编号 | +| uid | int | 任务所属用户 | +| base_amount | int | 基准金额，单位分 | +| target_count | int | 目标数量，默认 4 | +| success_count | int | 当前成功数量 | +| reward_amount | int | 当前税前奖励，单位分 | +| tax_amount | int | 税费，单位分；完成任务为 0，提前兑现按 7% | +| arrival_amount | int | 到账金额，单位分 | +| trigger_amount | int | 等价报单商品订单触发金额，默认 433300 分 | +| reward_trigger_status | tinyint | 现有奖励链路触发状态：0 未触发，1 已触发，2 触发失败 | +| reward_trigger_time | int | 分销奖金、积分奖励、等级任务触发时间 | +| status | tinyint | 0 进行中，1 已完成，2 提前兑现待审核，3 已提前兑现，4 异常关闭 | +| completed_at | datetime | 完成时间 | +| cashed_at | datetime | 提前兑现时间 | +| create_time | int | 创建时间 | +| update_time | int | 更新时间 | + +#### 7.1.2 待推广金额流水表 `eb_syj_promote_amount_log` + +| 字段 | 类型 | 说明 | +|---|---|---| +| id | bigint | 主键 | +| uid | int | 用户 ID | +| type | varchar | consume/task_create/refund/admin_adjust | +| amount | int | 变动金额，单位分，可正可负 | +| balance | int | 变动后待推广金额，单位分 | +| order_id | int | 关联订单 ID | +| task_id | int | 关联任务 ID | +| remark | varchar | 说明 | +| create_time | int | 创建时间 | + +#### 7.1.3 任务进度明细表 `eb_syj_promote_task_record` + +| 字段 | 类型 | 说明 | +|---|---|---| +| id | bigint | 主键 | +| task_id | int | 任务 ID | +| uid | int | 任务所属用户 | +| source_type | varchar | order_pay/order_confirm/task_created/manual | +| source_uid | int | 触发用户 | +| order_id | int | 来源订单 ID，可为空 | +| child_task_id | int | 来源下级任务 ID，可为空 | +| step_no | int | 第几单，1-4 | +| step_rate | int | 本档比例，按百分比存整数 | +| step_reward | int | 本档奖励，单位分 | +| status | tinyint | 1 有效，0 无效 | +| create_time | int | 创建时间 | + +#### 7.1.4 任务结算表 `eb_syj_promote_settlement` + +| 字段 | 类型 | 说明 | +|---|---|---| +| id | bigint | 主键 | +| task_id | int | 任务 ID | +| uid | int | 收益用户 | +| settle_type | varchar | complete/early_cash/manual | +| success_count | int | 结算时成功数量 | +| reward_amount | int | 税前奖励 | +| tax_amount | int | 税费；完成任务为 0，提前兑现按 7% | +| arrival_amount | int | 到账金额 | +| user_brokerage_id | int | 关联 CRMEB 佣金记录 | +| user_bill_id | int | 关联 CRMEB 账单 | +| status | tinyint | 待审核、审核通过、审核驳回、已发放、已撤销 | +| audit_uid | int | 审核管理员 ID，可复用当前审核链路时按实际字段落库 | +| audit_time | int | 审核时间，可复用当前审核链路时按实际字段落库 | +| create_time | int | 创建时间 | +| paid_time | int | 发放时间 | + +#### 7.1.5 任务奖励触发记录表 `eb_syj_promote_reward_trigger` + +该表用于记录“推四免一有效推广任务等价当前报单商品订单”后，触发现有分销奖金、积分奖励、分销等级任务的结果。若当前代码已有统一奖励流水，可不新增独立表，但必须能从现有流水反查到推四免一有效推广任务。 + +| 字段 | 类型 | 说明 | +|---|---|---| +| id | bigint | 主键 | +| task_id | int | 推广任务 ID | +| task_no | varchar | 推广任务编号 | +| uid | int | 触发用户 | +| spread_uid | int | 当前推荐上级 | +| trigger_amount | int | 触发金额，默认 433300 分 | +| trigger_type | varchar | brokerage/points/agent_level | +| ref_id | int | 关联现有佣金、积分或等级任务流水 ID | +| status | tinyint | 0 待处理，1 成功，2 失败 | +| error_msg | varchar | 失败原因 | +| create_time | int | 创建时间 | +| update_time | int | 更新时间 | + +### 7.2 用户字段建议 + +优先不改 `eb_user`。待推广金额可通过流水表聚合，也可为性能增加冗余字段： + +| 字段 | 是否必需 | 说明 | +|---|---|---| +| syj_pending_promote_amount | 可选 | 待推广金额，单位分 | + +如担心改用户表影响范围，首版可仅使用流水表 + 聚合缓存。 + +--- + +## 8. 接口建议 + +### 8.1 用户端接口 + +| 接口 | 方法 | 说明 | +|---|---|---| +| `/api/syj/promote/overview` | GET | 我的待推广金额、任务统计、奖励统计 | +| `/api/syj/promote/tasks` | GET | 我的任务列表 | +| `/api/syj/promote/task/:id` | GET | 任务详情 | +| `/api/syj/promote/task/:id/cash` | POST | 提交提前兑现申请，进入后台审核 | +| `/api/syj/promote/share` | GET | 分享链接/海报数据，复用 CRMEB 推荐参数 | + +### 8.2 后台接口 + +| 接口 | 方法 | 说明 | +|---|---|---| +| `/adminapi/syj/promote/config` | GET | 规则配置 | +| `/adminapi/syj/promote/config` | POST | 保存规则配置 | +| `/adminapi/syj/promote/tasks` | GET | 任务列表 | +| `/adminapi/syj/promote/task/:id` | GET | 任务详情 | +| `/adminapi/syj/promote/task/:id/recalculate` | POST | 重新计算 | +| `/adminapi/syj/promote/amount_logs` | GET | 待推广金额流水 | +| `/adminapi/syj/promote/settlements` | GET | 结算列表 | +| `/adminapi/syj/promote/settlement/:id/audit` | POST | 审核提前兑现申请，通过后发放、驳回后保留任务状态 | +| `/adminapi/syj/promote/reward_triggers` | GET | 查询推广任务触发的分销奖金、积分奖励、等级任务记录 | + +### 8.3 签到接口 + +签到优先复用现有接口： + +| 能力 | 现有接口 | 改造 | +|---|---|---| +| 签到配置 | `sign/config` | 增加文章 ID / 浏览秒数配置 | +| 签到提交 | `sign/user` 或 `sign/integral` | 提交时校验浏览时长 | +| 签到记录 | `sign/list`、`sign/calendar` | 直接复用 | + +--- + +## 9. 实现建议 + +### 9.1 后端最小改造点 + +| 位置 | 改造说明 | +|---|---| +| 订单确认收货链路 | 参与规则商品确认收货后累计购买人待推广金额，并尝试创建任务；新增商品默认参与 | +| 推广任务生成链路 | 每生成 1 个推四免一有效推广任务，按当前代码 1 个报单商品订单触发现有分销奖金、积分奖励和分销等级任务 | +| 推荐订单计入链路 | 复用后台 `brokerage_timing`：`on_pay` 支付成功后计入任务进度，`on_confirm` 确认收货后计入任务进度；任务进度与现有奖励触发记录分开追溯 | +| fsgx 佣金计算链路 | 保持现有分销奖金计算逻辑，增加推四免一有效推广任务作为等价触发来源 | +| 积分奖励链路 | 复用当前积分奖励、积分日志和积分释放逻辑，增加推广任务来源标识 | +| 分销等级链路 | 复用当前分销等级与后台配置的等级任务，推广任务进入等级任务统计 | +| 佣金/余额入账 | 完成任务直接按推四免一口径入账；提前兑现经后台审核通过后入账；分销奖金仍走现有逻辑 | +| 系统配置 | 增加芍药居任务相关配置项 | +| 后台路由 | 增加 `syj/promote/*` 管理接口 | + +### 9.2 前端最小改造点 + +| 端 | 改造说明 | +|---|---| +| UniApp | 新增“我的推广任务”列表/详情/提前兑现页面 | +| UniApp | 个人中心或推广中心增加入口 | +| UniApp | 商品详情/支付结果增加芍药居规则文案 | +| UniApp | 签到页加文章浏览 10 秒门槛 | +| Admin | 新增轻量任务管理页面 | +| Admin | 规则配置页面可复用系统配置表单样式 | + +### 9.3 默认配置建议 + +| 配置项 | 值 | +|---|---| +| `brokerage_cycle_count` | `4` | +| `brokerage_cycle_rates` | `[10,20,30,40]` | +| `brokerage_scope` | `queue_only` | +| `brokerage_timing` | 沿用当前配置 | +| `hjf_queue_pool_enable` | `0` | +| `hjf_umbrella_reward_enable` | `0` | +| `syj_task_base_amount` | `433300` | +| `syj_task_as_queue_order_enable` | `1` | +| `syj_task_trigger_brokerage_enable` | `1` | +| `syj_task_trigger_points_enable` | `1` | +| `syj_task_trigger_agent_level_enable` | `1` | +| `syj_complete_tax_rate` | `0` | +| `syj_early_cash_tax_rate` | `7` | +| `syj_early_cash_enable` | `1` | +| `syj_early_cash_audit_enable` | `1` | +| `syj_reward_usage_mode` | `brokerage_withdrawable` | +| `syj_agent_recruit_enable` | `0` | + +--- + +## 10. 验收标准 + +### 10.1 待推广金额与任务 + +- 新增商品默认 `is_queue_goods=1`。 +- 任意新增商品订单确认收货 4333 元后，用户自动生成 1 个任务。 +- 任意新增商品订单确认收货 10000 元后，用户生成 2 个任务，剩余待推广金额 1334 元。 +- 积分、优惠券抵扣部分不计入待推广金额。 +- 仅被运营设置为 `is_queue_goods=0` 的商品订单不生成任务。 +- 每生成 1 个推四免一有效推广任务，系统按当前代码 1 个报单商品订单触发基准记录奖励触发来源。 + +### 10.2 推荐进度 + +- 被推荐订单达到后台 `brokerage_timing` 对应节点后，推荐人最早进行中任务成功数 +1：`on_pay` 支付成功后计入，`on_confirm` 确认收货后计入。 +- 推荐人无进行中任务时，不生成任务进度。 +- 任务达到 4/4 后自动完成。 +- 多任务并行时按创建时间顺序计入。 + +### 10.3 奖励结算 + +- 1 单成功可申请提前兑现，税前 433.30 元，审核通过后扣 7% 到账 402.97 元。 +- 2 单成功可申请提前兑现，税前 1299.90 元，审核通过后扣 7% 到账 1208.91 元。 +- 3 单成功可申请提前兑现，税前 2599.80 元，审核通过后扣 7% 到账 2417.81 元。 +- 4 单完成税前奖励 4333.00 元，不扣 7%，到账 4333.00 元。 +- 所有结算均能在 CRMEB 佣金/账单中追溯。 + +### 10.4 分销奖金、积分与等级 + +- 推四免一有效推广任务生成后，能够触发现有分销奖金/佣金逻辑，并在现有佣金流水中追溯到该任务。 +- 推四免一有效推广任务生成后，能够触发现有积分奖励逻辑，并在积分日志中追溯到该任务。 +- 若当前积分释放配置启用，推四免一有效推广任务产生的积分进入现有积分释放逻辑。 +- 会员等级复用当前分销等级，升级条件按后台配置的分销等级任务计算。 +- 分销等级任务统计中，推四免一有效推广任务按等价报单商品订单计入。 + +### 10.5 提前兑现 + +- 0 单任务不可兑现。 +- 提前兑现需二次确认并提交后台审核。 +- 审核通过后任务关闭，后续订单不再计入该任务。 +- 审核驳回后任务保持进行中，可继续接收推荐订单。 +- 已占用的 4333 元不退回待推广金额。 + +### 10.6 签到 + +- 签到页先展示产品文章。 +- 10 秒内签到按钮不可点击。 +- 10 秒后可签到。 +- 同日重复签到返回明确提示。 + +### 10.7 补充规则隔离 + +- 首版用户端不出现“推三免一”结算口径。 +- 首版任务结算不使用 20%、30%、50% 作为推四免一奖励比例。 +- 首版不新增独立等级积分体系，等级、积分、升级任务均复用当前代码。 +- 首版不出现代理商 19800 元招商、加权分红、股东权益、字画赠品等入口。 +- 已确认首版奖励进入 CRMEB 佣金账户并沿用提现链路，不做下单黄金或不能提现限制。 + +--- + +## 11. 问题确认记录 + +| 编号 | 问题 | 确认结果 | PRD 落地口径 | +|---|---|---|---| +| Q1 | 推荐有效订单是否必须是 4333 元报单商品？ | 新增的所有商品默认设置 `is_queue_goods=1`，所有新增商品订单都是有效订单 | 新增商品默认参与待推广金额累计和推荐计数；保留 `is_queue_goods=0` 作为运营排除个别商品的开关 | +| Q2 | 主线到底是“推四免一”还是补充说明中的“推三免一”？ | 按“推四免一”执行 | 首版不出现推三免一结算口径 | +| Q3 | 奖励比例是 10%/20%/30%/40%，还是 20%/30%/50%？ | 推广任务按 10%/20%/30%/40% | 首版任务奖励比例固定为 10%、20%、30%、40% | +| Q4 | 奖励是否能提现，还是仅可用于平台内消费/下单黄金？ | 采纳复用 CRMEB 佣金账户和提现链路的建议 | 首版不做下单黄金或不能提现限制 | +| Q5 | 积分等级体系是否进入首版？ | 根据最新反馈，积分奖励和会员等级复用当前代码 | 首版复用当前积分奖励、积分日志、分销等级和后台配置的分销等级任务 | +| Q6 | 下级“生成任务”是否也计入上级任务，还是只按下级订单达到返佣时机节点计入？ | 采纳配置开关建议 | 首版保留“下级生成任务计入上级任务”能力，并通过配置控制；推荐订单计入节点复用后台 `brokerage_timing` | +| Q7 | 任意套餐包是否都可计入有效订单？ | 任意商品订单都是有效订单 | 新增商品默认 `is_queue_goods=1`，因此任意新增商品/套餐包订单默认有效 | +| Q8 | 完成 4 单是否也扣 7%？ | 不扣除 | 完成 4 单到账 4333 元；1-3 单提前兑现仍扣 7% | +| Q9 | 招商合作是否需要系统功能支持？ | 采纳建议 | 招商合作不纳入首版默认需求 | +| Q10 | 提前兑现是否需要后台审核？ | 后台审核，复用当前代码 | 提前兑现提交申请，后台审核通过后发放；驳回后任务继续进行 | +| Q11 | 签到是否发奖励？ | 采纳建议 | 复用 CRMEB 签到奖励配置，运营可配置为 0 | +| Q12 | 推广任务与当前报单商品订单是什么关系？ | 每满 4333 元生成 1 个推四免一有效推广任务；1 个推四免一有效推广任务等价当前代码 1 个报单商品订单 | 推四免一有效推广任务作为现有分销奖金、积分奖励和分销等级任务的触发基准 | + +--- + +## 12. 研发拆分 + +| 阶段 | 范围 | 交付 | +|---|---|---| +| Phase 1 | 配置与数据表 | 配置项、任务表、流水表、结算表 | +| Phase 2 | 订单确认收货挂钩 | 消费累计、任务生成 | +| Phase 3 | 推荐任务进度 | 推荐订单计入任务、任务完成 | +| Phase 4 | 奖励触发与结算 | 推广任务触发现有分销奖金、积分奖励、分销等级任务；完成结算、提前兑现审核、佣金/账单入账 | +| Phase 5 | 用户端页面 | 我的任务、任务详情、兑现交互 | +| Phase 6 | 后台页面 | 任务列表、详情、结算、导出 | +| Phase 7 | 签到改造 | 文章浏览 10 秒后签到 | +| Phase 8 | 回归与配置 | 芍药居默认配置落库，验证现有分销奖金、积分奖励、分销等级任务复用正确 | +| Phase 9 | 补充规则评审 | 招商合作、奖励用途限制是否进入后续版本 | diff --git a/docs/project-shaoyaoju/prd-require.md b/docs/project-shaoyaoju/prd-require.md new file mode 100644 index 00000000..3ac1ea31 --- /dev/null +++ b/docs/project-shaoyaoju/prd-require.md @@ -0,0 +1,242 @@ +# 芍药居小程序 - 业务需求与推广规则整理 + +> 文档定位：对已补充/修改过的原始需求进行结构化梳理，作为 `PRD_shaoyaoju_V1.0.md` 的业务口径来源。 +> 整理日期：2026-05-01 +> 当前状态：需求整理稿，含待确认口径。 + +--- + +## 一、核心结论 + +芍药居小程序的主线推广模式为“推四免一”： + +- 会员每累计 4333 元有效消费，可获得 1 个推广任务资格。 +- 每个推广任务目标为推荐 4 个有效订单。 +- 4 单全部完成后，任务税前奖励合计 4333 元。 +- 未完成 4 单时，会员可按已完成单数申请提前兑现。 +- 奖励按 10%、20%、30%、40% 四档递进计算，并扣除 7% 税费/手续费后发放。 + +补充内容中还包含会员等级（暨分销等级）、积分奖励、积分释放、招商合作等规则。这些规则与主线“推四免一”存在部分口径冲突，本文已单独归类为“补充规则”和“待确认问题”。 + +--- + +## 二、核心概念 + +| 概念 | 说明 | +|---|---| +| 会员 | 通过分享码注册并完成首单购买的用户 | +| 有效消费 | 会员购买参与规则的商品后，确认收货且未退款的实际支付金额 | +| 实际支付金额 | 用户真实支付金额；积分抵扣部分不计入，优惠/抵扣部分需按运营口径确认 | +| 待推广金额 | 会员有效消费的累计余额，用于生成推广任务 | +| 推广任务 | 每满 4333 元待推广金额自动生成的任务，目标为推荐 4 个有效订单 | +| 有效订单 | 被推荐用户完成购买、确认收货且未退款/撤单/风控无效的订单 | +| 提前兑现 | 任务未满 4 单时，按已成功单数结算并关闭任务 | +| 税费/手续费 | 奖励结算时扣除 7%，到账金额为税前奖励扣除费用后的金额 | +| 积分 | 补充等级规则中的奖励资产，是否纳入首版需确认 | + +--- + +## 三、主流程 + +```text +会员消费 + -> 确认收货后累计待推广金额 + -> 每满 4333 元自动生成 1 个推广任务 + -> 会员分享并推荐有效订单 + -> 推荐订单计入任务进度 + -> 满 4 单自动完成，或 1-3 单时提前兑现 + -> 按 10% + 20% + 30% + 40% 计算奖励 + -> 扣除 7% 税费/手续费后发放 +``` + +--- + +## 四、推四免一规则 + +### 4.1 消费累计 + +- 会员每次购物确认收货后，订单实际支付金额计入“待推广金额”。 +- 积分抵扣部分不计入待推广金额。 +- 示例：订单金额 5000 元，积分抵扣 500 元，实际支付 4500 元，则计入待推广金额 4500 元。 + +### 4.2 任务生成 + +- 待推广金额大于或等于 4333 元时，系统自动生成 1 个推广任务。 +- 生成任务后，待推广金额扣除 4333 元，剩余金额继续保留累计。 +- 一次消费金额较大时，可连续生成多个任务。 + +| 待推广金额 | 生成任务数 | 扣除金额 | 剩余待推广金额 | +|---:|---:|---:|---:| +| 4333 元 | 1 | 4333 元 | 0 元 | +| 5200 元 | 1 | 4333 元 | 867 元 | +| 10000 元 | 2 | 8666 元 | 1334 元 | + +### 4.3 多任务并行 + +- 一个任务未完成时，待推广金额再次满 4333 元，可继续生成新任务。 +- 会员可同时拥有多个进行中的推广任务。 +- 推荐订单建议按任务创建时间顺序，优先计入最早的进行中任务。 + +### 4.4 推荐计数 + +- 每个推广任务目标为 4 个有效订单。 +- 推荐订单确认收货后，计入推荐人的任务进度。 +- 当前任务达到 4 单后，后续推荐订单计入下一个进行中任务。 +- 推荐人没有进行中任务时，推荐订单是否保留但不计奖，需按系统实现口径确认。 + +### 4.5 上级关联 + +原始需求包含以下规则： + +- 生成推广任务时，系统检查直属上级是否有进行中的任务。 +- 如果直属上级存在进行中任务，则上级的“推广成功数量”加 1。 +- 上级也能从下级的推广成果中获益。 + +该规则与“推荐订单确认收货计入上级任务”可能重复，需要运营确认最终计数口径。建议系统实现时保留来源类型，区分“订单确认”和“下级任务生成”。 + +### 4.6 提前兑现 + +- 任务未完成 4 单时，会员可选择提前结束任务。 +- 0 单成功时不建议允许提前兑现。 +- 1-3 单成功时，按实际成功单数计算奖励。 +- 提前兑现后，该任务关闭，不再接收新的推荐订单。 +- 提前兑现后，已占用的 4333 元消费额不退回待推广金额。 + +--- + +## 五、奖励计算 + +单个任务基准金额为 4333 元。 + +| 推荐成功单数 | 本档比例 | 本档奖励 | 累计比例 | 累计税前奖励 | +|---:|---:|---:|---:|---:| +| 第 1 单 | 10% | 433.30 元 | 10% | 433.30 元 | +| 第 2 单 | 20% | 866.60 元 | 30% | 1299.90 元 | +| 第 3 单 | 30% | 1299.90 元 | 60% | 2599.80 元 | +| 第 4 单 | 40% | 1733.20 元 | 100% | 4333.00 元 | + +计算公式： + +```text +税前奖励 = 4333 × 累计奖励比例 +税费/手续费 = 税前奖励 × 7% +到账金额 = 税前奖励 - 税费/手续费 +``` + +提前兑现参考： + +| 成功单数 | 税前奖励 | 税费/手续费 7% | 到账金额 | +|---:|---:|---:|---:| +| 1 单 | 433.30 元 | 30.33 元 | 402.97 元 | +| 2 单 | 1299.90 元 | 90.99 元 | 1208.91 元 | +| 3 单 | 2599.80 元 | 181.99 元 | 2417.81 元 | +| 4 单 | 4333.00 元 | 303.31 元 | 4029.69 元 | + +--- + +## 六、签到规则 + +- 签到前，用户需先浏览产品功效介绍文章。 +- 浏览满 10 秒后，才可签到。 +- 每个自然日是否只能签到一次、签到奖励是否发放积分，沿用平台签到配置或由运营另行确认。 + +--- + +## 七、补充等级与积分规则 + +以下内容来自新增的“全方位盈利指南”类说明，建议作为二期/配置化能力评估，是否进入首版需确认。 + +### 7.1 基础规则 + +- 项目产品：澳的利草本饮料小程序。 +- 对外话术：采用“推四免一”分享模式。 +- 用户通过分享码注册并完成首单购买后，获得分享资格。 + +### 7.2 会员等级/分销等级 + +| 等级 | 晋升条件 | 权益/奖励 | +|---|---|---| +| 普通会员 | 扫描分享码注册并完成首单购买 | 获得分享资格；原补充说明中提到分享订单享受 20%、30%、50% 阶梯奖励 | +| 业务主管 | 直推 3 位有效会员 | 团队每新增 1 单奖励 500 积分；积分按每日 0.4%释放 | +| 业务经理 | 团队累计 30 单 | 直推每单额外奖励 800 积分；团队级差奖励 300 积分/单 | +| 业务总监 | 团队累计 100 单 | 直推每单额外奖励 1000 积分；享受团队差补，业务经理差补 200 积分/单，业务主管差补 500 积分/单 | + +### 7.3 积分与平级规则 + +- 小程序内任意套餐包均可购买。 +- 在商城选购商品达到套餐包价值，同样计算为成功购买/分享一单。 +- 平级会员不可同时享受积分，新增奖励归属新增级。 +- 积分按千分之四每日释放。 +- 已释放积分可在商城兑换产品。 + +### 7.4 奖励使用限制 + +补充说明中提到“所得奖励不能提现，可以直接在平台下单黄金”。该口径与主规则中的“扣除 7% 后发放/提现”存在冲突，需要确认： + +- 奖励是否允许提现。 +- 奖励是否仅可用于平台内消费。 +- “黄金”是否属于平台商品、积分兑换品或特定业务资产。 + +### 7.5 招商合作 + +补充说明中包含代理商招募规则： + +- 招募代理商限定名额：49 名。 +- 加入条件：一次性购买 19800 元产品。 +- 代理商权益： + - 获得 19800 元产品。 + - 每月加权分红，直到累计达到 3 倍为止。 + - 达到 3 倍后，业绩前 10 名进入永久股东。 + - 上市前拥有优先认购原始股权利。 + - 赠送价值 2 万元的张大师字画一副。 + +该部分涉及招商、分红、股东权益和商品赠品，建议作为独立合规/运营方案确认，不默认纳入小程序首版功能。 + +--- + +## 八、场景示例 + +### 场景一：正常完成 + +1. 会员 A 消费累计 5000 元。 +2. 系统生成 1 个推广任务，待推广金额剩余 667 元。 +3. 会员 A 推荐好友 B、C、D、E 各完成 1 个有效订单。 +4. 任务完成，税前奖励 4333 元。 +5. 扣除 7% 税费/手续费后，到账 4029.69 元。 + +### 场景二：提前兑现 + +1. 会员 A 消费累计 4333 元。 +2. 系统生成 1 个推广任务。 +3. 会员 A 推荐成功 2 单后申请提前兑现。 +4. 税前奖励为 4333 × (10% + 20%) = 1299.90 元。 +5. 扣除 7% 税费/手续费 90.99 元后，到账 1208.91 元。 +6. 任务关闭，后续订单不再计入该任务。 + +### 场景三：多任务并行 + +1. 会员 A 消费累计 10000 元。 +2. 系统生成 2 个推广任务，待推广金额剩余 1334 元。 +3. 任务 1 完成 4 单，任务 2 完成 2 单。 +4. 任务 1 自动完成结算，任务 2 可继续推进或提前兑现。 + +--- + +## 九、待确认问题 + +| 编号 | 问题 | 当前整理建议 | +|---|---|---| +| Q1 | 主线到底是“推四免一”还是补充说明中的“推三免一”？ | 首版按“推四免一”执行，推三免一视为旧口径或待确认内容 | +| Q2 | 奖励比例是 10%/20%/30%/40%，还是 20%/30%/50%？ | 推广任务按 10%/20%/30%/40%；20%/30%/50% 标为待确认补充规则 | +| Q3 | 奖励是否能提现？ | 当前主规则按扣 7% 后发放；“不能提现、用于下单黄金”需另行确认 | +| Q4 | 积分等级体系是否进入首版？ | 建议首版先聚焦推四免一，等级积分作为后续配置化能力 | +| Q5 | 下级生成任务是否计入上级任务？ | 建议保留配置开关，避免与推荐订单确认收货重复计数 | +| Q6 | 任意套餐包是否都可计入有效订单？ | 建议明确只有参与规则的报单商品/套餐包计入 | +| Q7 | 完成 4 单是否也扣 7%？ | 当前整理为所有结算均扣 7% | +| Q8 | 招商合作是否需要系统功能支持？ | 建议作为独立运营方案，不纳入首版默认需求 | + +--- + +## 十、一句话总结 + +每累计 4333 元有效消费生成 1 个“推四免一”推广任务，推荐 4 个有效订单可获得 4333 元税前奖励，也可在完成 1-3 单时提前兑现；等级积分、奖励使用限制和招商合作属于补充口径，需运营确认后再进入产品方案。 diff --git a/docs/project-shaoyaoju/secondary-development-guide.md b/docs/project-shaoyaoju/secondary-development-guide.md new file mode 100644 index 00000000..9cd0b53d --- /dev/null +++ b/docs/project-shaoyaoju/secondary-development-guide.md @@ -0,0 +1,1471 @@ +# 芍药居项目二次开发详细说明文档 + +> 文档日期：2026-05-02 +> 面向对象：后端研发 +> 技术底座：CRMEB Pro v3.5.1 + 当前 fsgx/HJF 二开代码 +> 业务依据：`docs/project-shaoyaoju/PRD_shaoyaoju_V1.0.md` +> 差异依据：`docs/project-shaoyaoju/syj-fsgx-diff.md` +> 代码根目录：`pro_v3.5.1` + +--- + +## 1. 开发目标 + +芍药居项目不是重写一套商城、分销、积分或会员系统，而是在当前项目代码基础上增加一层“推四免一有效推广任务”的业务适配层。 + +核心目标： + +1. 用户有效消费金额每满 `4333` 元，自动生成 `1` 个“推四免一有效推广任务”。 +2. 每个推广任务在系统侧等价当前代码中的 `1` 个 `is_queue_goods=1` 报单商品订单触发基准。 +3. 推广任务创建后，继续复用当前代码的分销返佣、积分奖励、分销等级、后台分销等级任务、积分日志和佣金流水。 +4. 推广任务自身负责记录推四免一进度、4 单完成结算、1-3 单提前兑现、后台审核和追溯。 +5. 返佣时机不为芍药居单独固定，复用当前代码的 `brokerage_timing` 配置。 + +一句话落地口径： + +```text +有效消费金额 floor(amount / 4333) + -> 生成 N 个推四免一有效推广任务 + -> 每个任务等价当前 1 个报单商品订单触发单位 + -> 复用分销奖金、积分奖励、分销等级任务 + -> 任务自身记录推四免一进度和结算 +``` + +--- + +## 2. 术语边界 + +| 术语 | 本项目含义 | 不等同于 | +|---|---|---| +| 推广任务 | 推四免一有效推广任务维度，由用户有效消费累计满 4333 元生成 | 后台分销等级任务 | +| 等价报单触发单位 | 为复用当前代码，将 1 个推广任务视为当前 1 个 `is_queue_goods=1` 报单商品订单触发基准 | 必须真实创建商城订单 | +| 分销等级 | 当前代码 `eb_agent_level` 与 `eb_user.agent_level` 体系 | 新建会员等级表 | +| 分销等级任务 | 当前后台配置的 `eb_agent_level_task` 升级任务 | 推四免一任务本身 | +| 积分奖励 | 当前 HJF/FSGX 的冻结积分、积分日志、释放逻辑 | 新建独立积分账户 | +| 返佣时机 | 当前 `brokerage_timing` 配置决定的发放节点 | 芍药居固定支付或固定确认收货 | + +开发时必须避免把“推四免一有效推广任务”写成新的分销等级任务。二者关系是：推广任务作为业务来源，按等价报单触发单位计入当前后台配置的分销等级任务。 + +--- + +## 3. 当前代码能力地图 + +### 3.1 订单支付主链路 + +| 链路 | 当前代码 | 说明 | +|---|---|---| +| 支付成功入口 | `app/services/order/StoreOrderSuccessServices.php` | `paySuccess()` 更新支付状态后触发 `event('order.pay')` | +| 支付事件监听 | `app/listener/order/Pay.php` | 处理佣金发放、等级检查、积分奖励、订单后置任务 | +| 确认收货 | `app/services/order/StoreOrderTakeServices.php` | `storeProductOrderUserTakeDelivery()` 内处理赠送积分、返佣、经验等 | +| 建单与佣金计算 | `app/services/order/StoreOrderCreateServices.php` | 标记 `is_queue_goods`，计算 `one_brokerage`、`two_brokerage` | + +当前支付事件中已经存在 HJF/FSGX 报单商品处理逻辑： + +- `is_queue_goods=1` 订单会进入报单商品相关处理。 +- `hjf_queue_pool_enable=1` 时走 `HjfOrderPayJob` 异步处理。 +- `hjf_queue_pool_enable=0` 时在 `Pay.php` 中同步执行等级检查和积分奖励。 + +芍药居二开应尽量把新逻辑挂在订单生命周期的明确节点上，不直接改散在页面层或支付回调层。 + +### 3.2 分销返佣能力 + +| 能力 | 当前代码 | 说明 | +|---|---|---| +| 返佣计算 | `StoreOrderCreateServices.php` | 根据商品、推荐人、周期配置计算订单佣金 | +| 返佣发放 | `StoreOrderTakeServices::backOrderBrokerage()` | 写佣金账户、佣金流水，并处理二级返佣 | +| 支付即返 | `listener/order/Pay.php` | 当 `brokerage_timing=on_pay` 时支付后立即调用返佣 | +| 确认后返 | `StoreOrderTakeServices.php` | 当 `brokerage_timing=on_confirm` 时确认收货后返佣 | +| 返佣配置 | `app/services/system/config/SystemConfigServices.php` | `brokerage_cycle_count`、`brokerage_cycle_rates`、`brokerage_scope`、`brokerage_timing` | + +当前返佣时机已由配置控制： + +| 配置值 | 行为 | +|---|---| +| `brokerage_timing=on_pay` | 支付成功后发放佣金，确认收货时跳过返佣 | +| `brokerage_timing=on_confirm` | 支付成功后不发佣金，确认收货后发放佣金 | + +芍药居不新增独立返佣时机配置，只复用该逻辑。 + +### 3.3 积分奖励能力 + +| 能力 | 当前代码 | 说明 | +|---|---|---| +| 积分奖励计算 | `app/services/hjf/PointsRewardServices.php` | 按 `eb_agent_level.direct_reward_points`、`umbrella_reward_points` 计算 | +| 积分释放 | `app/services/hjf/PointsReleaseServices.php` | 使用 `hjf_release_rate` 释放冻结积分 | +| 冻结积分日志 | `app/model/hjf/PointsReleaseLog.php` | 对应 `eb_points_release_log` | +| 营销后台积分日志 | `app/services/user/UserBillServices.php` | 已有 `hjf_reward_direct_integral`、`hjf_reward_umbrella_integral` 类型 | +| 补发工具 | `app/command/HjfPatchMissingRewards.php` | 用于缺失奖励补发场景 | + +当前积分奖励已经具备幂等检查：`points_release_log` 中同一订单、同类奖励存在时跳过重复发放。芍药居推广任务接入时，应保留相同幂等策略，推荐使用 `syj_task_id` 或等价来源单号参与幂等。 + +### 3.4 分销等级与等级任务能力 + +| 能力 | 当前代码 | 说明 | +|---|---|---| +| 分销等级 | `app/services/agent/AgentLevelServices.php` | 使用 `eb_agent_level` | +| 等级任务 | `app/services/agent/AgentLevelTaskServices.php` | 后台配置的升级任务 | +| HJF 会员等级包装 | `app/services/hjf/MemberLevelServices.php` | 薄封装，底层仍复用分销等级 | +| 后台等级配置 | `app/controller/admin/v1/agent/AgentLevel.php`、`AgentLevelTask.php` | 原分销等级与任务配置 | +| HJF 等级后台 | `app/controller/admin/v1/hjf/MemberController.php` | 读取和保存 `eb_agent_level` 的积分奖励字段 | + +芍药居会员等级继续使用 `eb_user.agent_level`。升级任务继续走后台分销等级任务配置，不新增独立会员等级任务表。 + +### 3.5 队列与公排能力 + +当前代码存在 HJF 公排池能力： + +| 能力 | 当前代码 | +|---|---| +| 公排入队 | `app/services/hjf/QueuePoolServices.php` | +| 支付后异步处理 | `app/jobs/hjf/HjfOrderPayJob.php` | +| 退款任务 | `app/jobs/hjf/QueueRefundJob.php` | +| 用户端接口 | `app/controller/api/v1/hjf/QueueController.php` | +| 后台接口 | `app/controller/admin/v1/hjf/QueueController.php` | +| 数据表 | `eb_queue_pool` | + +芍药居 PRD 明确首版不做公排池/排队退款机制。该能力可保留代码但默认关闭，确保 `hjf_queue_pool_enable=0`。推四免一任务不要复用 `eb_queue_pool` 作为主任务表，否则业务含义会混淆。 + +--- + +## 4. 芍药居目标架构 + +### 4.1 推荐分层 + +```text +订单生命周期 + -> 芍药居消费累计服务 + -> 推四免一任务服务 + -> 等价报单触发适配服务 + -> 当前分销返佣 / 积分奖励 / 分销等级任务 + -> 任务进度与结算服务 +``` + +建议新增 `syj` 命名空间，避免继续扩散在 `hjf` 命名空间中。 + +| 层 | 建议服务 | 职责 | +|---|---|---| +| 消费累计 | `SyjPromoteAmountServices` | 统计有效订单金额，生成金额流水，计算可生成任务数 | +| 任务核心 | `SyjPromoteTaskServices` | 创建任务、分配推荐订单、完成任务、提前兑现 | +| 奖励适配 | `SyjPromoteRewardTriggerServices` | 将任务映射为当前报单商品订单触发单位 | +| 结算 | `SyjPromoteSettlementServices` | 处理 4 单完成结算、提前兑现扣费、账单关联 | +| 后台查询 | `SyjPromoteAdminServices` | 任务列表、详情、异常、导出、审核 | + +### 4.2 推广任务生成规则 + +有效金额计算： + +```text +valid_amount = pay_price - refunded_amount +task_count = floor((user_pending_amount + valid_amount) / 4333) +remaining_amount = (user_pending_amount + valid_amount) % 4333 +``` + +首版口径： + +- 以订单实际支付金额 `pay_price` 为基础。 +- 积分抵扣、优惠券抵扣不计入有效消费金额。 +- 运费默认不计入，除非业务另行确认。 +- 发生退款后，未生成任务的累计金额应回滚；已生成任务的订单进入异常或人工处理。 + +推荐挂载节点： + +| 节点 | 推荐动作 | 原因 | +|---|---|---| +| 支付成功 | 不生成任务，最多记录待处理标识 | 避免未确认收货、退款导致任务提前生效 | +| 确认收货 | 生成消费累计和推广任务 | 与“有效订单”口径一致 | +| 售后退款 | 回滚未结算金额或标记任务异常 | 保证金额与任务可追溯 | + +若业务最终要求支付即生成任务，也应通过配置控制，并明确退款回滚策略。 + +### 4.3 等价报单触发规则 + +每个推广任务创建成功后，调用奖励适配服务生成一次“等价报单触发”。 + +触发参数至少包含： + +| 参数 | 说明 | +|---|---| +| `task_id` | 推广任务 ID | +| `uid` | 任务归属用户 | +| `source_order_id` | 生成任务的来源订单 | +| `amount` | 固定或配置为 4333 | +| `trigger_no` | 等价触发单号，建议使用 `SYJ-TASK-{task_id}` | +| `trigger_type` | `syj_promote_task` | +| `qty` | 固定为 1；若一次消费生成多个任务，每个任务独立触发 | + +适配服务职责： + +1. 记录任务触发状态，防止重复触发。 +2. 以等价报单触发单位调用当前分销返佣逻辑。 +3. 调用当前积分奖励逻辑，确保 `points_release_log` 与 `user_bill` 仍有记录。 +4. 调用当前分销等级任务统计逻辑，让后台配置的任务继续生效。 +5. 记录当前任务与佣金流水、积分流水、等级任务记录的关联。 + +注意：如果现有返佣服务强依赖真实 `store_order.id`，不要直接伪造不完整订单数组。应优先抽出统一的“奖励触发上下文”方法，或创建完整可追溯的等价触发记录，再由适配层组装当前服务所需字段。 + +### 4.4 推荐进度规则 + +推广任务生成后，推荐人分享给下级，下级有效订单计入推荐人的任务进度。 + +匹配规则： + +1. 下级订单必须为参与规则商品订单，通常为 `is_queue_goods=1`。 +2. 下级订单达到当前后台返佣设置中的佣金发放时机后才计入任务进度，复用 `brokerage_timing`：`on_pay` 表示支付成功后计入，`on_confirm` 表示确认收货后计入。 +3. 根据订单上的 `spread_uid` 找到推荐人。 +4. 推荐人必须存在未完成、未关闭、未提前兑现的推广任务。 +5. 若推荐人有多个进行中任务，按创建时间从早到晚填充。 +6. 单个下级有效订单默认只能计入一个任务一次。 +7. 同一购买人是否可重复计入多个任务，建议首版允许按订单计入，若运营要求按用户去重再增加配置。 + +任务进度： + +| 计入第几单 | 推荐奖励比例 | 完成状态 | +|---:|---:|---| +| 1 | 10% | 可申请提前兑现 | +| 2 | 20% | 可申请提前兑现 | +| 3 | 30% | 可申请提前兑现 | +| 4 | 40% | 任务完成，结算 4333 元，不扣 7% | + +### 4.5 结算规则 + +完成 4 单： + +- 任务状态改为 `completed`。 +- 结算金额为 `4333` 元。 +- 不扣 `7%`。 +- 入账到当前 CRMEB 佣金账户或业务确认的奖励账户。 +- 写入任务结算流水，关联 `user_bill` 或 `user_brokerage`。 + +提前兑现 1-3 单： + +- 用户发起提前兑现申请。 +- 后台审核通过后关闭任务。 +- 按当前已完成档位计算可兑现奖励。 +- 扣除 `7%` 手续费或税费。 +- 入账后任务状态改为 `cashed_out`。 +- 审核拒绝后任务保持进行中。 + +建议公式： + +```text +gross_amount = 4333 * current_rate +fee_amount = gross_amount * 7% +net_amount = gross_amount - fee_amount +``` + +其中 `current_rate` 为当前已完成档位对应比例：`10%`、`20%`、`30%`。 + +--- + +## 5. 建议新增数据表 + +### 5.1 `eb_syj_promote_task` + +用于保存推四免一有效推广任务。 + +| 字段 | 类型建议 | 说明 | +|---|---|---| +| `id` | int | 主键 | +| `uid` | int | 任务归属用户 | +| `task_no` | varchar(64) | 任务编号 | +| `source_order_id` | int | 来源订单主键 | +| `source_order_no` | varchar(64) | 来源订单号 | +| `base_amount` | decimal(10,2) | 任务基准金额，默认 4333 | +| `status` | tinyint | 0 进行中，1 已完成，2 提前兑现，3 已关闭，4 异常 | +| `progress_count` | tinyint | 已完成推荐单数 | +| `target_count` | tinyint | 目标单数，默认 4 | +| `reward_trigger_status` | tinyint | 等价报单触发状态 | +| `reward_trigger_no` | varchar(64) | 等价触发单号 | +| `finish_time` | int | 完成时间 | +| `cashout_time` | int | 提前兑现时间 | +| `add_time` | int | 创建时间 | +| `update_time` | int | 更新时间 | + +建议索引： + +- `idx_uid_status (uid, status)` +- `idx_source_order (source_order_id)` +- `uniq_task_no (task_no)` +- `uniq_reward_trigger_no (reward_trigger_no)` + +### 5.2 `eb_syj_promote_amount_log` + +用于记录用户待推广金额累计与扣减。 + +| 字段 | 类型建议 | 说明 | +|---|---|---| +| `id` | int | 主键 | +| `uid` | int | 用户 | +| `order_id` | int | 来源订单 | +| `amount` | decimal(10,2) | 本次变动金额 | +| `before_amount` | decimal(10,2) | 变动前待推广金额 | +| `after_amount` | decimal(10,2) | 变动后待推广金额 | +| `type` | varchar(32) | `income`、`consume_task`、`refund_rollback`、`manual_adjust` | +| `link_id` | int | 关联任务或退款记录 | +| `mark` | varchar(255) | 说明 | +| `add_time` | int | 创建时间 | + +用户当前待推广金额可放在独立余额表，也可通过流水聚合。考虑查询效率，建议增加用户扩展字段或独立汇总表。 + +### 5.3 `eb_syj_promote_task_record` + +用于记录推荐订单计入任务进度。 + +| 字段 | 类型建议 | 说明 | +|---|---|---| +| `id` | int | 主键 | +| `task_id` | int | 推广任务 | +| `uid` | int | 推荐人 | +| `order_uid` | int | 下单用户 | +| `order_id` | int | 下级订单 | +| `order_no` | varchar(64) | 下级订单号 | +| `source_type` | varchar(32) | 来源类型：`order_pay`、`order_confirm`、`task_created`、`manual` | +| `trigger_timing` | varchar(32) | 推荐订单计入时使用的 `brokerage_timing` 快照 | +| `step_no` | tinyint | 第几单，1-4 | +| `reward_rate` | decimal(5,2) | 对应比例 | +| `status` | tinyint | 1 有效，2 已退款失效 | +| `add_time` | int | 创建时间 | + +建议增加唯一索引 `uniq_order_task (order_id, task_id)` 或 `uniq_order (order_id)`，避免同一订单重复计入。 + +### 5.4 `eb_syj_promote_settlement` + +用于任务完成或提前兑现结算。 + +| 字段 | 类型建议 | 说明 | +|---|---|---| +| `id` | int | 主键 | +| `task_id` | int | 推广任务 | +| `uid` | int | 用户 | +| `settle_type` | varchar(32) | `complete`、`early_cashout` | +| `gross_amount` | decimal(10,2) | 应结算金额 | +| `fee_rate` | decimal(5,2) | 手续费/税费比例 | +| `fee_amount` | decimal(10,2) | 扣费金额 | +| `net_amount` | decimal(10,2) | 实到账 | +| `bill_id` | int | 关联账单 | +| `brokerage_id` | int | 关联佣金流水 | +| `audit_status` | tinyint | 0 待审核，1 通过，2 拒绝 | +| `audit_uid` | int | 审核管理员 | +| `audit_remark` | varchar(255) | 审核说明 | +| `audit_time` | int | 审核时间 | +| `add_time` | int | 创建时间 | + +### 5.5 `eb_syj_promote_reward_trigger` + +用于记录推广任务触发现有奖励链路的结果。 + +| 字段 | 类型建议 | 说明 | +|---|---|---| +| `id` | int | 主键 | +| `task_id` | int | 推广任务 | +| `uid` | int | 任务用户 | +| `trigger_no` | varchar(64) | 等价触发单号 | +| `trigger_amount` | decimal(10,2) | 触发金额，默认 4333 | +| `brokerage_status` | tinyint | 分销返佣触发状态 | +| `points_status` | tinyint | 积分奖励触发状态 | +| `level_task_status` | tinyint | 分销等级任务触发状态 | +| `brokerage_link_id` | varchar(255) | 关联佣金流水，可存 JSON | +| `points_link_id` | varchar(255) | 关联积分流水，可存 JSON | +| `level_task_link_id` | varchar(255) | 关联等级任务记录，可存 JSON | +| `error_msg` | varchar(500) | 失败原因 | +| `add_time` | int | 创建时间 | +| `update_time` | int | 更新时间 | + +--- + +## 6. 配置项 + +### 6.1 继续复用当前配置 + +| 配置 | 当前含义 | 芍药居口径 | +|---|---|---| +| `brokerage_cycle_count` | 周期人数 | 建议设为 `4` | +| `brokerage_cycle_rates` | 周期比例 JSON | 建议设为 `[10,20,30,40]` | +| `brokerage_scope` | 返佣范围 | 默认 `queue_only` 或按运营确定 | +| `brokerage_timing` | 佣金发放时机 | 继续复用，支持 `on_pay`、`on_confirm` | +| `hjf_release_rate` | 积分释放比例 | 继续用于当前积分释放 | +| `hjf_umbrella_reward_enable` | 伞下积分奖励开关 | 继续复用 | + +### 6.2 建议新增芍药居配置 + +| 配置 | 默认值 | 说明 | +|---|---:|---| +| `syj_task_base_amount` | `4333` | 每满多少有效消费生成 1 个推广任务 | +| `syj_task_target_count` | `4` | 推四免一目标单数 | +| `syj_task_reward_rates` | `[10,20,30,40]` | 任务进度比例 | +| `syj_early_cashout_fee_rate` | `7` | 提前兑现扣费比例 | +| `syj_task_generate_timing` | `on_confirm` | 任务生成节点，首版建议确认收货 | +| `syj_task_order_dedupe` | `order` | 推荐订单计入方式，首版按订单 | +| `syj_reward_trigger_enable` | `1` | 是否启用任务等价报单触发 | + +### 6.3 必须关闭或谨慎使用的配置 + +| 配置 | 建议 | 原因 | +|---|---|---| +| `hjf_queue_pool_enable` | `0` | 芍药居首版不做公排池/排队退款 | +| `hjf_trigger_multiple` | 保留 | 仅 HJF 公排使用，不作为芍药居推四免一主配置 | +| `hjf_withdraw_fee_rate` | 不直接复用 | 芍药居提前兑现扣 7% 应放入任务结算配置 | + +--- + +## 7. 后端开发落点 + +### 7.1 订单确认收货接入 + +推荐在 `StoreOrderTakeServices::storeProductOrderUserTakeDelivery()` 成功完成原逻辑后，触发芍药居消费累计。 + +接入原则： + +1. 原有赠送积分、返佣、经验、事业部逻辑保持不变。 +2. 只对 `is_queue_goods=1` 的有效订单累计。 +3. 使用事务或幂等记录，避免确认收货重复调用导致重复生成任务。 +4. 订单退款、售后状态不满足时不生成任务。 + +建议伪流程： + +```text +确认收货成功 + -> 判断订单 is_queue_goods=1 + -> 判断订单未生成过 syj 消费累计流水 + -> 计算有效金额 + -> 写入 syj_promote_amount_log + -> floor(累计金额 / 4333) 生成任务 + -> 每个任务调用 SyjPromoteRewardTriggerServices +``` + +### 7.2 支付事件接入 + +当前 `listener/order/Pay.php` 已经处理 `brokerage_timing=on_pay` 的返佣。芍药居不应破坏这个逻辑。 + +如任务生成节点为 `on_confirm`，支付事件只需要保留现状。如后续配置为支付即生成任务，可在 `Pay.php` 中增加独立开关判断，但必须保证： + +- 同一订单只触发一次。 +- 售后退款能回滚或标记异常。 +- `brokerage_timing=on_pay` 不导致同一等价任务重复返佣。 + +### 7.3 返佣适配 + +当前返佣逻辑主要依赖订单字段： + +| 字段 | 用途 | +|---|---| +| `uid` | 下单用户 | +| `spread_uid` | 一级推荐人 | +| `spread_two_uid` | 二级推荐人 | +| `pay_price` | 订单金额 | +| `one_brokerage` | 一级佣金 | +| `two_brokerage` | 二级佣金 | +| `is_queue_goods` | 是否报单商品 | +| `id` | 账单关联 ID | +| `order_id` | 订单号 | + +芍药居任务触发返佣时有两种实现路径： + +| 路径 | 说明 | 推荐度 | +|---|---|---| +| 抽出统一奖励触发上下文 | 将当前订单返佣逻辑改造成可接收 `order` 或 `syj_task` 上下文 | 推荐 | +| 构造完整虚拟订单数组 | 由适配服务组装当前方法所需字段 | 可用，但必须完整追溯 | +| 创建真实商城订单 | 为任务创建系统订单 | 不推荐，容易污染订单统计和财务 | + +必须做到： + +- `brokerage_timing` 仍决定发放节点。 +- 同一 `task_id` 不重复发放佣金。 +- 佣金流水能追溯到任务和来源订单。 +- 返佣失败可重试，不影响任务主记录创建。 + +### 7.4 积分奖励适配 + +当前 `PointsRewardServices::reward()` 参数为： + +```php +reward(int $orderUid, string $orderId, int $orderDbId = 0, array $preUpgradeLevels = [], int $qty = 1) +``` + +芍药居推广任务可以按以下方式复用： + +- `orderUid` 使用任务归属用户。 +- `orderId` 使用等价触发单号，例如 `SYJ-TASK-10001`。 +- `orderDbId` 若没有真实订单，可传来源订单 ID，或扩展为支持任务来源。 +- `qty` 固定为 `1`。 +- `preUpgradeLevels` 仍在触发前快照推荐链路用户等级。 + +建议增强： + +1. `points_release_log` 增加或通过 `order_id` 标记任务来源。 +2. `UserBillServices` 写入积分日志时保留任务编号。 +3. 幂等条件从 `order_id + type` 扩展为 `trigger_no + type`，避免补偿任务重复发放。 + +### 7.5 分销等级任务适配 + +当前等级任务统计位于 `AgentLevelTaskServices`。代码里已有对 `is_queue_goods` 报单商品订单数量的统计能力。 + +芍药居二开要实现： + +- 推广任务创建后，按 1 个等价报单触发单位计入后台分销等级任务。 +- 后台仍由运营配置分销等级任务，不新增独立会员等级任务。 +- 若当前统计完全从 `store_order` 查询，需要补充统计来源，让 `syj_promote_task` 也能计入。 + +推荐改造方式： + +| 方式 | 说明 | +|---|---| +| 统计服务抽象 | 将“报单订单数”改为“有效任务触发数”，内部合并真实订单与 syj 任务 | +| 增加任务来源查询 | 在 `AgentLevelTaskServices` 中增加 syj 任务计数 | +| 数据镜像 | 将 syj 任务写入一个统一触发表，等级任务统一查该表 | + +首选“统一触发表”或“统计服务抽象”，避免在多处 SQL 中重复拼接任务逻辑。 + +### 7.6 推荐订单计入任务 + +推荐订单计入任务进度的节点复用当前代码后台返佣设置中的佣金发放时机配置项 `brokerage_timing`： + +| 配置 | 推荐订单计入任务节点 | 复用代码节点 | +|---|---|---| +| `on_pay` | 下级订单支付成功后计入 | `listener/order/Pay.php` 的支付成功事件 | +| `on_confirm` | 下级订单确认收货后计入 | `StoreOrderTakeServices::storeProductOrderUserTakeDelivery()` | + +执行任务进度匹配： + +```text +下级订单达到 brokerage_timing 对应节点 + -> 订单 is_queue_goods=1 + -> 读取 order.spread_uid + -> 查询推荐人最早的进行中 syj_promote_task + -> 写 syj_promote_task_record + -> task.progress_count + 1 + -> progress_count = 4 时完成结算 +``` + +需要注意： + +- 同一订单不能重复计入。 +- 任务计入节点必须与当前 `brokerage_timing` 一致，不为芍药居单独固定支付成功或确认收货。 +- 推荐人没有进行中任务时，不创建任务进度。 +- 订单退款时，若任务未结算应回滚进度；若已结算应进入异常处理或人工复核。 +- 多任务并行时，优先填充最早任务。 + +### 7.7 提前兑现与后台审核 + +用户端： + +- 展示当前进行中任务。 +- 当 `progress_count` 为 1-3 时允许发起提前兑现。 +- 已完成 4 单的任务不走提前兑现，直接完成结算。 + +后台： + +- 待审核列表。 +- 任务详情。 +- 审核通过：扣 7%，入账，关闭任务。 +- 审核拒绝：任务继续进行。 + +审核通过必须使用事务： + +```text +锁定任务 + -> 校验状态仍为进行中 + -> 校验进度为 1-3 + -> 计算 gross / fee / net + -> 写入佣金或账单 + -> 写 settlement + -> 更新任务状态 +``` + +--- + +## 8. 接口建议 + +### 8.1 用户端接口 + +建议新增 `/api/syj/promote/*`。 + +| 接口 | 方法 | 说明 | +|---|---|---| +| `/api/syj/promote/overview` | GET | 我的推广任务概览 | +| `/api/syj/promote/task/list` | GET | 我的任务列表 | +| `/api/syj/promote/task/:id` | GET | 任务详情 | +| `/api/syj/promote/task/:id/records` | GET | 推荐订单进度 | +| `/api/syj/promote/task/:id/cashout` | POST | 发起提前兑现 | +| `/api/syj/promote/amount/log` | GET | 待推广金额流水 | +| `/api/syj/promote/settlement/list` | GET | 结算记录 | + +任务概览建议返回： + +```json +{ + "pending_amount": "866.00", + "base_amount": "4333.00", + "active_task_count": 2, + "completed_task_count": 3, + "cashout_task_count": 1, + "available_cashout_amount": "1299.90" +} +``` + +### 8.2 后台接口 + +建议新增 `/adminapi/syj/promote/*`。 + +| 接口 | 方法 | 说明 | +|---|---|---| +| `/adminapi/syj/promote/task/list` | GET | 任务列表 | +| `/adminapi/syj/promote/task/:id` | GET | 任务详情 | +| `/adminapi/syj/promote/task/:id/records` | GET | 任务进度 | +| `/adminapi/syj/promote/cashout/list` | GET | 提前兑现审核列表 | +| `/adminapi/syj/promote/cashout/:id/audit` | POST | 审核提前兑现 | +| `/adminapi/syj/promote/settlement/list` | GET | 结算流水 | +| `/adminapi/syj/promote/config` | GET/POST | 任务配置 | +| `/adminapi/syj/promote/retry-trigger/:task_id` | POST | 重试奖励触发 | + +后台列表筛选建议： + +- 用户 ID / 手机号 / 昵称 +- 任务编号 +- 来源订单号 +- 状态 +- 创建时间 +- 是否触发奖励成功 +- 是否存在异常 + +--- + +## 9. 管理端与用户端页面影响 + +### 9.1 用户端 + +建议新增或改造： + +| 页面 | 功能 | +|---|---| +| 我的推广任务 | 展示进行中、已完成、已兑现、异常任务 | +| 任务详情 | 展示 4 单进度、每单订单、奖励比例、可兑现信息 | +| 提前兑现 | 用户确认提前兑现，展示扣 7% 后到账金额 | +| 资产页 | 继续展示佣金、积分、等级，文案改为芍药居 | +| 推广中心 | 增加任务入口，继续复用分享关系能力 | + +页面文案要避免出现 fsgx 旧口径，例如“推三免一”“20/30/50”“公排退款”等。 + +### 9.2 管理后台 + +建议新增： + +| 页面 | 功能 | +|---|---| +| 推广任务列表 | 查询任务状态、用户、来源订单、进度 | +| 推广任务详情 | 查看任务进度、等价奖励触发记录、积分/佣金流水 | +| 提前兑现审核 | 审核通过/拒绝，展示扣费计算 | +| 任务配置 | 4333、4 单、10/20/30/40、7% 等配置 | +| 异常任务 | 奖励触发失败、退款冲突、重复计入等问题处理 | + +继续复用： + +- 商品管理 +- 订单管理 +- 分销等级与分销等级任务配置 +- 分销员管理 +- 积分日志 +- 佣金流水 +- 提现审核 + +--- + +## 10. 数据迁移与初始化 + +当前项目已有迁移参考： + +| 文件 | 说明 | +|---|---| +| `database/hjf_migration.sql` | HJF/FSGX 表和字段迁移 | +| `help/migrations/fsgx_v1.sql` | fsgx 初始迁移参考 | +| `database/hjfshop.sql` | 包含部分 HJF 表结构 | + +芍药居应新增独立迁移文件，例如： + +```text +database/syj_migration.sql +``` + +迁移内容： + +1. 创建 `eb_syj_promote_task`。 +2. 创建 `eb_syj_promote_amount_log`。 +3. 创建 `eb_syj_promote_task_record`。 +4. 创建 `eb_syj_promote_settlement`。 +5. 创建 `eb_syj_promote_reward_trigger`。 +6. 插入 `syj_*` 配置项。 +7. 确保 `brokerage_cycle_count=4`、`brokerage_cycle_rates=[10,20,30,40]` 可由后台配置覆盖。 +8. 确保 `hjf_queue_pool_enable=0`。 + +数据初始化建议： + +- 新增商品默认 `is_queue_goods=1`。 +- 旧商品是否批量设为 `1` 由运营确认。 +- 已有用户等级继续使用 `eb_user.agent_level`，不迁移到新表。 +- 已有积分奖励字段继续使用 `eb_agent_level.direct_reward_points`、`umbrella_reward_points`。 + +--- + +## 11. 幂等、事务与异常处理 + +### 11.1 幂等点 + +| 场景 | 幂等键 | +|---|---| +| 订单消费累计 | `order_id + type=income` | +| 任务生成 | `source_order_id + split_index` | +| 等价奖励触发 | `task_id` 或 `reward_trigger_no` | +| 积分奖励 | `reward_trigger_no + reward_type` | +| 推荐订单计入 | `order_id` 或 `order_id + task_id` | +| 完成结算 | `task_id + settle_type=complete` | +| 提前兑现 | `task_id + settle_type=early_cashout` | + +### 11.2 事务边界 + +必须使用事务的场景： + +- 确认收货后累计金额并生成任务。 +- 任务创建后写奖励触发记录。 +- 推荐订单计入任务进度。 +- 第 4 单完成任务并结算。 +- 提前兑现审核通过。 +- 退款导致任务回滚或异常标记。 + +### 11.3 异常处理 + +| 异常 | 处理建议 | +|---|---| +| 奖励触发失败 | 任务保留，`reward_trigger_status=failed`，后台允许重试 | +| 积分发放失败 | 记录失败原因，允许按任务重试 | +| 返佣失败 | 不重复生成任务，单独重试返佣触发 | +| 推荐订单退款 | 未结算任务回滚进度，已结算任务进入异常 | +| 来源订单退款 | 未触发任务回滚累计，已生成任务标记异常或人工处理 | +| 并发确认收货 | 使用唯一索引和事务锁避免重复生成任务 | +| 并发推荐订单 | 锁定任务行，按最早任务顺序写入进度 | + +--- + +## 12. 测试与验收场景 + +### 12.1 任务生成 + +| 场景 | 期望 | +|---|---| +| 订单有效金额 `4332` | 不生成推广任务，不触发任务维度奖励 | +| 订单有效金额 `4333` | 生成 1 个推广任务，剩余待推广金额为 0 | +| 订单有效金额 `8666` | 生成 2 个推广任务 | +| 订单有效金额 `9000` | 生成 2 个推广任务，剩余 334 | +| 多个小额订单累计满 4333 | 在达到阈值的确认收货节点生成任务 | +| 同一订单重复确认收货回调 | 不重复生成任务 | + +### 12.2 奖励触发 + +| 场景 | 期望 | +|---|---| +| 生成 1 个推广任务 | 触发一次等价报单奖励 | +| 生成 2 个推广任务 | 触发两次等价报单奖励 | +| 积分奖励重复调用 | `points_release_log` 和 `user_bill` 不重复写入 | +| 分销等级任务 | 推广任务计入当前后台配置的分销等级任务 | +| 任务触发失败后重试 | 不重复创建任务，只补触发失败部分 | + +### 12.3 返佣时机 + +| 配置 | 验收 | +|---|---| +| `brokerage_timing=on_pay` | 支付后返佣，确认收货不重复返佣 | +| `brokerage_timing=on_confirm` | 支付后不返佣，确认收货后返佣 | + +### 12.4 推荐进度 + +| 场景 | 期望 | +|---|---| +| 推荐人无进行中任务 | 下级订单不计入推四免一进度 | +| 推荐人有 1 个任务 | 下级有效订单计入该任务 | +| 推荐人有多个任务 | 优先计入最早创建的进行中任务 | +| `brokerage_timing=on_pay` | 下级订单支付成功后匹配并计入任务进度 | +| `brokerage_timing=on_confirm` | 下级订单确认收货后匹配并计入任务进度 | +| 第 4 单达到计入节点 | 任务完成，结算 4333，不扣 7% | +| 已计入订单退款 | 未结算任务回滚进度，已结算任务标记异常 | + +### 12.5 提前兑现 + +| 场景 | 期望 | +|---|---| +| 进度 0 单 | 不允许提前兑现 | +| 进度 1-3 单 | 允许申请提前兑现 | +| 审核通过 | 扣 7%，入账，任务关闭 | +| 审核拒绝 | 任务继续进行 | +| 已完成 4 单 | 不走提前兑现，按完成结算 | + +### 12.6 配置与后台 + +| 场景 | 期望 | +|---|---| +| 修改 4333 基准金额 | 新任务按新配置生成，旧任务保留原基准 | +| 修改 10/20/30/40 比例 | 新任务按新配置，旧任务按创建时快照 | +| 后台查看任务详情 | 能看到来源订单、推荐订单、奖励触发、积分/佣金流水 | +| 后台重试奖励触发 | 只补失败部分，不重复发放成功部分 | + +--- + +## 13. 按功能拆分开发清单 + +本章用于把开发说明拆成可排期、可验收的功能包。每个功能包均包含前端、后端、数据库、配置/权限、Checklist。实施时建议按功能包建任务，后端先完成接口契约和测试数据，前端再并行联调。 + +### 13.1 基础配置与初始化 + +**功能目标** + +建立芍药居二开所需的基础配置、菜单、权限和默认数据，保证后续任务生成、奖励触发、结算审核都能读取统一配置。 + +**前端** + +| 端 | 开发项 | 说明 | +|---|---|---| +| Admin | 新增芍药居配置页 | 管理 `4333` 基准金额、目标单数、奖励比例、提前兑现扣费、任务生成节点 | +| Admin | 菜单与权限 | 增加“芍药居/推广任务/任务配置”菜单，按当前后台权限体系挂载 | +| 用户端 | 暂无独立页面 | 用户端读取配置展示由任务页统一处理 | + +**后端** + +| 模块 | 开发项 | 说明 | +|---|---|---| +| 配置服务 | `SyjPromoteConfigServices` | 封装 `syj_*` 配置读取，统一默认值和类型转换 | +| 后台接口 | `GET/POST /adminapi/syj/promote/config` | 获取和保存配置 | +| 校验 | 配置保存校验 | 金额大于 0，目标单数大于 0，比例数组长度与目标单数一致，扣费比例 0-100 | + +**数据库** + +| 项 | 说明 | +|---|---| +| `eb_system_config` | 插入 `syj_task_base_amount`、`syj_task_target_count`、`syj_task_reward_rates`、`syj_early_cashout_fee_rate`、`syj_task_generate_timing`、`syj_reward_trigger_enable` | +| 后台权限表 | 按当前系统菜单/权限表增加芍药居配置和任务管理权限 | + +**配置/默认值** + +| 配置 | 默认值 | +|---|---| +| `syj_task_base_amount` | `4333` | +| `syj_task_target_count` | `4` | +| `syj_task_reward_rates` | `[10,20,30,40]` | +| `syj_early_cashout_fee_rate` | `7` | +| `syj_task_generate_timing` | `on_confirm` | +| `syj_reward_trigger_enable` | `1` | +| `hjf_queue_pool_enable` | `0` | + +**Checklist** + +- [ ] 新增 `syj_*` 配置项迁移脚本。 +- [ ] 配置读取服务能返回正确默认值。 +- [ ] 后台配置页保存后立即生效。 +- [ ] `hjf_queue_pool_enable` 默认关闭。 +- [ ] 配置保存有边界校验和错误提示。 +- [ ] 后台菜单和权限能控制配置页访问。 + +### 13.2 消费累计与推广任务生成 + +**功能目标** + +订单达到有效节点后，将用户有效消费金额计入待推广金额；每满 `4333` 元自动生成 1 个推四免一有效推广任务。 + +**前端** + +| 端 | 开发项 | 说明 | +|---|---|---| +| 用户端 | 任务概览展示 | 展示待推广金额、距下一个任务差额、已生成任务数 | +| 用户端 | 订单支付/确认提示 | 支付成功页或订单详情提示“确认收货后计入推广任务” | +| Admin | 任务详情来源展示 | 后台任务详情展示来源订单、生成金额和拆分序号 | + +**后端** + +| 模块 | 开发项 | 说明 | +|---|---|---| +| 订单接入 | 确认收货后触发累计 | 推荐接入 `StoreOrderTakeServices::storeProductOrderUserTakeDelivery()` 成功后 | +| 金额服务 | `SyjPromoteAmountServices::recordOrderAmount()` | 计算有效金额，写累计流水 | +| 任务服务 | `SyjPromoteTaskServices::generateByAmount()` | 根据累计金额拆分生成任务 | +| 幂等 | 订单累计幂等 | 同一订单只能写一次 `income` 流水 | +| 并发 | 用户维度锁 | 同一用户多个订单并发确认时，串行计算待推广金额 | + +**数据库** + +| 表 | 用途 | +|---|---| +| `eb_syj_promote_amount_log` | 记录订单计入、任务扣减、退款回滚、人工调整 | +| `eb_syj_promote_task` | 保存推广任务主体 | +| 用户汇总字段或汇总表 | 保存当前待推广金额，避免每次聚合流水 | + +建议在任务表保存配置快照： + +| 字段 | 说明 | +|---|---| +| `base_amount` | 创建任务时的基准金额 | +| `target_count` | 创建任务时的目标单数 | +| `reward_rates` | 创建任务时的奖励比例 JSON | +| `fee_rate` | 创建任务时的提前兑现扣费比例 | + +**配置/权限/依赖** + +| 项 | 说明 | +|---|---| +| `syj_task_base_amount` | 控制每个任务的消费金额门槛 | +| `syj_task_generate_timing` | 首版建议 `on_confirm`，若改为 `on_pay` 必须补退款回滚 | +| 订单状态依赖 | 依赖订单已支付、未删除、达到有效节点 | +| 商品依赖 | 订单或商品需满足 `is_queue_goods=1` | + +**Checklist** + +- [ ] `4332` 元有效金额不生成任务。 +- [ ] `4333` 元有效金额生成 1 个任务。 +- [ ] `8666` 元有效金额生成 2 个任务。 +- [ ] 多笔小额订单累计满额后能生成任务。 +- [ ] 同一订单重复确认收货不重复累计。 +- [ ] 并发确认收货不会重复生成或扣减待推广金额。 +- [ ] 任务保存创建时的配置快照。 +- [ ] 来源订单、来源金额、任务编号可在后台追溯。 + +### 13.3 等价报单奖励触发 + +**功能目标** + +推广任务创建后，按当前代码的 1 个 `is_queue_goods=1` 报单商品订单触发基准，复用分销返佣、积分奖励和分销等级任务。 + +**前端** + +| 端 | 开发项 | 说明 | +|---|---|---| +| 用户端 | 任务详情奖励状态 | 展示“奖励触发中/已触发/触发失败待处理” | +| 用户端 | 积分/佣金入口 | 继续跳转当前积分日志、佣金记录页面 | +| Admin | 奖励触发详情 | 展示分销、积分、等级任务触发结果和失败原因 | +| Admin | 重试按钮 | 对失败任务提供“重试奖励触发” | + +**后端** + +| 模块 | 开发项 | 说明 | +|---|---|---| +| 适配服务 | `SyjPromoteRewardTriggerServices` | 统一处理推广任务到现有奖励链路的映射 | +| 返佣 | 调用当前返佣入口 | 必须尊重 `brokerage_timing`，不绕开现有时机 | +| 积分 | 调用 `PointsRewardServices::reward()` | 使用等价触发单号作为幂等来源 | +| 等级任务 | 调用或扩展 `AgentLevelTaskServices` | 推广任务按 1 个有效报单触发单位计入 | +| 补偿 | 重试接口/命令 | 只补失败部分，成功部分不可重复 | + +**数据库** + +| 表 | 用途 | +|---|---| +| `eb_syj_promote_reward_trigger` | 保存任务触发分销、积分、等级任务的状态 | +| `eb_points_release_log` | 继续保存冻结积分奖励日志 | +| `eb_user_bill` | 继续保存后台可见积分日志 | +| 佣金流水表 | 继续保存现有分销佣金记录 | +| 分销等级任务记录表 | 继续保存现有任务完成记录 | + +**配置/权限/依赖** + +| 项 | 说明 | +|---|---| +| `syj_reward_trigger_enable` | 控制推广任务是否触发现有奖励链路 | +| `brokerage_timing` | 控制佣金发放节点，必须完全复用当前逻辑 | +| `hjf_umbrella_reward_enable` | 控制伞下积分奖励是否发放 | +| 后台权限 | 重试奖励触发必须限制为运营/管理员权限 | + +**Checklist** + +- [ ] 1 个任务只触发 1 次等价报单奖励。 +- [ ] 2 个任务触发 2 次等价报单奖励。 +- [ ] 积分奖励幂等，不重复写 `points_release_log`。 +- [ ] 后台积分日志能看到任务触发的积分记录。 +- [ ] 分销等级任务按推广任务计数。 +- [ ] `brokerage_timing=on_pay` 时不出现确认收货重复返佣。 +- [ ] `brokerage_timing=on_confirm` 时不出现支付后提前返佣。 +- [ ] 奖励触发失败可后台重试。 +- [ ] 重试不会重复发放已成功的佣金或积分。 + +### 13.4 推荐订单计入任务进度 + +**功能目标** + +下级有效订单按推荐关系计入推荐人的推四免一任务进度，计入节点复用当前后台返佣设置中的 `brokerage_timing`：`on_pay` 支付成功后计入，`on_confirm` 确认收货后计入，满 4 单完成任务。 + +**前端** + +| 端 | 开发项 | 说明 | +|---|---|---| +| 用户端 | 任务进度条 | 展示 1/4、2/4、3/4、4/4 状态 | +| 用户端 | 推荐订单列表 | 展示下级昵称、订单时间、有效金额、当前档位 | +| 用户端 | 分享入口 | 复用当前推广二维码/分享海报能力 | +| Admin | 进度明细 | 后台任务详情展示每一单来源、订单号、下级用户 | + +**后端** + +| 模块 | 开发项 | 说明 | +|---|---|---| +| 订单接入 | 按 `brokerage_timing` 匹配任务 | `on_pay` 接支付成功事件，`on_confirm` 接确认收货流程 | +| 任务分配 | 最早任务优先 | 推荐人多个进行中任务时，按创建时间填充 | +| 进度记录 | `SyjPromoteTaskRecordServices` | 写入任务进度明细 | +| 状态推进 | 任务进度 +1 | 进度达到目标单数后触发完成结算 | +| 幂等 | 订单计入幂等 | 同一订单默认只能计入一次 | + +**数据库** + +| 表 | 用途 | +|---|---| +| `eb_syj_promote_task_record` | 保存下级订单计入任务进度的明细 | +| `eb_syj_promote_task` | 更新 `progress_count` 和任务状态 | +| `eb_store_order` | 读取订单、推荐人、支付状态、确认状态 | + +任务进度明细需保存 `source_type` 和 `trigger_timing`，用于区分 `brokerage_timing=on_pay` 的支付成功计入与 `brokerage_timing=on_confirm` 的确认收货计入。 + +**配置/权限/依赖** + +| 项 | 说明 | +|---|---| +| `syj_task_target_count` | 控制任务目标单数，首版为 4 | +| `syj_task_order_dedupe` | 控制按订单或按用户去重，首版建议按订单 | +| `brokerage_timing` | 控制推荐订单计入任务进度的节点，复用后台返佣设置 | +| 推荐关系依赖 | 依赖订单 `spread_uid` 或当前推荐关系快照 | +| 任务状态依赖 | 仅进行中任务可接收推荐订单 | + +**Checklist** + +- [ ] 推荐人无进行中任务时，下级订单不计入进度。 +- [ ] 推荐人有 1 个任务时，下级订单计入该任务。 +- [ ] 推荐人有多个任务时，优先计入最早进行中任务。 +- [ ] `brokerage_timing=on_pay` 时，下级订单支付成功后计入任务进度。 +- [ ] `brokerage_timing=on_confirm` 时，下级订单确认收货后计入任务进度。 +- [ ] 同一订单重复支付回调或重复确认收货时不重复计入。 +- [ ] 第 4 单计入后自动完成任务。 +- [ ] 任务进度在用户端和后台一致。 +- [ ] 推荐订单退款后能回滚或标记异常。 + +### 13.5 任务完成结算 + +**功能目标** + +推广任务完成 4 单后，结算 `4333` 元，不扣 `7%`，并复用当前佣金/账单/提现链路。 + +**前端** + +| 端 | 开发项 | 说明 | +|---|---|---| +| 用户端 | 完成状态 | 任务详情展示“已完成”与到账金额 | +| 用户端 | 结算记录 | 展示结算时间、结算金额、到账账户 | +| 用户端 | 资产入口 | 跳转当前佣金账户或提现页 | +| Admin | 结算流水 | 后台查看完成结算记录和关联账单 | + +**后端** + +| 模块 | 开发项 | 说明 | +|---|---|---| +| 结算服务 | `SyjPromoteSettlementServices::complete()` | 第 4 单后自动结算 | +| 入账 | 复用佣金账户/账单服务 | 写入当前可提现账户 | +| 状态 | 更新任务为 `completed` | 写完成时间，禁止再次计入 | +| 幂等 | 完成结算幂等 | 同一任务只能完成结算一次 | + +**数据库** + +| 表 | 用途 | +|---|---| +| `eb_syj_promote_settlement` | 保存完成结算记录 | +| `eb_syj_promote_task` | 保存任务完成状态 | +| `eb_user_bill` 或佣金流水表 | 保存资金入账流水 | + +**配置/权限/依赖** + +| 项 | 说明 | +|---|---| +| `syj_task_reward_rates` | 完成 4 单时不按提前兑现比例扣费，直接按任务基准结算 | +| 资金账户依赖 | 首版复用当前佣金账户和提现链路 | +| 任务状态依赖 | 只有进行中且进度达到目标单数的任务可完成结算 | + +**Checklist** + +- [ ] 第 4 单计入后自动结算。 +- [ ] 完成结算金额为任务 `base_amount`。 +- [ ] 完成 4 单不扣 7%。 +- [ ] 同一任务不会重复结算。 +- [ ] 结算流水能关联任务、用户和账单。 +- [ ] 用户资产页能看到到账变化。 +- [ ] 已完成任务不能再申请提前兑现。 + +### 13.6 提前兑现申请与审核 + +**功能目标** + +任务进度为 1-3 单时，用户可申请提前兑现；后台审核通过后扣 7%，入账并关闭任务。 + +**前端** + +| 端 | 开发项 | 说明 | +|---|---|---| +| 用户端 | 提前兑现按钮 | 仅进度 1-3 且任务进行中时展示 | +| 用户端 | 兑现确认弹窗 | 展示应结算、扣费、预计到账 | +| 用户端 | 审核状态 | 展示待审核、已通过、已拒绝 | +| Admin | 审核列表 | 展示用户、任务、进度、金额、申请时间 | +| Admin | 审核操作 | 通过/拒绝，填写备注 | + +**后端** + +| 模块 | 开发项 | 说明 | +|---|---|---| +| 用户申请 | `POST /api/syj/promote/task/:id/cashout` | 创建待审核结算记录 | +| 后台审核 | `POST /adminapi/syj/promote/cashout/:id/audit` | 审核通过后入账并关闭任务 | +| 金额计算 | 按当前进度比例 | `gross=base_amount*rate`，`net=gross-fee` | +| 状态机 | 任务和审核记录联动 | 防止审核期间任务继续完成导致重复结算 | + +**数据库** + +| 表 | 用途 | +|---|---| +| `eb_syj_promote_settlement` | 保存提前兑现申请、审核和入账结果 | +| `eb_syj_promote_task` | 审核中可增加锁定状态，审核通过后改为提前兑现 | +| `eb_user_bill` 或佣金流水表 | 保存到账流水 | + +**配置/权限/依赖** + +| 项 | 说明 | +|---|---| +| `syj_early_cashout_fee_rate` | 首版默认 7 | +| 后台审核权限 | 审核通过/拒绝必须限制后台权限 | +| 资金账户依赖 | 审核通过后复用当前佣金账户/账单服务入账 | +| 状态依赖 | 审核中任务需避免继续完成结算造成双重入账 | + +**Checklist** + +- [ ] 进度 0 单不能申请提前兑现。 +- [ ] 进度 1-3 单可以申请提前兑现。 +- [ ] 已完成、已关闭、异常任务不能申请提前兑现。 +- [ ] 审核通过扣 7% 后入账。 +- [ ] 审核拒绝后任务继续进行。 +- [ ] 审核通过后任务不能继续计入推荐订单。 +- [ ] 审核中并发第 4 单时有明确状态处理，不重复结算。 +- [ ] 用户端和后台金额计算一致。 + +### 13.7 用户端推广任务中心 + +**功能目标** + +为用户提供待推广金额、任务列表、任务详情、推荐进度、提前兑现和结算记录入口。 + +**前端** + +| 页面/文件建议 | 开发项 | 说明 | +|---|---|---| +| `view/uniapp/api/syjPromote.js` | API 封装 | 任务概览、列表、详情、兑现、流水 | +| `pages/syj/promote_task/index.vue` | 我的任务列表 | 进行中、已完成、已兑现、异常筛选 | +| `pages/syj/promote_task/detail.vue` | 任务详情 | 进度、推荐订单、奖励触发、结算 | +| 推广中心 | 增加入口 | 从现有推广中心进入“我的推广任务” | +| 资产页 | 文案联动 | 佣金、积分、等级继续复用当前页面 | + +**后端** + +| 接口 | 说明 | +|---|---| +| `GET /api/syj/promote/overview` | 概览 | +| `GET /api/syj/promote/task/list` | 任务列表 | +| `GET /api/syj/promote/task/:id` | 任务详情 | +| `GET /api/syj/promote/task/:id/records` | 推荐进度 | +| `POST /api/syj/promote/task/:id/cashout` | 提前兑现申请 | +| `GET /api/syj/promote/amount/log` | 待推广金额流水 | +| `GET /api/syj/promote/settlement/list` | 结算记录 | + +**数据库** + +用户端接口主要读取： + +- `eb_syj_promote_task` +- `eb_syj_promote_task_record` +- `eb_syj_promote_amount_log` +- `eb_syj_promote_settlement` +- 现有用户、订单、佣金、积分日志表 + +**配置/权限/依赖** + +| 项 | 说明 | +|---|---| +| 登录态 | 所有用户端任务接口必须登录后访问 | +| 数据权限 | 用户只能查看自己的任务、流水和结算 | +| 分享依赖 | 分享二维码/海报复用当前推广能力 | +| 文案依赖 | 页面统一使用芍药居口径 | + +**Checklist** + +- [ ] 未登录访问被拦截。 +- [ ] 任务列表分页正常。 +- [ ] 状态筛选正确。 +- [ ] 任务详情只允许本人查看。 +- [ ] 提前兑现按钮按状态展示。 +- [ ] 空状态、异常状态、加载失败状态完整。 +- [ ] 页面文案不出现 fsgx 旧口径。 +- [ ] 金额、比例、小数位显示一致。 + +### 13.8 管理后台任务管理 + +**功能目标** + +运营和财务能查看推广任务、推荐进度、奖励触发、结算流水、提前兑现审核和异常重试。 + +**前端** + +| 页面/文件建议 | 开发项 | 说明 | +|---|---|---| +| `view/admin/src/api/syjPromote.js` | 后台 API 封装 | 任务、配置、审核、重试 | +| `view/admin/src/router/modules/syj.js` | 后台路由 | 芍药居菜单 | +| `pages/syj/promoteTask/index.vue` | 任务列表 | 搜索、筛选、导出入口 | +| `pages/syj/promoteTask/detail.vue` | 任务详情 | 来源订单、进度、奖励、结算 | +| `pages/syj/cashout/index.vue` | 提前兑现审核 | 审核通过/拒绝 | +| `pages/syj/config/index.vue` | 规则配置 | 基准金额、比例、扣费等 | + +**后端** + +| 接口 | 说明 | +|---|---| +| `GET /adminapi/syj/promote/task/list` | 任务列表 | +| `GET /adminapi/syj/promote/task/:id` | 任务详情 | +| `GET /adminapi/syj/promote/task/:id/records` | 进度明细 | +| `GET /adminapi/syj/promote/cashout/list` | 审核列表 | +| `POST /adminapi/syj/promote/cashout/:id/audit` | 审核 | +| `GET /adminapi/syj/promote/settlement/list` | 结算流水 | +| `GET/POST /adminapi/syj/promote/config` | 配置 | +| `POST /adminapi/syj/promote/retry-trigger/:task_id` | 重试奖励触发 | + +**数据库** + +后台需要支持组合筛选索引： + +| 索引建议 | 用途 | +|---|---| +| `task_no` | 按任务号搜索 | +| `uid,status` | 按用户和状态筛选 | +| `source_order_no` | 按来源订单搜索 | +| `add_time` | 按创建时间筛选 | +| `audit_status,add_time` | 提前兑现审核列表 | + +**配置/权限/依赖** + +| 项 | 说明 | +|---|---| +| 后台菜单权限 | 任务列表、详情、配置、审核、重试分别授权 | +| 导出权限 | 结算和财务导出建议单独授权 | +| 操作审计 | 审核、重试、人工处理必须写操作人和备注 | +| 数据权限 | 若后台存在门店/供应商隔离，需按当前后台规则过滤 | + +**Checklist** + +- [ ] 后台任务列表支持状态、时间、用户、订单号筛选。 +- [ ] 任务详情展示来源订单和 4 单进度。 +- [ ] 奖励触发结果能看到成功/失败和失败原因。 +- [ ] 重试奖励触发有权限控制。 +- [ ] 提前兑现审核操作有二次确认。 +- [ ] 审核通过/拒绝写管理员和备注。 +- [ ] 列表导出字段满足财务核对。 +- [ ] 页面权限与当前后台权限体系一致。 + +### 13.9 积分、分销等级与资产展示 + +**功能目标** + +用户通过推广任务获得的积分、等级成长、佣金资产，都继续在当前积分、等级、资产页面可查，不新建平行资产体系。 + +**前端** + +| 端 | 开发项 | 说明 | +|---|---|---| +| 用户端 | 积分记录文案 | 显示任务来源，例如“推广任务积分奖励” | +| 用户端 | 等级展示 | 继续使用当前分销等级/会员等级展示 | +| 用户端 | 佣金资产 | 继续复用当前佣金账户和提现入口 | +| Admin | 积分日志筛选 | 可按 HJF/SYJ 类型查任务积分 | +| Admin | 分销等级任务 | 保持原后台配置入口 | + +**后端** + +| 模块 | 开发项 | 说明 | +|---|---|---| +| 积分日志 | 扩展 mark/source | 明确写入推广任务编号 | +| 资产概览 | 复用或包装现有资产接口 | 可增加任务统计字段 | +| 等级任务 | 保持 `AgentLevelTaskServices` 为唯一升级逻辑 | 不新增会员等级任务 | + +**数据库** + +| 表 | 说明 | +|---|---| +| `eb_agent_level` | 继续保存等级和奖励积分配置 | +| `eb_user.agent_level` | 继续保存用户当前等级 | +| `eb_points_release_log` | 保存冻结积分明细 | +| `eb_user_bill` | 后台积分日志 | +| `eb_syj_promote_reward_trigger` | 关联任务与积分/等级触发结果 | + +**配置/权限/依赖** + +| 项 | 说明 | +|---|---| +| 分销等级配置 | 继续由当前 `agent/level` 后台维护 | +| 分销等级任务配置 | 继续由当前 `agent/level_task` 后台维护 | +| 积分释放配置 | 继续复用 `hjf_release_rate` | +| 数据展示权限 | 积分、佣金、等级页面沿用当前权限体系 | + +**Checklist** + +- [ ] 任务触发积分后，用户端积分相关页面可查。 +- [ ] 后台积分日志可查到任务来源。 +- [ ] 用户等级仍取 `eb_user.agent_level`。 +- [ ] 分销等级后台配置不被替换。 +- [ ] 推广任务计入后台配置的等级任务。 +- [ ] 资产页面没有出现独立新账户造成口径冲突。 + +### 13.10 售后退款、异常与补偿 + +**功能目标** + +处理来源订单退款、推荐订单退款、奖励触发失败、积分或佣金补发等异常场景，避免资金和任务状态失真。 + +**前端** + +| 端 | 开发项 | 说明 | +|---|---|---| +| 用户端 | 异常状态展示 | 任务异常时提示联系客服或等待处理 | +| Admin | 异常任务列表 | 展示退款冲突、触发失败、结算冲突 | +| Admin | 人工处理入口 | 标记已处理、重试触发、备注 | + +**后端** + +| 模块 | 开发项 | 说明 | +|---|---|---| +| 售后接入 | 监听退款成功 | 判断来源订单或推荐订单影响 | +| 回滚服务 | `SyjPromoteExceptionServices` | 回滚未结算任务或标记异常 | +| 补偿命令 | `syj:promote:retry-trigger` | 批量重试奖励触发失败任务 | +| 审计日志 | 记录人工处理 | 保留管理员、原因、前后状态 | + +**数据库** + +| 表 | 说明 | +|---|---| +| `eb_syj_promote_task` | 增加异常状态和异常原因 | +| `eb_syj_promote_task_record` | 推荐订单退款后标记失效 | +| `eb_syj_promote_amount_log` | 来源订单退款后写回滚流水 | +| `eb_syj_promote_reward_trigger` | 保存触发失败和重试次数 | +| 异常处理日志表 | 可新增，也可复用系统日志 | + +**配置/权限/依赖** + +| 项 | 说明 | +|---|---| +| 售后状态依赖 | 需明确退款成功、部分退款、撤销售后的处理节点 | +| 人工处理权限 | 仅运营/管理员可标记异常处理结果 | +| 补偿命令权限 | 只能由运维或管理员执行 | +| 日志依赖 | 关键异常必须写业务日志，便于财务追溯 | + +**Checklist** + +- [ ] 来源订单未生成任务前退款，待推广金额正确回滚。 +- [ ] 来源订单已生成任务后退款，任务进入异常或人工处理。 +- [ ] 推荐订单未结算前退款，任务进度回滚。 +- [ ] 推荐订单已完成结算后退款，任务进入异常。 +- [ ] 奖励触发失败可后台重试。 +- [ ] 补偿命令不会重复发放已成功奖励。 +- [ ] 所有人工处理都有备注和操作人。 + +### 13.11 测试、命令与上线检查 + +**功能目标** + +为芍药居二开提供可重复执行的测试、补偿命令和上线前检查清单。 + +**前端** + +| 端 | 开发项 | 说明 | +|---|---|---| +| 用户端 | 联调测试账号 | 准备普通用户、推荐人、下级用户 | +| Admin | 联调账号权限 | 准备运营、财务、超级管理员权限 | +| 前端构建 | 页面路由检查 | 确认新增页面能在 H5/小程序/Admin 正常访问 | + +**后端** + +| 类型 | 开发项 | 说明 | +|---|---|---| +| 单元测试 | 金额累计、任务生成、结算公式 | 覆盖 4332/4333/8666 | +| 集成测试 | 支付/确认收货/推荐计入 | 覆盖订单生命周期 | +| 命令 | `syj:promote:retry-trigger` | 重试奖励触发失败 | +| 命令 | `syj:promote:verify` | 检查配置、表结构、任务异常 | +| 日志 | 关键节点日志 | 任务生成、奖励触发、结算、退款 | + +**数据库** + +上线前检查： + +- 表结构和索引已执行。 +- 配置项已初始化。 +- `hjf_queue_pool_enable=0`。 +- 旧商品 `is_queue_goods` 口径已由运营确认。 +- 后台菜单和权限已初始化。 + +**配置/权限/依赖** + +| 项 | 说明 | +|---|---| +| 测试环境 | 需准备可支付或可模拟支付的测试链路 | +| 队列依赖 | 若奖励触发异步化，需确认队列 worker 正常 | +| 定时任务 | 若积分释放依赖定时任务，需确认计划任务开启 | +| 日志权限 | 上线后需要能查看业务日志和异常日志 | + +**Checklist** + +- [ ] 后端测试覆盖 4332、4333、8666、9000。 +- [ ] 返佣时机 `on_pay` 和 `on_confirm` 都通过验收。 +- [ ] 积分奖励幂等测试通过。 +- [ ] 等级任务计数测试通过。 +- [ ] 提前兑现审核测试通过。 +- [ ] 退款异常测试通过。 +- [ ] 用户端任务列表和详情联调通过。 +- [ ] 后台任务管理、配置、审核联调通过。 +- [ ] 上线前配置检查命令通过。 + +--- + +## 14. 开发顺序建议 + +1. 新增数据库迁移和配置项。 +2. 新增 `syj` 模型、DAO、核心服务。 +3. 接入确认收货后的消费累计和任务生成。 +4. 实现等价报单奖励触发适配，先打通积分和等级任务，再打通佣金。 +5. 实现推荐订单计入任务进度。 +6. 实现 4 单完成结算。 +7. 实现提前兑现申请和后台审核。 +8. 增加用户端接口和后台接口。 +9. 补充管理端、用户端页面。 +10. 补齐测试、补偿命令、后台重试能力。 + +建议优先打通最小闭环： + +```text +确认收货生成任务 + -> 任务触发积分和等级任务 + -> 推荐 4 单完成 + -> 结算入账 +``` + +返佣、提前兑现、后台页面可在最小闭环稳定后并行完善。 + +--- + +## 15. 风险与注意事项 + +1. 不要新建独立会员等级体系，避免和 `eb_user.agent_level` 冲突。 +2. 不要把推四免一任务直接写成后台分销等级任务。 +3. 不要默认启用 HJF 公排池，芍药居首版不做排队退款。 +4. 不要用不完整的虚拟订单直接调用返佣方法，容易造成账单、统计和幂等问题。 +5. 不要绕开 `brokerage_timing`，否则会出现支付和确认收货重复返佣。 +6. 不要让积分奖励只写 `points_release_log`，后台积分日志还需要通过 `user_bill` 可查。 +7. 不要把旧 fsgx 文案带到芍药居页面，尤其是“推三免一”“20/30/50”“公排退款”。 +8. 退款、重复回调、并发确认收货是主要风险点，必须用唯一索引、事务和状态机兜住。 + +--- + +## 16. 与现有文档关系 + +| 文档 | 用途 | +|---|---| +| `docs/project-shaoyaoju/prd-require.md` | 原始需求整理与业务补充 | +| `docs/project-shaoyaoju/PRD_shaoyaoju_V1.0.md` | 产品需求主文档 | +| `docs/project-shaoyaoju/syj-fsgx-diff.md` | 芍药居与 fsgx 当前代码差异 | +| `docs/project-shaoyaoju/secondary-development-guide.md` | 面向后端工程师的二次开发说明 | + +研发实施时，以 PRD 确认业务口径，以差异文档确认复用边界，以本文档确认代码落点、数据结构、接口和验收方式。 diff --git a/docs/project-shaoyaoju/syj-fsgx-diff.md b/docs/project-shaoyaoju/syj-fsgx-diff.md new file mode 100644 index 00000000..c7b399df --- /dev/null +++ b/docs/project-shaoyaoju/syj-fsgx-diff.md @@ -0,0 +1,289 @@ +# 芍药居项目与 fsgx 当前代码差异对比 + +> 文档日期：2026-05-02 +> 当前分支：`syj-bypass-auth` +> 对比基线：fsgx 项目代码与文档（`fsgx-bypass-auth` / `docs/project-fsgx/*`） +> 业务需求来源：`docs/project-shaoyaoju/prd-require.md` 与后续确认反馈 +> 目标：明确“最小修改、最大复用”的落地边界 + +--- + +## 1. 总体结论 + +芍药居不需要重做商城主体，也不需要重写当前 fsgx 已有的分销奖金、积分奖励、分销等级和提现能力。当前代码已经提供大量可复用能力： + +- 商品、订单、支付、售后 +- `spread_uid` 推荐关系 +- 报单商品 `is_queue_goods` +- 分销奖金/周期佣金配置 +- 积分奖励、积分日志、积分释放 +- 分销等级与后台配置的分销等级任务 +- 佣金记录与提现 +- 分销员管理 +- 用户资产聚合 +- 签到基础接口与页面 + +芍药居与 fsgx 的核心差异不是“重做奖励体系”，而是新增一层“消费累计生成推四免一有效推广任务”的适配层。本文档中的“推广任务”如无特别说明，均特指“推四免一有效推广任务维度”，不是后台配置的分销等级任务。 + +```text +用户有效消费累计每满 4333 元 + -> 自动生成 1 个推四免一有效推广任务 + -> 该任务在系统侧等价当前代码 1 个报单商品订单 + -> 复用现有分销奖金、积分奖励、分销等级任务 + -> 同时承载推四免一进度、完成结算和提前兑现 +``` + +因此研发重点是让推广任务成为当前报单商品订单奖励链路的触发基准，而不是另起一套分销、积分或会员等级系统。 + +--- + +## 2. 核心规则差异 + +| 维度 | fsgx 当前规则/代码 | 芍药居目标规则 | 改造方式 | +|---|---|---|---| +| 触发基准 | 报单商品订单触发分销奖金、积分奖励、分销等级任务 | 每满 4333 元生成 1 个推四免一有效推广任务，任务等价 1 个报单商品订单 | 新增任务生成与触发适配层 | +| 任务资格 | 无“用户自身消费累计生成推四免一有效推广任务”概念 | 用户自身有效消费累计满 4333 元生成推四免一有效推广任务 | 新增待推广金额和推广任务 | +| 推四免一进度 | 当前代码无任务维度 | 推荐 4 个达到 `brokerage_timing` 对应节点的有效订单完成任务 | 新增任务进度记录，计入节点复用后台返佣时机 | +| 分销奖金 | 由报单商品订单触发 | 由推四免一有效推广任务等价触发 | 复用现有分销奖金逻辑，增加任务来源标识 | +| 积分奖励 | 由当前订单/报单逻辑触发 | 由推四免一有效推广任务等价触发 | 复用现有积分奖励、积分日志、积分释放逻辑 | +| 会员等级 | 当前分销等级与后台等级任务配置 | 继续复用当前分销等级 | 推四免一有效推广任务计入后台配置的分销等级任务 | +| 奖励比例 | fsgx 旧口径可能为 20/30/50 | 芍药居推四免一为 10/20/30/40 | 配置为 4 档比例 | +| 完成结算 | 当前无推四免一任务完成结算 | 4 单完成到账 4333 元，不扣 7% | 新增任务完成结算 | +| 提前兑现 | 当前无任务中途兑现 | 1-3 单可申请，后台审核，通过后扣 7% | 新增提前兑现申请与审核 | +| 上级联动 | 推荐订单按推广关系计佣 | 下级生成任务也可计入上级任务 | 新增配置开关并记录来源类型 | +| 奖励用途 | 当前佣金可进入提现链路 | 首版复用佣金账户和提现链路 | 不做下单黄金或不能提现限制 | +| 招商合作 | 无代理商招商/分红/股东权益 | 补充需求包含 19800 元招商包等 | 不进入首版，独立评审 | +| 签到 | CRMEB 原签到 | 浏览产品文章 10 秒后签到 | 复用签到页，新增前置文章门槛 | + +--- + +## 3. 代码复用矩阵 + +### 3.1 直接复用 + +| 能力 | 当前代码位置/模块 | 复用说明 | +|---|---|---| +| 商品管理 | `StoreProduct`、后台商品页面 | 新增商品默认 `is_queue_goods=1`，允许运营排除个别商品 | +| 下单支付 | 订单创建、支付、确认收货链路 | 复用订单生命周期，用于累计待推广金额 | +| 推荐关系 | `spread_uid`、`spread` 参数、用户服务 | 继续作为上下级关系唯一依据 | +| 分销奖金 | 当前分销/佣金服务、`UserBrokerage` / `UserBill` | 推四免一有效推广任务等价报单商品订单后复用 | +| 积分奖励 | fsgx 积分奖励、积分日志、积分释放 | 推四免一有效推广任务等价报单商品订单后复用 | +| 分销等级 | 当前分销等级模块与后台等级任务配置 | 会员等级复用当前分销等级 | +| 提现 | CRMEB `extract` | 奖励入账后走原提现链路 | +| 资产总览 | `/api/hjf/assets/overview` | 可改文案后复用或新增 `/api/syj/assets/overview` 包装 | +| 签到 | `view/uniapp/pages/users/user_sgin/index.vue`、`sign/*` API | 加 10 秒文章门槛 | +| 文章内容 | CRMEB 文章/CMS | 签到前置文章直接复用 | + +### 3.2 复用但需改配置/小改 + +| 能力 | 当前 fsgx | 芍药居改造 | +|---|---|---| +| 周期人数 | `brokerage_cycle_count = 3` | 改为 `4` | +| 周期比例 | `[20,30,50]` | 改为 `[10,20,30,40]` | +| 返佣范围 | `brokerage_scope` | 新增商品默认 `is_queue_goods=1`，仍可按 `queue_only` 控制 | +| 返佣节点 | 当前代码配置决定 | 芍药居复用当前代码逻辑和后台配置，不单独固定节点 | +| 积分奖励触发 | 当前订单/报单商品触发 | 增加推广任务触发来源 | +| 分销等级任务 | 后台配置任务 | 推四免一有效推广任务按等价报单商品订单计入 | +| 用户推广中心 | CRMEB 推广中心/fsgx 佣金进度 | 增加推广任务入口和任务触发记录 | + +### 3.3 必须新增 + +| 新增项 | 原因 | +|---|---| +| `SyjPromoteTaskServices` | 处理任务生成、进度、完成、提前兑现 | +| 任务等价订单触发适配服务 | 将推四免一有效推广任务映射为当前代码 1 个报单商品订单触发基准 | +| `eb_syj_promote_task` | fsgx 没有按 4333 元生成的任务实体 | +| `eb_syj_promote_amount_log` | fsgx 没有待推广金额累计流水 | +| `eb_syj_promote_task_record` | 需要记录每个任务的推荐来源 | +| `eb_syj_promote_settlement` | 任务完成和提前兑现需记录税费、到账、关联账单 | +| `eb_syj_promote_reward_trigger` 或等价追溯能力 | 记录任务触发分销奖金、积分奖励、分销等级任务的结果 | +| 用户端任务列表/详情页 | fsgx 没有任务页面 | +| 后台任务管理页 | 运营需要按任务排查进度、订单和奖励触发 | +| 提前兑现接口和审核 | fsgx 没有任务中途关闭结算 | + +### 3.4 建议隐藏或关闭 + +| 能力/文案 | 芍药居处理 | +|---|---| +| 公排队列相关旧文件 | 保留代码，确保 `hjf_queue_pool_enable = 0` | +| fsgx “邀请 3 人免单”文案 | 全部改为“推四免一任务” | +| 20/30/50 阶梯奖励文案 | 不作为推四免一任务口径展示 | +| 奖励下单黄金/不可提现入口 | 首版不新增，避免与佣金提现链路冲突 | +| 代理商招商、分红、股东权益入口 | 首版不新增，等待独立方案确认 | + +注意：积分奖励、积分日志、积分释放、分销等级不再隐藏或关闭，首版按当前代码逻辑复用。 + +--- + +## 4. 业务流程差异 + +### 4.1 fsgx 当前奖励触发流程 + +```text +用户 A 分享 + -> 用户 B 绑定 A 为上级 + -> B 购买报单商品 + -> 订单达到当前触发节点 + -> 系统触发 A 的分销奖金 + -> 系统触发积分奖励/积分日志/积分释放 + -> 系统计入分销等级任务 +``` + +### 4.2 芍药居目标流程 + +```text +用户 A 自己购买商品 + -> 累计 A 的待推广金额 + -> 每满 4333 元生成 1 个推四免一有效推广任务 + -> 该任务等价当前 1 个报单商品订单 + -> 触发现有分销奖金、积分奖励、分销等级任务 + -> A 分享给 B/C/D/E + -> B/C/D/E 的有效订单依次计入 A 的任务进度 + -> 满 4 单完成任务，到账 4333 元，不扣 7% + -> 1-3 单可申请提前兑现，后台审核通过后扣 7% +``` + +### 4.3 推荐订单处理 + +```text +推荐订单 + -> 判断订单是否参与规则商品 + -> 等待订单达到后台 brokerage_timing 对应节点 + - on_pay: 支付成功后 + - on_confirm: 确认收货后 + -> 查推荐人 spread_uid + -> 查推荐人是否有进行中 syj 任务 + -> 有任务：写入任务进度 + -> 无任务：不产生 syj 任务进度，仅保留 CRMEB 订单/关系数据 +``` + +### 4.4 推四免一有效推广任务奖励触发处理 + +```text +推四免一有效推广任务创建 + -> 写入 syj_promote_task + -> 生成奖励触发来源记录 + -> 以“等价报单商品订单”参数调用当前分销奖金逻辑 + -> 调用当前积分奖励/积分日志/积分释放逻辑 + -> 调用当前分销等级任务统计逻辑 + -> 记录每条现有流水与 syj_task_id 的关联 +``` + +--- + +## 5. 文件级改造建议 + +### 5.1 后端新增文件 + +| 文件 | 说明 | +|---|---| +| `app/model/syj/SyjPromoteTask.php` | 推广任务模型 | +| `app/model/syj/SyjPromoteAmountLog.php` | 待推广金额流水模型 | +| `app/model/syj/SyjPromoteTaskRecord.php` | 任务进度明细模型 | +| `app/model/syj/SyjPromoteSettlement.php` | 任务结算模型 | +| `app/model/syj/SyjPromoteRewardTrigger.php` | 任务触发现有奖励链路记录，可按实际复用现有流水替代 | +| `app/dao/syj/*Dao.php` | 对应 DAO | +| `app/services/syj/SyjPromoteTaskServices.php` | 核心任务服务 | +| `app/services/syj/SyjPromoteRewardTriggerServices.php` | 推四免一有效推广任务等价报单订单触发适配 | +| `app/controller/api/v1/syj/SyjPromote.php` | 用户端任务接口 | +| `app/controller/admin/v1/syj/SyjPromote.php` | 后台任务接口 | + +### 5.2 后端修改文件 + +| 文件 | 修改点 | +|---|---| +| `route/api.php` | 增加 `/api/syj/promote/*` | +| `route/admin.php` | 增加 `/adminapi/syj/promote/*` | +| `StoreOrderTakeServices.php` | 确认收货时触发消费累计与任务生成 | +| 当前分销奖金服务 | 增加推广任务来源，或提供可被任务适配服务调用的统一入口 | +| 当前积分奖励服务 | 增加推广任务来源，复用积分奖励与日志逻辑 | +| 当前分销等级任务服务 | 允许推四免一有效推广任务按等价报单商品订单计入后台配置任务 | +| `SystemConfigServices.php` | 增加芍药居任务相关配置 | +| `SystemTimerServices.php` | 若当前积分释放已启用，确保任务触发积分进入现有释放链路 | + +### 5.3 UniApp 新增/修改 + +| 文件 | 修改点 | +|---|---| +| `view/uniapp/api/syjPromote.js` | 新增任务接口封装 | +| `view/uniapp/pages/syj/promote_task/index.vue` | 我的任务列表 | +| `view/uniapp/pages/syj/promote_task/detail.vue` | 任务详情、奖励触发记录与提前兑现 | +| `view/uniapp/pages/users/user_spread_user/index.vue` | 增加“我的推广任务”入口 | +| `view/uniapp/pages/users/user_sgin/index.vue` | 增加文章浏览 10 秒门槛 | +| 推广中心/资产页 | 展示分销奖金、积分、分销等级沿用当前页面或文案 | +| 商品详情/支付结果页 | 文案从 fsgx 改为芍药居 | + +### 5.4 Admin 新增/修改 + +| 文件 | 修改点 | +|---|---| +| `view/admin/src/api/syjPromote.js` | 后台任务接口 | +| `view/admin/src/router/modules/syj.js` | 芍药居后台菜单 | +| `view/admin/src/pages/syj/promoteTask/index.vue` | 任务列表 | +| `view/admin/src/pages/syj/promoteTask/detail.vue` | 任务详情、奖励触发、积分触发、等级任务触发 | +| `view/admin/src/pages/syj/promoteConfig/index.vue` | 规则配置，可复用表单组件 | +| 当前分销等级配置页 | 继续作为会员等级和升级任务配置入口 | +| 当前积分日志页 | 显示推广任务来源 | + +--- + +## 6. 配置差异 + +| 配置 | fsgx 值 | 芍药居值 | +|---|---|---| +| `brokerage_cycle_count` | 3 | 4 | +| `brokerage_cycle_rates` | `[20,30,50]` | `[10,20,30,40]` | +| `brokerage_scope` | `queue_only` 或按 fsgx 配置 | `queue_only`，新增商品默认 `is_queue_goods=1` | +| `brokerage_timing` | 当前配置 | 沿用当前配置 | +| `hjf_queue_pool_enable` | 0 | 0 | +| `hjf_umbrella_reward_enable` | 视 fsgx | 0 | +| `syj_task_base_amount` | 无 | 433300 | +| `syj_task_as_queue_order_enable` | 无 | 1 | +| `syj_task_trigger_brokerage_enable` | 无 | 1 | +| `syj_task_trigger_points_enable` | 无 | 1 | +| `syj_task_trigger_agent_level_enable` | 无 | 1 | +| `syj_complete_tax_rate` | 无 | 0 | +| `syj_early_cash_tax_rate` | 无 | 7 | +| `syj_early_cash_enable` | 无 | 1 | +| `syj_early_cash_audit_enable` | 无 | 1 | +| `syj_parent_task_on_child_task` | 无 | 1 | +| `syj_reward_usage_mode` | 无 | `brokerage_withdrawable` | +| `syj_agent_recruit_enable` | 无 | 0 | + +分销等级、等级任务、积分奖励、积分释放的业务参数优先沿用当前后台配置，不新增平行配置体系。 + +--- + +## 7. 风险点 + +| 风险 | 说明 | 建议 | +|---|---|---| +| 双重奖励 | 推四免一有效推广任务等价订单触发当前奖励，若真实订单也触发同一奖励可能重复 | 明确只有推四免一有效推广任务作为芍药居分销奖金/积分触发基准，真实消费订单只负责累计待推广金额 | +| 触发幂等 | 任务生成后重复调用分销奖金/积分/等级任务会重复发放 | 增加 `task_id + trigger_type` 唯一约束或幂等锁 | +| 任务进度与奖励触发混淆 | 任务生成触发现有奖励，推荐订单计入推四免一进度，两者不是同一事件 | 流水区分 `task_created`、`order_pay`、`order_confirm` 等来源类型 | +| 积分释放兼容 | 当前积分释放可能只识别订单来源 | 增加推广任务来源标识，确保进入现有释放链路 | +| 分销等级统计偏差 | 后台等级任务可能按订单、人数、金额等维度统计 | 明确推四免一有效推广任务按 4333 元报单商品订单等价计入 | +| 推荐计数重复 | 下级订单达到 `brokerage_timing` 节点与下级任务创建都可能计入上级推四免一任务 | 增加配置开关并记录来源类型 | +| 退款冲正复杂 | 已生成任务并触发奖励后发生退款 | 首版进入异常待处理，后续设计奖励冲正 | +| 旧页面文案误导 | fsgx 页面仍有推荐三人/20/30/50 叙事 | 上线前做文案 grep 和页面走查 | +| 招商合规风险 | 19800 元招商包、加权分红、股东权益、赠品不属于商城主线 | 不进入首版，等待独立合规和运营方案 | + +--- + +## 8. 验收对照 + +| 验收项 | 标准 | +|---|---| +| 任务生成 | 用户订单累计满 4333 元后生成 1 个推广任务 | +| 多任务 | 用户订单累计 10000 元后生成 2 个任务，剩余待推广金额 1334 元 | +| 等价触发 | 每个推四免一有效推广任务按当前代码 1 个报单商品订单触发基准记录 | +| 分销奖金 | 推四免一有效推广任务生成后触发现有分销奖金逻辑，并可从佣金流水反查任务 | +| 积分奖励 | 推四免一有效推广任务生成后触发现有积分奖励逻辑，并可从积分日志反查任务 | +| 分销等级 | 推四免一有效推广任务计入后台配置的分销等级任务 | +| 推荐计数 | 被推荐有效订单达到后台 `brokerage_timing` 对应节点后，推荐人最早进行中任务 +1 | +| 无任务不计进度 | 推荐人没有任务时，被推荐订单不产生 syj 任务进度 | +| 完成奖励 | 4 单完成税前 4333 元，不扣 7%，到账 4333 元 | +| 提前兑现 | 2 单提前兑现税前 1299.90 元，审核通过扣 7% 后到账 1208.91 元 | +| 签到 | 浏览文章满 10 秒才可签到 | +| fsgx 旧文案 | 三人免单、20/30/50 文案不在芍药居核心页面出现 | +| 补充规则隔离 | 奖励下单黄金、代理商招商、分红股东权益不在首版用户端和后台默认出现 |