# 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 还是组合方案。
- 多设备同步精度目标。
- 资源包压缩格式和签名机制。
- 出厂测试报告的最终存储位置和格式。