feat(schedule): 重构课表多端同步为 per-plan revision CAS

[WALKERKILLER]

Background / 背景

排课器的课表方案云同步已经由 #537 建立，并在 #571 / #573 后补充了 CAS、网络恢复和 Web 端自动恢复策略。

本次基于最新 dev 对 Web、Mobile、/api/pk/plans 与数据库实现重新排查后，确认目前仍有一个同步模型层面的多端冲突问题：

• 当前服务端以“每用户一份完整快照”作为写入单元：plans + activePlanId + majorSelected + weekView 共用一个 updatedAt / baseUpdatedAt CAS。
• 任一设备对任一方案或 UI 状态的修改都会推进整包版本；两个设备即使只修改不同方案，也会在同一个快照版本上竞争。
• Web 在真实分歧时采用“云端为主 + 将本地方案克隆为 [本地自动恢复]方案 x”的策略；这能保数据，但不是同一方案的真正多端合并。反复发生真实冲突时，恢复方案仍会持续占用正常方案额度，最终可能触及 MAX_PLANS = 10。
• Mobile 当前冲突策略与 Web 不一致：Mobile 会停下并要求用户在“使用云端 / 保留本地”之间选择；同一账号跨 Web / App 使用时行为不统一。
• activePlanId、weekView 等设备 UI 状态也参与整包 revision，制造了与课表内容无关的冲突。

需要区分一个已修复的历史问题：PR #668（commit 8f8bac85）已经修复了 Go wire 的 null 键与本地缺省键导致“同内容也被重复克隆”的问题。当前要解决的是真实多端修改下，整包快照 + 恢复副本模型仍然会产生结构性冲突和方案膨胀，不是重新修 #668。

资源评估

本改造应以低服务器负载为约束，不引入重型同步基础设施。推荐方案在正常实现下预计比现有整包同步更省：

• 单次修改只写一个方案，不再重写用户全部方案 JSON；
• 三方合并在客户端完成，服务端只做读取和 revision 条件写；
• 不使用 WebDAV Server、CRDT、OT、WebSocket、Redis 锁、消息队列、后台 merge worker 或完整版本历史；
• 干净状态不做固定 10s 同步心跳，仅在本地 dirty、进页、重新聚焦（必要时）、网络恢复时触发同步。

Target Users / 目标用户

• 同一 YourTJ 账号同时在多个浏览器、电脑、手机 App 上使用排课器的用户；
• 网络不稳定、离线编辑后重新联网的用户；
• Web / Mobile 排课器维护者，需共享统一的同步语义与契约。

User Story / 用户故事

作为在多台设备上使用排课器的学生，我希望同一个课表方案在不同设备上的修改能够按方案正确同步；当两端修改互不冲突时自动合并，当确实修改了同一字段且无法自动判断时再提示我处理，而不是不断生成新的“自动恢复方案”或让我在整份本地/云端数据之间二选一。

Scope / 范围

1. 将同步冲突粒度从“用户整包快照”降为“单个 plan”

建议服务端按 (user_id, plan_id) 保存方案，每个方案独立维护整数 revision，例如：

user_id
plan_id
revision      // BIGINT / integer，服务端递增
payload       // 现阶段可继续复用现有 PkPlan JSON，避免同时重构数据模型
updated_at    // 仅用于展示/诊断，不再承担同步正确性

不要求第一阶段立即瘦身 PkPlan payload；先只改变同步粒度，降低迁移风险。

2. 使用整数 revision 做条件写，不再用时间戳承担 CAS 版本号

客户端写入时携带自己观察到的 baseRevision：

UPDATE ... SET payload=?, revision=revision+1
WHERE user_id=? AND plan_id=? AND revision=?

• 命中：保存成功并返回新 revision；
• 未命中：返回冲突，并尽量在冲突响应中直接附带当前 remote plan + revision，避免客户端额外 GET；
• 新方案仅允许 baseRevision = 0 / create 语义。

updated_at 保留为显示时间，不参与版本一致性判断。

3. 三方合并放在客户端完成

Web / Mobile 为每个已同步方案保留最近一次成功同步的 base snapshot：

base   = 上一次同步成功的方案
local  = 当前本地方案
remote = 409 返回的云端最新方案

客户端执行 base / local / remote 三方合并：

• 仅 local 改动 → 保留 local；
• 仅 remote 改动 → 采用 remote；
• 两端修改不同课程 / 不同自定义事件 → 自动合并；
• 同一课程教学班、同一事件或同一字段被两端改成不同值 → 才进入显式冲突处理。

实现时应优先复用现有稳定标识（planId、custom event id、课程/教学班标识），不引入 CRDT。

4. 取消“正常方案列表中的自动恢复副本”作为常规冲突策略

