# 设备数据采集与上报协议完整文档

> 版本：v1.0  更新日期：2025-11-19
### 1. service.conf 采集项下发（平台 → 设备）
```json
[
    {
        "host_uuid": "qbxmjyzrkpntfgswaevodhluicqzxplkm",
        "device_uuid": "deviceuuid1",
        "task_id": "6588",
        "address": "房间东侧",
        "type": "2",
        "facility": "01"
    },
    {
        "host_uuid": "qbxmjyzrkpntfgswaevodhluicqzxplkm",
        "device_uuid": "deviceuuid2",
        "task_id": "6589",
        "address": "房间南侧",
        "type": "1",
        "facility": "02"
    },
    {
        "host_uuid": "qbxmjyzrkpntfgswaevodhluicqzxplkm",
        "device_uuid": "deviceuuid3",
        "task_id": "6590",
        "address": "房间西侧",
        "type": "smog",
        "facility": "03"
    }
]
```
字段名       | 类型   | 必填 | 说明                               | 示例值
-------------|--------|------|------------------------------------|--------------------------------------
host_uuid    | string | 是   | 网关/采集主机唯一ID                | qbxmjyzrkpntfgswaevodhluicqzxplkm
device_uuid  | string | 是   | 传感器设备唯一ID                   | deviceuuid1
task_id      | string | 是   | 平台任务ID，用于追踪和撤销         | 6588
address      | string | 是   | 安装位置描述                       | 房间东侧
type         | string | 是   | 传感器类型                         | "1"→温湿度，"2"→水浸传感器，"3"→烟雾
facility     | string | 是   | 设施点位编码（固定2位）            | 01、02、03
### 2. 上报数据（metric_data）
```json
{
    "method": "metric_data",
    "params": {
        "route_key": "/dthjjc/device/3eeba8usb86c0gs448oktxay41a0rm1v/data",
        "metric": {
            "type": "data",
            "args": [
                {
                    "deviceuuid": "deviceuuid1",
                    "type": "1",
                    "facility": "2",
                    "address": "房间东侧",
                    "value":  { "temp": "25.3", "humidity": "12.5" } 
                },
                {
                    "deviceuuid": "deviceuuid2",
                    "type": "2",
                    "facility": "1",
                    "address": "房间南侧",
                    "value": "0"
                },
                {
                    "deviceuuid": "deviceuuid3",
                    "type": "3",
                    "facility": "3",
                    "address": "房间西侧",
                    "value": "0"
                }
            ]
        }
    }
}
```
层级                    | 字段名        | 类型            | 必填 | 说明
------------------------|---------------|-----------------|------|-----------------------------------------
根对象                  | method        | string          | 是   | 固定值 "metric_data"
params                  | route_key     | string          | 是   | 格式：/dthjjc/device/{host_uuid}/data
params.metric           | type          | string          | 是   | 固定值 "data"
params.metric.args      | -             | array           | 是   | 每项对应一个设备
args[i]                 | deviceuuid    | string          | 是   | 设备唯一ID
args[i]                 | type          | string          | 是   | 传感器类型
args[i]                 | facility      | string          | 是   | 设施编码（两位）
args[i]                 | address       | string          | 是   | 安装位置
args[i]                 | value         | string/array    | 是   | 实际值，格式见下表

value 格式对照表
type   | 传感器类型     | value 类型      | 示例值                                    | 说明
-------|----------------|----------------|-------------------------------------------|----------------------
1      | 温湿度传感器   | array[object]  | [{"temp":"25.3","humidity":"12.5"}]      | 必须包含temp和humidity
2      | 水浸传感器  | string         | "0" 或 "1"                                | 0=正常 1=报警
3/smog | 烟雾传感器     | string         | "0" 或 "1"                                | 0=正常 1=报警

### 3. 上报事件（event_data）

# 3.1 离线报警示例
```json
{
    "method": "event_data",
    "params": {
        "route_key": "/dthjjc/device/deviceuuid3/event",
        "metric": {
            "type": "event",
            "args": {
                "description": "The sensor is offline",
                "timestamp": "1763544662",
                "host_uuid": "qbxmjyzrkpntfgswaevodhluicqzxplkm",
                "device_uuid": "device3",
                "level": "alarm",
                "last_successful_time": "1763544625",
                "sensor_type": "SmokeTransducer(3)",
                "recommendation": "Check device connection and communication line"
            }
        }
    }
}
```
# 3.2 恢复在线示例
```json
{
    "method": "event_data",
    "params": {
        "route_key": "/dthjjc/device/deviceuuid3/event",
        "metric": {
            "type": "event",
            "args": {
                "description": "Sensor online",
                "timestamp": "1763544662",
                "host_uuid": "qbxmjyzrkpntfgswaevodhluicqzxplkm",
                "device_uuid": "device3",
                "level": "online",
                "sensor_type": "SmokeTransducer(3)"
            }
        }
    }
}

```
# 3.3 首次执行采集任务之后上报状态
```json
{
    "method": "metric_data",
    "params": {
        "metric": {
            "args": {
                "description": "Environmental detection system started successfully",
                "timestamp": "1763644447",
                "host_uuid": "pemsyszrkpntfgswaevodhluicqzxplkm",
                "level": "system_start",
                "device_count": 3,
                "online_count": 3
            },
            "type": "event"
        },
        "route_key": "/dthjjc/device/pemsyszrkpntfgswaevodhluicqzxplkm/event"
    }
}
```

event_data 通用字段说明
字段名                | 类型   | 必填 | 说明
----------------------|--------|------|-------------------------------------------
description           | string | 是   | 事件描述
timestamp             | string | 是   | UNIX 时间戳（秒）
host_uuid             | string | 是   | 主机UUID
device_uuid           | string | 是   | 设备UUID
level                 | string | 是   | alarm / online  等
last_successful_time  | string | 否   | 仅离线时填写
sensor_type           | string | 否   | 传感器类型描述
recommendation        | string | 否   | 处理建议
device_count          | string | 否   | 检测设备数量
online_count          | string | 否   | 当前在线数量

### 4. 协议总览

上报类型     | method         | route_key 后缀 | 说明
-------------|----------------|----------------|------------------------------------
普通数据上报 | metric_data    | /data          | 定时上报温湿度、水浸传感器、烟雾等数值
事件上报     | event_data     | /event         | 设备离线、恢复在线、报警等事件