3. 模型资产识别与分类

在控制原型开发中，真正需要被版本治理的并不只是“模型文件”本身。一个典型的控制器原型工程，往往同时包含 Simulink 模型、Stateflow 状态机、数据字典、标定文件、MATLAB 脚本、测试用例、接口定义文件以及自动生成的代码等。如果这些对象没有被统一识别和分类，版本管理就会退化为“把整个文件夹丢进 Git”，最终导致无法判断某个变更到底影响了什么、谁该为哪类文件负责、哪些文件可以自动生成而不必入库。因此，本节的核心任务是：先建立“资产识别”的视角，再给出可落地的分类与命名规范。

一、先识别：控制原型中的六类核心资产

识别资产的关键，不是看文件扩展名，而是看它在开发链条中承担什么职责、由谁维护、变更后影响谁。按职责划分，控制原型工程通常包含以下六类对象：

• Simulink 模型（.slx）：承载控制算法、被控对象、信号路由与调度逻辑，是功能行为的主要载体。它通常包含子系统层级、采样时间、求解器配置和接口定义。
• Stateflow 状态机（.slx 内嵌或独立）：描述模式切换、使能/禁止、故障降级等离散逻辑。它常与 Simulink 模型同文件存储，但逻辑复杂度高，应单独识别为“状态逻辑资产”。
• 数据字典（.sldd / .mat / .m）：定义参数、信号、枚举、总线对象及其数据类型、单位、初值和取值范围，是模型与标定之间的契约层。
• 标定文件（.a2l / .cdfx / .par / .m）：面向台架或整车标定的参数集合，通常与数据字典中的参数对象一一对应，但按工况或版本分组。
• 脚本与工具（.m / .mlx / .py）：包括模型初始化、批量编译、接口生成、检查脚本和自动化测试驱动，属于“工程自动化资产”。
• 测试用例（.m / .xlsx / .sltest）：定义输入激励、期望输出、容差和判定条件，是验证模型行为是否满足需求的依据。

这六类资产在变更频率、评审方式和可生成性上差异很大。例如，Simulink 模型和 Stateflow 逻辑通常需要人工评审；数据字典和标定文件需要与接口、参数表对齐；脚本和测试用例则更强调可重复执行。识别阶段建议为每个对象打上三个标签：职责类型、维护责任人、是否可自动生成。这三个标签直接决定后续的入库策略和命名规则。

二、再分类：按“变更影响面”而非文件类型分组

很多团队习惯按扩展名分类，例如“所有 .m 放一起、所有 .slx 放一起”。这种做法在版本治理中并不好用，因为同一扩展名的文件可能承担完全不同的职责。更有效的分类维度是变更影响面：

• 接口级资产：数据字典中的总线、枚举、信号名、单位。一旦变更，所有引用它的模型、标定和测试都可能受影响，必须走严格评审。
• 行为级资产：Simulink 模型和 Stateflow 逻辑。变更影响功能行为，需要配套回归测试。
• 参数级资产：标定文件、参数表。变更通常不改变结构，但会改变性能表现，需要记录工况和版本。
• 工具级资产：脚本、自动化检查、代码生成配置。变更影响构建流程，需要保证可重复执行。
• 验证级资产：测试用例、期望输出、容差配置。变更影响判定标准，需要与需求条目关联。

分类完成后，建议在工程目录中直接体现这种分层，例如：

ctrl_prototype/
├─ 01_behavior/        % Simulink 模型、Stateflow
│   ├─ ctrl_core.slx
│   └─ mode_manager.slx
├─ 02_contract/        % 数据字典、接口定义
│   ├─ ctrl_data.sldd
│   └─ interface_def.m
├─ 03_calibration/     % 标定文件、工况分组
│   ├─ cal_eco.cdfx
│   └─ cal_sport.cdfx
├─ 04_automation/      % 脚本、构建、检查
│   ├─ init_project.m
│   └─ check_model.m
└─ 05_verification/    % 测试用例、期望结果
    ├─ tc_accel.m
    └─ tc_fault_recovery.m

这种目录结构本身就是一种分类规范：任何人打开工程，都能立刻判断某个文件属于哪一层、变更后应该通知谁、需要跑哪类测试。

三、命名规范：让文件名携带可检索的治理信息

命名规范的目标不是“好看”，而是让文件名在版本历史、变更单和评审记录中可被快速检索和比对。推荐采用“层级前缀 + 对象名 + 类型后缀 + 版本/工况标识”的结构，各字段用下划线连接，避免空格和中文。以下是一组可直接参考的命名示例：

命名中应避免出现“final”“new”“test2”“copy”这类无信息量词汇。如果确实需要区分迭代，应使用版本号或日期，例如 v01、20240612，而不是 final_v2_really。对于自动生成的文件，建议在文件名或目录中加 _gen 标识，并在版本库中通过 .gitignore 排除，避免生成物与源文件混在一起造成冲突。

四、从识别到治理：建立资产清单

识别和分类的最终产物，是一份可维护的模型资产清单。清单不需要复杂，但应至少包含：资产名称、路径、类型、责任人、是否可自动生成、关联需求或接口、最近变更日期。下面给出一个可直接填写的示例片段：

资产清单示例（节选）
--------------------------------------------------------------
名称                     类型        责任人   可生成  关联接口
mdl_torque_ctrl_core     Simulink    张工     否      IF_TORQUE_REQ
sf_mode_manager_fault    Stateflow   李工     否      IF_MODE_STS
dd_powertrain_v2         数据字典    王工     否      IF_TORQUE_REQ
cal_eco_20240612         标定文件    赵工     否      PAR_TORQUE_MAP
scr_init_project         脚本        张工     是      -
tc_accel_pedal_step      测试用例    李工     否      REQ_ACC_001
--------------------------------------------------------------

这份清单的价值在于：当某个接口或需求发生变更时，可以快速定位受影响的模型、标定和测试用例，而不是靠记忆或全库搜索。对于控制原型项目，建议把清单与版本库中的目录结构、命名规范三者对齐——目录体现分类，命名体现身份，清单体现责任与关联。三者一致，后续的版本分支、变更评审和基线发布才有可靠的基础。

最后需要强调：识别与分类不是一次性工作。随着原型从算法验证走向台架、整车，资产类型会增加，责任人会调整，标定工况会分化。因此，命名规范和资产清单应作为工程约定的一部分被持续维护，并在每次基线发布前做一次一致性检查。只有先把“有哪些资产、分别是什么、归谁管”说清楚，版本治理才不至于变成对一堆文件的盲目管理。