temp

deploy/sql/README_表结构修改说明.md

@@ -0,0 +1,320 @@
+# 表结构修改说明
+
+本文档说明系统重构需要的所有表结构修改，包括：
+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表一段时间，确认无误后再删除
+
+## 八、联系信息
+
+如有问题，请联系开发团队。