• 可自动三方合并的冲突不创建新方案；
• 无法自动合并时提供明确的局部冲突处理；
• 若仍需保底副本，放到独立的 conflict draft/archive，而不是 plans 正常集合，不计入 MAX_PLANS，也不参与下一轮正常同步；
• 同一冲突必须幂等，不能重复产生多个恢复草稿。

5. 删除语义防止离线旧设备复活方案

第一阶段无需长期 tombstone 表：

• 新建方案只能使用 baseRevision = 0；
• 已同步方案始终使用 baseRevision > 0；
• 若客户端提交 baseRevision > 0 但服务端该 planId 已不存在，则返回 deleted/conflict（409/410），不得当作新建；
• planId 不复用。

这样可以直接物理删除方案，同时防止长期离线设备把已删除方案重新创建。

6. 将设备 UI 状态从方案内容 CAS 中拆出

建议：

• activePlanId：仅本地；
• weekView：仅本地；
• majorSelected：不得继续与所有 plans 共用 revision。若确有跨设备同步价值，可后续作为独立轻量 preference 资源；否则先保留本地。

避免“电脑切换查看周次”导致“手机编辑课表方案”产生云端冲突。

7. 统一 Web / Mobile 同步状态机

Web 与 Mobile 对以下行为必须一致：

• 首次云同步；
• 本地 dirty；
• 409；
• 网络失败后的重试；
• 远端删除；
• 同一方案三方合并；
• 无法自动合并时的用户提示；
• 账号切换时本地数据归属。

8. 改为 dirty / lifecycle 驱动同步

不新增常驻连接，取消干净状态的固定 10s 同步心跳：

• 本地方案修改：约 3s debounce 后上传该 dirty plan；
• 进入排课页：拉取方案及 revisions；
• 页面重新聚焦：仅在距离上次同步达到合理阈值时拉取；
• offline -> online：立即处理 dirty plans；
• 网络失败：仅 dirty 数据按退避策略重试。

Out of Scope / 不做什么

本 Issue 第一阶段明确不做：

• 部署完整 WebDAV 服务；
• CRDT / OT；
• WebSocket 实时协作；
• Redis / 分布式锁 / 消息队列；
• 服务端三方 merge worker；
• 每次修改的完整历史版本表；
• 同步架构改造同时重做整个课程数据 schema；
• 多人共同编辑同一份课表（本 Issue 仅解决同一账号多设备）。

Migration / 迁移建议

建议渐进迁移，避免一次性推翻现有 /api/pk/plans：

1. 新增 per-plan 存储与契约；
2. 对现有每用户 snapshot 做一次性/惰性拆分，将原有 plans[] 原样迁移为 per-plan rows；
3. 第一阶段 payload 继续兼容现有 PkPlan，只改变 revision 与同步粒度；
4. Web / Mobile 使用同一契约与冲突规则后，再移除旧整包写入路径；
5. 迁移期间不得丢失现有本地或云端方案；旧的 [本地自动恢复] 方案按普通已有方案迁移，不做自动删除。

Acceptance Criteria / 验收标准

• 两台设备从同一 revision 出发，分别修改不同方案，双方均可保存，不产生 409。
• 两台设备修改同一方案但不同课程/不同事件时，可通过三方合并得到一份方案，不新增“自动恢复方案”。
• 两台设备修改同一方案的同一字段为不同值时，只对实际冲突项提示用户处理，不要求整份“使用本地/使用云端”二选一。
• Web 与 Mobile 对首次同步、dirty、409、网络恢复、远端删除的行为一致。
• 已在另一设备删除的方案不会被长期离线设备重新“复活”。
• activePlanId / weekView 的本地变化不会推进课表方案 revision。
• 正常同步冲突不会增加 plans.length；不存在因多端反复修改而逐步占满 MAX_PLANS 的路径。
• 服务端不承担三方合并计算，不引入 WebDAV / CRDT / WebSocket / Redis 锁 / MQ 等额外基础设施。
• 单方案修改只上传/写入该 plan，不重写该用户其他方案。
• 现有云端方案可无损迁移，且迁移前后的方案内容与用户归属一致。
• 为 Web、Mobile、Backend/Contract 增加对应并发与迁移回归测试。

Supplementary Materials / 补充材料

相关历史：

• feat: 排课器课表方案云端同步——多端会话登录可查看自己的排课方案 #537：排课器课表方案云端同步
• bug: 多端课表云同步失效——手机 Web 排课后桌面端无法同步最新排课 #571：多端课表云同步失效
• feat: 排课器 web 端云端同步体验优化——默认自动上传、网络恢复自动补传、移除不一致弹窗 #573：Web 端自动上传 / 网络恢复 / 自动恢复方案策略
• fix(schedule): normalize plan content fingerprints across wire shapes #668：已修复跨 wire shape 指纹不一致导致同内容恢复方案重复克隆的问题

