suyu_two/docs/ai/handoff.md

当前开发交接

更新日期：2026-08-31。本文件只保留当前工作区、本轮改动、验证结果和后续人工检查项。

当前状态

• hmi_editor_widget.cpp 和 logic_editor_widget.cpp 已面向初学者补充大量单行注释，重点说明 Qt 图形视图三套坐标、图元生命周期、绘制、命中测试、选择、鼠标手势、内嵌指令输入和服务层提交；logic_editor_service.h/.cpp 进一步补充鼠标横竖线范围 API、原子提交、回滚和单步撤销说明；未修改业务逻辑
• main_window.cpp 已补充大量关键单行注释，说明 Qt 对象所有权、事件过滤、信号槽、定时器、排队调用、对话框、Model/View 自定义角色、工程文件和运行版导出 API；未修改业务逻辑
• 真机本地梯形图推算链路已补充关键代码注释，明确完整 PLC 轮询边界、缓存到临时仓库的隔离、执行器输出落点、轨迹信号转交和画布投影，并强调该轨迹不是 PLC 内部真实程序轨迹
• 新增 docs/二次开发/工程新建保存加载与JSON说明.md，按“业务规则 -> 核心调用链”说明新建、保存、加载的状态保护与严格 JSON 4.0 读写；代码阅读清单已补充入口
• 测试程序已优化：功能测试入口按用例独立报告 [PASS]/[FAIL]，单个用例失败不会跳过同一目标的其他用例；HMI 数值运行测试拆出独立用例并去除重复原始字序断言；数量边界失败提示由统一上限常量生成，运行包夹具同步为工程格式 4.0
• 性能测试已调整为合法上限扫描、超限压力扫描、4001 个 M 位边界访问和 256 个 D 字连续块访问四项基准
• HMI 编辑态支持基础控件布局对齐：左、水平居中、右、顶部、垂直居中、底部；至少选中两个控件后从 HMI 工具栏“布局”菜单执行，对齐只修改控件位置并支持单步撤销/重做
• docs/用户使用/状态文本控件说明.md 的状态文本控件已完成，新增独立 HmiControlType::StatusText，普通 Label 保持固定文本职责
• M 状态支持一个 M 地址和 OFF/ON 两个显示文本，D 状态支持 Int16/Int32/Float32/Float64 以及最多 16 个连续区间
• D 区间统一为 [下限, 上限)，首个下限和末个上限必须为“不限”，相邻区间必须首尾相接，覆盖整个数值域
• 状态文本只读；离线从虚拟寄存器读取，真机从 PLC 轮询缓存读取；绑定缺失、仓库不可用、读取失败和 NaN/Inf 统一显示 --
• 编辑画布固定显示“状态文本”，运行画布显示映射结果；字号、颜色、粗体、斜体复用现有 HMI 外观属性
• 状态文本配置使用独立 Qt Designer 对话框；属性面板隐藏普通绑定和数值类型编辑入口，改用“状态映射”专用配置按钮
• HMI 控件按类型自动固定绑定区域：按钮/指示灯为 M，数值显示/输入为 D；新增控件自动分配当前区域的顺序地址，属性面板只修改地址编号，状态文本仍在专用对话框选择 M 或 D
• HMI 按钮保留置 ON、置 OFF、翻转和点动四种操作，并可附加一个 M 位或 D 数值启用条件；条件不满足或读取失败时按钮置灰且禁止操作
• 按钮启用条件配置使用独立 Qt Designer 对话框；支持 M 地址 + OFF/ON、D 地址 + 四种数据类型 + 六种比较方式 + 比较值
• 编辑态数据监控新增“离线 M/D/真机 PLC M/D”显式选择，默认离线且连接 PLC 不自动切换；真机必须连接并完成首读，断线后保留真机选择、显示不可用并禁写，重连首读后恢复；两套数据互不复制
• 数据监控和自由监控输入 M 地址时，类型框固定显示 Bit（位） 并禁止选择数值类型；输入 D 地址时恢复四种数值类型
• 普通编程器的运行监控窗口也提供离线/真机模式下拉切换；跨运行模式时自动经过编辑态，真机首读和工程校验失败会保持原运行态
• 用户运行程序已经收敛为 HMI 专用运行版：导出时只保留 HMI 页面、报警和导航数据，移除控制逻辑与地址备注；运行版隐藏编辑器、梯形图、自由监控、离线模式和串口配置控件
• 用户运行版启动后自动读取同目录 config/runtime.ini 的六个串口字段并连接真实 PLC；运行版不启动本地梯形图扫描，HMI 读写只在 PLC 首读完成后放行
• 用户运行版串口被拔出或 PLC 端口超时后自动按配置重连，重连和重新首读期间保持 HMI 页面、禁止写入且绝不切换到虚拟数据；普通编程器仍使用原来的手动连接和故障回编辑态流程
• 用户运行版恢复路径已收敛：USB 串口消失时每 3 秒完整重连，PLC 无响应或超时时保留串口并由通信层每 2 秒轻量探测；同一次故障只提示一次，串口打开但首读未完成不会清除提示周期
• json/ 下的两个本地示例工程已同步到严格 formatVersion: "4.0"，按钮补齐 buttonEnableCondition: null 字段，页面、报警、导航和梯形图数据保持原样
• 关键 Markdown 文档已按当前代码和文档职责复核，修正 JSON 4.0 版本约定、状态文本文档引用和验收测试目标数量

