Unified_Authentication_Platform/docs/AI_DB_GUIDE.md

AI 开发规范：数据库变更指南 (Database Migration Guide)

1. 核心原则 (Core Principles)

本项目的数据库管理采用 "Schema as Code" 模式，由 Flyway 和 SQLAlchemy 共同管理。 AI 在执行任何涉及数据库结构（Schema）的变更时，必须严格遵循以下流程。

🚫 禁止行为：

1. 禁止 直接告诉用户去数据库执行 SQL 语句。
2. 禁止 仅修改 Python models 代码而不创建 SQL 迁移脚本（这会导致代码与数据库不一致）。
3. 禁止 修改已经存在的/旧的 V 开头的 SQL 文件（历史记录不可篡改）。

---

2. 变更流程 (Workflow)

当用户提出需求（如：“给用户表加一个手机号字段”）时，AI 需按顺序执行以下步骤：

第一步：确定版本号

1. 扫描项目根目录下的 sql/ 文件夹。
2. 找到当前最大的版本号（例如当前是 V4__xxx.sql）。
3. 新文件的版本号 = 当前最大版本号 + 1（即 V5）。

第二步：创建迁移脚本 (Migration Script)

在 sql/ 目录下创建新文件。

• 命名规则：V{Version}__{Description}.sql

  • 注意：V 大写。
  • 注意：版本号与描述之间是 双下划线 (__)。
  • 示例：sql/V2__add_phone_column.sql

• 内容规范：

  • 使用标准 MySQL 8.0 语法。
  • 尽量保证操作的可重入性（虽然 Flyway 会保证只执行一次，但写法上推荐防御性编程）。
    

  -- 示例内容
  ALTER TABLE users ADD COLUMN phone_number VARCHAR(20) DEFAULT NULL COMMENT '用户手机号';
  -- 如果是创建表
  CREATE TABLE IF NOT EXISTS new_table (...);
  

  第三步：同步 SQLAlchemy 模型 (Sync Models)

  修改后端代码以匹配新的数据库结构。

  • 目标路径：backend/app/models/
  • 操作：找到对应的 Python 模型文件（如 user.py），添加或修改对应的 Column 定义。
    

  # backend/app/models/user.py
  class User(Base):
      # ... 原有字段
      phone_number = Column(String(20), nullable=True, comment="用户手机号") # 新增
  

第四步：同步 Pydantic Schema (Optional)

如果该字段需要通过 API 暴露或接收，需同步修改 Schema。

• 目标路径：backend/app/schemas/
• 操作：在 UserBase 或 UserCreate/UserUpdate 模型中添加字段。

---

3. 示例场景 (Example Scenario)

用户指令：

"帮我增加一个功能，记录用户的最后登录IP。"

AI 应执行的操作：

1. 读取文件列表：检查 sql/，发现最新是 V1__init.sql。

2. 创建文件：sql/V2__add_last_login_ip.sql。

   ALTER TABLE users ADD COLUMN last_login_ip VARCHAR(50) DEFAULT NULL;
   

   1. 修改模型：backend/app/models/user.py。 python last_login_ip = Column(String(50), nullable=True)

3. 修改 Schema：backend/app/schemas/user.py (视情况而定)。

4. 回复用户：

   "已为您创建了数据库迁移脚本 V2 并更新了后端模型。请执行 docker-compose up -d 以应用变更。"

---

4. 故障排查 (Troubleshooting)

如果 Flyway 启动失败（校验和错误）：

• 原因：有人修改了已经执行过的 SQL 文件。
• AI 建议：不要尝试通过 AI 修复历史文件的 checksum。建议用户进入 uap_migration 容器手动运行 flyway repair，或者在开发环境中清理 flyway_schema_history 表中的失败记录。