---
id: T-625
title: 发布元数据文件名增加应用版本号
phase: 8
deps: [T-624]
status: DONE
created: 2026-07-13
---

## 问题 / 背景

打包脚本当前固定生成 `release/release-metadata.json`。连续构建多个版本时，新文件会覆盖旧文件，运营也无法仅从文件名判断它对应哪个安装包，容易把旧 hash 或大小录入 cmhub 发布接口。

要求发布元数据文件名与应用版本绑定。例如 `APP_VERSION=0.1.6` 时生成 `release-metadata0.1.6.json`。

## 方案

1. 修改 `scripts/build_exe.ps1`，从已经读取的 `$appVersion` 生成 `$releaseMetadata = Join-Path $releaseRoot "release-metadata${appVersion}.json"`；版本来源仍只有 `app/version.py`。
2. 同版本重新打包前删除并重建对应的版本化元数据文件；保留 `release/` 下其他版本的 `release-metadata<版本>.json`，便于和历史 zip 一一对应。
3. 构建时清理历史无版本文件 `release/release-metadata.json`，避免运营误把旧文件当成本轮元数据；不得用通配符批量删除其他版本文件。
4. `app.release_manifest metadata --output` 继续接收脚本传入的完整路径，JSON 内容、zip SHA-256、`size_bytes` 和 `release.version` 生成逻辑不变；元数据仍不放进便携 zip。
5. 同步 `docs/packaging.md`、`docs/update-check.md` 和 `docs/04-architecture.md` 中的文件树、发版步骤及唯一版本源说明。

## 验收要点

- `APP_VERSION=0.1.6` 时，构建产物包含 `release/release-metadata0.1.6.json`，不再生成无版本的 `release-metadata.json`。
- JSON 中 `release.version` 为 `0.1.6`，`download_filename`、`sha256` 和 `size_bytes` 与 `蝦皮圈優化助手0.1.6.zip` 一致。
- 同版本重打会覆盖 `release-metadata0.1.6.json`；`release-metadata0.1.5.json` 等其他版本文件不会被删除或覆盖。
- 旧的 `release-metadata.json` 会被安全清理；清理目标经过现有 `Assert-InProject` 边界校验。
- 便携 zip 内不包含任何 `release-metadata*.json`，自动升级客户端运行逻辑不受影响。

## 测试要求

- 更新 `tests/test_packaging.py`，断言构建脚本使用 `release-metadata${appVersion}.json`，不再把无版本文件作为当前输出，并且只清理明确的旧文件名和当前版本文件。
- 使用临时 zip 调用 `app.release_manifest metadata`，验证版本化输出文件名、JSON 版本、大小和 SHA-256。
- 运行 `python -m ruff check app tests main.py`、`python -m compileall app main.py`、`python -m unittest discover -s tests` 和 `git diff --check`。
- 条件允许时运行一次 `scripts/build_exe.ps1`，核对真实 release 目录；未运行必须在执行记录中说明。

## 边界（不改什么）

- 不修改 `APP_VERSION`、发布包目录名或 `蝦皮圈優化助手<版本>.zip` 文件名。
- 不改变发布元数据 JSON schema、cmhub 版本接口字段或客户端自动升级校验。
- 不删除其他版本发布目录、zip 或版本化元数据，不读取或打包 `data/`。
- 不修改业务 Tab、CDP、AI、Excel、SQLite 业务数据或蝦皮更新流程。

## 执行记录

- 2026-07-13：构建脚本改为生成 `release-metadata${appVersion}.json`，同版本重打覆盖当前文件，保留其他版本化元数据，并只额外清理历史无版本 `release-metadata.json`。
- 2026-07-13：补齐构建脚本静态约束和版本化输出文件测试，同步架构、版本接口与打包文档；发布元数据 JSON schema 和自动升级运行逻辑未改变。
- 2026-07-13：独立干净 worktree 验证通过：Ruff、Python 3.10 compileall、完整 unittest 439 项及 `git diff --check` 全绿。
- 2026-07-13：使用当前工作区 `APP_VERSION=0.1.5` 完成真实 Windows 打包，生成 `release-metadata0.1.5.json`；JSON 版本/zip文件名正确，zip大小 `53295265` 与 SHA-256 `187638dd14875d7039db4b16c570f66b1878909d850f3c8b69d50941706866bc` 均与实物一致。历史 `release-metadata0.1.6.json` 保留，旧无版本文件不存在，zip 内不含元数据文件。