完善建模交互、组件图标与系统协议
This commit is contained in:
ljz committed
1 parent
456c29b3b6
commit
6572defaa4
66 files changed
+10067
-4163
No files matched your search
@@ -2,7 +2,7 @@
|
||||
|
||||
状态：已在 `experimental` 临时组件库实施
|
||||
适用范围：`app/simulation/components`、组件注册中心、System XML 和 React Flow 组件库
|
||||
当前试验库：`experimental`（界面名称：临时测试组件库）
|
||||
当前试验库：`experimental`（仅用于注册契约验证，不在前端组件库中显示）
|
||||
|
||||
## 0. 文档定位
|
||||
|
||||
@@ -150,8 +150,11 @@ MODEL_VERSION = "1.0.0"
|
||||
- 次版本：向后兼容地新增参数、结果或能力。
|
||||
- 主版本：端口、参数语义或方程发生不兼容变化。
|
||||
|
||||
当前 System XML v2 尚未保存模型版本。正式发布组件库前，应在 XML 中增加
|
||||
`library` 和 `modelVersion`，并提供旧工程迁移规则。
|
||||
当前 System XML v3 要求每个 `Component` 显式保存 `modelVersion`，并与注册模型
|
||||
版本完全一致；不一致时拒绝加载，不做静默升级。v3 不另存 `library`，而由全局唯一的
|
||||
`Component/@type` 定位注册模型。旧模型的自动迁移仍未实现，需要另行提供显式规则。
|
||||
因此当前“修订/次版本向后兼容”只表示合同设计意图，不表示旧 XML 会被解析器自动
|
||||
接受；任意模型版本变化都会使旧 XML 的精确版本检查失败。
|
||||
|
||||
## 5. 组件库清单
|
||||
|
||||
@@ -206,7 +209,7 @@ LIBRARY = ComponentLibrarySpec(
|
||||
- 启动错误能明确定位到具体库和模型。
|
||||
|
||||
当前 `experimental/library.py` 已按此格式声明库、分类和五个公开模型；
|
||||
`experimental/__init__.py` 只保留旧常量的兼容别名。
|
||||
`experimental/__init__.py` 只公开规范化的 `LIBRARY` 清单。
|
||||
|
||||
## 6. 模型类契约
|
||||
|
||||
@@ -572,8 +575,8 @@ GET /api/components/catalog
|
||||
一类目录数据，前端据此生成下拉栏；后续增加算法时由介质模型注册新的选项，
|
||||
前端不硬编码算法名称。
|
||||
- 模型的 `role: "amesimGasMediumDefinition"` 表示该模型是项目级介质定义。
|
||||
此类模型允许 `ports: []`，在 System XML v2 中仍按普通零端口
|
||||
`Component` 保存。
|
||||
此类模型允许 `ports: []`，在 System XML v3 中仍按普通零端口
|
||||
`Component` 保存；XML 不写任何 `Port` 快照，只保存模型版本和完整参数。
|
||||
|
||||
这些字段在目录对象中均为可选。宽松读取目录的消费者可以把未知编辑器参数
|
||||
退化为普通数值输入；按本仓库 JSON Schema 严格校验的消费者必须与后端成套
|
||||
@@ -586,8 +589,9 @@ GET /api/components/catalog
|
||||
Peng-Robinson，并映射到 `fluidType=12/eosType=6`。编译层负责保存这种映射，
|
||||
前端只使用目录选项。
|
||||
|
||||
当前前端保留内置兜底目录，用于后端未启动时继续打开工程。兜底只是一种开发期
|
||||
容错机制，不能成为新增模型的正式注册方式；正式环境应明确提示目录加载失败。
|
||||
前端不再维护内置兜底目录。后端目录不可用时，组件区保持为空，并在“组件库”
|
||||
标题旁显示红色“加载失败”状态；悬停或聚焦该状态可查看失败范围和详细原因。
|
||||
`experimental` 试验库即使由成功的目录响应返回，也不会出现在组件区。
|
||||
|
||||
### 14.1 前端实际读取步骤
|
||||
|
||||
@@ -599,12 +603,10 @@ React Flow 启动时：
|
||||
4. 检查模型 `type` 是否全局重复。
|
||||
5. 将参数数组转换为参数面板定义。
|
||||
6. 按库、分类和模型的 `order` 排序。
|
||||
7. 成功时显示“后端目录”。
|
||||
8. 请求或格式校验失败时显示“内置兜底”并使用开发期兜底目录。
|
||||
|
||||
前端兜底目录不保证包含新模型。新增公开模型后，只要 FastAPI 正常提供目录，前端
|
||||
就能读取；若要求后端离线时也显示新模型，才需要有意识地同步兜底定义。兜底定义
|
||||
仍不能成为端口、参数或默认值的权威来源。
|
||||
7. 过滤仅用于注册验证的 `experimental` 试验库。
|
||||
8. 成功时用绿色状态显示“已加载 X 个组件库”，不追加其他成功说明。
|
||||
9. 请求或格式校验失败时显示红色“加载失败”，不显示任何兜底组件；悬停状态可
|
||||
查看具体库名（目录响应可识别时）或受影响范围、接口地址与错误原因。
|
||||
|
||||
### 14.2 修改后如何生效
|
||||
|
||||
@@ -625,19 +627,20 @@ System XML 中：
|
||||
```xml
|
||||
<Component
|
||||
id="cylinder_1"
|
||||
name="cylinder_1"
|
||||
type="cylinder"
|
||||
componentType="cylinder">
|
||||
modelVersion="1.0.0">
|
||||
<Parameter name="volume" value="0.01"/>
|
||||
</Component>
|
||||
```
|
||||
|
||||
映射规则：
|
||||
|
||||
- `id`：工程内唯一的组件实例 ID。
|
||||
- `name`：用户可修改的组件实例名称。
|
||||
- `type`：必须匹配唯一的 `MODEL_TYPE`。
|
||||
- `componentType`：当前为兼容字段，应与 `type` 相同。
|
||||
- `<Port name>`：必须存在于模型的 `PORTS`。
|
||||
- `<Parameter name>`：必须存在于模型的 `PARAMETERS`。
|
||||
- `modelVersion`：必须与该模型当前 `MODEL_VERSION` 完全一致。
|
||||
- `<Parameter name>`：必须完整且只能来自模型的 `PARAMETERS`，数值使用 SI。
|
||||
- XML v3 不保存 `name/componentType/Port` 或画布布局；连接中的
|
||||
`Endpoint/@port` 必须存在于模型的 `PORTS`。
|
||||
|
||||
介质定义组件不通过物理端口连接。编译器先收集目录角色为
|
||||
`amesimGasMediumDefinition` 的零端口组件，再解析带
|
||||
@@ -720,7 +723,9 @@ AI 不应仅因为某个 `.py` 文件位于组件目录，就假定它是公开
|
||||
| 模型工厂 | 已实现 | 模型类统一 `create()` |
|
||||
| 模型发现 | 已实现 | 按库清单受控发现 |
|
||||
| 启动校验 | 已实现首版 | 覆盖版本、分类、端口、参数、单位和默认实例 |
|
||||
| XML/工程中的模型版本与迁移 | 未实现 | 正式库发布前补齐 |
|
||||
| System XML 中的模型版本 | 已实现 | v3 显式保存并严格匹配 `modelVersion` |
|
||||
| 工程 JSON 的整体版本 | 已实现 | 固定为 `projectSchemaVersion: 1`，节点显式锁定 `modelVersion` |
|
||||
| 自动版本迁移 | 未实现 | 当前明确拒绝不匹配版本，本阶段不实现迁移 |
|
||||
| 目录 JSON Schema | 已实现 | `schemas/component-catalog-v1.schema.json` |
|
||||
|
||||
## 19. 推荐实施顺序
|
||||
@@ -731,7 +736,8 @@ AI 不应仅因为某个 `.py` 文件位于组件目录，就假定它是公开
|
||||
4. 已完成：公开模型统一实现 `create()`，集中式工厂函数已删除。
|
||||
5. 已完成：注册表由库清单构建，并在导入时执行契约和默认实例校验。
|
||||
6. 已完成：已增加组件目录 JSON Schema。
|
||||
7. 待完成：在 System XML 和工程文件中保存模型版本，并设计迁移机制。
|
||||
7. 已完成：System XML v3 保存并严格校验模型版本；工程 JSON 使用
|
||||
`projectSchemaVersion: 1`，每个节点保存创建时的 `modelVersion`，当前不实现旧工程迁移。
|
||||
8. 待完成：规范稳定后新建正式组件库，不再向 `experimental` 增加生产模型。
|
||||
|
||||
该顺序可以保证每一步都保持现有前端和 System XML 可用，不需要一次性重写模型、
|
||||
@@ -745,7 +751,7 @@ AI 不应仅因为某个 `.py` 文件位于组件目录，就假定它是公开
|
||||
| 新增分类 | 库 `categories`、模型 `DISPLAY.category_id`、测试 | 物理端口和求解器 |
|
||||
| 新增组件库 | 新库包和 `library.py`、启用列表、测试 | 已有库清单 |
|
||||
| 修改参数默认值或范围 | 模型 `PARAMETERS`、测试、必要的版本 | 前端参数硬编码 |
|
||||
| 修改端口 | 模型 `PORTS`、`DISPLAY.ports`、XML/网络测试、版本迁移 | 库分类 |
|
||||
| 修改端口 | 模型 `PORTS`、`DISPLAY.ports`、主版本、XML/网络拒绝边界测试 | 库分类 |
|
||||
| 新增专用图标 | 模型 `DISPLAY.symbol`、前端图标渲染器 | 参数和物理方程 |
|
||||
| 新增物理域 | 端口协议、网络、求解器、XML、前端兼容规则和测试 | 仅修改分类名称 |
|
||||
| 修改目录响应结构 | 后端序列化、JSON Schema、前端解析、协议版本和测试 | 单个模型方程 |
|
||||
@@ -757,7 +763,7 @@ AI 不应仅因为某个 `.py` 文件位于组件目录，就假定它是公开
|
||||
| 模型完全没有出现在目录响应 | 模型类路径是否加入已启用库的 `models` |
|
||||
| FastAPI 无法启动 | 启动错误中的库、模型和字段；通常是契约校验失败 |
|
||||
| 接口有模型但前端没有 | `schemaVersion`、前端控制台、目录规范化错误 |
|
||||
| 前端显示“内置兜底” | 8000 端口、`/api/components/catalog`、后端是否重启 |
|
||||
| 前端显示红色“加载失败” | 悬停状态查看详情，再检查 8000 端口、`/api/components/catalog`、后端是否重启 |
|
||||
| 分类错误 | `DISPLAY.category_id` 与库 `categories` |
|
||||
| 端口数量或位置错误 | `PORTS` 与 `DISPLAY.ports` 是否完全一致 |
|
||||
| 参数面板缺字段 | 模型 `PARAMETERS` 和目录响应，不先改前端 |
|
||||
|
||||
Reference in new issue
Block a user