SystemSimulationApp/docs/update-log/更新日志-2026-08-15.md

更新日志 2026-08-15

记录范围

本文记录 model-development 分支截至 2026-08-15 的当前未提交工作区改动。范围包括前端建模交互、组件图标与参数驱动布局、后端模型合同、求解与采样安全、工程 JSON、System XML v3、文档、Schema 和自动化测试。

重点摘要

• 建模区完成框选纠正、待放置式粘贴、纵向滚轮平移、双向滚动条、接触边去交互化和端口显示重构。
• 仿真控制台改为停靠在图形建模区底部，可折叠、调高并在折叠状态显示摘要。
• 组件库固定使用图标模式，移除前端兜底测试库，增加明确的加载成功/失败状态。
• LMECHN1 改为 1～20 个动态右侧端口，默认 2 个，并同步更新图标、编号、连接、迁移和求解合同。
• FORC 的力方向改为显式参数，不再由图标旋转或镜像改变物理符号。
• MECMAS21 默认改为启用摩擦并使用理想限位，图标根据摩擦和限位参数显示四种外观。
• System XML 升级为 v3；ReactFlow 工程 JSON 固定为 projectSchemaVersion: 1，组件实例增加严格的 modelVersion 合同。
• 增加采样点数量、浮点时间精度、物理岛、端口基数和模型版本等安全检查。

前端建模与交互

选择与框选

• 框选过程改为按组件实际图标包络同步纠正 React Flow 内部选择状态，而不是依赖透明节点外框。
• 框选区域缩回图标包络之外时立即取消误选，消除“没有框到却仍被选中”和一帧选中闪烁。
• 框选结束、取消、自动平移和视口变化后会复核并清理选择矩形状态。
• 批量选择结束后只保留各组件自身的虚线选中框，不保留整体选择矩形。
• 从组件库拖入的新组件会成为唯一选中项，后续复制、旋转、镜像等操作不会继续作用于旧选择。

复制与待放置粘贴

• Ctrl+V 不再立即把副本写入工程，而是进入跟随鼠标的待放置预览状态。
• 待放置状态支持：
  • 左键确认位置；
  • 中键单击旋转；
  • Esc 取消；
  • 普通滚轮平移、Ctrl+滚轮 缩放、中键拖动画布和拖动滚动条。
• 待放置期间会锁定撤销、重做、再次粘贴、属性修改、组件库拖入、工程加载和视图切换等会改变模型的操作。
• 多组件副本会连同内部连线一起预览和落地。
• 节点和边 ID 在生成副本时会避让当前工程中的既有 ID；修复复制已连接的同类型组件时副本复用旧 ID、覆盖预览并最终移动原组件的问题。
• 提交待放置内容前再次执行重复 ID 防御检查。

端口、连线与吸附

• 自动接触吸附采用双下限：低倍缩放至少保留 10px 屏幕判定范围，高倍缩放至少保留 10 个画布单位；解决放大后半径被换算得过小、并与 18 单位网格叠加后端口难以对接的问题，同时避免缩小时退化成约 1px 的命中范围。
• 一次拖动可匹配同一落点内的全部兼容端口，并按距离和端口合同进行确定性配对。
• 已连接端口统一隐藏、禁止指针事件且不可再次发起连接；前端信号端口不再提供扇出入口。
• 物理端口可见层改为真实 SVG 圆形；信号端口使用 SVG 圆角矩形，避免非整数缩放时 CSS 圆角端口显示成不同椭圆。
• 可见端口图形以 6×6 为基准并随画布同比缩放；物理圆形横纵缩放保持一致。
• 可见图形与 Handle 命中层解耦，外层继续保留约 15×15px 的操作热区，缩小画面后仍便于连接。
• isContactEdge 成为工程边的显式字段；完全重合的接触边不绘制路径、不提供按钮、焦点、点击或框选入口。
• 删除接触边端点的透明圆形保护层，避免保护层覆盖 PNCH012 等小型多端口元件的主体选择区域。
• 普通可见连线仍保留中段选择和删除能力；点击节点、画布或普通边会清理残留的端口连接状态。
• 加载工程时以当前目录端口合同为准，删除、重复占用、类型不兼容或当前参数下未启用的端口连接会被逐条丢弃并报告原因。

