完善MECMAS21参数配置与分组交互

2026-08-03 23:51:27 +08:00
1 parent 32f21f08ff
commit be54070855
@@ -45,7 +45,7 @@
 | `PNPL01` | 16 | 零气动流源 | 第一版公开 | `amesim_pnpl01`，`boundary` | 当前实现一端零流边界，只约束端口质量流量为 0；压力源/外部边界语义留后续扩展。 |
 | `PNGD00` | 1 | 氦气气体定义 | 氦气 Peng-Robinson 首版公开 | `amesim_helium_medium`，`media` | 已映射源模型 `fluidType=12/eosType=6`；密度和压力使用 PR EOS，热量学暂用手册参考点的定比热闭合。完整压力相关残余焓、比热和真实气体临界流仍待状态相关物性接口。 |
 | `PNRP17` | 8 | 气动活塞与移动体耦合 | 第一版公开 | `amesim_pnrp17`，`mechanical` | 已接入 1 个气动端口和 4 个一维机械端口，按 `dp/dr/x0/gi` 计算环形有效面积、扫掠容积、容积变化率和表压作用力；已与 PNCH012、双质量块跑通 System XML 联合仿真，完整事件语义和 AMESim baseline 仍待校准。 |
-| `MECMAS21` | 10 | 一维平动质量 | 第一版公开 | `amesim_mecmas21`，`mechanical` | 已接入一维机械端口 `x/v/f`、双端质量状态和基本摩擦/限位项，并跑通零力源与信号力源最小 System XML；完整 AMESim 接触/事件语义仍留后续对齐。 |
+| `MECMAS21` | 10 | 一维平动质量 | 第一版公开 | `amesim_mecmas21`，`mechanical` | 已接入一维机械端口 `x/v/f`、双端质量状态和基本摩擦/限位项，并跑通零力源与信号力源最小 System XML；参数注册已对齐 AMESim 选项码与条件显示，高级静摩擦、Stribeck 公式和倾角重力分量仍未实现。 |
 | `LMECHN1` | 2 | 动态线性机械节点 | 第一版公开 | `amesim_lmechn1`，`mechanical` | 已接入 9 端一维机械节点、端口位移/速度等值和节点力平衡，并跑通 `FORC -> LMECHN1 -> MECMAS21` 最小 System XML；端口朝向/符号细节留后续 AMESim baseline 对齐。 |
 | `LSTP00A` | 8 | 弹性接触/端止动 | 第一版公开 | `amesim_lstp00a`，`mechanical` | 已接入两端一维机械端口、相对位移/速度接触力和最小 System XML 仿真；当前是连续罚函数基础版，完整 AMESim 事件/非光滑接触语义留后续 baseline 对齐。 |
 | `F000` | 16 | 零力源 | 第一版公开 | `amesim_f000`，`mechanical` | 已作为一端机械零力边界公开，约束端口力为 0。 |
@@ -550,8 +550,20 @@ GET /api/components/catalog
 6. 使用 `symbol` 选择图标渲染器。
 7. 不在前端重新定义参数默认值、边界或端口语义。

-目录协议提供以下可选的 AMESim 介质扩展字段：
+目录协议提供以下可选的参数编辑器与 AMESim 介质扩展字段：

+- 参数的 `editor: "choice"` 表示数值是稳定的离散编码，必须同时提供非空
+  `options: [{"value": 1, "label": "..."}]`。前端显示标签，但工程、XML 与
+  求解器仍保存和接收 `value` 数值，不得把标签写入模型数据。
+- 参数可通过 `visibleWhen: [{"parameter": "mode", "values": [1, 2]}]`
+  声明显示条件。多个条件之间按 AND 处理，同一条件的多个 `values` 按 OR
+  处理；控制参数必须拥有固定 `options`。隐藏参数的既有值必须保留，不能因
+  界面联动而重置或从工程、XML 中删除。
+- 模型可通过可选的 `parameterGroups` 声明纯展示用参数分组。每组包含稳定的
+  `id`、显示 `label`、组间 `order`、有序参数名数组 `parameters` 和布尔值
+  `defaultExpanded`；默认应为 `false`。同一参数最多属于一个组，组内参数名
+  必须引用该模型已注册的参数。分组不改变参数默认值、条件显示、工程保存或
+  System XML 语义；无分组的模型不输出该字段。
 - 参数的 `editor: "amesimGasReference"` 表示该数值不是普通连续量，而是
  项目介质定义的 `gi` 引用。前端应保留索引 `0`，并从当前画布的介质定义
  组件生成其余下拉项；索引下拉项只显示数值，不拼接介质名称或中文说明。
