# 工程版本警告与统一参数输入验收

报告版本：1.0.1；日期：2026-09-12；基线：`22579e5` 加本次工作区改动。

本次落实旧组件版本警告和参数输入语义统一。验收案例为 `tests/data/test-mql-8-corrected.json`，157 个组件、178 条连接、1092 个已保存参数。测试没有改动四路/八路基准文件、C 方程、雅可比算法或求解精度。

## 实现与使用规则

- 导入时集中列出不同/缺失版本；运行或生成 XML 时再次警告，兼容的数据使用当前模型。类型、端口、未知参数、范围和非法表达式仍校验，版本警告不会掩盖实际错误。
- 导出工程 JSON 时，兼容节点写当前模型版本；无法转换的草稿保留旧格式/原版本并提示。当前编辑草稿保留来源版本，重新导入新文件后使用导出版本。
- 外部工程格式升级到 `projectSchemaVersion: 2`：数值、数字字符串、表达式均使用 `parameterUnits`，缺省为目录 SI 单位。网页、HTTP、CLI 在进入数值计算前完成求值与单位转换。XML/内部数值构造器严格接收有限 SI 数字和当前版本。
- v1 兼容保持原数值的 SI 含义；不能手工只把版本号改为 2。用网页导出完成转换。内部编辑数据、浏览器草稿及结果快照继续保留 v1/SI 数字表示。
- 单位换算表由网页与 Python 共用。表达式支持受限算术、幂、常量和白名单函数；两端共用测试数据，禁止任意代码、非有限结果和离散参数表达式。

导出时检查数值能否经显示单位精确往返。不能时，该参数改用 SI 单位导出，并在控制台说明，避免物理输入漂移。本八路工程的 30 个压力参数因此从 bar 改为 Pa 显示；数值大小与单位共同保持同一个精确 SI 输入。未额外保存一份隐藏的数值副本。

## 功能验收

真实构建后的网页由临时 `127.0.0.1:8036` 提供，Chromium 151.0.7922.34；未模拟 API 或 C 结果。顺序运行原工程、将全部组件版本改成 `0.0.1` 的工程、浏览器重新导出的 v2 工程。三次均以原始配置运行到 10 s，1002 个采样点。1785 列、共 1,788,570 个结果值逐值相同，编译缓存键也相同。

| 工程 | 导入完成 ms | 点击至 HTTP 响应收齐 ms | 点击至 IndexedDB 保存完成 ms | C 求解 s |
| --- | ---: | ---: | ---: | ---: |
| current | 364.45 | 3759.60 | 3882.24 | 2.6147 |
| old | 255.86 | 3725.61 | 3869.42 | 2.6327 |
| exported-v2 | 237.20 | 3710.86 | 3807.77 | 2.5902 |

这是本机回环、缓存命中的验收记录，各工程各一次；不用于推断远程端口转发速度或长期性能提升。导入时间包含浏览器事件和界面工作，不等于版本检查耗时。

真实网页与 HTTP 分别输入 `2.5`、`"2.5"`、`"=2.5"`、`"2+0.5"`、`"sqrt(6.25)"`，单位为 bar，均生成 250000 Pa；`"=10+10"` degC 均生成 293.15 K。浏览器导出后保留数字或表达式的正确单位语义。浏览器 `pageerror` 为 0。

| 验收层次 | 结果 |
| --- | --- |
| 后台相关回归 | 49 项通过；包含 HTTP XML/网络入口、CLI、SI 数值边界、版本/端口错误、单位、表达式、原生执行与结果传输 |
| 前端相关回归 | 分批覆盖 54 个不同用例，最终通过；包含原参数表、科学计数法、压力、存档、旧版 LMECHN1/FORC、非法参数与精确导出；失败项修正后定向 9 项复测通过 |
| TypeScript/Vite | 生产构建通过；仍有既有的大包体提示 |
| 原八路 CLI 输入 | 新旧适配代码生成 XML 逐字节一致，106719 字节 |
| 全量后台扩展检查 | 运行 362 项；3 处旧夹具缺失错误，1 项跳过，未宣称全量通过 |

