架构设计

FastBee-Arduino 采用“配置驱动 + 运行时门控”的嵌入式架构。Web/API 修改配置，核心模块加载配置并协调网络、协议、外设和规则；健康监控负责在资源紧张时降级高风险功能。

模块关系

启动顺序

1. 初始化串口、日志、LittleFS 和配置存储。
2. 检查芯片/Flash/PSRAM 资源，运行 FeatureBudget。
3. 加载 /config/features.json，应用依赖和用户开关。
4. 初始化 WiFi/AP、网络适配器和 Web/API 路由。
5. 网络就绪后初始化 MQTT、Modbus 和其他 requiresNetwork 功能。
6. 初始化外设驱动、规则引擎和任务调度，进入主循环。

网络依赖模块采用延迟初始化，避免 WiFi 启动峰值与 Modbus、I2C 传感器或脚本引擎同时分配内存。

核心模块

模块	职责	关键代码
FastBeeFramework	启动编排、依赖注入、服务生命周期	src/core/FastBeeFramework.cpp
RuntimeFeatureManager	注册功能、读取 features.json、依赖和状态	src/core/RuntimeFeatureManager.cpp
FeatureBudget	按 DRAM 水位拒绝重型功能，避免 OOM	include/core/FeatureBudget.h
NetworkManager	WiFi AP/STA、适配器切换、重连和 AP 回退	src/network/NetworkManager.cpp
WebConfigManager	路由注册、认证中间件、静态资源和限流	src/network/WebConfigManager.cpp
ProtocolManager	MQTT/Modbus 生命周期和数据分发	src/protocols/ProtocolManager.cpp
PeripheralManager	外设配置、引脚校验、驱动实例和读写	src/core/PeripheralManager.cpp
PeriphExecManager	触发器、条件、动作和执行结果	src/core/PeriphExecManager.cpp
HealthMonitor	堆、任务栈、网络和看门狗监控	src/systems/HealthMonitor.cpp

配置数据流

Web 表单/API
    ↓ 校验
RuntimeFeatureManager / ConfigStorage
    ↓ 原子写入
LittleFS /config/*.json
    ↓ 重启或按模块 reload
运行时对象与驱动
    ↓
MQTT 上报、SSE 推送、规则条件

配置保存采用临时文件、解析校验和替换，写入失败时保留旧文件。网络、设备、协议、外设、规则、功能和认证配置分别存放，便于备份与迁移。

功能门控

驱动调用 RuntimeFeatureManager::shouldEnable(key)，同时满足：

compiled AND userEnabled AND budgetPassed AND NOT runtimeDisabled

父功能关闭会级联关闭依赖功能，例如 lcd → lcdGb2312、ruleScript → commandScript。Web 页面显示的 compiled/userEnabled/active 字段来自同一注册表，不应另外维护一份能力矩阵。

网络与协议

• WiFi 是默认适配器；STA 失败时可回退 AP，后台探测恢复后再切回 STA。
• W5500 和 EC801E-CN 通过 INetworkAdapter 接口接入，需编译开关和外部硬件。
• MQTT 使用 ProtocolManager 统一发布/订阅；MQTTS 在同一 MQTT 栈中通过运行时功能开关控制。
• Modbus RTU 当前为主站，轮询结果进入外设缓存，可被规则和 MQTT 使用。

Web 与安全

• WebConfigManager 集中注册 /api/* 路由，具体处理器位于 src/network/handlers/。
• 管理 API 通过 WebHandlerContext 校验 Session/Cookie。/api/health、/api/system/capabilities、登录/会话探测及配网相关路由有各自的免认证边界，配网写入还受设备当前模式限制，详见API 参考。
• 静态资源来自 LittleFS，低内存时 WebMemoryGuard 对重型请求返回 503 和 Retry-After。
• SSE /api/events 用于传感器、Modbus、MQTT 状态推送；客户端需处理断线重连。

扩展原则

新增功能时应同时完成：

1. 在 FeatureFlags.h 定义编译开关，在 RuntimeFeatureManager 注册运行时功能和依赖。
2. 在对应模块增加资源预算、错误处理和低内存降级路径。
3. 在 Web/API、配置导入导出和 /api/system/capabilities 中保持同一命名。
4. 更新设备端文档、构建矩阵和测试矩阵。
5. 运行 native、设备 API 和浏览器冒烟测试。

开发入口见 项目结构、构建配置、API 参考 和 板卡能力与验证边界。