简介

本开发文档面向DouPHP小程序的营销功能页面模块，覆盖优惠券领取与使用、分销推广、分享传播、VIP会员等关键能力。文档从系统架构、数据模型、业务流程、接口调用到优化策略与常见问题进行系统化说明，帮助开发者快速理解并扩展营销相关功能。

项目结构

营销功能在小程序端以页面为单位组织，后端通过API路由暴露能力，业务逻辑由前后端服务协同完成，数据模型集中在front/admin的对应模块中。

graph TB
subgraph "小程序前端"
C["优惠券页面<br/>pages/coupon"]
D["分销页面<br/>pages/distribution"]
S["分享页面<br/>pages/share"]
V["VIP页面<br/>pages/vip"]
U["工具库<br/>utils/promotion.ts"]
end
subgraph "API层"
RC["coupon 路由"]
RD["distribution 路由"]
RS["share 路由"]
RV["vip 路由"]
end
subgraph "业务服务"
FC["Coupon 服务"]
FD["Distribution 服务"]
FS["Share 服务"]
FV["Vip 服务"]
end
subgraph "数据模型"
MC["Coupon 模型"]
MD["Distribution 模型"]
MS["Share 模型"]
MV["Vip 模型"]
end
C --> RC
D --> RD
S --> RS
V --> RV
RC --> FC
RD --> FD
RS --> FS
RV --> FV
FC --> MC
FD --> MD
FS --> MS
FV --> MV

核心组件

• 优惠券：提供领取、查看、使用（下单抵扣）能力，包含状态流转与规则校验。
• 分销：建立上下级关系，记录佣金明细，支持结算与统计。
• 分享：生成带追踪参数的分享链接/二维码，统计点击、转化效果。
• VIP：等级体系、权益展示、续费管理。

架构总览

小程序页面通过统一HTTP服务调用API路由，路由将请求分发至对应业务服务，服务操作数据模型完成持久化与计算，最终返回结果给前端渲染或交互。

sequenceDiagram
participant U as "用户"
participant P as "小程序页面"
participant API as "API路由"
participant SVC as "业务服务"
participant M as "数据模型"
U->>P : 触发操作(领取/使用/分享/加入分销/购买VIP)
P->>API : 发起请求(携带参数与凭证)
API->>SVC : 调用具体方法
SVC->>M : 读取/写入数据
M-->>SVC : 返回结果
SVC-->>API : 封装响应
API-->>P : 返回数据
P-->>U : 更新界面/提示结果

详细组件分析

优惠券模块

• 领取流程：校验用户资格、券库存、有效期、适用范围；成功后记录领取日志。
• 使用流程：下单时选择可用券，服务端校验门槛金额、商品范围、叠加规则；扣减后标记使用。
• 状态流转：未使用→已使用/已过期；可配置防刷策略（如限制领取次数、设备/IP限流）。

flowchart TD
Start(["开始"]) --> CheckUser["校验用户资格"]
CheckUser --> |通过| CheckStock["检查库存与规则"]
CheckUser --> |不通过| EndFail["结束(失败)"]
CheckStock --> |通过| Issue["发放优惠券"]
CheckStock --> |不通过| EndFail
Issue --> Log["记录领取日志"]
Log --> EndOk["结束(成功)"]

分销模块

• 关系建立：通过邀请码/链接绑定上下级关系，支持层级与比例配置。
• 佣金计算：基于订单金额、商品佣金比例、层级系数计算；支持冻结期与结算。
• 统计与提现：展示收益明细、团队业绩、可提现余额。

sequenceDiagram
participant A as "邀请人"
participant B as "被邀请人"
participant API as "API路由"
participant SVC as "分销服务"
participant M as "分销模型"
B->>API : 提交邀请码/链接参数
API->>SVC : 建立分销关系
SVC->>M : 写入关系表
M-->>SVC : 成功
SVC-->>API : 返回绑定结果
API-->>B : 提示绑定成功
Note over A,B : 后续订单产生佣金
B->>API : 下单(含分销标识)
API->>SVC : 计算佣金并记录
SVC->>M : 写入佣金明细
M-->>SVC : 成功
SVC-->>API : 返回佣金信息
API-->>A : 更新收益

分享模块

• 链接生成：为商品/活动页生成带追踪参数的分享链接或二维码，包含来源、渠道、时间戳等。
• 追踪统计：记录点击、访问、注册、下单等事件，形成转化漏斗。
• 裂变机制：结合分销与优惠券，实现“分享→领券→下单→再分享”的闭环。

