iot-integration

name	iot-integration
description	接入层（Tap）集成模式：MQTT Tap、Webhook Tap、Shifu 可选连接器；统一 Event Envelope、幂等/DLQ。编写设备接入代码时使用。见 ADR-0016。

接入层（Tap）集成模式

接入 = 可插拔 Tap 层：连接器镜像不变的端侧流 → 统一 Event Envelope，behind 统一可切换接口（ADR-0016）。所有连接器幂等 + DLQ 在边界。

连接器 A：MQTT Tap（默认，多数旁路客户）

• 作为新 MQTT Client 共享订阅现有 Broker 的 topic（$share/grp/topic），不侵入
• 需客户提供 Broker 地址 + ACL 放行
• 收到消息 → Event Normalizer → 统一 Event Envelope

连接器 B：Webhook Tap

• 端点：POST /webhooks/iot-event
• 鉴权：HMAC-SHA256（X-IoT-Webhook-Signature header），secret 来自 Infisical（逐 Tenant，绝不进源码，ADR-0014）
• Schema：见下 Event Envelope（Zod 校验）
• 幂等：Redis SET NX EX 24h on eventId + SQL UNIQUE (raw_event_id)
• DLQ：dispatch 失败的 event 入 Redis list

连接器 C：Shifu（可选，工业协议/K8s 客户）

• 非默认——仅当客户需边缘工业协议适配（OPC UA/Modbus/RTSP…）或 K8s 数字孪生
• EdgeDevice CRD → DeviceShifu Pod 归一协议为事件 → 经本连接器入 Event Envelope
• 在 Tap 接口后可替换（Neuron / PLC4X / Telegraf）
• Shifu 边缘 twin 与服务端 Twin（ADR-0010）互补：边缘归一协议，服务端镜像状态

连接器 D：CDC Tap（将来）

• 对客户现有 DB 做变更捕获（Debezium + outbox）

Event Envelope 规范（所有连接器一致）

{
  eventId: string,    // UUID v7
  tenantId: string,
  accountId: string,  // 数据归属单元 = 隔离边界（ADR-0004）
  deviceId: string,
  eventType: string,  // 通用，按场景 Zod enum（非鸟种专用）
  timestamp: string,  // ISO 8601
  payload: unknown    // 原生 payload
}

userId 可选：无人参与的纯设备链路不带。Event Envelope 是 Twin（状态镜像）与 Telemetry Store（时序）的输入。