cmshoppe/docs/tasks/T-615.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-615	自动升级发布契约与可验证发布清单	8	T-540 T-544	TODO	2026-07-13

问题 / 背景

当前 T-544 版本接口只够支持“打开浏览器下载”：客户端虽然读取 sha256，但不校验，服务端也可能返回空值；发布包没有机器可验证的文件清单、包大小和更新器协议。自动下载并替换程序前，必须先让服务端元数据、zip内容和本地版本源形成一致且可自动验证的发布契约。

本任务是自动升级的发布基础，不下载、不安装、不替换用户程序。

方案

1. 扩展 docs/update-check.md 的服务端契约。自动安装版本必须提供：version、force_update/min_supported_version、HTTPS download_url、64位十六进制 sha256、size_bytes、package_format=cmshopee-portable-v1、updater_protocol 和中文发布说明。保留顶层与 release 子对象兼容读取，但自动安装字段必须来自同一 release。
2. 新增发布清单生成逻辑，构建 package-manifest.json，至少包含包格式、应用版本、入口文件、更新器协议、允许替换的根项目和程序文件清单。每个文件记录规范化相对路径、字节数和 SHA-256；清单自身不递归列入自身。
3. 修改 scripts/build_exe.ps1：组装 release 目录后生成清单，再压缩 zip；压缩完成后计算整个 zip 的 SHA-256 和准确字节数，生成与服务端录入字段一致的 release-metadata.json。发布人员不得手工估算 hash 或大小。
4. 清单只允许程序根项目，例如 cmshopee.exe、_internal/、version.txt、README.txt、package-manifest.json 和后续的 cmshopee-updater.exe；明确排除 data/ 与 .cmshopee-update/。
5. 预留 manifest_signature、signature_algorithm、min_updater_protocol 字段，第一阶段不因签名缺失阻断构建；数字签名与Authenticode单独迭代，不把未实现的签名宣称为已验证安全能力。
6. 同步 docs/packaging.md 和 docs/04-architecture.md，明确当前自动升级引导版本、服务端发布步骤和发布包边界。

验收要点

• 同一 APP_VERSION 同时出现在GUI版本源、version.txt、manifest、release目录和zip元数据中。
• release-metadata.json 中的zip大小与磁盘实际大小一致，SHA-256重新计算一致。
• manifest覆盖发布包内所有程序文件，不包含绝对路径、反斜线漂移、重复路径或任何 data/ 内容。
• 构建缺少入口、_internal/、版本文件或发现用户数据时失败，不生成可发布元数据。
• docs/update-check.md 能直接交给服务端实现，不再把空 sha256 视为可自动安装。

测试要求

• 更新 tests/test_packaging.py，覆盖manifest字段、文件清单、hash/大小、排除用户数据和版本一致性。
• 运行ruff、compileall、完整unittest、构建脚本静态/可控测试和 git diff --check。

边界（不改什么）

• 不实现客户端下载、解压、替换、重启或更新进度窗口。
• 不修改CDP、AI、Excel、SQLite业务表或蝦皮流程。
• 不把真实下载密钥、API Key、Cookie或用户数据写入清单和发布元数据。

执行记录

（完成后记录实现、验证命令与结果。）