cmshoppe/docs/tasks/T-624.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-624	自动升级适配 cmhub 最小发布接口字段	8	T-623	DONE	2026-07-13

问题 / 背景

cmhub GET /api/v1/client/releases/latest?platform=windows 的正式响应只提供 platform 和 release 内的 version、download_url、sha256、release_notes、force_update、size_bytes、published_at。客户端当前还把 package_format、updater_protocol、min_updater_protocol 当作服务端自动安装必填字段，导致线上已经提供 hash 和大小后仍被阻断。

方案

1. 版本接口只读取并依赖 cmhub 正式响应中已有的发布字段，不要求服务端增加包格式或更新器协议字段。
2. app/update_installer.py 从接口结果构造安装元数据时，package_format 固定使用客户端 PACKAGE_FORMAT，updater_protocol 固定使用客户端 UPDATER_PROTOCOL，最低协议使用当前兼容默认值。
3. 不降低安装包验证：下载后仍要求包内 package-manifest.json 的格式、协议、版本、文件大小和 SHA-256 与客户端支持范围一致；不兼容的包仍在替换程序前拒绝。
4. 同步版本接口、打包和架构文档，明确服务端字段与包内 manifest 字段的职责边界。

验收要点

• 与线上示例完全同形、缺少 package_format 和协议字段的强制更新响应可以进入自动下载流程。
• 缺少或错误的 version、download_url、sha256、size_bytes 仍被阻断；force_update 继续决定是否强制。
• 包内 manifest 的包格式或更新器协议不兼容时仍拒绝安装。
• HTTP 外链继续沿用 T-623 的公网地址与完整性校验。

测试要求

• 增加 cmhub 正式 JSON 结构的解析、强制门禁和内部安装元数据默认值测试。
• 运行 python -m ruff check app tests main.py、python -m compileall app main.py、python -m unittest discover -s tests 和 git diff --check。

边界（不改什么）

• 不修改 cmhub 服务端，不要求新增接口字段。
• 不移除大小、整包 SHA-256、安全解压、manifest、事务替换、健康确认或回滚。
• 不修改业务 Tab、CDP、AI、Excel、SQLite 业务数据或蝦皮更新流程。

执行记录

• 2026-07-13：metadata_from_update_info() 不再要求版本接口提供包格式和更新器协议，统一使用客户端内置 PACKAGE_FORMAT / UPDATER_PROTOCOL；包内manifest格式、协议、版本和逐文件hash校验保持不变。
• 2026-07-13：新增与 cmhub 线上响应完全同形的解析、强制门禁、内部安装元数据和 GUI HTTP 提示回归测试，并同步版本接口、打包和架构文档。
• 2026-07-13：使用线上接口实测通过：旧版本 0.1.5 能识别 0.1.6 强制更新，读取 size_bytes=53318076，并补齐内部包格式 cmshopee-portable-v1、协议 1。
• 2026-07-13：为隔离工作区既有提示词/版本号改动，在独立干净 worktree 验证通过：Ruff、Python 3.10 compileall、完整 unittest 438 项及 git diff --check 全绿；未执行完整安装包替换和重启。