文档手册

Tag：从建站点到诊断读值

一个 Tag 不是单独的一行配置，它是一条从现场到页面的路径：站点说明这台 HQControl 属于哪里，设备说明它去连哪台 PLC 或数据源，Tag 说明读 PLC 的哪个地址、按什么数据类型解析、多久采一次，Tag 诊断说明这条路径现在有没有真实值。后续章节也按这个写法展开：先讲入口和顺序，再讲每个可见控件，最后讲如何验证。

数据地基

数据地基: Tag：从建站点到诊断读值

Tag 是 HQControl 的数据地基。画面上的数字、报警的阈值、趋势的曲线、第三方接口的实时值，都不是各自去连 PLC，而是共同读取这份 Tag 主数据和最新值。第一次上手不要先配报警、趋势或画面绑定，按真实顺序走：先建站点，再连设备或 PLC，再建 Tag，最后用 Tag 诊断确认读到值。

先把 Tag 放在整条链路里看

建站点：给本机一个稳定站点身份。
连设备：让 IO Worker 知道要连哪台 PLC、走哪种协议。
建 Tag：把 PLC 地址、符号路径或寄存器映射成系统统一点名。
Tag 诊断：用实时值、质量和时间戳确认这条链路已经通。

第一步：建站点，先确定本机身份

进入“Sites / 站点管理”，先确认默认站点、本地节点和访问名。单机项目通常只需要确认默认站点启用，并且和系统状态里的本地站点一致。联邦、冗余或多站点项目才需要继续维护远端站点、备用节点和访问名。站点编码以后会出现在联邦拓扑、当前采集节点和设备归属里，所以不要因为显示名称变化就随手改编码。

站点编码：稳定身份，给联邦、冗余和设备采集关系引用。
站点名称：给人看的名称，可以比编码更友好。
本地节点：当前这台 HQControl 所在节点，系统状态里也会显示。
访问名：其他浏览器或站点访问这台机器时使用的主机名、域名或固定地址。
改完站点后回系统状态，看本地站点、节点和联邦拓扑是否按预期变化。

第二步：连设备或 PLC，先让采集链路站起来

进入“Devices / 设备连接”，点击新增设备连接。设备页决定 HQControl 连接哪台 PLC 或数据源：设备编码、显示名称、协议类型、地址模式、Host、Port、Rack、Slot、Unit ID、轮询开关、默认扫描周期、连接超时、请求超时、重连间隔、最大并发请求、批量读取和启用状态都在这里。保存后应先确认设备连接成功、IO 模块无告警，再批量建立 Tag。

设备编码：Tag 导入和完整点名会引用它，正式使用后不要随意改。
协议类型：按真实链路选择 Siemens S7、OPC UA、Modbus TCP 或内部变量，不要为了简化操作混用。
地址模式：S7 绝对地址走 DB/Byte/Bit，S7 符号地址走 OPC UA 符号路径。
Host / Port：主机和端口要对应真实协议，S7 TCP 常见 102，OPC UA 常见 4840，Modbus TCP 常见 502。
Rack / Slot：只用于 S7 绝对地址链路，符号地址不要拿它判断可用性。
Unit ID：Modbus TCP 从站或单元 ID，按设备说明书填写。
扫描周期和超时：先用稳妥默认值，单台慢 PLC 优先调设备自身，不要先放大全站默认值。

连接方式先分叉：S7 绝对、S7 符号、Modbus 不要混着填

设备是否能连上，和 Tag 地址是否能读对，是两件事。连接检查通过只说明网络、握手或会话大体可用，不代表每个 DB、符号路径、寄存器和数据类型都正确。这里要把三条常见链路先分清。

S7 绝对地址：设备用 S7 TCP，通常端口 102，Tag 填 S7 地址区、DB 号、偏移量和博图数据类型。
S7 符号地址：设备地址模式切到符号地址，连接目标是 OPC UA Endpoint，例如 opc.tcp://192.168.1.222:4840，Tag 填 symbolicAddress。
OPC UA 符号链路：要在 PLC 或网关侧开启 OPC UA Server，确认 Endpoint、安全策略、证书、账号和变量访问权限。
Modbus TCP：确认 Unit ID、寄存器类型、寄存器地址号、地址基准、字节序和数据类型。
数组、UDT 和复杂结构先拆成明确标量 Tag，再进入 HQControl。
连接检查通过以后，仍要用 Tag 诊断确认具体 Tag 的值、质量和时间戳。

