fix(#48): add the missing version-local migration for syb_session

Adding SYBSession to migrations.Migrate was not enough. Schema reaches an
existing database only through a version-local file; with the previous
version already recorded in sys_migration, Migrate never re-ran and the
table simply never appeared. The unit tests build a fresh database every
time, so they stayed green while the real database was missing a table —
which surfaced as "Error 1146: Table 'goauto.syb_session' doesn't exist"
on the first import attempt.

server/.gitignore was hiding these files. go-admin ignores version-local
because it is where generated local migrations land, but every GoAuto
migration belongs in version control; the existing ones had been forced
in with `git add -f`. Un-ignoring *.go there also recovers four migrations
that were never committed at all — 1786700000000 through 1786700300000,
covering the base schema, device registration, heartbeat and collection
execution. A fresh clone could not have built a working database.

Guard the class of mistake rather than just this instance:

  - migrations.VerifyTables checks every model's table after migrating and
    names what is missing along with the fix.
  - The migrate command runs it, so the failure lands at migrate time
    instead of at the first request that needs the table.
  - initDB no longer discards migrateModel's error. Upstream had
    `_ = migrateModel()` followed by an unconditional "初始化成功", so a
    failed migration reported success and the launcher believed it.

Also records the two-step rule in Common-Changes: a new model needs both
the model registration and a new version file.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
QiuSW
2026-08-20 10:10:11 +08:00
co-authored by Claude Opus 5
parent a81d60523d
commit e6f533b71e
10 changed files with 241 additions and 6 deletions
+17 -2
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki,禁止直接编辑本文件)
wiki_page: Common-Changes
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Common-Changes.-
wiki_revision: bba4d9558ccf9c6b5953ac99b958e81dc52a0637
synchronized_at: 2026-08-19T01:22:30Z
wiki_revision: 20cd4cd33e0cc7573e16b1de1442650e68fe472c
synchronized_at: 2026-08-20T02:07:25Z
<!-- gitea-wiki-mirror:end -->
# 常见修改指南
@@ -36,6 +36,21 @@ synchronized_at: 2026-08-19T01:22:30Z
停止条件:规则需要创建订单、支付、任意脚本、OCR/VLM 或点击不唯一候选。
## 新增数据库模型或字段
`[必须]` **两步都要做,缺一不可:**
1. 把模型加进 `server/app/goauto/models/schema.go`,并登记到 `migrations.MigratedModels()`;
2. 在 `server/cmd/migrate/migration/version-local/` 下**新建一个版本文件**(时间戳递增,照抄同目录已有文件的写法)。
只做第 1 步对**全新数据库**有效,对**已有数据库无效**:旧版本号已经记在 `sys_migration` 里,`Migrate()` 不会再次执行,表就是不会出现。而单元测试每次都用全新数据库,所以照样全绿——这个缺口只会在真实环境里暴露成一句 `Error 1146: Table ... doesn't exist`(见 [#48](https://git.ilapage.cn/OPC/goauto/issues/48))。
`[必须]` 模型必须显式声明 `TableName()` 返回单数表名。漏写时 gorm 会静默使用复数,迁移照样成功。
迁移命令跑完会调用 `migrations.VerifyTables` 核对所有表是否都在,缺表时直接以非零码退出并报出表名。
停止条件:修改或删除已有列、需要数据回填、涉及唯一键语义变化。
## 增加错误码
错误码必须包含稳定代码、用户可读消息、是否可重试和建议处理。同步更新 Android、服务端、管理端和 `docs/08-agent-api-contract.md`。