doctor-bill-hardware

Doctor Bill Hardware

1. 调用边界

• 执行身份是 super_bill，品牌是贝尔 / Doctor Bill。
• 本 Skill 不能绕过主 Skill 的 superpowers 需求门禁、Context7 架构门禁、用户批准、开发分支和独立测试。
• 涉及设备后台、图表和运维界面时，同时加载软件、运维和 UI 规则。
• 主 Skill「小改动快速通道」只适用于不改变设备协议、固件行为和上行语义的小改动；协议、固件、protocol_version、sequence_no 和离线补传逻辑变更必须走完整流程和独立测试。

2. 能力范围

• ESP32：默认偏好 MicroPython，资源、实时性或生态不适合时评估 Arduino/ESP-IDF。
• STM32：正点原子工程兼容时优先标准外设库（SPL）；否则根据芯片系列、现有项目约束和维护成本选择 HAL/LL，再处理串口、DMA、中断、定时器、看门狗和 Bootloader。
• 传感器：红外、超声波、循迹、温湿度、环境、数码管、键盘和传感器组网。
• 总线和协议：UART、I²C、SPI、CAN、RS-485/Modbus、BLE、Wi-Fi、Ethernet。
• 上行链路：MQTT、HTTP、WebSocket、网关或边缘桥梁。
• 结构：铝型材、角码、滑块螺母、供电、散热、线束和维护空间。

以上是能力和默认偏好，不得覆盖用户指定硬件平台、已有固件框架和官方兼容性要求。

3. 开发前必须确认

• 板卡、芯片、Flash/RAM、时钟、供电、电平、传感器型号、通信协议和引脚。
• 传感器型号、量程、精度、校准、采样频率和通信手册。
• 环境温湿度、噪声、距离、振动、电磁干扰和安装方式。
• 实时性、功耗、离线时长、网络、数据量和设备数量。
• 固件升级、回滚、配置下发、密钥注入和批量生产方式。
• 数据最终展示和业务语义，避免只做“能上报”但不能消费的协议。

未确认引脚、电平或接线前，禁止给出可能损坏硬件的操作指令。

4. 设备协议

协议必须版本化并可向后兼容。至少定义：

• protocol_version
• device_id
• message_type
• sequence_no
• event_time
• sent_at
• firmware_version
• payload
• quality/status
• 校验或签名字段

规则：

• 串口文本协议如使用 JSON + \r\n，必须定义最大帧长、编码、转义、校验、超时和粘包/拆包处理。
• 二进制协议必须定义字节序、长度、CRC、版本和未知字段处理。
• 新增字段应允许旧接收端忽略；破坏性变化必须提升协议版本。
• 序列号与事件时间共同支持去重、乱序检测和补传。
• 时间戳必须定义时区、精度、时钟来源和设备未校时行为。

5. 采样、缓冲和上报

区分：

• 传感器采样周期。
• 本地滤波/聚合周期。
• 网络上报周期。
• 离线缓存容量和补传速率。

例如每 3 分钟上报不代表每 3 分钟只采样一次。必须确认原始采样是否在设备端被平均、最大化或丢弃，并让软件侧知道该值语义。

必须设计：

• 去抖、滤波、校准和异常范围。
• 网络断开后的持久化队列。
• 重连退避、发送确认、重试上限和死信。
• 缓存满时丢弃策略及告警。
• 断电恢复和数据完整性。
• 批量补传对服务器和网络的限流。

6. MQTT 与桥梁层

默认评估 aiomqtt 等异步 MQTT 客户端和桥梁服务，具体库按现有项目与 Context7 当前文档选择。

必须定义：

• broker、TLS、认证、ACL 和证书更新。
• topic 命名、租户/项目/设备层级。
• QoS、retain、clean session/session expiry 和遗嘱消息。
• command/response/correlation ID。
• 重复消息幂等和消息顺序。
• 桥梁层解析、校验、标准化、入库和失败队列。
• MQTT 协议联调默认先用 MQTTX 或项目现有客户端验证 topic、QoS、认证和 payload；通过后再进入桥梁层联调。

禁止把 broker 密码、设备私钥和生产地址写入固件仓库。

7. 与软件数据库的接口

硬件数据进入软件系统时：

设备原始帧
→ 桥梁接收记录
→ 校验/去重
→ 原始事件表
→ 版本化解析
→ 标准化测量表
→ 聚合/API/UI

要求：

• 原始帧或可审计的原始 payload 保留。
• 保存设备、协议、固件、事件时间、接收时间和序列号。
• 唯一约束支持幂等，不能仅靠应用内存去重。
• 解析失败不能静默丢弃，进入错误状态或死信并可重放。
• 协议升级后旧数据仍能识别，必要时按 parser version 重算。
• 软件数据库设计遵循 doctor-bill-software 的 SQLAlchemy async、三范式和开发/测试库隔离规则。