领域与运行链路

• 新增 HmiStatusBitTextConfig、HmiStatusWordTextConfig、HmiStatusValueRange 及状态文本领域校验
• D 状态文本参与完整连续 D 字范围的冲突检查，也参与 16 位 MOVE/ADD/SUB 写入保护
• HmiRuntimeService::readStatusText() 统一执行 M 位文本映射和 D 半开区间映射，不提供写入接口
• RuntimeModeService 将 D 状态文本占用的全部连续字加入 PLC 轮询地址和 RegisterWordRange
• JSON 已升级为唯一 formatVersion: "4.0"；按钮保存为 buttonEnableCondition，状态文本保存为 statusText.source、M 的 offText/onText 或 D 的 ranges
• 旧 1.0、2.0、3.0 和其他版本工程直接拒绝，不提供迁移、双写、回退或兼容适配

关键文件

• 领域模型和规则：app/src/domain/hmi_model.h/.cpp、hmi_control_registry.*、project_model.cpp、project_limits.h
• 运行读取：app/src/services/hmi_runtime_service.*、runtime_mode_service.cpp
• 工程持久化：app/src/infrastructure/json_project_storage.*
• 运行版配置：app/src/infrastructure/runtime_settings_loader.*
• 运行版导出：app/src/services/project_service.*、app/src/ui/main_window.cpp
• 编辑服务和属性面板：app/src/services/hmi_editor_service.cpp、app/src/ui/property_panel_controller.*
• 状态文本对话框：app/src/ui/status_text_dialog.*
• 按钮启用条件对话框：app/src/ui/button_extension_dialog.*
• HMI 画布和工具栏：app/src/ui/hmi_editor_widget.cpp、main_window.cpp/.ui、toolbar_icon_factory.*
• 用户说明：docs/用户使用/状态文本控件说明.md
• 用户说明：docs/用户使用/HMI控件绑定说明.md
• 用户说明：docs/用户使用/按钮启用条件说明.md
• 格式契约：docs/工程格式说明.md

验证结果