第三步：进入 Tag 管理，先读懂列表顶部控件

进入“Tags / Tag 管理”以后，先不要直接点新增。顶部控件决定当前查看的 Tag 范围：设备筛选、功能组、设备组、信号分组和搜索框会一起收窄结果；Table 是表格视图，Group Tree 按功能组、设备组、信号分组展开，Name Tree 按点名分段展开。树视图是按需加载，展开分支时才请求子节点，大项目里这是正常表现。

设备筛选：只看某台设备下的 Tag，也是下载模板和导入时最重要的上下文。
功能组 / 设备组 / 信号分组：只筛选已经填写这些归属字段的 Tag，空归属不会自动补成层级。
搜索框：支持输入 Tag 片段，也可配合 ? 或 * 做模糊匹配。
Table / Group Tree / Name Tree：分别适合批量核对、按归属查、按点名层级查。
Refresh / 刷新：重新加载设备、Tag 和统计，导入或批量修改后先点它确认结果。
Load More / 加载更多：列表未全量加载时继续拉取后续 Tag；全选只作用于已加载范围。

新增或编辑 Tag：先确认归属边界

点击“新增 Tag”会打开抽屉。第一组是“归属”：设备、设备协议、功能组、设备组、信号分组和 Tag。设备是必选项，设备协议是只读提示，来自所选设备；Tag 名称只允许字母、数字、-、_，并支持用 . 分段，不能包含 [ 或 ]，因为方括号保留给读位表达式。

设备：选择这条 Tag 属于哪台 PLC 或数据源。
设备协议：只读显示当前设备协议，用来提醒下面会出现哪类地址字段。
功能组：产线、区域、工段或系统，例如 Line01、Water。
设备组：对象或设备单元，例如 Pump01、ValveGroup03。
信号分组：点位用途，例如 status、control、diagnosis。
Tag：本设备内的点名，导入、画面绑定、报警、趋势和接口都会引用它。
归属字段不是强制树。现场没有对应层级时可以留空，不应为了层级显示而填写不真实的归属。

地址与采集组：按设备协议填，不要跨模式混填

第二组是“地址与采集”。这个区域会根据设备协议和地址模式变换字段。内部变量会显示变量类型、断电保持、设置初始值和初始值；S7 符号地址显示符号地址和博图数据类型；S7 绝对地址显示 S7 地址区、DB 号、博图数据类型和偏移量；Modbus 显示寄存器类型、寄存器地址号和 Modbus 数据类型；OPC UA 显示 OPC 通道、OPC 设备和 OPC 地址。底部的“地址”是只读预览，用来确认系统最终会怎样解析这条地址。

内部变量：适合系统内部状态或脚本写入值，不直接读 PLC。
断电保持：开启后重启仍保留最后一次写入值。
设置初始值：没有运行写入值时使用，已有写入值优先。
符号地址：填写 PLC 符号变量路径，不再填写 DB 号和偏移量。
S7 地址区 / DB 号 / 偏移量：用于绝对地址，偏移量可以表达字节或位偏移。
寄存器类型 / 寄存器地址号：用于 Modbus，必须和设备说明书的地址基准一致。
地址预览：保存前看一眼，发现模式不对时先改设备或地址字段。

状态组：先决定这条 Tag 参与哪些运行能力

第三组是“状态”。启用是总开关，关闭后这条 Tag 不参与采集和运行显示。启用报警表示这条 Tag 会进入报警判断，勾选后还要选择报警类型：故障或警告。启用趋势表示这条 Tag 参与趋势归档和趋势查询。不要在 Tag 还没读到稳定值时批量打开报警和趋势，否则后续会把地址错误、类型错误和真实工艺异常混在一起。

启用：控制这条 Tag 是否参与采集和运行显示。
启用报警：只表示参与报警判断，阈值和规则还要到报警配置里维护。
报警类型：故障用于停机、保护、严重异常；警告用于提醒和非停机风险。
启用趋势：只表示进入趋势归档和查询范围，留存周期还要看数据留存策略。
删除：只在编辑已有 Tag 时显示；被画面、报警、趋势、接口引用的点位不应直接删除。

导入、模板和 Target ID：批量操作也要有可追踪目标

Tag 多时优先用模板导入。先在顶部选择设备，再打开“模板说明”，下载“模板 JSON”或“模板 Excel”。导入文件里的 deviceCode 必须和本机设备编码完全一致，大小写也要一致；code 是本设备内 Tag 名称，不能靠显示名、符号地址或地址自动生成。导入会先做预检查，结果里的 targetId 是本次导入行的目标标识，用于标识哪一行会新增、更新、跳过或报错。