sequenceDiagram
participant U as "用户"
participant P as "分享页面"
participant API as "分享路由"
participant SVC as "分享服务"
participant M as "分享模型"
U->>P : 点击分享
P->>API : 生成分享链接/二维码
API->>SVC : 创建追踪记录
SVC->>M : 写入分享ID与参数
M-->>SVC : 成功
SVC-->>API : 返回链接/二维码
API-->>P : 展示分享素材
Note over U,P : 被分享者打开链接
U->>API : 访问分享链接(携带追踪参数)
API->>SVC : 记录访问/转化事件
SVC->>M : 更新统计
M-->>SVC : 成功
SVC-->>API : 返回统计结果

VIP模块

• 等级体系：定义等级名称、权益、升级条件（累计消费/积分/时长）。
• 续费管理：支持按周期续费，自动续期或手动续费；到期提醒。
• 权益应用：下单折扣、专属券、优先客服等。

stateDiagram-v2
[*] --> 未开通
未开通 --> 试用中 : "首次开通"
试用中 --> 正式会员 : "支付成功"
正式会员 --> 即将到期 : "到期前提醒"
即将到期 --> 已过期 : "未续费"
已过期 --> 未开通 : "重新购买"
正式会员 --> 已过期 : "未续费"
已过期 --> 正式会员 : "续费成功"

依赖关系分析

• 前端依赖：小程序页面依赖HTTP服务与工具库（如promotion.ts），用于组装参数、处理分享与促销逻辑。
• 路由依赖：API路由根据路径分发到对应控制器与服务。
• 服务依赖：各业务服务依赖数据模型进行CRUD与复杂计算。
• 模型依赖：数据模型与数据库表结构映射，支撑状态机与统计。

graph LR
P1["coupon.ts"] --> R1["coupon.php"]
P2["distribution/index.ts"] --> R2["distribution.php"]
P3["share/index.ts"] --> R3["share.php"]
P4["vip/index.ts"] --> R4["vip.php"]
R1 --> S1["Coupon 服务"]
R2 --> S2["Distribution 服务"]
R3 --> S3["Share 服务"]
R4 --> S4["Vip 服务"]
S1 --> M1["Coupon 模型"]
S2 --> M2["Distribution 模型"]
S3 --> M3["Share 模型"]
S4 --> M4["Vip 模型"]

性能考虑

• 缓存策略：对热门券列表、VIP等级、分享统计热点数据进行缓存，降低DB压力。
• 异步处理：佣金结算、分享统计上报采用队列异步处理，避免阻塞主流程。
• 限流与熔断：对高频接口（如领券、分享）实施限流，防止恶意刷取。
• 索引优化：为常用查询字段（用户ID、券ID、订单ID、分享ID）建立索引，提升查询效率。

故障排查指南

• 优惠券防刷

  • 现象：短时间内大量领取或使用异常。
  • 排查：检查领取频率限制、设备/IP限流、库存并发控制。
  • 参考：miniprogram/default/pages/coupon/coupon.ts、api/route/coupon.php、front/model/coupon/Coupon.php

• 分销作弊检测

  • 现象：同一用户多次绑定不同上级、虚假订单刷佣。
  • 排查：校验绑定唯一性、订单真实性、佣金计算规则一致性。
  • 参考：miniprogram/default/pages/distribution/index.ts、api/route/distribution.php、front/model/distribution/Distribution.php

• 分享链接失效

  • 现象：分享链接无法打开或无追踪数据。
  • 排查：检查分享参数完整性、路由解析、统计写入是否成功。
  • 参考：miniprogram/default/pages/share/index.ts、api/route/share.php、front/model/share/Share.php

• VIP续费失败

  • 现象：续费支付成功但状态未更新。
  • 排查：支付回调处理、状态同步、重试机制。
  • 参考：miniprogram/default/pages/vip/index.ts、api/route/vip.php、front/model/vip/Vip.php

结论

本模块围绕“券-分-享-VIP”四大营销能力构建，通过清晰的前后端分层与数据模型设计，实现了可配置、可扩展的营销活动体系。建议在生产环境加强限流与风控、完善统计与分析、持续优化用户体验与转化率。

附录

• 开发示例指引
  • 二维码生成：在分享页面调用工具库生成带追踪参数的二维码，便于线下投放与线上裂变。
  • 邀请链接分享：分销页面生成邀请链接，附带邀请人与渠道参数，便于归因统计。
  • 佣金结算：分销服务按订单与规则计算佣金，支持冻结期与批量结算任务。
• 推广效果优化
  • 提升分享转化率：优化分享素材、设置新用户首单优惠、简化下单流程。
  • 裂变传播机制：结合分销与优惠券，设计“分享→领券→下单→再分享”的激励闭环。
  • 用户激励策略：阶梯奖励、限时加成、排行榜与成就徽章，增强参与感与复购率。