# 开发文档索引

本目录是 SystemSimulationApp 协议和开发规范的统一入口。

跨 HTTP、组件目录、模型合同和 System XML 的版本边界统一见
[后端接口版本与定义规范 v1](backend-interface-version-spec-v1.md)。

## 更新记录

- [更新日志 2026-08-15](更新日志-2026-08-15.md)

## 模型开发

1. [组件模型建模规范 v1](component-model-authoring-spec-v1.md)
   用于创建或修改模型，包括端口、参数、结果、方程、版本、测试和 AI 修改协议。
2. [组件库分类、发现与读取规范 v1](component-library-spec-v1.md)
   用于理解组件库清单、自动发现、启动校验、目录接口和前端读取流程。
3. [组件目录 JSON Schema v1](../schemas/component-catalog-v1.schema.json)
   `GET /api/components/catalog` 的机器可读结构。
4. [AMESim 子模型公开组件迁移矩阵](amesim-component-migration-matrix.md)
   用于划分 `test_mql` 子模型族的公开组件、内部模型和暂不支持范围。
5. [AMESim 氦气 Peng-Robinson 介质模型](amesim-helium-peng-robinson.md)
   记录本地 AMESim 资料、氦气参数、索引映射和首版计算边界。

建议人工和 AI 先阅读建模规范，再阅读读取规范，然后参考目标分类中最接近的现有
模型。不要从前端兜底数据反推后端物理契约。

## System XML

- [System XML v3 协议（当前规范）](system-xml-v3.md)
- [System XML v3 XSD（当前 Schema）](../schemas/system-simulation-v3.xsd)

新增模型时，模型类和组件库清单是后端事实来源；System XML v3 只保存求解所需的
组件实例、模型版本、参数、连接和仿真设置。端口契约由注册模型恢复，画布位置、图标
方向等编辑信息只属于工程 JSON。XML 解析器不能自行创造模型端口或参数。

## 当前代码入口

| 目的 | 文件 |
| --- | --- |
| 组件基类 | [`app/simulation/core/base.py`](../app/simulation/core/base.py) |
| 端口契约 | [`app/simulation/core/ports.py`](../app/simulation/core/ports.py) |
| 参数与结果元数据 | [`app/simulation/core/metadata.py`](../app/simulation/core/metadata.py) |
| 库和显示声明 | [`app/simulation/core/catalog.py`](../app/simulation/core/catalog.py) |
| 库发现与注册校验 | [`app/simulation/registry.py`](../app/simulation/registry.py) |
| 临时库清单 | [`app/simulation/components/experimental/library.py`](../app/simulation/components/experimental/library.py) |
| AMESim 第一版公开临时库清单 | [`app/simulation/components/amesim/library.py`](../app/simulation/components/amesim/library.py) |
| `test_mql` 固定算例入口 | [`app/simulation/examples/test_mql/system.py`](../app/simulation/examples/test_mql/system.py) |
| 元件完整示例 | [`app/simulation/components/example.md`](../app/simulation/components/example.md) |
| System XML v3 解析与语义校验 | [`app/system_xml.py`](../app/system_xml.py) |
| System XML v3 XSD | [`schemas/system-simulation-v3.xsd`](../schemas/system-simulation-v3.xsd) |

## AI 使用原则

- 先读规范和相邻模型，再改代码。
- 只从 `library.py` 受控登记公开模型。
- 不在前端复制后端端口、参数或默认值作为正式来源。
- 不覆盖用户已有改动。
- 不自行猜测缺失的物理方程。
- 修改后运行针对性测试和完整回归，并报告未完成的验证。