帮助中心

Appearance

5. 数据字典 ​

本章解释 DASS2 测点/上传点各字段的含义、取值范围与限制，用于填写点表、构造请求体和解读响应。

口径说明：中文名称取自 DASS2 前端 dasserver-ui 的字段标签（src/config/i18N.js 的 pointEdit 段），字段含义取自后端结构体注释（models/repositories/point_repository.go），枚举取值与长度限制取自后端真实校验代码。三者一致时不再分别标注。

5.1 三层 ID：ID / UID / PID 别搞混 ​

这是 DASS2 数据模型里最容易出错的地方——同一个测点有三个「ID」：

字段中文名含义谁分配备注
IDIDDASS2 关系库（SQLite）自增主键系统只在本地库里有意义，用于接口寻址
UID—本地实时库（openPlant）测点 ID用户填 / 系统分配点表里的 ID 列写的就是它；≥1024
PID—云端实时库测点 ID云端本机不维护，通常为 0

【警告】点表模板里的列名叫 ID，但它对应的是实时库点号 UID，不是数据库主键。这是两份「ID」语义打架的地方，导入时不要试图去匹配接口返回的 ID。

对照实测：

json
{"ID":226,"UID":1026,"PID":0,"PN":"AX002","GN":"W3.JEN.AX002","SN":"jen"}

点表里填的 ID=1026 → 落到接口返回的 UID=1026；接口返回的 ID=226 是本地库自增主键。

GN（全局名称）= 节点名.点名，例如节点 W3.JEN + 点名 AX002 → W3.JEN.AX002，全节点唯一。

5.2 测点字段全表 ​

5.2.1 导入模板的 34 列 ​

实测 POST /v1/point/template/{dasId} 下载的 xlsx，第一个工作表表头为 34 列，顺序如下：

ID  PN  AN  RT  ED  EU  AD  SR  EVENT  REDATA1  PH  PL  FK  FB  AP
H4  LC  H3  ZH  HL  LL  ZL  L3  L4  KR  IV  FM  FQ  TV  BV  KZ  DT  DB
列中文名导入时是否必需说明
IDID条件必需实时库点号（写入 UID）。数字、≥1024、文件内不可重复。isLink=true（自动添加到实时库）时可留空由系统分配；isLink=false 时必填
PN点名必需节点下唯一。字符集：数字、大小写字母、# : @ - _。长度见 5.4。导入时自动转大写
AN别名否测点别名
RT类型（数据类型）必需列表头数据存到 openPlant 的类型，见 5.3.1
ED描述否自由文本
EU量纲否工程单位，如 kg、s、℃
AD地址信息否驱动侧地址，格式随驱动而变（如 Modbus 为 1.3.0）
SR采集点类型否由驱动定义，取值受该驱动支持的列表限制，见 5.3.2
EVENT控制字段否整数，写入 Event
REDATA1保留字段1否留空时默认写入 "1"（不是空字符串！）
PH测点上限否数值，float64
PL测点下限否数值，float64
FK比例系数否数值，默认 1
FB偏移量否数值，默认 0
AP报警级别否整数
H4报警高4限否数值
LC报警属性否整数
H3报警高3限否数值
ZH报警高2限否数值
HL报警高限否数值
LL报警低限否数值
ZL报警低2限否数值
L3报警低3限否数值
L4报警低4限否数值
KR特征字否文本
IV初始值否数值
FM显示格式否整数（int16），枚举由前端 / 实时库定义，后端不校验
FQ分辨率否整数（int32）
TV量程上限否数值。校验：不得小于 BV
BV量程下限否数值。校验：不得大于 TV
KZ压缩类型否见 5.3.4
DT死区类型否见 5.3.3
DB死区否数值，默认 0.2，不可小于 0

5.2.2 接口返回但不属于导入模板的字段 ​

GET /v1/point* 返回的测点对象比模板列更多，以下是补充字段：

字段中文名说明
PID—云端实时库测点 ID
GN全局名称节点名.点名，唯一
SN—所属采集服务的名称（不是 ID）
CP设备号文本
EX计算公式计算点使用
DS当前状态位域，见 5.3.5
AV实时值类型自适应：可能返回数字或字符串；orm:"-"，不落库
AS状态文本状态
TM最后更新时间Unix 时间戳（秒）
FLAG操作状态云端交互用，新导入的点实测为 "adding"
SYNC操作状态云端交互用
UM操作状态云端交互用
REDATA1 / REDATA2保留字段1 / 2自由使用
C1~C8报警限颜色分别对应 LL / ZL / L3 / L4 / HL / ZH / H3 / H4 的颜色
PT点的来源整数
KT计算类型整数
MAXV MINV MAXTIME MINTIME AVGV FLOW统计值最大/最小值与时刻、平均值、流量

【注意】AV（实时值）字段类型不稳定——同一接口在不同测点类型下可能返回数字或字符串。客户端反序列化请用「任意类型」或用字符串兜底，不要强类型绑定成 float。

5.3 枚举速查 ​

5.3.1 RT 数据类型（存到 openPlant 的类型） ​

点表填落库值含义
AX0模拟量输入
DX1开关量输入
I222 字节整型
I434 字节整型
R848 字节浮点
LONG5长整型
TEXT6文本
BLOB7二进制块

【注意】比较时大小写不敏感（后端先 ToUpper）。RT 是表头必需列——缺这个列整批导入直接失败。

5.3.2 SR 采集点类型 ​

SR 的合法取值由驱动决定，不是全局固定枚举。导入时后端会拿它跟该服务所用驱动支持的列表比对，不在列表内则报 采集点类型不匹配。

