# System XML v1 协议

System XML 是 ReactFlow 前端与 PythonModels 仿真层之间的稳定交换格式。

## 基本约定

- 根元素固定为 `System`，`schemaVersion` 固定为 `1`。
- `unitSystem` 固定为 `SI`。组件参数必须保存为 SI 基准值，界面显示单位不进入数值换算语义。
- 子元素顺序固定为 `Simulation`、`Components`、`Connections`。
- `Component.id` 是稳定的仿真实例 ID；`name` 是用户可编辑的显示名称。
- `Component.type` 是 PythonModels 模型类型；`componentType` 是前端组件类型。
- `Connection.source/target` 只标识图形拓扑端点，不代表仿真中的实际流动方向。正流和倒流由求解器决定。
- v1 文档不携带结果数据；仿真结果通过运行接口返回。

## 完整示例

```xml
<?xml version="1.0" encoding="UTF-8"?>
<System name="transfer-system" schemaVersion="1" unitSystem="SI">
  <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">
      <Port name="port_b"/>
      <Parameter name="volume" value="0.01"/>
      <Parameter name="p0" value="35000000"/>
      <Parameter name="T0" value="300"/>
    </Component>
    <Component id="tank_1" name="tank_1" type="tank" componentType="tank" x="420" y="180">
      <Port name="port_a"/>
      <Parameter name="volume" value="0.1"/>
      <Parameter name="p0" value="100000"/>
      <Parameter name="T0" value="300"/>
    </Component>
  </Components>
  <Connections>
    <Connection id="edge-1" source="cylinder_1" sourcePort="port_b" target="tank_1" targetPort="port_a"/>
  </Connections>
</System>
```

## Simulation

| 属性 | 类型 | 含义 | 约束 |
|---|---|---|---|
| `tStart` | double | 仿真起始时间，单位 s | 有限数 |
| `tStop` | double | 仿真结束时间，单位 s | 必须大于 `tStart` |
| `step` | double | 结果采样间隔，单位 s | 必须大于 0 |
| `maxStep` | double | 求解器最大积分步长，单位 s | 必须大于 0 |
| `method` | string | 求解器名称，例如 `BDF` | 非空 |

## Components

每个 `Component` 必须包含唯一 `id`、显示名称、模型类型、前端类型和画布坐标。组件下可以包含多个 `Port` 和 `Parameter`。

参数的 `value` 必须是可转换为有限浮点数的 SI 值。具体组件支持的端口、参数和取值范围由后续组件注册表协议约束。

## Connections

每个 `Connection` 必须包含唯一 `id` 和两个完整端点：

- `source` + `sourcePort`
- `target` + `targetPort`

端点中的组件 ID 必须存在，端口名称必须属于对应组件。v1 前端仍使用 source/target 组织连线，但仿真层必须将它们视为连接的两个端点，不得直接解释为固定物理流向。

## 版本兼容

- 解析器遇到缺少 `schemaVersion` 的旧 XML 时，应明确报告“旧协议”，不能静默当作 v1。
- v1 新增可选字段时必须保持旧解析器可忽略；删除字段或改变字段语义时必须升级主版本。
- XSD 只验证文档结构和基础数据类型。跨字段约束、组件端口规则和拓扑可求解性由仿真校验层负责。