qsc20001102/AquaControlAI

Fork 0

Files

T

qsc20001102 711205c059 11

2026-07-11 20:14:16 +08:00

49 KiB

Raw Blame History

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

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

跨文档契约发生冲突时，必须遵循《一致性决策基线》；该文件的已采纳决策优先于本文旧表述。

1. 概述

1.1 模块定位

本模块是平台的数据基础层，负责：

管理PLC设备及其连接配置
定义数据采集点位（从PLC读取数据）
定义数据写入点位（向PLC写入控制指令）
运行时执行数据采集任务，将数据写入TDengine
运行时执行控制指令下发任务

1.2 模块边界

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

1.3 核心概念关系

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

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

2. 设备管理

2.1 数据模型

2.1.1 数据库表：devices

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协议：

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

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

Modbus TCP协议：

{
    "unit_id": 1,
    "float32_order": "ABCD"
}

字段	类型	必填	说明
unit_id	int	是	Modbus从站地址，范围1~247
float32_order	string	是	REAL 占用两个寄存器时的四字节排列：`ABCD`、`BADC`、`CDAB`、`DCBA`；默认 `ABCD`

float32_order 直接描述从两个寄存器读取到的四个字节如何重排为 IEEE-754 32 位浮点数，不再叠加第二个 word_order 字段，避免字节交换与字交换职责重叠。INT 类型按标准 16 位寄存器顺序解析。

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：

{
    "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)：

{
    "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} — 修改设备

PUT 使用完整替换语义，以下字段全部必填：

{
    "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
    }
}

校验规则与新增一致，额外要求 enabled 为布尔值。
修改连接参数或协议配置后，Service 在事务提交后发布配置变更事件；采集引擎断开旧连接并使用新参数重连。
enabled=false 时运行时状态立即进入 disabled；enabled=true 后先返回 disconnected，连接成功后变为 connected。
配置变更正常情况下 1 秒内生效，5 秒全量校对保证最终一致。

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

将该设备的 deleted 字段设为 true
如果设备正在运行中，采集引擎应立即停止该设备的所有采集任务并断开连接
同时该设备下所有采集点和写入点也一并逻辑删除；已有 TDengine 历史数据不删除，作为归档数据继续只读查询

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

Request body：

{
    "ids": ["uuid1", "uuid2"]
}

ids 可选；省略时导出全部符合当前权限和逻辑删除规则的设备。

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

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,""float32_order"":""ABCD""}",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)：

{
    "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 字段说明：

由设备 Service 通过 DeviceRuntimeStatusProvider 获取运行时状态后组装；Handler 不直接访问采集引擎
枚举值：connected、disconnected、disabled
enabled=false 时始终为 disabled，无需查询引擎运行时状态
enabled=true 时，如果采集引擎未运行或查询不到该设备状态，统一返回 disconnected

GET /api/v1/devices/{id} 返回与列表项相同的完整设备对象；不存在或已逻辑删除时返回 HTTP 404、code=40004。

GET /api/v1/devices/protocols 返回注册表中的协议工厂元数据：

{
    "code": 0,
    "message": "success",
    "data": {
        "items": [
            {"protocol_type":"S7","default_port":102,"config_schema":{"type":"object"}},
            {"protocol_type":"MODBUS_TCP","default_port":502,"config_schema":{"type":"object"}}
        ]
    }
}

设备导入结果使用统一结构：

{
    "code": 0,
    "message": "success",
    "data": {
        "total": 10,
        "created": 6,
        "updated": 3,
        "failed": 1,
        "errors": [{"row":8,"field":"host","message":"无效的IP地址或域名"}]
    }
}

设备 CSV 成功时直接返回文件流，不使用 JSON envelope；失败时返回统一 JSON 错误。

3. 数据采集点管理

3.1 数据模型

3.1.1 数据库表：collection_points

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'
    unit                VARCHAR(32),
    valid_min           DOUBLE PRECISION,
    valid_max           DOUBLE PRECISION,

    collect_interval    INTEGER NOT NULL DEFAULT 1 CHECK (collect_interval >= 1),
    store_history       BOOLEAN NOT NULL DEFAULT TRUE,
    history_interval    INTEGER NOT NULL DEFAULT 1 CHECK (history_interval BETWEEN 1 AND 1440),
    history_started_at  TIMESTAMP WITH TIME ZONE,

    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),

    CHECK (valid_min IS NULL OR valid_max IS NULL OR valid_min <= valid_max)
);

