Appearance
Migration
來源：
backend/migrator/migration/、backend/migrator/migration/LATEST.sql、backend/migrator/migrator_test.go::TestLatestVersion。
怎麼運作
Argus server 啟動時自動跑 metastore migration：
- 讀
backend/migrator/migration/<version>/<NNNN>##<name>.sql列表 - 與
revision/migration_history表比對，找出 pending - 依版本順序套用
- 失敗 → server fail-fast，需人工修補
不要直接
psql改 metastore schema。它會破壞 migration 順序與migrator_test.go的版本檢查。
版本目錄
| 主版本 | 用途 |
|---|---|
3.0 – 3.18 | Argus 演進歷程；每個目錄含若干 NNNN##name.sql 與一個 schema snapshot |
LATEST.sql | 當前 schema 完整 snapshot（fresh-install 用） |
當前最新主版本：3.18（含 9000-9006 系列，多為 Argus P0-AUTH-* identity / RLS / replag 相關）。
最新版本列表（3.18）：
| 檔名 | 主題 |
|---|---|
0000##add_email_verification_code.sql | email 驗證碼 |
9000##create_internal_risk_rule.sql | P0-3 Risk Rule 引擎 |
9001##add_principal_login_id.sql | P0-AUTH login_id 欄位 |
9002##drop_principal_name_phone.sql | P0-AUTH 移除舊欄位 |
9003##migrate_refresh_token_to_login_id.sql | refresh token 改用 login_id |
9004##migrate_creator_email_to_login_id.sql | creator 欄位改用 login_id |
9005##add_replag_seed.sql | replication lag 種子 |
9006##audit_rls_and_roles.sql | audit log RLS + role 隔離 |
新增 migration 必同時：寫
<NNNN>##<name>.sql+ 改LATEST.sql+ 改migrator_test.go::TestLatestVersion。流程細節見AGENTS.md。
Composite-PK 表清單
下列表使用複合主鍵。所有 WHERE / JOIN / USING / DELETE / UPDATE predicate 必須 帶完整 PK，不可只以 id 過濾。
| 表 | 主鍵 |
|---|---|
plan | (project, id) |
issue | (project, id) |
task | (project, id, pipeline) |
task_run | (project, id, task) |
plan_check_run | (project, id, plan) |
plan_webhook_delivery | (project, id, plan) |
db_group | (project, id) |
release | (project, id) |
task_run_log | (project, id, task_run) |
違反者會出現 BYT-9259 類的 cross-project bleed bug。觸及這些表的新 store 方法必須補對應
TestCollision_*測試（見backend/tests/）。
客製 migration（不推薦）
如果你真的需要手動修 metastore（例：救援），程序：
- 在 staging 完全重現問題
- 寫 down/up 兩個 SQL，dry-run
- 取得 DBA Lead + Argus owner 雙簽
- 執行；同步寫
LATEST.sql+ 補 migration 檔 - 於下次 release 把這段補進正式 migration 序列
跳過任一步 → 下次自動 migration 會踩到「current schema != expected schema」並 fail-fast。