画布导航

• 普通鼠标滚轮改为纵向平移建模画布。
• Ctrl+滚轮 保留缩放；中键拖动画布平移行为保持不变。
• 建模区新增底部水平滚动条和右侧垂直滚动条，滚动条、React Flow 视口和键盘滚动操作双向同步。
• 滚动条使用窄轨道，在保证可点击的同时尽量减少对建模区域的占用。
• 移除建模区左下角 React Flow 放大、缩小、适配和锁定按钮。
• 隐藏建模区和结果系统图右下角的 React Flow 水印。

仿真控制台

• 新增 DockedSimulationConsole，控制台只占用中央图形建模区底部，不再横跨模型库和参数栏。
• 支持鼠标拖拽和键盘调整高度，双击分隔条恢复默认高度；高度写入本地存储。
• 折叠后只保留约 40px 标题栏和最后一条日志/进度摘要。
• 折叠状态收到新日志或仿真进度时只更新摘要，不再自动展开完整控制台。
• 保留仿真进度、停止、清空、XML 日志和普通日志功能。
• 控制台不再记录拖入组件、手动连接、自动吸附、拖开接触连接、全选、网格显示和适配画布等低价值建模噪声；继续保留仿真、检查、XML、复制粘贴、撤销重做、旋转镜像、删除、保存加载及重要迁移警告。
• 控制台文本选择使用浏览器原生复制，不再触发画布组件复制快捷键。
• 旧浮动控制台代码暂由功能开关保留，便于对基础版本进行回退审阅。

组件库

• 组件库固定使用图标卡片模式，删除图标/列表切换按钮、列表元信息、本地显示模式设置和相关残留代码。
• 图标卡片保持固定尺寸，保留名称截断、悬停完整名称和放大预览。
• 字体层级调整为：组件库标题 16px、库分组 14px、类别分组 12px。
• 成功状态只显示“已加载 X 个组件库”和绿色状态标记。
• 加载失败时不再显示前端临时测试兜底库，组件区域保持为空并显示红色状态。
• 失败状态支持悬停或键盘聚焦查看详细原因；能识别目录中具体失败的组件库时直接显示其名称。
• experimental 临时测试库无论目录加载成功还是失败都不会出现在组件库中。
• 从组件库拖拽时使用工作区 viewBox、实际节点尺寸和当前缩放生成待拖入图像，避免落地前后图标形状或大小跳变。

参数、工程与结果页

• 只有一个固定选项的 choice 参数不再显示，避免出现没有实际选择价值的参数行。
• LMECHN1 右侧端口数执行 1..20 整数校验；超过上限时显示“右侧端口数量不能超过20”。
• LMECHN1 缩减端口数前会检查即将隐藏的端口是否仍连接；参考端口编号变化时迁移已有参考连接。
• 参数表、模型检查和 XML 导出共用模型合同与参数验证。
• XML 数值输出使用可往返的双精度文本，减少格式化造成的物理输入精度损失。
• 缺失或不匹配 modelVersion 的工程仍可加载检查，但组件显示合同警告，且不能通过模型检查、生成 XML 或运行仿真。
• 仿真结果快照同步要求工程 Schema、节点模型版本、端口结构和 isContactEdge 合同；结果系统图复用新的端口图形。
• 结果页容器尺寸变化时重新约束上下窗格布局，避免控制台或工作区尺寸变化造成裁切。

组件图标与模型合同

图标布局基础设施

• 组件图标布局可根据参数动态返回 viewBox、工作区画布、节点尺寸和端口锚点。
• 图标渲染器新增 palette/canvas 场景，使组件库固定缩略图与工作区动态图标能够分别定义。
• 删除旧 legacyPortAnchors 映射，端口布局、连接、吸附和 XML 导出统一使用组件目录及当前注册图标合同。

LMECHN1 动态线性机械节点