正确姿势：先 GET /v1/point/sr 或 GET /v1/driver/conf/{driverId} 拿到该驱动支持的 SR 列表，再填点表。实测模板里出现过 INT16、FLOAT，但不要把它们当成全集。

5.3.3 DT 死区类型 ​

点表填落库值含义
（任意其它值 / 空）0默认
ENG1工程量死区

【注意】后端逻辑是「先置 0，再判断是否等于 ENG」，所以任何非 ENG 的字符串都会静默变成 0，不会报错。

5.3.4 KZ 压缩类型 ​

点表填落库值含义
（任意其它值 / 空）0默认
LINEAR1线性压缩
NONE2不压缩

【注意】与 DT 同样的问题：非法值静默降级为 0，不报错。

5.3.5 DS 当前状态（位域） ​

DS 不是枚举，而是位掩码。DASS2 前端据此分三态：

状态判定条件
Good(DS & (1 << 15)) == 0
Timeout(DS & (1 << 15)) != 0
Bad(DS & (1 << 9)) != 0

实测新导入未取值的测点 DS = -32768（即 1 << 15 置位），属于 Timeout 态，这是正常的，不代表导入失败。

【注意】/v1/point 查询接口支持用 DS 过滤，传的是状态名（Good / Bad / Timeout）而不是数值；传别的会直接报 非法的测点状态。

5.3.6 UM 操作状态 ​

consts/consts.go 中只定义了一个取值：

值含义
adding新增中（导入后尚未与云端同步）

实测新导入测点的 FLAG 为 "adding"。该字段族（FLAG / SYNC / UM）用于与云平台的状态交互，本地二次开发一般不必关心。

5.3.7 服务状态 ​

值含义
running运行中
stop已停止
error异常（此时只能执行退出）

5.4 长度与数量限制 ​

实测通过 GET /v1/system/conf 读取真机限制：

配置项实测值含义
Base.MaxPnLength32点名（PN）长度上限，单位按字符计。conf/dasserver.conf 中对应 pn.length=32
Base.MaxLengthServiceName11服务名长度上限，与《使用手册》「长度不超过 11 位」一致
Service.MaxNumber10采集服务最大数量
Point.MaxNumber2000测点最大数量
License.MaxLicense(密钥串)授权信息
License.DeviceIA-22授权绑定的设备型号前缀

【注意】点名上限是 32，不是 60。 DASS2 与 DASS5 的口径不同：DASS5 的点名上限是 60 字节，DASS2 实测为 32（char(32) 的老文档口径对 DASS2 是准确的）。跨版本搬运点表时务必注意。
【注意】测点数量受**授权（License）**约束，不只是 Point.MaxNumber。导入前建议核对 GET /v1/mqtt/baseInfo 的 licensePoint / userdPoint。

其它后端常量（consts/consts.go）：

常量值含义
QueryLimit1000单次查询上限
MaxInsertNumber10000单次插入上限
MaxUpdateNumber100000单次更新上限
MaxDeleteNumber10000单次删除上限
MaxCsvRecordLength100000CSV 记录长度上限
DefaultPagenum20默认分页条数

【警告】点表单批行数受 MaxInsertNumber（10000）约束。超大批量请拆分成多个 xlsx 分批导入，因为导入是同步阻塞的，一个超大文件很容易把请求拖到超时。

5.5 采集点（point）与上传点（upoint）的关系 ​

两者字段结构几乎完全相同（同一套 Point 结构体），区别在「数据流向」与「归属」：

维度采集点 point上传点 upoint
方向从设备/驱动采进来向上一级传出去
归属服务driverType = das 的采集服务driverType = upload 的上传服务
SN 字段采集服务名上传服务名（两者可以不同！）
典型 RT随采集数据而定需与云端约定一致
接口/v1/point/*/v1/upoint/*

实测对照（同一台设备）：

json
// GET /v1/point?limit=1  → 采集点，SN=jen
{"ID":226,"UID":1026,"PN":"AX002","GN":"W3.JEN.AX002","SN":"jen","RT":0,"FLAG":"adding"}

// GET /v1/upoint?limit=1 → 上传点，SN=mqtt（上传服务）
{"ID":124,"UID":1029,"PN":"DX001","GN":"W3.JEN.DX001","SN":"mqtt","RT":1,
 "CP":"DX001;QZ-TEST-METER-005;METER-005;desc; Nari; PDZ833"}

注意上传点的 GN 仍是 W3.JEN.DX001（沿用采集节点名），但 SN 是上传服务 mqtt。

【注意】上传点的 CP（设备号）字段实测承载了分号分隔的复合信息（点号;设备名;设备编号;描述;厂商;型号），格式由上传驱动定义，不是单一设备号。填表时以对应上传驱动的配置说明为准。

5.6 上传点模板格式差异（实测） ​

两个模板接口返回的文件格式不同，前端下载逻辑也因此不同：

接口实测格式表头示例
POST /v1/point/template/{dasId}xlsx（响应体以 PK 开头）34 列，见 5.2.1
POST /v1/upoint/template/{dasId}CSV（纯文本）ID,AN,AD,SR,ED,FK,FB,EVENT

上传点模板实测内容：

csv
ID,AN,AD,SR,ED,FK,FB,EVENT
1046,g02,1.3.0,INT16,22,1,0,0
1047,g023,1.3.0,FLOAT,22,1,0,1

【警告】上传点模板列数与采集点不一致（8 列 vs 34 列），且是 CSV。不要把采集点模板直接拿去做上传点导入，也不要用同一个解析器处理两者。