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

通过对比旧接口 (`/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. 根本原因分析

1.  **静态属性缺失**：
    *   新接口的 `SimService` 或 `SimResultConverter` 在生成快照或转换结果时，可能仅输出了“变化量”或“当前计算量”，而漏掉了 `SimUnit` 中的 `staticProperties`。
    *   虽然 `SimService` 初始化时将静态值写入了 `SimContext`，但在 `SimResultConverter.toFrames` 中，可能未正确将所有属性（静态+动态）合并输出。

2.  **元数据缺失**：
    *   新接口的返回值直接是 `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 结构

```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
                    }
                }
            }
            // ...
        ]
    }
}
```