• 模型版本由 0.1.0 升级到 0.2.0。
• 默认右侧端口数由 8 改为 2，允许范围扩展为 1～20。
• 目录注册 port_1～port_21；当 v1=N 时，显示 N 个右侧端口，并把 port_{N+1} 作为左侧参考端口。
• 工作区使用 custom 动态画布：端口数量增加时纵向扩展，改变数量时尽量保持元件中心不动。
• 默认 2 个右侧端口时节点约为 148×96px；20 个右侧端口时高度约为 534px。
• 主框线宽为 2.5px；引线和小连接框线宽为 1.5px；连接框约为 6×5，引线与连接框保持同轴。
• 组件库固定显示 5 个右侧引脚和 1 个左侧参考引脚，占组件库画布 90%，不受工作区参数影响。
• 端口编号随数量更新；20 个右侧端口时保持单列，旋转后保持单行且不重叠。
• “节点求和模式”后端仍保留唯一标准模式合同，前端隐藏该无效配置行。
• 旧 0.1.0 工程中的固定参考端口 port_9 可按 v1 迁移为动态参考端口，并将 sum 规范化为标准值。
• 求解层只要求活动端口 port_1..port_{N+1} 连接；活动端口位移、速度相等，力代数和为零。
• 未启用的预留端口增加 x/v/f=0 约束，避免其参与当前节点计算或造成方程欠定。

PNRP17 图标

• 按参考图重绘上部壳体、上下左侧填充壁面、下部基座、活塞套、活塞面、水平活塞杆和接口引线。
• 左侧壳体补充参考图中的实心壁面。
• 上下两组左右箭头复用同一几何，右箭头由镜像生成，确保大小和形状完全一致。
• 箭头尖端分别触碰左侧壁面和活塞壁面。
• 两侧箭杆各等量延长 1.8 个逻辑单位，中间仍保留约 2.4 个逻辑单位的空隙，与参考图比例一致。
• 主轮廓线宽调整为 2.1px，箭头等细节调整为 1.9px。
• 使用约 1.21 的纵向比例修正整体外观；保持 standard 尺寸档位和约 132×112px 节点尺寸。
• 端口排列调整为：左侧 port_3/port_2、右侧 port_4/port_5、底部 port_1；锚点随最终几何同步更新。
• 忽略参考截图中的绿色接口提示像素，并保证引线不会被端口图标完全遮挡。

PN3NODE2 与 P4NODE2 图标

• 两个节点均调整为 small 工作区画布，图形最长边占方形 viewBox 的 40%。
• 按参考图改为直线汇流结构：上下、右侧及端口外露引线使用 1.5px 细线，中心汇流支路使用 4px 粗线。
• 粗汇流支路显式绑定 port_2，固定显示在左侧；PN3NODE2 的其余端口位于上、下方，P4NODE2 的其余端口位于上、右、下方。
• 中心使用与粗线比例一致的实心洋红圆点，颜色统一为 #8b134f。
• 删除 SVG 内重复绘制的端口小圆，端口图形由统一的 React Flow Handle 负责；外露细引线在 Handle 覆盖后仍保持可见。

PNL00R 与 PNL0001～PNL0003 图标

• 四个管路元件统一使用 standard 工作区画布，节点尺寸统一为约 132×112px。
• 图形以画布中心等比缩放，最长边占 64×64 方形 viewBox 的 60%。
• 左右接口锚点随图形同步收拢，引线在端口图标覆盖后仍保留可见长度。
• 组件库继续按 standard 档位的独立缩略图规则显示，不受工作区 60% 占比影响。

MECMAS21 图标与默认状态

• useFriction 默认值由 1 改为 2，即默认启用摩擦。
• stoptype 默认值由 4 改为 1，即默认使用理想限位。
• 新拖入元件和组件库缩略图默认显示“有摩擦、有末端约束”外观。
• 根据摩擦与限位参数显示四种图标：有摩擦有约束、有摩擦无限位、无摩擦有约束、无摩擦无限位。
• 参数切换只改变摩擦、导轨和限位区域，核心滑块、节点尺寸和选择包络保持一致。
• 滑块主轮廓继续使用 2.5px 最终线宽。

LSTP00A 图标

• 按参考图重绘左右接口框、三条竖向导轨、上部弹性曲线和下部机械连接结构。
• 使用 standard 画布和约 65% 的工作区占比；组件库按 standard 档位显示 90%。
• 图标颜色为 #00af00，工作区线宽统一为 3px。
• 左右引线延伸到接口 Handle 内侧后仍保持可见，节点包络基本为正方形。

