# EG800 产测上位机开发与发布

## 1. 目录职责

| 目录 | 用途 | 是否提交 |
| --- | --- | --- |
| `src/` | 上位机与 FT1 协议源码 | 是 |
| `config/` | 默认发布配置 | 是 |
| `scripts/` | 音频、固件、上位机发布脚本 | 是 |
| `tests/` | 单元测试 | 是 |
| `docs/` | 工厂与开发文档 | 是 |
| `firmware/` | 默认产测与正式固件 | 是，二进制由 Git LFS 管理 |
| `vendor/` | 完整 Aboot 厂商工具 | 否，本地依赖 |
| `build/` | 中间产物、备份和开发日志 | 否 |
| `dist/` | 最终 release 目录和 ZIP | 否 |

不要在 `dist/` 保存需要长期保留的文件。`build_release.ps1` 每次发布前都会校验目标位于
`factory_host` 内，然后清空并重建目标目录。

## 2. 环境准备

在项目根目录执行：

```powershell
python -m pip install -r .\factory_host\requirements.txt
python -m pip install pyinstaller
```

完整固件构建还需要当前 EG800 SDK 的编译环境能够正常执行 `build.bat app` 和
`build.bat firmware`。

发布还要求本机存在完整厂商工具目录：

```text
factory_host/vendor/aboot-tools-2024.08.08-win-x64/
```

`vendor/` 被 Git 忽略，不能只放一个 `adownload.exe`；请保留原工具的 DLL、配置、驱动和
平台文件。发布脚本缺少该目录时会直接报错，不会生成残缺包。

## 3. 开发与测试

运行源码：

```powershell
python -B .\factory_host\src\factory_host.py
```

运行全部测试：

```powershell
python -B -m unittest discover -s .\factory_host\tests -p "test_*.py" -v
```

源码模式读取 `factory_host/config/factory_host_config.json`，日志写入
`factory_host/build/logs/`。默认相对固件路径会解析到 `factory_host/dist/firmware/`。

## 4. 更新产测音频和固件

音频源位于：

```text
audio_prompts/factory_test/customer_fs/
```

生成并验证音频文件系统：

```powershell
python -B .\factory_host\scripts\build_factory_audio_package.py
```

输出位于 `factory_host/build/audio/`。脚本会检查五个固定 MP3 的名称与格式，生成
262144 字节 `customer_fs.bin`，反向解包并逐文件核对 SHA-256。

生成产测完整固件：

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\factory_host\scripts\build_factory_firmware.ps1
```

输出位于 `factory_host/build/firmware/`。脚本会临时替换 SDK 的业务
`customer_fs.bin`，完成后恢复原文件并核对哈希。恢复失败时不得继续发布。

确认新固件后，将其更新为默认产测固件：

```text
factory_host/firmware/test/EG800AKCN_11LG-FT1-factory-test.zip
```

也可以不覆盖默认文件，在发布时通过 `-FactoryFirmware` 显式选择。

## 5. 生成交付包

使用默认两份固件：

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\factory_host\scripts\build_release.ps1
```

使用指定固件，路径相对于项目根目录，也支持绝对路径：

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass `
  -File .\factory_host\scripts\build_release.ps1 `
  -FactoryFirmware "factory_host\build\firmware\EG800AKCN_11LG-FT1-factory-test.zip" `
  -OfficialFirmware "factory_host\firmware\official\EG800AKCN_11LG-official-fac.zip"
```

发布脚本会：

1. 清空并重建 `factory_host/dist/`。
2. 从 `src/` 生成无控制台窗口的单文件 EXE。
3. 复制完整 Aboot 工具目录，不能只复制 `adownload.exe`。
4. 复制产测与正式固件到 `dist/firmware/`。
5. 把配置、使用说明、下载器和日志目录放入 `.runtime/`。
6. 生成包含 Git revision、文件大小和 SHA-256 的 `release_manifest.json`。
7. 生成 `EG800-Factory-Tool-Full-Package.zip`。

## 6. 发布检查

发布前至少执行：

```powershell
python -B -m unittest discover -s .\factory_host\tests -p "test_*.py" -v
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\factory_host\scripts\build_release.ps1
tar.exe -tf .\factory_host\dist\EG800-Factory-Tool-Full-Package.zip
```

ZIP 顶层只能包含：

```text
START-EG800-FACTORY-TOOL.exe
firmware/
.runtime/
```

还应在一台真实设备上验证：自动等待上电烧录、断开后才允许下一台、DBG UART 自动识别、
七项 FT1 状态、GNSS 累计数据、JSON/CSV 保存，以及产测固件和正式固件切换。

## 7. 固件替换规则

- 产测与正式固件都必须是 Aboot 可直接烧录的内层 ZIP，不要选择外层 `*-target.zip`。
- 默认文件名保持不变时无需修改配置。
- 修改文件名时同步更新 `config/factory_host_config.json`。
- 每次发布核对 `.runtime/release_manifest.json` 中的大小和 SHA-256。
- 不要把源码、`build/`、SDK 编译目录或历史日志交付给工厂。