会员管理开发文档

1. 文档概述

1.1 文档目的

本文档旨在详细说明CRMEB系统中会员管理模块的设计架构、核心功能、代码实现及开发规范，为系统开发人员提供完整的开发参考。

1.2 适用范围

本文档适用于CRMEB系统开发人员、维护人员及二次开发人员，用于指导会员管理模块的开发、扩展和维护工作。

1.3 术语定义

术语	解释
会员等级	基于用户经验值划分的等级体系，不同等级享有不同权益
经验值	用户通过各种行为获得的数值，用于提升会员等级
会员权益	不同会员等级享有的专属福利，如折扣、优惠券等
会员卡片	展示会员等级、有效期、权益等信息的可视化卡片
积分	用户通过各种行为获得的可用于消费的数值
积分商城	用于兑换商品或服务的积分兑换平台
会员有效期	会员等级的有效期限，过期后可能降级或失效

2. 核心功能模块

2.1 会员等级管理

等级列表：展示系统配置的会员等级，支持搜索、分页
等级添加：添加新的会员等级，设置等级名称、折扣、经验值要求等
等级编辑：修改会员等级信息，包括名称、折扣、经验值要求等
等级删除：删除会员等级
等级状态管理：启用/禁用会员等级
等级排序：调整会员等级的显示顺序

2.2 用户等级管理

用户等级列表：展示用户当前等级信息，支持搜索、分页
等级赠送：手动为用户赠送会员等级
等级清除：清除用户的会员等级
等级有效期管理：设置和修改会员等级的有效期
等级自动检测：定期检测用户是否达到升级条件，自动升级

2.3 经验值管理

经验值配置：配置各种行为获得的经验值数量
经验值记录：记录用户经验值的变动情况
经验值查询：查询用户经验值的获取和使用记录
经验值统计：统计用户经验值的来源分布

2.4 积分管理

积分配置：配置各种行为获得的积分数量
积分增加：手动为用户增加积分
积分扣除：手动为用户扣除积分
积分记录：记录用户积分的变动情况
积分查询：查询用户积分的获取和使用记录
积分统计：统计用户积分的来源和使用分布

2.5 会员权益管理

折扣权益：配置不同等级的商品折扣比例
等级图标：配置各等级的专属图标和背景图
会员卡片：生成和管理会员卡片
权益规则：配置会员享有的其他权益，如专属客服、优先发货等

2.6 会员等级升级机制

经验值累积：通过签到、下单、邀请等行为累积经验值
升级条件检测：定期检测用户是否达到升级条件
自动升级：达到升级条件后自动更新会员等级
升级通知：发送等级升级通知给用户

3. 代码结构与设计

3.1 架构设计

系统采用分层架构设计，严格遵循MVC设计模式：

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Models       │     │     Daos        │     │    Services     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                         ┌─────────────────┐
                         │ Controllers     │
                         └─────────────────┘
                                 │
                         ┌─────────────────┐
                         │     Routes      │
                         └─────────────────┘

3.2 核心文件结构

3.2.1 模型层（Model）

会员相关模型：

UserLevel.php - 用户实际会员等级信息模型
SystemUserLevel.php - 系统会员等级配置模型
User.php - 用户基本信息模型，包含经验值、积分等字段

3.2.2 服务层（Services）

会员管理Services：

UserLevelServices.php - 会员等级设置与管理，自动检测用户升级条件
UserBillServices.php - 积分增加与扣除，积分记录管理
UserServices.php - 用户基本信息管理，包括等级、经验值、积分等

3.2.3 控制器层（Controller）

会员控制器：

UserLevel.php - 会员等级管理控制器
User.php - 用户管理控制器，包含等级、经验值、积分等管理功能

3.2.4 路由配置

会员路由：

user.php - 包含会员管理相关的API路由

4. 数据库设计

4.1 系统会员等级表（system_user_level）

字段名	数据类型	描述
id	int(10) unsigned	等级ID
name	varchar(20)	等级名称
icon	varchar(255)	等级图标
bg	varchar(255)	等级背景图
grade	int(10)	等级
experience_min	int(10)	最低经验值
experience_max	int(10)	最高经验值
discount	decimal(10,2)	折扣比例
status	tinyint(1)	状态（0-禁用，1-启用）
is_show	tinyint(1)	是否显示（0-隐藏，1-显示）
sort	int(10)	排序
add_time	int(10)	添加时间

4.2 用户等级表（user_level）

