# 文件合同与当前代码依据

## 格式与单位

| 格式 | 当前合同 |
| --- | --- |
| 工程 JSON v2 | 新建/导出的编辑工程；数值、十进制数字字符串、表达式全部按 parameterUnits[name] 解释，省略单位使用目录 SI 单位 |
| 工程 JSON v1 | 兼容读取；普通数值/十进制数字字符串为 SI，表达式按显示单位解释 |
| System XML v3 | 根元素 schemaVersion="3" unitSystem="SI"，只保存执行模型 |

v2 的 p0: 2.5、"2.5"、"=2.5" 配 bar 都是 250000 Pa；20 degC 为 293.15 K。压力为绝压，不能自动加减大气压。缺失参数使用目录 SI 默认值，不随显示单位二次换算。

v1→v2 由前端 encodeProjectParameters() 等现有转换逻辑完成，不得只改版本号。内部归一化的 v1/SI 对象不是 v2 导出文件。未知型号、参数、单位不能靠改版本掩盖。

## 编辑工程字段

```text
projectSchemaVersion: 2
name: string
nodes[]:
  id: 唯一稳定 ID
  type: "simulationComponent"
  position: { x: 有限数值, y: 有限数值 }
  data:
    label, componentType, modelType, modelVersion
    ports[]: { name, kind, domain, nominalRole, side, positiveFlowDirection? }
    parameters: { 参数名: 数值或表达式字符串 }
    parameterUnits: { 参数名: 单位 }
    parameterScientificNotation: {}
    rotation: 0 | 90 | 180 | 270
    mirrored: boolean
edges[]:
  id, source, target, sourceHandle, targetHandle
  data: { isContactEdge: boolean, routePoints?: [{x,y}] }
simulation: { t_start, t_stop, step, max_step, method }
```

- 顶层禁止未知字段，假设与验收记录放独立报告。componentType/modelType 均用真实注册类型，显示标签不是模型标识。
- Handle 用真实端口名，不按画面编号猜测。普通连线 isContactEdge=false，接触连线由网页几何决定。
- 目录端口不能原样复制：信号端口 positiveFlowDirection:null 必须省略。生成器只复制必要快照字段；物理合同始终来自注册表。
- LMECHN1 保存完整 21 个注册端口快照；v1=N 决定 N 个右端口和 port_(N+1) 左参考端口。连通性只统计注册模型 active_ports() 返回的活动端口。
- 网页要求每个活动显示端口恰好连接一次，不能用后端对某些未接信号口的容忍替代网页检查，不能删快照端口绕过。
- 介质节点属于工程但不一定进入动态求解。gi=0 为内置空气；1..99 引用唯一介质定义。多介质不能重复套用默认 gi=1。
- 离散参数按目录 editor/options 数值编码，部分开关为 1/2，不能推定为 0/1。

## 执行与结果

step 是结果采样间隔，max_step 是内部最大步长。当前执行方法为 RK45/BDF；四个时间字段支持平台表达式。

JSON 适配层对不同/缺失组件版本警告并选择当前模型；类型、端口、未知参数和数值错误仍拒绝。LMECHN1/FORC 的显式兼容处理由平台完成，不能推广为任意迁移。新工程始终取当前版本。

XML 的组件需要精确 modelVersion 和完整 SI 参数，连接为两个 Endpoint(component,port)。JSON 导出器补齐默认参数，XML 解析器本身不猜默认值。XML parse 返回执行模型，不能直接作为可无损恢复布局的工程。

simulation_skill.py inspect 返回源哈希、版本、组件/连接/变量分页、诊断与未接端口；不是网页导入验收。默认页大小分别为 50/25/20，用 --component ID、--variable-query QUERY 和 offset/limit 定位。compiledForSimulation=false 的配置节点仍属于工程。

结果曲线按 key + componentId + quantity + unit 选择。separate 分图；overlay 仅叠加同单位且可比较的量；stacked 用于不同量。不能把固定参数当时间序列。

## 权威来源（相对仓库根目录）

- app/main.py：ReactFlowProjectPayload、JSON→XML、编译及 HTTP 接口。
- app/project_parameters.py、frontend/src/projectCompatibility.ts：版本、单位、表达式与兼容转换。
- app/simulation/registry.py、GET /api/components/catalog：型号、参数、端口、版本。
- frontend/src/App.tsx：parseProjectPayload、displayedPortsForNodeData、导入导出与网页检查。
- schemas/parameter-units.json、schemas/system-simulation-v3.xsd。
- docs/standard/backend-interface-version-spec-v1.md、component-library-spec-v1.md、port-computation-contract.md、system-xml-v3.md。

文档文件名 v1 不是工程版本。代码变更与说明不一致时核对解析器、注册表与测试。