# Current Handoff

- Goal: 完成综合平台编程器的结构化梯形图、HMI、离线仿真和 Modbus RTU 真机链路
- Branch: `main`
- Current status: 第 1~10 步的软件实现与自动化测试已完成，待连接 XDH-60T4-E 进行真机安全验证和整理最终交付资料

## 当前能力

- 梯形图条件使用递归 `Node / Series / Parallel` 表达式树，可表示 `A OR (B AND C)` 和嵌套串并联
- 编辑器使用固定行列网格和正交连线，支持当前节点后串联、单节点并联、连续节点范围并联、删除节点或网络以及设置输出线圈
- 画布只选择可见节点，不暴露内部表达式容器；橡皮框或多选连续节点后可直接建立并联支路
- 执行器递归求值并生成节点、表达式、网络轨迹，离线运行时画布显示导通路径和故障位置
- HMI 和梯形图直接配置 M/D 地址，不依赖预先创建的数据点
- `ActiveRegisterRepository` 在离线虚拟仓库与 PLC 缓存仓库之间切换
- `PlcCommunicationService` 使用 Qt SerialBus 异步连接、轮询和单点写入，UI 不阻塞
- 真机连接收集 HMI、报警定义和梯形图实际引用地址，按 M/D 分区并合并相邻地址读取
- 真机模式要求首次读取完成，不复制离线值，不运行 PC 软件逻辑执行器
- 通信错误停止轮询并保留最后一次有效缓存，状态栏和日志显示错误
- 通信故障立即撤销当前连接的首读资格；真机运行中发生故障会自动返回编辑态，重新进入真机前必须重新连接并完成新一轮首读
- PLC 故障态可直接“重新配置”，连接前自动清理旧串口会话，不再要求用户先手动点击断开
- PLC 日志区分连接阶段串口无法打开与已连接后的本地串口意外中断；后者自动转为已断开并禁用重复断开操作
- 主窗口静态控件已迁入 `main_window.ui`，PLC 参数由独立配置对话框收集后再发起连接
- 已增加运行监控工作台：离线仿真同时显示 HMI、梯形图轨迹和自由监控，真机运行只显示 HMI 和自由监控
- 自由监控支持 `M0~M4000`、`D0~D4000` 地址输入、连续批量添加、去重、删除、清空和最多 64 项限制
- 自由监控读取活动寄存器仓库，离线使用虚拟 M/D，真机使用 PLC 缓存，通信故障保留并标记最后有效值
- HMI 按钮支持 TouchWin 同类的置 ON、置 OFF、取反和瞬时 ON，默认瞬时 ON
- 工程支持多个有序 HMI 页面和多个有序控制逻辑，工程树可选择切换、新增、重命名、删除、启停和上下移动
- 主窗口使用会话态当前页面 ID、当前逻辑 ID，所有编辑入口不再固定操作第一项
- 工程持久化初始 HMI 页面；运行态由 `HmiNavigationService` 从初始页启动并处理本地 PageJump 导航
- HMI 已开放不绑定寄存器的 `Label` 和独立 `PageJump` 创建入口，属性区按控件类型显示绑定、按钮操作或目标页面
- HMI 已增加 AlarmList 和报警配置入口，支持 M ON、D 高限、D 低限，统一显示当前报警和确认状态；运行态无报警时隐藏，报警恢复后立即移除
- 离线执行器按工程顺序扫描所有启用逻辑，禁用草稿不阻止运行；轨迹按逻辑 ID 隔离，运行工作台可切换当前投影
- 梯形图已支持上升沿、下降沿、T/C 常开/常闭触点、非保持 TON、CTU/CTD、MOVE 和 ADD/SUB；边沿与计数都按上升沿扫描语义执行，TON 按 `steady_clock` 计算实际 ET
- T/C 是 `T0~T4000`、`C0~C4000` 的离线仿真内部资源；C 计数器的 CV 保存到 D 地址，PV 支持常量或 D 地址，复位使用 M 地址；T/C 资源本身不读写 M/D，也不进入 Modbus 轮询，同一资源只允许一个已启用驱动
- ADD/SUB 使用 `int32_t` 中间值并将结果饱和到 `-32768~32767`；越界只在运行轨迹的 `WordTraceValue::overflow` 标记，不停止扫描
- 工程已支持 M/D 地址注释和 `LadderRung` 网络注释；地址注释只保存地址与文本，不混入当前值和引用状态
- HMI 运行按钮已区分悬停、按下、释放和禁止写入外观，运行态不再显示编辑选中框，可写按钮使用手型光标
- PLC 轮询集合已扩展为 HMI、报警定义、梯形图和自由监控地址的并集，连接后可动态增删监控地址
- 已在真实 `COM3 / 9600 / 8E1 / 站号 1` 上完成只读联机验证，项目通信服务可完成 M/D 首次读取并进入真机运行前置状态

