新旧接口模拟数据结果分析及优化建议

通过对比旧接口 (/projects/simulation/init) 和新接口 (/sim/run) 的返回数据，发现以下主要差异：

1. 数据结构与层级差异

差异点	旧接口 (`/projects/simulation/init`)	新接口 (`/sim/run`)	影响分析
顶层包装	包含 `msg`, `code`, `data` (标准 Result 结构)	仅包含 `data` (需确认 Controller 是否使用了 `Result` 包装)	前端解析逻辑需调整，或新接口需补齐统一响应封装。
元数据 (Metadata)	`data` 层包含 `projectId`, `scenarioId`, `generated`, `issues`	缺失这些元数据	缺少调试信息和上下文关联，不利于前端展示“生成了多少帧/事件”。
帧列表 (Frames)	`data.frames`	`data.frames`	结构一致，核心数据都在。

2. 帧内数据 (Frame Content) 差异

差异点	旧接口	新接口	影响分析
设备属性完整性	包含 `diameter`, `height`, `u_enrichment`, `u_concentration` 等所有属性	仅包含 `u_concentration` 和 `deviceType`	严重。新接口未输出静态属性（如尺寸）或未变化的属性，前端渲染（如 3D 模型）可能因缺少 `diameter/height` 而无法绘制设备。
时间步 (Time)	从 `time: 1` 开始	从 `time: 0` 开始	新接口更符合“初始状态 t=0”的逻辑，旧接口可能跳过了 t=0 或索引偏移。
数值精度	`20.0` (保留一位小数)	`20.0`	一致。

3. 根本原因分析

静态属性缺失：
- 新接口的 SimService 或 SimResultConverter 在生成快照或转换结果时，可能仅输出了“变化量”或“当前计算量”，而漏掉了 SimUnit 中的 staticProperties。
- 虽然 SimService 初始化时将静态值写入了 SimContext，但在 SimResultConverter.toFrames 中，可能未正确将所有属性（静态+动态）合并输出。
元数据缺失：
- 新接口的返回值直接是 SimResultConverter.toFrames 的结果（仅含 frames），未包装 projectId 等上下文信息。

4. 优化建议

4.1 补齐静态属性 (High Priority)

修改 SimResultConverter 或 SimService，确保输出的 devices 状态中包含：

静态属性：diameter, height, volume 等（从 Topology 或 DB 加载的）。
初始属性：u_enrichment 等在 t=0 时设定的值。

建议方案：在 SimResultConverter 中，遍历 SimContext 的快照时，确保 key 覆盖了所有属性，或者在输出前将 SimUnit.staticProperties merge 到每一帧的 device state 中。

4.2 统一响应结构 (Medium Priority)

建议 SimController 返回 Result<Map<String, Object>> 而非直接返回 Map，保持与旧接口一致的 code/msg/data 结构。

4.3 补充元数据 (Low Priority)

在返回的 data 对象中，补充 projectId, scenarioId 以及 generated 统计信息，方便前端展示。

4.4 时间轴对齐

确认业务需要 t=0。通常 t=0 作为初始状态是必要的。

5. 预期修正后的 JSON 结构

{
    "code": 0,
    "msg": "success",
    "data": {
        "projectId": "...",
        "scenarioId": "...",
        "frames": [
            {
                "step": 0,
                "time": 0,
                "devices": {
                    "device_id_1": {
                        "deviceType": "CylindricalTank",
                        "diameter": 20.0,      <-- 补齐静态值
                        "height": 20.0,        <-- 补齐静态值
                        "u_enrichment": 0.1,   <-- 补齐初始值
                        "u_concentration": 10.0
                    }
                }
            }
            // ...
        ]
    }
}

3.8 KiB Raw Permalink Blame History Unescape Escape