本次排查在最新 dev 上确认：

• Web：apps/gooseforum/resource/src/site/composables/useScheduleSync.ts
• Web store：apps/gooseforum/resource/src/site/composables/useScheduleStore.ts
• Backend：apps/gooseforum/app/http/controllers/pk/plans.go、apps/gooseforum/app/models/forum/pk/schedule_snapshot_rep.go
• Mobile：apps/mobile/packages/forum_app/lib/src/schedule/schedule_sync.dart
• Contract：packages/api-contract/components/schemas.yaml

现有 Web 云同步回归测试 47/47 通过，说明 #668 所覆盖的“同内容重复克隆”回归当前成立；本 Issue 处理的是测试通过后仍存在的同步粒度与冲突模型问题。

Code of Conduct

• I agree to follow this project's Code of Conduct / 我同意遵守本项目的行为准则

[oryn-mini]

🧹 Oryn Mini · 🧭 Your input is needed

Code review · Attempt 1 · Cycle 1

Waiting for your decision: 拆分后 majorSelected（学期/年级/专业）应继续跨设备同步，还是降级为设备本地状态？这决定契约是新增 preference 资源还是直接删字段。
Validation has not run. No repair patch was published by this attempt.

View the Actions run

Run details · operational receipt

{
  "version": 1,
  "workKey": "review:0659c7424ea10cea809b43b3",
  "sourceKey": "0659c7424ea10cea809b43b3",
  "intent": "review",
  "phase": "completed",
  "attempt": 1,
  "cycle": 1,
  "leaseID": "42f2e0d3-3438-4ea9-9cf5-6877f6908f31",
  "verdict": "needs_human",
  "triage": {
    "category": "feature",
    "priority": "P2",
    "confidence": "high",
    "reproduction": "source_proven",
    "proof": "sufficient",
    "decision": "keep_open",
    "closeReason": "none",
    "canonicalNumber": 714,
    "implementationCandidate": false,
    "complexity": "large",
    "evidence": [
      {
        "path": "apps/gooseforum/app/models/forum/pk/schedule_snapshot.go",
        "line": 94,
        "sha": "7a564466275ecebce2cc0f3b4cc1c362fb90aced",
        "detail": "ScheduleSnapshotEntity 以 user_id uniqueIndex 单行存储 plans/active_plan_id/major_selected/week_view 四字段，updated_at 为唯一同步时钟，无逐方案 revision 列。"
      },
      {
        "path": "apps/gooseforum/app/models/forum/pk/schedule_snapshot_rep.go",
        "line": 111,
        "sha": "7a564466275ecebce2cc0f3b4cc1c362fb90aced",
        "detail": "CompareAndSwapScheduleSnapshot 用 `Where(\"user_id = ? AND updated_at = ?\", ...)` 做条件写，版本号是 RFC3339Nano 时间戳而非整数 revision，RrowsAffected==0 时返回 ErrScheduleSnapshotConflict。"
      },
      {
        "path": "apps/gooseforum/app/models/forum/pk/schedule_snapshot_rep.go",
        "line": 89,
        "sha": "7a564466275ecebce2cc0f3b4cc1c362fb90aced",
        "detail": "base==\"\" 走 OnConflict{DoNothing} 的 create-only 语义，非空 base 走时间戳精确匹配；不存在「base 指向已删除 plan」的判定分支，删除后写入会被当作新行创建。"
      },
      {
        "path": "apps/gooseforum/app/http/controllers/pk/plans.go",
        "line": 37,
        "sha": "7a564466275ecebce2cc0f3b4cc1c362fb90aced",
        "detail": "PutPlansReq 只带 BaseUpdatedAt *string 与整包四字段；BaseUpdatedAt 省略时执行无条件 UpsertScheduleSnapshot，契约描述也写明 omission preserves unconditional replacement。"
      },
      {
        "path": "apps/gooseforum/app/http/controllers/pk/plans.go",
        "line": 87,
        "sha": "7a564466275ecebce2cc0f3b4cc1c362fb90aced",
        "detail": "CAS 冲突返回 Code 409 且 Data 为空对象，不附带当前 remote 方案与 revision，客户端必须再发一次 GET（issue 第 2 条要求冲突响应尽量直接带回远程方案）。"
      },
      {
        "path": "apps/gooseforum/resource/src/site/composables/useScheduleSync.ts",
        "line": 101,
        "sha": "7a564466275ecebce2cc0f3b4cc1c362fb90aced",
        "detail": "PK_SYNC_AUTOSAVE_MS = 10000，干净状态每 10s 心跳整包重传；issue 第 8 条要求取消该心跳，改为 dirty/lifecycle 驱动。"
      },
      {
        "path": "apps/gooseforum/resource/src/site/composables/useScheduleSync.ts",
        "line": 203,
        "sha": "7a564466275ecebce2cc0f3b4cc1c362fb90aced",
        "detail": "mergeAndUpload 在提交前检查 mergedPlans.length > MAX_PLANS 或 >1MB 即置 mergeBlocked 返回 blocked，说明恢复副本策略确有容量上限阻塞路径。"
      },
      {
        "path": "apps/gooseforum/resource/src/site/composables/useScheduleSync.ts",
        "line": 209,
        "sha": "7a564466275ecebce2cc0f3b4cc1c362fb90aced",
        "detail": "合并与普通上传的 payload 都包含 activePlanId/majorSelected/weekView，UI 状态随内容一起推进同一个 baseUpdatedAt 版本。"
      },
      {
        "path": "apps/gooseforum/resource/src/site/composables/useScheduleStore.ts",
        "line": 93,
        "sha": "7a564466275ecebce2cc0f3b4cc1c362fb90aced",
        "detail": "MAX_PLANS = 10，且新增/复制方案在该上限处直接返回 null；恢复克隆不受独立配额保护。"
      },
      {
        "path": "apps/gooseforum/resource/src/site/composables/useScheduleStore.ts",
        "line": 194,
        "sha": "7a564466275ecebce2cc0f3b4cc1c362fb90aced",
        "detail": "clonePlansAsAutoRestore 按 planContentKey 去重后把本地方案追加为恢复方案，是「正常方案列表中的自动恢复副本」这一被 issue 要求取消的常规冲突策略。"
      },
      {
        "path": "apps/gooseforum/resource/src/site/composables/useScheduleStore.ts",
        "line": 1004,
        "sha": "7a564466275ecebce2cc0f3b4cc1c362fb90aced",
        "detail": "solidify 持久化 plans/activePlanId/weekView 并在 changed 时调用 solidifyHook，即切换周视图或激活方案会触发同步钩子标脏。"
      },
      {
        "path": "apps/mobile/packages/forum_app/lib/src/schedule/schedule_sync.dart",
        "line": 136,
        "sha": "7a564466275ecebce2cc0f3b4cc1c362fb90aced",
        "detail": "Mobile 在 `isDirty || store.syncedAt != remote.updatedAt` 时直接设置为 conflict 并停下等待用户选择，与 Web 的自动合并策略不一致。"
      },
      {
        "path": "apps/mobile/packages/forum_app/lib/src/pages/schedule/schedule_page.dart",
        "line": 146,
        "sha": "7a564466275ecebce2cc0f3b4cc1c362fb90aced",
        "detail": "冲突弹窗注释明确「使用云端」整包采用 /「保留本地」立即上行，正是 issue 要移除的整包二选一交互。"
      },
      {
        "path": "packages/api-contract/components/schemas.yaml",
        "line": 3643,
        "sha": "7a564466275ecebce2cc0f3b4cc1c362fb90aced",
        "detail": "PkPlansPutRequest/PkPlansSnapshotData 把 plans/activePlanId/majorSelected/weekView 定义为整体替换的单个快照，与 per-plan revision 契约不兼容，改造必须同 PR 更新契约与生成产物。"
      },
      {
        "path": "docs/product/current-state.md",
        "line": 74,
        "sha": "7a564466275ecebce2cc0f3b4cc1c362fb90aced",
        "detail": "文档把「排课方案云同步」标为 Current 并记录整包快照 + 恢复方案克隆 + 10s 心跳 + 移动端弹窗语义，本改造落地后必须同步更新状态词与描述。"
      },
      {
        "path": "docs/decisions/README.md",
        "line": 58,
        "sha": "7a564466275ecebce2cc0f3b4cc1c362fb90aced",
        "detail": "决策日志要求「在多个有意义方案间取舍且未来可能被重新审视」时建 MADR；同步粒度、majorSelected 归属与冲突草稿归档属此类，需补记录或明确 spec。"
      },
      {
        "path": "apps/gooseforum/app/migration/schedule_snapshot_schema_test.go",
        "line": 32,
        "sha": "7a564466275ecebce2cc0f3b4cc1c362fb90aced",
        "detail": "迁移测试仅断言 pk_schedule_snapshot 表存在（含升级路径），没有任何 per-plan 表或 revision 列断言，佐证目标模型尚未实现。"
      }
    ],
    "risks": [
      "迁移期新旧写入路径并存：老客户端仍整包 PUT，若 per-plan 写入与旧快照路径没有明确的优先级/兼容规则，会出现双方互相覆盖或数据分叉。",
      "取消 10s 心跳后若 dirty/lifecycle 触发漏掉页面聚焦或联网事件，编辑可能长时间停在本机不上传，相对 #573 的自动补传是可感知的体验回退。",
      "mobile Dart 契约镜像仍是手工同步（生成标注为 Planned），后端契约一旦改动，Web TS 与 Mobile 类型容易漂移，需在同 PR 逐项对齐。",
      "冲突草稿/归档不计入 MAX_PLANS 若没有独立上限，会变成无界存储，同时要兼顾服务端 1MB/请求体积与账号注销时的删除语义。",
      "dev 实例每次部署同步主库快照，迁移若不可逆或有损，线上回滚窗口很小，需要先做可重放的拆分迁移演练。"
    ],
    "decisionNote": {
      "question": "拆分后 `majorSelected`（学期/年级/专业）应继续跨设备同步，还是降级为设备本地状态？这决定契约是新增 preference 资源还是直接删字段。",
      "options": [
        "本地化：最彻底地消除 UI 状态冲突，代价是换设备后需重新选择专业/年级",
        "拆为独立轻量 preference 资源（独立 revision）：保留跨设备便利，代价是多一条契约、存储与状态机分支",
        "继续随方案同步：迁移成本最低，但与本 issue 第 6 条「UI 状态不参与方案 CAS」目标冲突"
      ],
      "recommendation": "按 issue 建议先把 activePlanId/weekView 本地化，`majorSelected` 走独立 preference（单独 revision、不参与 plan CAS）；若想压缩第一阶段范围，可先本地化并在契约上预留偏好资源位，避免把它继续留在整包版本里。"
    }
  },
  "run": "https://github.com/YourTongji/YourTJ-Hub/actions/runs/35894489217",
  "summary": "Waiting for your decision: 拆分后 `majorSelected`（学期/年级/专业）应继续跨设备同步，还是降级为设备本地状态？这决定契约是新增 preference 资源还是直接删字段。\nValidation has not run. No repair patch was published by this attempt."
}

