# BACnet HTTP 接口说明

## 目标

本服务通过 HTTP 接口连接 BACnet/IP 设备。BACnet 功能使用 `BAC0` 实现，当前提供点位读取和点位搜索。

当前仅支持 `BACnet/IP`。

## 接口列表

- `POST /api/dc-gateway/bacnet/read_points`：按点位对象读取，固定返回 `present-value`。
- `POST /api/dc-gateway/bacnet/search_points`：读取设备 `object-list`，搜索常见 BACnet 点位对象并返回基础信息和值。
- `GET /api/dc-gateway/health`：健康检查。

## 通用返回约定

接口业务结果统一使用 HTTP `200` 返回，是否成功由 JSON 中的 `code` 判断。

成功：

```json
{
  "code": 0,
  "msg": "success",
  "data": {}
}
```

失败：

```json
{
  "code": 1,
  "msg": "BACnet communication error",
  "data": {
    "points": []
  }
}
```

字段说明：

| 字段 | 类型 | 说明 |
|---|---|---|
| `code` | integer | `0` 表示成功，`1` 表示失败。 |
| `msg` | string | 成功时为 `success`，失败时为错误信息。 |
| `data` | object | 接口数据。 |

`data` 固定为对象。两个 BACnet 接口都会在 `data.device` 返回设备信息，点位列表返回在 `data.points`。

## 设备参数校验

以下字段用于 `/bacnet/read_points` 和 `/bacnet/search_points` 请求体顶层。

| 字段 | 是否必传 | 默认值 | 校验 | 说明 |
|---|---:|---|---|---|
| `ip` | 是 | 无 | 必须是合法 IP 地址 | BACnet/IP 设备地址。 |
| `bacnet_device_id` | 是 | 无 | `0..4194303` | BACnet 设备对象实例号。 |
| `port` | 否 | `47808` | `1..65535` | BACnet/IP UDP 端口。 |

响应中的设备信息固定包含：

```json
{
  "device_type": "BACnet/IP",
  "ip": "192.168.75.240",
  "port": 47808,
  "bacnet_device_id": 12345
}
```

## 对象类型

请求中的 `object_type` 支持常见写法，例如 `AnalogInput`、`analogInput`、`analog-input`。响应统一返回 `AnalogInput` 这类格式。

常见点位对象类型：

| 响应值 | BACnet 含义 |
|---|---|
| `AnalogInput` | 模拟输入 |
| `AnalogOutput` | 模拟输出 |
| `AnalogValue` | 模拟值 |
| `BinaryInput` | 二进制输入 |
| `BinaryOutput` | 二进制输出 |
| `BinaryValue` | 二进制值 |
| `MultiStateInput` | 多状态输入 |
| `MultiStateOutput` | 多状态输出 |
| `MultiStateValue` | 多状态值 |

`/bacnet/search_points` 只返回上表中的常见点位对象类型。`/bacnet/read_points` 可按对象类型读取 `present-value`，但目标对象必须支持该属性。

## 接口一：读取点位

### URL

```http
POST /api/dc-gateway/bacnet/read_points
```

### 请求体

`read_points` 固定读取每个对象的 `present-value`。

```json
{
  "ip": "192.168.75.240",
  "bacnet_device_id": 12345,
  "port": 47808,
  "points": [
    {
      "object_type": "AnalogInput",
      "object_id": 1
    }
  ]
}
```

字段说明：

| 字段 | 类型 | 必填 | 校验 | 说明 |
|---|---|---:|---|---|
| `points` | object[] | 是 | 至少 1 个点位 | BACnet 点位对象列表。 |
| `points[].object_type` | string | 是 | 合法 BACnet 对象类型写法 | BACnet 对象类型。 |
| `points[].object_id` | integer | 是 | `0..4194303` | BACnet 对象实例号。 |

### 成功返回

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "device": {
      "device_type": "BACnet/IP",
      "ip": "192.168.75.240",
      "port": 47808,
      "bacnet_device_id": 12345
    },
    "points": [
      {
        "object_type": "AnalogInput",
        "object_id": 1,
        "present_value": 12.3
      }
    ]
  }
}
```

### 失败返回

设备通信失败：

```json
{
  "code": 1,
  "msg": "No response from BACnet device",
  "data": {
    "device": {
      "device_type": "BACnet/IP",
      "ip": "192.168.75.240",
      "port": 47808,
      "bacnet_device_id": 12345
    },
    "points": []
  }
}
```

请求字段校验失败：

```json
{
  "code": 1,
  "msg": "points: List should have at least 1 item after validation, not 0",
  "data": {
    "points": []
  }
}
```

## 接口二：搜索点位

### URL

```http
POST /api/dc-gateway/bacnet/search_points
```

### 请求体

搜索点位只需要设备信息。服务会读取设备对象的 `object-list`，并过滤常见点位对象类型。

```json
{
  "ip": "192.168.75.240",
  "bacnet_device_id": 12345,
  "port": 47808
}
```

### 成功返回

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "device": {
      "device_type": "BACnet/IP",
      "ip": "192.168.75.240",
      "port": 47808,
      "bacnet_device_id": 12345
    },
    "points": [
      {
        "name": "Zone Temperature",
        "description": "Room temperature",
        "object_type": "AnalogInput",
        "object_id": 1,
        "present_value": 24.5
      }
    ]
  }
}
```

搜索每个点位时读取以下属性：

| 返回字段 | BACnet 属性 |
|---|---|
| `name` | `object-name` |
| `description` | `description` |
| `present_value` | `present-value` |

单个点位的 `description` 或 `present_value` 读取失败时，该字段返回 `null`，不会中断整个搜索。设备连接或 `object-list` 读取失败时，接口返回 `code=1`。

### 失败返回

```json
{
  "code": 1,
  "msg": "No response from BACnet device",
  "data": {
    "device": {
      "device_type": "BACnet/IP",
      "ip": "192.168.75.240",
      "port": 47808,
      "bacnet_device_id": 12345
    },
    "points": []
  }
}
```

## 本地 BACnet 客户端绑定

网关会为每次 BACnet 请求启动本地 BACnet 客户端，并自动推断到目标设备的本机地址。可通过环境变量覆盖：

| 字段 | 默认值 | 说明 |
|---|---|---|
| `BACNET_LOCAL_IP` | 自动按到目标设备的路由推断 | 本地 BACnet 客户端绑定 IP。 |
| `BACNET_LOCAL_MASK` | `24` | 本地 BACnet 客户端网络掩码位数。 |
| `BACNET_LOCAL_PORT` | 自动选择空闲 UDP 端口 | 本地 BACnet 客户端绑定 UDP 端口。 |

## 测试默认设备

BACnet 集成测试默认设备参数：

| 字段 | 默认值 |
|---|---|
| `BACNET_DEVICE_IP` | `192.168.75.240` |
| `BACNET_DEVICE_ID` | `12345` |
| `BACNET_PORT` | `47808` |