434aa8c69d
Phase1 后端核心：
- 新增 fsgx_v1.sql 迁移脚本（is_queue_goods/frozen_points/available_points/no_assess）
- SystemConfigServices 返佣设置扩展（周期人数/分档比例/范围/时机）
- StoreOrderCreateServices 周期循环佣金计算
- StoreOrderTakeServices 佣金发放后同步冻结积分
- StoreProductServices/StoreProduct 保存 is_queue_goods
Phase2 后端接口：
- GET /api/hjf/brokerage/progress 佣金周期进度
- GET /api/hjf/assets/overview 资产总览
- HjfPointsServices 每日 frozen_points 0.4‰ 释放定时任务
- PUT /adminapi/hjf/member/{uid}/no_assess 不考核接口
- GET /adminapi/hjf/points/release_log 积分日志接口
Phase3 前端清理：
- hjfCustom.js 路由精简（仅保留 points/log）
- hjfQueue.js/hjfMember.js API 清理/重定向至 CRMEB 原生接口
- pages.json 公排→推荐佣金/佣金记录/佣金规则
Phase4-5 前端改造：
- queue/status.vue 推荐佣金进度页整体重写
- 商品详情/订单确认/支付结果页文案与逻辑改造
- 个人中心/资产页/引导页/规则页文案改造
- HjfQueueProgress/HjfRefundNotice/HjfAssetCard 组件改造
- 推广中心嵌入佣金进度摘要
- hjfMockData.js 全量更新（公排字段→佣金字段）
Phase6 Admin 增强：
- 用户列表新增 frozen_points/available_points 列及不考核操作按钮
- hjfPoints.js USE_MOCK=false 对接真实积分日志接口
Phase7 配置文档：
- docs/fsgx-phase7-config-checklist.md 后台配置与全链路验收清单
Made-with: Cursor
311 lines
12 KiB
Markdown
311 lines
12 KiB
Markdown
# 范氏国香商城小程序 · 产品需求文档（PRD）V1.0
|
||
|
||
> 技术底座：CRMEB Pro v3.5 二次开发
|
||
> 文档日期：2026-03-23
|
||
> 文档状态：当前分支产品需求基线（对齐 fsgx 需求）
|
||
|
||
---
|
||
|
||
## 1. 文档说明
|
||
|
||
### 1.1 文档目的
|
||
|
||
本文档基于《范氏国香小程序fsgx-V1.0.docx》整理，定义范氏国香商城小程序（微信端 + 管理后台）的功能范围、核心业务逻辑、参数配置和交付验收标准，并明确当前分支与目标需求的差异，作为后续研发、测试与运营的统一依据。
|
||
|
||
### 1.2 文档范围
|
||
|
||
- 用户端（微信小程序）功能需求
|
||
- 管理后台（PC端）功能需求
|
||
- 核心业务逻辑（推荐返现、会员等级、积分释放）
|
||
- 数据改造与非功能性要求
|
||
- 当前版本不一致/不满足项清单
|
||
|
||
### 1.3 术语定义
|
||
|
||
| 术语 | 定义 |
|
||
|---|---|
|
||
| 报单商品 | 参与推荐奖励与等级业绩统计的商品，当前目标主商品为艾制品三条套餐（4333元/单） |
|
||
| 普通商品 | 不参与推荐奖励的商品，可支持积分支付 |
|
||
| 待释放积分 | 推荐奖励入账后冻结的积分，按日释放 |
|
||
| 已释放积分 | 已完成释放、可消费的积分，仅可用于普通商品 |
|
||
| 直推 | 用户直接邀请并绑定的一级成员 |
|
||
| 伞下 | 用户的所有直推及其下级组成的推荐网络 |
|
||
| 会员分销等级 | 创客、云店、服务商、分公司 |
|
||
| 级差 | 上级可获得的奖励与下级当前等级奖励之间的差额机制 |
|
||
| 推荐返现循环 | 邀请满 3 人按 20%/30%/50%返现，后续继续按 3 人周期循环 |
|
||
|
||
### 1.4 版本记录
|
||
|
||
| 版本 | 日期 | 变更说明 | 负责人 |
|
||
|---|---|---|---|
|
||
| V1.0 | 2026-03-23 | 首版：按 fsgx 需求重编写，并纳入当前分支差异清单 | AI + 产品/研发 |
|
||
|
||
---
|
||
|
||
## 2. 产品概述
|
||
|
||
### 2.1 产品背景
|
||
|
||
范氏国香商城定位于大健康艾制品电商场景，通过小程序承载商品销售、社交裂变与会员激励，形成“购买-推荐-复购”的增长闭环。
|
||
|
||
### 2.2 产品定位
|
||
|
||
| 维度 | 描述 |
|
||
|---|---|
|
||
| 产品形态 | 微信小程序 + PC 管理后台 |
|
||
| 核心商品 | 艾制品三条套餐（4333元/单）及周边商品 |
|
||
| 商业模式 | 社交裂变 + 推荐返现 + 会员积分体系 |
|
||
| 目标用户 | 有健康消费需求且具备社交分享意愿的用户 |
|
||
| 核心差异化 | 邀请三人返现免单机制 + 分级积分激励 |
|
||
|
||
### 2.3 目标用户
|
||
|
||
| 用户类型 | 特征 | 核心诉求 |
|
||
|---|---|---|
|
||
| 普通消费者 | 首购用户，关注商品价值 | 流畅下单与可见返现规则 |
|
||
| 推广用户（创客） | 有一定社交资源 | 明确返现进度和积分收益 |
|
||
| 团队用户（云店/服务商） | 有管理下级需求 | 团队数据透明、收益可追踪 |
|
||
| 平台运营人员 | 负责运营与风控 | 高效配置、可追溯财务与订单 |
|
||
|
||
### 2.4 产品目标
|
||
|
||
- 为用户提供明确、可预期的推荐返现与积分成长体验
|
||
- 通过返现循环与等级激励提高裂变转化与复购
|
||
- 为运营提供“参数可配、过程可查、结果可审计”的后台系统
|
||
- 保持 CRMEB 复用能力，降低二开复杂度与维护成本
|
||
|
||
---
|
||
|
||
## 3. 核心业务逻辑
|
||
|
||
### 3.1 推荐返现机制（核心）
|
||
|
||
#### 3.1.1 基础规则
|
||
|
||
- 用户 A 邀请的直推成员按“购买报单商品并支付成功”计入有效推荐
|
||
- 同一推荐周期按 3 人结算：
|
||
- 第 1 人：返现 20%
|
||
- 第 2 人：返现 30%
|
||
- 第 3 人：返现 50%
|
||
- 累计返现 100% 后进入下一轮 3 人循环
|
||
- 返现金额进入用户现金余额，可提现（扣除手续费）
|
||
|
||
#### 3.1.2 可配置参数
|
||
|
||
- 周期人数（默认 3）
|
||
- 周期内每位返现比例（默认 20/30/50）
|
||
- 返现基数（按实付金额/按固定金额）
|
||
- 返现发放时机（支付即发放/确认收货后）
|
||
|
||
#### 3.1.3 异常与边界
|
||
|
||
- 退款/撤单后，需回滚对应返现及进度
|
||
- 同设备/同账号异常刷单需支持风控拦截
|
||
- 后台人工取消订单时，需同步返现逆操作并记录审计日志
|
||
|
||
### 3.2 会员等级体系
|
||
|
||
| 等级 | 升级条件 | 直推积分奖励 | 伞下积分奖励 | 说明 |
|
||
|---|---|---:|---:|---|
|
||
| 普通会员 | 注册即得 | 0 | 0 | 可参与推荐返现 |
|
||
| 创客 | 直推满3单 | 500 | 0 | 阈值可配置 |
|
||
| 云店 | 伞下满30单（至少3直推） | 800 | 300 | 级差计算 |
|
||
| 服务商 | 伞下满100单（至少3直推） | 1000 | 200 | 级差计算 |
|
||
| 分公司 | 伞下满1000单（至少3直推） | 1300 | 300 | 级差计算 |
|
||
|
||
规则补充：
|
||
|
||
- 等级默认自动升级，允许后台手动调整
|
||
- 支持“不考核”开关，标记用户不参与自动考核
|
||
- 批量购买触发升级时，先升级后结算剩余单据奖励
|
||
|
||
### 3.3 账户与积分体系
|
||
|
||
| 账户 | 来源 | 用途 | 提现 |
|
||
|---|---|---|---|
|
||
| 现金余额 | 推荐返现、后台充值 | 消费、提现 | 可提现（默认7%手续费） |
|
||
| 待释放积分 | 等级后推荐奖励 | 按日释放 | 不可提现 |
|
||
| 已释放积分 | 每日释放所得 | 购买普通商品 | 不可提现 |
|
||
|
||
积分规则：
|
||
|
||
- 日释放比例默认 0.4%（千分之四），后台可调
|
||
- 积分不可转赠，不可直接提现
|
||
- 报单商品不允许积分支付
|
||
|
||
### 3.4 多单购买与升级联动
|
||
|
||
- 用户一次购买 N 单报单商品时：
|
||
1. 先按新增有效业绩判断是否升级
|
||
2. 从达标后剩余单数起，按新等级发放积分奖励
|
||
3. 推荐返现按周期规则逐单累计
|
||
|
||
---
|
||
|
||
## 4. 用户端功能需求（小程序）
|
||
|
||
### 4.1 登录与注册
|
||
|
||
- 微信授权登录、手机号快捷绑定（P0）
|
||
- 推荐关系参数绑定且不可篡改（P0）
|
||
- 新用户规则引导页（P1）
|
||
|
||
### 4.2 首页
|
||
|
||
- Banner 与活动专区（P0）
|
||
- 报单商品与普通商品推荐区（P0）
|
||
- 公告通知（P1）
|
||
|
||
### 4.3 商品与购买
|
||
|
||
- 商品分为报单商品与普通商品
|
||
- 订单提交与支付成功后触发：推荐返现 + 等级积分逻辑
|
||
- 支付方式：
|
||
- 微信/支付宝：所有商品
|
||
- 余额：按后台商品配置
|
||
- 积分：仅普通商品，且受后台配置控制
|
||
|
||
### 4.4 推荐裂变
|
||
|
||
- 专属分享海报和邀请链接
|
||
- 推荐关系树可视化展示（直推/伞下）
|
||
- 推荐收益列表（返现 + 积分）可追踪到订单
|
||
- 推荐返现循环进度展示（当前周期第几人、已返现金额、下一档比例）
|
||
|
||
### 4.5 个人中心
|
||
|
||
- 我的订单：状态筛选、详情、物流、售后
|
||
- 我的资产：现金余额、待释放积分、已释放积分
|
||
- 我的推荐：人数、订单、等级、收益统计
|
||
- 提现申请：显示手续费、预计到账金额
|
||
|
||
---
|
||
|
||
## 5. 管理后台功能需求（PC端）
|
||
|
||
### 5.1 数据看板
|
||
|
||
- 今日新增、订单、销售额、返现金额
|
||
- 推荐转化漏斗（邀请点击 -> 绑定 -> 首购）
|
||
- 会员等级分布与升级趋势
|
||
|
||
### 5.2 用户管理
|
||
|
||
- 用户查询、详情、关系树
|
||
- 等级手动调整、不考核开关
|
||
- 账户资金与积分人工调整（带原因与日志）
|
||
|
||
### 5.3 商品管理
|
||
|
||
- 报单商品标记 `is_queue_goods`
|
||
- 支付方式可配置（余额/积分开关）
|
||
- 上下架、库存、预警
|
||
|
||
### 5.4 订单管理
|
||
|
||
- 订单检索、详情、发货、售后
|
||
- 支持后台取消订单并触发全额返还逻辑
|
||
- 取消/退款对返现与积分的冲销记录
|
||
|
||
### 5.5 财务管理
|
||
|
||
- 推荐返现流水（按用户/订单/周期）
|
||
- 提现申请审核与手续费管理
|
||
- 积分发放与释放日志
|
||
- 日/月/年报表导出
|
||
|
||
### 5.6 营销配置中心
|
||
|
||
- 推荐返现周期人数
|
||
- 分段返现比例（如 20/30/50）
|
||
- 等级升级门槛与奖励值
|
||
- 积分释放比例
|
||
- 提现手续费
|
||
- 返佣范围配置：所有商品 / 仅报单商品
|
||
|
||
### 5.7 内容与活动管理
|
||
|
||
- Banner、文章、公告管理
|
||
- 活动发布、报名、核销
|
||
|
||
---
|
||
|
||
## 6. 与当前版本不一致/不满足功能点（重点）
|
||
|
||
说明：以下“当前版本”基于当前分支代码与既有 HJF 方案，对照 fsgx V1.0 目标形成。
|
||
|
||
| 序号 | 功能点 | fsgx 目标要求 | 当前版本现状 | 差异结论 | 优先级 |
|
||
|---:|---|---|---|---|---|
|
||
| 1 | 核心激励模型 | 邀请三人返现 20/30/50 循环 | 以“公排进四退一”为主展示与规则 | 重大不一致 | P0 |
|
||
| 2 | 返现来源定义 | 现金余额主要来源为推荐返现 | 当前语义与实现更偏公排退款 | 业务口径不一致 | P0 |
|
||
| 3 | 普通会员奖励 | 普通会员可参与返现（升级后叠加积分） | 当前描述与逻辑偏“升级后才有主要奖励” | 奖励起点不一致 | P0 |
|
||
| 4 | 批量购买升级结算 | 先升级再结算剩余单奖励 | 当前未形成明确落地逻辑 | 功能缺失 | P0 |
|
||
| 5 | 后台取消订单返还 | 支持后台取消后全额返还 | 当前规则与流程未完整覆盖 | 功能缺失 | P0 |
|
||
| 6 | 营销参数模型 | 返现比例与人数可自由配置 | 当前仍有公排触发倍数相关配置 | 参数模型不一致 | P0 |
|
||
| 7 | 返佣范围配置 | 支持“所有商品/报单商品” | 已提出问题项，未确认完整落地 | 功能不完整 | P1 |
|
||
| 8 | 商品编辑 is_queue_goods | 保存后需正确落库 | 已有缺陷记录：修改后未更新数据库 | 缺陷待修复 | P0 |
|
||
| 9 | 前端文案与页面结构 | 以推荐返现为主叙事 | 当前存在 queue 公排页面及文案 | 交互叙事不一致 | P1 |
|
||
| 10 | Mock 到真实接口收敛 | 关键模块应接入真实 API | 部分 HJF 模块仍为 USE_MOCK | 集成不完整 | P1 |
|
||
|
||
建议验收标准（针对差异）：
|
||
|
||
- 返现配置改动后，下一笔有效订单按新规则生效并可追溯
|
||
- 推荐三人循环在用户端可见进度且与财务流水一致
|
||
- 取消订单时，返现与积分冲销一致且无脏账
|
||
- `is_queue_goods` 在商品编辑保存后稳定落库并影响支付/奖励逻辑
|
||
|
||
---
|
||
|
||
## 7. 数据库与接口改造方案
|
||
|
||
### 7.1 数据模型建议
|
||
|
||
- 返现进度表：记录用户返现周期状态（周期索引、当前位次、累计返现金额）
|
||
- 返现流水表：记录返现发放/冲销明细（来源订单、比例、金额、状态）
|
||
- 奖励配置表：支持“周期人数 + 分段比例”可配置
|
||
- 订单扩展字段：记录是否参与返现、返现计算版本
|
||
|
||
### 7.2 关键接口建议
|
||
|
||
- `GET /api/rebate/progress`：用户当前返现周期进度
|
||
- `GET /api/rebate/logs`：返现流水列表
|
||
- `PUT /admin/rebate/config`：返现配置管理
|
||
- `POST /admin/order/cancel_refund`：后台取消并触发返还/冲销
|
||
|
||
### 7.3 兼容策略
|
||
|
||
- 保留旧数据结构，新增版本号字段区分公排历史与返现新逻辑
|
||
- 新逻辑灰度开关，允许按时间或商品范围切换
|
||
- 财务报表提供历史口径与新口径并行查询
|
||
|
||
---
|
||
|
||
## 8. 非功能性需求
|
||
|
||
### 8.1 性能
|
||
|
||
- 下单后奖励计算链路接口 P95 < 300ms（异步结算除外）
|
||
- 财务流水分页查询在 10 万级数据下响应 < 2s
|
||
- 每日积分释放任务在 5 分钟内完成
|
||
|
||
### 8.2 一致性与安全
|
||
|
||
- 奖励发放、冲销、提现须事务一致
|
||
- 订单状态变化与奖励状态双向校验，避免重复发放
|
||
- 所有金额计算使用高精度方案，禁止浮点误差
|
||
- 关键操作（配置变更、人工调账、取消返还）必须审计留痕
|
||
|
||
### 8.3 可运维性
|
||
|
||
- 关键任务提供失败重试与报警
|
||
- 提供“按订单重算奖励”工具接口（仅管理员可用）
|
||
- 配置变更需记录操作者、变更前后值、生效时间
|
||
|
||
---
|
||
|
||
## 附录 A：本版本实施优先级（建议）
|
||
|
||
- P0（首批上线）：核心返现引擎、订单取消返还、商品报单标记修复、财务流水闭环
|
||
- P1（第二阶段）：推荐进度可视化、营销配置增强、Mock 全量切换真实接口
|
||
- P2（优化阶段）：风控规则、运营分析看板深化、批量重算工具
|