主题
CatchShop 用户模块数据字典
数据表概览
CatchShop 商城用户模块包含 7 个核心数据表：
| 表名 | 中文名称 | 用途 |
|---|---|---|
user_balance | 用户余额表 | 存储用户余额和积分信息 |
user_balance_log | 余额变动日志表 | 记录用户余额变动历史 |
user_points_log | 积分变动日志表 | 记录用户积分变动历史 |
user_address | 用户地址表 | 存储用户收货地址信息 |
user_level | 用户等级表 | 定义用户等级规则 |
user_level_log | 等级变动日志表 | 记录用户等级变动历史 |
shop_vip_recharge_plans | VIP 充值套餐表 | 存储 VIP 充值套餐配置 |
1. user_balance - 用户余额表
表说明：存储用户的余额、积分等资金信息，所有金额以分为单位存储。
| 字段名 | 类型 | 长度 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
id | bigint unsigned | - | 是 | - | 主键 ID（自增） |
user_id | int | - | 是 | - | 用户 ID |
balance | int | - | 是 | 0 | 余额（分） |
points | int | - | 是 | 0 | 积分 |
pay_money | int | - | 是 | 0 | 用户支付金额（分） |
actual_pay_money | int | - | 是 | 0 | 实际支付金额（不含退款/分） |
created_at | timestamp | - | 否 | NULL | 创建时间 |
updated_at | timestamp | - | 否 | NULL | 更新时间 |
deleted_at | timestamp | - | 否 | NULL | 软删除时间 |
索引信息：
- PRIMARY KEY (
id) - INDEX
idx_user_id(user_id)
关联关系：
user_id→users.id(用户基础信息)
业务规则：
- 余额不能为负数
- 所有金额以分为单位存储，显示时转换为元
- 积分变动通过事件机制自动更新
2. user_balance_log - 余额变动日志表
表说明：记录用户余额的所有变动情况，包括充值、消费、退款等场景。
| 字段名 | 类型 | 长度 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
id | int unsigned | - | 是 | - | 主键 ID（自增） |
user_id | int | - | 是 | 0 | 用户 ID |
scene | tinyint | - | 是 | 10 | 余额变动场景：1=用户充值，2=用户消费，3=管理员操作，4=订单退款 |
money | int | - | 是 | 0 | 变动金额（分） |
describe | varchar | 500 | 是 | - | 描述/说明 |
remark | varchar | 500 | 是 | - | 管理员备注 |
created_at | int unsigned | - | 是 | - | 创建时间戳 |
updated_at | int unsigned | - | 是 | - | 更新时间戳 |
索引信息：
- PRIMARY KEY (
id) - INDEX
idx_user_id(user_id)
关联关系：
user_id→users.id(用户基础信息)
变动场景枚举：
1- 用户充值 (SCENE_USER_RECHARGE)2- 用户消费 (SCENE_USER_CONSUMPTION)3- 管理员操作 (SCENE_ADMIN_OPERATION)4- 订单退款 (SCENE_ORDER_REFUND)
3. user_points_log - 积分变动日志表
表说明：记录用户积分的所有变动情况，确保积分流水的完整性和可追溯性。
| 字段名 | 类型 | 长度 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
id | int unsigned | - | 是 | - | 主键 ID（自增） |
user_id | int | - | 是 | 0 | 用户 ID |
amount | int | - | 是 | 0 | 变动数量 |
description | varchar | 500 | 是 | - | 描述/说明 |
remark | varchar | 500 | 是 | - | 管理员备注 |
created_at | int unsigned | - | 是 | - | 创建时间戳 |
updated_at | int unsigned | - | 是 | - | 更新时间戳 |
索引信息：
- PRIMARY KEY (
id) - INDEX
idx_user_id(user_id)
关联关系：
user_id→users.id(用户基础信息)
4. user_address - 用户地址表
表说明：存储用户的收货地址信息，支持省市区三级联动。
| 字段名 | 类型 | 长度 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
id | int unsigned | - | 是 | - | 主键 ID（自增） |
user_id | int | - | 是 | 0 | 用户 ID |
name | varchar | 30 | 是 | - | 收货人姓名 |
mobile | varchar | 20 | 是 | - | 联系电话 |
province_id | int | - | 是 | 0 | 省份 ID |
city_id | int | - | 是 | 0 | 城市 ID |
region_id | int | - | 是 | 0 | 区/县 ID |
address_detail | varchar | 255 | 是 | - | 详细地址 |
created_at | timestamp | - | 否 | NULL | 创建时间 |
updated_at | timestamp | - | 否 | NULL | 更新时间 |
deleted_at | timestamp | - | 否 | NULL | 软删除时间 |
索引信息：
- PRIMARY KEY (
id) - INDEX
idx_user_id(user_id)
关联关系：
user_id→users.id(用户基础信息)province_id→areas.id(省份信息)city_id→areas.id(城市信息)region_id→areas.id(区县信息)
业务规则：
- 删除地址使用软删除
- 省市区必须符合三级联动关系
5. user_level - 用户等级表
表说明：用户等级配置表，定义不同等级的权益和升级条件。
| 字段名 | 类型 | 长度 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
id | int unsigned | - | 是 | - | 主键 ID（自增） |
icon | varchar | 255 | 否 | NULL | 等级 icon |
name | varchar | 255 | 是 | - | 等级名称 |
sort | int | - | 是 | 0 | 等级权重（1-9999） |
upgrade | int | - | 是 | 0 | 升级条件 |
equity | int | - | 是 | 0 | 等级权益（折扣率 0-100） |
status | int | - | 是 | 1 | 状态：1=启用，0=禁用 |
creator_id | int | - | 是 | 0 | 创建人 ID |
created_at | timestamp | - | 否 | NULL | 创建时间 |
updated_at | timestamp | - | 否 | NULL | 更新时间 |
deleted_at | timestamp | - | 否 | NULL | 软删除时间 |
索引信息：
- PRIMARY KEY (
id)
业务规则：
- 等级按 sort 字段排序，数值越大等级越高
- 升级条件可配置不同的升级要求
- 权益折扣率范围为 0-100
6. user_level_log - 用户等级变动日志表
表说明：记录用户等级变动的历史记录。
| 字段名 | 类型 | 长度 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
id | int unsigned | - | 是 | - | 主键 ID（自增） |
user_id | int | - | 是 | 0 | 用户 ID |
prev_level_id | int | - | 是 | 0 | 变更前的等级 ID |
current_level_id | int | - | 是 | 0 | 变更后的等级 ID |
type | int | - | 是 | 1 | 变更类型：1=后台管理员设置，2=自动升级 |
remark | varchar | 255 | 否 | NULL | 备注信息 |
created_at | int unsigned | - | 是 | - | 创建时间戳 |
updated_at | int unsigned | - | 是 | - | 更新时间戳 |
索引信息：
- PRIMARY KEY (
id)
关联关系：
user_id→users.id(用户基础信息)prev_level_id→user_level.id(原等级)current_level_id→user_level.id(新等级)
变更类型枚举：
1- 后台管理员设置 (TYPE_ADMIN_SET)2- 自动升级 (TYPE_AUTO_UPGRADE)
7. shop_vip_recharge_plans - VIP 充值套餐表
表说明：存储 VIP 充值套餐配置，用户可以选择不同的充值套餐获得额外赠送。
| 字段名 | 类型 | 长度 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
id | int unsigned | - | 是 | - | 主键 ID（自增） |
title | varchar | 255 | 是 | - | 套餐标题 |
price | int | - | 是 | 0 | 充值金额（分） |
handles_price | int | - | 是 | 0 | 赠送金额（分） |
sort | int | - | 是 | 0 | 排序权重 |
creator_id | int | - | 是 | 0 | 创建人 ID |
created_at | timestamp | - | 否 | NULL | 创建时间 |
updated_at | timestamp | - | 否 | NULL | 更新时间 |
deleted_at | timestamp | - | 否 | NULL | 软删除时间 |
索引信息：
- PRIMARY KEY (
id)
业务规则：
- 充值金额和赠送金额都以分为单位存储
- 套餐按 sort 字段排序显示
- 删除套餐使用软删除
业务规则说明
余额管理规则
- 金额单位：所有金额以分为单位存储，避免浮点数精度问题
- 变动记录：所有余额变动必须记录日志，确保可追溯
- 事务保护：余额变动和日志记录必须在同一事务中完成
- 负余额控制：系统禁止余额为负数
积分管理规则
- 事件驱动：积分变动通过事件机制触发，自动记录日志
- 变动类型：支持多种积分获取和消费场景
- 等级关联：积分数量可作为用户等级升级条件
- 有效期管理：可扩展积分有效期功能
地址管理规则
- 三级联动：省市区必须符合行政区划关系
- 软删除：地址删除使用软删除，保留历史数据
- 数量限制：可配置每个用户最大地址数量
等级体系规则
- 升级条件：支持按消费金额或积分数量升级
- 权益配置：每个等级可配置不同的折扣和权益
- 自动升级：系统自动检查并升级用户等级
- 降级保护：一般不支持等级降级，保护用户权益
VIP 充值套餐规则
- 套餐配置：每个套餐包含充值金额和赠送金额
- 金额处理：所有金额以分为单位存储，显示时转换为元
- 排序显示：套餐按 sort 字段排序，便于管理和展示
- 软删除保护：删除套餐使用软删除，保留历史数据
数据一致性
- 余额和积分的变动必须是原子操作
- 所有日志记录必须与主表数据保持一致
- 软删除的数据不参与业务逻辑计算
- VIP 充值套餐的金额计算必须准确无误