设计思想
本章定义电控代码的架构目标和设计边界。核心原则与 XRobot 官方设计思想对齐，再叠加队内工程约束。
1. 目标
电控软件不是“能跑就行”，而是要满足四个长期目标：
- 可维护：新人能快速读懂并修改，不靠“口口相传”。
- 可扩展：新车、新机构、新模块能低成本接入。
- 可观测：问题出现时能快速定位，不靠猜。
- 可复用：共性能力沉淀成模块，而不是散落在业务代码里。
2. 分层与职责
建议按下面三层组织：
- 平台与硬件层（LibXR / BSP / Middlewares）
- 业务模块层（Modules）
- 应用集成层（User / 配置 / 主流程）
2.1 平台与硬件层
- 提供线程、消息、外设、回调、时基等基础能力。
- 只做通用能力，不写业务决策。
- 改动要谨慎，优先在业务模块解决问题。
2.2 业务模块层
- 一个模块只做一个明确职责（例如 Gimbal、Chassis、CMD）。
- 对外只暴露稳定接口（事件、Topic、构造参数）。
- 模块之间通过消息和事件协作，避免强耦合直接调用。
2.3 应用集成层
- 负责实例化模块、注入依赖、拼装系统行为。
- 负责按车型/兵种切换参数和模板类型。
- 不承载底层算法实现细节。
3. 模块化原则
3.1 单一职责
- CMD 只做命令汇聚和发布。
- Chassis/Gimbal/Launcher 只做各自控制闭环。
- EventBinder 只做事件映射。
3.2 依赖显式注入
- 所有关键依赖必须放进构造参数。
- 不允许隐藏全局状态依赖。
- 模块依赖在 manifest 和 README 中保持一致。
3.3 生命周期一致
- 初始化：完成硬件绑定与资源注册。
- 运行：固定周期读取输入、计算输出、发布状态。
- 监控：通过终端/Topic 提供可观测信息。
4. 控制链路设计
统一按“输入 -> 决策 -> 执行 -> 反馈”建模：
- 输入层：DR16、HostData、传感器驱动。
- 决策层：CMD、模式机、EventBinder。
- 执行层：Gimbal、Chassis、Launcher、Wheelleg。
- 反馈层：Motor/IMU/功率状态，通过 Topic 回流。
这样做的好处：
- 每一层都有清晰边界，问题好定位。
- 可以替换某一层而不重写整条链路。
5. 实时性设计
- 控制线程保持周期稳定，避免随机抖动。
- 回调里不做阻塞操作，尤其避免耗时 IO。
- 持锁区只做快速读写，不做外设阻塞发送。
- 高频路径避免动态分配和重复构造大对象。
6. 调试设计
调试能力是架构的一部分，不是“后补”。
- 每个关键模块都应提供最小可用状态观测。
- 调试实现与业务实现分离，建议用
*.inl管理。 - Debug 构建启用调试接口，Release 构建关闭调试实现。
7. 工程演进策略
- 先保证接口稳定，再优化实现细节。
- 先补文档，再推广到全模块统一。
- 先小范围验证，再批量迁移。
推荐节奏：
- 单模块改造
- 分支联调
- 全链路回归
- 合并主干