docs: 更新网络注释规则说明

docs/ai/handoff.md

@@ -10,6 +10,14 @@
 - 本轮没有实现 Int64、无符号数、二/八/十六进制、ASCII、POU 变量监控、信捷原版寄存器网格或自定义监控偏移
 - TouchWin 没有原生 Double64 数值控件；本项目的 `Double (Float64)` HMI 是基于 PLC 连续四个 D 的增强能力
 
+## 梯形图网络注释
+
+- `ControlLogic::networkHeadIndex()` 统一判定网络首行；同一网络只允许首行的 `LadderRung.comment` 非空
+- 选中网络内任意支路编辑“网络注释”时，输入框读取并修改网络首行，画布也只在网络首行上方显示该注释
+- 用竖线或粘贴合并网络时，单侧注释移动到新首行，相同注释去重；两侧注释不同时整次操作原子失败并恢复拓扑、注释、修改状态和历史
+- 删除竖线拆分网络时不复制注释；新产生的下方网络默认没有注释
+- 旧的行注释接口已直接替换为网络注释接口，没有保留重载、适配层或回退分支；严格 `formatVersion: "2.0"` 工程若在支路行保存非空注释会直接拒绝，不迁移隐藏注释
+
 ## 梯形图竖线连续录入
 
 - 工具栏“竖线”和 `F12` 成功连接当前行与下一行后，会保持原列位置并自动选择下一视觉行；连续操作可以逐段向下建立竖线
@@ -60,6 +68,8 @@
 ## 最近验证
 
 - 13 个 Release Functional 测试目标全量通过
+- 网络注释回归覆盖从支路编辑首行注释、网络首行查找、单侧移动、相同注释去重、不同注释原子回滚、一次撤销/重做、拆分不复制、支路隐藏注释领域校验和严格 `2.0` JSON 拒绝
+- 离屏画布回归确认从支路编辑的注释只显示在网络首行上方
 - 新增回归覆盖 Int32 最小/最大值和负数、Float32 `20.0` 字序、Double `1.0` 字序、Double 偶数地址、NaN/Inf、JSON 往返、HMI 复制粘贴、多字冲突和 16 位梯形图写入保护
 - 监控回归覆盖四类型批量步长、完整轮询地址、离线初始值捕获、停止仿真恢复、64 行与 256 实际地址上限的候选拒绝
 - PLC 回归覆盖 Int16 单字路径、Int32/Double 一次多字回调、Double `D118~D121` 不跨 120 字边界、无法合法拆分的重叠范围拒绝和地址集合原子切换
@@ -68,11 +78,12 @@
 - 梯形图画线回归覆盖 `Esc` 退出鼠标画线和删线模式
 - Qt Release 主程序已重新构建到 `build/release/release/integrated_platform.exe`，离屏启动 3 秒正常保持事件循环
 - `git diff --check` 通过，没有空白错误
-- 本轮竖线改动只涉及编辑服务和画布交互，不访问 PLC，因此没有重复真机测试
+- 本轮网络注释改动只涉及领域模型、编辑服务、严格 JSON 校验和画布显示，不访问 PLC，因此没有做真机测试
 
 ## 工作区与下一步
 
-- 本轮代码和说明文档已提交 Git；工作区仅保留既有 `AGENTS.md` 修改和未跟踪的 docx 文件
+- 本轮网络注释代码、测试和说明文档已拆分提交；工作区还保留既有 `AGENTS.md` 修改和未跟踪的 docx 文件，不能覆盖或回退
+- 人工复查截图场景：用竖线连接 `000/001`，选中 `001` 编辑网络注释，确认注释出现在 `000` 网络首行上方
 - 设备可用后在 PLC STOP 状态先读取一组连续 D 原值，分别验证 Int32、Float32、Double 的一次多寄存器写入与读回，再恢复全部原值并读回确认
 - 人工打开控制逻辑页面，分别从网格、列边界和第 10 列位置连续按 F12，检查选中框、滚动和状态栏提示
 - 人工打开 HMI 页面和数据监控，检查四类型下拉框、Double 偶数地址提示、长数值显示和不同系统缩放下的输入框布局

docs/architecture.md

@@ -67,6 +67,7 @@ Project
 
 - 页面、逻辑、行、网格、节点和竖线使用稳定 ID；名称可修改，数组顺序决定视觉顺序和离线扫描顺序
 - 梯形图是连续网格：`Gap/Wire/Node` 是独立格子对象，竖线连接相邻行列边界，插入/删除行会维护连接关系，删线即可拆分网络
