suyu_two/docs/ai/handoff.md

当前开发交接

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

当前状态

• HMI 编辑态支持基础控件布局对齐：左、水平居中、右、顶部、垂直居中、底部；至少选中两个控件后从 HMI 工具栏“布局”菜单执行，对齐只修改控件位置并支持单步撤销/重做
• 当前窗口需求.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 地址 + 四种数据类型 + 六种比较方式 + 比较值
• 编辑态数据监控与运行态自由监控使用同一套读写行为：未连接 PLC 时读写虚拟 M/D，连接并完成首读后自动读写 PLC 缓存；PLC 首读期间禁止写入，编辑态 PLC 写入不更新离线初始值
• 普通编程器的运行监控窗口也提供离线/真机模式下拉切换；跨运行模式时自动经过编辑态，真机首读和工程校验失败会保持原运行态

领域与运行链路

• 新增 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/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

验证结果

• 13 个 Release Functional 测试目标全部通过：领域、设置、报警、HMI 编辑、逻辑编辑、离线仿真、工程管理、监控、运行包、运行模式、运行面板、PLC 对话框、PLC 运行时；监控专项新增编辑态 PLC 缓存读写、首读门槛和断开回退测试
• HMI 编辑专项覆盖六种对齐方向、批量对齐单步撤销/重做、非法选择原子性和无变化不产生历史记录
• 状态文本专项覆盖 M OFF/ON 映射、D 四类型区间边界、区间间隙/重叠、整数边界、NaN/Inf、只读约束、16 区间上限、JSON 往返和旧 2.0 拒绝
• 按钮专项覆盖 M/D 条件满足与不满足、服务层二次拒绝、点动条件变化后的释放复位、条件 JSON 往返和条件引用地址轮询
• 属性面板专项覆盖按钮/数值控件自动分配连续默认地址，以及手动修改地址编号后保持固定区域
• 运行模式专项覆盖 Double 状态文本的 D70~D73 轮询地址及四字 RegisterWordRange
• git diff --check 已通过；当前尚未连接真实 PLC，本轮新增编辑态 PLC 监控读写使用 Fake/缓存仓库验证，真实设备读写仍需按 STOP 安全流程现场确认
• Release 主程序已在本轮最终代码上重新构建；设置 Qt offscreen 环境后启动 3 秒仍保持事件循环，验证结束已关闭进程

工作区说明

• 保留用户已有的 AGENTS.md 修改和未跟踪 Word 临时文件，不覆盖、不回退
• 本轮不提交 Git，等待用户确认后再决定提交边界

后续人工检查

• 编辑态连接 PLC 并完成首读，打开“数据监控”，确认数据源切换为 PLC 缓存、M/D 值持续刷新且写入后等待轮询确认
• 编辑态 PLC 正在首读或断开时，确认监控显示对应等待/虚拟状态，写入权限符合提示
• 打开 HMI 页面添加“状态文本”，确认属性面板的专用配置按钮、M/D 切换和区间表布局在常用缩放下无重叠
• 打开 HMI 页面添加按钮，分别配置 M 位和 D 数值启用条件，确认条件不满足时按钮置灰且无法点击，满足后恢复可操作
• 离线运行写入虚拟 M/D，确认 M OFF/ON 和 D 在 30、80 边界的显示结果；停止运行后恢复编辑占位词
• 设备可用时在 STOP 状态读取原值，确认状态文本使用的 M/D 被轮询读回；测试只读，不向设备写入状态文本数据