旧版前端工程文件导入时版本对比查验、审阅与仿真时部分阻挡功能实现；前端参数输入格式统一规范
This commit is contained in:
lujingze committed
1 parent
22579e51c9
commit
44b6ea74ab
32 files changed
+2087
-322
No files matched your search
@@ -1,7 +1,9 @@
|
||||
# 后端接口版本与定义规范 v1
|
||||
|
||||
修订日期：2026-09-12；核对代码基线：`22579e5`。本版按代码补齐存储/执行、表达式、流式结果、浏览器保存和任务生命周期边界。
|
||||
|
||||
本文统一说明 SystemSimulationApp 后端的接口边界、版本编号和事实来源。规范版本为
|
||||
`1.0.0`。这个编号只表示本文档自身的修订版本，不等同于 HTTP API、System XML、
|
||||
`1.2.0`。这个编号只表示本文档自身的修订版本，不等同于 HTTP API、System XML、
|
||||
组件目录或单个模型的版本。
|
||||
|
||||
## 1. 当前版本基线
|
||||
@@ -17,7 +19,7 @@
|
||||
| System XML Schema | `3` | XML 校验、编译和仿真输入 | `schemas/system-simulation-v3.xsd` |
|
||||
| 组件库版本 | 各库独立 | 一个组件库的发布边界 | 各库 `library.py` 的 `version` |
|
||||
| 模型合同版本 | 各模型独立 | 单个 `MODEL_TYPE` 的物理和数据合同 | 模型类的 `MODEL_VERSION` |
|
||||
| ReactFlow 工程 JSON | `1` | 编辑器存档 | `projectSchemaVersion`、`ReactFlowProjectPayload` 和前端读取代码 |
|
||||
| ReactFlow 工程 JSON | `2`（兼容读 `1`） | 编辑器存档 | `projectSchemaVersion`、`ReactFlowProjectPayload` 和前端读取代码 |
|
||||
| 结果文件格式 | `1` | 前端导入、导出的结果快照 | `SimulationResultsView.tsx` |
|
||||
|
||||
因此，`schemaVersion=3` 只能说明文件是 System XML v3，不能说明“后端 API 是
|
||||
@@ -70,7 +72,7 @@ DISPLAY = ...
|
||||
- `PORTS` 定义端口名称、种类、物理域、名义角色、变量和连接规则；
|
||||
- `PARAMETERS` 定义 SI 单位、默认值、范围和离散选项；
|
||||
- `RESULT_VARIABLES` 定义结构化结果元数据；
|
||||
- `DISPLAY` 只定义前端展示，不得成为物理方程的隐式输入。
|
||||
- `DISPLAY` 中图形、布局、分组不定义物理方程；但 `role="amesimGasMediumDefinition"` 已用于前端及 XML 介质引用检查。网络构造还依据 `AmesimGasMediumDefinitionComponent` 的继承关系识别介质定义，不能只加 role 就得到介质能力。
|
||||
|
||||
物理流变量统一以进入组件为正。物理连接的两个端点无方向；信号方向由注册端口的
|
||||
`output/input` 合同决定。
|
||||
@@ -122,13 +124,13 @@ FastAPI 当前直接注册未版本化的 `/api/...` 路由，没有 `/api/v1`
|
||||
| --- | --- | --- |
|
||||
| `GET /api/components/catalog` | 无 | 组件目录 JSON v1 |
|
||||
| `GET /api/reactflow/projects` | 无 | 已保存工程摘要列表 |
|
||||
| `GET /api/reactflow/projects/{id}` | 工程 ID | 严格校验后的工程 JSON v1 |
|
||||
| `GET /api/reactflow/projects/{id}` | 工程 ID | 经 Pydantic 存储结构检查的原始 JSON；不保证可执行或可被浏览器导入 |
|
||||
| `POST /api/reactflow/projects/{id}` | `ReactFlowProjectPayload` | 保存摘要 |
|
||||
| `POST /api/reactflow/system-xml` | `ReactFlowProjectPayload` | `application/xml`，System XML v3 |
|
||||
| `POST /api/reactflow/compile-model` | `ReactFlowProjectPayload` | 编译网络 JSON |
|
||||
| `POST /api/reactflow/compile-model` | `ReactFlowProjectPayload` | 网络结构 JSON；不生成或编译 C |
|
||||
| `POST /api/system-xml/validate` | 原始 XML v3 | 三层校验报告 |
|
||||
| `POST /api/system-xml/parse` | 原始 XML v3 | 规范化执行模型 |
|
||||
| `POST /api/system-xml/compile-model` | 原始 XML v3 | 校验报告、设置和网络 |
|
||||
| `POST /api/system-xml/compile-model` | 原始 XML v3 | 校验报告、设置和网络；不生成或编译 C |
|
||||
| `POST /api/system-xml/simulate` | 原始 XML v3 | 同步仿真结果 |
|
||||
| `POST /api/system-xml/simulate-stream` | 原始 XML v3 | `application/x-ndjson` 事件流 |
|
||||
| `GET /api/system-xml/simulations/{id}` | 路径 ID | 任务快照 |
|
||||
@@ -143,6 +145,45 @@ OpenAPI，但当前多数 JSON 响应仍以 `dict[str, object]` 构造，XML、C
|
||||
也使用原始响应类型。因此 OpenAPI 目前不是完整的响应合同；代码、Schema 和合同测试
|
||||
仍是必要依据。
|
||||
|
||||
### 6.1 工程存储与执行入口
|
||||
|
||||
`ReactFlowProjectPayload` 顶层禁止未知字段，节点 data 和边 data 保留额外编辑元数据。存储不等同于执行校验：可保留缺失/不同的组件版本供查看。浏览器要求有效布局、端口对象与 `data.isContactEdge`；信号端口 `positiveFlowDirection: null` 仍应省略，这部分精简规则未改。
|
||||
|
||||
**工程 JSON v2**：参数数值、十进制数字字符串、数学表达式，全部按 `parameterUnits[name]` 指定的单位解释；缺省使用目录 SI 单位。缺失参数采用目录 SI 默认值，不随显示单位二次换算。例如单位选 `bar` 时，`2.5`、`"2.5"`、`"=2.5"`、`"2+0.5"` 均得到 `250000 Pa`。温度使用仿射换算，`20 degC = 293.15 K`；压力是绝压，不添加大气压偏移。
|
||||
|
||||
**旧工程 JSON v1**：为保持已有模型物理输入不变，普通数值/十进制数字字符串仍按 SI，表达式按显示单位解释。不可只把版本号 1 改成 2。浏览器兼容读取后提示旧规则，手工导出时将 SI 数字转换回所选单位，写出 v2。若某参数经过显示单位往返会改变浮点末位，则该参数改用 SI 单位导出并提示，保持求解输入逐值精确不变。编辑器内存、浏览器草稿/本地保存和结果快照继续使用内部 v1/SI 数字表示，不是新的外部 JSON v2。无法转换的未知组件/参数草稿保留 v1 和原版本，发出警告供修复，不丢字段。
|
||||
|
||||
| 入口 | 输入处理 | 数值执行边界 |
|
||||
| --- | --- | --- |
|
||||
| 网页参数面板与 JSON v2 | 数值与表达式均使用所选单位；导出 XML 前求值 | 完整、有限 SI 数值和当前模型版本 |
|
||||
| HTTP JSON→XML / compile-model | `prepare_project()` 共享表达式解析和单位换算，返回版本警告 | 严格数值化后调用原 XML/网络构造器 |
|
||||
| 原生 CLI JSON 输入 | 与 HTTP 复用 `prepare_project()`，警告写入 stderr | 同上；XML 输入仍不允许表达式 |
|
||||
| XML / 内部数值构造器 / C | 不接收显示单位或表达式；数字字符串也应在输入适配层转为数字 | 仅有限 SI 数值；版本与端口/参数合同严格校验 |
|
||||
|
||||
语法统一为有界算术 `+ - * / ^ **`、括号、科学计数法、常量 `pi/e`（不区分大小写）及函数 `sqrt abs sin cos tan asin acos atan exp ln log log10 min max pow`。幂右结合，`-2^2=-4`；`ln/log` 均是自然对数。最多 512 字符、256 词元/运算、32 层嵌套、16 个函数参数；禁止代码执行、未知变量、除零和非有限结果。离散编辑器参数只允许合法数值选项，不接受表达式。仿真时间设置同样可输入表达式，单位固定 s。
|
||||
|
||||
组件版本检查使用当前目录内存索引，导入时集中提示；运行/生成 XML 时再次警告，单纯版本不同或缺失不阻止执行。组件缺失、类型冲突、端口不兼容、未知参数、非法数值仍阻止执行。浏览器导出 JSON 时，只有通过组件兼容与参数校验的节点更新为当前版本；未通过者保留原版本。该过程不是旧方程的复现，也不能证明物理语义兼容，警告须明确可能失败或结果与实际不符。
|
||||
|
||||
HTTP XML 导出在 `X-Component-Version-Warnings` 返回 URL 编码 JSON（代码、说明、总数、最多前 10 个组件，头部限制 3800 字节）；compile-model 在响应 `warnings` 中返回完整清单。没有版本差异时无需该响应头。
|
||||
|
||||
参数单位换算表唯一来源为 [`schemas/parameter-units.json`](../../schemas/parameter-units.json)，网页和 Python 共用；表达式语法用跨语言同一组用例验收。
|
||||
|
||||
### 6.2 流式结果、保存与 CSV
|
||||
|
||||
C 程序把结果写为 JSON。数值数组使用 Ryu 的 binary64 往返编码，结合缓冲写出；流式路径附带字节索引，Python 读取较小元数据并直接拼接 series 字节，避免将全部曲线转成 Python 浮点列表再编码。HTTP 数据仍是普通 JSON 数组，没有改成二进制数组协议。
|
||||
|
||||
`simulate-stream` 的心跳是带 `heartbeat: true` 的 `event="progress"`，队列无消息时约每 5 秒发送；最终事件为 `result` 或 `error`。一个 NDJSON 事件可能分成多段字节 yield，消费者须按换行组装，不能按 HTTP chunk 一段一对象处理。同步 `/simulate` 默认仍物化完整曲线；任务 GET 遇到保留的原生 series 会以分段 JSON 返回，外部对象结构相同。
|
||||
|
||||
正式网页在接收和解析后将结果交给界面，`resultPersistence.ts` 再异步把曲线打包为 Float64Array 写入 IndexedDB，事务完成后才发布 sessionStorage 指针。因此“结果可查看”“浏览器持久化完成”和“下载文件保存”是不同事件。`.simresult` 仍通过 JSON 编码保存；不能把数值往返精度等同于所有导出文本逐字节一致。
|
||||
|
||||
网页 CSV 由 `resultCsvExport.ts` 向 Web Worker 分块传输数据并生成 Blob，默认不调用仍保留的 `/api/simulation-results/csv`。列顺序来自结果元数据，数值使用原始 SI，与图表显示单位分开；后端 CSV 接口为另一个可用入口。普通网页只能知道已生成 Blob/触发下载，无法通用地确认操作系统已将文件落盘，自动化测量需要额外下载完成信号。
|
||||
|
||||
### 6.3 任务生命周期
|
||||
|
||||
流式接口接受可选 `X-Simulation-Id`，省略时生成 ID，并在响应头返回。状态、取消标志与最终结果保存在当前 Python 进程内存中；服务重启即丢失，不是持久任务队列。终态任务超过 600 秒后，在注册新任务时清理，不是精确到时删除。取消 reason 为 `user/stalled`，断开事件流会请求 `stalled` 取消。
|
||||
|
||||
原生执行默认超时 300 秒；C 可返回部分结果，进程超过时限再加 5 秒，或收到取消后 5 秒仍未退出，Python 才强制结束并报错。不能把所有取消都承诺为立即终止且一定有完整结果文件。
|
||||
|
||||
## 7. 数据命名、单位和错误
|
||||
|
||||
- XML 属性和目录 JSON 主要使用 `camelCase`；
|
||||
@@ -205,14 +246,12 @@ System XML 校验问题统一包含：
|
||||
- 不对不匹配的 `modelVersion` 做自动升级；
|
||||
- 旧版本值只用于验证“不受支持输入应被拒绝”的边界测试。
|
||||
|
||||
ReactFlow 工程 JSON 只接受 `projectSchemaVersion: 1` 的当前结构，每个节点必须保存
|
||||
目录给出的 `modelVersion`。执行、编译和 XML 导出前会再次核对节点版本；缺失或不匹配
|
||||
时明确拒绝，不能先补当前默认参数再冒充当前模型。字符串端口、缺失连接 Handle 或
|
||||
已经删除的兼容标记也不会被猜测、补齐或迁移；以后确有升级需求时再为新的工程版本
|
||||
单独设计迁移器。
|
||||
ReactFlow 工程 JSON 接受 v1/v2，导出使用 v2 的统一单位规则。输入适配层允许版本警告后选择当前模型，内部执行 XML 仍精确匹配。LMECHN1/FORC 的既有显式迁移由网页和 Python 输入层对齐；PNVO 的布局兼容留在网页。不得把一般版本提示解释为自动保留旧模型的物理语义。
|
||||
|
||||
工程结构解析先于目录恢复。当前信号端口的 `positiveFlowDirection` 应缺省，不能从目录复制 `null`；连线须有 `data.isContactEdge` 布尔字段。后端请求模型接受的数据不一定通过前端 `parseProjectPayload()`，应使用实际浏览器导出的结构并验证往返，见[目录与工程协议](component-library-spec-v1.md)。旧 XML v1/v2 不属于上述型号专用处理的范围。
|
||||
|
||||
MECMAS21 的 `useFriction`、`strib` 等 AMESim 选项统一使用目录声明的原生编码：
|
||||
`1` 表示“否/禁用”，`2` 表示“是/启用”。工程 JSON v1、组件目录、System XML v3
|
||||
`1` 表示“否/禁用”，`2` 表示“是/启用”。工程 JSON v1/v2、组件目录、System XML v3
|
||||
和模型构造器不再接受或自动换算旧的 `0/1` 编码，也不再使用
|
||||
`amesimParameterEncodingVersion` 触发猜测式转换。
|
||||
|
||||
@@ -226,3 +265,7 @@ MECMAS21 的 `useFriction`、`strib` 等 AMESim 选项统一使用目录声明
|
||||
4. 更新当前规范和示例；
|
||||
5. 增加请求、响应、拒绝边界和前后端联调测试；
|
||||
6. 明确说明未实现的兼容或迁移能力。
|
||||
|
||||
## 2026-09-12 / 1.2.0 修订
|
||||
|
||||
实现工程组件版本警告、外部 JSON v2 一致单位语义、网页/HTTP/CLI 表达式归一化；XML v3、数值内核模型版本与求解精度未改变。验收记录见 `docs/other/2026-09-12-project-contract-acceptance.md`。
|
||||
Reference in new issue
Block a user