You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
4.3 KiB
4.3 KiB
项目长期约定
- 项目作者：
suyu - 文件、终端输出和源代码统一使用 UTF-8
新会话阅读顺序
- 先读
docs/ai/handoff.md，确认当前状态、未提交改动、验证结果和下一步 - 涉及模块边界、数据流、运行模式或持久化时，再读
docs/architecture.md - 按任务读取下方索引中的业务文档；Markdown 没有答案时再查
docs/pdf/
三个入口文档各自只负责一类信息：
AGENTS.md：长期有效的开发、构建和安全约束docs/architecture.md：稳定的分层、模块边界、核心模型和数据流docs/ai/handoff.md：当前进度、工作区状态、最近验证和下一步；更新时替换旧状态，不追加开发流水账
关键文件索引
- 当前交接：
docs/ai/handoff.md - 架构与数据流：
docs/architecture.md - C++ 规范：
docs/C++代码规范.md - 原始需求：
docs/0_综合平台编程器_修改.md - 数量边界最终规则：
docs/用户使用/数量边界确认方案.md - 工程 JSON 格式：
docs/工程格式说明.md - 开发阶段顺序：
docs/开发顺序.md（阶段参考，当前状态以 handoff 为准） - 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/ - Debug 构建运行：
pwsh -NoLogo -NoProfile -File .\scripts\build_and_run_qt.ps1 - Release 构建运行：
pwsh -NoLogo -NoProfile -File .\scripts\build_and_run_qt.ps1 -Configuration Release - 打开主界面：
& '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 内部程序轨迹
- 代码注释只解释不明显的约束，末尾不要加句号
。
验证与安全
- 代码改动必须构建相关测试；共享模型、持久化、运行模式或 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