protocol-docs/docs/architecture.md

AI球项目架构初稿

本文档描述 AI球项目的初版系统架构，用于后续设备端、PC 上位机、应援脚本、资源包和出厂测试协作对齐。

1. 目标

• 支持 AI球设备播放灯效、音效、表情或动作反馈。
• 支持 PC 上位机进行设备管理、内容同步和测试控制。
• 支持演唱会/活动现场通过应援脚本驱动多台设备同步表现。
• 支持资源包分发和版本管理。
• 支持出厂测试流程记录设备是否合格。

2. 模块划分

2.1 设备端

设备端运行在 AI球硬件上，负责：

• 接收 PC 上位机或同步播放器下发的控制命令。
• 管理本地状态机，例如空闲、连接、同步播放、测试、异常。
• 播放资源包中的灯效、音频、表情或动作资源。
• 执行出厂自检项目并返回结果。

2.2 PC 上位机

PC 上位机用于生产、调试和现场运行：

• 扫描并连接 AI球设备。
• 下发设备控制命令和同步播放状态。
• 导入、校验和分发应援脚本及资源包。
• 执行出厂测试并导出测试报告。

2.3 应援脚本

应援脚本描述指定时间点的表现动作：

• 以 content_id 标识一场内容或曲目。
• 以 time_ms 表示相对播放时间。
• 动作类型可包括灯效、音效、表情、震动或组合动作。
• 脚本应能被 PC 上位机校验，并被设备端按时间轴执行。

2.4 资源包

资源包用于承载设备端执行所需资源：

• 包含资源清单、版本号、资源路径和校验信息。
• 可被 PC 上位机导入并分发到设备。
• 设备端应校验资源包版本和资源完整性。

2.5 出厂测试

出厂测试用于首批设备生产验证：

• 覆盖烧录、自检、屏幕/灯效、喇叭、麦克风、按键、无线充电、通信和应援脚本播放。
• 每台设备应产生唯一测试记录。
• 不合格设备应记录失败项和复测结果。

3. 初版数据流

1. 内容制作方生成应援脚本和资源包。
2. PC 上位机导入并校验脚本/资源包。
3. PC 上位机将资源包分发到 AI球设备。
4. 演出或测试时，PC 上位机下发同步状态和播放进度。
5. 设备端根据本地资源和脚本时间轴执行表现动作。
6. 生产阶段 PC 上位机采集出厂测试结果并生成报告。

4. 待确认问题

• 设备端通信链路采用 USB、BLE、Wi-Fi 还是组合方案。
• 多设备同步精度目标。
• 资源包压缩格式和签名机制。
• 出厂测试报告的最终存储位置和格式。