@@ -7,6 +7,9 @@ System XML v2 是 ReactFlow 建模前端与 `app.simulation` 仿真层之间的
 - 根元素 `System` 的 `schemaVersion` 固定为 `2`，`unitSystem` 固定为 `SI`。
 - 新导出的介质引用语义使用可选根属性
  `mediumReferenceVersion="1"`。缺少该属性的文档按旧版介质索引规则读取。
+- AMESim 离散参数版本属性在 XSD 中仅为兼容旧文档而可省略；所有当前导出器
+  必须写出 `amesimParameterEncodingVersion="1"`，表示参数采用组件目录中的
+  规范编码。
 - 子元素顺序固定为 `Simulation`、`Components`、`Connections`。
 - `Component.id` 是稳定实例 ID，`name` 是用户可编辑名称。
 - 参数以 SI 基准值保存；显示单位不改变 XML 中的数值含义。
@@ -18,7 +21,7 @@ System XML v2 是 ReactFlow 建模前端与 `app.simulation` 仿真层之间的

 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
-<System name="transfer-system" schemaVersion="2" unitSystem="SI" mediumReferenceVersion="1">
+<System name="transfer-system" schemaVersion="2" unitSystem="SI" mediumReferenceVersion="1" amesimParameterEncodingVersion="1">
  <Simulation tStart="0" tStop="2" step="0.1" maxStep="0.005" method="BDF"/>
  <Components>
    <Component id="cylinder_1" name="cylinder_1" type="cylinder" componentType="cylinder" x="90" y="180" rotation="0" mirrored="false">
@@ -147,6 +150,23 @@ AMESim 介质定义继续使用普通的零端口 `Component`，不增加新的
 数值字段 `"mediumReferenceVersion": 1`；因此旧文档一经解析并重新保存，便
 不再依赖旧版启发式迁移。

+### AMESim 参数编码兼容
+
+早期 ReactFlow 工程和 System XML 没有 `amesimParameterEncodingVersion`，并对
+`MECMAS21.useFriction` 与 `MECMAS21.strib` 使用应用内部的 `0/1` 编码。读取这类
+旧数据时，`0` 映射为规范 AMESim 编码 `1`，`1` 映射为 `2`。旧 System XML
+发生转换时返回 `AMESIM_PARAMETER_ENCODING_MIGRATED` 语义层警告。
+
+版本字段缺失（ReactFlow JSON 中也包括显式 `null`）专用于识别上述旧数据；
+它不是当前客户端可省略的默认值。由于旧编码 `1` 与规范编码 `1` 含义相反，
+所有按当前组件目录创建或保存工程的客户端都必须写出数值版本字段 `1`，不能
+发送无版本的新数据。
+
+带有 `amesimParameterEncodingVersion="1"` 的 XML，以及顶层数值字段
+`"amesimParameterEncodingVersion": 1` 的 ReactFlow 工程，均已使用规范编码，
+不得再重解释其 `1/2` 值。新导出的 XML 与规范化后的工程数据始终写出版本 1，
+因此完成一次读取和保存后不再依赖旧编码迁移。
+
 ## 仿真模型编译接口

 `POST /api/reactflow/compile-model` 接收与工程保存、XML 导出相同的 ReactFlow 工程 JSON。它会执行以下操作：