# 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 打包基础