+- `ControlLogic::networkHeadIndex()` 是网络首行的唯一判定；每个网络只有首行的 `LadderRung::comment` 可以非空，支路行保存注释属于无效工程结构
 - 当前编辑页面和当前逻辑是 UI 会话状态，不写入工程
 - HMI 控件类型、默认值、绑定规则和运行值类型由无 Qt 依赖的 `hmi_control_registry` 统一描述
 - HMI 数值控件通过 `RegisterDataType` 选择 `Int16`、`Int32`、`Float32` 或 `Float64`；底层仓库始终保存原始 16 位 D 字，统一编解码层按低地址低字顺序组合 1、2 或 4 个连续 D
@@ -116,7 +117,7 @@ ApplicationSettings（启动后只读）
 
 连续梯形图不再使用串并联表达式树。`LadderRung` 是按视觉顺序排列的一行，前 10 列固定保存 `LadderCell`，每格独立表示 `Gap`、`Wire` 或条件 `Node`；第 11 列是独立输出槽。行之间的网络关系由 `ControlLogic::verticalConnections` 保存，每根竖线只连接相邻两行的一个 `0~10` 列边界。长竖线由多个相邻连接对象组成，因此可以逐段画线、删线、拆分和恢复。
 
-`LogicEditorService` 负责网格、竖线和行的原子编辑：横向手势批量设置 `Wire / Gap`，纵向手势批量创建或删除相邻 `VerticalConnection`，插入行会拆分原连接，删除行只在上下同列连接都存在时合并。一次鼠标手势和一次工具栏操作都只产生一条撤销记录，失败时回滚整个编辑。`LogicEditorWidget` 只负责命中测试、绘制和将服务结果投影到画布，不直接修改工程容器。
+`LogicEditorService` 负责网格、竖线、行和网络注释的原子编辑：横向手势批量设置 `Wire / Gap`，纵向手势批量创建或删除相邻 `VerticalConnection`，插入行会拆分原连接，删除行只在上下同列连接都存在时合并。用户从任意支路编辑网络注释时，服务统一读写网络首行；竖线或粘贴合并网络时，单侧注释移动到新首行，相同注释去重，不同注释阻止整次合并。一次鼠标手势和一次工具栏操作都只产生一条撤销记录，失败时回滚整个编辑。`LogicEditorWidget` 只负责命中测试、绘制和将服务结果投影到画布，不直接修改工程容器。
 
 梯形图复制使用服务层值对象 `LogicClipboardFragment`，不保存源模型指针。`GridObjects` 模式按相对行列保存明确选中的 `Wire / Node`、输出和竖线，未选位置不写入片段，也不把 `Gap` 当成待覆盖内容；`WholeRows` 模式只由左侧行号选择产生，保存完整 10 格、输出、注释和选中行内部的竖线。`LogicEditorService::pasteClipboard()` 先校验全部目标行列、对象类型、冲突和数量上限，再统一分配新 ID 并提交一次历史记录；任一目标非法时恢复模型和工程修改状态。当前光标行与明确整行选择是两份独立 UI 状态，不能互相回退。
 

docs/工程格式说明.md

