# 桌面应用打包简版指南

## 一句话总结

技术栈：`React 前端 + Python FastAPI 后端 + Electron 外壳 + electron-builder 安装包`

用户双击桌面图标 → Electron 启动 → 自动拉起后端 → 窗口加载后端页面。

---

## 打包前准备

### 1. 安装依赖

```powershell
# 前端依赖
cd chatlab-web/frontend
npm install

# Electron 依赖
cd ../../electron-launcher
npm install

# Python 依赖
cd ../chatlog_fastAPI
py -3.12 -m pip install -r requirements.txt
py -3.12 -m pip install pyinstaller
```

### 2. 确认文件齐全

- `chatlog.exe` 存在于项目根目录
- `lib/windows_x64/wx_key.dll` 存在
- Node.js、Python 3.12 可用

---

## 一键打包

```powershell
cd 项目根目录
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1
```

这个脚本会依次完成：
1. 生成应用图标
2. 构建 React 前端（`npm run build`）
3. 用 PyInstaller 打包 Python 后端
4. 复制所有资源到 `electron-launcher/build-resources/`
5. 扫描敏感文件（.env、证书、数据库等自动排除）
6. 调用 electron-builder 生成 NSIS 安装包
7. 输出到 `release/` 目录

最终产物：`release/ChatLab-Setup-版本号.exe`

---

## 调试时跳过某些步骤

```powershell
# 只改前端，跳过后端打包
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1 -SkipBackend

# 只改后端，跳过前端构建
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1 -SkipFrontend

# 只准备资源，不生成安装包
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1 -SkipInstaller
```

---

## 打包流程原理

```
scripts/build-desktop.ps1（总控脚本）
    │
    ├── Vite 构建前端 → chatlab-web/frontend/dist/
    │
    ├── PyInstaller 打包后端 → chatlog_fastAPI/dist/ChatLabBackend/
    │
    ├── 复制所有资源到 build-resources/
    │     ├── frontend/（前端静态文件）
    │     ├── backend/（Python 后端 exe + _internal/）
    │     ├── chatlog.exe（微信数据服务）
    │     └── lib/windows_x64/wx_key.dll
    │
    └── electron-builder 打包 → release/安装包
```

**核心原则：**
- 运行期必须作为真实文件存在的内容（exe、DLL、前端 dist）走 `extraResources`，不进 asar
- 用户数据写 `%APPDATA%/ChatLab`，不写安装目录
- Electron 主进程只负责窗口和进程管理，不承载业务逻辑

---

## 安装后的目录结构

```
安装目录/
  ChatLab售后智能助手.exe
  resources/
    app.asar              ← Electron 主程序
    backend/
      ChatLabBackend.exe  ← Python 后端
      _internal/
    frontend/
      index.html          ← React 页面
      assets/
    chatlog.exe           ← 微信数据服务
    lib/windows_x64/
      wx_key.dll
```

---

## 签名打包（正式发布）

```powershell
$env:CHATLAB_PFX_FILE = "D:\certs\ChatLab-CodeSigning.pfx"
$env:CHATLAB_PFX_PASSWORD = "证书密码"
$env:CHATLAB_FORCE_SIGN = "1"

powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1
```

注意事项：
- 证书不要放项目目录
- 密码不要写进代码仓库
- 签名可显著降低 SmartScreen 拦截概率

---

## 打包后验证

1. 检查 `release/` 下安装包是否生成
2. 在干净 Windows 机器上安装测试
3. 确认双击启动 → 后端启动 → 页面正常加载
4. 确认关闭后无残留进程
5. 确认用户数据在 `%APPDATA%/ChatLab`

---

## 常见问题

| 问题 | 原因 | 解决 |
|---|---|---|
| 前端空白 | 前端 dist 没复制到 build-resources | 检查 `build-resources/frontend/index.html` 是否存在 |
| 后端启动失败 | PyInstaller 缺少 hidden imports | 检查 `.spec` 文件，补充缺失模块 |
| 找不到 exe/DLL | 资源没复制或被打进 asar | 外部 exe/DLL 必须走 `extraResources` |
| 关闭后残留进程 | 只杀了父进程没杀子进程树 | 使用 `taskkill /pid /f /t` |
| 客户电脑提示风险 | 安装包未签名 | 使用代码签名证书 |