suyu_two/docs/开发顺序.md

综合平台编程器开发顺序

本文规定项目的推荐开发顺序。原则是先建立稳定的数据模型和模块边界，再完成编辑功能，最后接入仿真与真实 PLC。每个阶段完成后都应保证项目可以构建、运行并提交一次 Git 记录。

当前进度

第 1~10 步的软件实现已完成，工程格式继续使用 1.0，不保留旧梯形图结构的兼容代码。当前重点是第 11 步中的真机安全验证和第 12 步交付资料。

1. 建立开发基线

• 初始化 Git 仓库，确认 .gitignore、编码规则和提交规范。
• 验证 Qt 5.15.2、qmake、MinGW、Qt SerialBus 的构建环境。
• 建立可启动的 Qt Widgets 空工程和独立构建目录。

完成标准：空程序可以通过 qmake 构建并正常启动。

2. 搭建项目分层骨架

• 建立 UI、领域、服务、基础设施和测试目录。
• 明确模块依赖方向，MainWindow 只负责界面组织，不承载业务逻辑。
• 在 docs/architecture.md 中记录目录职责和核心数据流。

完成标准：各层具有清晰入口，工程仍可独立构建。

3. 定义核心数据模型与接口

• 定义工程、HMI 页面、HMI 控件、结构化控制逻辑和 M/D 地址模型。
• 定义统一的寄存器仓库接口，隔离虚拟寄存器与真实 PLC 寄存器。
• 定义编辑态、离线运行态和真机运行态的状态边界。

完成标准：核心模型不依赖具体 UI、串口或 Modbus 实现。

4. 实现工程管理

• 实现新建、保存、另存为和加载工程。
• 保存 HMI 配置、控制逻辑、M/D 绑定和必要的工程版本信息。
• 使用服务层编排工程操作，基础设施层负责版本化 JSON 转换和原子文件写入。
• 对无效文件、缺失字段和不兼容版本给出明确错误。

完成标准：空工程和示例工程可以保存后重新加载，数据保持一致。

5. 完成主界面与状态管理

• 使用 Qt Designer 搭建工具栏、工程区域、HMI 编辑区、逻辑编辑区、属性区和状态反馈区。
• 实现编辑态与运行态的统一切换入口。
• 根据当前状态限制不可用操作，避免编辑与运行同时发生。

完成标准：主界面结构完整，状态切换行为明确且可见。

6. 实现 HMI 编辑器

• 支持基础控件的添加、选择、移动、删除和属性配置。
• 支持按钮、指示灯、数值显示和数值输入等基础控件。
• HMI 控件只绑定统一寄存器仓库，不直接访问仿真器或串口。

完成标准：能够管理多个有序 HMI 页面，配置初始页、固定文本和页面跳转，并随工程保存和加载。

7. 实现控制逻辑编辑器

• 使用 Node / Series / Parallel 表达式树建立梯形图逻辑模型，支持嵌套串并联关系。
• 支持节点前后串联插入、与节点并联、与整个支路并联、删除和输出线圈配置。
• 实现常开、常闭、上升沿、下降沿、T/C 触点、普通线圈、置位/复位、TON、CTU/CTD、MOVE、ADD/SUB 以及 D 值与常量比较。
• 上升沿和下降沿按一次扫描脉冲执行；TON 使用离线执行器的 steady_clock 和 T 资源表，不为每个 TON 创建独立 Qt 定时器；CTU/CTD 使用 C 资源和 D 区 CV，按上升沿计数。
• 明确 M/D 为外部地址、T/C 为离线资源；ADD/SUB 以有符号 16 位结果饱和处理溢出，不能让一次越界中止扫描。
• M/D 注释作为工程级地址元数据保存，网络注释作为 LadderRung 字段保存，两者都不改变寄存器轮询行为。
• 新增节点类型时使用独立配置类型，不向通用节点结构持续堆叠无关字段。
• 编辑器只生成逻辑模型，不直接修改 HMI 或 PLC。
• 工程可包含多个有序控制逻辑，离线执行器按顺序扫描全部启用项，运行工作台只切换当前轨迹投影。
• 画布按表达式结构自动布线，显示节点或支路选择范围，不允许节点自由拖动，也不保存自由线段。

