Web_BLS_RCUAction_Server/docs/kafka_format.md

Kafka 推送格式与数据拆分规范

本文档定义了上游服务向 Kafka 推送消息的标准 JSON 格式。

核心变更：上游服务负责将原始报文解析为结构化的 JSON 对象。对于包含多个设备状态或故障信息的命令（如 0x36），上游必须将其转换为 JSON 数组，后端服务直接遍历这些数组进行入库，不再依赖对 udp_raw 的二次解析。

1. Kafka 基础信息

• Topic: blwlog4Nodejs-rcu-action-topic
• 分区数: 6
• 消息格式: JSON String

2. 消息结构定义 (Schema)

JSON 消息由 Header 信息 和 业务列表数据 组成。

2.1 顶层字段 (Header & 统计)

字段名	类型	必填	说明
ts_ms	Number	是	日志产生时间戳 (Key1)
hotel_id	Number	是	酒店 ID
room_id	String	是	房间 ID
device_id	String	是	设备 ID
direction	String	是	"上报" 或 "下发"
cmd_word	String	是	命令字 (如 "0x36", "0x0F")
frame_id	Number	是	通讯帧号
udp_raw	String	是	UDP 原始报文 (作为备份/校验)
sys_lock_status	Number	否	系统锁状态 (0:未锁, 1:锁定)
report_count	Number	否	上报设备数量 (对应 device_list 长度)
fault_count	Number	否	故障设备数量 (对应 fault_list 长度)
action_type	String	否	行为类型 (建议上游预填，或后端默认处理)
device_list	Array	否	设备状态列表 (结构见 2.2)
fault_list	Array	否	设备故障列表 (结构见 2.3)
control_list	Array	否	控制参数列表 (用于 0x0F)

2.2 设备状态对象 (Item in device_list)

对应 0x36 命令中的 P8~P13。

JSON 字段名	DB 映射字段	类型	说明
dev_type	dev_type	Number	设备类型
dev_addr	dev_addr	Number	设备地址
dev_loop	dev_loop	Number	设备回路
dev_data	dev_data	Number	设备状态

2.3 设备故障对象 (Item in fault_list)

对应 0x36 命令中的 P15~P20。

JSON 字段名	DB 映射字段	类型	说明
dev_type	dev_type	Number	故障设备类型 (复用 dev_type)
dev_addr	dev_addr	Number	故障设备地址 (复用 dev_addr)
dev_loop	dev_loop	Number	故障设备回路 (复用 dev_loop)
error_type	error_type	Number	故障类型
error_data	error_data	Number	故障内容

2.4 控制参数对象 (Item in control_list)

对应 0x0F 下发命令。

JSON 字段名	DB 映射字段	类型	说明
dev_type	dev_type	Number	控制设备类型
dev_addr	dev_addr	Number	控制设备地址
loop	dev_loop	Number	控制设备的回路地址 (复用 dev_loop)
type_l	type_l	Number	执行方式
type_h	type_h	Number	执行内容

---

3. 后端入库逻辑

后端服务接收到 JSON 后，逻辑简化为：

1. 遍历 device_list: 为数组中每个对象生成一条 DB 记录。
   • 映射：dev_type -> dev_type, dev_addr -> dev_addr, dev_loop -> dev_loop, dev_data -> dev_data。
   • action_type: "36上报"。
2. 遍历 fault_list: 为数组中每个对象生成一条 DB 记录。
   • 映射：dev_type -> dev_type, dev_addr -> dev_addr, dev_loop -> dev_loop, error_type -> error_type, error_data -> error_data。
   • action_type: "36上报"。
3. 遍历 control_list: 为数组中每个对象生成一条 DB 记录。
   • 映射：dev_type -> dev_type, dev_addr -> dev_addr, loop -> dev_loop, type_l -> type_l, type_h -> type_h。
   • action_type: "0F下发"。

---

4. 参考 JSON 示例

4.1 0x36 混合上报 (2个设备状态 + 1个故障)

{
  "ts_ms": 1706428800123,
  "hotel_id": 1001,
  "room_id": "8001",
  "device_id": "dev_001",
  "direction": "上报",
  "cmd_word": "0x36",
  "frame_id": 1001,
  "udp_raw": "3601...",
  "sys_lock_status": 1,
  "report_count": 2,
  "fault_count": 1,
  "device_list": [
    {
      "dev_type": 1,
      "dev_addr": 10,
      "dev_loop": 1,
      "dev_data": 100
    },
    {
      "dev_type": 1,
      "dev_addr": 11,
      "dev_loop": 2,
      "dev_data": 0
    }
  ],
  "fault_list": [
    {
      "dev_type": 1,
      "dev_addr": 10,
      "dev_loop": 1,
      "error_type": 1,
      "error_data": 1
    }
  ]
}

4.2 0x0F 下发控制 (包含多个控制指令)

{
  "ts_ms": 1706428805000,
  "hotel_id": 1001,
  "room_id": "8001",
  "direction": "下发",
  "cmd_word": "0x0F",
  "frame_id": 1002,
  "udp_raw": "0F...",
  "action_type": 2,
  "control_list": [
    {
      "dev_type": 1,
      "dev_addr": 10,
      "loop": 1,
      "type_l": 0,
      "type_h": 1
    }
  ],
  "details": {
    "full_control_data": "..." 
  }
}