suyu_two/docs/ai/handoff.md

当前开发交接

更新日期：2026-08-25。本文件只保留当前工作区状态、最近验证和下一步，不记录历史开发流水账；稳定架构和业务细节分别以 docs/architecture.md 及对应专题文档为准。

当前状态

• 分支：main
• 核心闭环可用：HMI 编辑、结构化梯形图、离线仿真、工程 JSON、运行监控、自由监控和 Modbus RTU 真机读写均已实现
• D 区 Float32/REAL 读写已接入：HMI 和自由监控可选 Int16/Float32，底层仍保存原始 16 位字，Float32 使用低字/高字连续双 D 编解码
• 真机本地梯形图只读推算已实现：HMI/自由监控继续读写 PLC，本地梯形图只读 PLC 缓存并在临时仓库推算轨迹
• 应用外部配置业务已经完成，固定读取可执行文件目录下的 config/application.ini
• 配置支持 6 个体验型数量上限、2 个新建 HMI 页面默认尺寸和 6 个 PLC 串口默认参数
• 配置启动时只读取一次，不热更新，不覆盖已有文件，不回写 PLC 配置窗口中的临时修改
• 当前没有代码阻塞，12 个 Release 功能测试、性能测试和 Release 主程序构建均已通过

工作区状态

• 当前未提交修改同时包含应用外部配置功能和真机本地只读推算功能，涉及启动加载、领域与服务动态上限、运行模式、PLC 轮询回调、UI 轨迹投影、测试和文档
• 工程树的新建页面、新建控制逻辑及重命名入口已统一禁止提交空名称或纯空白名称，确认按钮会随输入有效性即时启停
• 新增 ApplicationSettings、严格 UTF-8 INI 加载器及独立 application_settings_tests
• 新增用户文档 docs/用户使用/应用配置说明.md，并同步架构、数量边界、测试约定和 AGENTS.md 索引
• build/ 只保存本地构建和测试输出，不纳入 Git
• 未创建或修改发布包内的默认 INI；正式程序首次运行时由加载器按实际可执行文件目录创建

本轮变更结论

• 默认配置文件包含 [Config]、[ProjectLimits]、[HmiDefaults] 和 [PlcDefaults] 四个分区，当前版本固定为 1
• 文件不存在时自动创建目录和默认文件，本次使用代码默认值；创建或读取失败时默认值启动，底部输出详细原因并弹一次警告
• 缺失普通字段使用默认值，未知字段忽略；重复字段、版本错误、非法 UTF-8、非整数、越界或不支持的串口枚举值会使整份配置回退
• 领域聚合校验、编辑服务、JSON 保存加载、运行前校验和 UI 使用同一份启动期 ProjectLimitSettings
• 用户调低上限后，超限工程在局部对象中解析失败，不替换当前工程、不加载部分内容，也不修改原 JSON
• 全工程 HMI 控件 2048、全工程网络 2048、M/D 地址、16 位数值、梯形图结构、表达式、Modbus 和文件容量继续使用代码硬限制
• DefaultPageWidth/DefaultPageHeight 只影响新建页面；已有页面继续使用工程 JSON 中的尺寸
• PLC 默认值初始化主窗口连接配置；不存在的默认 COM 端口仍按现有规则过滤，不会制造无效端口项
• 页面和控制逻辑名称在界面提交前统一去除首尾空白；服务层继续负责空名称、长度和唯一性校验
• 真机每次完整 PLC 轮询成功后，复制梯形图引用的 M/D 到独立临时虚拟仓库，再复用离线扫描规则计算轨迹
• 本地线圈、MOVE、ADD、SUB 只修改本轮临时仓库；前面网络的临时结果可供本轮后续网络使用，下一轮重新从 PLC 最新缓存开始
• 真机轨迹明确标记为“PLC 缓存 · 本地推算轨迹”，不读取、生成、下载或修改 PLC 内部程序和内部轨迹
• 真机梯形图区显示只读边界提示：本地输出不写入 PLC 程序或 M/D，同时说明 HMI 和自由监控仍可写 PLC
• 本地推算失败或 PLC 断线/通信故障时停止推算并退出真机运行；推算故障详情在退出后保留，下一次启动重新清理
• Float32 工程 JSON 固定保存 dataType: "int16" 或 "float32"；缺少字段直接拒绝加载，不增加旧结构兼容分支
• 普通梯形图比较、MOVE、ADD、SUB 继续按 Int16；普通整数指令可以读取 Float32 占用字，但不能写入其任一 D
• 自由监控完全重复点拒绝，部分重叠允许但提示；Float32 批量地址步长为 2，并显示 D 起始~结束范围
• Float32 写入使用一次写两个连续保持寄存器，真机缓存等待轮询读回；Float32 轮询分块不会拆开两个连续字

最近验证

• 2026-08-25 执行 run_qt_tests.ps1 -Configuration Release -Suite All，12 个 Release 功能测试目标和性能测试全部通过
• 2026-08-25 新增 Float32 编解码、HMI 双字读写、D3999/D4000 边界、HMI 重叠、自由监控步长/重叠/读写和 Float32 轮询元数据测试；All 套件全部通过
• application_settings_tests 覆盖首次创建与默认内容、完整加载、缺失和未知字段、重复字段、越界、非整数、版本不兼容、非法 UTF-8 及创建失败回退
• 领域和服务测试覆盖 HMI 页面/控件、报警、控制逻辑/网络动态上限与新建页面默认尺寸
• 工程管理测试覆盖调低页面上限后拒绝两页面工程，并确认当前工程状态保持不变
• 性能基准通过：代表性软件扫描约 0.203 ms，4001 个虚拟寄存器边界工作量约 0.0454 ms
• 重新执行 qmake 并完成 Release 主程序链接：build/float32/release/integrated_platform.exe
• 新增真机测试覆盖：本地临时输出不改变 PLC 源仓库、同一轮后续网络可见、完整轮询只触发一次推算、断线/通信故障停止推算并返回编辑态、推算故障详情保留
• 使用已有 build/manual_plc_discovery_probe/release/manual_plc_discovery_probe.exe 在 COM3 / 9600 / 8E1 / 站号 1 完成一次真实 D0 探测，结果找到 PLC；本轮未重复执行真实 M/D 写入恢复流程
• 本轮未做完整真机运行轨迹人工验收：改动的本地推算路径只读取 PLC 缓存、输出只写临时仓库，不改变 PLC 通信写入；交付前仍建议现场连接真实 PLC 确认轨迹随完整轮询刷新

待完成

1. 代码功能无待完成项；提交前按逻辑完整改动提交当前配置、真机本地推算和 Float32 功能、测试及文档
2. 现场使用真实 PLC 做一次 Float32 真机验收：读取 D10/D11 原值，写入一个有限 Float32，确认一次双寄存器请求，轮询读回显示正确，恢复原值并再次读回确认
3. 现场同时确认 HMI 写入仍正常、本地轨迹随每轮 PLC 缓存刷新、PLC 源 M/D 不被本地梯形图输出改变

下一会话起点

1. 先运行 git status --short，保留当前应用配置和真机本地推算的全部未提交修改
2. 若继续改配置字段，同步更新默认文件内容、严格加载器、配置测试和 docs/用户使用/应用配置说明.md
3. 提交前重新运行 Release 测试、主程序构建和 git diff --check