huangjingfen/docs/project-shaoyaoju/PRD_shaoyaoju_V1.0.md

# 芍药居小程序 · 产品需求文档（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 | 补充规则评审 | 招商合作、奖励用途限制是否进入后续版本 |