ARCBOS
ENGINEERED FOR EXTREME CONDITIONS
文件定位
本文件为 SnowBot 全栈软件系统架构规划文档。
本文件用于定义 SnowBot 软件系统的长期架构方向、分层逻辑、模块边界、接口关系、仓库结构、状态机、安全策略与阶段化开发顺序。
本文件不是当前外包合同范围，也不是供应商报价清单。
当前工程样机阶段严格执行：
Alpha补齐 + Beta闭环也就是：
Alpha：系统打通，机器可控、可联调
Beta：任务闭环，固定场地内可执行基础路线任务以下能力属于后续 Gamma / Delta / Fleet / Service 阶段，不纳入当前外包默认范围：
- SLAM / 建图
- 全局路径规划
- 区域覆盖算法
- 高级动态避障
- 自动回充 / 自动对桩
- 云端任务调度
- 多机协同
- 完整远程运维平台
- 无人值守
与当前外包文档的关系
本文件 = 软件架构总览 / 长期技术方向
外包主需求文档 = 当前合同与验收边界
工程任务清单 = Alpha/Beta阶段具体执行任务当前软件外包与供应商报价，必须以以下文件为准：
- 《SnowBot Alpha补齐与Beta闭环移动机器人导航控制系统软件外包主需求文档》
- 《SnowBot Alpha补齐与Beta闭环软件外包工程任务清单》
本文件可以用于架构评审、技术负责人沟通、工程师 onboarding 和后续版本规划，但不得被供应商直接解释为当前阶段完整交付范围。
系统总架构
SnowBot 软件系统采用分层架构。
Cloud / Fleet Layer 云端与车队层（后续）
Application Layer 任务与应用层
Autonomy Layer 定位、路径、状态机与安全决策
Middleware Layer ROS2 / 通信中间件
Control Interface Layer 底盘、执行机构与安全接口
Embedded Layer MCU / 驱动 / IO / 实时控制
Hardware Layer 传感器、电机、电池、执行机构当前 Alpha/Beta 阶段只做最小本地闭环，不做完整云端平台。
当前阶段最小闭环
Alpha/Beta 阶段必须先完成以下最小闭环：
传感器输入
→ 融合定位
→ 路线录制 / 回放
→ 路径跟踪
→ 底盘控制
→ 障碍检测
→ 安全停车 / 降级
→ 日志导出该闭环未完成，不得进入更高级自治开发。
Alpha阶段软件能力
目标：系统打通，机器可控。
必须完成：
- 工控机 / IPC 环境
- Linux / Ubuntu 基础环境
- ROS2 或等效运行环境
- 底盘控制接口
- 底盘反馈接口
- RTK / GNSS 驱动接入
- IMU 驱动接入
- 里程计 / odometry 接入
- lidar 接入
- 手动控制链路
- 手动 / 自动模式切换
- 急停软件联动
- 基础日志
- 基础部署脚本
Alpha 不做：
- 自动作业
- 路径规划
- 复杂避障
- 自动回充
Beta阶段软件能力
目标：固定场地内完成基础任务闭环。
必须完成：
- RTK + IMU + odometry 融合定位
- 固定场地局部坐标系
- 路线录制
- 路线存储
- 路线回放
- 路径跟踪控制
- 基础路径偏差处理
- 基础障碍检测
- 前向安全区
- 边界约束
- 安全停车
- 降级逻辑
- 任务状态机
- 日志导出
- 参数调整工具
- 现场联调
Beta 不做：
- SLAM / 建图硬交付
- 全局路径规划
- 区域覆盖算法
- 自动回充
- 云端调度
- 多机协同
- 无人值守
模块拆分
当前 Alpha/Beta 软件包建议拆分为：
sensor_adapter
├─ RTK / GNSS input
├─ IMU input
├─ odometry input
└─ lidar input
localization
├─ fusion
└─ pose output
route_manager
├─ route record
├─ route storage
└─ route replay
controller_beta
├─ path tracking
├─ velocity command
└─ stop / degraded command
safety_monitor
├─ obstacle stop
├─ boundary constraint
├─ sensor health check
└─ degraded trigger
task_manager
├─ state machine
├─ mode switch
└─ task coordination
debug_tools
├─ parameter tuning
├─ route tools
└─ log export状态机设计
Beta 阶段至少应包含以下状态：
idle
ready
manual_assist
route_record
route_replay
pause
obstacle_stop
degraded_mode
fault_stop
task_complete状态机原则：
- 安全状态优先于任务状态
- 人工接管优先于自动执行
- 降级优先于继续冒险运行
- 不确定时停车
安全架构
安全优先级高于任务完成。
必须支持：
- 急停软件联动
- 障碍触发停车
- 边界越界保护
- 定位异常降级
- 传感器异常降级
- 通信异常降级
- 人工接管等待
- 故障停车
原则：
不确定就停
停车优先于绕行
本地安全优先于远程控制仓库与代码结构
建议仓库：
snowbot-navigation-beta建议目录：
/src
/config
/launch
/docs
/tests
/logs_sample
/replay_data
/handover必须提交：
- 源代码
- 配置文件
- 启动脚本
- 部署说明
- 接口文档
- 测试记录
- 已知问题清单
- 外部依赖清单
禁止：
- 只交二进制
- 只交 demo
- 隐藏核心逻辑
- 未披露 SDK / API / 云服务
- 未进入 ARCBOS GitHub 仓库
代码规范
要求：
- UTF-8 编码
- 英文目录名
- 英文文件名
- 英文变量名
- 英文函数名
- 英文代码注释
- README 可中英文，但英文优先
禁止：
- 中文变量名
- 拼音核心模块名
- 写死个人路径
- 写死账号、token、服务器地址
- 提交密钥或私钥
外部依赖约束
未经 ARCBOS 书面确认，不得引入：
- 外部 API
- 外部 SDK
- 在线地图服务
- 云日志服务
- 在线模型服务
- 依赖特定国家或地区服务器的服务
所有外部依赖必须披露：
- 名称
- 版本
- 来源
- 开源协议
- 是否可商用
- 是否联网
- 是否上传数据
- 是否影响北美部署
开发顺序
正确开发顺序：
1. 接口冻结
2. Alpha系统打通
3. 定位输入可用
4. 路线录制 / 回放
5. 路径跟踪
6. 障碍停车
7. 降级处理
8. 端到端联调
9. 文档与交接禁止：
- 先做复杂算法
- 先做云平台
- 先做自动回充
- 先做全局规划
- 在基础闭环未完成前做高级自治
里程碑映射
M1：接口与架构冻结
M2：Alpha补齐完成
M3：Beta路径执行可用
M4：障碍与安全可用
M5：整机联调与交付后续阶段路线图
Gamma 阶段可加入：
- SLAM / 建图
- 全局路径规划
- 区域覆盖算法
- 动态障碍识别
- 云端监控
Delta 阶段可加入：
- 自动回充
- 自动对桩
- 自恢复
- 长时间无人值守
Fleet / Service 阶段可加入：
- 多机协同
- Fleet Dashboard
- RaaS / SaaS
- SLA 管理
- 预测维护
最终原则
先系统打通
再任务闭环
后高级自治当前执行必须回到：
Alpha补齐 + Beta闭环