会员模块

会员模块位于 modules/Member，负责会员档案、分组、等级、标签、地址、资产账户、成长体系和后台配置。模块前端位于 web/src/views/member，后台菜单由 MemberMenusSeeder 注册，当前已经覆盖会员运营最常用的管理链路。

模块能力

能力	说明
会员档案	管理用户名、手机号、邮箱、头像、分组、等级、成长值、备注等基础资料
会员画像	通过分组、等级、标签、地址组织会员信息
资产账户	维护余额、积分和资产流水
成长体系	维护成长值、等级匹配、等级变更记录和升级奖励
运营配置	管理命名、货币展示、功能开关、入会奖励、积分规则、余额规则、成长规则和调账审计

模块的主线可以概括为：

会员档案
├─ 分组 / 等级 / 标签 / 地址
├─ 资产账户：余额、积分、资产流水
└─ 成长体系：成长值、等级变更、升级奖励

会员配置
└─ 驱动功能开关、入会奖励、积分兑换、等级匹配和审计规则

业务架构

模块里的业务关系可以这样理解：

• 会员配置 位于规则层，决定新会员默认归属、功能开关、积分兑换、成长匹配和调账审计
• 会员档案 是业务中心，承接基础资料，并把会员延展到画像、资产和成长三条线
• 会员画像 负责运营识别，分组表达粗粒度归类，标签表达灵活特征，地址承接履约信息
• 资产体系 处理余额、积分和兑换，是会员价值流转的账户侧
• 成长体系 处理成长值、等级和升级奖励，是会员长期运营的激励侧
• 运营记录 收口资产、成长和等级变化，承担追溯与审计

代码结构

目录	职责
Http/Controllers	接收后台请求，协调模型和服务
Http/Requests	收敛表单校验
Models	定义表结构、查询字段、关系和列表能力
Service	承载会员生命周期、资产、成长和配置规则
Support	提供配置默认值、金额计算、审计上下文和日志列表查询
Enums	维护状态、资产类型、业务场景和功能开关

四个服务构成模块骨架：

服务	主要职责
MemberProfileService	初始化新会员、同步标签、设置默认地址
MemberAssetService	初始化账户、调账、积分兑换余额、写入资产流水
MemberGrowthService	调整成长值、匹配等级、写入成长和等级日志、发放升级奖励
MemberConfigService	读取、保存、预览会员配置，并提供金额和积分计算能力

核心流程

新会员初始化

后台创建会员后，MembersController::store() 会调用 MemberProfileService::initializeLifecycle()：

1. 按配置写入默认分组和默认等级
2. 创建会员资产账户
3. 读取入会奖励配置
4. 按需发放积分奖励和成长值奖励
5. 通过同一个业务单号把奖励流水串起来

这一流程由事务包裹，资产初始化、奖励发放和成长值变化会保持一致。

资产调整

后台调账入口是 POST member/members/{id}/asset/adjust。MemberAssetService 负责：

1. 校验资产类型与金额
2. 根据配置把余额输入转换成最小货币单位
3. 检查功能开关、调账开关、单次上限和负余额规则
4. 锁定账户并更新余额或积分
5. 写入 member_asset_logs

余额字段使用整数保存，默认按“分”存储；展示格式由会员配置中的货币规则控制。

积分兑换余额

后台兑换入口是 POST member/members/{id}/points/redeem。系统会：

1. 校验积分兑换、积分、余额三个功能开关
2. 校验最低兑换积分和单次最高兑换金额
3. 按兑换比例把积分换算成余额
4. 在同一事务中扣减积分、增加余额
5. 生成两条共享同一业务单号的资产流水

成长值与等级

后台成长值入口是 POST member/members/{id}/growth/adjust。MemberGrowthService 会：

1. 调整成长值并写入成长流水
2. 按启用等级和成长值门槛匹配目标等级
3. 根据配置决定是否允许自动匹配与降级
4. 发生等级变化时写入 member_level_logs
5. 满足条件时发放升级奖励积分

等级升级奖励支持 once_per_level 和 always 两种策略。once_per_level 会根据等级日志判断会员是否已经进入过该等级。

数据结构

表	作用
members	会员主表
member_groups	会员分组
member_levels	会员等级、成长门槛和升级奖励配置
member_tags	标签字典
member_has_tags	会员与标签的多对多关系
member_addresses	收货地址
member_assets	会员资产账户，一人一户
member_asset_logs	余额和积分流水
member_growth_logs	成长值流水
member_level_logs	等级变更记录

