同步仿真框架并接入AMESim气动组件

README.md

@@ -1,36 +1,37 @@
 # SystemSimulationApp
 
-本仓库用于把 Modelica 和 AMESim 系统模型迁移到可运行、可测试、可与原模型结果对比的 Python 仿真平台。
+ReactFlow 系统建模与 `app.simulation` 仿真后端。
 
-## 当前模型
+## 后端接口
 
-- `Testmodel`：旧 Modelica 迁移模型，已有可运行的 ODE 近似、结果导出和 OpenModelica 对比能力。
-- `test_mql`：当前开发主线，从 `AmesimModels/test_mql.ame` 迁移到 `PythonModels`。
+- `GET /api/components/catalog`：返回组件库与模型版本、分类、图标键、端口布局和参数契约，供 ReactFlow 启动时自动加载。
+- `POST /api/reactflow/system-xml`：导出 System XML v2。
+- `POST /api/reactflow/compile-model`：将 ReactFlow 节点、参数和连线编译为仿真网络，并返回组件端口、无方向物理连接、压力-流量方程结构及未连接端口。
+- `POST /api/reactflow/simulate-testmodel`：运行现有固定拓扑 TestModel；该接口暂时不是任意拓扑求解器。
+- `POST /api/reactflow/simulate-test-mql`：运行现有固定拓扑 AMESim `test_mql` 迁移模型；该接口不把 AMESim 子模型注册为公开拖拽组件。
+- `POST /api/system-xml/validate`：接收原始 System XML v2，返回 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 文件。
 
-`test_mql` 已完成 112 个气动状态和 20 个机械状态组成的 132 状态总闭包，可以短时积分并按 AMESim `Data_Path` 生成 comparison 报告。当前工作重点已经从拓扑接入转为数值校准；尚不能宣称 Python 结果与 AMESim 完全一致。
+气动端口的后端契约采用 `p` 势变量相等、`m_flow` 流变量代数和为零、`h_outflow` 按 stream 规则混合。所有组件统一规定 `m_flow > 0` 表示流入组件，物理连接的端点顺序不表示流向。
 
-## 目录
+当前网络层可以从组件和连接生成压力-流量残差，使用 SciPy 完成非线性代数闭合和时间积分，并按实际流向传播 stream 焓。XML 通用仿真当前采用半显式 ODE/代数 MVP：气瓶和贮箱作为储能元件，孔板及 XML 管段作为阻性元件，三通作为等压零结点。它不是完整 DAE 求解器，也不等价于严格 Modelica.Fluid 实现。
 
-- `AmesimModels/`：AMESim 源模型及模型级迁移说明。
-- `PythonModels/core/`：状态、网络、介质和求解器基础设施。
-- `PythonModels/components/`：气动、机械及通用组件方程。
-- `PythonModels/systems/`：系统装配、closure、snapshot、端口写回和 RHS。
-- `PythonModels/reporting/`：AMESim 结果读取、schema validation 和误差比较。
-- `PythonModels/scripts/`：仿真与 comparison 命令行入口。
-- `tests/`：组件、闭包、运行入口和回归测试。
+XML 解析依赖 `lxml` 执行本地 XSD 校验。安装或更新 Python 环境时使用：
 
-## 运行 test_mql
-
-运行默认的 132 状态短时域 AMESim 对比：
-
-```bash
-python3 -m PythonModels.scripts.run_test_mql_full_state_comparison
+```powershell
+.\.venv-win\Scripts\python.exe -m pip install -r requirements.txt
 ```
 
-运行全量测试：
+## 文档
 
-```bash
-python3 -m unittest discover -s tests -t .
-```
-
-详细迁移说明见 `AmesimModels/test_mql/README.md`，Python 平台说明见 `PythonModels/README.md`。本机开发恢复记录保存在根目录 `STATUS.md`；该文件被 `.git/info/exclude` 忽略，不会随正常提交推送。
+- [开发文档索引](docs/README.md)
+- [组件模型建模规范 v1](docs/component-model-authoring-spec-v1.md)
+- [组件库分类、发现与读取规范 v1](docs/component-library-spec-v1.md)
+- [组件目录 JSON Schema v1](schemas/component-catalog-v1.schema.json)
+- [System XML v2 协议](docs/system-xml-v2.md)
+- [System XML v2 XSD](schemas/system-simulation-v2.xsd)
+- [System XML v1 协议（旧版）](docs/system-xml-v1.md)
+- [System XML v1 XSD（旧版）](schemas/system-simulation-v1.xsd)