banban/factory_host/docs/DEVELOPMENT.md

EG800 产测上位机开发与发布

1. 目录职责

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

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

2. 环境准备

在项目根目录执行：

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

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

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

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

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

3. 开发与测试

运行源码：

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

运行全部测试：

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. 更新产测音频和固件

音频源位于：

audio_prompts/factory_test/customer_fs/

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

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

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

生成产测完整固件：

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

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

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

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

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

5. 生成交付包

使用默认两份固件：

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

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

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. 发布检查

发布前至少执行：

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 顶层只能包含：

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 编译目录或历史日志交付给工厂。