FORC 力源

• 模型版本由 0.1.0 升级为 0.2.0。
• 新增显式 direction 参数：1 为正向，-1 为反向。
• 删除图标旋转或镜像改变求解力符号的布局耦合；旋转和镜像只影响显示。
• 旧版 FORC 工程在前端定向迁移时补充正向参数和当前模型版本。

后端求解与安全性

组件与网络合同

• 为组件增加 required_connection_ports：默认要求全部物理端口连接，动态组件可只声明当前活动端口。
• 禁止同一组件的任意两个端口互相连接。
• 每个信号输入只允许一个驱动源。
• 后端和 System XML 仍支持一个信号输出连接多个输入；当前前端 UI 采用更严格的一端口一连接策略，不提供信号扇出。
• 物理岛检查只遍历物理组件与物理连接，信号连线不再错误合并独立物理岛。
• 可识别通过同一信号源控制、但自身缺少动态储能锚点的物理孤岛。

仿真采样安全

• 新增稳定的采样时间错误类型与错误码合同。
• 采样网格在分配数组前检查起止时间、跨度、步长和派生数量是否有限且可表示。
• 采样步长必须大于零；最多允许 10001 个采样点。
• 极小步长、整数转换溢出和浮点精度不足以推进绝对时间的情况会被提前拒绝。
• 采样序列保证同时包含起止时间、至少两个点且严格递增。
• System XML 语义校验会提前调用同一采样检查，不安全输入不会进入积分器。

工程 JSON v1

• ReactFlow 工程顶层增加必填 projectSchemaVersion: 1。
• 每个节点保存 modelVersion；执行前必须与组件目录当前模型版本完全一致。
• componentType、modelType 与注册模型类型必须一致。
• 端口必须保存为结构化对象，不再从旧字符串端口猜测合同。
• 工程边必须保存布尔值 data.isContactEdge。
• 参数显示单位、科学计数法原始文本和未来展示元数据继续参与工程持久化。
• 后端严格校验工程 JSON v1；损坏数据和不支持的版本返回 422。
• 删除并拒绝旧兼容标记：
  • mediumReferenceVersion；
  • amesimParameterEncodingVersion；
  • presentationLayoutVersion。

System XML v3

• System XML v3 成为当前唯一支持的求解协议，并新增 schemas/system-simulation-v3.xsd 与 docs/system-xml-v3.md。
• 删除 v1/v2 XSD 和协议文档，不再自动识别或迁移旧 XML。
• 根节点固定 schemaVersion="3" 和 unitSystem="SI"。
• Simulation/@step 更名为 sampleStep。
• 组件只保存 id、type、必填 modelVersion 和完整 SI 参数。
• 连接只保存可选 id 及两个 (component, port) 端点。
• 坐标、旋转、镜像、显示名、端口快照、连接 kind/domain 和端点 role 等编辑器数据不再进入 XML。
• 端口种类、物理域、信号方向和变量合同统一从组件注册表恢复。
• v3 语义校验覆盖模型版本、参数完整性与范围、重复 ID/端点、组件自连、端口存在性、端口域、信号方向、信号输入多驱动和物理端口重复连接。
• /api/system-xml/parse 返回编辑器无关的执行 model，不再返回 ReactFlow 工程。
• XML 可直接编译为公共 SolverModelInput；ReactFlow JSON 与 XML 共用网络编译入口。
• JSON→XML 导出会补齐注册默认参数、写出当前完整参数、剔除编辑器字段，并在返回前再次执行 XSD 与语义校验。

兼容性与破坏性变更

• System XML v1/v2 文件必须由来源端重新导出 v3，不能只修改版本号。
• 旧 XML 的 step 必须改为 sampleStep，并为每个组件补齐当前 modelVersion 和完整注册参数。
• /api/system-xml/parse 的响应从 ReactFlow project 改为执行 model，调用方必须适配。
• 严格模型版本检查会拒绝未迁移的 FORC 0.1.0 和 LMECHN1 0.1.0 执行文件。
• MECMAS21 不再把旧 0/1 编码静默转换成 AMESim 原生 1/2；旧工程需要明确迁移。
• 介质引用不再猜测旧格式：缺失介质定义时不会把 gi=1 自动映射为内置空气，XML 缺失 gi 或 property_model 时不会自动补值。
• 缺少 projectSchemaVersion、使用字符串端口或携带已删除兼容标记的旧工程不符合工程 JSON v1。
• 删除 Pydantic v1 序列化兼容分支，后端当前明确依赖 Pydantic v2。
• experimental 组件包删除旧 LIBRARY_ID/LABEL/VERSION/... 兼容别名，只保留规范化 LIBRARY 清单。

