简介

本开发文档面向DouPHP小程序VIP会员功能页面，围绕VIP会员等级管理、权益展示、续费管理等核心能力进行系统化说明。重点覆盖：

• 数据模型设计：会员等级定义、权益配置、有效期管理
• 开通流程：购买流程、支付方式集成、自动续费设置
• 权益展示：专属折扣、优先服务、免费试用等权益的落地方式
• 会员中心页面：会员状态查询、权益查看、续费操作
• 管理功能：等级升级、降级处理、权限控制
• 营销能力：限时优惠、推荐奖励、体验卡发放
• 常见问题：续费失败处理、权益异常恢复、会员状态同步

项目结构

与VIP会员相关的前后端代码主要分布在以下位置：

• API层：小程序端接口入口，负责返回套餐列表、用户VIP记录等
• 前台Web：PC端或H5的VIP页面与会员中心
• 后台管理：VIP记录管理与批量操作
• 基础能力：VIP生命周期状态判定工具类
• 语言包：多语言文案支持
• 升级脚本：数据库字段迁移与状态机对齐

graph TB
subgraph "小程序/API"
A["api/controller/vip/VipController.php"]
B["api/controller/vip/UserController.php"]
end
subgraph "前台Web"
C["front/controller/vip/VipController.php"]
D["front/controller/vip/UserController.php"]
E["front/service/vip/VipService.php"]
end
subgraph "后台管理"
F["admin/controller/vip/VipController.php"]
end
subgraph "基础能力"
G["core/foundation/vip/VipStatus.php"]
end
subgraph "语言与升级"
H["languages/en_us/vip.lang.php"]
I["_'/module/vip/_update/data/upgrade.php"]
end
A --> E
B --> E
C --> E
D --> E
F --> E
E --> G
A -.-> H
B -.-> H
C -.-> H
D -.-> H
F -.-> H
E -.-> I

核心组件

• 小程序VIP控制器：提供VIP套餐列表、支付成功页等接口
• 小程序会员中心控制器：按当前登录用户分页获取VIP开通记录
• 前台VIP服务：组装VIP套餐展示数据、拼装VIP记录列表并附加订单链接与状态徽章
• 前台VIP控制器：渲染VIP页面与会员中心页面
• 后台VIP控制器：VIP记录列表、删除、批量操作
• 基础状态工具：根据起止时间计算VIP当前状态（生效中/已过期/无记录），并提供徽章样式映射
• 语言包：统一VIP相关文案
• 升级脚本：将VIP表状态字段与订单状态机对齐，确保前后端一致

架构总览

小程序端通过API访问VIP相关能力；前台Web用于PC/H5展示；后台用于运营与管理。VIP服务作为业务编排层，聚合模型与工具类，对外暴露清晰的数据结构。

sequenceDiagram
participant Mini as "小程序前端"
participant ApiVip as "api/controller/vip/VipController.php"
participant ApiUser as "api/controller/vip/UserController.php"
participant Svc as "front/service/vip/VipService.php"
participant Status as "core/foundation/vip/VipStatus.php"
Mini->>ApiVip : 请求VIP套餐列表
ApiVip->>Svc : buildVipPackageListData()
Svc-->>ApiVip : 套餐列表数据
ApiVip-->>Mini : 返回套餐数据
Mini->>ApiUser : 请求我的VIP记录
ApiUser->>Svc : buildVipLogListData(userId, page)
Svc->>Status : classify(start_at,end_at,now)
Status-->>Svc : active/expired/none
Svc-->>ApiUser : 记录列表+状态徽章
ApiUser-->>Mini : 返回记录数据

详细组件分析

小程序VIP套餐与记录接口

• 套餐列表接口：返回套餐名称、天数、价格、内容、图片等，供小程序展示购买选项
• 会员中心接口：按当前用户ID分页拉取VIP开通记录，包含订单号、价格、起止时间、IP、订单状态、创建时间等