字段名	数据类型	描述
id	int(10) unsigned	记录ID
uid	int(10)	用户ID
level_id	int(10)	会员等级ID
is_forever	tinyint(1)	是否永久（0-否，1-是）
start_time	int(10)	开始时间
end_time	int(10)	结束时间
status	tinyint(1)	状态（0-过期，1-有效）
add_time	int(10)	添加时间

4.3 用户表（user）

字段名	数据类型	描述
uid	int(10) unsigned	用户ID
user_level	int(10)	当前会员等级ID
experience	int(10)	经验值
integral	int(10)	积分
sign_num	int(10)	连续签到天数
sign_integral	int(10)	已领取签到积分
// 其他用户信息字段	// 数据类型	// 描述

4.4 用户账单表（user_bill）

字段名	数据类型	描述
id	int(10) unsigned	账单ID
uid	int(10)	用户ID
category	varchar(20)	资金类型（integral-积分，experience-经验值）
type	varchar(20)	变动类型（sign-签到，order-订单，invite-邀请）
pm	tinyint(1)	收支方向（1-收入，0-支出）
number	varchar(50)	流水号
money	decimal(10,2)	变动金额
balance	decimal(10,2)	变动后余额/积分/经验值
mark	varchar(255)	备注
add_time	int(10)	添加时间

5. API接口说明

5.1 会员等级管理

5.1.1 获取系统会员等级列表

请求URL：/adminapi/v1/user/level/list
请求方法：GET
权限要求：user/user_level/list
返回结果：系统会员等级列表数据

5.1.2 添加系统会员等级

请求URL：/adminapi/v1/user/level/create
请求方法：POST
权限要求：user/user_level/create
请求参数：
- name：等级名称
- grade：等级
- experience_min：最低经验值
- experience_max：最高经验值
- discount：折扣比例
- icon：等级图标
- bg：等级背景图
返回结果：操作结果

5.1.3 获取用户等级列表

请求URL：/adminapi/v1/user/user_level/list
请求方法：GET
权限要求：user/user/user_level_list
请求参数：
- page：页码
- limit：每页数量
- keyword：搜索关键词
返回结果：用户等级列表数据

5.1.4 为用户赠送会员等级

请求URL：/adminapi/v1/user/user_level/give/{uid}
请求方法：POST
权限要求：user/user/user_level_give
请求参数：
- level_id：会员等级ID
- is_forever：是否永久（0-否，1-是）
- days：有效期（天）
返回结果：操作结果

5.2 积分管理

5.2.1 获取积分记录列表

请求URL：/adminapi/v1/user/integral/list
请求方法：GET
权限要求：user/integral/list
请求参数：
- page：页码
- limit：每页数量
- uid：用户ID
- type：变动类型
返回结果：积分记录列表数据

5.2.2 为用户增加积分

请求URL：/adminapi/v1/user/integral/add/{uid}
请求方法：POST
权限要求：user/integral/add
请求参数：
- integral：积分数量
- mark：备注
返回结果：操作结果

5.2.3 为用户扣除积分

请求URL：/adminapi/v1/user/integral/sub/{uid}
请求方法：POST
权限要求：user/integral/sub
请求参数：
- integral：积分数量
- mark：备注
返回结果：操作结果

5.3 用户端接口

5.3.1 获取会员等级列表

请求URL：/api/v1/user/level/list
请求方法：GET
权限要求：登录用户
返回结果：会员等级列表数据

5.3.2 获取用户等级信息

请求URL：/api/v1/user/level/info
请求方法：GET
权限要求：登录用户
返回结果：当前用户的等级信息

5.3.3 获取积分记录

请求URL：/api/v1/user/integral/list
请求方法：GET
权限要求：登录用户
请求参数：
- page：页码
- limit：每页数量
返回结果：当前用户的积分记录

5. 开发规范与流程

5.1 代码规范

命名规范：
- 类名采用大驼峰命名法，如 UserLevelServices
- 方法名采用小驼峰命名法，如 checkUpgradeCondition
- 变量名采用小驼峰命名法，如 userExperience
- 常量名采用全大写，下划线分隔，如 LEVEL_STATUS_ENABLE
代码结构：
- 严格遵循分层架构，禁止跨层调用
- 每个方法职责单一，代码行数控制在50行以内
- 适当添加注释，说明方法功能、参数含义和返回值
- 经验值和积分变动必须记录变动原因和相关业务ID
数据一致性：
- 所有经验值和积分变动都必须通过事务确保数据一致性
- 会员等级变动必须同步更新相关表的数据
- 必须记录完整的变动日志，便于追溯