文档与 Schema

新增

• docs/backend-interface-version-spec-v1.md：统一说明 HTTP、组件目录、工程 JSON、组件库、模型和 System XML 的版本边界与事实优先级。
• docs/system-xml-v3.md：System XML v3 当前协议。
• schemas/system-simulation-v3.xsd：System XML v3 Schema。
• docs/后端求解逻辑与效率优化调研.md：当前半显式 ODE、代数闭合、采样、流式任务与性能优化方向。
• docs/接口类型与表示方式总结.md：组件目录、工程 JSON、System XML 和编译结果之间的字段边界。

更新

• 根 README.md、app/simulation/README.md 和 docs/README.md 同步当前接口、协议入口和求解能力说明；文档索引新增本更新日志入口。
• docs/component-library-spec-v1.md 更新组件库发现、启动校验、临时库显示和前端读取规则。
• docs/component-model-authoring-spec-v1.md 更新模型版本、动态端口和合同测试要求。
• docs/amesim-component-migration-matrix.md 更新 AMESim 机械组件迁移状态。

删除

• docs/system-xml-v1.md
• docs/system-xml-v2.md
• schemas/system-simulation-v1.xsd
• schemas/system-simulation-v2.xsd
• tests/test_reactflow_project_medium_reference.py，其覆盖被工程 JSON v1、介质合同和 System XML v3 测试替代。

测试覆盖

新增或扩展的后端测试

• 工程 JSON v1 的版本、节点模型版本、端口结构、旧兼容标记、持久化元数据和损坏数据拒绝。
• System XML v3 的最小模型、编辑器字段拒绝、模型版本、参数、组件自连、端口合同、信号方向和连接基数。
• 仿真采样点上限、严格递增、两端点、极小步长、非有限时间和浮点不可推进时间。
• 物理岛检查在信号扇出场景下的正确性。
• FORC 正反方向、非法值及旋转不改变物理方向。
• MECMAS21 新默认值和旧编码拒绝。
• LMECHN1 默认 2 个、最大 20 个右侧端口、动态参考端口、未启用端口零约束和方程组方阵性。
• LMECHN1 的 2 端口与 8 端口完整仿真，均验证 10 N / 2 kg = 5 m/s²。
• 氦气、介质、气室、管路、阀、孔板、节点、PNRP17、UD00 等现有 XML 测试统一迁移到工程 JSON v1 与 System XML v3。

新增或扩展的前端 E2E

• 实际图标包络框选、框选回撤和虚线选择框。
• 待放置式粘贴、鼠标跟随、中键旋转、视口操作、ID 避让和控制台原生复制。
• 底部停靠控制台的范围、高度、折叠摘要和持久化。
• 组件库成功/失败状态、临时库过滤、固定图标模式、字号、折叠、悬停预览和工作区拖拽预览。
• 动态端口数量、编号、旋转布局、参考端口吸附、旧工程迁移及上限错误。
• 接触边无交互入口、已连接端口隐藏、端口圆形和随视口缩放。
• 高倍缩放吸附双下限、PNRP17 等长箭杆以及 PN3NODE2/P4NODE2 的 40% 直线汇流图标。
• PNL00R、PNL0001、PNL0002、PNL0003 的 standard 画布、60% 工作区占比与接口锚点。
• 工程版本、模型版本、MECMAS21 编码拒绝、System XML v3 导出与双精度参数文本。
• 结果页适配、端口图形、水印隐藏和控制台作用范围。

当前已复核的定向检查

