SystemSimulationApp

ReactFlow 系统建模与 app.simulation 仿真后端。

开发环境准备

Windows/Linux 的运行、测试、原生工具链及时间剖析依赖，统一见 平台依赖说明。2026-09-16 的 Jacobian 复用与剖析工具继续使用现有 SUNDIALS 7.4.0，本轮未新增运行库依赖；以下安装命令供准备环境时使用。

后端编排层统一使用 Python 3.12；仓库根目录的 .python-version 记录本轮参考补丁版本 3.12.3。requirements.txt 保留支持范围， constraints/python312-direct.txt 固定跨平台开发环境的直接依赖参考版本； constraints/python312-linux-x86_64.lock 则完整固定发布与 CI 所用的 Linux x86_64 wheel、全部传递依赖及其 SHA-256。

Windows：

py -3.12 -m venv .venv-win
.\.venv-win\Scripts\python.exe -m pip install `
  -r requirements.txt `
  -c constraints/python312-direct.txt
.\.venv-win\Scripts\python.exe -m pip check

Linux：

python3.12 -m venv .venv
./.venv/bin/python -m pip install \
  -r constraints/python312-linux-x86_64.lock
./.venv/bin/python -m pip check

Linux 发布锁仅适用于兼容 manylinux_2_28 的 Linux x86_64 和 CPython 3.12。它启用 --only-binary=:all: 与 --require-hashes，因此不会静默改用源码包或未审计 wheel； CI 和正式性能复测必须直接以 -r 安装该文件。Windows 或其他平台的开发环境继续 使用 requirements.txt 加 constraints/python312-direct.txt。若要测试 requirements.txt 声明的兼容范围，可显式省略约束，但这类结果不应与锁定环境的 性能数据直接比较。

升级参考版本时，应在干净的 Python 3.12 Linux x86_64 虚拟环境中解析范围文件， 仅下载兼容 wheel，逐个记录 wheel 的 SHA-256，再从空环境安装发布锁并运行 pip check、依赖契约测试与后端测试。不能只复制 pip freeze，因为它既不证明 依赖来源，也不校验安装产物。

前端使用 Vite 8，需要 Node.js 20.19+ 或 22.12+。首次启动前安装前端依赖。

Windows（PowerShell，使用仓库内的便携 Node.js）：

$nodeDir = Get-ChildItem .tools -Directory -Filter "node-*-win-x64" |
  Where-Object { (Test-Path "$($_.FullName)\node.exe") -and (Test-Path "$($_.FullName)\npm.cmd") } |
  Select-Object -First 1
& "$($nodeDir.FullName)\npm.cmd" --prefix frontend ci

Linux：

cd frontend
npm ci
cd ..

Windows 启动脚本会自动使用 .tools/node-*-win-x64 下兼容的便携 Node.js；Linux 启动脚本优先使用 .tools/node-*-linux-x64 下兼容的运行时（如果存在），否则使用 PATH 中的 node 和 npm。start-all.sh 需要 Bash 4.3 或更高版本。

启动项目

脚本统一存放在 bat/ 目录。三个入口分别用于同时启动、只启动后端、只启动前端。

Windows：

bat\start-all.bat
bat\start-backend.bat
bat\start-reactflow.bat

Linux：

./bat/start-all.sh
./bat/start-backend.sh
./bat/start-reactflow.sh

后端地址为 http://127.0.0.1:8000，前端地址为 http://127.0.0.1:5173。Windows 的 start-all.bat 会分别打开两个命令行窗口；Linux 的 start-all.sh 会在同一终端管理两个进程，按 Ctrl+C 会同时停止它们。

网页的 System XML 仿真默认使用 C 内核（native）；后端入口和启动脚本使用同一默认值，不需要每次手动设置环境变量。启动日志显示 Simulation numeric engine: native，启动预热仅检查 C 工具链和 XML Schema，不执行 Python/SciPy 求解器预热。模型专用 EXE 在提交模型时生成或从缓存复用。

当前 C 构建支持 Windows x64 和 Linux x86_64，已覆盖组件库当前注册的 27 类模型（22 类 Amesim、5 类实验组件）。具体公式范围与连接限制见原生后端说明；不支持的自定义模型或未收敛的连接会明确报错，不自动切回 Python。旧 Python 数值后端已删除；Linux 原生工具链安装与静态链接说明见 C 后端说明。旧固定拓扑示例接口返回 HTTP 410，请改用统一 XML 接口。

后端接口

• GET /api/components/catalog：返回组件库与模型版本、分类、图标键、端口布局和参数契约，供 ReactFlow 启动时自动加载。
• POST /api/reactflow/system-xml：导出精简的 System XML v3。
• POST /api/reactflow/compile-model：将 ReactFlow 节点、参数和连线编译为仿真网络，并返回组件端口、无方向物理连接、压力-流量方程结构及未连接端口。
• POST /api/reactflow/simulate-testmodel：运行现有固定拓扑 TestModel；该接口暂时不是任意拓扑求解器。
• POST /api/reactflow/simulate-test-mql：返回固定拓扑 AMESim test_mql 的结构与采样摘要；132 状态数值对比使用独立 comparison 入口。AMESim 子模型已有 19 个第一版公开模型，但该接口本身不是任意拖拽拓扑求解器。
• POST /api/system-xml/validate：接收原始 System XML v3，返回 XML、XSD 和模型语义三层诊断。
• POST /api/system-xml/parse：校验 XML，并返回可直接编译、求解的规范化模型数据；它不还原 ReactFlow 画布布局。
• POST /api/system-xml/compile-model：校验并解析 XML，然后创建 app.simulation 组件网络。
• POST /api/system-xml/simulate：按 XML 中的组件、连接、参数和仿真设置运行当前支持的气动、标量信号及一维机械网络 MVP，并返回组件及端口时间序列。
• POST /api/simulation-results/csv：校验结构化结果快照并导出 UTF-8 CSV 文件。

气动端口的后端契约采用 p 势变量相等、m_flow 流变量代数和为零、h_outflow 按 stream 规则混合。所有组件统一规定 m_flow > 0 表示流入组件，物理连接的端点顺序不表示流向。

当前网络层按端口域处理气动压力/流量与 stream 焓、标量信号传播，以及一维机械 x/v 等值和 f 平衡。默认 C 后端在生成的 EXE 内完成连接闭合、RK45/CVODE BDF 积分及信号/限位事件。通用仿真仍有已声明的拓扑和物理公式范围，并不等价于完整 Amesim 或 Modelica.Fluid 实现。

XML 解析依赖 lxml 执行本地 XSD 校验，该依赖已包含在 requirements.txt 中。

文档

• 开发文档索引
• 现行规范索引与新组件注册流程
• 后端接口版本与定义规范 v1
• 组件模型建模规范 v1
• 组件库分类、发现与读取规范 v1
• 组件目录 JSON Schema v1
• System XML v3 协议（当前规范）
• System XML v3 XSD（当前 Schema）

旧 Python 积分器、模型数值公式及物性缓存已移除。公共配置、进度和采样校验分别位于 app/simulation/config.py 与 sampling.py；模型 Python 文件仅保留参数、端口、结果和方程结构声明。质量/能量初值也由 C 计算。

后端运行依赖不再包含 NumPy/SciPy；运行测试请安装 requirements-test.txt。Windows C 回归需要配置 GCC 与 SUNDIALS，见 C 后端说明。删除范围和验证见 Python 数值实现退役记录。