全量检查的缺失项为两组测试仍指向不存在的 `AmesimModels/test_mql.ame`，以及缺少 `tests/fixtures/high_stiffness_explicit_rk45.xml`。这些测试/夹具不在本次实现改动内，没有伪造数据或改成通过。原始日志保留。没有重新执行 Amesim 对照。Linux 实测完成；Windows 使用通用 Python/浏览器实现，没有新增平台专用调用，但本次没有 Windows 实机验收。

## 缺失输入后续修复 / 2026-09-12

用户确认移动/删除了夹具后，已按实际文件哈希修复历史 AME 路径；高刚度 XML 未找到，按用户授权改为当前八路完整 BDF 测试。全量后台重新执行 375 项，374 通过、1 条原条件跳过，0 失败/错误。原 RK45 专项未恢复，不将本次替代用例算成原覆盖。另修复前端/审计对已删除 JSON/XML 的依赖，画布复测 11 项通过。上述表格保留前次原始执行结果；文件映射、报告依据及本次测试日志见 [路径修复报告](2026-09-12-test-input-path-refresh.md)。

## 版本检查的独立耗时

在 Chromium 内执行正式 `projectCompatibility.ts` 中的目录索引、版本比较及提示文字生成函数。目录仅建立一次内存 Map，通过 WeakMap 按目录数组复用；每次扫描节点，无逐组件网络请求或文件扫描。预热后每组 200 个样本、每样本 10 次调用；时间分辨率约 0.1 ms，通过批量计时减小量化误差。首次索引建立约 0.10 ms。

| 组件数 | 当前版本：中位/P95 ms | 全部旧版：中位/P95 ms | 旧版检查＋提示文字：中位/P95 ms |
| ---: | ---: | ---: | ---: |
| 157 | 0.010 / 0.020 | 0.010 / 0.020 | 0.030 / 0.040 |
| 1000 | 0.030 / 0.040 | 0.060 / 0.070 | 0.160 / 0.230 |
| 10000 | 0.280 / 0.310 | 0.550 / 0.620 | 1.720 / 1.820 |

该表不包含 React 绘制控制台文字、JSON 解析或整模型合法性检查。对实际八路案例，版本扫描和生成提示的中位耗时约 0.03 ms；不构成可感知的等待。

Python 输入适配的完整成本另外测量，包含防御性复制、版本对照、1092 个已保存参数的求值/换算及仿真时间转换，并非版本扫描本身：

| 阶段 | 中位 ms | P95 ms |
| --- | ---: | ---: |
| Pydantic 结构读取 | 2.084 | 2.299 |
| 当前版本输入归一化 | 11.684 | 13.276 |
| 全部旧版输入归一化 | 11.754 | 30.189 |
| 归一化后严格构造 XML | 22.358 | 43.884 |

以上为预热后各 200 次测量，尾部受调度与垃圾回收波动影响。不能把当前/旧版的微小中位数差当成稳定性能变化。

## 文件与复现

- 现行规范：[接口规范 1.2.0](../standard/backend-interface-version-spec-v1.md#61-工程存储与执行入口)、[规范索引](../standard/README.md)。
- 回归代码：`tests/test_project_input_contract.py`、`frontend/tests/e2e/project-input-contract.spec.ts`；共享表达式用例为 `tests/fixtures/parameter-expressions.json`。
- 网页验收：`tests/manual/browser_project_contract.mjs`；后台阶段计时：`tests/manual/benchmark_project_input.py`。
- 原始记录在被 Git 忽略的 `test/project-contract-20260912/`。最终网页记录为 `browser-accepted/summary.json`、`version-check.json`、三份 XML/结果文件、`upgraded-eight.json`、五份单位用例 JSON 和 `acceptance.png`。其他 browser 子目录是诊断过程，不能当作最终验收。
- `backend-input-timing.json`、`backend-targeted.log`、`backend-all.log`、`frontend-regression.log`、`frontend-final-targets.log` 保留对应计时/测试；前端第一次 26 项参数相关通过记录见本报告与执行记录。

本次没有安装新环境或上传 Git；环境和运行产物仍保持忽略。测试结束后停止临时 8036 服务，5173/8000 始终未启动。