# JiGuang 算法接入与打包命令说明

本文档说明 `entry.cp311-win_amd64.pyd` 与 Electron 项目的开发、打包、发布命令。

---

## 目录结构

```text
JiGuang-program/
├── entry.cp311-win_amd64.pyd   # 算法核心（算法方提供，可替换）
├── license.lic                 # 授权文件
├── public_key.pem              # 公钥
├── runner.py                   # Python 桥接脚本
├── runner.dist/                # Nuitka 编译产物（含 api_runner.exe）
├── runner.build/               # 编译缓存（可删除，不影响运行）
├── build_runner.bat            # 首次/依赖变更时编译 api_runner.exe
├── sync_entry.bat              # 同步 entry.pyd 到 runner.dist（秒级）
└── requirements.txt            # Python 依赖清单
```

---

## 一、本地开发调试

在项目根目录执行（**不要用** `npm run dev` 单独开浏览器）：

```powershell
cd C:\Users\milo\Desktop\激光\jg
npm install
npm run electron:dev
```

开发环境调用链：

```text
Vue → Electron → python runner.py → entry.cp311-win_amd64.pyd
```

### 开发环境前置条件

- 已安装 **Python 3.11**
- 已安装依赖：

```powershell
cd serves\JiGuang-program
python -m pip install -r requirements.txt
```

### 仅替换 entry.pyd 后开发

```powershell
# 1. 覆盖 JiGuang-program\entry.cp311-win_amd64.pyd
# 2. 重启应用
cd C:\Users\milo\Desktop\激光\jg
npm run electron:dev
```

**不需要**重新执行 `build_runner.bat`。

---

## 二、首次生成 api_runner.exe（只需一次）

用于在没有 Python 的电脑上离线运行。耗时 **1~3 小时**。

```powershell
cd C:\Users\milo\Desktop\激光\jg\serves\JiGuang-program
.\build_runner.bat
```

编译成功后确认：

```powershell
dir runner.dist\api_runner.exe
dir runner.dist\entry.cp311-win_amd64.pyd
```

可选：删除编译缓存减小体积

```powershell
rmdir /s /q runner.build
```

---

## 三、更新 entry.pyd 后发布（常用，无需重编 api_runner）

算法方提供新的 `entry.cp311-win_amd64.pyd` 时：

```powershell
# 1. 覆盖 JiGuang-program 根目录下的 entry.cp311-win_amd64.pyd

# 2. 同步到 runner.dist（几秒钟）
cd C:\Users\milo\Desktop\激光\jg\serves\JiGuang-program
.\sync_entry.bat

# 3. 重新打 Electron 安装包
cd C:\Users\milo\Desktop\激光\jg
npm run electron:build
```

`npm run electron:build` 会自动先执行 `sync:entry`。

安装包输出路径：

```text
dist_electron\激光测距仪-0.0.1-setup.exe
```

---

## 四、命令速查表

| 命令                                        | 位置            | 用途                           | 耗时       |
| ------------------------------------------- | --------------- | ------------------------------ | ---------- |
| `npm run electron:dev`                      | 项目根目录      | 本地开发调试                   | 秒级       |
| `python -m pip install -r requirements.txt` | JiGuang-program | 安装 Python 依赖               | 分钟级     |
| `.\build_runner.bat`                        | JiGuang-program | 首次编译 api_runner.exe        | 1~3 小时   |
| `.\sync_entry.bat`                          | JiGuang-program | 同步 entry.pyd 到 runner.dist  | 秒级       |
| `npm run sync:entry`                        | 项目根目录      | 同上（npm 快捷方式）           | 秒级       |
| `npm run electron:build`                    | 项目根目录      | 打 Windows 安装包              | 10~30 分钟 |
| `npm run electron:build:full`               | 项目根目录      | 完整重编 api_runner + 打安装包 | 1~3 小时+  |

---

## 五、什么时候需要 build_runner.bat？

| 场景                           | 是否需要 build_runner.bat               |
| ------------------------------ | --------------------------------------- |
| 更换新的 entry.pyd             | ❌ 不需要，用 sync_entry.bat            |
| 更换 license.lic               | ❌ 不需要，用 sync_entry.bat            |
| 修改 runner.py                 | ❌ 开发直接用 python；发布前 sync_entry |
| **首次**搭建生产环境           | ✅ 需要                                 |
| 升级 pandas/numpy/scipy 等依赖 | ✅ 需要                                 |
| 更换 Python 3.11 版本          | ✅ 需要                                 |

---

## 六、生产环境运行方式

安装包在用户电脑上的调用链：

```text
激光测距仪.exe → runner.dist\api_runner.exe → entry.cp311-win_amd64.pyd
```

用户电脑**不需要**安装 Python，可**离线运行**。

---

## 七、常见问题

### 1. PowerShell 无法运行 bat/ps1

```powershell
# bat 必须加 .\
.\build_runner.bat
.\sync_entry.bat

# ps1 需要绕过执行策略
powershell -ExecutionPolicy Bypass -File .\build_runner.ps1
```

### 2. 路径中的 ADMINI~1 是乱码吗？

不是。这是 Windows 8.3 短路径，属于正常现象。

### 3. 本机能跑，别的电脑报错

- 确认已用 `build_runner.bat` 生成 `runner.dist\api_runner.exe`
- 确认发布前执行了 `sync_entry.bat`
- 确认安装包是最新 `npm run electron:build` 产物

### 4. build_runner 编译内存不足

脚本已使用 `--jobs=1` 降低内存占用。若仍失败，开发阶段可：

```powershell
rmdir /s /q runner.dist
npm run electron:dev
```

---

## 八、Vue 侧 API 调用（无需修改）

```javascript
// 加载测量数据
await window.electronAPI.callPythonAPI("loaddata", [
  定位文件,
  测量文件,
  锥角,
  倾角,
  阈值,
]);

// 获取历史数据 CSV 路径
await window.electronAPI.callPythonAPI("getpath");

// 查看历史详情
await window.electronAPI.callPythonAPI("historydata", [时间, 场站, 风机编号]);

// 删除历史数据
await window.electronAPI.callPythonAPI("deletedata", [时间, 场站, 风机编号]);
```

---

## 九、推荐发布流程（总结）

```powershell
# 首次（或依赖升级时）才执行
cd serves\JiGuang-program
.\build_runner.bat

# 每次发版
# 1. 更新 entry.pyd / license.lic（如有）
# 2. 同步 + 打包
cd C:\Users\milo\Desktop\激光\jg
npm run electron:build

# 3. 分发
# dist_electron\激光测距仪-0.0.1-setup.exe
```