CREATE UNIQUE INDEX idx_collection_points_name
    ON collection_points(name) WHERE deleted = FALSE;
CREATE INDEX idx_collection_points_device_id
    ON collection_points(device_id) WHERE deleted = FALSE;
CREATE INDEX idx_collection_points_group_name
    ON collection_points(group_name) WHERE deleted = FALSE;

history_started_at 在点位首次准备写入 TDengine 前设置。一旦非空，device_id 和 data_type 不可修改；需要改变设备归属或数据类型时必须新建点位，防止同一历史子表混入不同语义的数据。

3.1.1.1 历史模块只读元数据接口

设备与采集点配置由数据管理模块拥有。历史模块必须调用公开的进程内只读领域接口，不得直接查询 devices、collection_points 表或调用数据管理 Repository。

接口能力：

type HistoryPointMetadataOptions struct {
    IncludeArchived bool
}

ListHistoryPointMetadata(ctx context.Context, opts HistoryPointMetadataOptions) ([]HistoryPointMetadata, error)
GetHistoryPointMetadata(ctx context.Context, pointIDs []uuid.UUID, includeArchived bool) ([]HistoryPointMetadata, error)

稳定 DTO 至少包含：

点位 ID、名称、分组、单位、设备 ID/名称、数据类型；
enabled、deleted、设备启用/删除状态、store_history、history_interval；
history_started_at；
可空 latest_value，结构为 {value, quality, quality_reason, ts}。

IncludeArchived=true 时必须返回逻辑删除或禁用但配置记录仍保留的点位。历史模块再结合 TDengine 是否存在记录确定 has_history_data 和 lifecycle_status。

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 中配置的 float32_order 解析。

3.1.3 分组机制

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

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

3.1.4 实时数据

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

API 返回采集点时应附带最新采集值；没有缓存时 latest_value 固定为 null：

{
    "id": "uuid",
    "name": "曝气池DO_01",
    "latest_value": {
        "value": 2.35,
        "quality": "good",
        "quality_reason": null,
        "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：

{
    "name": "曝气池DO_01",
    "group_name": "曝气池",
    "device_id": "uuid-of-device",
    "address": "DB2.10",
    "data_type": "REAL",
    "unit": "mg/L",
    "valid_min": 0,
    "valid_max": 20,
    "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
unit：可选，0~32字符；用于历史表格和图表展示
valid_min / valid_max：可选；同时提供时必须 valid_min <= valid_max，超范围值记为 bad 但保留原始值
collect_interval：必填，最小值1（秒）
store_history：可选，默认true
history_interval：当 store_history=true 时必填，必须为 1~1440 的整数（分钟）；store_history=false 时可省略并使用默认值 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} — 修改采集点

PUT 使用完整替换语义，请求字段与新增一致，并额外要求 enabled：

{
    "name": "曝气池DO_01",
    "group_name": "曝气池",
    "device_id": "uuid-of-device",
    "enabled": true,
    "address": "DB2.10",
    "data_type": "REAL",
    "unit": "mg/L",
    "valid_min": 0,
    "valid_max": 20,
    "collect_interval": 1,
    "store_history": true,
    "history_interval": 5
}

history_started_at 非空时，修改 device_id 或 data_type 返回 HTTP 409、code=41009。
名称、分组、地址、单位、有效范围、采集周期和历史间隔可以修改。
Service 在事务提交后发布配置变更事件，采集引擎停止旧任务并按新配置启动；5 秒内保证最终生效。

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)：

{
    "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",
                "unit": "mg/L",
                "valid_min": 0,
                "valid_max": 20,
                "collect_interval": 1,
                "store_history": true,
                "history_interval": 1,
                "enabled": true,
                "latest_value": {
                    "value": 2.35,
                    "quality": "good",
                    "quality_reason": null,
                    "ts": "2026-07-09T10:00:01+08:00"
                },
                "created_at": "...",
                "updated_at": "..."
            }
        ]
    }
}

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