• HMI 和梯形图画布注释补充后，Release All 全量测试通过，14 个功能测试目标共 135 个用例全部通过，4 项性能测试通过；本轮继续补充鼠标画线服务 API 注释，Release Functional 的 14 个目标、135 个用例再次全部通过，画布与服务文件重新参与编译，Release 主程序构建成功，git diff --check 通过，未连接真实 PLC
• main_window.cpp 注释补充后，Release All 全量测试通过，14 个功能测试目标共 135 个用例全部通过，4 项性能测试通过；Release 主程序重新编译成功，git diff --check 通过，未连接真实 PLC
• 本轮新增和索引业务文档，并为真机本地梯形图推算链路补充代码注释；未修改业务行为，已执行 Markdown UTF-8 读取检查、Release Functional 全量测试和 git diff --check，未连接真实 PLC
• 14 个 Release Functional 测试目标全部通过，功能用例逐项输出结果：领域 18、设置 6、运行版设置 4、报警 2、HMI 编辑 12、逻辑编辑 27、离线仿真 19、工程管理 11、监控 7、运行包 1、运行模式 5、运行面板 13、PLC 对话框 3、PLC 运行时 7，共 135 个用例
• M 地址类型框联动修改后，14 个 Release Functional 测试目标重新运行并全部通过，Release 主程序构建成功
• Release Performance 四项基准全部通过：合法上限规模扫描约 21.75 ms/次，超限压力扫描约 1.09 ms/次，4001 个 M 位逐地址读写约 0.0479 ms/次，256 个 D 字连续块读写约 0.000062 ms/次；结果仅作为本机执行器和虚拟仓库基线
• HMI 编辑专项覆盖六种对齐方向、批量对齐单步撤销/重做、非法选择原子性和无变化不产生历史记录
• 状态文本专项覆盖 M OFF/ON 映射、D 四类型区间边界、区间间隙/重叠、整数边界、NaN/Inf、只读约束、16 区间上限、JSON 往返和旧 2.0 拒绝
• 按钮专项覆盖 M/D 条件满足与不满足、服务层二次拒绝、点动条件变化后的释放复位、条件 JSON 往返和条件引用地址轮询
• 属性面板专项覆盖按钮/数值控件自动分配连续默认地址，以及手动修改地址编号后保持固定区域
• 运行模式专项覆盖 Double 状态文本的 D70~D73 轮询地址及四字 RegisterWordRange
• 数据监控专项覆盖连接 PLC 不自动切换、首读前拒绝真机选择、离线/真机读写隔离、断线保持真机选择并禁写、重连首读后恢复，以及运行态继续跟随活动仓库
• 运行版恢复策略专项覆盖仅 Disconnected 完整重连、Faulted 保留串口探测、一次故障只提示一次，以及必须 Connected + 首读完成 才结束故障周期
• git diff --check 已通过；当前尚未连接真实 PLC，本轮新增编辑态 PLC 监控读写使用 Fake/缓存仓库验证，真实设备读写仍需按 STOP 安全流程现场确认
• Release 主程序已在本轮最终代码上重新构建；新增运行版启动链路、最小配置加载和收敛后的自动恢复逻辑通过编译，设置 Qt offscreen 环境后启动验证仍保持事件循环；导出运行版的真实串口连接、拔线和恢复尚未接入设备验证

工作区说明

• 保留用户已有的 AGENTS.md 修改和未跟踪 Word 临时文件，不覆盖、不回退
• 当前有三份此前未提交的测试修正：数量边界提示和测试夹具初始化、工程总行数分支测试名称、运行包工程格式夹具；本轮新增数据监控、用户运行版 PLC 恢复策略、界面调用、专项测试和对应文档改动，来源不明的非代码文件继续保留且未修改

后续人工检查

• 编辑态保持“离线 M/D”后连接 PLC，确认监控不会自动切换；完成首读后手动切到“真机 PLC M/D”，确认 M/D 持续刷新且写入后等待轮询确认
• 分别在 PLC 未连接、正在连接和正在首读时尝试选择真机，确认切换被拒绝并说明原因；真机选择期间断线时确认仍显示真机、值不可用且禁写，手动切回离线后恢复离线值
• 打开 HMI 页面添加“状态文本”，确认属性面板的专用配置按钮、M/D 切换和区间表布局在常用缩放下无重叠
• 打开 HMI 页面添加按钮，分别配置 M 位和 D 数值启用条件，确认条件不满足时按钮置灰且无法点击，满足后恢复可操作
• 离线运行写入虚拟 M/D，确认 M OFF/ON 和 D 在 30、80 边界的显示结果；停止运行后恢复编辑占位词
• 设备可用时在 STOP 状态读取原值，确认状态文本使用的 M/D 被轮询读回；测试只读，不向设备写入状态文本数据
• 用真实工程执行一次“导出用户运行程序”，确认导出目录只出现 HMI 运行 exe、Qt 依赖、平台插件、样式目录和 config/runtime.ini，并确认 exe 启动后不出现编辑器或串口配置界面
• 设备可用时使用导出运行版按 runtime.ini 自动连接，在 STOP 状态确认首读和 HMI 读回；测试结束恢复全部临时写入值并再次读回
• 真机运行中分别拔出 USB 串口适配器、断开 PLC 侧 RS-485 端口并重新接回；确认 USB 断线走完整串口重连、PLC 侧断线走轻量探测，同一次故障只提示一次，恢复后重新首读并恢复 HMI 写入，且恢复期间不显示虚拟数据