49 lines
3.8 KiB
Markdown
49 lines
3.8 KiB
Markdown
---
|
||
id: T-615
|
||
title: 自动升级发布契约与可验证发布清单
|
||
phase: 8
|
||
deps: [T-540, T-544]
|
||
status: DONE
|
||
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或用户数据写入清单和发布元数据。
|
||
|
||
## 执行记录
|
||
|
||
- 2026-07-13：新增 `app/release_manifest.py`，统一生成程序文件清单与zip发布元数据；构建脚本在压缩前生成manifest、压缩后生成准确hash和大小。
|
||
- 2026-07-13：发布目录仅允许程序根项目，拒绝 `data/`、`.cmshopee-update/`、未知根项目、版本不一致、重复路径和符号链接；同步更新发布契约、打包文档与架构边界。
|
||
- 2026-07-13：干净worktree验证通过：`python -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`py -3.10 -m unittest discover -s tests`（394项）、`git diff --check`。
|