---

[oryn-mini]

🧹 Oryn Mini · 🧭 Your input is needed

🟡 P2 · Normal · 💡 Feature · High confidence

What I found

当前 /api/pk/plans 以「每用户一份整包 JSON 快照」为写入单元：plans、activePlanId、majorSelected、weekView 共用同一个 updated_at 时间戳 CAS，因此两台设备修改不同方案、甚至只是切换周视图，都会在同一条版本上互撞。冲突兜底同样不对等——Web 会把本地方案克隆成「[本地自动恢复]方案x」塞回正常方案列表（反复冲突会挤压 MAX_PLANS=10），Mobile 则停下来让用户在整包「使用云端／保留本地」之间二选一。本 issue 要把冲突粒度降到一个方案一条记录、用整数 revision 做条件写、三方合并放客户端并统一两端状态机，属于排课方案云同步从「能同步」走向「真正多端可用」的结构性改造，涉及数据库迁移、契约与生成客户端、两端状态机与迁移兼容，需要一次协调落地。

Proposed change

• 存储与版本：现状是每用户一行 pk_schedule_snapshot，plans/active_plan_id/major_selected/week_view 四字段共享 updated_at 时间戳 CAS → 目标按 (user_id, plan_id) 存行、每个方案独立整数 revision 条件写，updated_at 只用于展示/诊断，不再承担版本号。
• 冲突处理：现状是 Web 把本地分歧方案克隆为「[本地自动恢复]方案x」并追加上传、Mobile 弹整包二选一弹窗 → 目标为客户端 base/local/remote 三方合并，仅对同一课程教学班／同一自定义事件／同一字段的真正冲突做局部提示，冲突草稿移出正常 plans 集合且不计入 MAX_PLANS。
• 设备 UI 状态：现状 activePlanId/weekView（以及 majorSelected）随整包 PUT 推进同一 revision → 目标把 activePlanId/weekView 留在本地，majorSelected 要么本地化、要么拆成独立轻量 preference 资源，不再与课表内容共用版本。
• 删除语义：现状 DELETE 直接删整行、无逐方案版本守卫，离线旧设备以过期 base 上传命中 409 后走合并路径会把本地仍持有的已删方案写回 → 目标规定 baseRevision=0 仅用于新建、baseRevision>0 命中不存在的 planId 返回 409/410，planId 不复用。
• 同步触发：现状是 3s debounce 加干净状态 10s 心跳整包重传 → 目标取消心跳，改为本地 dirty（约 3s debounce）只上传该方案、进页拉取方案与 revisions、重新聚焦按阈值拉取、offline -> online 立即处理 dirty，失败仅对 dirty 数据退避重试。

