# Migrations

MySQL 8 的 Alembic 迁移目录。

当前数据库设计基线位于 `4/model_platform_schema.sql`。

## V1 基线

- Alembic：`1.18.5`
- 基线版本：`20260724_0001`
- 迁移文件：`versions/20260724_0001_v1_schema_baseline.py`
- 业务表：26 张
- 外键：71 个
- 索引：94 个
- `upgrade()`：可以从空 MySQL 8 数据库建立完整 V1 Schema。
- `downgrade()`：按反向依赖顺序删除 26 张业务表。

现有 `model_platform` 数据库原本由 V1 DDL 建立，结构校验一致后已使用
`alembic stamp head` 接管，没有重复执行建表。

## 常用命令

所有命令必须通过环境变量传入连接串，仓库中不保存数据库密码：

```powershell
$env:DATABASE_URL = "mysql+asyncmy://<user>:<password>@<host>:3306/<database>?charset=utf8mb4"
alembic -c alembic.ini current
alembic -c alembic.ini check
alembic -c alembic.ini upgrade head
```

迁移发布后不得直接修改旧版本；表结构变化应新增 revision，并评审自动生成的
数据类型、约束、索引、默认值和回滚顺序。

## 第 8 小步验收记录

- 执行日期：2026-07-24
- 目标服务：Docker Compose `mysql`
- 数据库：`model_platform`
- MySQL：8.0.36
- 空库升级：通过
- 模型与数据库结构校验：26 张表、71 个外键、差异 0
- `alembic check`：`No new upgrade operations detected`
- 回滚到 base：通过，剩余业务表 0
- 临时测试数据库：验收后已删除
- 现有开发库版本：`20260724_0001 (head)`

## 第 9 小步数据迁移

旧版 `文件1/platform_data/system.json` 已通过
`data/migrate_system_json.py` 事务化迁移到 MySQL：

- `roles`：2 行；
- `permissions`：13 行；
- `role_permissions`：21 行；
- `users`：4 行；
- `audit_logs`：26 行。

迁移工具默认 dry-run，显式 `--apply` 才写库；重复执行不会重复写入。

## 第 10 小步 Workspace 迁移

旧版 `文件1/server.py` 中的 `WORKSPACE_DEFINITIONS` 已通过
`data/migrate_legacy_workspaces.py` 事务化迁移到 MySQL：

- `workspaces`：2 行；
- `workspace_members`：4 行；
- 已有 `audit_logs.workspace_id`：按用户唯一 Workspace 关系补齐 26 行。

迁移工具使用 AST 读取静态常量，不执行旧版服务代码；默认 dry-run，显式
`--apply` 才写库。重复执行与后端镜像内隔离 dry-run 的变更数均为 0。