--- name: fsgx development tasks overview: 基于 page-dev-specs-fsgx.md（V2 分销模块复用方案），将全部开发工作拆解为 7 个阶段、24 个具体任务，按依赖关系排序，后端核心先行、前端改造跟进、最后清理与验收。 todos: - id: p1-db-schema content: "Phase1: 数据表变更 — eb_system_config 新增 4 个配置键 + eb_user 新增 frozen_points/available_points/no_assess" status: completed - id: p1-rake-back content: "Phase1: 返佣设置扩展 — SystemConfigServices::rakeBackFormBuild() 新增周期人数、分段比例、返佣范围、发放时机表单项" status: completed - id: p1-brokerage-calc content: "Phase1: 佣金计算链路改造（核心）— StoreOrderCreateServices 周期循环比例 + StoreOrderTakeServices 积分发放" status: completed - id: p1-product-fix content: "Phase1: 商品报单标记修复 — otherSet.vue payload + StoreProductServices 保存 is_queue_goods" status: completed - id: p2-progress-api content: "Phase2: 新增 GET /api/hjf/brokerage/progress 佣金周期进度聚合接口" status: completed - id: p2-assets-api content: "Phase2: 新增 GET /api/hjf/assets/overview 资产总览聚合接口" status: completed - id: p2-points-cron content: "Phase2: 积分释放定时任务 — 每日 frozen_points 0.4‰ 转 available_points + 日志" status: completed - id: p2-no-assess-api content: "Phase2: 新增 PUT /adminapi/hjf/member/{uid}/no_assess 不考核接口" status: completed - id: p3-admin-route content: "Phase3: Admin 路由精简 — hjfQueue.js 移除 5 条旧路由，仅保留 points/log" status: completed - id: p3-admin-api-clean content: "Phase3: Admin API 清理 — 移除 hjfQueue.js 和 hjfMember.js" status: completed - id: p3-uniapp-api-clean content: "Phase3: UniApp API 简化 — hjfQueue.js 仅保留 getBrokerageProgress()，移除 hjfMember.js" status: completed - id: p3-pages-json content: "Phase3: pages.json 路由标题改造 — 公排状态/历史/规则 → 推荐佣金/佣金记录/佣金规则" status: completed - id: p4-queue-status content: "Phase4: 推荐佣金进度页核心改造 — pages/queue/status.vue 整体重写" status: completed - id: p4-goods-detail content: "Phase4: 商品详情页改造 — 报单标记文案 + 佣金提示 + 隐藏积分支付" status: completed - id: p4-order-confirm content: "Phase4: 订单确认页改造 — 报单商品禁用积分支付 + 佣金预览" status: completed - id: p4-user-center content: "Phase4: 个人中心页改造 — 入口文案 + 等级展示改为 agent_level_name" status: completed - id: p4-assets-page content: "Phase4: 我的资产页改造 — 余额来源 + 文案 + 对接聚合接口" status: completed - id: p4-components content: "Phase4: 组件改造 — HjfQueueProgress/HjfRefundNotice/HjfAssetCard" status: completed - id: p5-guide-text content: "Phase5: 引导页 + 规则页 + 支付结果页文案改造" status: completed - id: p5-spread-enhance content: "Phase5: 推广中心增强 — 嵌入佣金进度摘要 + 报单商品标记" status: completed - id: p5-mock-update content: "Phase5: Mock 数据更新 — 公排字段→佣金字段" status: completed - id: p6-admin-user content: "Phase6: Admin 用户管理增强 — 新增列 + 操作按钮" status: completed - id: p6-points-mock content: "Phase6: 积分日志 USE_MOCK 改 false" status: completed - id: p7-config-test content: "Phase7: 后台配置（分销等级 + 人人分销 + 返佣设置 + 提现费率）+ 全链路验收测试" status: completed isProject: false --- # 范氏国香商城 — 开发任务计划 基于 [docs/page-dev-specs-fsgx.md](docs/page-dev-specs-fsgx.md) 制定，按依赖关系分 7 个阶段执行。 --- ## 依赖关系总览 ```mermaid flowchart TD Phase1[Phase1_后端核心] --> Phase2[Phase2_后端接口] Phase1 --> Phase3[Phase3_前端清理] Phase2 --> Phase4[Phase4_前端P0改造] Phase3 --> Phase4 Phase4 --> Phase5[Phase5_前端P1改造] Phase4 --> Phase6[Phase6_Admin增强] Phase5 --> Phase7[Phase7_配置验收] Phase6 --> Phase7 ``` --- ## Phase 1: 后端核心改造（P0，所有前端依赖此阶段） ### 1.1 数据表变更 - `eb_system_config` 新增 4 个配置键：`brokerage_cycle_count`、`brokerage_cycle_rates`、`brokerage_scope`、`brokerage_timing` - `eb_user` 新增字段：`frozen_points`、`available_points`、`no_assess`（积分模块用） ### 1.2 返佣设置扩展 - 文件：[app/services/system/config/SystemConfigServices.php](pro_v3.5.1/app/services/system/config/SystemConfigServices.php) - 在 `rakeBackFormBuild()` 方法中新增表单项：周期人数、各档比例 JSON、返佣范围（所有/仅报单）、发放时机（支付即发/确认收货后） - 增加验证规则 ### 1.3 佣金计算链路改造（核心中的核心） - 文件：[app/services/order/StoreOrderCreateServices.php](pro_v3.5.1/app/services/order/StoreOrderCreateServices.php) - 修改一级佣金计算：固定比例 → 查询推荐人下级报单商品有效订单数 → 取模周期人数得位次 → `cycle_rates[position]` 取当前比例 - 判断 `brokerage_scope`：若 `queue_only` 则仅 `is_queue_goods=1` 的商品参与 - 文件：[app/services/order/StoreOrderTakeServices.php](pro_v3.5.1/app/services/order/StoreOrderTakeServices.php) - `backOrderBrokerage` 方法：佣金发放后，若推荐人有分销等级，同步发放积分到 `frozen_points` ### 1.4 商品报单标记修复 - 前端：[view/admin/src/pages/product/productAdd/components/otherSet.vue](pro_v3.5.1/view/admin/src/pages/product/productAdd/components/otherSet.vue) — 确认 `is_queue_goods` 在保存 payload 中 - 后端：`StoreProductServices` — 确认保存逻辑处理 `is_queue_goods` 字段写入 --- ## Phase 2: 后端新增接口 + 积分体系 ### 2.1 佣金周期进度聚合接口 - 新增 `GET /api/hjf/brokerage/progress` - 逻辑：统计 `spread_uid` 下级购买报单商品的有效订单数，取模 `brokerage_cycle_count`，返回 `cycle_total`/`cycle_current`/`cycle_rates`/`total_brokerage` ### 2.2 资产总览聚合接口 - 新增 `GET /api/hjf/assets/overview` - 返回 `brokerage_price`（CRMEB 字段）+ `frozen_points`/`available_points`/`today_release`（自定义）+ `agent_level_name`（CRMEB 字段） ### 2.3 积分释放定时任务 - 定时任务：每日将 `frozen_points` 的 0.4‰ 转入 `available_points` - 积分消费扣减逻辑 - 积分日志写入 ### 2.4 不考核接口 - 新增 `PUT /adminapi/hjf/member/{uid}/no_assess` --- ## Phase 3: 前端清理 — 移除旧模块 ### 3.1 Admin 路由精简 - [view/admin/src/router/modules/hjfQueue.js](pro_v3.5.1/view/admin/src/router/modules/hjfQueue.js) — 移除 `queue/order`、`queue/finance`、`queue/config`、`member/level`、`member/config` 路由，仅保留 `points/log` - 建议重命名文件为 `hjfCustom.js` ### 3.2 Admin API 文件清理 - 移除 `admin/src/api/hjfQueue.js`（佣金订单/配置/财务由 CRMEB 佣金记录覆盖） - 移除 `admin/src/api/hjfMember.js`（由 CRMEB `agent_level` 接口覆盖） ### 3.3 UniApp API 文件简化 - `uniapp/api/hjfQueue.js` — 仅保留 `getBrokerageProgress()` 一个聚合接口，移除公排相关函数 - `uniapp/api/hjfMember.js` — 可移除，由 CRMEB `spread` 系列接口替代 ### 3.4 UniApp pages.json 路由标题改造 - `pages/queue/status`：公排状态 → 推荐佣金 - `pages/queue/history`：公排历史 → 佣金记录（或重定向到 `user_spread_money`） - `pages/queue/rules`：公排规则 → 佣金规则 --- ## Phase 4: 前端 P0 改造 ### 4.1 推荐佣金进度页（核心改造） - [view/uniapp/pages/queue/status.vue](pro_v3.5.1/view/uniapp/pages/queue/status.vue) — 整体改造 - 顶部：周期进度环（调用 `/api/hjf/brokerage/progress`） - 底部：佣金记录列表（调用 CRMEB `/api/spread/commission/detail`） - 组件 `HjfQueueProgress.vue` 改为佣金周期进度环 ### 4.2 商品详情页改造 - [view/uniapp/pages/goods_details/index.vue](pro_v3.5.1/view/uniapp/pages/goods_details/index.vue) - "公排商品"→"报单商品"标记文案 - 报单商品增加佣金提示 - 报单商品隐藏积分支付入口 ### 4.3 订单确认页改造 - [view/uniapp/pages/goods/order_confirm/index.vue](pro_v3.5.1/view/uniapp/pages/goods/order_confirm/index.vue) - 报单商品禁用积分支付 - 展示"本单推荐人可获佣金 ¥X" ### 4.4 个人中心页改造 - [view/uniapp/pages/user/index.vue](pro_v3.5.1/view/uniapp/pages/user/index.vue) - "公排查询"→"推荐佣金"入口文案 - 等级展示改为从 CRMEB `agent_level_name` 获取 ### 4.5 我的资产页改造 - [view/uniapp/pages/assets/index.vue](pro_v3.5.1/view/uniapp/pages/assets/index.vue) - 余额来源改为 `brokerage_price` - "公排累计退款"→"推荐累计佣金" - 调用 `/api/hjf/assets/overview` 聚合接口 ### 4.6 组件改造 - `HjfQueueProgress.vue` → 佣金周期进度环（props: `cycleCurrent/cycleTotal/cycleRates`） - `HjfRefundNotice.vue` → 佣金到账通知弹窗 - `HjfAssetCard.vue` → 文案改为"推荐佣金"，余额来源改为 `brokerage_price` --- ## Phase 5: 前端 P1 改造 ### 5.1 新用户引导页文案 - [view/uniapp/pages/guide/hjf_intro.vue](pro_v3.5.1/view/uniapp/pages/guide/hjf_intro.vue) + `hjfMockData.js` - 品牌名改为"范氏国香"，公排叙事改为佣金叙事 ### 5.2 佣金规则说明页改造 - [view/uniapp/pages/queue/rules.vue](pro_v3.5.1/view/uniapp/pages/queue/rules.vue) - "进四退一"→"推荐佣金流程"，示例金额 ¥4,333 - 新增等级积分说明 ### 5.3 支付结果页文案 - [view/uniapp/pages/goods/order_pay_status/index.vue](pro_v3.5.1/view/uniapp/pages/goods/order_pay_status/index.vue) - "进入公排队列"→"推荐好友可获佣金" ### 5.4 推广中心增强 - [view/uniapp/pages/users/user_spread_user/index.vue](pro_v3.5.1/view/uniapp/pages/users/user_spread_user/index.vue) - 顶部嵌入佣金周期进度摘要 - 成员列表增加"是否已购报单商品"标记 ### 5.5 Mock 数据更新 - `hjfMockData.js`（UniApp + Admin）— 公排字段替换为佣金字段 --- ## Phase 6: Admin 后台增强 ### 6.1 用户管理增强 - [view/admin/src/pages/user/list/index.vue](pro_v3.5.1/view/admin/src/pages/user/list/index.vue) - 新增列：分销等级名称、待释放积分、已释放积分 - 操作列增加"调整分销等级"和"设置不考核"按钮 ### 6.2 积分日志 Mock 切换 - [view/admin/src/pages/hjf/pointsLog/index.vue](pro_v3.5.1/view/admin/src/pages/hjf/pointsLog/index.vue) - `USE_MOCK` 改为 `false`，对接真实接口 --- ## Phase 7: 配置与验收 ### 7.1 后台分销等级配置 - 通过 CRMEB 后台创建 4 个分销等级（创客/云店/服务商/分公司） - 配置等级任务（直推人数、伞下订单数） - 配置各等级佣金上浮比例 ### 7.2 后台运营配置 - 开启"人人分销" - 返佣设置：配置周期人数=3，比例=[20,30,50]，范围=仅报单商品 - 提现手续费率 7% - 首页 DIY 配置报单商品推荐位 ### 7.3 全链路验收测试 - 注册→绑定推荐关系→购买报单商品→佣金计算→佣金发放→积分奖励→提现 - 分销等级自动升级验证 - 佣金周期进度正确性验证