Response (200)：

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

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

CSV格式定义：

name,group_name,device_name,address,data_type,unit,valid_min,valid_max,collect_interval,store_history,history_interval,enabled
曝气池DO_01,曝气池,一期曝气柜PLC,DB2.10,REAL,mg/L,0,20,1,TRUE,1,TRUE
进水pH,进水仪表,进水仪表柜PLC,DB1.0,REAL,pH,0,14,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，再按对应协议校验地址和数据类型。
若更新已有点位且 history_started_at 非空，CSV 不得改变 device_name 对应的设备或 data_type。
响应沿用设备导入的 {total,created,updated,failed,errors} 结构。

GET /api/v1/collection-points/{id} 返回列表项的完整对象，并包含 history_started_at；无实时缓存时 latest_value=null。

采集点 CSV 成功时直接返回文件流，不使用 JSON envelope；失败时返回统一 JSON 错误。

4. 数据写入点管理

4.1 数据模型

4.1.1 数据库表：write_points

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,
    deleted             BOOLEAN NOT NULL DEFAULT FALSE,

    address             VARCHAR(256) NOT NULL,
    data_type           VARCHAR(16) NOT NULL,  -- 'BOOL', 'INT', 'REAL'
    unit                VARCHAR(32),
    readback_tolerance  DOUBLE PRECISION NOT NULL DEFAULT 0.0001
                        CHECK (readback_tolerance >= 0),

    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_id
    ON write_points(device_id) WHERE deleted = FALSE;
CREATE INDEX idx_write_points_group_name
    ON write_points(group_name) WHERE deleted = FALSE;

4.1.2 与采集点的区别

维度	采集点	写入点
方向	从PLC读取	向PLC写入
存储历史	支持	不支持，只记录操作日志
周期	周期采集	API 指令触发
写入开关	无	`write_enabled`
写入来源	无	当前阶段仅人工写入，服务端固定为 `manual`
回读	无	写入后必须回读验证

4.1.3 地址与回读规则

地址格式与采集点一致，但只允许可写区域：S7 的 DB/M/Q，Modbus 的 Coil/保持寄存器。
BOOL、INT 回读必须严格相等。
REAL 使用 abs(readback-target) <= readback_tolerance；默认容差 0.0001。
同一设备的采集、写入和回读通过设备连接命令队列串行执行，避免协议客户端并发冲突。

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	查询写入操作日志

4.2.2 写入点 CRUD

新增请求：

{
    "name": "加药泵频率",
    "group_name": "加药间",
    "device_id": "uuid-of-device",
    "enabled": true,
    "write_enabled": false,
    "address": "DB2.10",
    "data_type": "REAL",
    "unit": "Hz",
    "readback_tolerance": 0.01
}

POST 中 enabled 可省略，默认 true；PUT 中全部字段必填。
名称全局唯一；设备必须存在且未删除；地址必须可写并与数据类型兼容。
readback_tolerance 仅对 REAL 生效，范围 0~1,000,000。
GET 列表支持 page、page_size、keyword、device_id、group_name、data_type、enabled、write_enabled。
DELETE 设置 deleted=true 并立即拒绝新的写入请求。

成功响应中的写入点对象包含上述字段及 id、device_name、protocol_type、created_at、updated_at。

配置 CSV：

name,group_name,device_name,address,data_type,unit,enabled,write_enabled,readback_tolerance
加药泵频率,加药间,一期加药间PLC,DB2.10,REAL,Hz,TRUE,FALSE,0.01

导入以 name 为唯一标识，存在则更新；失败结果返回行号、字段和稳定错误原因。写入点 CSV 成功时直接返回文件流，不使用 JSON envelope；失败时返回统一 JSON 错误。

4.2.3 执行写入

