huangjingfen/docs/page-dev-specs-fsgx.md

# 范氏国香商城 · 页面开发说明文档（V2 — 基于分销模块复用）

> 对应 PRD：`docs/PRD_fsgx_V1.0.md`  
> 技术底座：CRMEB Pro v3.5 二次开发（UniApp + iView Admin）  
> 文档日期：2026-03-23  
> 文档状态：V2 — 基于分销模块最大化复用原则修订

---

## 核心原则

> **最大限度复用 CRMEB 分销模块**：  
> 1. "创客/云店/服务商/分公司"四级体系 → 使用 CRMEB **分销等级**（`agent_level` 表）  
> 2. "推荐佣金 20/30/50"→ 在 CRMEB **分销佣金**（`brokerage`）计算链路上改造  
> 3. 佣金配置 → 扩展 CRMEB **返佣设置**（`rake_back`）  
> 4. 佣金记录 → 复用 CRMEB **佣金记录**（`UserBrokerage` / `UserBill`）  
> 5. 推荐关系 → 复用 CRMEB **推广关系**（`spread_uid`）  
> 6. 提现 → 复用 CRMEB **提现功能**（`extract`）  
> 7. 仅在 CRMEB 不覆盖的功能点上做自定义扩展（积分释放、报单标记等）

---

## 目录

