Table of Contents

20 MVP-1 可逆迁移与 admin 基线

背景与目标
最终方案
修改文件
验收结果
测试
遗留问题
相关提交
验收结论

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

20 MVP-1 可逆迁移与 admin 基线

类型：需求
所属 Epic：#3
所属 MVP / 版本：#19 / MVP-1
状态：已完成
日期：2026-08-21
Gitea 工单：#20
实现提交：6035ac4d9a4da2f52f5dc05f4e7a9e3791f39b95

背景与目标

为已确认的 MVP-1 提供唯一的生产表结构演进路径：建立可运行的 go-admin 最小系统基线，并在保留 MVP-0 数据的前提下引入 Provider 凭据版本、模型能力、路由池、熔断 runtime、连通性审计和生成记录增量字段。生产启动仍不得使用 GORM AutoMigrate。

最终方案

000002_admin_baseline 固化 go-admin f06540883b41d03782bb6b2c4150f298f328c6b6 所需身份、权限及 CRUD 元数据 sys_* 表；不创建管理员账号或已知密码。回退前通过数据库 guard 确认不存在管理员业务数据。
000003_mvp1_routing 先创建新表并回填凭据信封/能力，再增加引用和约束，最后清空旧 providers.api_key_enc。回退先恢复活动凭据到旧列，再移除新引用和表；不支持的 x-goog-api-key 降级会在改表前拒绝。
000004_mvp1_admin_seed 只按稳定的角色键、菜单路径和 API handle 写入或删除 Chorus 角色、菜单、API、菜单关联和 Casbin 权限。
sys_casbin_rule 保留 go-admin 的 512 字符字段，使用生成的 SHA-256 列去重，避免 utf8mb4 复合唯一索引超过 MySQL 3072 字节上限。

修改文件

migrations/000002_admin_baseline.{up,down}.sql：审查后的 go-admin 基线和管理员数据回退 guard。
migrations/000003_mvp1_routing.{up,down}.sql：凭据、路由、熔断、审计和 MVP-0 增量字段的可逆演进。
migrations/000004_mvp1_admin_seed.{up,down}.sql：Chorus 管理角色、菜单、API 和权限种子。
migrations/migrations_test.go：迁移编号、关键表/约束、禁用 AutoMigrate、稳定种子键和 guard 的静态契约检查。
migrations/mysql_integration_test.go：显式开启的 MySQL up/down/up 集成验证。

验收结果

验收标准	结果
空 MySQL 8 与含 MVP-0 fixture 的 up/down/up	通过
凭据信封回填、active credential 与 down 恢复	通过
路由、能力、审计、generation 增量字段及外键/索引	通过
管理菜单/API/权限种子按稳定键可逆	通过
生产未引入 AutoMigrate 或真实 Provider 调用	通过

测试

MySQL 8 隔离库：up -> legacy MVP-0 fixture -> up -> down 3 -> up 通过；验证 provider credential 回填/恢复、MVP-0 generation 保留、能力、admin 种子和 schema。
MySQL 8 空库：up -> down -all -> up 通过，最终版本 4；无终端用户、1 个 Chorus 角色、18 个 Chorus API 种子。
go build ./...、go vet ./...、go test -count=1 ./...、go test -race -count=1 ./migrations 通过。
python dev_scripts/harness.py check --strict 和 python -m unittest discover -s tests -v（42 项）通过。
未验证部分：尚未接入 go-admin 二进制、管理 API 或管理 UI；由 #21-#24 继续实现。未调用真实 Provider，未使用真实用户或生产数据。

遗留问题

无。本工单不实现路由算法、上游调用、管理 API 或页面逻辑。

验收结论

用户于 2026-08-21 明确确认 #20 验收通过。
迁移与验证证据见本页的验收结果和测试；未导出 docs/task/。