---
id: T-615
title: 自动升级发布契约与可验证发布清单
phase: 8
deps: [T-540, T-544]
status: TODO
created: 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或用户数据写入清单和发布元数据。

## 执行记录

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