114 lines
5.7 KiB
Markdown
114 lines
5.7 KiB
Markdown
# SystemSimulationApp
|
||
|
||
ReactFlow 系统建模与 `app.simulation` 仿真后端。
|
||
|
||
## 开发环境准备
|
||
|
||
后端统一使用 Python 3.12；仓库根目录的 `.python-version` 记录本轮参考补丁版本
|
||
`3.12.3`。`requirements.txt` 保留支持范围，
|
||
`constraints/python312-direct.txt` 固定应用直接依赖的参考版本。普通开发、性能复测和
|
||
CI 应同时使用两者，以避免同一代码在不同时间解析到不同的 NumPy、SciPy 或 Web
|
||
框架版本。
|
||
|
||
Windows：
|
||
|
||
```powershell
|
||
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：
|
||
|
||
```bash
|
||
python3.12 -m venv .venv
|
||
./.venv/bin/python -m pip install \
|
||
-r requirements.txt \
|
||
-c constraints/python312-direct.txt
|
||
./.venv/bin/python -m pip check
|
||
```
|
||
|
||
约束文件只固定代码直接导入或启动的 `fastapi`、`lxml`、`numpy`、`pydantic`、
|
||
`scipy` 和 `uvicorn`。`uvicorn[standard]` 的可选传递依赖包含平台差异，因此仍由 pip
|
||
按目标平台解析；这套方案固定求解器和接口层的主要版本，但不是带 wheel 哈希的逐位
|
||
相同发布锁。若要测试 `requirements.txt` 声明的兼容范围，可显式省略 `-c`，但这类
|
||
结果不应与受约束环境的性能数据直接比较。
|
||
|
||
升级参考版本时，应在干净的 Python 3.12 虚拟环境中同时安装范围文件和约束文件，
|
||
运行 `pip check` 与后端测试，再更新约束；不要从单个平台的 `pip freeze` 直接复制
|
||
所有传递依赖。
|
||
|
||
前端使用 Vite 8，需要 Node.js `20.19+` 或 `22.12+`。首次启动前安装前端依赖。
|
||
|
||
Windows（PowerShell，使用仓库内的便携 Node.js）：
|
||
|
||
```powershell
|
||
$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：
|
||
|
||
```bash
|
||
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
|
||
bat\start-all.bat
|
||
bat\start-backend.bat
|
||
bat\start-reactflow.bat
|
||
```
|
||
|
||
Linux：
|
||
|
||
```bash
|
||
./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` 会同时停止它们。
|
||
|
||
## 后端接口
|
||
|
||
- `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` 平衡，并使用 SciPy 完成非线性代数闭合和时间积分。XML 通用仿真当前采用半显式 ODE/代数 MVP：气瓶和贮箱作为储能元件，孔板及 XML 管段作为阻性元件，三通作为等压零结点，同时支持已登记的信号和机械基础件。它不是完整 DAE 或事件求解器，也不等价于严格 Modelica.Fluid 实现。
|
||
|
||
XML 解析依赖 `lxml` 执行本地 XSD 校验，该依赖已包含在 `requirements.txt` 中。
|
||
|
||
## 文档
|
||
|
||
- [开发文档索引](docs/README.md)
|
||
- [后端接口版本与定义规范 v1](docs/standard/backend-interface-version-spec-v1.md)
|
||
- [组件模型建模规范 v1](docs/standard/component-model-authoring-spec-v1.md)
|
||
- [组件库分类、发现与读取规范 v1](docs/standard/component-library-spec-v1.md)
|
||
- [组件目录 JSON Schema v1](schemas/component-catalog-v1.schema.json)
|
||
- [System XML v3 协议（当前规范）](docs/standard/system-xml-v3.md)
|
||
- [System XML v3 XSD（当前 Schema）](schemas/system-simulation-v3.xsd)
|