开发规范与注释约定

强制同步规则

自 2026-04-13 起，Code 目录内任何代码改动都必须同步更新以下 3 份文档：

1. Code/文档/开发规范与注释约定.md
2. Code/文档/总体架构与代码分析.md
3. Code/文档/修改记录.md

如果改动没有同步更新这 3 份文档，则视为变更未完成。

顶层架构规范

1. PLC 工程任务只绑定 PRG_MainControl，且基础周期固定为 1ms。
2. PRG_MachineController、PRG_ManualMode、PRG_MoldAdjustMode、PRG_AutoCycle 只保留为兼容占位，不得再加入任务调度。
3. 所有共享变量统一放在 Code/全局变量/GlobalVars.st。
4. 所有需要全局复用的顶层实例统一放在 Code/实例管理/Instances.st。
5. 模式路由、自动流程调度和执行模块调用统一由 FB_MachineController 管理，不允许在其他顶层程序中重复驱动同一功能块实例。
6. PRG_MainControl 必须运行在 1ms 基础任务上，并在顶层统一生成固定 10ms 工艺节拍和固定 100ms 温控节拍；FB_MachineController 只消费顶层下发的 10ms 节拍，FB_EK312 必须每 1ms 都由顶层调用一次，但只在顶层下发的 100ms 节拍上执行一轮温控计算。
7. 执行模块负责先把现场反馈、模块报警和 stConfig 写入 ST_AxisRefHyd，再在模块内部各自实例化 FB_HydAxis，并通过统一接口 bStart、bStop、bEStop、bReset、bDir、uiMode、uiCmdPres、uiSpd、udiPos、uiForce、uiAcc、uiDec、uiJerk 完成最终轴实例化、限幅和轴层诊断；禁止再在 FB_MachineController 重复实例化同一根轴。
8. FB_EK312 统一由 PRG_MainControl 顶层直接调用并由顶层驱动其 100ms 刷新拍；FB_MachineController 不处理温控块接口、温控状态和温控报警，不再直接实例化或消费温控块结果。
9. HMI 与面板的 Modbus 通讯统一由 PRG_MainControl 顶层调用 FB_Modbus 收口；GlobalVars.st 必须统一收口 gvl_stModbus、gvl_ePanelModel、gvl_stPanelIO、gvl_stPanelButtons、gvl_stPanelCommandSource、gvl_stHMIPara、gvl_stHMIParaCommand、gvl_stHMIParaStatus 八类相关顶层边界。
10. 面板调度块只能回写独立命令源 gvl_stPanelCommandSource，不得再直接写最终 gvl_stCommand；模式选择和手动点动命令必须统一经过 FB_CommandArbiter 仲裁后再供温控和主控消费。
11. 现场物理公共运行命令必须先收口到独立命令源 gvl_stPLCDigitalCommandSource，不得在 PRG_MainControl、FB_MachineController 或其他业务块中直接散写 gvl_stCommand.bStart、bStop、bReset、bEStop。
12. FB_CommandArbiter 中必须显式写清公共运行命令的来源和优先级；当前维护基线为：gvl_stPLCDigitalCommandSource 覆盖基础命令快照中的 bStart、bStop、bReset、bEStop，面板命令源只覆盖 uiMachineMode 与 stManual.*。
13. 面板管理统一使用 ST_PanelButtons.aButton[TO_UINT(ePanelButton_*)] 收口逻辑键的排序号、键值和灯值；同一逻辑键的键值与灯值必须共用同一个 uiPanelOrder，不同面板型号只允许在对应 FB_MK110、FB_MK116、FB_MK150 中调整排序号定义。
14. 面板逻辑键命名必须统一采用 E_PanelButtonID 中的当前工艺语义命名，例如 ePanelButton_SemiAuto、ePanelButton_FullAuto、ePanelButton_MoldAdjust、ePanelButton_Heater、ePanelButton_Metering、ePanelButton_Injection、ePanelButton_SuckBack、ePanelButton_EjectIn、ePanelButton_EjectOut、ePanelButton_NozzleIn、ePanelButton_NozzleOut、ePanelButton_CoreAIn、ePanelButton_CoreAOut、ePanelButton_AirBlow、ePanelButton_AirBlowA、ePanelButton_AirBlowB；禁止再回退到旧字段式命名或重新引入并行别名结构。
15. 面板管理中的输入字、输出字和位操作辅助接口统一使用 UINT 类型，并统一采用 uiINx、uiOUTx、uiValue 前缀，禁止再在该层新增 WORD 类型或 w* 前缀接口变量。
16. 若某面板型号允许通过 FB_MKxxx 调整逻辑键排序，则对应读键函数不得再维护第二套固定排序号；读键函数必须直接消费该 FB_MKxxx 已写入的 uiPanelOrder 定义，并按 1..64 顺排映射到 uiIN0..uiIN3，避免同一型号出现两处排序号源。
17. 面板管理的公共抽象层统一放在 Code/面板管理/面板公用；后续若新增可复用的公共逻辑，应优先扩展 F_PanelReadKeyByOrder、FB_PanelReader、FB_PanelLampEncoder、FB_PanelLampWriter 这类公共块，而不是直接在各型号目录重复展开；公共遍历逻辑必须优先基于 ST_PanelButtons.aButton 数组循环实现，具体型号功能块应保持 FB_MK110、FB_MK116、FB_MK150 这种“先清零全部 uiPanelOrder，再只覆写本型号已提供键位”的结构。
18. 若同一个面板调度块在同一扫描周期内既要读键又要写灯，则必须先完成型号映射与读键，再更新命令源和灯请求，最后由独立灯编码层统一生成原始输出字；禁止通过双调用同一型号块来修补同拍出灯时序。
19. FB_MachineController 内部若继续扩展复杂逻辑，必须优先复用或扩展 FB_MachineModeResolver、FB_MachineCommandComposer、FB_MachineStatusAggregator 三层，而不是把模式解析、命令合成、状态汇总重新堆回单一大块。
20. HMI 参数链必须显式拆成“ST_Modbus.stHMIInput -> FB_Modbus 输入绑定阶段 -> HMI 业务边界 -> FB_HMIParaInterface -> FB_Modbus 输出绑定阶段 -> ST_Modbus.stHMIOutput”；禁止再让 FB_HMIParaInterface 直接消费实际通讯镜像。
21. 面板链必须显式拆成“ST_Modbus.stPanelInput -> FB_Modbus 输入绑定阶段 -> ST_PanelIO -> FB_PanelDispatcher -> FB_Modbus 输出绑定阶段 -> ST_Modbus.stPanelOutput”；禁止再让面板调度块直接消费实际通讯镜像。
22. Code/IO管理 负责现场原始 IO 绑定与语义收口；原始数字量点位统一收口到 Code/IO管理/PLCIOTypes.st 的 ST_PLCIO 与 GlobalVars.st 中的 gvl_PLC，并由 PRG_MainControl 统一先调用数字量输入绑定块、再调用 FB_PLCMachineInputMapper 收口输入语义与公共命令、再调用 FB_PLCMachineOutputMapper 收口输出语义、最后调用数字量输出绑定块。
23. ST_Modbus 及其 stHMIInput、stHMIOutput、stPanelInput、stPanelOutput 才是实际 Modbus 通讯镜像边界；ST_HMIProcessPara、ST_HMIParaCommand、ST_HMIParaStatus、ST_PanelIO 则属于 PLC 内部业务边界，注释中必须明确写清这两层职责，不得再混写。
24. 若后续接入真实 Modbus 主站/从站驱动、寄存器地址表或协议版本兼容层，只允许把地址绑定与报文拆装落在 gvl_stModbus 与 FB_Modbus 这一层；禁止把实际寄存器地址、报文偏移或驱动句柄直接散写到业务块。