完成标准：能够表达 A OR (B AND C) 等嵌套逻辑，并配置启动、停止和状态保持逻辑。

8. 实现离线仿真运行

• 实现虚拟 M/D 寄存器和固定周期的软件逻辑执行器，T/C 仅作为离线仿真内部资源，计数器 CV 通过 D 地址可观测。
• 将 HMI、虚拟寄存器和控制逻辑形成完整闭环。
• 验证 TON 的接通延时、断开复位、多个 T 独立计时、CTU/CTD 上升沿计数、复位/完成状态、MOVE 和 ADD/SUB 的网络顺序语义。
• 实现启动、停止、异常和当前运行状态反馈。
• 记录节点、支路和网络导通轨迹，在画布突出导通路径和故障节点。

完成标准：不连接 PLC 时，可以通过 HMI 操作并观察逻辑运行结果。

9. 实现 Modbus RTU 真机通信

• 使用 Qt SerialBus 的 QModbusRtuSerialMaster 封装独立通信服务。
• 实现串口配置、连接、断开、M/D 读写、轮询、超时和错误反馈。
• 使用从 0 开始的原始 Modbus 地址，通信过程不得阻塞 UI。
• 收集 HMI 和梯形图实际引用地址，按 M/D 分区并合并相邻地址轮询。
• 写请求不乐观更新缓存，等待下一次读回确认 PLC 实际值。

完成标准：软件链路和自动化测试完成后，先在 PLC STOP 状态下稳定读取和写入 M0、D0，再验证批量轮询。

10. 完成运行模式集成

• 离线模式连接虚拟寄存器并启动软件逻辑执行器。
• 真机模式连接 PLC 寄存器缓存并停止软件逻辑执行器。
• 切换到真机模式时先读取 PLC 数据，不自动下发离线仿真值。

完成标准：两种运行模式可安全切换，数据来源和界面状态不会混淆。

11. 完成稳定性与测试

• 优先为地址边界、M/D 区域约束、HMI 和逻辑配置校验、工程校验以及模式切换规则编写自动化测试。
• 工程文件实现后测试保存加载往返和错误文件处理
• 逻辑执行器实现后测试启动停止保持等代表性场景 不为每个简单访问器单独编写测试
• 通信层验证断线、超时、CRC/协议异常和关键地址读写 真机只做少量安全冒烟测试
• 完成一次离线仿真闭环和一次真机 RUN 联动流程测试

完成标准：核心流程可重复执行，异常有反馈，程序不会崩溃或误写 PLC。

当前待办：自动化回归已覆盖核心领域、编辑、存储、仿真、运行模式、PLC 缓存和主界面；真实串口、接线、STOP 安全写入和 RUN 联动仍需连接 XDH-60T4-E 验证。

12. 完成交付与演示

• 整理规格书、方案书、测试大纲、构建运行说明和演示工程。
• 准备工程创建、HMI 配置、逻辑配置、离线仿真、真机联机和状态反馈的演示流程。
• 最后再评估新增控件、设备适配或插件机制等可选加分项。

完成标准：在干净环境中可以按文档构建，并完整演示验收流程。

建议进度

周期	阶段
第 1 周	第 1~5 步：基线、架构、模型、工程管理和主界面
第 2 周	第 6~8 步：HMI、控制逻辑和离线仿真
第 3 周	第 9~10 步：Modbus RTU 和运行模式集成
第 4 周	第 11~12 步：测试、修复、文档和演示

执行纪律

• 不跨阶段提前堆叠功能；发现前置模型不稳定时，先修正前置阶段。
• 每完成一个阶段，都执行构建和对应测试，并更新 docs/ai/handoff.md。
• 核心验收功能完成前，不优先开发插件系统、复杂动画和非必要控件。