How it fits together

Web 与 Mobile 各自整包 PUT，服务端每用户单行快照用共享时间戳做 CAS；冲突由客户端恢复克隆或二选一弹窗消化。

flowchart TD
  accTitle: 当前整包快照同步拓扑
  accDescr: Web 与 Mobile 各自整包 PUT，服务端每用户单行快照用共享时间戳做 CAS；冲突由客户端恢复克隆或二选一弹窗消化。
  n_0["Web useScheduleSync"]
  n_1["Mobile ScheduleSyncController"]
  n_2["GET/PUT/DELETE /api/pk/plans"]
  n_3["pk_schedule_snapshot 单行"]
  n_4["updated_at 时间戳 CAS"]
  n_5["plans 列表 MAX_PLANS 10"]
  n_0 -->|"整包 PUT"| n_2
  n_1 -->|"整包 PUT"| n_2
  n_2 -->|"四字段整体替换"| n_3
  n_3 -->|"共享同一 revision"| n_4
  n_4 -->|"409 重对账"| n_0
  n_4 -->|"409 阻塞弹窗"| n_1
  n_0 -->|"恢复方案克隆占用额度"| n_5

Loading

Review findings

🟡 Medium · 整包快照共用同一时间戳 CAS，不同方案也互相竞争 — apps/gooseforum/app/models/forum/pk/schedule_snapshot_rep.go:111

