# 项目长期约定

- 项目作者：`suyu`。

## 关键文件索引

- C++ 代码规范：`docs/C++代码规范.md`。
- 需求参考文档：`docs/0_综合平台编程器_修改.md`。
- 推荐开发顺序：`docs/开发顺序.md`。
- Qt 应用源码根目录：`app/`。
- 本机构建输出目录：`build/`（不纳入 Git）。
- Qt 一键构建运行脚本：`scripts/build_and_run_qt.ps1`。
- XDH-60T4-E 硬件与接线要点：`docs/XDH-60T4-E硬件与接线要点.md`。
- XDH-60T4-E 指令与 Modbus 要点：`docs/XDH-60T4-E指令与Modbus要点.md`。
- PLC 官方手册：`docs/pdf/`。
- 当前开发进度和未完成事项：`docs/ai/handoff.md`（创建后每次新会话优先阅读；不要把动态进度写入本文件）。
- 架构、模块边界和数据流：`docs/architecture.md`（创建后优先阅读）。
- 查阅资料时，先读取 UTF-8 编码的 Markdown 文档；只有 Markdown 中找不到所需信息时，才查阅 `docs/pdf/` 内的 PDF 手册。

## 技术栈与构建

- 使用 C++、Qt 5.15.2 和 Qt Widgets；UI 默认使用 Qt Designer 的 `.ui` 文件。
- 使用 qmake，不使用 CMake。
- Qt MinGW 套件根目录：`D:\Qt5.15.2\5.15.2\mingw81_64`。
- 构建前在 PowerShell 7 中设置 Qt 工具链路径；MinGW 工具目录为常见安装位置，如实际安装位置不同，以本机路径为准：

```powershell
$env:QTDIR = 'D:\Qt5.15.2\5.15.2\mingw81_64'
$env:Path = "$env:QTDIR\bin;D:\Qt5.15.2\Tools\mingw810_64\bin;$env:Path"
qmake <项目文件>.pro
mingw32-make -j2
```

- 优先在独立构建目录执行 qmake 和 `mingw32-make`，不要将生成物混入源代码目录。
- 文件读写、终端查看和源代码统一使用 UTF-8。
- 一键构建并运行 Debug 程序：`pwsh -NoLogo -NoProfile -File .\scripts\build_and_run_qt.ps1`。
- 一键构建并运行 Release 程序：`pwsh -NoLogo -NoProfile -File .\scripts\build_and_run_qt.ps1 -Configuration Release`。
- 打开 ui 文件：` & 'D:\Qt5.15.2\5.15.2\mingw81_64\bin\designer.exe' '.\app\src\ui\main_window.ui'`

## Git 提交约定

- 每次提交只包含一个逻辑完整的改动；提交前必须完成对应的构建或测试验证。
- 提交信息使用 `类型: 简短说明` 格式，例如 `feat: 建立 Qt 工程基线`。
- 类型使用 `feat`、`fix`、`docs`、`test`、`refactor` 或 `chore`。

## 架构与运行模式

- 保持 UI、领域、服务和基础设施分层；业务逻辑不得堆入 `MainWindow` 或 Qt 槽函数。
- HMI 只绑定 M/D 寄存器仓库，不得直接读写串口；串口通信必须异步，不能阻塞 UI。
- M 区和 D 区的项目可用地址均为 `0~4000`；Modbus 代码使用从 `0` 开始的原始地址。
- 离线模式使用虚拟 M/D，并运行软件逻辑执行器。
- 真机模式使用 PLC 的真实 M/D，软件逻辑执行器必须停止；切换时先读取 PLC 数据，不自动写入离线虚拟值。
- 真机联动设备时 PLC 必须处于 RUN；STOP 仅用于安全通信验证。

## 注意
- 生成注释的文本结尾别加逗号 `。`。