9.5 KiB
9.5 KiB
表结构修改说明
本文档说明系统重构需要的所有表结构修改，包括：
- UUID迁移（将所有bigint类型的ID改为CHAR(36)类型的UUID）
- 用户系统重构（删除UserTemp表，优化UserAuth表）
一、UUID迁移
1.1 概述
将所有表的主键ID从bigint类型改为CHAR(36)类型的UUID，同时将所有外键关联字段也改为UUID类型。
注意：开发环境使用简化版脚本（uuid_migration_simple.sql），直接修改表结构，不保留旧数据。
1.2 涉及的表
核心业务表：
user- 用户表agent- 代理表product- 产品表order- 订单表query- 查询报告表user_auth- 用户认证表
代理相关表：
agent_commission- 代理佣金表agent_invite_code- 代理邀请码表agent_link- 代理链接表agent_order- 代理订单表agent_wallet- 代理钱包表agent_withdrawal- 代理提现表agent_withdrawal_tax- 代理提现税费表agent_rebate- 代理返利表agent_relation- 代理关系表agent_upgrade- 代理升级表agent_real_name- 代理实名表agent_config- 代理配置表agent_product_config- 代理产品配置表agent_short_link- 代理短链表agent_invite_code_usage- 邀请码使用记录表agent_freeze_task- 代理冻结任务表
订单相关表：
order_refund- 订单退款表
查询相关表：
query_cleanup_log- 查询清理日志表query_cleanup_detail- 查询清理详情表query_cleanup_config- 查询清理配置表
产品相关表：
product_feature- 产品功能表feature- 功能表
其他表：
authorization_document- 授权书表global_notifications- 全局通知表
管理后台表：
admin_user- 管理员用户表admin_role- 管理员角色表admin_menu- 管理员菜单表admin_api- 管理员API表admin_dict_type- 字典类型表admin_dict_data- 字典数据表admin_user_role- 管理员用户角色关联表admin_role_menu- 管理员角色菜单关联表admin_role_api- 管理员角色API关联表
1.3 修改内容
主键字段：
- 所有表的
id字段：bigint→CHAR(36) - 移除
AUTO_INCREMENT属性 - 插入时使用
UUID()函数或应用层生成UUID
外键字段（软关联）：
user_id：bigint→CHAR(36)agent_id：bigint→CHAR(36)order_id：bigint→CHAR(36)product_id：bigint→CHAR(36)invite_code_id：bigint→CHAR(36)link_id：bigint→CHAR(36)commission_id：bigint→CHAR(36)wallet_id：bigint→CHAR(36)withdrawal_id：bigint→CHAR(36)parent_agent_id：bigint→CHAR(36)team_leader_id：bigint→CHAR(36)cleanup_log_id：bigint→CHAR(36)query_id：bigint→CHAR(36)feature_id：bigint→CHAR(36)parent_id（菜单）：bigint→CHAR(36)dict_type_id：bigint→CHAR(36)role_id：bigint→CHAR(36)menu_id：bigint→CHAR(36)api_id：bigint→CHAR(36)used_user_id：bigint→CHAR(36)used_agent_id：bigint→CHAR(36)
1.4 执行脚本
开发环境：执行文件 uuid_migration_simple.sql
- 直接修改表结构，不保留旧数据
- 适用于开发环境，没有重要数据
生产环境：执行文件 uuid_migration.sql
- 完整的迁移流程，保留旧数据以便回滚
- 需要分阶段执行，包含数据迁移和验证
开发环境执行步骤：
- 直接执行
uuid_migration_simple.sql - 所有表的主键和外键字段直接改为CHAR(36)
- 插入新记录时，在应用层生成UUID
注意事项：
- 开发环境脚本直接修改表结构，不保留旧数据
- 如果表中有数据，需要先清空数据或手动填充UUID
- 代码层面需要同步修改所有ID字段类型（int64 → string）
二、用户系统重构
2.1 概述
删除UserTemp表，统一使用User表（通过mobile字段是否为空区分临时用户和正式用户），优化UserAuth表结构。
2.2 涉及的表
需要修改的表：
user- 用户表（无需修改结构，只需确保mobile可为空）user_auth- 用户认证表（添加唯一索引）user_temp- 临时用户表（删除）
需要迁移数据的表：
order- 订单表（更新user_id）query- 查询报告表（更新user_id）
2.3 修改内容
2.3.1 UserAuth表
添加唯一索引：
ALTER TABLE `user_auth`
ADD UNIQUE INDEX `uk_auth_type_key` (`auth_type`, `auth_key`);
作用：
- 确保同一个认证方式（auth_type + auth_key）只能绑定一个用户
- 防止重复绑定
2.3.2 UserTemp表
删除原因：
- 临时用户可以直接创建User表记录（mobile为空）
- 临时用户的认证信息存储在UserAuth表
- 通过User.mobile是否为空来区分临时用户和正式用户
- 统一使用User表，逻辑更清晰
删除步骤：
- 迁移UserTemp数据到User和UserAuth表
- 更新关联的订单和报告的user_id
- 验证数据完整性
- 删除UserTemp表
2.4 执行脚本
开发环境：执行文件 user_system_refactor.sql（已简化）
- 直接删除UserTemp表
- 添加UserAuth唯一索引
生产环境：如需数据迁移，请参考完整版脚本
开发环境执行步骤：
- 添加UserAuth唯一索引
- 直接删除UserTemp表
注意事项：
- 开发环境脚本直接删除UserTemp表，不进行数据迁移
- 删除UserTemp表前，确保代码中已移除所有对UserTemp表的引用
三、执行顺序
3.1 推荐执行顺序
开发环境：
-
先执行用户系统重构（
user_system_refactor.sql）- 添加UserAuth唯一索引
- 删除UserTemp表
-
再执行UUID迁移（
uuid_migration_simple.sql）- 直接修改所有表结构
- 需要同步修改代码
生产环境：
- 先执行用户系统重构（完整版，包含数据迁移）
- 再执行UUID迁移（完整版，包含数据迁移和验证）
3.2 如果先执行UUID迁移
如果先执行UUID迁移，需要注意：
- UserTemp表的ID也会改为UUID
- 迁移UserTemp数据时，需要使用UUID映射
- 用户系统重构脚本需要相应调整
四、代码修改清单
4.1 UUID迁移需要的代码修改
Model层：
- 所有Model的ID字段类型：
int64→string - 所有外键字段类型：
int64→string - 移除
AUTO_INCREMENT相关逻辑 - 插入时生成UUID（使用
uuid.NewString()）
Service层：
- 所有使用ID的地方改为UUID
- 查询条件改为UUID
- 关联查询改为UUID
API层：
- 请求参数中的ID改为UUID
- 响应数据中的ID改为UUID
数据库操作：
- 插入操作：使用
uuid.NewString()生成UUID - 查询操作：使用UUID字符串查询
- 更新操作：使用UUID字符串更新
4.2 用户系统重构需要的代码修改
删除UserTemp相关代码：
- 删除
UserTempModel - 删除所有使用
UserTemp的代码 - 删除临时用户创建逻辑中的UserTemp相关代码
修改用户创建逻辑：
- 临时用户：直接创建User记录（mobile为空）
- 创建UserAuth记录（auth_type + auth_key）
修改用户查询逻辑：
- 通过UserAuth表查询用户
- 通过User.mobile是否为空判断用户类型
修改账号合并逻辑：
- 绑定手机号时，检查手机号是否已存在
- 如果存在，合并账号（迁移数据）
- 如果不存在，更新User.mobile
五、验证清单
5.1 UUID迁移验证
- 所有表的主键已改为CHAR(36)
- 所有外键字段已改为CHAR(36)
- 插入新记录时自动生成UUID
- 查询操作使用UUID正常
- 关联查询使用UUID正常
- 索引和约束已更新
- 数据完整性验证通过
5.2 用户系统重构验证
- UserAuth表有唯一索引
uk_auth_type_key - UserTemp表数据已迁移（如果存在）
- 订单和报告的user_id已更新
- UserTemp表已删除（如果存在）
- 临时用户创建逻辑使用User表
- 账号合并逻辑正常工作
- 数据完整性验证通过
六、回滚方案
6.1 UUID迁移回滚
如果UUID迁移出现问题，可以：
- 保留原ID字段（迁移脚本中已保留）
- 恢复主键为原ID字段
- 删除UUID字段
- 恢复代码使用int64类型
6.2 用户系统重构回滚
如果用户系统重构出现问题，可以：
- 恢复UserTemp表（从备份）
- 恢复订单和报告的user_id
- 恢复代码使用UserTemp表
七、常见问题
7.1 UUID性能问题
问题：UUID作为主键可能影响性能
解答：
- UUID是字符串类型，索引效率略低于bigint
- 但UUID的优势是全局唯一，适合分布式系统
- 如果性能问题严重，可以考虑使用BINARY(16)存储UUID（需要转换）
7.2 UUID长度问题
问题：CHAR(36)占用空间较大
解答：
- UUID标准格式是36字符（包含连字符）
- 如果空间敏感，可以使用BINARY(16)存储（需要转换函数）
- 当前使用CHAR(36)便于调试和查看
7.3 UserTemp数据迁移问题
问题：如何确保UserTemp数据正确迁移？
解答：
- 通过auth_type和auth_key匹配UserAuth记录
- 建立UserTemp.id到User.id的映射关系
- 迁移后验证数据完整性
- 保留UserTemp表一段时间，确认无误后再删除
八、联系信息
如有问题，请联系开发团队。