# ws_channel 模块 API 文档与交互逻辑

## 注意websocket的数据格式为: text

## 一、模块概述
`ws_channel` 是基于 Erlang + Cowboy WebSocket 实现的 MQTT 相关交互模块，主要用于服务注册、主题订阅、指标数据上报、事件发送及消息广播等功能，通过 WebSocket 协议实现客户端与服务端的实时双向通信。


## 三、核心 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. 连接关闭（主动断开或异常终止）