commit 045e3bd941f0e35df66b9a98f6bd11e9e2900014
Author: guoqiancheng <guoqiancheng@aioe.tech>
Date:   Wed Nov 19 19:49:18 2025 +0800

    上传文件至 /

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..67666c2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,156 @@
+# 设备数据采集与上报协议完整文档
+
+> 版本：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)"
+            }
+        }
+    }
+}
+```
+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 | 否   | 处理建议
+
+### 4. 协议总览
+
+上报类型     | method         | route_key 后缀 | 说明
+-------------|----------------|----------------|------------------------------------
+普通数据上报 | metric_data    | /data          | 定时上报温湿度、水浸传感器、烟雾等数值
+事件上报     | event_data     | /event         | 设备离线、恢复在线、报警等事件
\ No newline at end of file