- [Part 1: 小程序端（UniApp）](#part-1-小程序端uniapp)
  - [1.1 新用户引导页](#11-新用户引导页)
  - [1.2 登录页](#12-登录页)
  - [1.3 首页](#13-首页)
  - [1.4 商品详情页](#14-商品详情页)
  - [1.5 订单确认页](#15-订单确认页)
  - [1.6 支付结果页](#16-支付结果页)
  - [1.7 推荐佣金进度页](#17-推荐佣金进度页)
  - [1.8 佣金收益页](#18-佣金收益页)
  - [1.9 推荐佣金规则说明页](#19-推荐佣金规则说明页)
  - [1.10 个人中心页](#110-个人中心页)
  - [1.11 我的资产页](#111-我的资产页)
  - [1.12 积分明细页](#112-积分明细页)
  - [1.13 推广中心/团队页](#113-推广中心团队页)
  - [1.14 提现页](#114-提现页)
- [Part 2: 管理后台（Admin Vue）](#part-2-管理后台admin-vue)
  - [2.1 分销员管理](#21-分销员管理)
  - [2.2 佣金记录](#22-佣金记录)
  - [2.3 返佣设置](#23-返佣设置)
  - [2.4 分销等级管理](#24-分销等级管理)
  - [2.5 积分日志](#25-积分日志)
  - [2.6 商品编辑 - 报单标记](#26-商品编辑---报单标记)
  - [2.7 商品列表](#27-商品列表)
  - [2.8 提现申请管理](#28-提现申请管理)
  - [2.9 用户管理](#29-用户管理)
- [Part 3: 后端改造要点](#part-3-后端改造要点)
  - [3.1 佣金计算链路改造](#31-佣金计算链路改造)
  - [3.2 分销等级映射](#32-分销等级映射)
  - [3.3 积分体系（自定义扩展）](#33-积分体系自定义扩展)
- [Part 4: 公共组件与 API 层](#part-4-公共组件与-api-层)
  - [4.1 UniApp 组件](#41-uniapp-组件)
  - [4.2 API 文件](#42-api-文件)
  - [4.3 Mock 数据](#43-mock-数据)

---

## 模块映射总览

| fsgx 需求 | CRMEB 分销模块对应 | 改造方式 |
|---|---|---|
| 推荐关系绑定 | `spread_uid`（推广关系） | 直接复用 |
| 推荐佣金 20/30/50 | 一级佣金 `one_brokerage` | 改造计算逻辑：从固定比例改为周期循环比例 |
| 创客/云店/服务商/分公司 | `agent_level`（分销等级） | 配置 4 个分销等级，升级条件对齐 |
| 等级积分奖励 | 暂无直接对应 | 在佣金发放链路上新增积分奖励逻辑 |
| 佣金提现 | `extract`（提现模块） | 直接复用，手续费配置为 7% |
| 佣金记录 | `UserBrokerage` / `UserBill` | 直接复用 |
| 推广中心 | `user_spread_user` / `user_spread_money` | 复用 + 文案改造 |
| 返佣配置 | `rake_back`（返佣设置） | 扩展：增加周期人数、分段比例、返佣范围 |
| 分销员管理 | `agentManage`（分销员管理） | 直接复用 |
| 佣金财务流水 | `finance/commission`（佣金记录） | 直接复用 |
| 报单商品标记 | `is_queue_goods`（自定义字段） | 自定义扩展 |
| 积分释放 | 无对应 | 自定义扩展 |

---

## Part 1: 小程序端（UniApp）

基础路径：`pro_v3.5.1/view/uniapp/`

---

### 1.1 新用户引导页

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/guide/hjf_intro.vue` |
| 路由 | `pages/guide/hjf_intro`（pages.json，custom nav） |
| 当前状态 | **需改造（文案）** |
| PRD 章节 | 4.1 登录与注册 — 新用户引导（P1） |
| 优先级 | P1 |

**改造要点**

仅更新 `MOCK_GUIDE_DATA` 中的轮播文案：

| slide | 当前文案 | 目标文案 |
|---|---|---|
| 1 | 欢迎来到黄精粉健康商城 | 欢迎来到范氏国香商城 |
| 2 | 公排返利机制 — 每进4单退1单 | 推荐佣金 — 邀请3人购买即可免单 |
| 3 | 会员积分体系 — 推荐好友即获积分 | 分级积分奖励 — 升级后推荐再得积分 |

**验收标准**

- 文案为推荐佣金叙事，品牌名为"范氏国香"
- 阅读完成后写入本地标记不再重复展示

---

### 1.2 登录页

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/users/login/index.vue` |
| 当前状态 | **CRMEB 直接复用** |
| 优先级 | P0 |

**复用说明**

CRMEB 分销模块的 `spread` 参数绑定机制完全满足需求。确认以下逻辑正常：

- 分享链接携带 `spread` / `spid` 参数
- 首次登录自动绑定 `spread_uid`，不可篡改
- 绑定推荐关系后自动成为推广人（需后台"人人分销"开启）

**依赖 API**

- CRMEB 原有授权/手机号绑定接口

**验收标准**

- 推荐关系绑定正确
- 后台"人人分销"开启后，新注册用户自动成为分销员

---

### 1.3 首页

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/index/index.vue` |
| 当前状态 | **CRMEB DIY 直接复用** |
| 优先级 | P0 |

**复用说明**

无代码改动，仅通过后台 DIY 配置报单商品（4333 元）推荐位。

---

### 1.4 商品详情页

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/goods_details/index.vue` |
| 当前状态 | **需改造（文案 + 逻辑）** |
| PRD 章节 | 4.3 商品与购买（P0） |
| 优先级 | P0 |

**改造要点**

| 改造项 | 说明 |
|---|---|
| 报单标记文案 | `is_queue_goods` 标记文案从"公排商品"改为"报单商品" |
| 佣金提示 | 报单商品展示"推荐好友购买，可获佣金奖励" |
| 佣金展示 | 复用 CRMEB 商品详情中的"预计佣金"展示（`product.attrInfo.brokerage`） |
| 积分支付 | 报单商品隐藏积分支付入口 |

**依赖 API**

- `GET /api/product/detail/{id}` — CRMEB 原有（含 `is_queue_goods`、佣金信息）

**验收标准**

- 报单商品展示"报单商品"角标 + 佣金提示
- 普通商品展示标准详情
- 佣金金额显示正确

---

### 1.5 订单确认页

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/goods/order_confirm/index.vue` |
| 当前状态 | **需改造** |
| 优先级 | P0 |

**改造要点**

| 改造项 | 说明 |
|---|---|
| 积分支付过滤 | 报单商品（`is_queue_goods === 1`）禁用积分支付 |
| 佣金预览 | 复用 CRMEB 订单确认中的佣金计算，展示"本单推荐人可获佣金 ¥X" |

**依赖 API**

- `POST /api/order/confirm` / `POST /api/order/create` — CRMEB 原有

---

### 1.6 支付结果页

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/goods/order_pay_status/index.vue` |
| 当前状态 | **需改造（文案）** |
| 优先级 | P1 |

**改造要点**

| 改造项 | 当前 | 目标 |
|---|---|---|
| 报单商品提示 | "您的订单已进入公排队列" | "支付成功！推荐好友购买可获得佣金" |
| 跳转按钮 | "查看公排状态" | "查看推荐佣金"→ 跳转 `pages/queue/status` |

---

### 1.7 推荐佣金进度页

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/queue/status.vue` |
| 当前状态 | **核心改造** |
| PRD 章节 | 4.4 推荐裂变 — 佣金进度（P0） |
| 优先级 | P0 |

**功能描述（目标）**

展示当前用户的推荐佣金周期进度：

- 顶部：周期进度环（第 N 人 / 共 3 人，已获佣金 X%）
- 中部：三段进度条（20% → 30% → 50%），标注每档完成状态
- 底部：我的佣金记录列表

**实现方案 — 基于分销模块**

| 数据来源 | CRMEB 模块 | 说明 |
|---|---|---|
| 佣金进度 | 统计用户下级购买报单商品数量 | 对 `spread_uid` 下级的报单商品订单计数，取模周期人数得当前位次 |
| 佣金记录 | `UserBrokerage` 佣金记录 | 筛选类型 `get_brokerage`（一级佣金），即为推荐佣金记录 |
| 累计佣金 | `brokerage_price`（佣金余额） | CRMEB 用户表已有字段 |

**API 接口**

复用 CRMEB 原有接口 + 新增 1 个进度聚合接口：

```
GET /api/hjf/brokerage/progress   (新增)

Response:
{
  cycle_total: 3,               // 周期人数（来自 rake_back 配置）
  cycle_current: 1,             // 当前周期已完成人数
  cycle_rates: [20, 30, 50],    // 各档比例（来自 rake_back 配置）
  total_brokerage: "4333.00"    // 累计佣金收入
}

GET /api/spread/commission/detail?page=1&limit=15  (CRMEB 原有，佣金明细)
```

**依赖组件**

- `HjfQueueProgress` → 改造为周期进度环组件

**验收标准**

- 进度环数据与用户实际推荐报单商品订单数一致
- 佣金记录列表复用佣金明细数据
- 空态引导文案

---

### 1.8 佣金收益页

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/users/user_spread_money/index.vue` |
| 当前状态 | **CRMEB 复用 + 文案确认** |
| PRD 章节 | 4.4 推荐裂变 — 推荐收益列表（P1） |
| 优先级 | P1 |

**复用说明**

CRMEB 原有"佣金收益"页面已包含：佣金明细列表、收入/支出 Tab、分页加载。直接复用，无需改造文案（本身就叫"佣金"）。

**注意**：原 `pages/queue/history.vue` 不再作为独立入口，改为跳转到此页面，或将 `history.vue` 重定向到 `user_spread_money`。

**依赖 API**

- `GET /api/spread/commission/detail` — CRMEB 原有佣金明细

**验收标准**

- 列表展示佣金收入记录
- 分页正常

---

### 1.9 推荐佣金规则说明页

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/queue/rules.vue` |
| 当前状态 | **核心改造（静态文案）** |
| 优先级 | P1 |

**改造要点**

| 改造项 | 当前 | 目标 |
|---|---|---|
| 机制标题 | "进四退一流程" | "推荐佣金流程" |
| 流程图 | 4 人入队触发退款 | A 推荐 B/C/D，A 获 20%/30%/50% 佣金 |
| 示例金额 | ¥3,600 | ¥4,333 |
| 等级说明 | 无 | 新增"升级创客后，每单额外获得 500 积分"说明 |

---

### 1.10 个人中心页

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/user/index.vue` |
| 当前状态 | **需改造（文案 + 入口）** |
| 优先级 | P0 |

**改造要点**

| 改造项 | 当前 | 目标 |
|---|---|---|
| 入口文案 | "公排查询" | "推荐佣金" |
| 跳转路径 | `/pages/queue/status` | 保持不变 |
| 等级展示 | class `vip` 区域 | 改为从 CRMEB `agent_level_name`（分销等级名称）获取，显示"创客/云店/服务商/分公司" |
| 推广中心入口 | CRMEB 原有"分销中心"入口 | 确认可见，文案可改为"推广中心" |

**依赖 API**

- `GET /api/user` — CRMEB 原有（含 `agent_level`、`brokerage_price` 等字段）

---

### 1.11 我的资产页

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/assets/index.vue` |
| 当前状态 | **需改造** |
| 优先级 | P0 |

**改造要点**

| 改造项 | 当前 | 目标 |
|---|---|---|
| 现金余额 | 展示 `now_money` | 改为展示 `brokerage_price`（佣金余额），或两者都展示 |
| 来源文案 | "公排累计退款" | "推荐累计佣金" |
| 统计字段 | `total_queue_refund` | 改为累计佣金收入（从 `UserBrokerage` 汇总） |

**API 接口**

```
GET /api/hjf/assets/overview   (保留的自定义聚合接口)

Response:
{
  brokerage_price: "7200.00",   // 佣金余额（可提现）= CRMEB user.brokerage_price
  frozen_points: 15000,          // 待释放积分（自定义）
  available_points: 3200,        // 已释放积分（自定义）
  today_release: 6,              // 今日释放量（自定义）
  total_brokerage: "14400.00",   // 累计佣金收入
  total_points_earned: 18200,
  agent_level: 2,
  agent_level_name: "云店"       // 来自 CRMEB agent_level
}
```

---

### 1.12 积分明细页

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/assets/points_detail.vue` |
| 当前状态 | **保持（自定义模块）** |
| 优先级 | P1 |

**复用说明**

积分释放体系（待释放/已释放/每日释放）为自定义扩展，不属于 CRMEB 分销模块。保持现有实现，集成时 `USE_MOCK` 改为 `false`。

---

### 1.13 推广中心/团队页

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/users/user_spread_user/index.vue` |
| 当前状态 | **CRMEB 复用 + 增强** |
| PRD 章节 | 4.4 推荐裂变（P1） |
| 优先级 | P1 |

**复用说明**

CRMEB 原有"推广中心"页面已包含：直推成员列表、推广人数统计、推广海报。

**改造要点**

| 改造项 | 说明 |
|---|---|
| 顶部增加 | 嵌入佣金周期进度摘要组件（复用 `HjfQueueProgress`） |
| 数据增强 | 每个成员增加"是否已购报单商品"标记（需后端接口增加字段） |

**依赖 API**

- `GET /api/spread/people` — CRMEB 推广人列表
- `GET /api/spread/count` — CRMEB 推广统计
- `GET /api/hjf/brokerage/progress` — 自定义进度聚合

---

### 1.14 提现页

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/users/user_cash/index.vue` |
| 当前状态 | **CRMEB 直接复用** |
| 优先级 | P0 |

**复用说明**

CRMEB 提现功能完全满足需求：提现金额输入、手续费计算（后台配 7%）、渠道选择、提交审核。

确认后台 `rake_back` 配置中 `extract_time`（佣金冻结天数）和手续费率配置正确即可。

---

## Part 2: 管理后台（Admin Vue）

基础路径：`pro_v3.5.1/view/admin/src/`

---

### 2.1 分销员管理

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/agent/agentManage.vue` |
| 路由 | `/admin/agent/agent_manage/index`（CRMEB 原有） |
| 当前状态 | **CRMEB 直接复用** |
| PRD 章节 | 5.2 用户管理（P0） |
| 优先级 | P0 |

**复用说明**

CRMEB 原有"分销员管理"页面已包含：分销员列表、筛选（等级/昵称/手机号）、推广人列表弹窗（含推广订单、佣金字段）、统计卡片。

**改造要点**

| 改造项 | 说明 |
|---|---|
| 等级筛选 | 确认下拉中包含"创客/云店/服务商/分公司"选项（来自 `agent_level` 配置） |

**验收标准**

- 分销员列表展示正确
- 推广人列表弹窗可查看推荐关系与佣金明细

---

### 2.2 佣金记录

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/finance/commission/index.vue` |
| 路由 | `/admin/finance/finance/commission`（CRMEB 原有） |
| 当前状态 | **CRMEB 直接复用** |
| PRD 章节 | 5.5 财务管理 — 佣金流水（P0） |
| 优先级 | P0 |

**复用说明**

CRMEB 原有"佣金记录"页面已包含：佣金流水列表、用户/时间/金额筛选、明细弹窗。所有通过分销佣金发放的记录自动出现在此页面。

**注意**：原 `pages/hjf/queueFinance` **不再需要**，其功能完全由 CRMEB 佣金记录覆盖。

---

### 2.3 返佣设置

| 属性 | 内容 |
|---|---|
| 页面路径 | 系统配置 `rake_back` Tab（通过 `SystemConfigServices::rakeBackFormBuild` 生成） |
| 路由 | `/admin/setting/system_config_rake_back`（CRMEB 原有） |
| 当前状态 | **需改造（核心）** |
| PRD 章节 | 5.6 营销配置中心（P0） |
| 优先级 | P0 |

**功能描述**

CRMEB 返佣设置页面，通过 `rakeBackFormBuild` 方法动态生成表单。

**改造要点**

| 改造项 | 当前 | 目标 |
|---|---|---|
| 一级返佣比例 | 固定百分比 `store_brokerage_ratio` | 改为多段比例：支持配置周期人数 + 各档比例（如 3 人循环 20/30/50） |
| 二级返佣 | `store_brokerage_two` | 保留，或设为 0（fsgx 无二级返佣需求） |
| 新增配置 | — | `brokerage_cycle_count`（周期人数，默认 3） |
| 新增配置 | — | `brokerage_cycle_rates`（各档比例 JSON，如 `[20,30,50]`） |
| 新增配置 | — | `brokerage_scope`（返佣范围：`all` 所有商品 / `queue_only` 仅报单商品） |
| 新增配置 | — | `brokerage_timing`（发放时机：`on_pay` 支付即发 / `on_confirm` 确认收货后） |

**后端改造**

- `SystemConfigServices::rakeBackFormBuild()` — 新增上述配置字段的表单项
- `SystemConfigValidate` — 增加对应验证规则
- `eb_system_config` 表 — 新增配置键值对

**验收标准**

- 返佣设置页展示新增配置项
- 保存后配置值正确持久化
- 佣金计算链路读取新配置生效

---

### 2.4 分销等级管理

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/setting/membershipLevel/index.vue` |
| 路由 | `/admin/setting/membership_level/index`（CRMEB 原有） |
| 当前状态 | **CRMEB 复用 + 配置对齐** |
| PRD 章节 | 5.6 营销配置 — 等级门槛与奖励（P0） |
| 优先级 | P0 |

**复用说明**

使用 CRMEB 分销等级（`agent_level` 表）管理"创客/云店/服务商/分公司"。

**配置要求**

在后台配置 4 个分销等级：

| 等级 | 名称 | 升级条件（等级任务） | 一级佣金上浮 | 二级佣金上浮 |
|---|---|---|---|---|
| Lv.1 | 创客 | 直推满 3 单 | 按需配置 | 0 |
| Lv.2 | 云店 | 伞下满 30 单（至少 3 直推） | 按需配置 | 按需配置 |
| Lv.3 | 服务商 | 伞下满 100 单（至少 3 直推） | 按需配置 | 按需配置 |
| Lv.4 | 分公司 | 伞下满 1000 单（至少 3 直推） | 按需配置 | 按需配置 |

**等级任务配置**

通过 CRMEB 的"等级任务"机制（`agent_level_task` 表）设置升级条件：

- 任务类型：推广人数（直推）、推广订单数（伞下）
- 升级条件自动判定，满足后自动升级

**改造要点**

| 改造项 | 说明 |
|---|---|
| 等级数据 | 在后台创建 4 个等级 + 对应等级任务 |
| 佣金上浮 | 等级的 `one_brokerage`/`two_brokerage` 字段配置上浮百分比，通过 `AgentLevelServices::getAgentLevelBrokerage` 自动叠加到基础比例 |
| 积分奖励 | 需在佣金发放链路中新增积分逻辑（见 Part 3） |

**注意**：原 `pages/hjf/memberLevel` 和 `pages/hjf/memberConfig` **不再需要**，其功能由 CRMEB 分销等级管理覆盖。

**依赖 API**

- `GET /adminapi/agent/level` — CRMEB 分销等级列表
- `POST /adminapi/agent/level` — 创建等级
- `PUT /adminapi/agent/level/{id}` — 编辑等级
- `GET /adminapi/agent/level_task` — 等级任务管理

---

### 2.5 积分日志

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/hjf/pointsLog/index.vue` |
| 路由 | `/admin/hjf/points/log`（自定义路由，保留） |
| 当前状态 | **保持（自定义模块）** |
| 优先级 | P1 |

**复用说明**

积分释放体系为自定义扩展，CRMEB 分销模块不覆盖。保留现有 `pointsLog` 页面，集成时 `USE_MOCK` 改 `false`。

---

### 2.6 商品编辑 - 报单标记

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/product/productAdd/components/otherSet.vue` |
| 当前状态 | **缺陷修复（P0）** |
| 优先级 | P0 |

**缺陷说明**

`is_queue_goods` 修改保存后未更新数据库（`issues-0323-1.md`）。

**改造要点**

| 改造项 | 说明 |
|---|---|
| 前端 | 确认 `is_queue_goods` 包含在商品保存 payload |
| 后端 | 确认 `StoreProductServices` 保存时处理 `is_queue_goods` |
| 佣金联动 | 当 `brokerage_scope = queue_only` 时，仅报单商品参与佣金计算 |

---

### 2.7 商品列表

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/product/productList/index.vue` |
| 当前状态 | **已修复，确认稳定** |
| 优先级 | P0 |

**复用说明**

报单商品 Tab 筛选已修复。确认 `is_queue_goods` 筛选生效即可。

---

### 2.8 提现申请管理

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/finance/userExtract/index.vue` |
| 路由 | `/admin/finance/user_extract/index`（CRMEB 原有） |
| 当前状态 | **CRMEB 直接复用** |
| PRD 章节 | 5.5 财务管理 — 提现审核（P0） |
| 优先级 | P0 |

**复用说明**

CRMEB 提现管理完全满足需求。确认手续费率 7% 在 `rake_back` 配置中正确设置。

---

### 2.9 用户管理

| 属性 | 内容 |
|---|---|
| 页面路径 | `pages/user/list/index.vue` |
| 当前状态 | **需增强** |
| 优先级 | P0 |

**改造要点**

| 改造项 | 说明 |
|---|---|
| 新增列 | 分销等级名称（`agent_level_name`，CRMEB 已支持） |
| 新增列 | 待释放积分（`frozen_points`）、已释放积分（`available_points`）— 自定义字段 |
| 操作增强 | "调整分销等级"按钮 → 调用 CRMEB `agentManage/giveAgentLevel` 接口 |
| 操作增强 | "设置不考核"开关 → 自定义接口 `hjf/member/{uid}/no_assess` |

**依赖 API**

- `GET /adminapi/user/user` — CRMEB 用户列表
- `POST /adminapi/agent/manage/give_agent_level` — CRMEB 赋予分销等级
- `PUT /adminapi/hjf/member/{uid}/no_assess` — 自定义不考核设置

---

## Part 3: 后端改造要点

---

### 3.1 佣金计算链路改造（核心）

**改造位置**：`app/services/order/StoreOrderCreateServices.php`（计算佣金金额）+ `app/services/order/StoreOrderTakeServices.php`（发放佣金）

**当前逻辑**

```
一级佣金 = 商品价格 × (store_brokerage_ratio + 等级上浮)
```

**目标逻辑**

```
1. 读取 brokerage_scope 配置：
   - 若 queue_only，仅 is_queue_goods=1 的商品参与
2. 查询推荐人当前周期位置：
   - 统计推荐人下级购买报单商品的有效订单数
   - position = count % cycle_count  (0-indexed)
3. 当前单的佣金比例 = cycle_rates[position]
4. 一级佣金 = 商品实付金额 × 当前比例%
5. 若推荐人有分销等级（创客及以上），额外发放积分奖励
```

**关键文件**

| 文件 | 改造说明 |
|---|---|
| `app/services/order/StoreOrderCreateServices.php` | 修改佣金金额计算：从固定比例改为查询周期位次后取对应比例 |
| `app/services/order/StoreOrderTakeServices.php` | `backOrderBrokerage` 方法：发放佣金时，若有分销等级则额外调用积分奖励逻辑 |
| `app/services/agent/AgentLevelServices.php` | `getAgentLevelBrokerage`：确认等级佣金上浮逻辑与周期比例的叠加方式（加法 or 替代） |
| `app/services/system/config/SystemConfigServices.php` | `rakeBackFormBuild`：新增周期配置表单 |

**数据表变更**

| 表 | 变更 |
|---|---|
| `eb_system_config` | 新增键：`brokerage_cycle_count`、`brokerage_cycle_rates`、`brokerage_scope`、`brokerage_timing` |
| `eb_user`（可选） | 新增字段：`frozen_points`、`available_points`、`no_assess`（若积分模块需要） |

---

### 3.2 分销等级映射

使用 CRMEB `agent_level` 表，无需新建等级表。

| fsgx 等级 | agent_level 配置 | 等级任务 |
|---|---|---|
| 创客 | Lv.1, name="创客" | 任务：直推报单商品订单 ≥ 3 |
| 云店 | Lv.2, name="云店" | 任务：伞下报单商品订单 ≥ 30，且直推 ≥ 3 |
| 服务商 | Lv.3, name="服务商" | 任务：伞下报单商品订单 ≥ 100，且直推 ≥ 3 |
| 分公司 | Lv.4, name="分公司" | 任务：伞下报单商品订单 ≥ 1000，且直推 ≥ 3 |

**注意**：CRMEB 等级任务可能不直接支持"仅计报单商品订单"的条件，需确认 `AgentLevelTaskServices` 是否支持自定义筛选，或需改造任务判定逻辑。

---

### 3.3 积分体系（自定义扩展）

积分释放（待释放/已释放/每日释放）不属于 CRMEB 分销模块，保持为自定义扩展：

- 在佣金发放时（`StoreOrderTakeServices::backOrderBrokerage`），若推荐人有分销等级，同步发放积分到 `frozen_points`
- 定时任务：每日将 `frozen_points` 的 0.4‰ 转入 `available_points`
- 积分消费：购买普通商品时扣减 `available_points`

---

## Part 4: 公共组件与 API 层

---

### 4.1 UniApp 组件

基础路径：`pro_v3.5.1/view/uniapp/components/`

| 组件 | 文件 | 改造说明 | 优先级 |
|---|---|---|---|
| HjfQueueProgress | `HjfQueueProgress.vue` | 改为佣金周期进度环：接收 `cycleCurrent/cycleTotal/cycleRates` | P0 |
| HjfRefundNotice | `HjfRefundNotice.vue` | 改为佣金到账通知弹窗 | P0 |
| HjfAssetCard | `HjfAssetCard.vue` | 文案"公排退款"→"推荐佣金"；余额来源改为 `brokerage_price` | P1 |
| HjfMemberBadge | `HjfMemberBadge.vue` | 保持，等级名称来源改为 `agent_level_name` | P1 |
| HjfDemoPanel | `HjfDemoPanel.vue` | 保持不变（调试用） | — |

---

### 4.2 API 文件

#### 可移除/简化的 API 文件

由于分销模块复用，以下自定义 API 可简化：

| 文件 | 当前 | 目标 |
|---|---|---|
| UniApp `hjfQueue.js` | 公排状态/历史（Mock） | 仅保留 `getBrokerageProgress()` 一个聚合接口；佣金记录由 CRMEB 佣金明细接口代替 |
| UniApp `hjfMember.js` | 会员信息/团队（Mock） | 由 CRMEB `spread` 系列接口代替，可移除 |
| Admin `hjfQueue.js` | 公排订单/配置/财务（Mock） | 移除：佣金订单由 CRMEB 佣金记录代替；配置由 `rake_back` 代替 |
| Admin `hjfMember.js` | 会员列表/配置/等级（Mock） | 移除：由 CRMEB `agent_level` 接口代替 |

#### 保留的自定义 API 文件

| 文件 | 用途 |
|---|---|
| UniApp `hjfAssets.js` | 资产聚合接口（余额+积分+佣金统计），`USE_MOCK` 改 `false` |
| Admin `hjfPoints.js` | 积分释放日志，`USE_MOCK` 改 `false` |

#### 新增接口汇总

| 接口 | 方法 | 说明 |
|---|---|---|
| `/api/hjf/brokerage/progress` | GET | 佣金周期进度聚合（周期位次、比例、累计佣金） |
| `/api/hjf/assets/overview` | GET | 资产总览聚合（佣金余额+积分+等级） |

---

### 4.3 Mock 数据

| 文件 | 改造说明 |
|---|---|
| UniApp `hjfMockData.js` | 公排模块数据替换为佣金数据（字段对齐佣金结构）；`total_queue_refund` → `total_brokerage`；引导文案更新 |
| Admin `hjfMockData.js` | 移除公排 Mock（`MOCK_QUEUE_*`）；会员 Mock 保持（`MOCK_MEMBER_*`）直到 CRMEB 接口完全对接 |

---

## 附录：pages.json 路由改造

| 路由 | 当前标题 | 目标标题 |
|---|---|---|
| `pages/queue/status` | `公排状态` | `推荐佣金` |
| `pages/queue/history` | `公排历史` | `佣金记录`（或重定向到 `user_spread_money`） |
| `pages/queue/rules` | `公排规则` | `佣金规则` |

---

## 附录：Admin 路由改造

原 `hjfQueue.js` 路由精简：

| 路由 | 当前 | 目标 |
|---|---|---|
| `queue/order` | 公排订单管理 | **移除**，使用 CRMEB `/admin/finance/finance/commission` |
| `queue/finance` | 公排财务流水 | **移除**，使用 CRMEB `/admin/finance/finance/commission` |
| `queue/config` | 公排配置 | **移除**，使用 CRMEB `/admin/setting/system_config_rake_back` |
| `member/level` | 会员等级管理 | **移除**，使用 CRMEB `/admin/agent/agent_manage/index` |
| `member/config` | 会员配置 | **移除**，使用 CRMEB `/admin/setting/membership_level/index` |
| `points/log` | 积分日志 | **保留** |

精简后 `hjfQueue.js` 路由仅保留 `points/log`，建议重命名文件为 `hjfCustom.js`。

---

## 附录：开发优先级总览

| 优先级 | 页面/任务 | 数量 |
|---|---|---|
| **P0** | 佣金计算链路改造（后端核心）、返佣设置扩展、商品编辑修复、分销等级配置、推荐佣金进度页、订单确认页、个人中心、我的资产、登录、提现、商品列表、用户管理增强、HjfQueueProgress 组件 | 13 |
| **P1** | 佣金规则说明页、佣金收益页确认、积分明细、推广中心增强、积分日志 Mock 切换、HjfAssetCard/HjfMemberBadge 文案、引导页文案、支付结果文案 | 8 |
| **P2** | 首页 DIY 配置 | 1 |

---

## 附录：被移除/合并的自定义页面清单

以下原 `pages/hjf/` 页面因功能被 CRMEB 分销模块覆盖而**不再需要独立维护**：

| 原页面 | 替代方案 |
|---|---|
| `pages/hjf/queueOrder` | CRMEB `finance/commission`（佣金记录） |
| `pages/hjf/queueFinance` | CRMEB `finance/commission`（佣金记录） |
| `pages/hjf/queueConfig` | CRMEB `setting/system_config_rake_back`（返佣设置，扩展） |
| `pages/hjf/memberLevel` | CRMEB `agent/agentManage`（分销员管理） |
| `pages/hjf/memberConfig` | CRMEB `setting/membershipLevel`（分销等级管理） |
| UniApp `pages/queue/history` | CRMEB `users/user_spread_money`（佣金收益），或保留并重定向 |