cmbot/docs/09-packaging-release.md

# 打包发布设计

## 1. 文档定位

本文档定义第一阶段的本地打包和发布规则。当前阶段只考虑将软件打包为可在 Windows 电脑上运行的桌面程序。

暂不包含：

- 局域网分发。
- 自动更新。
- 多版本启动器。
- 强制升级策略。
- 远程版本策略管理。

这些能力后续需要时再单独补充设计文档。

## 2. 打包目标

- 将 PySide6 桌面程序打包为 Windows 可运行程序。
- 目标电脑无需预装 Python 环境。
- 打包产物应包含运行所需依赖、资源文件、默认配置和模板。
- 打包后的程序应能在 Windows 10 / Windows 11 上启动。
- 打包结构应方便排查 Qt 插件、资源、配置和日志问题。

## 3. 推荐打包方式

使用 PyInstaller。

第一阶段推荐使用 `onedir` 模式：

```bash
pyinstaller --onedir --windowed src/main.py
```

原因：

- PySide6 / Qt 依赖文件较多，`onedir` 更容易排查问题。
- 启动速度通常优于 `onefile`。
- 资源文件、配置文件、模板文件更容易随程序目录管理。
- 后续如需局域网分发或增量替换，目录模式更合适。

不推荐第一阶段使用 `onefile`：

- 启动时需要解压临时文件。
- Qt 插件问题更难排查。
- 日志、模板和配置路径更容易混乱。

## 4. Python 与依赖要求

必须遵守：

- Python 版本：Python 3.7。
- GUI 框架：PySide6。
- 推荐 PySide6 版本：`PySide6==6.5.3`。
- 图片处理：Pillow。
- 打包工具：PyInstaller。

依赖版本应在项目根目录的 `requirements.txt` 中锁定。

打包前必须确认依赖可以在 Python 3.7 环境中安装。

## 5. 发布目录结构

推荐打包后的发布目录：

```text
CMBot/
  CMBot.exe
  _internal/
  config/
    app_config.json
    templates.json
  resources/
    icons/
    styles/
  logs/
  output/
  README.txt
```

说明：

- `CMBot.exe`：主程序入口。
- `_internal/`：PyInstaller 依赖目录。
- `config/`：默认配置和模板配置。
- `resources/`：图标、样式等资源。
- `logs/`：运行日志目录，程序启动时可自动创建。
- `output/`：默认输出目录，可自动创建。
- `README.txt`：给用户的简短使用说明。

## 6. 可写目录规则

程序运行时可能写入：

- 日志文件。
- 用户配置。
- 自定义模板。
- 导出图片。

规则：

- 程序必须确保 `logs/` 目录存在。
- 程序必须确保默认 `output/` 目录存在。
- 配置和模板写入前必须确认目录可写。
- 如果安装目录不可写，应提示用户选择可写目录，或后续改用用户数据目录。

第一阶段可以默认将配置、模板、日志和输出放在程序目录下，但必须处理目录不可写的错误。

## 7. 资源文件打包

需要随程序打包的资源：

- 应用图标。
- UI 样式文件。
- 默认模板文件。
- 默认配置文件。

规则：

- 资源文件路径不能写死为开发机绝对路径。
- 程序需要通过统一的资源路径函数获取资源。
- 打包环境和开发环境应使用同一套路径访问规则。

建议提供路径辅助函数：

```text
get_app_dir()
get_resource_path(relative_path)
get_config_path(relative_path)
get_log_dir()
get_output_dir()
```

## 8. PyInstaller 配置

第一阶段可以先使用命令行打包；项目稳定后应维护 `.spec` 文件。

建议命令：

```bash
pyinstaller ^
  --onedir ^
  --windowed ^
  --name CMBot ^
  --add-data "resources;resources" ^
  --add-data "config;config" ^
  src/main.py
```

注意：

- Windows 下 `--add-data` 的源路径和目标路径使用分号 `;` 分隔。
- 如果在 PowerShell 中执行，换行符和引号需要按实际环境调整。
- 打包命令应后续固化到脚本中，例如 `scripts/build.ps1`。

## 9. 版本号规则

软件需要有明确版本号。

规则：

- 当前版本号必须显示在标题栏软件名称右侧。
- 版本号应从统一位置读取，不应在多个 UI 文件中硬编码。
- 打包产物的版本号、窗口显示版本号和发布目录版本号应一致。

建议维护：

```text
src/version.py
```

示例：

```python
APP_NAME = "自动合成印花服饰效果图工具"
APP_VERSION = "1.0.0"
```

发布目录建议带版本号：

```text
CMBot-1.0.0/
```

## 10. 打包前检查

打包前必须检查：

- Python 版本是否为 3.7。
- 依赖是否安装成功。
- 程序是否可以在开发环境启动。
- 默认配置文件是否存在。
- 默认模板文件是否存在。
- 资源文件路径是否正确。
- 应用版本号是否正确。

建议命令：

```bash
python --version
pip freeze
python src/main.py
```

## 11. 打包后验证

打包后必须验证：

- 双击 `CMBot.exe` 可以启动。
- 标题栏显示正确版本号。
- 可以打开衣服图片文件夹。
- 可以打开印花图片文件夹。
- 可以显示预览区。
- 可以拖动、缩放、旋转印花。
- 可以导出当前单张图片。
- 可以生成日志文件。
- 程序关闭后再次启动正常。

若测试机器没有 Python 环境，应优先在该机器上验证。

## 12. 发布产物

第一阶段发布产物建议为压缩包：

```text
CMBot-1.0.0.zip
```

压缩包内包含：

```text
CMBot-1.0.0/
  CMBot.exe
  _internal/
  config/
  resources/
  README.txt
```

不应包含：

- 源代码。
- 测试文件。
- 开发环境缓存。
- 临时输出图片。
- 本机私人配置。
- 打包中间目录。

## 13. 暂不做

第一阶段不做：

- 局域网共享目录发布。
- 自动检查新版本。
- 自动下载更新。
- 多版本共存启动器。
- 按电脑名控制版本。
- 安装程序。
- Windows 注册表写入。
- 开机自启动。

如果后续要增加这些能力，应新增或扩展发布分发文档，不能直接混入当前第一阶段打包规则。