## 关键决策

- 工程格式继续使用 `1.0`，当前文件保存 HMI、报警定义和梯形图表达式树，不保留 `dataPoints` 结构及兼容代码
- 工程 `1.0` 直接要求 `alarmDefinitions`，不为缺少该字段的旧草稿增加迁移或默认值
- AlarmList 不直接保存报警逻辑，项目级 `AlarmService` 统一管理运行状态；当前不设置提示、警告、故障等级
- 当前 `1.0` 直接要求 `initialHmiPageId` 和 PageJump 的 `targetPageId`，开发阶段不为同版本旧草稿补默认值或迁移分支
- 页面跳转保存目标页面稳定 ID，不保存名称或数组索引；编辑器当前页面和当前逻辑属于会话状态，不写入工程
- 按钮操作是工程 `1.0` 的必填字段，不兼容或迁移缺少该字段的旧按钮数据
- 不读取旧的 `stages/branches` 结构，不添加旧格式迁移和兼容层
- 梯形图编辑结构而不是自由线段，避免悬空线、环路和多个输出路径
- 网格仅作为编辑投影，不进入工程格式；服务层把连续范围操作转换为规范化表达式树
- 条件节点继续使用 `std::variant` 的独立配置类型，不向通用节点添加无关字段
- HMI、梯形图和通信共享 `M0~M4000`、`D0~D4000` 地址范围
- 已删除统一数据点表、主窗口数据点 Dock 和属性区数据点下拉框；M/D 注释作为独立的工程级地址元数据实现
- PLC 读写使用从 `0` 开始的原始 Modbus 地址
- HMI 写请求不乐观修改 PLC 缓存，由下一次轮询确认真实值
- 真机运行时 PLC 内部程序是控制源，软件逻辑执行器保持停止
- 真机运行不显示本地梯形图导通轨迹，避免把本地工程误表示为 PLC 内部程序的真实执行状态
- 自由监控表属于当前调试会话，不进入工程 `1.0` JSON，不重新引入数据点表
- 工程 `1.0` 直接要求顶层 `registerComments` 和每个网络的 `comment` 字段，不增加旧工程迁移或缺省兼容
- 50 ms Qt 定时器只调度离线扫描；每个 TON 不创建独立 Qt 定时器，真机模式继续停止整个软件逻辑执行器
- 项目梯形图不下载到 PLC；真机模式停止本地软件逻辑执行器，只轮询新指令实际引用的 M/D 地址

## 自动化验证

以下测试均已完成干净构建并通过：

- `domain_tests`
- `logic_editor_service_tests`
- `offline_simulation_service_tests`
- `project_management_tests`
- `hmi_editor_service_tests`
- `runtime_mode_service_tests`
- `plc_runtime_tests`
- `main_window_tests`
- `register_monitor_service_tests`
- `alarm_service_tests`

`main_window_tests` 还覆盖 PLC 配置参数往返、独立配置弹窗入口，以及主窗口不再内嵌串口参数控件。

本轮边沿、TON 和注释实现增加了：上下沿一次扫描脉冲、不同逻辑同名边沿状态隔离、TON 到时与断开复位、多个 T 独立计时、网络顺序可见性、运行重启状态清理、T 引用完整性、M/D 与网络注释 JSON 往返、严格新字段缺失失败，以及 T 和纯注释地址不进入 PLC 轮询集合的覆盖。

本轮多页面和多逻辑实现增加了领域、服务、存储和主窗口集成覆盖：初始页约束、页面引用删除保护、页面/逻辑名称唯一性和顺序、禁用草稿逻辑、多逻辑扫描与轨迹隔离、严格 JSON `1.0` 必填字段、工程树选择切换、Label/PageJump 属性可见性、运行态页面跳转和逻辑轨迹选择。