几个字段约定值得先记住：

• 状态类字段统一使用 1 = 启用、2 = 禁用
• member_assets.balance 以最小货币单位保存
• member_asset_logs.asset_type 使用 balance、points
• 审计字段统一包含 scene、source_no、reason、remark
• 业务场景当前包含 admin_adjust、join_reward、points_redeem_balance、level_upgrade_reward

接口入口

会员模块路由集中在 modules/Member/routes/route.php。模块外层已经有 member 前缀，因此资源路由中还能看到一层 member/* 路径。

分组	接口	说明
会员	member/members	会员 CRUD
会员	member/members/{id}/detail	会员详情聚合视图
会员	member/members/tags/{id}	单会员打标
会员	member/members/tags/batch	批量打标
会员	member/members/{id}/asset/adjust	余额或积分调账
会员	member/members/{id}/growth/adjust	成长值调整
会员	member/members/{id}/points/redeem	积分兑换余额
基础资料	member/member/groups	分组 CRUD
基础资料	member/member/levels	等级 CRUD
基础资料	member/member/tags	标签 CRUD
基础资料	member/member/addresses	地址 CRUD
基础资料	member/member/addresses/{id}/default	设置默认地址
日志	member/member/asset/logs	资产流水列表
日志	member/member/growth/logs	成长值流水列表
日志	member/member/level/logs	等级变更记录
配置	member/member/config	查询和保存配置
配置	member/member/config/preview	预览积分和成长计算结果

控制器遵循“薄控制器”结构：参数校验放在 Http/Requests，业务规则进入服务层，列表查询复用模型和 MemberLogListQuery。

会员配置

配置通过 MemberConfigService 读写，最终写入系统配置表中的 member.* 键。配置共分八组：

分组	内容
brand	会员、分组、等级、余额、积分、成长值的显示名称
currency	币种、符号位置、小数位、千分位、输入单位
features	余额、积分、成长值、等级、标签、地址、积分兑换开关
lifecycle	默认分组、默认等级、入会奖励
points	积分获取、兑换比例、取整方式、兑换限制
balance	调账开关、单次上限、负余额规则
growth	成长获取、自动匹配、降级、升级奖励
adjustment	调账原因必填和各类原因选项

配置页还会输出兼容字段 assets 和 level，用于兼容旧调用方。新代码优先使用上表中的正式分组。

前端页面

菜单	页面
会员列表	web/src/views/member/members/index.vue
会员分组	web/src/views/member/memberGroups/index.vue
会员等级	web/src/views/member/memberLevels/index.vue
会员标签	web/src/views/member/memberTags/index.vue
会员地址	web/src/views/member/memberAddresses/index.vue
资产流水	web/src/views/member/memberAssetLogs/index.vue
成长值流水	web/src/views/member/memberGrowthLogs/index.vue
等级变更记录	web/src/views/member/memberLevelLogs/index.vue
会员配置	web/src/views/member/memberConfig/index.vue

useMemberConfig() 会把后台配置同步到页面层，直接影响字段名称、功能显隐、金额格式化和日志展示。

二次开发建议

新增会员变动场景

新增场景时，先扩展 MemberScene，再从服务层调用资产或成长能力，并复用 MemberChangeContext 生成审计字段和业务单号。这样可以让新业务自然进入现有流水体系。

$assetService->adjust(
    memberId: $memberId,
    assetType: MemberAssetType::Points->value,
    amount: $points,
    remark: '订单完成奖励',
    creatorId: 0,
    scene: MemberScene::YourScene->value,
    sourceNo: $orderNo,
    reason: '订单奖励'
);

接入消费返积分或返成长值

交易完成后，优先调用：

• MemberConfigService::calculateEarnPoints()
• MemberConfigService::calculateEarnGrowthValue()
• MemberAssetService::adjust()
• MemberGrowthService::adjust()

这样可以复用当前配置中的积分比例、成长比例、等级匹配和日志写入规则。

调整新会员默认策略

默认分组、默认等级、入会积分和入会成长值都从 lifecycle 配置读取。后台配置页和 MemberProfileService::initializeLifecycle() 是这条链路的两个入口。

扩展后台调账审计

审计原因配置在 adjustment 分组中。服务层通过 MemberChangeContext::guardReasonRequired() 统一判断必填规则，资产和成长调整都会复用这套约束。