命名规范

1. PRG_*：顶层程序入口，只用于任务级调度。
2. FB_*：功能块，封装可复用控制逻辑。
3. ST_*：结构体类型，定义模块参数、接口和状态边界。
4. E_*：枚举类型，定义状态机或模式值。
5. gvl_*：全局共享对象，只能用于 VAR_GLOBAL 顶层边界，不得替代模块内部临时变量。
6. 布尔量使用 b 前缀，整型使用 ui/udi/dw，浮点使用 r，结构体使用 st，枚举使用 e。

注释规范

文件头注释

每个 .st 文件必须在开头说明以下内容：

1. 文件职责。
2. 调用关系或数据边界。
3. 维护重点或使用限制。

编码与可读性

1. Code 目录下的 .st 文件统一使用 UTF-8 with BOM 编码保存；.md 文件统一使用 UTF-8。
2. 禁止提交乱码注释、错码注释、无 BOM 导致的显示乱码文件，或同一文件混用多种文本编码。
3. 发现旧文件存在注释错码时，不做“保留历史乱码”处理，应直接修正为可读中文，并同步补齐统一编码。

功能块注释

每个 FUNCTION_BLOCK 至少要说明：

1. 控制目标是什么。
2. 自动模式和手动模式的差异。
3. 关键状态机或互锁逻辑。
4. 对外输出的语义。

变量注释

以下变量必须写明用途：

1. VAR_IN_OUT、VAR_INPUT、VAR_OUTPUT、VAR 中的每一个变量定义都必须写详细注释，禁止再出现“只有部分变量有注释”的情况。
2. 后续新增的变量、实例、缓存、命令、状态、计时器、步骤号、报警号、模式号和数组定义，必须在首次提交时同步补齐详细注释。
3. 详细注释至少要写清楚：变量作用、谁来写、谁来读、特殊取值、单位/节拍/模式语义、是否用于互锁或状态汇总。
4. 若变量位于 TYPE ... STRUCT 定义中，也必须按同样标准补齐字段语义注释，不允许只写结构体段落说明而字段本身无语义。
5. 局部状态变量必须显式放在 VAR ... END_VAR 段中，不允许遗漏声明边界，也不允许以“命名看得懂”为理由省略注释。