sequenceDiagram
participant App as "小程序"
participant Ctrl as "api/controller/vip/VipController.php"
participant UserCtrl as "api/controller/vip/UserController.php"
participant Service as "front/service/vip/VipService.php"
App->>Ctrl : GET /?route=vip
Ctrl->>Service : buildVipPackageListData()
Service-->>Ctrl : 套餐数组
Ctrl-->>App : {title, package_list, content_field}
App->>UserCtrl : GET /?route=vip/user&page=1
UserCtrl->>Service : buildVipLogListData(userId, page, url)
Service-->>UserCtrl : {vip_log, pager}
UserCtrl-->>App : {title, log_list, pager}

前台VIP页面与会员中心

• VIP页面：加载套餐列表与可配置的内容字段，渲染购买入口
• 会员中心：按当前登录用户拉取VIP记录并分页展示，附带订单跳转链接

flowchart TD
Start(["进入VIP页面"]) --> LoadPkg["加载VIP套餐列表"]
LoadPkg --> RenderPage["渲染套餐卡片与内容字段"]
RenderPage --> ClickBuy{"点击购买?"}
ClickBuy -- 是 --> PayFlow["跳转支付流程(由下单/支付模块处理)"]
ClickBuy -- 否 --> End(["结束"])
PayFlow --> Success["支付回调/成功页"]
Success --> End

后台VIP记录管理

• 列表页：支持用户名、时间范围筛选与分页
• 删除与批量操作：单条删除与批量删除，返回统一结果

sequenceDiagram
participant Admin as "后台管理员"
participant ACtrl as "admin/controller/vip/VipController.php"
participant ASvc as "Admin VipService"
Admin->>ACtrl : 打开VIP记录列表
ACtrl->>ASvc : buildVipLogListData(username,time_start,time_end,page)
ASvc-->>ACtrl : 列表+分页
ACtrl-->>Admin : 渲染列表
Admin->>ACtrl : 删除/批量删除
ACtrl->>ASvc : deleteByIdOrConfirm()/batchDelete()
ASvc-->>ACtrl : 结果
ACtrl-->>Admin : 提示与跳转

VIP生命周期状态判定

• 三态模型：生效中、已过期、无记录
• 判定逻辑：基于start_at与end_at与当前时间比较，未来生效区间仍视为生效中
• 徽章样式：不同状态对应不同颜色，便于UI展示

flowchart TD
S(["输入 start_at, end_at, now"]) --> Check1{"end_at > now ?"}
Check1 -- 否 --> Expired["返回 EXPIRED"]
Check1 -- 是 --> Check2{"start_at <= now ?"}
Check2 -- 是 --> Active["返回 ACTIVE"]
Check2 -- 否 --> FutureActive["返回 ACTIVE<br/>未来生效区间"]

数据模型与字段说明

• VIP记录表关键字段
  • order_sn：订单编号
  • price：套餐价格
  • sale_price：促销价（升级脚本新增）
  • sale_price_type：促销价类型（升级脚本新增）
  • start_at：开始时间
  • end_at：结束时间
  • order_status：订单状态快照（字符串状态机：pending/paid/completed/cancelled）
  • created_at：购买时间
  • ip：下单IP
• VIP套餐表关键字段
  • id：主键
  • name：套餐名称
  • day：VIP天数
  • price：原价
  • promote_price/promote_end_at：促销价与截止时间（升级脚本对时间字段统一）
  • image：图片
  • content：权益描述（换行分隔）

开通流程与支付集成

• 购买入口：小程序或前台页面选择套餐后发起下单
• 支付集成：由系统订单与支付插件完成（如微信支付、支付宝等），成功后回调更新订单与VIP记录
• 自动续费：可在订单或套餐层面配置周期扣款策略（具体实现由订单/订阅模块负责）
• 状态同步：VIP记录的order_status与订单状态保持一致，升级脚本确保状态机对齐

