通用 Simulink HIL 建模规范

目标

建立可理解、可替换、可配置、可实时执行、可自动测试、可重复构建的 HIL 模型。把模型契约作为核心：端口表达角色与方向，Bus 表达数据结构，监视总线表达只读观察，Variant 表达产品差异，数据字典表达唯一真源，测试证据表达可发布性。

工作方式

1. 确认任务类型：新建、重构、接口设计、实时化、变体治理、旧模型迁移或合规评审。
2. 记录目标 MATLAB/Simulink、HIL 平台、编译器、目标机、许可证和兼容矩阵；不要把某个示例版本当成通用要求。
3. 读取与任务相关的参考文件：
   • 架构、层级、端口、总线和监视接口：读取 architecture-interfaces.md。
   • 数据字典、Variant、实时执行、库和初始化：读取 data-variants-realtime.md。
   • 旧模型改造：读取 migration-guide.md。
   • 评审或交付：读取 review-checklist.md。
4. 先定义边界和契约，再实现算法；先稳定接口，再集中数据，再收敛变体，最后优化结构和性能。
5. 把要求标为 MUST、SHOULD 或 MAY。偏离 MUST 时要求书面偏离、风险、责任人和关闭日期；偏离 SHOULD 时记录理由和替代控制。
6. 只在有日志、报告或测试结果时宣称通过；无法执行的动态检查应标为“未验证”，并列出环境缺口。

交付模式

设计新模型

• 输出顶层模块、功能接口、监视接口、任务/速率边界、数据字典分层、变体点和测试入口。
• 优先使用 Bus Element Ports、受控 Bus/ValueType、命名采样时间和命名配置。
• 保持根层只表达架构、分区和外部接口，不散布业务算法。

审查模型

• 先做静态盘点：依赖、层级、端口、Goto/From、工作区数据、参数、变体、采样时间、求解器和库链接。
• 再做动态验证：干净启动、Update Model、仿真、配置矩阵、构建、目标机性能和可重复重建。
• 用 review-checklist.md 输出表格，逐项记录状态、证据、风险和整改方法。

迁移旧模型

• 保留可运行基线和数值回归，不做一次性“大爆炸”重构。
• 在边界添加适配层，分阶段迁移隐式连接、匿名向量、全局监视信号、散乱 Variant 和 Base Workspace。
• 每个阶段都执行接口比较、回归仿真和目标构建。

通用化边界

• 将产品名、供应商 API、固定工具版本、固定接口前缀和示例阈值视为项目适配项。
• 保留可泛化规则：显式边界、稳定契约、只读监视、集中配置、单位和类型完整、确定性执行、干净环境重建。
• 允许受限工具链使用等价回退方案，但不得退回散乱常量、匿名接口或不可重复脚本状态。
• 供应商库默认保持链接和只读；项目定制放在外部包装层或自有组件中。

最低输出要求

• 给出架构或审查结论、适用工具链、假设和未验证项。
• 对每条问题给出模型位置、违反规则、工程风险、整改建议和验证方法。
• 对接口列出名称、方向、数据类型、维度、单位、采样率、所有者和描述。
• 对发布列出配置、测试、构建、性能、依赖和可重复性证据。