2026-08-13 真机排查发现 `QModbusRtuSerialMaster::connectDevice()` 在当前 Windows
串口驱动上会同步触发 `ConnectedState`。旧实现随后再次写入 `Connecting`，导致已经发出的
读取响应因服务状态不是 `Connected` 而被丢弃，首次读取标志永远不能完成。现已把
`Connecting` 状态设置移动到 Qt 连接调用之前，并在真实 PLC 上验证首轮 `M0~M2`、`D0`
读取约 288 ms 完成，缓存值为 `M0=1`、`M1=1`、`M2=0`、`D0=0`。主窗口现在会显示
连接、首读完成和具体中文通信故障，生产代码中的业务错误提示已统一为中文，JSON 字段和协议标记保持不变。

PLC 连接初始化会连续通知首读重置、正在连接和已连接。旧主窗口把每次通知都排队处理，
队列执行时读取到的已经是同一个最终状态，因此输出区会连续追加三条相同的“正在首读”。
现已在主窗口合并同一事件循环内的 PLC 状态刷新，并拒绝连续追加完全相同的输出消息。
真实 `COM3` 主窗口联调确认“正在首读”和“首次读取完成”各输出一次。

本轮已完整删除统一数据点业务，包括领域模型、服务、主窗口 Dock、属性区下拉框、JSON 字段和独立测试工程。当前开发阶段不保留 `dataPoints` 旧结构的迁移或兼容逻辑。主窗口测试明确验证已删除控件不存在，PLC 轮询测试改为验证从 HMI 实际绑定收集地址。

本轮梯形图编辑重构还验证了：固定网格渲染、水平/垂直正交布线、工具栏直接建立并联支路，以及连续范围 `A AND ((B AND C) OR D)` 的结构变换和非连续范围拒绝。

本轮自由监控与运行工作台实现还验证了：地址字符串解析和边界、连续范围展开、去重和数量
上限、活动仓库切换、离线工作台三区域同时可见、真机工作台只显示 HMI 与自由监控、离线
监控读取虚拟 M/D，以及真机运行期间新增地址立即进入 PLC 聚合轮询集合。PLC 动态轮询在
读取请求空闲后应用新集合，连接首读完成后不会因新增监控地址而回退。

运行工作台的 HMI 和梯形图是独立于编辑画布的模型投影。此前同一页面或逻辑 ID 在编辑态
发生变化后，运行投影的 `setPageId()` / `setLogicId()` 会因 ID 未变化而跳过重建，导致新建
HMI 控件在离线运行工作台中显示为空白。现在每次同步运行对象都会显式重建两个投影，主窗口
测试会保留一个已配置 HMI 控件，并断言离线运行视图实际包含该控件，而不再只检查区域可见。

Qt Release 应用已完成干净构建，并执行了启动与正常退出冒烟验证。`git diff --check` 无空白错误。

本轮修正 PLC 故障恢复状态链。通信服务发生错误时会清除当前连接的首次读取资格，运行模式
服务同时校验 PLC 必须处于 `Connected` 且当前连接已完成首读；真机运行期间发生故障会自动
返回编辑态，避免使用旧连接的首读结果重新进入真机运行。故障状态下主窗口开放“PLC 重新
配置”，用户确认后自动断开并清理旧会话，再发起新连接。旧连接未完成的异步回复使用连接代次
隔离，不能污染重连后的新会话。

PLC 错误分类已拆到独立基础设施模块。连接阶段无法打开串口时直接报告端口不存在或被占用，
保持未连接状态；已连接后收到 `ConnectionError` 或意外进入 `UnconnectedState` 时统一报告本地
串口连接已中断，自动清理并转为未连接状态，不再依赖错误瞬间的 Windows COM 口枚举结果。

PLC 断开状态现已与底层 Qt Modbus 会话保持一致。连接中断类错误会停止轮询、隔离旧回复并
主动关闭 `QModbusRtuSerialMaster`；再次连接前还会防御性清理残留的底层连接状态，避免界面已
禁用“断开 PLC”但重连仍提示连接已经启动。串口无法打开时，输出区只通过 PLC 状态刷新记录
一次故障，连接操作不再重复追加同一错误，但仍保留警告对话框。

PLC 未响应或通信超时且本地串口仍打开时，服务停止正常轮询，每次探测失败后等待 2 秒再发送
一次单地址只读探测，不重复输出相同的超时日志。探测成功后进入 `Recovering` 状态，重新读取全部轮询地址；
完整首读完成后才恢复 `Connected`。故障和恢复过程始终停留在编辑态，不自动回到真机运行，
“断开 PLC”继续用于释放本地串口会话。

