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

docs/system-xml-v2.md

@@ -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。它会执行以下操作：