• LMECHN1 方程、默认值、整数/上限与 2/8 端口仿真：6 个测试通过。
• 建模区端口连接、端口随画布缩放及结果页端口：3 个 E2E 通过。
• 本轮 PNRP17、PN3NODE2/P4NODE2、高倍缩放并开启网格的吸附、既有 10px 边界和控制台降噪：5 个定向 E2E 通过。
• PNL00R、PNL0001、PNL0002、PNL0003 的 standard 画布与 60% 工作区占比：1 个定向 E2E 通过。
• 合并远端求解优化后，完整后端测试共 589 项通过。
• 前端全量 E2E 首轮 91/95 通过；其余 4 项陈旧断言修正后定向重跑全部通过，当前 95 项覆盖均已验证。
• TypeScript 类型检查通过。
• Vite 生产构建通过；仍存在已有的单个大于 500 kB chunk 警告。
• git diff --check 在写入本日志前通过，仅报告既有 LF/CRLF 转换提示。

当前变更文件范围

前端源码

• frontend/src/App.tsx
• frontend/src/ComponentSymbol.tsx
• frontend/src/ContactAwareEdge.tsx
• frontend/src/DockedSimulationConsole.tsx（新增）
• frontend/src/SimulationResultsView.tsx
• frontend/src/componentSymbols/mechanical.tsx
• frontend/src/componentSymbols/pneumatic.tsx
• frontend/src/componentSymbols/types.ts
• frontend/src/styles.css

后端源码

• app/main.py
• app/system_xml.py
• app/simulation/components/amesim/mechanical/translational.py
• app/simulation/components/experimental/__init__.py
• app/simulation/core/base.py
• app/simulation/systems/generic.py
• app/simulation/systems/network.py

文档与 Schema

• README.md
• app/simulation/README.md
• docs/README.md
• docs/amesim-component-migration-matrix.md
• docs/backend-interface-version-spec-v1.md（新增）
• docs/component-library-spec-v1.md
• docs/component-model-authoring-spec-v1.md
• docs/system-xml-v1.md（删除）
• docs/system-xml-v2.md（删除）
• docs/system-xml-v3.md（新增）
• docs/后端求解逻辑与效率优化调研.md（新增）
• docs/接口类型与表示方式总结.md（新增）
• docs/更新日志-2026-08-15.md（新增）
• schemas/system-simulation-v1.xsd（删除）
• schemas/system-simulation-v2.xsd（删除）
• schemas/system-simulation-v3.xsd（新增）

前端测试

• frontend/tests/e2e/amesim-medium.spec.ts
• frontend/tests/e2e/component-symbols.spec.ts
• frontend/tests/e2e/fit-view.spec.ts
• frontend/tests/e2e/fixtures.ts
• frontend/tests/e2e/modeling-actions.spec.ts
• frontend/tests/e2e/palette-display.spec.ts
• frontend/tests/e2e/parameter-table.spec.ts

后端测试

• tests/test_amesim_gas_registry.py
• tests/test_amesim_helium_medium.py
• tests/test_amesim_helium_step_long_run.py
• tests/test_amesim_mechanical_public_components.py
• tests/test_amesim_mechanical_xml.py
• tests/test_amesim_pnch012_xml.py
• tests/test_amesim_pnch023_xml.py
• tests/test_amesim_pneumatic_node_xml.py
• tests/test_amesim_pnl0001_xml.py
• tests/test_amesim_pnl0002_pnl0003_xml.py
• tests/test_amesim_pnl00r_xml.py
• tests/test_amesim_pnor001_xml.py
• tests/test_amesim_pnpl01_xml.py
• tests/test_amesim_pnrp17_xml.py
• tests/test_amesim_pnvo001_fixed_xml.py
• tests/test_amesim_pnvo001_signal_xml.py
• tests/test_amesim_signal_components.py
• tests/test_amesim_ud00_xml.py
• tests/test_component_catalog.py
• tests/test_generic_system_xml_simulation.py
• tests/test_medium_reference_contract.py
• tests/test_reactflow_project_medium_reference.py（删除）
• tests/test_reactflow_project_schema.py（新增）
• tests/test_simulation_safety.py（新增）
• tests/test_system_xml_parser.py
• tests/test_system_xml_protocol.py
• tests/test_system_xml_v3.py（新增）
• tests/test_test_mql_example_runner.py