docs: 归档任务 #92

docs/task/92-client-windows打包与发布清单基础.md

@@ -0,0 +1,76 @@
+# 92 Client：建立 Windows 打包与发布清单基础
+
+- 类型：需求
+- 父级大工单：#1
+- 所属 MVP / 版本：#2 / Client 可运行任务闭环（MVP）
+- 状态：已完成
+- 日期：2026-08-10
+- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/92
+
+## 背景与目标
+
+Client 原来只能从源码运行，没有可重复执行的 Windows 打包脚本、统一版本来源和
+可校验的发布清单。本任务建立 one-dir 便携发布基础，并保证更新程序文件时不会
+覆盖根目录 `data/`。
+
+## 最终方案
+
+- 使用 Python 3.10、PyQt5 和 PyInstaller 6.21.0 构建。
+- 根目录 `Launcher.exe` 只启动 `app/CMAutoBuy.exe`，不联网、不下载、不更新文件。
+- 主程序使用 PyInstaller one-dir，依赖放在 `app/dependencies/`。
+- SQLite 等可写数据始终放在根目录 `data/`，更新包只包含 `app/`。
+- 构建生成完整便携包、更新包和 `autobuy——manifest.json`；清单保存版本、文件名、
+  字节大小和 SHA256。
+- 原计划把 Python 辅助代码放进 `client/packaging`，实际发现会遮蔽 PyInstaller
+  依赖的第三方 `packaging` 包，因此 PowerShell 脚本保留在 `packaging/`，Python
+  辅助代码改放 `build_tools/`。
+
+## 改了哪些
+
+- `.gitignore`：忽略独立打包环境和发布产物。
+- `client/build_client.bat`：增加可双击的简单构建入口。
+- `client/packaging/build.ps1`：安装固定依赖、打包、检查关键资源并组装发布物。
+- `client/packaging/requirements-build.txt`：固定 PyInstaller 6.21.0。
+- `client/build_tools/launcher.py`：实现只负责启动主程序的轻量启动器。
+- `client/build_tools/release_manifest.py`：生成发布清单和 SHA256。
+- `client/src/version.py`：增加单一软件版本来源，初始版本为 `0.1.0`。
+- `client/src/db.py`：打包后把数据目录解析到 `Launcher.exe` 同级的 `data/`。
+- `client/test/test_packaging.py`：覆盖启动路径、数据目录和清单校验。
+- `docs/client/`：同步更新上手、打包目录、数据路径和发布门禁。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| `client/build_client.bat` 完整构建并正确返回结果 | 通过 |
+| 生成 `Launcher.exe + app/ + data/` one-dir 便携目录 | 通过 |
+| 生成完整便携包和不含 `data/` 的更新包 | 通过 |
+| 清单精确命名为 `autobuy——manifest.json` | 通过 |
+| 清单版本、文件名、大小和 SHA256 与压缩包一致 | 通过 |
+| 打包程序把数据库写到根目录 `data/client.db` | 通过 |
+| Qt 平台插件、Fluent 资源和 `adbutils/binaries/adb.exe` 已收集 | 通过 |
+| 未新增联网更新、凭据落盘或真实下单行为 | 通过 |
+
+## 测试
+
+- 执行的命令：
+  - `C:/Python310/python.exe -m py_compile buyer_main.py src/version.py src/db.py build_tools/launcher.py build_tools/release_manifest.py test/test_packaging.py`
+  - `$env:QT_QPA_PLATFORM='offscreen'; C:/Python310/python.exe -m pytest test -q`
+  - `client/build_client.bat`
+  - 使用 Python `hashlib` 和 `zipfile` 校验清单、压缩包内容及更新包不含 `data/`。
+  - 解压完整便携包，以 `QT_QPA_PLATFORM=offscreen` 启动 `Launcher.exe`，检查主程序
+    进程和数据库实际位置。
+- 结果：Client 全量测试 `239 passed`；完整构建成功；发布清单校验成功；打包主程序
+  启动成功；数据库生成在根目录 `data/client.db`，没有生成 `app/data/client.db`。
+- **没验证到的部分**：尚未在另一台完全未安装 Python 的 Windows 机器上验证；尚未
+  验证杀毒软件误报和代码签名；尚未用打包产物连接真实 USB/Wi-Fi Android 设备；
+  PyInstaller 的发布许可仍需项目负责人按发布门禁最终确认。
+
+## 遗留问题
+
+- 联网检查、下载、安全解压、签名验证和下次启动替换 `app/` 不属于本任务，需要
+  单独创建更新功能工单。
+
+## 相关提交
+
+- `99252ae` 增加 Client Windows 打包基础