# 项目长期约定

- 项目作者：`suyu`
- 文件、终端输出和源代码统一使用 UTF-8
- 答复我的文本要说人话，口语化答复我

## 新会话阅读顺序

1. 先读 `docs/ai/handoff.md`，确认当前状态、未提交改动、验证结果和下一步
2. 涉及模块边界、数据流、运行模式或持久化时，再读 `docs/architecture.md`
3. 按任务读取下方索引中的业务文档；Markdown 没有答案时再查 `docs/pdf/`

三个入口文档各自只负责一类信息，不互相复制正文：

- `AGENTS.md`：长期有效的协作、构建、验证、安全和 Git 约束；不记录当前功能清单或开发进度
- `docs/architecture.md`：当前代码的稳定分层、模块边界、核心模型和数据流；不记录未提交文件和按日期排列的验证结果
- `docs/ai/handoff.md`：当前工作区状态、本轮改动、最近验证和下一步；更新时替换旧状态，不追加开发流水账或重复专题文档

格式字段、数量边界、测试范围和硬件资料分别以对应专题文档为准。功能变化时更新所属专题文档，入口文档只保留导航、稳定约束或当前交接信息。

## 关键文件索引

- 当前交接：`docs/ai/handoff.md`
- 架构与数据流：`docs/architecture.md`
- C++ 规范：`docs/C++代码规范.md`
- 原始需求：`docs/0_综合平台编程器_修改.md`
- 数量边界最终规则：`docs/用户使用/数量边界确认方案.md`
- 应用配置文件：`docs/用户使用/应用配置说明.md`
- 用户运行程序导出：`docs/用户使用/用户运行程序导出说明.md`
- 数据监控与离线初始值：`docs/用户使用/数据监控与离线初始值说明.md`
- 鼠标画线与删线：`docs/用户使用/鼠标画线与删线说明.md`
- 工程 JSON 格式：`docs/工程格式说明.md`
- 开发阶段顺序：`docs/开发顺序.md`（阶段参考，当前状态以 handoff 为准）
- 测试约定：`docs/测试约定.md`
- XDH-60T4-E 硬件接线：`docs/XDH-60T4-E硬件与接线要点.md`
- XDH-60T4-E 指令与 Modbus：`docs/XDH-60T4-E指令与Modbus要点.md`
- PLC 官方手册：`docs/pdf/`
- Qt 源码：`app/`
- 构建输出：`build/`（不纳入 Git）

## 技术栈与构建

- 使用 C++17、Qt 5.15.2、Qt Widgets 和 qmake，不使用 CMake
- UI 默认使用 Qt Designer `.ui` 文件；不要把静态表单重新堆回 C++
- Qt MinGW 套件：`D:\Qt5.15.2\5.15.2\mingw81_64`
- Windows 命令优先使用 PowerShell 7；显式调用使用 `pwsh -NoLogo -NoProfile -Command`，脚本使用 `pwsh -NoLogo -NoProfile -File`
- 复杂 PowerShell 逻辑写入 `.ps1` 后执行，避免嵌套引号；排查兼容问题时先确认 `$PSVersionTable.PSVersion` 和 `$PSVersionTable.PSEdition`
- 在独立构建目录运行 qmake 和 `mingw32-make`，不要把生成物写进 `app/`
- 项目编译运行：`pwsh -NoLogo -NoProfile -File .\scripts\build_and_run_qt.ps1`
- 测试编译运行：`pwsh -NoLogo -NoProfile -File .\scripts\run_qt_tests.ps1 -Configuration Release`
- Qt 项目打包：`pwsh -NoLogo -NoProfile -File .\scripts\package_qt_app.ps1`
- 打开主界面：`& 'D:\Qt5.15.2\5.15.2\mingw81_64\bin\designer.exe' '.\app\src\ui\main_window.ui'`

## 代码与架构约束

- 保持 `UI -> Services -> Domain` 依赖方向，基础设施实现服务契约；`domain` 不依赖 Qt、串口或文件系统
- 业务规则放领域或服务层，不得堆入 `MainWindow`、Qt 槽函数或图元绘制代码
- HMI 和运行界面只访问寄存器仓库，不直接访问串口；PLC 通信必须异步，不能阻塞 UI
- 编辑操作通过服务完成并保持原子性，失败时不得留下部分修改
- 数量边界统一定义在 `app/src/domain/project_limits.h`，修改时同步更新数量边界文档和边界测试
- M/D 项目地址范围固定为 `0~4000`；Modbus 使用从 `0` 开始的原始地址
- 离线模式使用虚拟 M/D 并运行软件逻辑执行器
- 真机模式使用 PLC 读回缓存；每轮完整轮询后在临时仓库推算本地梯形图轨迹，不把本地输出写入 PLC；切换时先读 PLC，不复制离线值
- 本项目不生成、编译或下载 PLC 程序，不得把本地梯形图轨迹当成 PLC 内部程序轨迹
- 代码注释只解释不明显的约束，末尾不要加句号 `。`

## 验证与安全

- 代码改动必须构建相关测试；共享模型、持久化、运行模式或 UI 工作流改动还要扩大回归范围
- 提交前至少完成对应自动化测试、Release 构建和 `git diff --check`
- 涉及 PLC 通信或真机运行模式的代码，使用 `COM3 / 9600 / 8E1 / 站号 1` 做真实读写验证；先读取原值，测试后恢复并读回确认
- STOP 用于安全通信验证；带真实设备的联动测试必须在确认接线和地址后切到 RUN
- 纯文档、领域校验或离线执行器改动不要求连接 PLC，但要在 handoff 中说明未做真机测试的原因
- 离线仿真不会向 PLC 下载程序

## Git 提交

- 不覆盖或回退工作区中来源不明的改动，开始前先检查 `git status` 和相关 diff
- 每次提交只包含一个逻辑完整改动，提交前完成对应验证
- 提交信息使用 `类型: 简短说明`，类型限 `feat`、`fix`、`docs`、`test`、`refactor`、`chore`