每用户单行存储 plans/active_plan_id/major_selected/week_view，条件写用 user_id = ? AND updated_at = ? 比对时间戳，模型与迁移中都没有整数 revision 列；控制器同样是四字段整体替换。因此任一设备修改任一方案（或仅改 UI 状态）都会推进同一版本，两台设备改不同方案仍会有一方拿到 409，对应 issue 验收项「两台设备分别修改不同方案，双方均可保存」当前无法满足。

🟡 Medium · 设备 UI 状态参与方案版本，制造与内容无关的冲突 — apps/gooseforum/resource/src/site/composables/useScheduleStore.ts:1004

store 的 solidify 会把 plans/activePlanId/weekView 一起持久化并调用同步钩子，PUT payload 也带上 activePlanId/majorSelected/weekView，所以「电脑切换查看周次」会标脏上传并推进快照版本，与手机端编辑课表方案共用同一个 CAS 版本。这正是 issue 第 6 条要拆开的耦合，需要在拆分方案存储时一并把 UI 状态移出。

🟡 Medium · 冲突兜底把恢复副本塞回 plans，持续占用 MAX_PLANS 额度 — apps/gooseforum/resource/src/site/composables/useScheduleSync.ts:203

Web 分歧合并用 clonePlansAsAutoRestore 把本地方案克隆进云端方案数组并整包重传，合并结果超过 MAX_PLANS=10 或 1MB 时置 mergeBlocked 仅做提示，没有清理引导；真实分歧反复发生时恢复方案会持续占用正常方案额度并最终阻塞同步。PR #668 只修掉了「同内容因 wire shape 差异被重复克隆」，剩余的是结构性副本策略，与本 issue 描述一致。

More findings (3)

🟡 Medium · Web 与 Mobile 冲突语义不一致 — apps/mobile/packages/forum_app/lib/src/pages/schedule/schedule_page.dart:146

Web 走「自动对账 + 恢复克隆 + 不弹阻塞窗」，Mobile 在本地 dirty 或 syncedAt 与服务端版本不符时弹阻塞弹窗，只能整包「使用云端」（adoptRemote）或整包「保留本地」立即上行（keepLocal）。同一账号跨 Web/App 使用时行为分裂，且 Mobile 的 3s debounce 之外没有心跳补传，与 Web 的重试策略也不同。

🟡 Medium · 删除没有逐方案版本守卫，离线设备可把已删方案写回 — apps/gooseforum/app/http/controllers/pk/plans.go:98

DELETE /api/pk/plans 直接按 user_id 删整行，服务端没有 baseRevision>0 对应方案已不存在的语义。长期离线的旧设备以过期 base 上传时会先 409，随后进入分歧合并路径，其本地仍持有的已删方案会被并入云端方案数组写回（表现为恢复副本），与 issue 验收项「已在另一设备删除的方案不会被长期离线设备重新复活」相冲突。

🔵 Low · 目标模型（per-plan 整数 revision）在代码与迁移中尚不存在 — apps/gooseforum/app/migration/schedule_snapshot_schema_test.go:32

pk 模型与迁移测试只覆盖 pk_schedule_snapshot 单行表的存在与列集合，没有任何 revision 字段或 per-plan 表；确认本 issue 是未实现的架构改造而非回归，实施需要新增表、PG 迁移测试与契约变更，不能靠单点补丁完成。

---

Next step