5.2 开发流程

需求分析：明确会员管理的功能需求和业务逻辑
设计阶段：设计数据结构、API接口和业务流程
编码实现：按照分层架构编写代码
单元测试：编写单元测试，确保功能正确性
集成测试：进行模块集成测试，测试会员与其他模块的交互
性能测试：对经验值和积分变动等高频操作进行性能测试
代码审查：提交代码审查，确保代码质量
部署上线：部署到生产环境

6. 常见问题与解决方案

6.1 会员等级升级不及时

问题：用户达到升级条件后，等级没有自动升级 解决方案：

检查自动检测任务是否正常运行
检查升级条件配置是否正确
检查升级逻辑是否存在bug
考虑添加手动触发升级的功能

6.2 积分计算不准确

问题：用户积分的计算与预期不符 解决方案：

检查积分配置是否正确
检查积分变动记录，找出问题所在
确保所有积分变动都通过统一的接口处理
添加积分对账功能，定期检查积分一致性

6.3 会员权益不生效

问题：用户享有某等级权益，但实际未生效 解决方案：

检查会员等级是否正确
检查权益配置是否正确
检查权益生效逻辑是否存在bug
添加权益生效日志，便于排查问题

6.4 大量用户同时升级导致性能问题

问题：系统中有大量用户同时达到升级条件，导致系统性能下降 解决方案：

优化升级检测算法，减少数据库查询
使用异步处理方式，避免阻塞主流程
考虑分级处理，先处理活跃用户
增加系统资源，提高并发处理能力

7. 扩展与定制

7.1 添加新的经验值获取渠道

配置经验值：在系统配置中添加新的经验值获取渠道和数量
修改代码：
- 在相关业务逻辑中添加经验值增加的调用
- 在UserBillServices中添加对应的经验值记录类型
前端修改：在前端添加对应的经验值获取入口和说明

7.2 添加新的积分使用方式

配置积分：在系统配置中添加新的积分使用方式和消耗规则
修改代码：
- 在相关业务逻辑中添加积分扣除的调用
- 在UserBillServices中添加对应的积分记录类型
前端修改：在前端添加对应的积分使用入口和说明

7.3 扩展会员权益

数据库修改：在system_user_level表中添加新的权益字段
代码修改：
- 修改会员等级配置和管理功能
- 在相关业务逻辑中添加权益判断和生效代码
前端修改：在前端添加对应的权益展示和使用入口

8. 文档更新记录

版本	更新日期	更新内容	更新人
1.0	2026-01-19	初始版本，包含会员等级管理、用户等级管理、经验值管理、积分管理、会员权益管理、会员等级升级机制等核心功能	AI Assistant

9. 附录

9.1 核心类关系图

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Models       │     │     Daos        │     │    Services     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                         ┌─────────────────┐
                         │ Controllers     │
                         └─────────────────┘
                                 │
                         ┌─────────────────┐
                         │     Routes      │
                         └─────────────────┘

9.2 会员等级升级流程图

会员等级升级流程：
1. 用户执行获取经验值的行为（签到、下单、邀请等）
2. 系统增加用户经验值，记录经验值变动
3. 检查用户当前经验值是否达到下一级别要求
4. 达到要求，更新用户等级
5. 记录等级变动日志
6. 发送等级升级通知给用户
7. 更新用户享有的权益

9.3 积分获取与使用流程图

积分获取与使用流程：
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   积分获取       │     │   积分管理       │     │   积分使用       │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   签到获得积分   │     │   积分增加       │     │   抵扣商品金额   │
│   下单获得积分   │     │   积分扣除       │     │   积分商城兑换   │
│   邀请获得积分   │     │   积分记录       │     │   参与活动消耗   │
│   活动获得积分   │     │   积分统计       │     └─────────────────┘
└─────────────────┘     └─────────────────┘

9.4 会员权益列表

权益名称	描述
折扣优惠	不同等级享受不同的商品折扣
等级图标	每个等级拥有专属图标和背景图
经验值加速	高级会员获得经验值的速度更快
专属客服	高级会员享受专属客服服务
优先发货	高级会员订单优先发货
生日福利	会员生日获得专属福利
专属活动	高级会员参与专属活动
积分翻倍	高级会员获得积分的倍数更高

提示：该文档由AI生成，仅供参考。

会员管理开发文档.md 17 KB History Raw