78 lines
3.8 KiB
Markdown
78 lines
3.8 KiB
Markdown
# 新旧接口模拟数据结果分析及优化建议
|
||
|
||
通过对比旧接口 (`/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
|
||
}
|
||
}
|
||
}
|
||
// ...
|
||
]
|
||
}
|
||
}
|
||
```
|