# 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 会保证只执行一次，但写法上推荐防御性编程）。
    
    ```sql
    -- 示例内容
    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` 定义。
    
    ```python
    # 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`。
    ```sql
    ALTER TABLE users ADD COLUMN last_login_ip VARCHAR(50) DEFAULT NULL;
    ```
3. **修改模型**：`backend/app/models/user.py`。
    ```python
    last_login_ip = Column(String(50), nullable=True)
    ```
4. **修改 Schema**：`backend/app/schemas/user.py` (视情况而定)。
5. **回复用户**：
    > "已为您创建了数据库迁移脚本 `V2` 并更新了后端模型。请执行 `docker-compose up -d` 以应用变更。"

---

## 4. 故障排查 (Troubleshooting)

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