Table of Contents

#41 MVP-2 数据迁移与 API Key 核心能力

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

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.

#41 MVP-2 数据迁移与 API Key 核心能力

类型：需求
所属 Epic：#3
所属 MVP / 版本：#35 / MVP-2
状态：已完成
日期：2026-08-24
Gitea 工单：#41
Wiki 页面：Task-41-MVP-2-数据迁移与-API-Key-核心能力
Wiki revision：以本页在线 last_commit 为准

背景与目标

为 MVP-2 后续用户 API Key、OpenAPI、限流和审计实现建立可迁移的数据结构与不依赖 HTTP 框架的核心凭据能力。完整 API Key 不得落库，生产继续禁止 AutoMigrate。

最终方案

新增可逆迁移 000006_mvp2_openapi_governance，创建 api_keys、api_audit_events，为 generations 增加 available_at 并重建队列索引，同时写入管理端 API Key 菜单、API 与 Casbin 稳定键 seed。
down 在 API Key 或审计表非空时主动失败，避免静默删除安全数据；生产不得用 force 绕过。
internal/platform/apikey 使用 crypto/rand 生成 chorus_<public_id>_<secret>，仅保存 secret 的 SHA-256，并用常量时间比较。
internal/core/apikey 实现按终端用户隔离的创建、读取、列表、改名和幂等撤销仓储；核心层没有引入 Gin 或 go-admin。
对照已确认设计补齐 last_used_at 索引、固定长度数据库约束、跨用户拒绝与重复 public_id 失败验证。

修改文件

migrations/000006_mvp2_openapi_governance.*.sql：MVP-2 数据结构、权限 seed 与受保护回滚。
internal/core/model、internal/core/apikey：API Key、API 审计和可用时间模型及 GORM 仓储。
internal/platform/apikey：随机令牌生成、解析、哈希和常量时间校验。
migrations/*_test.go 与相关包测试：静态契约、真实 MySQL 往返、归属、唯一性、事务和 JSON 防泄漏验证。
docs/02、03、04、10：从 Wiki 同步的实现、业务、验证与运维说明。

验收结果

验收标准	结果
完整 Key 只在生成结果内存值出现，数据库只保存哈希、前缀和元数据	通过
撤销、到期、用户归属和唯一约束有测试	通过
000006 在含 MVP-1 fixture 的隔离 MySQL 完成 up/down/up，非空数据 down 被拒绝	通过
`available_at`、索引和权限 seed 可逆，未使用 AutoMigrate	通过
Go、管理端、迁移、Harness 和 Wiki 镜像检查通过	通过

测试

执行命令：go test ./...、go vet ./...、go -C admin test ./...
执行命令：在明确命名并自动删除的 chorus_mvp2_test 上顺序执行 go test ./migrations -count=1 与 go test ./internal/core/apikey -count=1
执行命令：python dev_scripts/harness.py sync --check、python dev_scripts/harness.py check --strict、python -m unittest discover -s tests -v
结果：全部通过；Harness 42 项测试通过；未连接当前服务数据库，未调用真实 Provider。
未验证部分：未对生产/共享数据库执行迁移或回退；HTTP 路由、页面、限流和管理端 UI 属于后续工单。

遗留问题

#41 已于 2026-08-24 由用户验收通过。后续 #42～#47 继续交付 MVP-2 的 HTTP、页面、限流、审计管理与集成验收。