refactor: organize factory host release layout

2026-09-24 15:07:44 +08:00
parent 95d67962b1
commit c011f5c491
14 changed files with 490 additions and 161 deletions
@@ -1,94 +1,105 @@
 # EG800 FT1 工厂烧录与产测上位机

-本工具配套 `test/factory-test` 分支的独立产测固件，支持批量烧录、DBG UART
-协议采集、6 个硬件节点判定和结果落盘。
+本目录包含上位机源码、默认配置、测试、构建脚本和发布文档。最终交付物统一生成到
+`factory_host/dist/`，工厂不需要接触项目源码。

-## 主要功能
-
- 产测固件和正式固件分开保存，每个工位可独立选择。
- 烧录串口和产测 DBG UART 分开配置，避免把 DIAG/AT/调试口误认成烧录口。
- 主界面提供醒目的“启动自动烧录”：每 0.5 秒持续检测烧录串口，先让下载器按工位进入等待，再由设备上电触发烧录。
- 每个工位完成后会锁定当前设备；只有检测到该端口消失并重新出现（断开旧设备、连接下一台并上电）才会再次烧录，避免同一设备反复烧录。
- 烧录与串口扫描均在后台运行，Windows 子进程隐藏控制台窗口，不阻塞界面。
- 烧录和产测运行期间实时日志强制跟随最新一行，停止后才允许手工滚动。
- 只解析以 `FT1 ` 开头的协议行；普通 SDK 日志只显示，不进入产测数据库。
- 严格校验协议版本、消息类型、节点编号/名称、会话 ID 和递增序号。
- 显示 `BOOT_AUDIO`、`POWER_ADC`、`AUDIO_LOOPBACK`、`ESIM`、
-  `DATA_CALL`、`NFC` 的实时状态与结构化数据。
- 收到 `session_result` 或 `power_off` 时自动保存完整 JSON 和汇总 CSV。
- 保存 IMEI、ICCID、NFC UID、失败码、固件版本、节点耗时和总耗时。
-
-## 目录和启动
-
-完整烧录工具位于：
+## 工程结构

 ```text
-burn_tool/aboot-tools-2024.08.08-win-x64/adownload.exe
+factory_host/
+├─ src/                         # Python 上位机源码
+│  ├─ factory_host.py
+│  └─ ft1_protocol.py
+├─ config/                      # 开发和发布使用的默认配置
+│  └─ factory_host_config.json
+├─ scripts/                     # 音频、固件和 release 构建脚本
+│  ├─ build_factory_audio_package.py
+│  ├─ build_factory_firmware.ps1
+│  └─ build_release.ps1
+├─ tests/                       # 自动测试
+│  └─ test_factory_host.py
+├─ docs/
+│  ├─ USAGE.md                  # 工厂现场操作说明
+│  └─ DEVELOPMENT.md            # 开发、换包和发布说明
+├─ firmware/                    # 默认产测与正式固件
+├─ vendor/                      # 本地 Aboot 厂商工具，不提交
+├─ build/                       # 中间产物和开发日志，不提交
+├─ dist/                        # 最终交付目录，每次发布会重建
+├─ requirements.txt
+└─ README.md
 ```

-发布程序：
+`build/` 和 `dist/` 都被 Git 忽略。发布脚本只会清理 `dist/`，不会修改 `src/`、
+`config/`、`docs/`、`tests/` 或 `build/`。

-```text
-factory_host/dist/EG800FactoryHost.exe
-```
+## 功能

-默认“产测固件”和“正式固件”分别位于：
+- 产测固件与正式固件独立保存并醒目标识。
+- 持续检测烧录串口，支持多工位自动等待设备上电后烧录。
+- 同一设备烧录成功后锁定，端口断开并重新出现后才允许烧录下一台。
+- 自动识别 DBG UART，解析设备每 500 ms 广播的 FT1 状态。
+- 显示六个测试节点、IMEI、ICCID、NFC UID、失败码和实时日志。
+- 自动保存汇总 CSV 与单机 JSON，烧录和扫描过程不弹出控制台黑框。

-```text
-burn_tool/firmware/test/EG800AKCN_11LG-FT1-factory-test.zip
-burn_tool/firmware/official/EG800AKCN_11LG-official-fac.zip
-```
+## 快速验证

