6.8 KiB
工程版本警告与统一参数输入验收
报告版本：1.0.0；日期：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 实机验收。
版本检查的独立耗时
在 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、规范索引。
- 回归代码：
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 始终未启动。