321 lines
9.5 KiB
Markdown
321 lines
9.5 KiB
Markdown
# 表结构修改说明
|
||
|
||
本文档说明系统重构需要的所有表结构修改，包括：
|
||
1. UUID迁移（将所有bigint类型的ID改为CHAR(36)类型的UUID）
|
||
2. 用户系统重构（删除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`
|
||
- 完整的迁移流程，保留旧数据以便回滚
|
||
- 需要分阶段执行，包含数据迁移和验证
|
||
|
||
**开发环境执行步骤**：
|
||
1. 直接执行 `uuid_migration_simple.sql`
|
||
2. 所有表的主键和外键字段直接改为CHAR(36)
|
||
3. 插入新记录时，在应用层生成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表
|
||
|
||
**添加唯一索引**：
|
||
```sql
|
||
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表，逻辑更清晰
|
||
|
||
**删除步骤**：
|
||
1. 迁移UserTemp数据到User和UserAuth表
|
||
2. 更新关联的订单和报告的user_id
|
||
3. 验证数据完整性
|
||
4. 删除UserTemp表
|
||
|
||
### 2.4 执行脚本
|
||
|
||
**开发环境**：执行文件 `user_system_refactor.sql`（已简化）
|
||
- 直接删除UserTemp表
|
||
- 添加UserAuth唯一索引
|
||
|
||
**生产环境**：如需数据迁移，请参考完整版脚本
|
||
|
||
**开发环境执行步骤**：
|
||
1. 添加UserAuth唯一索引
|
||
2. 直接删除UserTemp表
|
||
|
||
**注意事项**：
|
||
- 开发环境脚本直接删除UserTemp表，不进行数据迁移
|
||
- 删除UserTemp表前，确保代码中已移除所有对UserTemp表的引用
|
||
|
||
## 三、执行顺序
|
||
|
||
### 3.1 推荐执行顺序
|
||
|
||
**开发环境**：
|
||
1. **先执行用户系统重构**（`user_system_refactor.sql`）
|
||
- 添加UserAuth唯一索引
|
||
- 删除UserTemp表
|
||
|
||
2. **再执行UUID迁移**（`uuid_migration_simple.sql`）
|
||
- 直接修改所有表结构
|
||
- 需要同步修改代码
|
||
|
||
**生产环境**：
|
||
1. 先执行用户系统重构（完整版，包含数据迁移）
|
||
2. 再执行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迁移出现问题，可以：
|
||
1. 保留原ID字段（迁移脚本中已保留）
|
||
2. 恢复主键为原ID字段
|
||
3. 删除UUID字段
|
||
4. 恢复代码使用int64类型
|
||
|
||
### 6.2 用户系统重构回滚
|
||
|
||
如果用户系统重构出现问题，可以：
|
||
1. 恢复UserTemp表（从备份）
|
||
2. 恢复订单和报告的user_id
|
||
3. 恢复代码使用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表一段时间，确认无误后再删除
|
||
|
||
## 八、联系信息
|
||
|
||
如有问题，请联系开发团队。
|