# 表结构修改说明

本文档说明系统重构需要的所有表结构修改，包括：
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表一段时间，确认无误后再删除

## 八、联系信息

如有问题，请联系开发团队。