• 先落定 majorSelected 的归属与冲突草稿存储/配额的产品决策再改契约：这决定 OpenAPI schema 是新增 preference 资源还是直接删字段，事后返工成本高于先决策。
• 迁移需在 PostgreSQL 上预演：用 app/migration 的 PG 测试验证旧 snapshot 拆分为 per-plan rows 的幂等与无损（含既有「[本地自动恢复]」方案按普通方案迁移、不自动删除），dev 实例每次部署会同步主库快照，回滚窗口有限。
• 保留旧整包写入路径一段时间并明确优先级：已安装的 Mobile 客户端仍会发整包 PUT，需确定版本协商或双路径兼容策略，避免新旧写入互相覆盖。
• 取消 10s 心跳前确认 dirty/lifecycle 触发覆盖页面聚焦与 online 事件，否则容易出现「改了但长时间不上传」，相对 feat: 排课器 web 端云端同步体验优化——默认自动上传、网络恢复自动补传、移除不一致弹窗 #573 的自动补传是可见回退。
• 契约与两端状态机同 PR 落地：openapi.yaml → 生成 TS → fixtures/route-coverage 门禁 → mobile Dart 镜像（生成仍是 Planned，需手工同步），并同步更新 docs/product/current-state.md 的状态词；若确认了方案取舍，按 docs/decisions/README.md 的判据补 MADR。

Maintainer decision: 拆分后 majorSelected（学期/年级/专业）应继续跨设备同步，还是降级为设备本地状态？这决定契约是新增 preference 资源还是直接删字段。

• 本地化：最彻底地消除 UI 状态冲突，代价是换设备后需重新选择专业/年级
• 拆为独立轻量 preference 资源（独立 revision）：保留跨设备便利，代价是多一条契约、存储与状态机分支
• 继续随方案同步：迁移成本最低，但与本 issue 第 6 条「UI 状态不参与方案 CAS」目标冲突

Recommendation: 按 issue 建议先把 activePlanId/weekView 本地化，majorSelected 走独立 preference（单独 revision、不参与 plan CAS）；若想压缩第一阶段范围，可先本地化并在契约上预留偏好资源位，避免把它继续留在整包版本里。

• 先回答 decisionNote 中的 majorSelected 归属问题并确定冲突草稿/归档的存储与配额口径，必要时按 docs/decisions/README.md 的判据补一份 MADR 或 spec，再动契约。
• 设计并实现按 (user_id, plan_id) 的方案存储与整数 revision 条件写：baseRevision=0 仅用于新建、过期返回附带当前 remote plan+revision 的 409、baseRevision>0 命中不存在返回 409/410，planId 不复用。
• 实现旧快照 → per-plan rows 的一次性或惰性拆分迁移，保证幂等、方案内容与用户归属无损，并补 PostgreSQL 迁移测试（YOURTJ_TEST_PG_URL 路径）。
• 更新 packages/api-contract（paths/schemas/fixtures）与生成 TS 类型、mobile Dart 镜像、web TS types，保持 route-coverage 门禁通过，旧整包写入在约定兼容期内保留。
• 统一 Web 与 Mobile 同步状态机（首次同步、dirty、409 局部冲突、网络恢复、远端删除、账号切换归属提示），并按最终方案更新 docs/product/current-state.md 的状态词。
• 补并发与迁移回归测试：不同方案并发保存互不 409、同一方案不同课程/事件可三方合并、恢复副本不进入正常方案集合、已删方案不被复活；本地跑 go test ./...、pnpm typecheck && pnpm test && pnpm build、node scripts/run-gates.mjs。

Things to watch

• 迁移期新旧写入路径并存：老客户端仍整包 PUT，若 per-plan 写入与旧快照路径没有明确的优先级/兼容规则，会出现双方互相覆盖或数据分叉。
• 取消 10s 心跳后若 dirty/lifecycle 触发漏掉页面聚焦或联网事件，编辑可能长时间停在本机不上传，相对 feat: 排课器 web 端云端同步体验优化——默认自动上传、网络恢复自动补传、移除不一致弹窗 #573 的自动补传是可感知的体验回退。
• mobile Dart 契约镜像仍是手工同步（生成标注为 Planned），后端契约一旦改动，Web TS 与 Mobile 类型容易漂移，需在同 PR 逐项对齐。
• 冲突草稿/归档不计入 MAX_PLANS 若没有独立上限，会变成无界存储，同时要兼顾服务端 1MB/请求体积与账号注销时的删除语义。
• dev 实例每次部署同步主库快照，迁移若不可逆或有损，线上回滚窗口很小，需要先做可重放的拆分迁移演练。

Verification

🔎 Evidence supports the conclusion. Confirmed in source; not reproduced in a live run.

No host validation commands were run for this report.

Source evidence (17)

