docs: add shaoyaoju secondary development guide

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 文案不在芍药居核心页面出现 |
+| 补充规则隔离 | 奖励下单黄金、代理商招商、分红股东权益不在首版用户端和后台默认出现 |