---
id: T-559
title: 版本检查响应契约 + 强制升级约定（force_update）固化进仓库
phase: 7
deps: [T-544]
status: DONE
created: 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` 源码确认一致；未跑单测（无代码改动）。