sequenceDiagram
participant U as "用户"
participant Front as "小程序/前台"
participant Order as "订单/支付模块"
participant Vip as "VIP服务"
participant DB as "数据库"
U->>Front : 选择套餐并下单
Front->>Order : 创建订单并发起支付
Order-->>U : 唤起支付
U-->>Order : 完成支付
Order->>DB : 写入订单与VIP记录(order_status=paid)
Order->>Vip : 触发VIP开通/续费逻辑
Vip->>DB : 更新start_at/end_at
Vip-->>Front : 返回成功

权益展示示例

• 专属折扣：在商品结算时根据VIP状态应用折扣规则（由商品/订单模块结合VIP状态实现）
• 优先服务：客服或工单优先级标识（由服务模块读取VIP状态）
• 免费试用：为VIP用户开放特定资源或次数（由资源/配额模块校验VIP状态）

说明：以上权益的具体实现位于各自业务模块，VIP状态作为统一判断依据。

会员中心功能实现

• 会员状态查询：通过API拉取VIP记录，结合起止时间计算当前状态
• 权益查看：套餐content字段以换行拆分展示权益条目
• 续费操作：再次选择套餐下单，支持叠加有效期

管理功能：等级升降与权限控制

• 等级升降：可通过后台调整用户等级或发放体验卡（由用户/等级模块配合VIP状态使用）
• 权限控制：在需要VIP权限的接口或页面中，依据VIP状态进行鉴权

营销功能：限时优惠、推荐奖励、体验卡

• 限时优惠：套餐促销价与截止时间（promote_price/promote_end_at）
• 推荐奖励：通过分销或积分模块发放奖励（与VIP独立但可联动）
• 体验卡：临时授予VIP权益（通过VIP记录或用户等级扩展）

依赖关系分析

• 控制器依赖服务：API与前台控制器均依赖VipService进行数据组装
• 服务依赖模型与工具：VipService调用VIP与套餐模型，并使用VipStatus进行状态判定
• 语言包贯穿各层：所有界面文案通过语言包统一输出
• 升级脚本保障一致性：确保VIP表状态字段与订单状态机一致

graph LR
ApiCtrl["api/controller/vip/*.php"] --> Svc["front/service/vip/VipService.php"]
FrontCtrl["front/controller/vip/*.php"] --> Svc
AdminCtrl["admin/controller/vip/VipController.php"] --> Svc
Svc --> Status["core/foundation/vip/VipStatus.php"]
Svc --> Lang["languages/en_us/vip.lang.php"]
Svc --> Upgrade["_'/module/vip/_update/data/upgrade.php"]

性能考虑

• 分页加载：VIP记录采用分页，避免一次性加载过多数据
• 状态计算：状态判定基于时间戳比较，复杂度O(1)，适合高频展示
• 图片与内容：套餐图片与内容按需加载，减少首屏压力
• 缓存建议：套餐列表与内容字段可考虑短期缓存，降低重复查询

故障排查指南

• 续费失败
  • 检查是否存在未付款订单：语言包提示存在未付款订单时需引导继续支付或取消
  • 核对订单状态与VIP记录状态是否一致，必要时执行状态同步
• 权益异常恢复
  • 确认VIP起止时间是否正确，必要时重新生成start_at/end_at
  • 检查套餐内容与配置是否被误改
• 会员状态同步
  • 升级脚本已将order_status切换为字符串状态机，确保前后端一致
  • 若出现不一致，检查支付回调与VIP开通逻辑是否完整执行

结论

本项目的小程序VIP会员功能以清晰的分层架构实现：API层提供数据接口，前台服务负责业务编排，基础状态工具保证状态判定一致性。通过升级脚本对齐状态机，确保前后端行为一致。结合语言包与后台管理能力，形成完整的VIP购买、展示、续费与管理闭环。后续可在权益模块与营销模块进一步扩展，提升用户体验与商业价值。

附录

• 常用接口路径参考
  • 小程序VIP套餐列表：/?route=vip
  • 小程序会员中心记录：/?route=vip/user&page=1
• 关键状态值
  • VIP状态：active/expired/none
  • 订单状态：pending/paid/completed/cancelled