docs: 归档任务 #102

docs/task/102-client发布产物命名规范.md

@@ -0,0 +1,77 @@
+# 102 Client：统一发布产物命名并生成固定清单
+
+- 类型：需求
+- 父级大工单：#1
+- 所属 MVP / 版本：MVP 后续 / 发布规范
+- 状态：已完成
+- 日期：2026-08-10
+- Gitea 工单：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/102>
+
+## 背景与目标
+
+原发布文件名同时使用连字符、英文后缀和 Unicode 破折号，不便于人工识别，也缺少
+稳定的在线清单入口。本任务统一 0.2.2 发布产物名称，同时兼容已保存旧默认清单地址
+的 Client。
+
+## 最终方案
+
+- 更新包使用 `CMAutoBuy_<版本>.zip`，完整便携包使用
+  `自动采集采购工具_<版本>.zip`。
+- 复制版本化便携包为 `自动采集采购工具.zip`，两份文件逐字节相同。
+- 固定清单使用 `autobuy_manifest.json`，并复制出内容相同的
+  `autobuy_manifest_<版本>.json` 供归档。
+- 清单只引用带版本号的 ZIP，并记录实际文件大小和 SHA256。
+- Client 默认读取固定清单；本地地址完全等于旧默认值时自动迁移，自定义地址不改。
+- 构建验证时发现 Windows PowerShell 5 会按系统代码页读取无 BOM 脚本中的中文，
+  因此中文便携包名称改用 Unicode 码点构造。这是对原实现方案的必要补充，发布名称
+  和用户确认的方案没有变化。
+
+## 改了哪些
+
+- `client/packaging/build.ps1`：生成新的 ZIP、固定清单、版本化清单和便携包别名。
+- `client/build_tools/release_manifest.py`：更新固定清单名并校验版本化清单名。
+- `client/src/update_service.py`、`client/src/update_ui_event.py`：更新默认清单地址并迁移
+  旧默认值。
+- `client/src/version.py`：版本升级为 0.2.2。
+- `client/src/settings_ui.py`：更新清单地址占位示例。
+- `client/test/test_packaging.py`、`client/test/test_update_service.py`、
+  `client/test/test_update_ui_event.py`：补充命名和配置迁移测试。
+- `docs/client/00-getting-started.md`、`docs/client/01-requirements.md`、
+  `docs/client/06-quality-security.md`：同步发布文件说明和验收门禁。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 更新包为 `CMAutoBuy_0.2.2.zip`，且只包含 `app/` | 通过 |
+| 生成两个约定的便携包，且字节和 SHA256 相同 | 通过 |
+| 生成固定与版本化清单，且内容相同 | 通过 |
+| 清单内文件名、大小和 SHA256 与版本化 ZIP 一致 | 通过 |
+| Client 默认读取固定清单 | 通过 |
+| 旧默认地址自动迁移，自定义地址不变 | 通过 |
+| 在线更新文件名使用 ASCII，人工便携包使用中文 | 通过 |
+| 自动测试、实际构建和打包启动冒烟通过 | 通过 |
+| 未改变 Admin 接口、采购流程和真实下单默认值 | 通过 |
+
+## 测试
+
+- 执行的命令：
+  - `C:/Python310/python.exe -m pytest test/test_packaging.py test/test_update_service.py test/test_update_ui_event.py -q --disable-warnings`
+  - `C:/Python310/python.exe -m pytest -q --disable-warnings`
+  - `C:/Python310/python.exe -m pytest test/test_packaging.py -q --disable-warnings`
+  - `.\build_client.bat`
+  - 使用 Python 校验发布文件集合、别名字节、清单大小与 SHA256、ZIP 内部结构。
+  - 离屏启动 `release/CMAutoBuy-0.2.2/Launcher.exe`，核对进程及文件版本。
+- 结果：针对性测试 31 项、全量测试 267 项、打包测试复跑 10 项全部通过；实际构建
+  成功，Launcher 启动版本为 0.2.2。
+- **没验证到的部分**：未把 0.2.2 产物上传真实发布服务器；未从已保存旧默认地址的
+  旧版 Client 完成一次真实在线下载、替换和回退流程。
+
+## 遗留问题
+
+服务器发布 0.2.2 时，应先上传新 ZIP 与 `autobuy_manifest.json`，并暂时保留旧的
+`autobuy——manifest.json`，避免尚未升级的旧 Client 无法发现新版本。
+
+## 相关提交
+
+- `240626f` feat: 统一 Client 发布产物命名 (#102)