Xiaoxia AI
80 lines
3.4 KiB
Markdown
80 lines
3.4 KiB
Markdown
# Schema Mainline
|
||
|
||
## 当前结论
|
||
|
||
小虾 SaaS 当前数据库结构主线已经切换为：
|
||
|
||
- Schema 定义真源：`packages/adapters/sqlalchemy_impl/models.py`
|
||
- 迁移执行真源：`alembic/versions/001_current_schema_baseline.py` 及后续 Alembic revisions
|
||
- 部署执行入口：`infra/docker/deploy-staging.sh` 中的 `alembic upgrade head`
|
||
|
||
`packages/adapters/sqlalchemy_impl/session.py::initialize_database()` 仍保留为开发/测试兜底函数，但 API 和 Worker 默认不再调用它：
|
||
|
||
- `apps/api/app/config.py::AUTO_CREATE_SCHEMA = False`
|
||
- `apps/worker/worker_app/core/config.py::auto_create_schema = False`
|
||
- `packages/adapters/sqlalchemy_impl/schema_guard.py` 会阻止 staging / production 开启自动建表
|
||
|
||
staging / production 不允许依赖 `Base.metadata.create_all()` 建表；表结构变更必须进入 Alembic revision。
|
||
|
||
## 已验证状态
|
||
|
||
截至 2026-06-21：
|
||
|
||
- Alembic baseline revision 已落地：`001_current_schema_baseline.py`
|
||
- staging 已完成 baseline stamp / upgrade
|
||
- staging 数据库 `alembic_version` 已确认：`002`
|
||
- staging health endpoint 已确认 healthy
|
||
- `develop` 部署 job 已确认 succeeded
|
||
- CI 已增加 Alembic offline upgrade SQL 生成检查，验证 migration 链可加载并能生成 `upgrade head` SQL
|
||
- CI 已增加 SQLAlchemy metadata snapshot drift 检查，防止改 models 后忘记同步 Alembic revision / schema snapshot
|
||
|
||
## 已废弃入口
|
||
|
||
以下文件不得用于 staging / production 建库：
|
||
|
||
- `init-tables.sql`
|
||
- `migrations/001_initial_schema.sql`
|
||
- `migrations/004_asset_management.sql`
|
||
|
||
这些 SQL 文件是历史快照，和当前 SQLAlchemy runtime schema 已经存在字段漂移。例如：
|
||
|
||
- 历史 `init-tables.sql` 使用 `assets.library_id/storage_key/mime_type`
|
||
- 当前 SQLAlchemy 使用 `assets.asset_library_id/file_url/file_type`
|
||
- 历史 SQL 文件没有完整覆盖 `generation_tasks/generated_videos/tasks/milestones/task_issues`
|
||
|
||
## 当前原则
|
||
|
||
1. 新字段必须先改 `packages/adapters/sqlalchemy_impl/models.py`。
|
||
2. 每次 schema 变更必须新增 Alembic revision。
|
||
3. Repository 映射必须和 SQLAlchemy model 同步。
|
||
4. Pydantic schema 只能表达 API 契约，不作为数据库真源。
|
||
5. Domain dataclass 只能表达业务实体，不作为数据库真源。
|
||
6. 历史 SQL 文件只允许作为参考，不允许部署脚本调用。
|
||
7. staging / production 只允许通过 Alembic 升级 schema。
|
||
8. `AUTO_CREATE_SCHEMA` 只能作为开发/测试兜底，staging / production 会被代码级 guard 阻止开启。
|
||
|
||
## Schema Drift 检查
|
||
|
||
CI 使用 `scripts/check_schema_metadata.py` 对比当前 SQLAlchemy metadata 和 `docs/schema-metadata-snapshot.json`。
|
||
|
||
如果 schema 变更是有意的，必须同时：
|
||
|
||
1. 修改 `packages/adapters/sqlalchemy_impl/models.py`。
|
||
2. 新增 Alembic revision。
|
||
3. 执行 `python scripts/check_schema_metadata.py --write` 刷新 snapshot。
|
||
4. 提交 models、revision、snapshot 三者。
|
||
|
||
## 下一步
|
||
|
||
后续 schema 工作应继续推进：
|
||
|
||
1. 对 production 首次接入 Alembic 前，按 `docs/PRODUCTION-RELEASE-CHECKLIST.md` 执行只读检查、备份、发布和 smoke。
|
||
|
||
## 禁止事项
|
||
|
||
- 不要新增 `init-*.sql` 作为运行时建表入口。
|
||
- 不要手工维护和 SQLAlchemy models 平行的 CREATE TABLE 文件。
|
||
- 不要让 API schema 或 domain entity 直接驱动数据库 schema。
|
||
- 不要在部署脚本中执行历史 SQL 快照。
|
||
- 不要在 staging / production 打开 `AUTO_CREATE_SCHEMA` 绕过 Alembic。
|