Engineering Principles

工程铁律

把稳定性要求写成可评审、可测试、可验收的规则——两条核心铁律、九大规则族、四十余条编号规则,覆盖连接生命周期、链路重建准入、恢复预算、防饿死、优雅关停与发布门禁。

定位:本栏目是《开发原则与验收标准》中两条核心铁律的操作层细则——战略层原则在此落地为编号规则、代码锚点、测试要求与验收判据,构成「铁律 → 细则 → 门禁 → 指标」体系的细则层。</div>

两条核心铁律

# 铁律 最小判据
1 任何性能优化不得以牺牲稳定性为代价 不得移除或弱化保留防线;不得新增无超时、无退避、无 recover 边界的 IO / 调度路径;性能类变更须附故障注入复跑结论
2 任何架构优化不得增加系统恢复复杂度 恢复的人工介入度、外部依赖、步骤数不增加;判定口径为「恢复复杂度净退化」——增强自愈不判违规

工业现场资源保护总纲:不得把频繁重连当作默认自愈方式。恢复优先级——优先复用现有连接 → 优先恢复单个设备的采集 → 仅在满足严格准入条件时重建共享链路 → 任何情况下不得以反复拨号掩盖资源释放失败。

九大规则族

CONN · 6 条

连接生命周期契约

「连接已关闭」是可验证状态:停新 I/O → 在途结束 → 资源释放 → 后台任务退出 → 切换完成,五事件齐备才允许安装新连接;含代际标识与 ReleaseUncertain。

REC · 12 条

南向恢复约束

重建准入铁律:设备未全部离线禁止重建;故障五分类;恢复范围与证据一致;看门狗防抖、全局限流、单 PLC 单连接、断网按目标路径判定。

BUD · 6 条

恢复预算

重试职责划分、任务整体时间预算、退避 / 冷却 / 限流职责表、单资源重连节流、控制写入幂等性、共享连接 deadline 协调。

SCAN · 6 条

采集调度与防饿死

端到端数据新鲜度链条、时间戳族与数据质量、负载过载策略、阈值族拆分、采样与数值变化分离、任务合并语义约束。

SAFE · 2 条

panic 存活保障

recover 四层语义与三态分类(RecoveredAndContinue / RestartWorker / ComponentFailed);进度监控区分「goroutine 活着」与「功能在推进」。

SHUTDOWN · 2 条

优雅关停

先关南向、最后关日志的硬序契约;六阶段可等待屏障、全局 + 单阶段预算、升级交接与退出前资源采样。

OBS · 3 条

可观测性契约

关键事件字段与脱敏规则、指标基数预算、限频统计补偿——日志记事件、指标记趋势、内部状态支撑实时决策。

DRV · 2 条

驱动能力矩阵

接口存在 ≠ 恢复能力完成:生命周期、并发保护、取消超时、故障分类、资源释放验证等统一要求;豁免须六要素 + 生命周期字段。

TEST · 5 条

验收门禁

验收矩阵、恢复成功六判据、PR 检查表、发布四态判定与阻断规则、门禁量化——未验证不等价于通过。

C-1 ~ C-17

缺口清单

17 项已登记缺口逐条标注关联规则与成熟度,是落地优先级与版本记录的共同基线;无编号的新增约束应先入清单再进代码。

栏目导航

页面 内容
工程铁律与恢复细则(全文) v2.4 完整规则文本:§0 核心铁律与治理、细则 1 防饿死、细则 2 连接生命周期、南向恢复约束、恢复预算、panic 存活、优雅关停、可观测性、驱动矩阵、验收门禁、缺口清单、修订路线与评审风险登记
2026 Q4 合规评审与改进计划 代码级系统评审结论(九族合规总览、新发现问题 N-1~N-14、文档一致性修正 6 处)与 28 项改进任务(优先级 / 责任角色 / 实施周期 / 验收标准)
开发原则与验收标准 战略层:两条核心铁律的原始声明与验收框架
发布门禁 G-Industrial 门禁与量化阈值落点(TEST-005 衔接)
采集路径并发与恢复设计 架构层恢复设计背景

规范用语

用语 含义
必须 不满足则违反工程规则或阻断发布
禁止 不允许出现的行为
应当 默认必须遵循;例外需给出理由并留痕
建议 推荐实践,不直接作为阻断条件

规则编号稳定,不因章节调整变化——代码评审、故障单与发布记录直接引用编号(如 REC-002、CONN-001),不依赖描述性文字。

缺口概览

主题 缺口编号 说明
重建准入与状态一致性 C-2 · C-10 四条件合取准入未实现;准入检查与采集回写的并发原子性未保证
连接关闭与资源释放 C-1 · C-8 逐协议先关后开缺专项测试;ReleaseUncertain 状态未实现
错误分类与 deadline C-12 · C-13 错误字符串分类未做联合判定;共享连接 deadline 未专项审计
重连节流与写安全 C-9 · C-16 单资源节流未实现;写幂等性声明与结果待确认流程缺失
统一恢复编排覆盖 C-3 omron / mitsubishi / snmp 已绑 linkMu 但未接入 ConnectionManager(2026-10-17 评审更正原记载);ice104 断线后无自动重连
调度与数据质量 C-6 时间戳族与点位级新鲜度未实现
panic 与关停 C-5 · C-7 · C-14 循环存活验证、关停阶段屏障与全局预算未落地
测试与发布 C-11 · C-15 · C-17 槽位耗尽测试缺失;门禁量化阈值待建;驱动能力新字段待建档

修订记录

版本 日期 要点
发布后评审 2026-10-17 系统性代码级评审(四组并行):九族均「部分合规」,C-1~C-17 全部确认存在,新发现问题 N-1~N-14,形成 2026 Q4 改进计划
v2.4 2026-10-16 纳入其他章节专项评审:错误联合判定、写幂等性、deadline 协调、任务合并语义、panic 三态、关停屏障、量化门禁
v2.3 2026-10-16 纳入工业现场专项评审:重建准入四条件合取、ReleaseUncertain、单资源重连节流
v2.2 2026-10-16 恢复路径分工:链路有存活设备期间,离线设备由防饿死机制探测恢复
v2.1 2026-10-16 所有者裁定:「设备未全部离线禁止重建」恢复为必须级铁律,强制保留
v2.0 2026-10-16 全面重构为九大规则族编号体系,建立规范用语与成熟度概念
v1.2 2026-10-16 新增重连 / 链路重建约束矩阵 R-0 ~ R-9
v1.1 2026-10-16 强化重新建立链接先关后开;新增程序退出先关南向再关日志

评审声明:附录 A / B 的风险登记基于文档与实现状态记录提出,未逐一审计仓库源码与现场设备——评审推断不得直接当作已确认的代码缺陷,落地前须源码审计。</div>