TorqueWrench/frontend/打包说明.md

# wrench_gui.py 打包说明

## 一、环境准备

### 1. 安装 Python 依赖

确保已安装所有必需的 Python 包：

```bash
# 进入 frontend 目录
cd frontend

# 安装依赖
pip install -r requirements.txt

# 安装 PyInstaller（如果未安装）
pip install pyinstaller
```

### 2. 检查文件结构

确保以下文件存在：

```
TorqueWrench/
├── frontend/
│   ├── wrench_gui.py          # 主程序
│   ├── device_manager.py      # 设备管理模块
│   ├── wrench_gui.spec        # PyInstaller 配置文件
│   ├── build_exe.bat          # Windows 打包脚本
│   └── build_exe.sh           # Linux/Mac 打包脚本
├── wrench_controller.py       # 扳手控制模块（父目录）
└── config.json                # 配置文件（父目录）
```

---

## 二、打包步骤

### Windows 系统

1. **打开命令提示符或 PowerShell**

2. **进入 frontend 目录**
   ```cmd
   cd F:\PyPro\TorqueWrench\frontend
   ```

3. **执行打包脚本**
   ```cmd
   build_exe.bat
   ```

   或者手动执行：
   ```cmd
   pyinstaller wrench_gui.spec
   ```

### Linux/Mac 系统

1. **打开终端**

2. **进入 frontend 目录**
   ```bash
   cd /path/to/TorqueWrench/frontend
   ```

3. **给脚本添加执行权限**
   ```bash
   chmod +x build_exe.sh
   ```

4. **执行打包脚本**
   ```bash
   ./build_exe.sh
   ```

   或者手动执行：
   ```bash
   pyinstaller wrench_gui.spec
   ```

---

## 三、打包输出

打包完成后，会在 `frontend/dist/` 目录下生成可执行文件：

### Windows
- **位置**: `frontend/dist/wrench_gui/wrench_gui.exe`
- **大小**: 约 15-30 MB（取决于依赖）

### Linux/Mac
- **位置**: `frontend/dist/wrench_gui/wrench_gui`
- **大小**: 约 15-30 MB

---

## 四、运行打包后的程序

### 1. 准备配置文件

将 `config.json` 复制到可执行文件所在目录：

**Windows:**
```cmd
copy ..\config.json dist\wrench_gui\config.json
```

**Linux/Mac:**
```bash
cp ../config.json dist/wrench_gui/config.json
```

### 2. 启动后端服务

确保后端 API 服务已启动：

```bash
# 进入 backend 目录
cd ../backend

# 启动后端（Windows）
start_backend.bat

# 或启动后端（Linux/Mac）
./start_backend.sh
```

### 3. 运行可执行文件

**Windows:**
- 双击 `dist/wrench_gui/wrench_gui.exe`
- 或在命令行执行：
  ```cmd
  dist\wrench_gui\wrench_gui.exe
  ```

**Linux/Mac:**
```bash
./dist/wrench_gui/wrench_gui
```

---

## 五、常见问题

### 1. 打包失败：找不到模块

**问题**: `ModuleNotFoundError: No module named 'xxx'`

**解决**:
- 检查是否已安装所有依赖：`pip install -r requirements.txt`
- 检查 `wrench_gui.spec` 中的 `hiddenimports` 是否包含缺失的模块

### 2. 运行时报错：找不到 config.json

**问题**: 程序启动时报错找不到配置文件

**解决**:
- 确保 `config.json` 在可执行文件同一目录下
- 检查 `wrench_gui.spec` 中的 `datas` 配置是否正确

### 3. 打包后的程序很大（>50MB）

**原因**: PyInstaller 会打包所有依赖库

**优化**:
- 使用虚拟环境，只安装必需的包
- 在 `wrench_gui.spec` 的 `excludes` 中添加不需要的模块

### 4. 控制台窗口也显示（Windows）

**问题**: 打包后的程序同时显示 GUI 和控制台窗口

**解决**:
- 检查 `wrench_gui.spec` 中 `console=False` 是否设置正确

### 5. 图标设置

如果需要自定义程序图标：

1. 准备图标文件（`.ico` 格式，Windows）
2. 修改 `wrench_gui.spec`：
   ```python
   icon='icon.ico',  # 图标文件路径
   ```
3. 重新打包

---

## 六、打包选项说明

### wrench_gui.spec 关键配置

- **`console=False`**: 不显示控制台窗口（GUI应用）
- **`upx=True`**: 使用 UPX 压缩（减小文件大小）
- **`datas`**: 包含的数据文件（如配置文件）
- **`hiddenimports`**: 需要显式导入的隐藏模块

### 单文件打包（可选）

如果需要打包成单个 `.exe` 文件，修改 `wrench_gui.spec`：

```python
exe = EXE(
    pyz,
    a.scripts,
    [],
    exclude_binaries=True,  # 改为 True
    name='wrench_gui',
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=True,
    console=False,
)
```

然后添加 `COLLECT` 部分（PyInstaller 会自动处理）。

---

## 七、分发打包后的程序

### 1. 最小分发包

需要包含的文件：

```
wrench_gui/
├── wrench_gui.exe          # 可执行文件
├── config.json              # 配置文件
└── README.txt               # 使用说明（可选）
```

### 2. 完整分发包（推荐）

```
wrench_gui/
├── wrench_gui.exe
├── config.json
├── README.txt
└── 使用说明.pdf            # 用户手册
```

### 3. 注意事项

- 确保目标机器已安装必要的运行时库（如 Visual C++ Redistributable，Windows）
- 如果使用了 UPX 压缩，某些杀毒软件可能会误报，建议关闭 UPX 或添加白名单

---

## 八、快速打包命令（一键打包）

### Windows
```cmd
cd frontend && build_exe.bat
```

### Linux/Mac
```bash
cd frontend && chmod +x build_exe.sh && ./build_exe.sh
```

---

## 九、验证打包结果

打包完成后，建议测试：

1. **运行可执行文件**
   - 检查是否能正常启动
   - 检查是否能连接到后端 API
   - 检查设备管理功能是否正常

2. **检查文件大小**
   - 正常大小：15-30 MB
   - 如果过大（>50MB），检查依赖

3. **测试功能**
   - 工单列表加载
   - 设备选择
   - 拧紧操作
   - 数据提交

---

## 十、技术支持

如果遇到打包问题：

1. 查看 PyInstaller 官方文档：https://pyinstaller.org/
2. 检查错误日志：`build/wrench_gui/warn-wrench_gui.txt`
3. 使用调试模式：在 `wrench_gui.spec` 中设置 `debug=True`