xsl
71204affab
Creates the vector extension plus id_user, id_user_identity, id_consent, bl_quota_rule, bl_quota, bl_ledger, tk_task and ob_ai_call using the domain prefixes of 架构文档 §6.1, and seeds the quota rules. Reversible: verified by an upgrade/downgrade/upgrade round-trip, which CI now runs on every push.
37 lines
1.8 KiB
Markdown
Executable File
37 lines
1.8 KiB
Markdown
Executable File
# `migrations/` — Alembic
|
||
|
||
异步引擎（asyncpg）+ pgvector。`Base.metadata` 来自 `packages/shared/models.py`。
|
||
|
||
```bash
|
||
make migrate # upgrade head
|
||
make makemigration m="add kb tables" # autogenerate
|
||
uv run alembic downgrade -1 # 回滚一步
|
||
```
|
||
|
||
## 规矩
|
||
|
||
1. **迁移必须向后兼容**（架构 §14.3）：加列不删列、先双写后切读。发布流程是
|
||
「先迁移，后发布」，所以新迁移必须能和**旧版应用代码**共存，否则回滚时数据
|
||
不兼容。
|
||
2. **必须可逆，或在文件头明确标注不可逆并说明原因**（§16.2 迁移检查清单）。
|
||
CI 会跑 `upgrade → downgrade base → upgrade`。
|
||
3. **表名必须带域前缀**：`id_` / `pf_` / `rp_` / `kb_` / `ag_` / `tr_` / `bl_` /
|
||
`tk_` / `cp_` / `ob_`。单库多域，前缀就是将来拆库的边界（§6.1）。
|
||
4. **主键用雪花 ID（bigint）**，不用自增（枚举攻击 + 分库冲突），不用 UUID
|
||
作主键（索引局部性差）。
|
||
5. **不要存人脸原图，也不要存可反推生物特征的数据**（TD-20 / CR-02）。诊断结果
|
||
只存分类标签与色值等派生量。
|
||
6. 需要过滤的字段一律提升为列；JSONB 只用于「结构会演进且不需要索引全部字段」
|
||
的场景（§6.1 原则 6）。
|
||
7. 配置类数据（配额规则、色板、路由）用迁移种子进表，不要硬编码进代码
|
||
（NFR-MAINT-05）。
|
||
|
||
## 已有迁移
|
||
|
||
| 版本 | 内容 |
|
||
| --- | --- |
|
||
| `0001` | pgvector 扩展；`id_user` `id_user_identity` `id_consent`；`bl_quota_rule` `bl_quota` `bl_ledger`；`tk_task`；`ob_ai_call`；配额规则种子数据 |
|
||
|
||
§6.2 里其余的表（`pf_` 画像与记忆、`rp_` 报告、`kb_` 知识库、`ag_` 会话、
|
||
`tr_` 换装、`cp_` 合规）尚未创建，属于 M2~M4。
|