lujingze/SystemSimulationApp
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

旧版前端工程文件导入时版本对比查验、审阅与仿真时部分阻挡功能实现；前端参数输入格式统一规范

Browse Source
This commit is contained in:
lujingze committed 2026-09-12 14:15:40 +00:00
1 parent 22579e51c9
commit 44b6ea74ab
32 files changed
+2087 -322
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/standard/component-library-spec-v1.md
+71 -59
View File
@@ -1,8 +1,12 @@
# 组件库分类、发现与读取规范 v1
状态：已在 `experimental` 临时组件库实施
适用范围：`app/simulation/components`、组件注册中心、System XML 和 React Flow 组件库
当前试验库：`experimental`（仅用于注册契约验证，不在前端组件库中显示）
文档版本：1.2.0
修订日期：2026-09-12
核对代码基线：`22579e5` 加本次输入合同实现；配套工程 JSON v2，XML v3 和模型版本不变。
状态：已在 `experimental` 与 `amesim` 组件库实施；本版按注册演练校正
适用范围：`app/simulation/components`、组件注册中心、System XML 和 React Flow 组件库
当前启用库：`experimental`（前端按库 ID 隐藏）、`amesim`（前端可见）。完整接入顺序见[新组件注册流程](component-registration-workflow-v1.md)，实际演练见[注册示例与验证](component-registration-example-v1.md)。
## 0. 文档定位
@@ -56,8 +60,7 @@ flowchart LR
E --> H["System XML 模型实例化"]
```
新增一个符合本规范的模型后，前端不应再修改 `App.tsx` 中的组件列表、参数列表
或分类列表。只有新增一种前端尚不支持的图形渲染方式时，才需要补充前端图标组件。
普通固定端口、已有参数编辑器和单位的模型由目录生成组件列表及参数面板，无需再复制型号定义。新图形、动态端口、新编辑器、新单位或物理域仍须补齐对应前端支持，见注册流程的条件修改表。上图只表示元数据发现；模型参与仿真还需原生发现、支持版本、方程生成及 C 模块链接。
## 2. 术语和层级
@@ -129,8 +132,7 @@ app/simulation/components/
- 参数名
- 结果变量名
标识符应使用 `snake_case`，只允许小写英文字母、数字和下划线，并以字母开头。
已有工程约定中的 `T`、`U` 等热力学变量可以保留。
库 ID、分类 ID、模型类型及端口名使用小写字母开头的小写字母、数字和下划线。参数和结果变量按成员标识符规则允许大小写字母，以字母开头，例如 `T0`、`T`、`U`；具体校验以注册器的标识符规则为准。
界面中文名称单独保存在 `label` 中。修改 `label` 不影响工程兼容性；修改机器标识
会影响工程文件、System XML、结果文件和后端注册，因此发布后不得直接改名。
@@ -144,7 +146,7 @@ LIBRARY_VERSION = "0.1.0"
MODEL_VERSION = "1.0.0"
```
版本遵循 `主版本.次版本.修订版本`：
版本遵循 `主版本.次版本.修订版本`（当前校验接受三段数字，不接受预发布或构建后缀）：
- 修订版本：只修复实现，不改变输入输出契约。
- 次版本：向后兼容地新增参数、结果或能力。
@@ -152,7 +154,7 @@ MODEL_VERSION = "1.0.0"
当前 System XML v3 要求每个 `Component` 显式保存 `modelVersion`，并与注册模型
版本完全一致；不一致时拒绝加载，不做静默升级。v3 不另存 `library`，而由全局唯一的
`Component/@type` 定位注册模型。旧模型的自动迁移仍未实现，需要另行提供显式规则。
`Component/@type` 定位注册模型。当前没有通用迁移框架；前端有部分型号专用迁移逻辑，不能推断新型号会自动迁移。
因此当前“修订/次版本向后兼容”只表示合同设计意图，不表示旧 XML 会被解析器自动
接受；任意模型版本变化都会使旧 XML 的精确版本检查失败。
@@ -241,17 +243,17 @@ class ExampleComponent(Component):
1. 构造函数调用 `super().__init__(name)`。
2. 使用 `set_parameter_values()` 保存所有规范化后的参数。
3. 使用 `register_declared_port()` 创建 `PORTS` 中声明的端口。
4. 组件级结果键必须与 `RESULT_VARIABLES` 完全一致。
4. 可见组件结果对应 `RESULT_VARIABLES` 中 `visible=True` 的项；端口结果对应活动端口的可见变量。
5. 所有内部计算均使用 SI 基准值。
6. 模型不能直接依赖 FastAPI、React Flow 或 XML DOM。
7. 模型的方程不能依赖图标方向、界面分类或画布位置。
完整方程示例参见
[`app/simulation/components/example.md`](../../app/simulation/components/example.md)。
[注册示例与验证](component-registration-example-v1.md)。
## 7. 界面显示声明
`DISPLAY` 只描述模型在前端的呈现，不参与物理求解：
`DISPLAY` 的图形、布局和分组描述前端呈现，不定义物理公式。例外是已实现的介质 `role`：前端及 XML 使用它做引用识别；后端网络另按介质定义基类判断，新增介质必须同步二者。普通显示声明示例：
```python
from app.simulation.core.catalog import (
@@ -319,6 +321,8 @@ PORTS = (
| `p` | effort | `equal` | `Pa` |
| `m_flow` | flow | `sumToZero` | `kg/s` |
| `h_outflow` | stream | `streamMix` | `J/kg` |
| `volume` | signal | `directed` | `m3` |
| `volume_flow` | signal | `directed` | `m3/s` |
气动端口统一约定 `m_flow > 0` 表示质量流入当前组件。`inlet`、`outlet` 是标称角色，
不应阻止反向流动；实际方向由求解结果中的流量符号决定。
@@ -362,15 +366,15 @@ PARAMETERS = (
- 用户输入可以使用其他公制单位，但提交后端前必须换算为 SI。
- 文本框编辑中的临时字符串不立即判错，失焦、回车或运行仿真时再执行数值校验。
后端不得静默忽略未知参数。缺少参数时可使用声明的默认值；出现未知参数时必须
后端不得静默忽略未知参数。Python 工厂可补齐声明默认值，XML 本身必须写全参数；出现未知参数时必须
返回包含组件 ID 和参数名的明确错误。
## 10. 结果变量规范
组件结果和端口结果分开管理：
- 组件结果来自 `RESULT_VARIABLES`。
- 端口结果根据 `PORTS` 中 `result_visible=True` 的端口变量自动生成。
- 组件结果来自 `RESULT_VARIABLES` 中 `visible=True` 的项。
- 端口结果根据活动端口中 `result_visible=True` 的变量自动生成。
- 求解器缓存、残差和调试量默认不进入用户结果。
每个结果变量必须提供：
@@ -451,6 +455,7 @@ def create(
```python
ENABLED_COMPONENT_LIBRARIES = (
"app.simulation.components.experimental.library:LIBRARY",
"app.simulation.components.amesim.library:LIBRARY",
)
```
@@ -464,6 +469,8 @@ ENABLED_COMPONENT_LIBRARIES = (
发现或校验失败时，FastAPI 应拒绝启动并给出库 ID、模型类型、字段和原因。
此启用列表仅控制注册中心。当前 `native_codegen/extended.py::catalog_contracts()` 另外显式读取两个内置库；新增第三个库必须同步该入口。`contracts.py::SUPPORTED_VERSIONS` 是独立的原生支持承诺，加入清单和支持版本后仍需实现状态、方程及输出映射。缓存不会替代这些接入步骤。
## 13. 启动校验规则
注册表完成前必须执行以下校验：
@@ -487,7 +494,7 @@ ENABLED_COMPONENT_LIBRARIES = (
### 13.3 端口
- 端口名在模型内唯一。
- 显示端口集合与物理端口集合完全一致。
- 显示端口集合与 `PORTS` 声明集合完全一致，包含物理端口与信号端口。
- 端口物理域、变量角色和连接规则有效。
- 实例实际注册的端口与静态声明一致。
@@ -503,8 +510,10 @@ ENABLED_COMPONENT_LIBRARIES = (
- 结果变量名在对应作用域内唯一。
- `quantity` 和单位有效。
- `component_result_values()` 的键与声明一致。
- 端口结果只来自声明为可见的端口变量。
- 检查组件结果声明的名称、物理量、单位和分类；启动时不执行数值求解。
- 端口结果只来自活动端口中声明为可见的变量。
Python `component_result_values()` 已移除。生成器须为 `result_variable_metadata()` 中全部可见键提供 C 输出映射；映射完整性和实际数值分别在原生生成、EXE 运行测试中验证，不应写成启动校验已覆盖。
## 14. 前端组件目录协议
@@ -578,10 +587,7 @@ GET /api/components/catalog
此类模型允许 `ports: []`，在 System XML v3 中仍按普通零端口
`Component` 保存；XML 不写任何 `Port` 快照，只保存模型版本和完整参数。
这些字段在目录对象中均为可选。宽松读取目录的消费者可以把未知编辑器参数
退化为普通数值输入；按本仓库 JSON Schema 严格校验的消费者必须与后端成套
升级，才能识别新增的 `editor` 值和 `options` 字段。正式前端必须依据目录字段
生成控件，不能硬编码具体 AMESim 模型名。
这些字段在目录对象中为可选，但 `editor` 值是受控枚举。注册器和 Schema 当前只支持上述三类；新增编辑器必须成套扩展元数据、校验和前端控件，不能将未知编辑器退化为普通输入作为正式支持。已有型号仍有专用动态端口/迁移逻辑，新增普通参数控件继续以目录为来源。
`property_model` 是每种介质组件内部的稳定选项编号，不等同于 AMESim 原始
`eosType`。例如空气组件的 `property_model=0` 表示理想气体，并映射到
@@ -620,9 +626,23 @@ cd F:\Master\SystemSimulationApp
只刷新浏览器无法让已运行的 Python 进程重新导入模型。前端源代码由 Vite 开发服务
热更新；普通目录内容变化不需要重启 Vite。
### 14.3 目录对象与工程快照不是同一协议
目录经 `normalizeComponentCatalog()` 转为前端模型定义；工程 JSON 经 `parseProjectPayload()` 校验后才与当前目录合并。后端能够从 JSON 生成合法 XML，不代表该 JSON 能被浏览器导入。 当前工程连线还必须有 `data.isContactEdge` 布尔字段，仅有两端点不足以通过浏览器解析。
例如目录中的信号端口可能含 `"positiveFlowDirection": null`，当前工程解析器仅接受该字段缺省或值为 `"intoComponent"`，因此信号端口快照应省略它：
```json
{"name":"out","kind":"signal","domain":"signal","nominalRole":"output","side":"right"}
```
人工或脚本生成工程应采用实际浏览器导出的结构，保留节点版本、按对应格式约定存储的参数、布局与真实连线端点；不要原样复制目录端口对象。物理供需规则仍来自注册表，快照不能覆盖它们。导入后检查模型、导出 XML、运行以及再次导出 JSON 都是必要验证。
当前前端要求所有显示端口恰好连接一次。后端独立信号算例可以只有未接端口警告，浏览器会将其视为运行前错误；网页验收须使用完整接线工程。
## 15. System XML 映射
System XML 中：
System XML 中的组件片段如下（仅演示字段结构；实际气瓶还须写全其余声明参数，不能直接将此片段作为有效最小算例）：
```xml
<Component
@@ -642,14 +662,14 @@ System XML 中：
- XML v3 不保存 `name/componentType/Port` 或画布布局；连接中的
`Endpoint/@port` 必须存在于模型的 `PORTS`。
介质定义组件不通过物理端口连接。编译器先收集目录角色为
`amesimGasMediumDefinition` 的零端口组件，再解析带
介质定义组件不通过物理端口连接。XML 和前端通过目录角色
`amesimGasMediumDefinition` 识别，网络构造则通过 `AmesimGasMediumDefinitionComponent` 基类识别并收集介质定义，再解析带
`editor="amesimGasReference"` 参数的组件引用；介质定义组件本身不进入数值
仿真网络。System XML 语义校验会在编译前检查介质索引的整数范围、定义唯一
性、正索引引用完整性，以及同一气动连通分量的引用一致性。
XML 解析器只负责结构、引用和契约校验；模型注册中心负责选择 Python 类并创建实例；
模型自身负责方程和状态。三层职责不得混合。
Python 模型负责声明与约束；原生生成器分配状态、生成方程和输出，公共 C 模块执行数值计算。目录注册不能替代原生实现。
## 16. 测试要求
@@ -673,24 +693,18 @@ XML 解析器只负责结构、引用和契约校验；模型注册中心负责
## 17. 新增模型操作清单
开发者新增模型时只执行以下步骤：
按[注册流程](component-registration-workflow-v1.md)执行以下步骤：
1. 在目标库的正确分类目录中新建模型文件。
2. 实现 `MODEL_TYPE`、`MODEL_VERSION`、`PORTS`、`PARAMETERS`、
`RESULT_VARIABLES` 和 `DISPLAY`。
3. 实现统一 `create()` 和模型方程。
4. 将模型类路径加入该库 `library.py` 的 `models`。
5. 添加模型单元测试和最小 XML/仿真测试。
6. 运行注册校验和完整测试。
7. 重启 FastAPI，刷新前端确认目录来源为“后端目录”。
1. 明确模型依据，列出参数、端口供需、状态、结果和支持边界。
2. 在目标库声明六个公共字段与类自身的 `create()`，校验默认值和参数边界。
3. 加入库清单；新库还需启用列表及原生 `catalog_contracts()` 入口。
4. 实现或复用 C 模块，新增导出函数时同步 `kernels.h`、`modules.py` 的导出及依赖。
5. 接入具体生成路径的状态、初始化、方程、输出、事件，核对求值依赖、雅可比与误差尺度；登记原生支持版本。
6. 完成独立数值对照、错误输入、最小完整网络、构建与缓存检查。
7. 重启后端，验证浏览器发现、编辑、导入导出、接线、运行、结果保存和 CSV；需要的新图形或交互能力同步实现。
8. 记录 Windows/Linux 的实际验证状态，交付接入说明与可复现实例。
正常情况下不需要修改：
- React Flow 左侧组件列表。
- 参数面板字段。
- System XML 模型类型分派代码。
- 结果变量关键词映射。
- 集中式模型工厂表。
普通型号通常不改通用 XML 分派、目录列表或参数面板字段；新协议、编辑器、单位及动态端口等按需修改。只通过目录和 XML 校验应标记“已注册”，不能标记“可求解”。
### 17.1 AI 修改约束
@@ -724,34 +738,26 @@ AI 不应仅因为某个 `.py` 文件位于组件目录，就假定它是公开
| 模型发现 | 已实现 | 按库清单受控发现 |
| 启动校验 | 已实现首版 | 覆盖版本、分类、端口、参数、单位和默认实例 |
| System XML 中的模型版本 | 已实现 | v3 显式保存并严格匹配 `modelVersion` |
| 工程 JSON 的整体版本 | 已实现 | 固定为 `projectSchemaVersion: 1`，节点显式锁定 `modelVersion` |
| 自动版本迁移 | 未实现 | 当前明确拒绝不匹配版本，本阶段不实现迁移 |
| 工程 JSON 的整体版本 | 已实现 | v2 统一所选单位语义，兼容读取 v1；节点保留来源版本并在兼容导出时更新 |
| 自动版本迁移 | 无通用框架，部分型号有前端专用迁移 | JSON 版本差异警告后生成当前 XML，XML 精确匹配；新型号明确语义兼容边界 |
| 目录 JSON Schema | 已实现 | `schemas/component-catalog-v1.schema.json` |
## 19. 推荐实施顺序
## 19. 维护与版本同步
1. 已完成：声明类型已放入独立的 `core/catalog.py`。
2. 已完成：`experimental/library.py` 已成为临时库唯一清单入口。
3. 已完成：五个公开模型自行声明 `DISPLAY` 和 `MODEL_VERSION`。
4. 已完成：公开模型统一实现 `create()`，集中式工厂函数已删除。
5. 已完成：注册表由库清单构建，并在导入时执行契约和默认实例校验。
6. 已完成：已增加组件目录 JSON Schema。
7. 已完成：System XML v3 保存并严格校验模型版本；工程 JSON 使用
`projectSchemaVersion: 1`，每个节点保存创建时的 `modelVersion`，当前不实现旧工程迁移。
8. 待完成：规范稳定后新建正式组件库，不再向 `experimental` 增加生产模型。
新增模型按第 17 节逐层验证，不再把“建立正式库”列为未来任务：`amesim` 已是启用的公开库。当前目录加载有缓存，修改 Python 声明、清单或原生发现代码后须重启服务。前端发布包有变更时须重新构建；仅刷新页面不会重新导入后端模块。
该顺序可以保证每一步都保持现有前端和 System XML 可用，不需要一次性重写模型、
解析器和界面。
模型版本修改时同时核对原生支持表、工程/XML 示例和兼容处理。原生内容缓存根据内容和构建环境失效，不以删除用户全部缓存作为新增模型的常规步骤。文档修订版本独立于库版本、模型版本、目录 schema 版本和工程格式版本。
## 20. 改动影响表
| 想做的改动 | 必须修改 | 通常不需要修改 |
| --- | --- | --- |
| 新增同库同分类模型 | 模型文件、`library.py/models`、测试 | 注册表、前端参数列表 |
| 新增同库同分类模型 | 模型声明、库清单、原生支持版本、代码生成及数值实现/复用、测试 | 注册中心启用表、普通前端参数列表 |
| 新增分类 | 库 `categories`、模型 `DISPLAY.category_id`、测试 | 物理端口和求解器 |
| 新增组件库 | 新库包和 `library.py`、启用列表、测试 | 已有库清单 |
| 新增组件库 | 新库包和清单、启用列表、原生 `catalog_contracts()`、逐型号数值接入和测试 | 已有库清单 |
| 修改参数默认值或范围 | 模型 `PARAMETERS`、测试、必要的版本 | 前端参数硬编码 |
| 修改端口 | 模型 `PORTS`、`DISPLAY.ports`、主版本、XML/网络拒绝边界测试 | 库分类 |
| 新增 C 导出函数/模块 | 数值模块、`kernels.h`、`modules.py` 导出/依赖、生成调用、适用的雅可比依赖与测试 | 前端分类 |
| 新增专用图标 | 模型 `DISPLAY.symbol`、前端图标渲染器 | 参数和物理方程 |
| 新增物理域 | 端口协议、网络、求解器、XML、前端兼容规则和测试 | 仅修改分类名称 |
| 修改目录响应结构 | 后端序列化、JSON Schema、前端解析、协议版本和测试 | 单个模型方程 |
@@ -762,12 +768,14 @@ AI 不应仅因为某个 `.py` 文件位于组件目录，就假定它是公开
| --- | --- |
| 模型完全没有出现在目录响应 | 模型类路径是否加入已启用库的 `models` |
| FastAPI 无法启动 | 启动错误中的库、模型和字段；通常是契约校验失败 |
| 接口有模型但前端没有 | `schemaVersion`、前端控制台、目录规范化错误 |
| 接口有模型但前端没有 | `schemaVersion`、目录规范化、库是否为隐藏的 `experimental` |
| 前端显示红色“加载失败” | 悬停状态查看详情，再检查 8000 端口、`/api/components/catalog`、后端是否重启 |
| 分类错误 | `DISPLAY.category_id` 与库 `categories` |
| 端口数量或位置错误 | `PORTS` 与 `DISPLAY.ports` 是否完全一致 |
| 参数面板缺字段 | 模型 `PARAMETERS` 和目录响应，不先改前端 |
| XML 报不支持类型 | XML `type` 是否精确匹配 `MODEL_TYPE` |
| 导入 JSON 失败但后端 XML 正常 | 工程解析器要求与目录对象的差异，尤其信号端口的 `null` 字段 |
| 目录可见但原生失败 | 原生发现入口、支持版本、C 输出映射和模块导出是否逐层齐全 |
| 图标是通用图形 | `symbol` 尚无专用前端渲染器，但模型仍应可用 |
最小诊断命令：
@@ -776,3 +784,7 @@ AI 不应仅因为某个 `.py` 文件位于组件目录，就假定它是公开
.\.venv-win\Scripts\python.exe -c "from app.simulation.registry import build_component_catalog; print(build_component_catalog())"
.\.venv-win\Scripts\python.exe -m unittest tests.test_component_registry tests.test_component_catalog
```
## 22. 本轮代码核对（2026-09-12）
1.1.1 修正了 DISPLAY 介质角色的实际用途、结果可见性和未知编辑器支持边界。工程存储/执行、HTTP/CLI 表达式和网页结果保存差异统一见[接口规范](backend-interface-version-spec-v1.md)，本规范不重复声明一套实现。