water/server/docs/WATER_DEVICE_INTEGRATION.md

供水设备接入预留（2026-09-10）

目前没有厂商设备协议，HTTP 和 MQTT 供水接入默认关闭，协议适配器为空。不生成模拟在线状态，不自动注册设备，不操作库存、套餐权益或配送任务。

预留入口

• HTTP：POST /iot/water/report，控制器 app/controller/WaterDeviceController.php。关闭时返回 HTTP 503 和 {"code":503,"message":"设备 HTTP 接口尚未启用","data":null}。
• MQTT：原 MqttSubscriber 接收消息后发送 mqtt.message 事件；config/event.php 注册 DeviceIngress::mqtt，供水开关关闭时直接忽略，不改变原 MQTT 订阅、发布和重连逻辑。
• 协议接口：app/service/water/DeviceProtocolAdapter.php。未来实现 fromHttp(body,headers) / fromMqtt(topic,payload,properties)，把厂商数据转换成内部报告；不相关消息返回 null。
• 内部处理：app/service/water/DeviceReport.php，仅接受已登记 SN，并检查关联企业、规格启用状态。无需新增数据库表。

内部报告约定

以下是服务端内部格式，不是对设备厂商协议的预设。暂不提供可直接启用的厂商适配器。

{
  "sn": "已登记设备SN",
  "kind": "heartbeat",
  "reported_at": "2026-09-10 12:00:00"
}

• kind=heartbeat：仅更新 sa_water_device.last_seen。时间为北京时间 Y-m-d H:i:s，必须在最近5分钟内且不晚于服务端当前时间。重复、较旧时间不刷新在线状态。
• kind=usage：额外提供 today_liters（当日累计用水升数，非本次增量，最多两位小数）。仅接收当天报告，同行锁下同日取累计最大值，跨日从新累计值开始；重复或乱序较小值不重复累加。
• 总览沿用最近15分钟 last_seen 判断在线。设备的 today_liters 与 telemetry_date 驱动“今日用水”，不计算账户 daily_liters 或补货预测。
• 心跳和用量可以使用同一秒时间；用量更新独立于心跳去重。
• 未知 SN 返回404；非法报告或停用关联档案返回422。HTTP 无效接入令牌返回401，超16KB返回413，未配置适配器返回503。MQTT 失败仅写简短错误码，不写原始消息或凭据。

2026-09-11 日用水历史

新增 sa_water_device_usage 和 WaterDeviceUsage 模型，部署先执行 php scripts/migrate_water_device_usage.php --apply。DeviceReport 在原设备行锁/事务内写入设备当日累计最大值，同日重复或乱序较小报告不累加，跨日保留旧记录。看板30日趋势使用该表；无报告日期保留空缺，不补造往日数据。HTTP/MQTT默认关闭和适配器为空的边界不变。详情参见 WATER_DEVICE_DASHBOARD.md。

拿到设备后需要补齐

1. Broker 地址、TLS、认证及 ACL，订阅和下发 Topic，SN 与连接身份的对应关系。
2. 心跳频率、时间格式及时区、留存消息行为、离线遗嘱、消息唯一编号、序号与重放规则。
3. 用水量单位、增量/累计口径、设备重启清零及跨日规则；换桶、故障、控制指令和确认报文。
4. 实现厂商适配器，在适配层验证签名/设备身份及 Topic/SN 绑定，并过滤留存、重放及无关消息。不要把历史消息的接收时间伪装成最新设备心跳。仅有增量数据时，先补持久化去重与聚合，不能直接映射为累计用量。
5. 在 config/water_device.php 填写可信的适配器类名并测试，再启用所需通道。HTTP 当前预留给可信设备网关，使用独立的至少32字符 WATER_DEVICE_HTTP_TOKEN（Bearer 头，通过HTTPS传输），不复用管理员JWT；若设备直连，须按真实协议补设备级鉴权。
6. HTTP 使用 WATER_DEVICE_HTTP_ENABLED，MQTT 使用 WATER_DEVICE_MQTT_ENABLED，MQTT 还需原 MQTT_ENABLED 和 Broker 配置。Windows 需重启相关 HTTP/MQTT 进程加载配置。

验证

php tests/water_device_ingress_test.php：30项检查通过，覆盖默认关闭、认证、适配器缺失、消息大小、心跳在线、重复/乱序/过期/未来时间、日累计幂等与跨日、无关Topic及库存权益隔离。数据库测试全部回滚，不启用实际网关或连接 Broker。

HTTP/MQTT 的真实设备收发、身份校验、重放防护和离线协议，待拿到设备后按上述清单联调。

本地验证：php webman route:list 已列出 POST 路由；重启本项目 HTTP 子进程后，实际请求 http://127.0.0.1:8787/iot/water/report 返回 HTTP503。原有 php tests/water_business_test.php 69项也通过，测试数据均回滚。MQTT 通道继续关闭，未来启用时需重启对应进程加载事件配置。