-两者都可通过主界面切换并选择，也可在外置
-`factory_host_config.json` 中替换，烧录时不要选择 `-target.zip` 外层归档。
-
-双击表格中的工位可以分别设置烧录口和产测 DBG UART 口。默认 USB 自动等待模式不需要
-
-填写烧录口；产测 UART 可留空并自动识别。“烧录选中”要求只选择一个工位；“批量烧录”
-在未选中行时作用于全部工位，选中后只作用于选中工位。
-
-单工位烧录时保持设备关机并连接 USB，选择工位后点击“烧录选中”。工位状态显示
-“等待上电”后再给设备开机。此时 `adownload` 会捕获 AROM USB 下载口并开始烧录，
-操作顺序与 Aboot 的 `usbOnly + usbAutoEnable` 默认设置一致。
-
-串口和协议记录位于：
-
-```text
-factory_host/dist/logs/factory_results.csv
-factory_host/dist/logs/sessions/*.json
-```
-
-## FT1 结果规则
-
-产测结果完全采用固件的 `session_result`，上位机不会用模糊正则猜测硬件是否通过。
-非零失败码会显示 `docs/factory_test.md` 中对应的中文含义。收到 `power_off` 后会再次
-刷新同一 JSON 文件，但不会在 CSV 中重复增加记录。
-
-`AUDIO_LOOPBACK=PASS` 表示 GPIO84（原三击测试按键）的录放数据链路成功。
-Loopback 仍然是按住录音、松开回放，最长录音 5 秒。
-
-## 产测音频包
-
-重新生成音频包：
+在项目根目录执行：

 ```powershell
-python -B .\factory_host\build_factory_audio_package.py
+python -m pip install -r .\factory_host\requirements.txt
+python -B -m unittest discover -s .\factory_host\tests -p "test_*.py" -v
+python -B .\factory_host\src\factory_host.py
 ```

-脚本会执行以下检查：
+源码模式会读取 `factory_host/config/factory_host_config.json`，运行日志写入
+`factory_host/build/logs/`，固件和下载器从现有 `factory_host/dist/` 解析。

-1. 源目录必须且只能包含五个固定文件名。
-2. 每个文件必须为 16 kHz、单声道、48 kbps MP3。
-3. 使用 SDK `mklfs-v2.exe -m` 生成 262144 字节 `customer_fs.bin`。
-4. 立即反向解包镜像并逐文件比对 SHA-256。
-5. 输出 ZIP、清单及校验值到 `factory_host/dist/factory_audio/`。
+## 生成 Release

-不要直接覆盖正式业务 `customer_fs.bin`。需要构建产测整包时，按照
-`docs/factory_test_windows_fs.md` 先备份业务镜像，再临时放入产测镜像。
+默认使用项目中的以下输入：

-## 开发验证
+```text
+factory_host/firmware/test/EG800AKCN_11LG-FT1-factory-test.zip
+factory_host/firmware/official/EG800AKCN_11LG-official-fac.zip
+factory_host/vendor/aboot-tools-2024.08.08-win-x64/
+```
+
+执行：

 ```powershell
-python -B -m unittest discover -s factory_host -p "test_*.py" -v
-powershell.exe -NoProfile -ExecutionPolicy Bypass -File factory_host\build_release.ps1
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\factory_host\scripts\build_release.ps1
 ```
+
+生成：
+
+```text
+factory_host/dist/
+├─ START-EG800-FACTORY-TOOL.exe
+├─ firmware/
+│  ├─ EG800AKCN_11LG-FT1-factory-test.zip
+│  └─ EG800AKCN_11LG-official-fac.zip
+├─ .runtime/                    # Windows 隐藏目录
+│  ├─ burn_tool/
+│  ├─ docs/USAGE.md
+│  ├─ factory_host_config.json
+│  ├─ release_manifest.json
+│  └─ logs/
+└─ EG800-Factory-Tool-Full-Package.zip
+```
+
+交付工厂时只发送 `EG800-Factory-Tool-Full-Package.zip`。解压后双击醒目的
+`START-EG800-FACTORY-TOOL.exe`；不要单独移动 EXE、固件或 `.runtime`。
+
+默认配置使用相对于发布目录的路径：
+
+```text
+firmware/EG800AKCN_11LG-FT1-factory-test.zip
+firmware/EG800AKCN_11LG-official-fac.zip
+.runtime/burn_tool/aboot-tools-2024.08.08-win-x64/adownload.exe
+```
+
+## 文档
+
+- 工厂操作：[docs/USAGE.md](docs/USAGE.md)
+- 开发、更新固件与发布：[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)
+- 固件侧 FT1 协议：[../docs/factory_test.md](../docs/factory_test.md)