From e79ec00bf66746761c6df9b74d92e5cbc3835f2d Mon Sep 17 00:00:00 2001
From: chengma <chengma2027@gmail.com>
Date: Mon, 13 Jul 2026 17:30:58 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=90=BD=20T-625=20=E5=8F=91=E5=B8=83?=
 =?UTF-8?q?=E5=85=83=E6=95=B0=E6=8D=AE=E7=89=88=E6=9C=AC=E5=8C=96=E5=91=BD?=
 =?UTF-8?q?=E5=90=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/tasks/T-625.md | 48 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 docs/tasks/T-625.md

diff --git a/docs/tasks/T-625.md b/docs/tasks/T-625.md
new file mode 100644
index 0000000..adf1624
--- /dev/null
+++ b/docs/tasks/T-625.md
@@ -0,0 +1,48 @@
+---
+id: T-625
+title: 发布元数据文件名增加应用版本号
+phase: 8
+deps: [T-624]
+status: TODO
+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 业务数据或蝦皮更新流程。
+
+## 执行记录
+
+- 尚未执行。