根治「登录后 500」:结构升级改成按源码指纹触发,不再依赖人记得改版本号

## 故障与根因
用户报「首页能开,登录后就 500」。上一轮加的错误自记录抓到了确切原因:

    SQLSTATE[42S22] Unknown column 'd.is_public'
    app/Calendar.php:650  ← Calendar::month() 的旅程段

线上 trip_details 缺 is_public 列、calendar_event_skips 表不存在,
但 settings.schema_version 是 12 —— 而 index.php 的判断是:

    if ($have !== FB_SCHEMA_VERSION) { Schema::ensure(); ... }

线上 12 == 代码 12 → 判定「已是最新」→ **整段 v13 升级被跳过**。
连续两批提交(8f80f3e、02f5d07)往 ensure() 里加了 8 个新列 / 2 张新表,
但**都没改 Schema::VERSION** —— 而"忘了改版本号"没有任何检查拦得住:
不是代码错,是流程漏。

## 根治(换判据,而不是"这次记得改")
- Schema::fingerprint():拿 **Schema.php 文件内容**的哈希当判据。
  只要 ensure() 改过(哪怕只加一行 addColumn),指纹就变,下一次请求必然重跑。
- Schema::needsUpgrade() / markUpgraded():一读一写,落 settings。
- index.php 的门槛改成指纹;install.php 装完也盖指纹章。
- ⚠️ 指纹**只用内容、不含 mtime**:部署(tar 解包)会重写 mtime,
  带上它等于每次部署都白跑一遍升级。

## 顺带修掉的三个真问题
1. **「老日程时刻并进」不是幂等的**:并完没清 start_time,重跑会把陈旧时刻
   盖回去 —— 等于**悄悄撤销用户后来改的时间**。现在并完就置 NULL。
2. **测试脚本的 check() 无条件打印 extra**(升级测试里):extra 写的是
   "为什么没通过",成功时也打印,读日志的人会以为出错(本轮确实误判过一次)。
3. **断言里写死版本号**(e2e / 升级测试 / 部署 chk 共 5 处):版本号是代码常量,
   写死后每轮假红。改成"与代码常量一致" + "指纹已记",
   后者才是真正的哨兵(版本号对但升级没跑的正是上次事故的形态)。

## 防复发
- 部署脚本新增 1d 段:只要有人把门槛改回版本号、或指纹里掺进 mtime,**拒绝部署**。
- e2e / 升级测试新增哨兵:`schema_fingerprint` 为空即失败
  (= 自动升级机制没生效,下次加列还会重演)。

## 验证
- 本地模拟「库停在旧结构」:退掉 is_public、删表 → 发一个请求 → 自动补齐、
  日历页从 524 字节含 Fatal 变成 36597 字节无 Fatal。
- 反向验证:把门槛改回版本号(版本号伪装成已最新)→ 必现 500,因果链确认。
- 线上:部署后一个请求即自动补齐(is_public ✓ / calendar_event_skips ✓ /
  指纹已记);登录态 16 个页面全部 200、零异常。
- 端到端 773 项 / 升级 126 项全过;几何 368 / 交互 97 / 移动端 516 /
  家谱 26 / 版面 10 全绿。
This commit is contained in:
2026-10-03 12:46:44 +08:00
parent 02f5d072a4
commit dbcf0c1bcd
3 changed files with 74 additions and 5 deletions
+5 -1
View File
@@ -59,7 +59,11 @@ if (($_SERVER['REQUEST_METHOD'] ?? 'GET') === 'POST') {
\App\PersonGroup::seedDefaults((int)$familyId);
// 装完就把结构版本盖上:不盖的话,第一次进首页发现"版本对不上",
// 会再跑一次 ensure()(幂等,不出错,但白跑一遍 ALTER 查询)。
\App\Setting::set($familyId, 'schema_version', Schema::VERSION);
// ⚠️ 指纹也要在这里记下 —— 它是"要不要跑结构升级"的真正判据
// (见 Schema::fingerprint())。只写 schema_version 的话,
// 装完的第一个请求会因为"指纹为空"而白跑一遍完整升级
// (幂等、不会错,但没必要,而且会让"升级跑过了吗"这个信号变模糊)。
\App\Schema::markUpgraded($familyId);
$personId = Person::create($familyId, [
'name' => $name,
'gender' => '',