Import / 导入：读取 JSON 或 Excel，解析后先进入预检查，不是立刻无脑写库。
Template Guide / 模板说明：解释当前设备协议对应的必填列、示例行和规则。
Template JSON / Template Excel：按当前设备和地址模式下载模板。
Import / 确认导入：预检查通过后才提交批次。
Cancel / 取消导入：发现设备编码、地址或类型不对时先取消，改文件后重来。
targetId：导入预检查和结果里用于定位行的目标 ID；重复 targetId 会被标记为重复目标。
跨服务器导出的文件可以导入，但必须先在本机建好匹配设备编码。

批量、导出和树视图：大项目先缩小范围再动手

顶部的选择和批量按钮用于已经加载出来的结果。Select Loaded / 全选已加载只选当前已加载范围，不代表数据库里的全部 Tag。Clear Loaded / 取消已加载选择、Clear Selection / 清空选择用于撤回选择。Batch Edit / 批量修改只会修改已勾选的字段，可批量改功能组、设备组、信号分组、报警启用、趋势启用和启用状态。Export All JSON / Excel 会按当前导入导出字段导出全量 Tag，适合交付留档或离线复核。

先用设备和分组筛选缩小范围，再全选已加载。
批量修改抽屉里每个字段前都有勾选框，没勾选的字段保持原样。
一次批量修改有数量上限，超出时继续缩小筛选范围。
导出 JSON 适合系统间迁移或版本对比。
导出 Excel 适合现场复核、客户签字和批量修订。
Expand / Collapse 只控制树视图展开收起，不改变 Tag 数据。

第四步：用 Tag 诊断确认真的读到值

建完 Tag 后进入“Tag Diagnosis / Tag 诊断”。左侧是可浏览的 Tag 库：顶部搜索支持 Tag 片段、? 或 *，树里先展开服务器，再展开设备，再双击或拖拽 Tag 到右侧。右侧“已选 Tag”显示当前要验证的点，值卡片会显示质量、实时值来源和时间戳。

Refresh List / 刷新列表：重新加载设备和 Tag 目录。
Read Now / 即时读取：让 IO Worker 对已选 Tag 做一次即时读取，GOOD/BAD 以本次读取为准。
Reconnect / 重连：重建 WebSocket 订阅，排查页面更新链路。
Clear Selected / 清空选择：清掉右侧已选 Tag 和当前结果。
质量 GOOD：值可信，可以继续配置画面、报警和趋势。
bad_address：地址写错、DB/寄存器/符号路径不存在或越界。
bad_type：地址能读，但数据类型和现场实际不匹配。
stale / timeout / no_data：看设备在线、当前采集节点、扫描周期和网络延迟。

本章样板：后续章节也按这个深度写

后续每章都照这个深度：开头先说明这个功能在整条链路里的位置，再按真实上手顺序讲入口、控件、字段、按钮、保存后去哪验证；配图不是装饰图，标题要写 UI 对象，说明文字要告诉读者用这张图判断什么。像 targetId、Load More、Read Now 这种容易被忽略的小控件，也要解释它出现在哪里、改变什么、不改变什么。

写作顺序：先场景，再入口，再控件，再验证，再常见错误。
字段说明：只讲当前 UI 看得到的字段；后端字段不要写成用户入口。
按钮说明：写清点击后发生什么、是否立即写库、是否需要确认。
配图标准：使用当前高清界面图，alt 描述页面，caption 说明判断动作。
验收标准：读者照着走，能从空站点走到一个 GOOD 质量的 Tag。

HQControl 设备连接列表 — **图示 1: 设备连接**
设备连接页集中维护协议、主机、端口、Rack、Slot、扫描周期和批量读取等采集参数。

HQControl Tag 管理页面 — **图示 2: Tag 管理**
Tag 管理承接地址、数据类型、扫描周期、报警趋势参与状态和控制能力，是画面与接口的共同基础。

HQControl Tag 编辑页面 — **图示 3: Tag 编辑**
编辑 Tag 时要同时确认设备、地址模式、数据类型、采集周期、报警趋势参与状态和控制权限。

HQControl Tag 诊断页面 — **图示 4: Tag 诊断**
Tag 诊断用于现场复核实时值、质量、时间戳和写入结果，是画面排障前的第一层验证。