diff --git a/docs/task/102-client发布产物命名规范.md b/docs/task/102-client发布产物命名规范.md new file mode 100644 index 0000000..229a658 --- /dev/null +++ b/docs/task/102-client发布产物命名规范.md @@ -0,0 +1,77 @@ +# 102 Client:统一发布产物命名并生成固定清单 + +- 类型:需求 +- 父级大工单:#1 +- 所属 MVP / 版本:MVP 后续 / 发布规范 +- 状态:已完成 +- 日期:2026-08-10 +- Gitea 工单: + +## 背景与目标 + +原发布文件名同时使用连字符、英文后缀和 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)