@@ -141,7 +141,7 @@ AlarmList 只负责显示项目级当前报警，不保存独立触发逻辑，
 }
 ```
 
-注释不保存寄存器当前值，也不自动把地址加入 Modbus 轮询。网络注释属于 `LadderRung`，与行 ID、名称、连续网格和输出并列保存。网络注释允许为空；非空时只能使用单行文本，不能包含回车或换行，且不能超过 128 个 UTF-8 字节：
+注释不保存寄存器当前值，也不自动把地址加入 Modbus 轮询。网络注释使用网络首行的 `LadderRung.comment` 保存，与行 ID、名称、连续网格和输出并列；通过任意竖线连接到上一行的支路行必须保存空字符串。同一网络只有首行注释可以非空，违反该规则的 `2.0` 工程直接拒绝加载，不迁移或回退。网络注释允许为空；非空时只能使用单行文本，不能包含回车或换行，且不能超过 128 个 UTF-8 字节：
 
 ```json
 {

docs/测试约定.md

@@ -20,9 +20,9 @@
 | `application_settings_tests` | 默认配置创建、严格 INI 校验、缺失与未知字段、版本和整份回退 |
 | `alarm_service_tests` | 报警定义和运行记录生命周期 |
 | `hmi_editor_service_tests` | HMI 编辑、原子删除、历史、导航和四种 D 数值控件读写 |
-| `logic_editor_service_tests` | 连续网格编辑、输出自动补尾线、网格与整行片段复制粘贴、冲突回滚和历史 |
+| `logic_editor_service_tests` | 连续网格编辑、网络注释首行归属与合并冲突、输出自动补尾线、网格与整行片段复制粘贴、冲突回滚和历史 |
 | `offline_simulation_service_tests` | 梯形图扫描语义、离线初始 M/D 快照、真机缓存副本推算、只读隔离、跨扫描状态和故障处理 |
-| `project_management_tests` | JSON 往返、非法文件和工程保存状态 |
+| `project_management_tests` | JSON 往返、支路隐藏注释等非法文件和工程保存状态 |
 | `register_monitor_service_tests` | 监视地址、四种 D 类型读写、离线初始值捕获、批量步长、重叠提示和活动仓库 |
 | `runtime_project_bundle_tests` | 用户运行程序封装的写入、读取、校验和损坏拒绝 |
 | `runtime_mode_service_tests` | 编辑、离线、真机只读轨迹、仓库切换和断路工程启动拦截 |

docs/用户使用/数量边界确认方案.md

@@ -53,7 +53,7 @@ HMI 页面宽度 `320~1600`、高度 `200~800` 仍是结构安全硬范围；`De
 | 字符串 | ID、格式版本、页面跳转目标 ID | 0 字节 | 128 个 UTF-8 字节 | 拒绝保存或加载；业务要求非空的 ID 仍必须非空 | ID 只用于稳定识别，不需要长文本 |
 | 字符串 | 工程名、页面名、控件文本、报警文本、网络名称 | 0 字节 | 256 个 UTF-8 字节 | 拒绝保存或加载；业务要求非空的字段仍必须非空 | 防止名称和显示文本异常增长；HMI 控件文本、报警标题和报警文本编辑界面分别使用上方的 12/12/20 字符输入限制 |
 | 注释 | 软元件注释 | 1 字节 | 64 个 UTF-8 字节 | 拒绝编辑、保存或加载；禁止回车和换行 | 注释绘制在梯形图节点下方，必须保持紧凑单行 |
-| 注释 | 梯形图网络注释 | 0 字节 | 128 个 UTF-8 字节 | 拒绝编辑、保存或加载；禁止回车和换行 | 注释绘制在网络标题下方，换行会挤占梯形图区域 |
+| 注释 | 梯形图网络注释 | 0 字节 | 128 个 UTF-8 字节 | 拒绝编辑、保存或加载；禁止回车和换行；支路行非空时拒绝加载 | 每个网络只由首行保存和绘制一条注释 |
 | 字符串 | HMI 属性名称 | 1 字节 | 128 个 UTF-8 字节 | 拒绝保存或加载 | 属性名是短标识 |
 | 字符串 | HMI 属性值 | 0 字节 | 1024 个 UTF-8 字节 | 拒绝保存或加载 | 属性值可能保存显示配置，但不能无限增长 |
 | 自由监控 | 去重后的监控地址 | 0 | 64 | 第 65 个监控地址不能加入 | 这是用户临时监控区，不应拖慢 PLC 轮询 |

docs/用户使用/连续梯形图网格说明.md

@@ -33,7 +33,9 @@
 
 行是视觉顺序，不再是禁止跨越的网络边界。用户通过竖线把上下行连接成一个电气网络，删除竖线后立即拆分。
 
-画布左侧只显示从 `000` 开始的视觉行号，不显示行名称。每个网络首行上方都有独立注释带，网络注释使用绿色文字；通过竖线连接的后续支路行不重复显示注释。绘制、点击命中、框选和滚动共同使用同一份行布局坐标。
+画布左侧只显示从 `000` 开始的视觉行号，不显示行名称。每个网络首行上方都有独立注释带，网络注释使用绿色文字；通过竖线连接的后续支路行不重复显示注释。选中网络内任意网格、输出或支路行编辑“网络注释”时，输入框读取并修改该网络首行的注释。绘制、点击命中、框选和滚动共同使用同一份行布局坐标。
+
+同一网络只允许保存一条注释。用竖线或粘贴合并两个网络时，只有一侧有注释就把它归到合并后的网络首行，两侧注释相同就只保留一条；两侧注释不同则拒绝整次操作并保留原网络。删除竖线拆分网络时，原注释仍留在原网络首行，不自动复制到新产生的下方网络。
 
 选择模式下，普通单击选择一个网格或对象；按住左键拖动可框选多个触点、横线、输出块和竖线。`Ctrl+拖动`追加对象，`Ctrl+单击`追加或取消单个对象。“并联支路”只使用当前选中的连续条件作为范围，不会默认把整行全部并联。