状态机注释

状态机代码必须满足：

1. 每个状态段前要能看出“当前状态做什么”。
2. 进入条件、退出条件、超时条件和报警条件要可直接读懂。
3. 对模式切换、复位、急停、停止这类公共分支要明确写出意图。

注释密度

1. 自 2026-04-17 起，代码按“逐变量、逐参数、逐执行行”作为强制注释基线维护。
2. 可执行代码原则上每一行都必须有详细注释，允许采用“同行注释”或“紧邻上方只解释下一行/下一小段的单用途注释”，但不能让读者再去猜这一行在做什么。
3. 功能块或程序调用参数采用多行展开时，每一行参数都必须说明该参数的来源与用途。
4. 主功能块文件至少要覆盖：文件头注释、全部 VAR_* 变量详细注释、主分支/状态入口注释、关键赋值与互锁行注释。
5. 类型文件至少要说明：类型职责、结构体字段语义、模式号或状态值的业务含义。
6. 对外部边界文件，例如 GlobalVars.st、Instances.st、PRG_MainControl.st，必须明确说明调用链、共享数据用途和顶层职责划分。
7. 自 2026-04-14 起，FB_Clamp、FB_MoldAdjust、FB_Nozzle、FB_Inject、FB_Meter、FB_Eject、FB_EjectMode、FB_Core 8 个执行块已作为“详细注释基线”补齐局部变量语义、公共分支意图和状态机段落说明；后续修改这些文件时不得把注释密度降回“只有文件头和接口注释”。

禁止事项

1. 禁止只写“处理逻辑”“执行动作”这类空洞注释。
2. 禁止用注释掩盖命名不清的问题。
3. 禁止在多个文件中保留彼此冲突的架构说明。
4. 禁止在代码中写“以后再补”“待完善”而不落到 修改记录.md。
5. 禁止新增无注释变量、无注释结构字段、无注释调用参数和大段无行意图说明的执行代码。

结构设计规范

1. 机器级输入输出边界统一收口到 ST_MachineCommand、ST_MachinePara、ST_MachineSensor、ST_MachineStatus；其中 ST_MachineSensor 当前只保留有真实数字量输入来源的机器语义字段，不再承载电子尺、压力尺和轴实际位置/速度/压力等数值反馈。
2. 新增模块时，先补类型定义，再补主控分发，再补执行块，最后补文档。
3. 轴类扩展优先放在 Code/伺服系统 目录下统一定义类型与轴层功能块；执行模块内部允许各自持有一份 FB_HydAxis 实例。
4. 不允许新增绕过 FB_MachineController 的模式调度链。
5. 如需增加新的全局变量，必须先证明该变量不能放在局部作用域或结构体边界中。
6. 所有 ST 结构化语句结束关键字必须带分号，例如 END_FOR;、END_CASE;、END_IF;，静态检查发现缺失时必须立即修复并同步记录。
7. 所有全局变量和全局实例统一使用 gvl_ 前缀，禁止再新增 g_ 前缀对象。
8. Code/伺服系统/液压轴/AxisTypes.st 中的 ST_AxisRefHyd 必须只保留当前液压执行链真实在用的公共边界字段，即“轴参与状态、能力边界、目标命令、实际反馈、泵请求、故障码、轴配置、轴状态”；禁止再把未接线、未消费的旧伺服全量元数据直接堆回该公共结构。
9. 现场原始数字量点位命名统一沿用电气 IO 表中的 X* / Y* 点号，不得在原始 IO 层再引入第二套并行别名；若要翻译成工艺语义，必须在原始 IO 层之后新增独立映射层。
10. PRG_MainControl、FB_MachineController、面板层和其他业务块禁止直接散写 gvl_PLC.X* / gvl_PLC.Y* 的工艺语义；原始输入必须先经过独立输入语义映射层翻译到 gvl_stSensor 等业务边界，原始输出必须先经过独立输出语义映射层再回写到 gvl_PLC.Y*。
11. 当主控继续扩展模块命令源或运行时状态时，必须优先扩展 ST_ModuleCommandSource、ST_EjectModeCommandSource、ST_MachineCommandSourceSet、ST_ModuleRuntimeStatus 及对应模块包装结构；禁止继续给 FB_MachineCommandComposer、FB_MachineStatusAggregator 或 FB_MachineController 追加超长标量参数表。

文档更新要求

改动开发规范时

同步更新本文件，并在 修改记录.md 记录变更原因。

改动模块职责、入口关系或状态边界时

同步更新 总体架构与代码分析.md，确保文档中的执行链、模块列表和风险说明与代码一致。

任何代码改动

都必须在 修改记录.md 增加一条带日期的记录，至少写明：

1. 变更日期。
2. 变更文件。
3. 变更目的。
4. 是否同步更新了另外两份文档。