add文档

README.md

@@ -1,13 +1,127 @@
-efka
+# ws_channel 模块 API 文档与交互逻辑
-=====
 
-An OTP application
+## 注意websocket的数据格式为: text
 
-1. 先解决数据的上行问题
+## 一、模块概述
-2. todo list
+`ws_channel` 是基于 Erlang + Cowboy WebSocket 实现的 MQTT 相关交互模块，主要用于服务注册、主题订阅、指标数据上报、事件发送及消息广播等功能，通过 WebSocket 协议实现客户端与服务端的实时双向通信。
-    要解决连接断开重新连接的问题 !!!
 
-Build
------
 
-    $ rebar3 compile
+## 三、核心 API 方法
+客户端通过发送 **JSON 格式文本消息** 与服务端交互，消息格式遵循 JSON-RPC 风格（包含 `id`、`method`、`params` 字段）。
+
+
+### 1. 服务注册（register）
+#### 功能
+注册服务并建立客户端与服务进程的关联，是后续操作（订阅、上报数据等）的前提。
+
+#### 请求格式
+```json
+{
+  "id": <整数，请求唯一标识>,
+  "method": "register",
+  "params": {
+    "service_id": <二进制，服务唯一标识，必填>,
+    "meta_data": <映射，服务元数据，可选>,
+    "container_name": <二进制，容器名称，可选>
+  }
+}
+```
+
+#### 响应格式
+- 成功响应：
+  ```json
+  {
+    "id": <与请求id一致>,
+    "result": "ok"
+  }
+  ```
+- 失败处理：服务端直接关闭连接（因 `attach_channel` 失败）
+
+### 2. 主题订阅（subscribe）
+#### 功能
+订阅指定主题，后续可接收该主题的广播消息。
+
+#### 请求格式
+```json
+{
+  "id": <整数，请求唯一标识>,
+  "method": "subscribe",
+  "params": {
+    "topic": <二进制，订阅的主题名称，必填>
+  }
+}
+```
+
+#### 响应格式
+- 成功响应：
+  ```json
+  {
+    "id": <与请求id一致>,
+    "result": "ok"
+  }
+  ```
+- 失败响应：
+  ```json
+  {
+    "id": <与请求id一致>,
+    "error": {
+      "code": -1,
+      "message": "错误描述"
+    }
+  }
+  ```
+
+#### 处理逻辑
+通过 `efka_subscription:subscribe(Topic, self())` 完成订阅，订阅成功后客户端会收到该主题的广播消息。
+
+
+### 3. 指标数据上报（metric_data）
+#### 功能
+向服务进程上报设备指标数据。
+
+#### 请求格式
+```json
+{
+  "method": "metric_data",
+  "params": {
+    "device_uuid": <二进制，设备唯一标识，必填>,
+    "route_key": <二进制，路由键，必填>,
+    "metric": <指标数据，必填>
+  }
+}
+```
+
+#### 响应处理
+服务端接收后无返回消息（处理逻辑：`efka_service:metric_data(ServicePid, DeviceUUID, RouteKey, Metric)`）
+
+
+### 4. 事件发送（event）
+#### 功能
+向服务进程发送事件消息。
+
+#### 请求格式
+```json
+{
+  "method": "event",
+  "params": {
+    "event_type": <二进制，事件类型，必填>,
+    "body": <事件内容，必填>
+  }
+}
+```
+
+## 五、基础交互协议
+1. **Ping/Pong 心跳**：
+    - 客户端发送 `ping` 消息
+    - 服务端回复 `pong` 消息，维持连接
+
+2. **未知消息处理**：
+    - 客户端发送未定义格式的消息时，服务端记录错误并关闭连接
+
+## 七、典型交互流程
+1. 客户端发起 WebSocket 连接
+2. 客户端发送 `register` 请求完成注册
+3. 客户端发送 `subscribe` 请求订阅目标主题
+4. 客户端通过 `metric_data` 上报指标数据 / 通过 `event` 发送事件
+5. 服务端向客户端推送已订阅主题的消息（`publish` 方法）
+6. 连接关闭（主动断开或异常终止）