huangjingfen/pro_v3.5.1/.cursor/plans/fsgx_development_tasks_ff68a8e9.plan.md

---
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 全链路验收测试

- 注册→绑定推荐关系→购买报单商品→佣金计算→佣金发放→积分奖励→提现
- 分销等级自动升级验证
- 佣金周期进度正确性验证