# 数据管理模块 — 开发规格说明

> 本文档属于《污水厂智能控制平台》的一部分，详细描述数据管理模块的功能、数据模型、API接口和业务逻辑，细度可达直接开发级别。

---

## 目录

- [1. 概述](#1-概述)
- [2. 设备管理](#2-设备管理)
- [3. 数据采集点管理](#3-数据采集点管理)
- [4. 数据写入点管理](#4-数据写入点管理)
- [5. 采集引擎（运行时）](#5-采集引擎运行时)
- [6. 写入引擎（运行时）](#6-写入引擎运行时)
- [7. 协议插件化架构](#7-协议插件化架构)

---

## 1. 概述

### 1.1 模块定位

本模块是平台的数据基础层，负责：
- 管理PLC设备及其连接配置
- 定义数据采集点位（从PLC读取数据）
- 定义数据写入点位（向PLC写入控制指令）
- 运行时执行数据采集任务，将数据写入TDengine
- 运行时执行控制指令下发任务

### 1.2 模块边界

| 交互对象 | 方向 | 内容 |
|----------|------|------|
| Web前端 | 双向 | 设备/点位CRUD、实时数据展示、控制指令下发 |
| TDengine | 单向写入 | 采集到的时序数据 |
| PostgreSQL | 双向 | 设备配置、点位配置、操作日志 |
| PLC设备 | 双向 | 读取寄存器、写入寄存器 |

### 1.3 核心概念关系

```
设备 (Device)                  ← 一个物理PLC或Modbus设备
 ├── 采集点 (CollectPoint)     ← 从该设备读取的测点（N个）
 └── 写入点 (WritePoint)       ← 向该设备写入的测点（M个）

采集点 ≠ 写入点，两者分开管理，独立配置。
```

---

## 2. 设备管理

### 2.1 数据模型

#### 2.1.1 数据库表：devices

```sql
CREATE TABLE devices (
    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name                VARCHAR(128) NOT NULL,
    protocol_type       VARCHAR(32) NOT NULL,
    enabled             BOOLEAN NOT NULL DEFAULT TRUE,
    deleted             BOOLEAN NOT NULL DEFAULT FALSE,
    
    -- 网络连接参数
    host                VARCHAR(256) NOT NULL,
    port                INTEGER NOT NULL,
    connect_timeout     INTEGER NOT NULL DEFAULT 5,       -- 连接超时，单位秒
    reconnect_interval  INTEGER NOT NULL DEFAULT 10,       -- 断线重连间隔，单位秒
    
    -- 协议级配置（JSON格式，由协议驱动自行解析）
    protocol_config     JSONB NOT NULL DEFAULT '{}',
    
    created_at          TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
    updated_at          TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
    created_by          VARCHAR(64),
    updated_by          VARCHAR(64)
);

-- 名称唯一（逻辑删除的记录不参与唯一约束）
CREATE UNIQUE INDEX idx_devices_name ON devices(name) WHERE deleted = FALSE;
```

#### 2.1.2 协议类型枚举

| 协议类型标识 | 说明 | 当前状态 |
|-------------|------|---------|
| `S7` | 西门子S7协议 | 已支持 |
| `MODBUS_TCP` | Modbus TCP协议 | 已支持 |
| （后续扩展） | 新增协议通过插件机制添加 | 待扩展 |

#### 2.1.3 各协议 protocol_config 定义

**S7协议**：

```json
{
    "rack": 0,
    "slot": 1
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| rack | int | 是 | PLC机架号，默认0 |
| slot | int | 是 | PLC插槽号，默认1 |

**Modbus TCP协议**：

```json
{
    "unit_id": 1,
    "byte_order": "ABCD",
    "word_order": "AB"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| unit_id | int | 是 | Modbus从站地址（站号），范围1~247 |
| byte_order | string | 是 | 32位浮点数（REAL）的字节序，详见下文 |
| word_order | string | 是 | 32位浮点数（REAL）的字序，详见下文 |

**byte_order 和 word_order 说明**：

对于Modbus中占用2个寄存器的REAL类型（32位浮点数），解析时需指定字节顺序：

| byte_order | 说明 | 示例（4字节: 0x41 0xA0 0x00 0x00） |
|------------|------|--------------------------------------|
| `ABCD` | 大端序（默认） | 41A00000 → 20.0 |
| `BADC` | 字节交换 | A0410000 → 乱码（通常不推荐） |
| `CDAB` | 字内字节交换 | 000041A0 → 20.0（某些PLC的格式） |
| `DCBA` | 小端序 | 0000A041 → 乱码（通常不推荐） |

| word_order | 说明 | 示例（4字节: 0x41 0xA0 0x00 0x00） |
|------------|------|--------------------------------------|
| `AB` | 正常字序 | 寄存器1=41A0, 寄存器2=0000 → 20.0 |
| `BA` | 字交换 | 寄存器1=0000, 寄存器2=41A0 → 20.0（某些PLC的格式） |

**最终解析公式**：按照 `word_order` 决定字的排列，再按 `byte_order` 决定每个字内的字节顺序。

#### 2.1.4 设备的业务状态

**持久化状态（数据库）**：

| 状态 | 说明 |
|------|------|
| enabled=true | 设备启用，采集引擎会为该设备建立连接并执行采集任务 |
| enabled=false | 设备禁用，采集引擎跳过该设备，已有连接断开 |
| deleted=true | 逻辑删除，数据保留但不再显示和使用 |

**运行时连接状态（采集引擎内存维护，不落库）**：

| 连接状态 | 枚举值 | 说明 |
|---------|--------|------|
| 连接成功 | `connected` | 设备已启用（enabled=true）且与PLC连接成功，可正常采集 |
| 连接失败 | `disconnected` | 设备已启用（enabled=true）但连接断开或连接失败（初次连接或重连均失败） |
| 连接禁用 | `disabled` | 设备未启用（enabled=false），不进行连接。采集引擎不维护该设备的连接状态 |

说明：
- `connection_status` 是运行时状态，由采集引擎维护在内存中，**不存储到数据库**
- 设备逻辑删除（deleted=true）时，在接口响应中表现为 `disabled`
- 采集引擎未运行时，所有 enabled=true 的设备均返回 `disconnected`

### 2.2 RESTful API

#### 2.2.1 接口列表

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/devices | 获取设备列表（支持分页、搜索、按协议筛选） |
| POST | /api/v1/devices | 新增设备 |
| GET | /api/v1/devices/{id} | 获取单个设备详情 |
| PUT | /api/v1/devices/{id} | 修改设备 |
| DELETE | /api/v1/devices/{id} | 逻辑删除设备 |
| POST | /api/v1/devices/export | 导出设备列表为CSV |
| POST | /api/v1/devices/import | 从CSV文件导入设备 |
| GET | /api/v1/devices/protocols | 获取当前支持的所有协议类型列表 |

#### 2.2.2 接口详细定义

**POST /api/v1/devices** — 新增设备

Request body：

```json
{
    "name": "一期曝气柜PLC",
    "protocol_type": "S7",
    "host": "192.168.1.100",
    "port": 102,
    "connect_timeout": 5,
    "reconnect_interval": 10,
    "protocol_config": {
        "rack": 0,
        "slot": 1
    }
}
```

Response (201)：

```json
{
    "code": 0,
    "message": "success",
    "data": {
        "id": "uuid-string",
        "name": "一期曝气柜PLC",
        "protocol_type": "S7",
        "enabled": true,
        "host": "192.168.1.100",
        "port": 102,
        "connect_timeout": 5,
        "reconnect_interval": 10,
        "protocol_config": {
            "rack": 0,
            "slot": 1
        },
        "created_at": "2026-07-09T10:00:00+08:00",
        "updated_at": "2026-07-09T10:00:00+08:00"
    }
}
```

校验规则：
- name：必填，1~128字符，不可重复（逻辑删除的记录不参与唯一性校验）
- protocol_type：必填，必须是当前系统支持的协议类型
- host：必填，合法的IP地址或域名
- port：必填，1~65535
- connect_timeout：可选，默认5，范围1~60
- reconnect_interval：可选，默认10，范围1~3600
- protocol_config：必填，根据protocol_type不同，校验规则不同

**PUT /api/v1/devices/{id}** — 修改设备

- 与新增使用相同的请求体结构
- 修改后，如果设备正在运行中，采集引擎应自动重新连接
- 如果修改了 enabled 字段（启用/禁用），响应中的 `connection_status` 同步变化：
  - 从 enabled=false 改为 true → 采集引擎尝试连接，`connection_status` 在异步连接完成前为 `disconnected`
  - 从 enabled=true 改为 false → `connection_status` 立即变为 `disabled`

**DELETE /api/v1/devices/{id}** — 逻辑删除

- 将该设备的 deleted 字段设为 true
- 如果设备正在运行中，采集引擎应立即停止该设备的所有采集任务并断开连接
- 同时该设备下所有采集点和写入点也一并逻辑删除

**POST /api/v1/devices/export** — 导出设备列表为CSV

Request body：

```json
{
    "ids": ["uuid1", "uuid2"]  // 可选，不传则导出全部
}
```

Response：CSV文件（Content-Type: text/csv; charset=utf-8-sig）

CSV格式定义：

```csv
name,protocol_type,host,port,connect_timeout,reconnect_interval,protocol_config,enabled
一期曝气柜PLC,S7,192.168.1.100,102,5,10,"{""rack"":0,""slot"":1}",TRUE
二期加药间PLC,MODBUS_TCP,192.168.2.50,502,5,10,"{""unit_id"":1,""byte_order"":""ABCD"",""word_order"":""AB""}",TRUE
```

注意：
- CSV使用UTF-8 with BOM编码
- 首行为标题行
- 布尔值导出为 TRUE/FALSE
- JSON字段导出为转义后的JSON字符串

**POST /api/v1/devices/import** — 从CSV导入设备

- Content-Type: multipart/form-data，文件字段名：file
- 导入逻辑：
  - 以name为唯一标识：如果CSV中的设备名称已存在，则更新该设备；不存在则新增
  - 导入完成后返回处理结果：成功数、失败数、失败原因列表
  - 校验规则与新增接口一致，校验失败的行跳过并记录原因

**GET /api/v1/devices** — 获取设备列表

Query parameters：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认20，最大100 |
| keyword | string | 否 | 搜索关键词（匹配name） |
| protocol_type | string | 否 | 按协议筛选 |
| enabled | bool | 否 | 按启用状态筛选 |

Response (200)：

```json
{
    "code": 0,
    "message": "success",
    "data": {
        "total": 50,
        "page": 1,
        "page_size": 20,
        "items": [
            {
                "id": "uuid",
                "name": "一期曝气柜PLC",
                "protocol_type": "S7",
                "enabled": true,
                "host": "192.168.1.100",
                "port": 102,
                "connect_timeout": 5,
                "reconnect_interval": 10,
                "protocol_config": { "rack": 0, "slot": 1 },
                "connection_status": "connected",
                "created_at": "...",
                "updated_at": "..."
            }
        ]
    }
}
```

`connection_status` 字段说明：
- 由 API Handler 从采集引擎运行时状态中获取后组装到响应中
- 枚举值：`connected`、`disconnected`、`disabled`
- enabled=false 时始终为 `disabled`，无需查询引擎运行时状态
- enabled=true 时，如果采集引擎未运行或查询不到该设备状态，统一返回 `disconnected`

---

## 3. 数据采集点管理

### 3.1 数据模型

#### 3.1.1 数据库表：collection_points

```sql
CREATE TABLE collection_points (
    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name                VARCHAR(128) NOT NULL,
    group_name          VARCHAR(64) NOT NULL DEFAULT 'default',
    device_id           UUID NOT NULL REFERENCES devices(id),
    enabled             BOOLEAN NOT NULL DEFAULT TRUE,
    deleted             BOOLEAN NOT NULL DEFAULT FALSE,
    
    -- 采集地址（协议驱动自行解析）
    address             VARCHAR(256) NOT NULL,
    
    -- 数据类型
    data_type           VARCHAR(16) NOT NULL,  -- 'BOOL', 'INT', 'REAL'
    
    -- 采集参数
    collect_interval    INTEGER NOT NULL DEFAULT 1,  -- 单位：秒，最小值1
    store_history       BOOLEAN NOT NULL DEFAULT TRUE,
    history_interval    INTEGER NOT NULL DEFAULT 1,  -- 单位：分钟，最小值1
    
    created_at          TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
    updated_at          TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
    created_by          VARCHAR(64),
    updated_by          VARCHAR(64)
);

-- 全局唯一名称（逻辑删除的记录不参与）
CREATE UNIQUE INDEX idx_collection_points_name ON collection_points(name) WHERE deleted = FALSE;

-- 按设备查询
CREATE INDEX idx_collection_points_device ON collection_points(device_id) WHERE deleted = FALSE;

-- 按分组查询
CREATE INDEX idx_collection_points_group ON collection_points(group_name) WHERE deleted = FALSE;
```

#### 3.1.2 各协议的地址格式

**S7协议地址格式**：

地址由协议类型决定解析方式，统一存储在 address 字段中：

| 地址类型 | 格式 | 示例 | 说明 |
|----------|------|------|------|
| DB | `DB{db_number}.{byte_offset}.{bit}` | `DB2.10.0` | 数据块，DB号2，字节偏移10，第0位 |
| M | `M{byte_offset}.{bit}` | `M4.0` | 中间寄存器，字节偏移4，第0位 |
| I | `I{byte_offset}.{bit}` | `I1.0` | 输入映像区，字节偏移1，第0位 |
| Q | `Q{byte_offset}.{bit}` | `Q3.0` | 输出映像区，字节偏移3，第0位 |

对于 INT 和 REAL 类型，address 不需要 .bit 部分：

| 数据类型 | 示例地址 | 说明 |
|----------|----------|------|
| BOOL | `DB2.10.0` | 读DB2的第10字节的第0位 |
| INT | `DB2.10` | 读DB2的第10字节开始的2字节（16位整数） |
| REAL | `DB2.10` | 读DB2的第10字节开始的4字节（32位浮点数） |

解析规则：
- 地址格式：`{type_prefix}{numbers}`，其中 numbers 以 `.` 分隔
- 对于 BOOL 类型：必须有3段（或2段，M/I/Q类型），如 `DB2.10.0` 或 `M4.0`
- 对于 INT/REAL 类型：BOOL类型的地址去掉最后的 .bit 部分，如 `DB2.10`、`M4`

**Modbus TCP协议地址格式**：

| 地址范围 | 功能码 | 对应Modbus寄存器类型 | 示例 |
|----------|--------|---------------------|------|
| `00001`~`09999` | 01/05/15 | 线圈（Coil），可读可写，位类型 | `00001` |
| `10001`~`19999` | 02 | 离散输入（Discrete Input），只读，位类型 | `10001` |
| `30001`~`39999` | 04 | 输入寄存器（Input Register），只读，16位 | `30001` |
| `40001`~`49999` | 03/06/16 | 保持寄存器（Holding Register），可读可写，16位 | `40001` |

地址与功能码的映射规则：

| 地址范围 | 读取功能码 | 写入功能码 | 数据类型限制 |
|----------|-----------|-----------|-------------|
| 00001~09999 | 01 | 05（写单个）/15（写多个） | 仅BOOL |
| 10001~19999 | 02 | 不支持 | 仅BOOL |
| 30001~39999 | 04 | 不支持 | INT/REAL |
| 40001~49999 | 03 | 06（写单个）/16（写多个） | INT/REAL |

地址与寄存器地址的换算：
- 地址 `00001` → 协议中的寄存器地址 0
- 地址 `40001` → 协议中的寄存器地址 0
- 地址 `40011` → 协议中的寄存器地址 10
- 公式：`register_address = modbus_address - (address_prefix * 10000 + 1)`

对于 BOOL 类型，每个地址对应一个位（线圈/离散输入）。
对于 INT 类型，每个地址对应1个寄存器（16位）。
对于 REAL 类型，每个地址对应2个连续寄存器（32位），读取时从指定地址连续读2个寄存器，按 device 中配置的 byte_order 和 word_order 解析。

#### 3.1.3 分组机制

分组是扁平结构，group_name 字段即分组名称。

- 默认分组名：`default`
- 分组名支持任意字符串（建议不超过64字符）
- 一个采集点只能属于一个分组
- 分组的增删改通过修改采集点的 group_name 字段实现
- 查询时支持按分组名筛选

#### 3.1.4 实时数据

实时数据不是存储在数据库中的字段，而是采集引擎运行时维护在内存中的最新值。

API 返回采集点时，应附带该点的最新采集值（如果存在）：

```json
{
    "id": "uuid",
    "name": "曝气池DO_01",
    "latest_value": {
        "value": 2.35,
        "quality": "good",
        "ts": "2026-07-09T10:00:01+08:00"
    }
}
```

### 3.2 RESTful API

#### 3.2.1 接口列表

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/collection-points | 获取采集点列表（支持分页、搜索、按设备/分组/数据类型筛选） |
| POST | /api/v1/collection-points | 新增采集点 |
| GET | /api/v1/collection-points/{id} | 获取单个采集点详情（含实时数据） |
| PUT | /api/v1/collection-points/{id} | 修改采集点 |
| DELETE | /api/v1/collection-points/{id} | 逻辑删除采集点 |
| POST | /api/v1/collection-points/export | 导出采集点列表为CSV |
| POST | /api/v1/collection-points/import | 从CSV文件导入采集点 |
| GET | /api/v1/collection-points/groups | 获取所有分组列表 |

#### 3.2.2 接口详细定义

**POST /api/v1/collection-points** — 新增采集点

Request body：

```json
{
    "name": "曝气池DO_01",
    "group_name": "曝气池",
    "device_id": "uuid-of-device",
    "address": "DB2.10",
    "data_type": "REAL",
    "collect_interval": 1,
    "store_history": true,
    "history_interval": 1
}
```

校验规则：
- name：必填，全局唯一，1~128字符
- group_name：可选，默认"default"，1~64字符
- device_id：必填，必须引用一个已存在的设备（且deleted=false）
- address：必填，1~256字符，根据设备协议类型校验格式
- data_type：必填，枚举值：`BOOL`、`INT`、`REAL`
- collect_interval：必填，最小值1（秒）
- store_history：可选，默认true
- history_interval：当store_history=true时必填，最小值1（分钟）
- address 和 data_type 的兼容性校验：
  - S7协议：BOOL类型必须包含bit位（如 `DB2.10.0`），INT/REAL类型不能包含bit位
  - Modbus协议：00001/10001 地址只能使用BOOL类型，30001/40001 地址只能使用INT/REAL类型

**PUT /api/v1/collection-points/{id}** — 修改采集点

- 修改后，如果采集引擎正在运行中，需要动态更新采集任务配置

**DELETE /api/v1/collection-points/{id}** — 逻辑删除

- 将该采集点的 deleted 字段设为 true
- 采集引擎应立即停止该点的采集任务

**GET /api/v1/collection-points** — 获取采集点列表

Query parameters：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 默认1 |
| page_size | int | 否 | 默认20，最大100 |
| keyword | string | 否 | 搜索name、group_name |
| device_id | string | 否 | 按设备筛选 |
| group_name | string | 否 | 按分组筛选 |
| data_type | string | 否 | 按数据类型筛选 |
| enabled | bool | 否 | 按启用状态筛选 |

Response (200)：

```json
{
    "code": 0,
    "message": "success",
    "data": {
        "total": 200,
        "page": 1,
        "page_size": 20,
        "items": [
            {
                "id": "uuid",
                "name": "曝气池DO_01",
                "group_name": "曝气池",
                "device_id": "uuid",
                "device_name": "一期曝气柜PLC",
                "protocol_type": "S7",
                "address": "DB2.10",
                "data_type": "REAL",
                "collect_interval": 1,
                "store_history": true,
                "history_interval": 1,
                "enabled": true,
                "latest_value": {
                    "value": 2.35,
                    "quality": "good",
                    "ts": "2026-07-09T10:00:01+08:00"
                },
                "created_at": "...",
                "updated_at": "..."
            }
        ]
    }
}
```

**GET /api/v1/collection-points/groups** — 获取分组列表

Response (200)：

```json
{
    "code": 0,
    "message": "success",
    "data": {
        "groups": [
            {
                "name": "default",
                "count": 10
            },
            {
                "name": "曝气池",
                "count": 25
            },
            {
                "name": "加药间",
                "count": 15
            }
        ]
    }
}
```

**POST /api/v1/collection-points/export** — 导出CSV

CSV格式定义：

```csv
name,group_name,device_name,address,data_type,collect_interval,store_history,history_interval,enabled
曝气池DO_01,曝气池,一期曝气柜PLC,DB2.10,REAL,1,TRUE,1,TRUE
进水pH,进水仪表,进水仪表柜PLC,DB1.0,REAL,5,TRUE,5,TRUE
风机运行状态,曝气池,一期曝气柜PLC,M4.0,BOOL,1,TRUE,1,TRUE
```

注意：
- device_name 列关联设备名称，导入时根据设备名称查找对应的 device_id
- 如果导入时 device_name 找不到对应的设备，则该行导入失败
- 其他规则与设备CSV导入一致

**POST /api/v1/collection-points/import** — 从CSV导入

- 导入逻辑：以 name 为唯一标识，存在则更新，不存在则新增
- 需先校验 device_name 是否有效

---

## 4. 数据写入点管理

### 4.1 数据模型

#### 4.1.1 数据库表：write_points

```sql
CREATE TABLE write_points (
    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name                VARCHAR(128) NOT NULL,
    group_name          VARCHAR(64) NOT NULL DEFAULT 'default',
    device_id           UUID NOT NULL REFERENCES devices(id),
    enabled             BOOLEAN NOT NULL DEFAULT TRUE,
    write_enabled       BOOLEAN NOT NULL DEFAULT FALSE,   -- 是否允许写入
    write_source        VARCHAR(16) NOT NULL DEFAULT 'manual',  -- 写入来源: 'manual'（仅人工）, 'auto'（仅程序自动）, 'both'（两者均可）
    deleted             BOOLEAN NOT NULL DEFAULT FALSE,
    
    -- 写入地址（协议驱动自行解析，格式与采集点相同）
    address             VARCHAR(256) NOT NULL,
    
    -- 数据类型
    data_type           VARCHAR(16) NOT NULL,  -- 'BOOL', 'INT', 'REAL'
    
    created_at          TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
    updated_at          TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
    created_by          VARCHAR(64),
    updated_by          VARCHAR(64)
);

CREATE UNIQUE INDEX idx_write_points_name ON write_points(name) WHERE deleted = FALSE;
CREATE INDEX idx_write_points_device ON write_points(device_id) WHERE deleted = FALSE;
CREATE INDEX idx_write_points_group ON write_points(group_name) WHERE deleted = FALSE;
```

#### 4.1.2 与采集点的区别

| 维度 | 采集点 | 写入点 |
|------|--------|--------|
| 方向 | 从PLC读取 | 向PLC写入 |
| 存储历史 | 支持（可配置写入TDengine） | 不支持（只记录操作日志） |
| 采集周期 | 有 | 无（指令触发，非周期执行） |
| 写入开关 | 无 | 有（write_enabled + write_source） |
| 写入来源 | 无 | 支持人工（manual）和程序自动（auto）两种来源 |
| 采集引擎 | 周期性调度 | 无（等待API触发） |

#### 4.1.3 地址格式

与采集点完全一致，参考 [3.1.2](#312-各协议的地址格式)。

注意：写入点必须使用可写的地址类型：
- S7协议：DB、M、Q 类型可写（I类型为输入，不可写）
- Modbus协议：00001（线圈）和 40001（保持寄存器）可写；10001（离散输入）和 30001（输入寄存器）不可写

### 4.2 RESTful API

#### 4.2.1 接口列表

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/write-points | 获取写入点列表 |
| POST | /api/v1/write-points | 新增写入点 |
| GET | /api/v1/write-points/{id} | 获取单个写入点详情 |
| PUT | /api/v1/write-points/{id} | 修改写入点 |
| DELETE | /api/v1/write-points/{id} | 逻辑删除 |
| POST | /api/v1/write-points/export | 导出CSV |
| POST | /api/v1/write-points/import | 从CSV导入 |
| POST | /api/v1/write-points/{id}/write | 执行写入操作（人工/程序自动均使用此接口） |
| GET | /api/v1/write-logs | 查询写入操作日志 |

**GET /api/v1/write-logs** — 查询写入操作日志

Query parameters：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 默认1 |
| page_size | int | 否 | 默认20，最大100 |
| point_id | string | 否 | 按写入点筛选 |
| device_id | string | 否 | 按设备筛选 |
| source | string | 否 | 筛选 manual/auto |
| result | string | 否 | 筛选 success/failed |
| start_time | string | 否 | 开始时间 |
| end_time | string | 否 | 结束时间 |
| keyword | string | 否 | 搜索 operator 或 point_name |

Response (200)：

```json
{
    "code": 0,
    "message": "success",
    "data": {
        "total": 500,
        "page": 1,
        "page_size": 20,
        "items": [
            {
                "id": "uuid",
                "point_id": "uuid",
                "point_name": "加药泵频率",
                "device_id": "uuid",
                "device_name": "一期加药间PLC",
                "address": "DB2.10",
                "data_type": "REAL",
                "source": "manual",
                "target_value": "20.5",
                "readback_value": "20.5",
                "result": "success",
                "error_message": null,
                "operator": "张三",
                "reason": "AI推荐加药量调整",
                "created_at": "2026-07-09T10:00:00+08:00"
            }
        ]
    }
}
```

#### 4.2.2 写入接口详细定义

**POST /api/v1/write-points/{id}/write** — 执行写入

Request body（人工写入）：

```json
{
    "value": 20.5,
    "source": "manual",
    "operator": "张三",
    "reason": "AI推荐加药量调整"
}
```

Request body（程序自动写入）：

```json
{
    "value": 25.0,
    "source": "auto",
    "operator": "ai-engine:aeration-model-v1",
    "reason": "曝气模型推理结果：进水负荷上升，需要增加风量"
}
```

校验规则：
- value：必填，类型必须与写入点的 data_type 匹配
  - BOOL：true/false
  - INT：整数
  - REAL：浮点数
- source：必填，枚举值：`manual`（人工）、`auto`（程序自动）
- operator：必填
  - 当 source=manual 时，操作人标识（如 "张三"）
  - 当 source=auto 时，调用方标识（如 "ai-engine:aeration-model-v1"）
- reason：可选，操作原因
- 写入来源校验：写入点的 write_source 字段必须与请求中的 source 匹配
  - write_source=manual：仅允许 source=manual
  - write_source=auto：仅允许 source=auto
  - write_source=both：manual 和 auto 都允许

写入流程：

```
1. 校验写入点是否存在且 write_enabled=true
2. 校验请求中的 source 是否在写入点 write_source 允许的范围内
3. 校验值类型与 data_type 匹配
4. 连接PLC（如果已连接则复用）
5. 写入地址（调用协议驱动的 Write 方法）
6. 回读验证（读取刚写入的地址，确认值一致）
   - 如果回读值与写入值一致：写入成功
   - 如果回读值与写入值不一致：重试一次，仍不一致则标记为失败
7. 记录操作日志到 write_logs 表
8. 返回写入结果
```

Response (200)：

```json
{
    "code": 0,
    "message": "success",
    "data": {
        "id": "uuid",
        "point_name": "加药泵频率",
        "value": 20.5,
        "result": "success",
        "readback_value": 20.5,
        "ts": "2026-07-09T10:00:00+08:00"
    }
}
```

写入失败时：

```json
{
    "code": 0,
    "message": "success",
    "data": {
        "id": "uuid",
        "point_name": "加药泵频率",
        "value": 20.5,
        "result": "failed",
        "error": "回读值不匹配: 期望20.5, 实际18.3",
        "ts": "2026-07-09T10:00:00+08:00"
    }
}
```

写入超时：

```json
{
    "code": 0,
    "message": "success",
    "data": {
        "id": "uuid",
        "point_name": "加药泵频率",
        "value": 20.5,
        "result": "timeout",
        "error": "写入操作超时: 设备无响应超过30秒",
        "ts": "2026-07-09T10:00:00+08:00"
    }
}
```

#### 4.2.3 写入操作日志表：write_logs

```sql
CREATE TABLE write_logs (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    point_id        UUID NOT NULL REFERENCES write_points(id),
    point_name      VARCHAR(128) NOT NULL,
    device_id       UUID NOT NULL REFERENCES devices(id),
    device_name     VARCHAR(128) NOT NULL,
    address         VARCHAR(256) NOT NULL,
    data_type       VARCHAR(16) NOT NULL,
    
    source          VARCHAR(16) NOT NULL,         -- 'manual' 或 'auto'
    target_value    TEXT NOT NULL,                -- 目标值（统一存为字符串）
    readback_value  TEXT,                         -- 回读值
    result          VARCHAR(16) NOT NULL,         -- 'success', 'failed', 'timeout'
    error_message   TEXT,
    
    operator        VARCHAR(64) NOT NULL,
    reason          TEXT,
    
    created_at      TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_write_logs_point ON write_logs(point_id);
CREATE INDEX idx_write_logs_device ON write_logs(device_id);
CREATE INDEX idx_write_logs_source ON write_logs(source);
CREATE INDEX idx_write_logs_time ON write_logs(created_at DESC);
```

---

## 5. 采集引擎（运行时）

### 5.1 架构概述

采集引擎是后台常驻服务，负责执行实际的数据采集任务。

```
┌─────────────────────────────────────────────────────┐
│                  采集引擎（Collector Engine）          │
│                                                       │
│  ┌──────────────┐  ┌──────────────┐                   │
│  │ 设备连接管理器  │  │ 采集任务调度器  │                 │
│  │ (Connection   │  │ (Scheduler)  │                   │
│  │  Manager)     │  └──────┬───────┘                   │
│  └──────┬───────┘         │                            │
│         │                 │ 每个采集点的独立协程/任务     │
│         │         ┌───────▼────────┐                   │
│         │         │  采集点执行单元   │                  │
│         │         │  (Point Runner) │                  │
│         │         └───────┬────────┘                   │
│         │                 │                            │
│         │         ┌───────▼────────┐                   │
│         │         │  数据后处理      │                   │
│         │         │  - 质量戳判定    │                   │
│         │         │  - 更新内存缓存  │                   │
│         │         │  - 写入TDengine  │                   │
│         │         └────────────────┘                   │
└─────────────────────────────────────────────────────┘
```

### 5.2 启动流程

```
1. 采集引擎启动
2. 从数据库加载所有 enabled=true AND deleted=false 的设备
3. 从数据库加载所有 enabled=true AND deleted=false 的采集点，按 device_id 分组
4. 对每个设备，尝试建立连接：
   a. 连接成功 → 标记为"已连接"，启动该设备下所有采集点的采集任务
   b. 连接失败 → 标记为"断开"，启动重连计时器
5. 每个采集点按 collect_interval 周期性执行
```

### 5.3 采集任务执行流程

```
每个采集点周期执行：
1. 检查设备连接状态：
   - 已连接 → 执行采集
   - 断开中 → 标记质量戳为 bad，跳过本次采集
2. 调用协议驱动读取数据：
   - 成功 → 获取原始值
   - 失败 → 递增失败计数，标记质量戳为 bad
3. 数据解析：
   - 根据 data_type 解析原始字节为对应类型值
   - 应用 byte_order/word_order（Modbus REAL类型）
4. 质量戳判定：
   - 读取成功 + 值在合理范围内 → good
   - 读取失败 → bad
   - 读取成功但值为 null/异常 → bad
5. 更新内存缓存（latest_values）：
   - key: 采集点ID
   - value: { value, quality, ts }
6. 写入TDengine（如果 store_history=true）：
   - 根据 history_interval 判断是否需要写入
   - 写入时使用质量戳标记
7. 发送MQTT消息（如果启用了MQTT）：
   - 主题：plc/{device_id}/{point_id}/realtime
   - 载荷：{ ts, value, quality }
```

### 5.4 质量戳判定规则

| 条件 | 质量戳（API层） | 质量戳（存储层 INT） |
|------|----------------|---------------------|
| 协议读取成功，返回有效值 | `good` | `0` |
| 协议读取成功，但值为 null 或解析异常 | `bad` | `1` |
| 协议读取失败（超时/无响应/异常） | `bad` | `1` |
| 设备连接断开 | `bad` | `1` |
| 设备连接断开后，断线期间所有采集点都标记为 `bad` | `bad` | `1` |
| 查询时间范围内无对应数据记录 | `none` | 不存在（无记录） |

> **质量戳转换约定**：TDengine 存储 INT 值（0=good, 1=bad），后端 API 层在返回响应时统一转换为字符串格式。前端始终处理字符串格式的质量戳。`none` 状态仅在查询无匹配记录时由 API 层返回，不会出现在 TDengine 存储中。

### 5.5 断线重连机制

```
1. 采集引擎检测到设备连接断开（读取失败或连接异常断开）
2. 立即标记该设备状态为"断开"
3. 该设备下所有采集点标记为 bad
4. 启动重连计时器（间隔 = 设备配置的 reconnect_interval）
5. 每次重连尝试：
   a. 连接成功 → 标记设备为"已连接"，恢复采集
   b. 连接失败 → 继续等待下一次重连
6. 重连成功后，自动恢复所有采集点的正常采集
7. 重连无次数限制，持续尝试直到成功或设备被禁用
```

### 5.6 动态配置更新

当用户通过API修改设备或采集点配置时，采集引擎需要动态响应：

| 用户操作 | 采集引擎响应 |
|----------|-------------|
| 新增设备 | 立即建立连接，启动采集任务 |
| 修改设备参数（IP/端口等） | 断开旧连接，使用新参数重新连接 |
| 删除设备 | 断开连接，停止所有采集任务 |
| 启用/禁用设备 | 禁用则断开；启用则连接并启动 |
| 新增采集点 | 立即启动该点的采集任务 |
| 修改采集点参数（地址/周期等） | 停止旧任务，按新参数启动 |
| 删除采集点 | 停止该点的采集任务 |
| 启用/禁用采集点 | 禁用则停止，启用则启动 |

实现方式：采集引擎启动一个配置变更监听协程，定期（每5秒）或通过数据库通知监听配置变更。

### 5.7 TDengine 数据写入

#### 5.7.1 超级表定义

```sql
-- 采集点数据超级表
CREATE STABLE IF NOT EXISTS collection_data (
    ts          TIMESTAMP,        -- 采集时间戳
    value       DOUBLE,           -- 采集值（所有类型统一转DOUBLE，BOOL转0/1）
    quality     INT,              -- 质量戳：0=good, 1=bad
    point_id    VARCHAR(32),      -- 采集点ID（加速查询冗余字段）
    point_name  VARCHAR(128)      -- 采集点名称（冗余字段，方便查询）
) TAGS (
    device_id   VARCHAR(32),      -- 设备ID
    device_name VARCHAR(128),     -- 设备名称
    data_type   VARCHAR(16)       -- 原始数据类型
);
```

#### 5.7.2 子表创建策略

每个采集点对应一个子表，子表名使用采集点ID去掉连字符后的字符串：

```sql
-- 假设采集点ID为: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
-- 子表名: a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d
CREATE TABLE IF NOT EXISTS a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d 
USING collection_data TAGS (
    'device-uuid', '一期曝气柜PLC', 'REAL'
);
```

#### 5.7.3 写入策略

- 写入时使用 `INSERT INTO ... USING ... TAGS` 语法，自动创建子表
- 批量写入：每1秒或每100条数据攒一批写入，提高写入效率
- 如果 store_history=false，不写入TDengine
- 写入频率由 history_interval 控制（例如 history_interval=5，则每5分钟写入一条）

### 5.8 运行时状态查询接口

采集引擎需要对外提供设备连接状态的查询能力，供 API Handler 层在组装设备列表/详情响应时获取。

```
采集引擎内部维护：
  deviceConnections map[string]ConnectionState  // key: device_id

  type ConnectionState struct {
      Status   string    // "connected" | "disconnected"
      Since    time.Time // 状态持续起始时间
  }

对外暴露的查询方法（在采集引擎实例上）：
  func (m *CollectorManager) GetDeviceStatus(deviceID string) string
  func (m *CollectorManager) GetDeviceStatusMap() map[string]string
```

状态查询规则：

| 条件 | 返回状态 |
|------|---------|
| 设备不在映射表中（引擎未初始化该设备） | `disconnected` |
| 设备在映射表中且连接成功 | `connected` |
| 设备在映射表中但连接已断开 | `disconnected` |
| 引擎未启动或不可用 | `disconnected` |

> 采集引擎以单例模式运行在服务端进程中，API Handler 通过依赖注入获取引擎实例的引用，直接调用 `GetDeviceStatusMap()` 查询状态。

---

## 6. 写入引擎（运行时）

### 6.1 架构概述

写入引擎负责接收写入请求（来自人工Web操作或AI引擎自动调用），执行写入操作并返回结果。两种写入来源共用同一个执行通道，区别仅在于 source 字段和 operator 字段不同。

```
写入请求
    │
    ├── source=manual（来自Web前端人工操作）
    └── source=auto（来自AI引擎程序自动调用）
    │
    ▼
┌─────────────────────┐
│  请求校验             │
│  - 写入点是否存在      │
│  - write_enabled=true │
│  - source是否允许      │
│  - 值类型校验          │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  指令执行             │
│  - 获取设备连接        │
│  - 调用协议驱动写入     │
│  - 回读验证            │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  结果记录             │
│  - 写入 write_logs   │
│  - 返回结果给调用方    │
└─────────────────────┘
```

### 6.2 写入安全策略

1. **write_enabled 开关**：写入点必须显式开启 write_enabled=true 才能写入，防止误操作
2. **写入来源校验**：写入点的 write_source 字段控制该点允许 manual/auto/both 哪种来源
3. **回读验证**：每次写入后必须回读确认，值一致才算成功
4. **操作审计**：所有写入操作记录到 write_logs，可追溯
5. **权限控制**：写入操作需要用户登录权限（由Web后端统一管理）

---

## 7. 协议插件化架构

### 7.1 接口定义

所有协议驱动必须实现以下接口：

```go
// ProtocolDriver 协议驱动接口
type ProtocolDriver interface {
    // 协议类型标识，如 "S7", "MODBUS_TCP"
    ProtocolType() string
    
    // 创建连接
    // config: 设备配置中的 protocol_config（JSONB解析后的map）
    // host: 设备IP
    // port: 设备端口
    // timeout: 连接超时（秒）
    Connect(config map[string]interface{}, host string, port int, timeout int) error
    
    // 断开连接
    Disconnect() error
    
    // 读取数据
    // address: 采集点地址字符串（如 "DB2.10", "M4.0", "40001"）
    // dataType: 数据类型（BOOL/INT/REAL）
    // 返回: 读取到的值（统一使用float64返回，BOOL返回0或1），错误
    Read(address string, dataType string) (float64, error)
    
    // 写入数据
    // address: 写入点地址字符串
    // dataType: 数据类型
    // value: 要写入的值（float64，BOOL类型时0=false，1=true）
    // 返回: 错误
    Write(address string, dataType string, value float64) error
    
    // 校验地址格式是否合法
    ValidateAddress(address string, dataType string) error
    
    // 获取协议配置的JSON Schema（用于前端动态渲染配置表单）
    ConfigSchema() map[string]interface{}
}
```

### 7.2 注册机制

```go
// 全局协议驱动注册表
var protocolDrivers = make(map[string]ProtocolDriver)

// 注册协议驱动
func RegisterProtocol(driver ProtocolDriver) {
    protocolDrivers[driver.ProtocolType()] = driver
}

// 获取协议驱动
func GetProtocol(protocolType string) (ProtocolDriver, error) {
    driver, ok := protocolDrivers[protocolType]
    if !ok {
        return nil, fmt.Errorf("不支持的协议类型: %s", protocolType)
    }
    return driver, nil
}
```

### 7.3 扩展新协议的步骤

1. 创建新的协议驱动文件，实现 `ProtocolDriver` 接口
2. 在 `init()` 函数中调用 `RegisterProtocol()` 注册
3. 在 `protocol_config` 中定义该协议特有的配置参数
4. 实现 `ConfigSchema()` 返回配置参数的JSON Schema，供前端动态渲染配置表单

### 7.4 目前支持的协议驱动

#### 7.4.1 S7 协议驱动

| 属性 | 说明 |
|------|------|
| ProtocolType | `S7` |
| 默认端口 | 102 |
| 依赖库 | `github.com/robinson/gos7` 或等效实现 |
| 连接方式 | 基于ISO TCP（RFC 1006） |
| 地址解析 | 见 [3.1.2 S7协议地址格式](#312-各协议的地址格式) |
| ConfigSchema | `{ "rack": { "type": "integer", "default": 0 }, "slot": { "type": "integer", "default": 1 } }` |

#### 7.4.2 Modbus TCP 协议驱动

| 属性 | 说明 |
|------|------|
| ProtocolType | `MODBUS_TCP` |
| 默认端口 | 502 |
| 依赖库 | `github.com/goburrow/modbus` 或等效实现 |
| 连接方式 | Modbus TCP直接连接 |
| 地址解析 | 见 [3.1.2 Modbus TCP协议地址格式](#312-各协议的地址格式) |
| ConfigSchema | `{ "unit_id": { "type": "integer", "default": 1, "min": 1, "max": 247 }, "byte_order": { "type": "string", "enum": ["ABCD", "BADC", "CDAB", "DCBA"], "default": "ABCD" }, "word_order": { "type": "string", "enum": ["AB", "BA"], "default": "AB" } }` |

---

## 附录A：前端页面结构参考

### A.1 页面布局

```
┌──────────────────────────────────────────┐
│  ┌──────────┐  ┌───────────────────────┐ │
│  │  ▽ 数据管理 │  │                        │ │
│  │    设备管理 │  │      内容区域           │ │
│  │    数据采集 │  │                        │ │
│  │    数据写入 │  │                        │ │
│  └──────────┘  └───────────────────────┘ │
└──────────────────────────────────────────┘
```

左侧导航栏说明：
- 导航栏为树形结构，主菜单可展开/收起
- 当前展开的主菜单：**数据管理**
- 展开后显示三个子菜单项：**设备管理**、**数据采集**、**数据写入**
- 点击子菜单项，右侧内容区域切换对应页面

### A.2 子页面：设备管理

- 设备列表表格（ID | 名称 | 协议类型 | IP | 端口 | 状态 | 操作）
- 新增/编辑设备弹窗（动态表单，协议类型切换时protocol_config区域联动变化）
- 删除确认（二次确认，提示"同时会删除该设备下所有采集点和写入点"）
- 启用/禁用开关
- 导入/导出CSV按钮

### A.3 子页面：数据采集

- 分组筛选器（横向标签或下拉菜单）
- 采集点列表表格（名称 | 分组 | 所属设备 | 地址 | 数据类型 | 采集周期 | 存储历史 | 最新值 | 质量戳 | 操作）
- 新增/编辑采集点弹窗（设备选择后，地址格式提示跟随设备协议变化）
- 拖拽修改分组（或通过编辑弹窗修改）
- 导入/导出CSV按钮

### A.4 子页面：数据写入

- 写入点列表表格（名称 | 分组 | 所属设备 | 地址 | 数据类型 | 允许写入 | 写入来源 | 操作）
- 新增/编辑写入点弹窗（写入来源下拉选项：仅人工/仅程序自动/两者均可）
- 执行写入操作弹窗：区分人工写入和程序自动写入
  - 人工写入：输入值、选择操作人、原因，点击确认后执行并显示结果
  - 程序自动写入：显示调用方标识（如 AI 模型名称）
- 写入操作日志查看（可筛选 source=manual 或 source=auto）
- 导入/导出CSV按钮

---

## 附录B：关键业务规则一览

| 编号 | 规则 | 说明 |
|------|------|------|
| R001 | 设备名称全局唯一 | 逻辑删除的记录不参与唯一性校验 |
| R002 | 采集点名称全局唯一 | 同上 |
| R003 | 写入点名称全局唯一 | 同上 |
| R004 | 逻辑删除级联 | 删除设备时，该设备下所有采集点和写入点也逻辑删除 |
| R005 | 采集地址格式校验 | 根据设备协议类型校验地址格式，创建设备时即确定协议 |
| R006 | 采集周期最小1秒 | 不可低于1秒 |
| R007 | 历史存储间隔最小1分钟 | 当store_history=true时有效 |
| R008 | 写入来源校验 | 写入点的 write_source 控制允许 manual/auto/both |
| R009 | 写入回读验证 | 每次写入后必须回读确认，不一致则重试1次 |
| R010 | 写入点地址类型限制 | 必须使用可写地址类型 |
| R011 | 质量戳自动判定 | 连接断开/读取失败/解析异常 → bad，正常 → good |
| R012 | 断线无限重连 | 持续按配置间隔重连，直到成功或设备被禁用 |
| R013 | 配置变更动态生效 | 修改设备/采集点配置后，采集引擎自动更新，无需重启 |

---

> 本文档版本：v1.1
> 最后更新：2026-07-09