数据库设计.md 15 KB
URS推广模块数据库设计 (三代推广版本)
1. 数据库表概览
URS推广模块包含以下核心数据表：
- urs_promotion_user_mappings - URS用户映射关系表（核心基础表）
- urs_promotion_user_referrals - URS用户推荐关系表
- urs_promotion_user_relation_cache - URS用户关系缓存表（性能优化）
- urs_promotion_user_talents - URS达人等级表
- urs_promotion_profits - URS团队收益记录表
- urs_promotion_talent_configs - URS达人等级配置表
1.1 版本更新说明
v3.0.0 (分离映射关系版本) 主要变更：
- 完全移除推荐码功能，简化系统架构
- 实现分离映射关系设计：独立的用户映射表 + 纯URS推荐关系表
- 推荐关系只存储URS用户ID，通过映射表关联农场用户
- 支持三代推广关系（直推、间推、三推）
- 新增两种收益类型：推广收益（按人头奖励）和种植收益（按比例分成）
- 推广收益使用奖励组配置固定金额，种植收益使用比例配置
- 优化数据库表结构，提升查询性能
v3.1.0 (关系缓存优化版本) 主要变更：
- 新增URS用户关系缓存表，实现多级关系预计算
- 优化收益分发逻辑，优先从缓存表查询推荐关系链
- 提供缓存重建和完整性检查功能
- 支持自动缓存生成和维护机制
2. 表结构详细设计
2.1 URS用户映射关系表 (urs_promotion_user_mappings)
URS用户映射关系表是整个URS推广系统的核心基础表，负责建立URS系统用户与农场系统用户之间的映射关系。该表实现了分离映射关系设计，使得URS推广关系可以独立于农场用户系统存在。
| 字段名 | 类型 | 长度 | 默认值 | 说明 |
|---|---|---|---|---|
| id | bigint unsigned | - | AUTO_INCREMENT | 主键ID |
| urs_user_id | bigint unsigned | - | - | URS用户ID（核心标识） |
| user_id | bigint unsigned | - | - | 农场用户ID（对应users表） |
| mapping_time | timestamp | - | CURRENT_TIMESTAMP | 映射建立时间（用户进入农场时间） |
| status | tinyint | - | 1 | 状态:1有效,0无效 |
| created_at | timestamp | - | CURRENT_TIMESTAMP | 创建时间 |
| updated_at | timestamp | - | CURRENT_TIMESTAMP | 更新时间 |
索引设计：
- PRIMARY KEY (
id) - UNIQUE KEY
uk_urs_user_id(urs_user_id) - 确保一个URS用户只能映射一个农场用户 - UNIQUE KEY
uk_user_id(user_id) - 确保一个农场用户只能映射一个URS用户 - KEY
idx_mapping_time(mapping_time) - 支持按时间查询 - KEY
idx_status(status) - 支持按状态筛选
业务规则：
- 一个URS用户只能映射一个农场用户（一对一关系）
- 一个农场用户只能映射一个URS用户（一对一关系）
- 映射关系一旦建立，不允许修改，只能禁用
- 用户进入农场时自动建立映射关系
- 支持自动创建农场用户并建立映射关系
2.2 URS用户推荐关系表 (urs_promotion_user_referrals)
存储URS用户与其直接推荐人的关系，是URS推广系统的核心基础表。
| 字段名 | 类型 | 长度 | 默认值 | 说明 |
|---|---|---|---|---|
| id | bigint unsigned | - | AUTO_INCREMENT | 主键ID |
| urs_user_id | bigint unsigned | - | - | URS用户ID（核心） |
| user_id | bigint unsigned | - | - | 农场用户ID（辅助） |
| urs_referrer_id | bigint unsigned | - | - | URS推荐人ID（核心） |
| referrer_id | bigint unsigned | - | - | 农场推荐人ID（辅助） |
| referral_code | varchar | 32 | NULL | 使用的推荐码（历史记录） |
| referral_time | timestamp | - | CURRENT_TIMESTAMP | 推荐时间 |
| status | tinyint | - | 1 | 状态:1有效,0无效 |
| created_at | timestamp | - | CURRENT_TIMESTAMP | 创建时间 |
| updated_at | timestamp | - | CURRENT_TIMESTAMP | 更新时间 |
索引设计：
- PRIMARY KEY (
id) - UNIQUE KEY
uk_urs_user_id(urs_user_id) - UNIQUE KEY
uk_user_id(user_id) - KEY
idx_urs_referrer_id(urs_referrer_id) - KEY
idx_referrer_id(referrer_id) - KEY
idx_referral_code(referral_code) - KEY
idx_referral_time(referral_time) - KEY
idx_status(status)
2.3 URS用户关系缓存表 (urs_promotion_user_relation_cache)
URS用户关系缓存表用于存储URS用户的多级推荐关系缓存，提升查询性能。该表预计算并存储用户的所有上级关系，避免在收益分发时进行递归查询。
| 字段名 | 类型 | 长度 | 默认值 | 说明 |
|---|---|---|---|---|
| id | bigint unsigned | - | AUTO_INCREMENT | 主键ID |
| user_id | bigint | - | - | 农场用户ID |
| related_user_id | bigint | - | - | 关联农场用户ID（上级） |
| urs_user_id | bigint | - | - | URS用户ID |
| urs_related_user_id | bigint | - | - | 关联URS用户ID（上级） |
| level | tinyint unsigned | - | - | 关系层级:1直接,2间接 |
| path | varchar | 255 | - | 关系路径,格式:1,2,3（农场用户ID） |
| urs_path | varchar | 255 | - | URS关系路径,格式:1,2,3（URS用户ID） |
| depth | tinyint unsigned | - | - | 层级深度,从1开始 |
| created_at | timestamp | - | CURRENT_TIMESTAMP | 创建时间 |
| updated_at | timestamp | - | CURRENT_TIMESTAMP | 更新时间 |
索引设计：
- PRIMARY KEY (
id) - UNIQUE KEY
idx_user_relation(user_id,related_user_id) - UNIQUE KEY
idx_urs_user_relation(urs_user_id,urs_related_user_id) - KEY
idx_user_id(user_id) - KEY
idx_related_user_id(related_user_id) - KEY
idx_urs_user_id(urs_user_id) - KEY
idx_urs_related_user_id(urs_related_user_id) - KEY
idx_level(level) - KEY
idx_depth(depth)
设计特点：
- 同时存储农场用户ID和URS用户ID，支持双重查询
- 使用path字段记录完整的关系路径，便于调试和分析
- 通过depth字段限制查询深度，提升性能
- 支持直接关系和间接关系的区分
2.4 URS达人等级表 (urs_promotion_user_talents)
存储URS用户的达人等级信息和团队统计数据。
| 字段名 | 类型 | 长度 | 默认值 | 说明 |
|---|---|---|---|---|
| id | bigint unsigned | - | AUTO_INCREMENT | 主键ID |
| urs_user_id | bigint unsigned | - | - | URS用户ID（核心） |
| user_id | bigint unsigned | - | - | 农场用户ID（辅助） |
| talent_level | tinyint | - | 0 | URS达人等级:0无,1初级,2中级,3高级,4资深,5顶级 |
| direct_count | int | - | 0 | 直推人数 |
| indirect_count | int | - | 0 | 间推人数 |
| third_count | int | - | 0 | 三推人数 |
| promotion_count | int | - | 0 | 团队总人数 |
| last_level_update_time | timestamp | - | NULL | 最后等级更新时间 |
| created_at | timestamp | - | CURRENT_TIMESTAMP | 创建时间 |
| updated_at | timestamp | - | CURRENT_TIMESTAMP | 更新时间 |
索引设计：
- PRIMARY KEY (
id) - UNIQUE KEY
uk_urs_user_id(urs_user_id) - UNIQUE KEY
uk_user_id(user_id) - KEY
idx_talent_level(talent_level) - KEY
idx_direct_count(direct_count) - KEY
idx_promotion_count(promotion_count)
2.4 URS团队收益记录表 (urs_promotion_profits)
记录URS团队收益分成的详细信息。
| 字段名 | 类型 | 长度 | 默认值 | 说明 |
|---|---|---|---|---|
| id | bigint unsigned | - | AUTO_INCREMENT | 主键ID |
| urs_user_id | bigint unsigned | - | - | 获得收益的URS用户ID（核心） |
| urs_promotion_member_id | bigint unsigned | - | - | 产生收益的URS用户ID（核心） |
| promotion_member_farm_user_id | bigint unsigned | - | NULL | 产生收益的农场用户ID |
| source_id | bigint unsigned | - | - | 收益来源ID |
| source_type | varchar | 32 | - | 收益来源类型 |
| profit_type | varchar | 32 | - | 收益类型:promotion_reward推广收益,planting_reward种植收益 |
| relation_level | tinyint | - | 1 | 推荐层级:1直推,2间推,3三推 |
| original_amount | decimal | 30,10 | 0.0000000000 |
原始收益金额（种植收益时使用） |
| profit_amount | decimal | 30,10 | 0.0000000000 |
获得收益金额 |
| profit_rate | decimal | 8,6 | 0.000000 | 分成比例（种植收益时使用） |
| reward_group_id | int | - | NULL | 奖励组ID（推广收益时使用） |
| talent_level | tinyint | - | 0 | 获得收益时的达人等级 |
| farm_user_id | bigint unsigned | - | NULL | 获得收益的农场用户ID（冗余字段，便于查询） |
| status | tinyint | - | 1 | 状态:1正常,0取消 |
| created_at | timestamp | - | CURRENT_TIMESTAMP | 创建时间 |
| updated_at | timestamp | - | CURRENT_TIMESTAMP | 更新时间 |
索引设计：
- PRIMARY KEY (
id) - KEY
idx_urs_user_id(urs_user_id) - KEY
idx_urs_promotion_member_id(urs_promotion_member_id) - KEY
idx_promotion_member_farm_user_id(promotion_member_farm_user_id) - KEY
idx_farm_user_id(farm_user_id) - KEY
idx_source(source_type,source_id) - KEY
idx_profit_type(profit_type) - KEY
idx_relation_level(relation_level) - KEY
idx_created_at(created_at) - KEY
idx_status(status)
2.5 URS达人等级配置表 (urs_promotion_talent_configs)
配置URS达人等级的要求和权益。
| 字段名 | 类型 | 长度 | 默认值 | 说明 |
|---|---|---|---|---|
| id | bigint unsigned | - | AUTO_INCREMENT | 主键ID |
| level | tinyint | - | - | 等级:0无,1初级,2中级,3高级,4资深,5顶级 |
| name | varchar | 32 | - | 等级名称 |
| direct_count_required | int | - | 0 | 所需直推人数 |
| promotion_count_required | int | - | 0 | 所需团队总人数 |
| promotion_direct_group | int | - | 0 | 直推奖励组ID |
| promotion_indirect_group | int | - | 0 | 间推奖励组ID |
| promotion_third_group | int | - | 0 | 三推奖励组ID |
| planting_direct_rate | decimal | 5,4 | 0.0000 | 直推分成比例 |
| planting_indirect_rate | decimal | 5,4 | 0.0000 | 间推分成比例 |
| planting_third_rate | decimal | 5,4 | 0.0000 | 三推分成比例 |
| icon | varchar | 255 | NULL | 等级图标 |
| description | text | - | NULL | 等级描述 |
| sort_order | int | - | 0 | 排序权重 |
| status | tinyint | - | 1 | 状态:1启用,0禁用 |
| created_at | timestamp | - | CURRENT_TIMESTAMP | 创建时间 |
| updated_at | timestamp | - | CURRENT_TIMESTAMP | 更新时间 |
索引设计：
- PRIMARY KEY (
id) - UNIQUE KEY
uk_level(level) - KEY
idx_sort_order(sort_order) - KEY
idx_status(status)
收益配置说明：
- 推广收益奖励组配置：
promotion_direct_group: 直推奖励组ID，0表示无奖励promotion_indirect_group: 间推奖励组ID，0表示无奖励promotion_third_group: 三推奖励组ID，0表示无奖励
- 种植收益分成比例配置：
planting_direct_rate: 直推分成比例，小数形式，如0.05表示5%planting_indirect_rate: 间推分成比例，小数形式，如0.03表示3%planting_third_rate: 三推分成比例，小数形式，如0.01表示1%
3. 索引设计说明
3.1 主要查询场景
- 用户映射查询：根据URS用户ID查询对应的农场用户ID，或反向查询
- 推荐关系查询：根据URS用户ID或农场用户ID查询推荐人和被推荐人
- 达人等级查询：根据URS用户ID或农场用户ID查询达人等级和团队统计
- 收益记录查询：根据URS用户ID或农场用户ID、时间范围查询收益记录
- 批量映射查询：批量获取多个URS用户ID对应的农场用户ID
3.2 索引优化策略
- 唯一索引：确保数据唯一性，如用户推荐关系、推荐码等
- 复合索引：支持多条件查询，如收益来源类型+ID
- 时间索引：支持时间范围查询和统计分析
- 状态索引：支持按状态筛选有效数据
4. 数据完整性约束
4.1 外键约束
- 所有urs_user_id字段关联URS系统用户表
- 所有user_id字段关联农场系统users表
- urs_referrer_id和referrer_id分别关联对应系统的用户表
- 确保推荐关系的用户在两个系统中都存在
- 用户映射表的user_id必须在users表中存在
4.2 业务约束
- 用户映射关系必须是一对一的（一个URS用户只能映射一个农场用户）
- 用户不能推荐自己
- 推荐关系不能形成循环
- 达人等级必须符合配置要求
- 收益分成比例必须在合理范围内
- 映射关系一旦建立不允许修改，只能禁用
5. 数据初始化
5.1 URS达人等级配置初始化
INSERT INTO `kku_urs_promotion_talent_configs` (
`level`,
`name`,
`direct_count_required`,
`promotion_count_required`,
`promotion_reward_rates`,
`planting_reward_rates`,
`description`,
`sort_order`,
`status`
) VALUES
-- 0级：非达人
(0, '非达人', 0, 0,
'{"1": 0, "2": 0, "3": 0}',
'{"1": 0, "2": 0, "3": 0}',
'普通用户，无达人等级，无推广收益', 0, 1),
-- 1级：初级达人
(1, 'URS初级达人', 3, 5,
'{"1": 0.05, "2": 0.02, "3": 0.01}',
'{"1": 0.03, "2": 0.01, "3": 0.005}',
'初级达人，享有基础推广收益', 1, 1),
-- 2级：中级达人
(2, 'URS中级达人', 8, 15,
'{"1": 0.08, "2": 0.04, "3": 0.02}',
'{"1": 0.05, "2": 0.02, "3": 0.01}',
'中级达人，享有更高推广收益', 2, 1),
-- 3级：高级达人
(3, 'URS高级达人', 15, 30,
'{"1": 0.12, "2": 0.06, "3": 0.03}',
'{"1": 0.08, "2": 0.04, "3": 0.02}',
'高级达人，享有优质推广收益', 3, 1),
-- 4级：资深达人
(4, 'URS资深达人', 30, 80,
'{"1": 0.15, "2": 0.08, "3": 0.04}',
'{"1": 0.10, "2": 0.05, "3": 0.025}',
'资深达人，享有专业推广收益', 4, 1),
-- 5级：顶级达人
(5, 'URS顶级达人', 50, 150,
'{"1": 0.20, "2": 0.10, "3": 0.05}',
'{"1": 0.15, "2": 0.08, "3": 0.04}',
'顶级达人，享有最高推广收益', 5, 1);
6. 性能优化建议
6.1 分表策略
- 收益记录表按月分表，提高查询性能
- 用户关系缓存表按用户ID范围分表
6.2 缓存策略
- URS达人等级配置使用Redis缓存
- 用户推荐关系使用缓存加速查询
- 收益分成规则使用内存缓存
6.3 归档策略
- 定期归档历史收益记录
- 备份重要的推荐关系数据
- 定期清理无效的历史推荐码记录
7. 更新日志
2025-06-16
- 扩展URS团队收益记录表：增加
promotion_member_farm_user_id字段，用于记录产生收益的农场用户ID - 更新模型和控制器：支持新字段的显示、筛选和关联查询
- 完善业务逻辑：在创建收益记录时自动填充农场用户ID，提高数据完整性
- 优化后台管理：增加新字段的列表显示和详情页面展示，完善相关链接功能
2025-06-14
- 创建URS推广模块基础结构
- 实现用户绑定关系管理
- 实现推荐关系管理
- 实现达人等级管理
- 实现收益记录管理
- 实现等级配置管理
备注: 本数据库设计专门为URS推广模块设计，与Promotion模块完全独立，使用不同的表名前缀以避免冲突。