POST /api/v1/write-points/{id}/write

{
    "value": 20.5,
    "reason": "工艺调整"
}

校验：

BOOL 只接受 JSON boolean；INT 只接受整数；REAL 接受 JSON number。
reason 可选，最多 500 字符。
请求体不得包含 source 或 operator；服务端固定记录 source=manual、operator=null。

执行流程：

校验点位、设备、enabled 和 write_enabled；
通过设备级连接队列写入；
回读并按数据类型验证；不一致时重试一次；
无论成功、失败或超时都写入 write_logs；
返回稳定业务结果，原始协议错误只写服务端日志。

成功：HTTP 200、code=0。

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

失败：HTTP 502、code=51001；超时：HTTP 504、code=51002。失败响应 data 至少包含 write_log_id、result 和稳定 error_message。

4.2.4 写入日志

查询参数：

参数	类型	必填	说明
page	int	否	默认1，最大 page_size=100
point_id	UUID	否	按写入点筛选
device_id	UUID	否	按设备筛选
result	string	否	`success
start_time / end_time	string	否	ISO 8601，最大跨度31天
keyword	string	否	搜索 point_name

API 根据 data_type 把数据库 TEXT 转换为 JSON boolean/number：

{
    "id": "uuid",
    "point_id": "uuid",
    "point_name": "加药泵频率",
    "device_id": "uuid",
    "device_name": "一期加药间PLC",
    "address": "DB2.10",
    "data_type": "REAL",
    "unit": "Hz",
    "source": "manual",
    "target_value": 20.5,
    "readback_value": 20.50001,
    "result": "success",
    "error_message": null,
    "operator": null,
    "reason": "工艺调整",
    "created_at": "2026-07-09T10:00:00+08:00"
}

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,
    unit            VARCHAR(32),

    source          VARCHAR(16) NOT NULL DEFAULT 'manual' CHECK (source = 'manual'),
    target_value    TEXT NOT NULL,
    readback_value  TEXT,
    result          VARCHAR(16) NOT NULL CHECK (result IN ('success', 'failed', 'timeout')),
    error_message   TEXT,
    operator        VARCHAR(64),
    reason          VARCHAR(500),
    created_at      TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_write_logs_point_id ON write_logs(point_id);
CREATE INDEX idx_write_logs_device_id ON write_logs(device_id);
CREATE INDEX idx_write_logs_created_at ON write_logs(created_at DESC);

5. 采集引擎（运行时）

5.1 架构概述

采集引擎是嵌入 Web 服务进程的后台常驻组件，负责执行实际的数据采集任务。

运行模型采用单进程嵌入式：cmd/server/main.go 是唯一的生产可执行入口。服务启动时初始化采集引擎并启动其后台协程；服务关闭时先停止接收新请求，再停止采集引擎并释放设备连接。采集引擎不作为独立的 cmd/collector 进程运行，因此 API 服务可通过进程内依赖访问其运行时状态。

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

5.2 启动流程

1. Web 服务完成依赖初始化后启动采集引擎
2. 从数据库加载所有 enabled=true AND deleted=false 的设备
3. 从数据库加载所有 enabled=true AND deleted=false 的采集点，按 device_id 分组
4. 对每个设备，尝试建立连接：
   a. 连接成功 → 标记为"已连接"，启动该设备下所有采集点的采集任务
   b. 连接失败 → 标记为"断开"，启动重连计时器
5. 调度器按 collect_interval 生成点位任务并投递到有界 worker pool；同一设备的协议操作串行执行

5.3 采集任务执行流程

每个点位到期时：
1. 调度器生成任务并投递到有界 worker pool；队列满时记录告警，不无限创建 goroutine。
2. 获取该设备的独立 ProtocolConnection，并进入设备级串行命令队列。
3. 读取和解析：
   - 成功且值在有效范围内（或未配置范围）→ value=实际值, quality=good；
   - 成功但超出 valid_min/valid_max → value=实际值, quality=bad, quality_reason=out_of_range；
   - 超时/断线/读取失败/解析失败 → value=null, quality=bad，并填写稳定 quality_reason。
4. 更新内存 latest_values：{value, quality, quality_reason, ts}。
5. store_history=true 且到达 history_interval 时写入 TDengine。
6. 首次准备写入历史数据前设置 history_started_at；设置成功后即禁止修改 device_id/data_type。
7. 如配置 MQTT，由独立发布队列异步发送，MQTT 失败不得阻塞采集任务。

5.4 质量戳判定规则

条件	value	quality	quality_reason	TDengine quality
读取、解析成功且在有效范围内	实际值	`good`	null	0
读取成功但超出有效范围	实际值	`bad`	`out_of_range`	1
协议超时	null	`bad`	`timeout`	1
设备断开	null	`bad`	`disconnected`	1
读取异常	null	`bad`	`read_error`	1
解析异常	null	`bad`	`parse_error`	1
查询目标时间无记录	null	`none`	null	不落库

API 始终返回字符串质量戳。none 只表示查询没有匹配记录；不得用 bad 代替缺失，也不得用 0 或上次值填充失败读取。

5.5 断线重连机制

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

5.6 动态配置更新

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

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

实现方式：Service 在配置事务提交后发布进程内变更事件，采集引擎正常情况下 1 秒内处理；同时每 5 秒按配置版本执行一次全量校对，作为丢事件后的兜底，因此对外保证 5 秒内最终生效。

5.7 TDengine 数据写入

5.7.1 超级表定义

CREATE STABLE IF NOT EXISTS collection_data (
    ts              TIMESTAMP,
    value           DOUBLE,           -- 可空；BOOL 使用 0/1
    quality         INT,              -- 0=good, 1=bad
    quality_reason  VARCHAR(32),      -- 可空稳定原因代码
    point_id        VARCHAR(36),
    point_name      VARCHAR(128)
) TAGS (
    device_id       VARCHAR(36),
    device_name     VARCHAR(128),
    data_type       VARCHAR(16)
);

point_id、device_id 使用 36 位标准 UUID。point_name、device_name 和 data_type 是写入/建表时快照；历史 API 的当前显示名称、单位和生命周期状态以 PostgreSQL 元数据为准。

5.7.2 子表创建策略

每个采集点对应一个子表。子表名由已校验 UUID 的规范化小写形式派生：固定前缀 p_ 加上去除连字符后的 32 位十六进制字符串，即 p_<uuid32>。不得接受或使用请求中直接传入的表名。

-- 假设采集点ID为: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
-- 子表名: p_a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d
CREATE TABLE IF NOT EXISTS p_a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d
USING collection_data TAGS (
    'd2e3f4a5-b6c7-4d8e-9f01-a2b3c4d5e6f7', '一期曝气柜PLC', 'REAL'
);

5.7.3 写入策略

首次准备历史写入前设置 history_started_at，然后使用 INSERT INTO ... USING ... TAGS 创建/写入子表
批量写入：每1秒或每100条数据一批；服务关闭前尽力刷新
store_history=false 时停止新增历史记录，但已存在的数据仍可在历史模块中查询
写入频率由 history_interval 控制
动态子表名只由已验证 UUID 派生并通过 ^p_[0-9a-f]{32}$ 校验；时间和值参数仍使用参数绑定

5.8 运行时状态查询接口

采集引擎实现只读 DeviceRuntimeStatusProvider，由设备 Service 注入使用；Handler 不直接访问引擎。

type DeviceRuntimeStatusProvider interface {
    GetDeviceStatus(ctx context.Context, deviceID uuid.UUID) ConnectionStatus
    GetDeviceStatuses(ctx context.Context, deviceIDs []uuid.UUID) map[uuid.UUID]ConnectionStatus
}

状态枚举：connected | disconnected | disabled。设备 Service 根据持久化 enabled/deleted 与运行时状态统一计算响应：禁用或删除始终为 disabled；启用但引擎无状态时为 disconnected。

采集引擎和最新值缓存均为进程内组件，通过公开接口注入相应 Service；不得由 Handler 获取单例或读取内部 map。

6. 写入引擎（运行时）

6.1 架构概述

写入引擎负责接收人工写入请求、执行写入操作并返回结果。当前阶段未接入身份认证或自动写入；服务端将每次请求记录为 source=manual、operator=null，表示发生了未认证的人工写入请求，而非已识别具体操作者。

写入请求
    │
    ▼
┌─────────────────────┐
│  请求校验             │
│  - 写入点是否存在      │
│  - write_enabled=true │
│  - 值类型校验          │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  指令执行             │
│  - 获取设备连接        │
│  - 调用协议驱动写入     │
│  - 回读验证            │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  结果记录             │
│  - 写入 write_logs   │
│  - 返回结果给调用方    │
└─────────────────────┘

6.2 写入安全策略

write_enabled 开关：写入点必须显式开启 write_enabled=true 才能写入，防止误操作
回读验证：BOOL/INT 严格相等；REAL 满足 abs(actual-target) <= readback_tolerance 才算成功
操作记录：所有写入操作记录到 write_logs，包含日志 ID、时间、点位、目标值、回读值、结果、失败原因和原因；当前阶段不记录具体操作者
访问边界：当前阶段未实施身份认证，写入 API 仅应部署在受信任的内部网络；接入身份认证后再补充操作者归属与权限控制

7. 协议插件化架构

7.1 接口定义

协议注册表保存无状态工厂；每个设备创建独立连接实例。

type DataType string

const (
    DataTypeBool DataType = "BOOL"
    DataTypeInt  DataType = "INT"
    DataTypeReal DataType = "REAL"
)

type DeviceConnectionConfig struct {
    DeviceID       uuid.UUID
    Host           string
    Port           int
    ConnectTimeout time.Duration
    ProtocolConfig map[string]any
}

type ProtocolDriverFactory interface {
    ProtocolType() string
    ValidateConfig(config map[string]any) error
    ValidateAddress(address string, dataType DataType, writable bool) error
    ConfigSchema() map[string]any
    NewConnection(ctx context.Context, cfg DeviceConnectionConfig) (ProtocolConnection, error)
}

type ProtocolConnection interface {
    Read(ctx context.Context, address string, dataType DataType) (float64, error)
    Write(ctx context.Context, address string, dataType DataType, value float64) error
    Close() error
}

约束：

Factory 必须无连接状态、可并发调用。
每个设备持有一个独立 ProtocolConnection。
Connection 默认不要求并发安全；ConnectionManager 必须按设备串行调度 Read/Write。
所有调用接收 context.Context，超时和取消由上层控制。
Close 必须幂等。

7.2 注册机制

type ProtocolRegistry struct {
    mu        sync.RWMutex
    factories map[string]ProtocolDriverFactory
}

func (r *ProtocolRegistry) Register(factory ProtocolDriverFactory) error {
    protocolType := factory.ProtocolType()
    r.mu.Lock()
    defer r.mu.Unlock()
    if _, exists := r.factories[protocolType]; exists {
        return fmt.Errorf("协议已注册: %s", protocolType)
    }
    r.factories[protocolType] = factory
    return nil
}

func (r *ProtocolRegistry) Get(protocolType string) (ProtocolDriverFactory, error) {
    r.mu.RLock()
    defer r.mu.RUnlock()
    factory, ok := r.factories[protocolType]
    if !ok {
        return nil, ErrUnsupportedProtocol
    }
    return factory, nil
}

注册错误必须在应用启动阶段暴露并终止启动，不使用隐藏失败的包级可变全局变量。

7.3 扩展新协议

实现 ProtocolDriverFactory 和设备级 ProtocolConnection；
为配置、地址、读写、超时、取消和并发隔离编写测试；
在应用装配阶段显式注册；
前端通过 ConfigSchema() 渲染协议配置表单；
更新协议列表和配置导入校验。

7.4 当前协议

7.4.1 S7

属性	说明
ProtocolType	`S7`
默认端口	102
连接粒度	每设备一个连接实例
地址解析	见 3.1.2
配置	`rack`、`slot`

7.4.2 Modbus TCP

属性	说明
ProtocolType	`MODBUS_TCP`
默认端口	502
连接粒度	每设备一个连接实例
地址解析	见 3.1.2
配置	`unit_id`、`float32_order`，其中 `float32_order ∈ {ABCD,BADC,CDAB,DCBA}`

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

A.1 页面布局

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

左侧导航栏说明：

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

A.2 子页面：设备管理

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

A.3 子页面：数据采集

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

A.4 子页面：数据写入

写入点列表表格（名称 | 分组 | 所属设备 | 地址 | 数据类型 | 单位 | 回读容差 | 允许写入 | 操作）
新增/编辑写入点弹窗（配置是否允许写入）
执行写入操作弹窗：输入值和可选原因，点击确认后执行并显示结果
写入操作日志查看（展示未认证人工写入的时间、点位、值、结果和原因）
导入/导出CSV按钮

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

编号	规则	说明
R001	设备名称全局唯一	逻辑删除的记录不参与唯一性校验
R002	采集点名称全局唯一	同上
R003	写入点名称全局唯一	同上
R004	逻辑删除级联	删除设备时，该设备下所有采集点和写入点也逻辑删除
R005	采集地址格式校验	根据设备协议类型校验地址格式，创建设备时即确定协议
R006	采集周期最小1秒	不可低于1秒
R007	历史存储间隔范围	1~1440 分钟；当store_history=true时必填
R008	人工写入记录	服务端固定记录 source=manual、operator=null；当前阶段不支持自动写入
R009	写入回读验证	BOOL/INT严格相等；REAL按readback_tolerance判断，不一致重试1次
R010	写入点地址类型限制	必须使用可写地址类型
R011	质量戳自动判定	失败时value=null且bad；越界时保留value并标记bad；无匹配记录为none
R012	断线无限重连	持续按配置间隔重连，直到成功或设备被禁用
R013	配置变更动态生效	事务后事件正常1秒内生效，5秒全量校对保证最终一致
R014	历史语义不可变	history_started_at非空后不可修改device_id或data_type
R015	协议连接隔离	注册Factory，每个设备独立Connection，同设备读写串行

本文档版本：v1.2 最后更新：2026-07-11

49 KiB Raw Blame History Unescape Escape

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

目录

1. 概述

1.1 模块定位

1.2 模块边界

1.3 核心概念关系

2. 设备管理

2.1 数据模型

2.1.1 数据库表：devices

2.1.2 协议类型枚举

2.1.3 各协议 protocol_config 定义

2.1.4 设备的业务状态

2.2 RESTful API

2.2.1 接口列表

2.2.2 接口详细定义

3. 数据采集点管理

3.1 数据模型

3.1.1 数据库表：collection_points

3.1.1.1 历史模块只读元数据接口

3.1.2 各协议的地址格式

3.1.3 分组机制

3.1.4 实时数据

3.2 RESTful API

3.2.1 接口列表

3.2.2 接口详细定义

4. 数据写入点管理

4.1 数据模型

4.1.1 数据库表：write_points

4.1.2 与采集点的区别

4.1.3 地址与回读规则

4.2 RESTful API

4.2.1 接口列表

4.2.2 写入点 CRUD

4.2.3 执行写入

4.2.4 写入日志

5. 采集引擎（运行时）

5.1 架构概述

5.2 启动流程

5.3 采集任务执行流程

5.4 质量戳判定规则

5.5 断线重连机制

5.6 动态配置更新

5.7 TDengine 数据写入

5.7.1 超级表定义

5.7.2 子表创建策略

5.7.3 写入策略

5.8 运行时状态查询接口

6. 写入引擎（运行时）

6.1 架构概述

6.2 写入安全策略

7. 协议插件化架构

7.1 接口定义

7.2 注册机制

7.3 扩展新协议

7.4 当前协议

7.4.1 S7

7.4.2 Modbus TCP

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

A.1 页面布局

A.2 子页面：设备管理

A.3 子页面：数据采集

A.4 子页面：数据写入

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

49 KiB

Raw Blame History