Xiaoxia AI
53 lines
2.0 KiB
Markdown
53 lines
2.0 KiB
Markdown
# Schema Mainline
|
|
|
|
## 当前结论
|
|
|
|
小虾 SaaS 当前运行时数据库结构的唯一主线是：
|
|
|
|
- `packages/adapters/sqlalchemy_impl/models.py`
|
|
- `packages/adapters/sqlalchemy_impl/session.py::initialize_database()`
|
|
|
|
`initialize_database()` 使用 SQLAlchemy `Base.metadata.create_all()` 创建缺失表，并通过 PostgreSQL advisory lock 避免多实例并发初始化。
|
|
|
|
## 已废弃入口
|
|
|
|
以下文件不得用于 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`
|
|
|
|
## 过渡原则
|
|
|
|
在正式引入 Alembic 前：
|
|
|
|
1. 运行时只允许 SQLAlchemy models 创建表。
|
|
2. 新字段必须先改 `packages/adapters/sqlalchemy_impl/models.py`。
|
|
3. Repository 映射必须和 SQLAlchemy model 同步。
|
|
4. Pydantic schema 只能表达 API 契约，不作为数据库真源。
|
|
5. Domain dataclass 只能表达业务实体，不作为数据库真源。
|
|
6. 历史 SQL 文件只允许作为参考，不允许部署脚本调用。
|
|
|
|
## 下一步：Alembic 化
|
|
|
|
后续应建立 Alembic 正式迁移链：
|
|
|
|
1. 以当前 staging 数据库实际结构生成 baseline revision。
|
|
2. 以 SQLAlchemy models 作为 autogenerate metadata。
|
|
3. 之后所有 schema 变更必须走 Alembic revision。
|
|
4. CI 增加迁移检查：`alembic upgrade head`。
|
|
5. 停止在生产入口调用 `Base.metadata.create_all()`，只保留开发/测试兜底。
|
|
|
|
## 禁止事项
|
|
|
|
- 不要新增 `init-*.sql` 作为运行时建表入口。
|
|
- 不要手工维护和 SQLAlchemy models 平行的 CREATE TABLE 文件。
|
|
- 不要让 API schema 或 domain entity 直接驱动数据库 schema。
|
|
- 不要在部署脚本中执行历史 SQL 快照。
|