2026-08-14 使用真实 `COM3 / 9600 / 8E1 / 站号 1` 完成只读恢复测试。连续 5 次读取
`M0~M2、D0` 的完整首读耗时为 `304 / 304 / 288 / 271 / 287 ms`，平均约 `291 ms`；串口
进入已连接状态平均约 `51 ms`。真机运行时拔掉 PLC 侧 RS-485 A/B 后，服务进入 `Faulted`，
运行模式同步退回 `Editing`；接回线后约 `7.05 s` 进入 `Recovering`，再用约 `224 ms` 完成
完整首读并恢复 `Connected`，最终仍保持 `Editing`。测试结束后再次首读耗时 `288 ms`，确认
恢复探针已释放 COM3。底层 Qt SerialBus 单次复测中，连接状态约 `58 ms`，读取 `M0~M2`
到 `96 ms`，继续读取 `D0` 到 `128 ms`，单次读响应约 `32~38 ms`；生产服务完整首读的主要
额外耗时来自 `200 ms` 正常轮询节拍。本次测试全程没有写入 PLC，读回值为
`M0=0、M1=0、M2=0、D0=0`。

本轮新增自动化测试覆盖故障自动退回编辑态、首读资格撤销、故障后禁止重新进入真机、故障态
直接重连清理旧会话、主窗口重新配置入口和五类核心通信错误。`plc_runtime_tests`、
`runtime_mode_service_tests`、`main_window_tests` 均通过，Qt Release 工程完成干净构建。

本轮参照 TouchWin 按钮业务新增四种位操作：置 ON、置 OFF、取反、瞬时 ON。按钮操作
使用领域枚举并写入工程 `1.0` JSON；运行服务按 Pressed/Released 事件生成写值，瞬时 ON
按下写 1、释放写 0，其他模式释放不重复写入。属性面板只在选中按钮时显示操作模式，新建
按钮默认瞬时 ON。相关服务、离线闭环、JSON 往返与主窗口测试已覆盖。

HMI 图元现已分离编辑选择与运行输入状态。运行按钮悬停时改变底色，按下时按钮面下移并
加深，释放后回弹；禁止写入时显示灰色且不接收鼠标写操作。运行态关闭图元选择，避免点击
后出现编辑选中框。主窗口测试使用真实鼠标按下和释放事件验证瞬时按钮写入、视觉状态切换、
手型光标、禁止写入和无运行选中框。

本轮新增最小报警闭环。项目级报警定义支持 M 位为 ON、D 值大于等于阈值、D 值小于等于
阈值；AlarmService 只维护当前报警的发生时间和确认状态，报警恢复后立即移除，多个 AlarmList 共享状态。
报警配置和列表展示分别由独立 Qt Designer 对话框与 HMI 图元完成，主窗口只协调服务。报警
地址已进入 PLC 聚合轮询。工程版本保持 `1.0`，`alarmDefinitions` 为必填字段，不增加兼容分支。

2026-08-17 使用 `COM3 / 9600 / 8E1 / 站号 1` 完成报警功能后的真机只读冒烟，成功读取
`M0~M2 = OFF`、`D0 = 0`，测试结束后正常关闭串口。本次没有执行任何 PLC 写操作。

本轮新增 CTU/CTD、MOVE、ADD/SUB 离线逻辑和编辑配置。领域校验限制 C/T 资源及 M/D 地址
范围，C 计数器要求唯一驱动和已绑定 C 触点；计数按上升沿执行，CV 通过 D 地址读写，CTU
复位为 0、CTD 复位装载 PV，ADD/SUB 越界采用有符号 16 位饱和并记录溢出轨迹。JSON 保存
加载、离线执行、主窗口入口和真机轮询地址覆盖已通过，项目 Release 构建通过。真机仍只验证
M/D 通信，不执行或下载这些本地梯形图指令。

## 待完成事项

1. 在 PLC STOP 状态确认 COM2 参数和 RS-485 A/B 接线
2. 用安全测试地址读取 `M0`、`D0`
3. 写入 `M0`、`D0` 并由 PLC 监控和下一次轮询确认
4. 真机复核电脑侧 USB 转串口拔除、PLC 侧 A/B 断开、超时和重新连接日志及恢复流程
5. PLC 切换 RUN 后执行完整 HMI 与设备联动测试
6. 整理测试记录、构建说明和演示工程

## 建议下一步

运行 Release 应用，配置实际 COM 口、站号、波特率和校验方式，在 PLC STOP 状态完成 `M0`、`D0` 首次安全读写。未确认设备程序与负载安全前不要在 RUN 状态写控制地址。