cmshoppe/docs/tasks/T-559.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-559	版本检查响应契约 + 强制升级约定（force_update）固化进仓库	7	T-544	DONE	2026-07-08

问题 / 背景

启动时客户端请求 https://cm.833729.com/api/v1/client/releases/latest?platform=windows 检查版本（app/update_check.py）。实测本地 0.1.0、线上 0.1.1 却不弹升级窗。核实原因：服务端响应没有 force_update、也没有 min_supported_version，客户端 is_forced_update() 判为"非强制"；而当前客户端只对强制更新弹窗（_run_startup_update_gate 仅处理 forced 分支），非强制既不阻断也不提示。

采用方案 A：发新版要强制时，服务端返回 force_update: true。客户端逻辑 T-544 已实现、无需改码——本任务把"客户端读哪些字段 + 强制规则 + 发版约定"固化成仓库文档，避免服务端格式漂移、并作为发强制版的操作手册。

方案

新增文档 docs/update-check.md（并在 docs/README.md 索引里加一行），内容：

• 接口：GET {APP_UPDATE_CHECK_URL}（当前 https://cm.833729.com/api/v1/client/releases/latest?platform=windows，硬编码于 app/version.py）。
• 客户端读取的字段（update_check.parse_update_info，顶层 payload 或 release 子对象里都认）：
  • version / latest_version（版本号；release.version 或顶层 latest_version，二选一必须有）
  • force_update（bool；true/1/yes 系列都识别）
  • min_supported_version（低于它的一律强制）
  • download_url、sha256（第一版不校验，可空）、release_notes/message（升级说明）
• 强制规则（is_forced_update）：force_update=true 且 本地 < latest_version → 强制；或 本地 < min_supported_version → 强制；两者都不满足 → 非强制（客户端当前不弹）。
• 发版约定：
  • 强制升到最新 → release.force_update: true（方案 A）。
  • 强制淘汰旧版 → min_supported_version 设为要淘汰之上的版本（方案 B）。
  • 不想强制 → 都不给（客户端当前不提示；若要温和可跳过提示，另立任务）。
• 示例响应（强制版，方案 A）：给出带 "force_update": true 的完整 JSON 样例。
• 失败放行：接口断网/超时/非法 JSON/缺字段 → 客户端记诊断日志放行、不阻断（写明，避免误以为坏了）。
• 服务端动作（本仓库外）：cm.833729.com 的 releases/latest 返回里加 force_update: true。

验收要点

• docs/update-check.md 写清接口、客户端字段读取、强制规则、发版约定、强制版示例 JSON、失败放行行为。
• docs/README.md 索引新增该文档链接。
• 明确客户端无需改代码（T-544 已实现），可选项目在正文标注。
• 不含真实密钥/内部地址以外的敏感信息（接口 URL 属公开）。

边界（不改什么）

只加文档（docs/update-check.md + README 索引）。不改 app/update_check.py/app/version.py/启动流程等客户端代码（T-544 已够）；服务端返回 force_update 属本仓库外配置。

执行记录

• 2026-07-08：完成 T-559。
• 文档：新增 docs/update-check.md——接口/客户端字段读取（对照 app/update_check.py 的 parse_update_info/is_forced_update：version|latest_version、force_update、min_supported_version、download_url、sha256、release_notes|message，顶层或 release 里都认）/强制规则/客户端行为（T-544 已实现）/失败放行/发版约定（方案A force_update:true、方案B min_supported_version）/三份示例响应。docs/README.md 加索引一行。
• 未改客户端代码：app/update_check.py/app/version.py/启动流程按契约已实现（T-544）；服务端返回 force_update 属本仓库外配置。
• 验证：纯文档任务，字段逐条对照 app/update_check.py 源码确认一致；未跑单测（无代码改动）。