protocol-docs/docs/state_machine.md

AI球状态机

本文档定义 AI球设备端的初版状态机，用于统一设备行为、PC 上位机控制和出厂测试流程。

1. 状态列表

状态	说明
BOOTING	设备启动中，初始化硬件和本地配置。
IDLE	空闲待机，可被发现或等待连接。
CONNECTED	已连接 PC 上位机或同步播放器。
RESOURCE_READY	已完成资源包校验，可执行应援脚本。
SYNC_PLAYING	正在按同步协议执行应援脚本。
PAUSED	播放暂停，保留当前进度。
FACTORY_TEST	正在执行出厂测试。
ERROR	发生错误，需要上报错误码并等待恢复。

2. 主要状态切换

当前状态	事件	下一状态	说明
BOOTING	初始化成功	IDLE	设备完成启动。
IDLE	建立连接	CONNECTED	PC 上位机接入。
CONNECTED	资源包校验成功	RESOURCE_READY	可进入同步播放。
RESOURCE_READY	收到播放命令	SYNC_PLAYING	根据 content_id 和 position_ms 开始执行。
SYNC_PLAYING	收到暂停命令	PAUSED	暂停当前表现。
PAUSED	收到继续命令	SYNC_PLAYING	从指定进度继续。
任意状态	进入出厂测试	FACTORY_TEST	生产或维修流程触发。
任意状态	发生严重错误	ERROR	记录错误码并停止危险动作。
ERROR	重置成功	IDLE	清理错误后恢复待机。

3. 设备端默认行为

• 进入 BOOTING 时执行硬件初始化和配置加载。
• 进入 IDLE 时关闭非必要高功耗模块。
• 进入 SYNC_PLAYING 时按应援脚本时间轴触发动作。
• 进入 FACTORY_TEST 时禁止普通播放命令干扰测试流程。
• 进入 ERROR 时上报错误码，并尽量保持安全可恢复状态。

4. 与其他模块关系

• PC 上位机负责触发连接、资源分发、播放控制和出厂测试。
• 应援脚本定义 SYNC_PLAYING 状态下的时间轴动作。
• 资源包必须在 RESOURCE_READY 前完成完整性校验。
• 出厂测试应覆盖主要状态切换是否可靠。