huangjingfen/docs/PRD_fsgx_V1.0.md

# 范氏国香商城小程序 · 产品需求文档（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（优化阶段）：风控规则、运营分析看板深化、批量重算工具