• apps/gooseforum/app/models/forum/pk/schedule_snapshot.go:94 — ScheduleSnapshotEntity 以 user_id uniqueIndex 单行存储 plans/active_plan_id/major_selected/week_view 四字段，updated_at 为唯一同步时钟，无逐方案 revision 列。

• apps/gooseforum/app/models/forum/pk/schedule_snapshot_rep.go:111 — CompareAndSwapScheduleSnapshot 用 Where("user_id = ? AND updated_at = ?", ...) 做条件写，版本号是 RFC3339Nano 时间戳而非整数 revision，RrowsAffected==0 时返回 ErrScheduleSnapshotConflict。

• apps/gooseforum/app/models/forum/pk/schedule_snapshot_rep.go:89 — base=="" 走 OnConflict{DoNothing} 的 create-only 语义，非空 base 走时间戳精确匹配；不存在「base 指向已删除 plan」的判定分支，删除后写入会被当作新行创建。

• apps/gooseforum/app/http/controllers/pk/plans.go:37 — PutPlansReq 只带 BaseUpdatedAt *string 与整包四字段；BaseUpdatedAt 省略时执行无条件 UpsertScheduleSnapshot，契约描述也写明 omission preserves unconditional replacement。

• apps/gooseforum/app/http/controllers/pk/plans.go:87 — CAS 冲突返回 Code 409 且 Data 为空对象，不附带当前 remote 方案与 revision，客户端必须再发一次 GET（issue 第 2 条要求冲突响应尽量直接带回远程方案）。

• apps/gooseforum/resource/src/site/composables/useScheduleSync.ts:101 — PK_SYNC_AUTOSAVE_MS = 10000，干净状态每 10s 心跳整包重传；issue 第 8 条要求取消该心跳，改为 dirty/lifecycle 驱动。

• apps/gooseforum/resource/src/site/composables/useScheduleSync.ts:203 — mergeAndUpload 在提交前检查 mergedPlans.length > MAX_PLANS 或 >1MB 即置 mergeBlocked 返回 blocked，说明恢复副本策略确有容量上限阻塞路径。

• apps/gooseforum/resource/src/site/composables/useScheduleSync.ts:209 — 合并与普通上传的 payload 都包含 activePlanId/majorSelected/weekView，UI 状态随内容一起推进同一个 baseUpdatedAt 版本。

• apps/gooseforum/resource/src/site/composables/useScheduleStore.ts:93 — MAX_PLANS = 10，且新增/复制方案在该上限处直接返回 null；恢复克隆不受独立配额保护。

• apps/gooseforum/resource/src/site/composables/useScheduleStore.ts:194 — clonePlansAsAutoRestore 按 planContentKey 去重后把本地方案追加为恢复方案，是「正常方案列表中的自动恢复副本」这一被 issue 要求取消的常规冲突策略。

• apps/gooseforum/resource/src/site/composables/useScheduleStore.ts:1004 — solidify 持久化 plans/activePlanId/weekView 并在 changed 时调用 solidifyHook，即切换周视图或激活方案会触发同步钩子标脏。

• apps/mobile/packages/forum_app/lib/src/schedule/schedule_sync.dart:136 — Mobile 在 isDirty || store.syncedAt != remote.updatedAt 时直接设置为 conflict 并停下等待用户选择，与 Web 的自动合并策略不一致。

• apps/mobile/packages/forum_app/lib/src/pages/schedule/schedule_page.dart:146 — 冲突弹窗注释明确「使用云端」整包采用 /「保留本地」立即上行，正是 issue 要移除的整包二选一交互。

• packages/api-contract/components/schemas.yaml:3643 — PkPlansPutRequest/PkPlansSnapshotData 把 plans/activePlanId/majorSelected/weekView 定义为整体替换的单个快照，与 per-plan revision 契约不兼容，改造必须同 PR 更新契约与生成产物。

• docs/product/current-state.md:74 — 文档把「排课方案云同步」标为 Current 并记录整包快照 + 恢复方案克隆 + 10s 心跳 + 移动端弹窗语义，本改造落地后必须同步更新状态词与描述。

• docs/decisions/README.md:58 — 决策日志要求「在多个有意义方案间取舍且未来可能被重新审视」时建 MADR；同步粒度、majorSelected 归属与冲突草稿归档属此类，需补记录或明确 spec。

• apps/gooseforum/app/migration/schedule_snapshot_schema_test.go:32 — 迁移测试仅断言 pk_schedule_snapshot 表存在（含升级路径），没有任何 per-plan 表或 revision 列断言，佐证目标模型尚未实现。

---

Discussion and CI reflect the snapshot read for this review. Current checks and approval are verified separately before merging.

_{🧹 Oryn Mini · Source 7a56446 · Built with Synergy core}