229 lines
9.0 KiB
Markdown
229 lines
9.0 KiB
Markdown
# 仿真运行模块设计文档
|
||
|
||
## 1. 概述
|
||
|
||
仿真运行模块是 XNSimPortal 系统的核心功能之一，负责组织、调度和监控仿真任务的全流程。该模块支持模型组与服务的自动加载、仿真任务的启动/暂停/终止、实时日志输出、进程状态监控等。前端采用 Web Components 技术，后端提供 RESTful API 及 SSE 实时输出，支持与 DDS、XNEngine 等底层服务集成。
|
||
|
||
### 1.1 模块组成
|
||
|
||
- **前端组件**：`run-sim.js` - 主组件
|
||
- **后端路由**：
|
||
|
||
- `routes/run-simulation.js` - 仿真运行与管理 API
|
||
- `routes/configurations.js` - 构型与模型组、服务 API
|
||
- `routes/dds-monitor.js` - DDS 监控 API
|
||
- `routes/system-control.js` - 引擎控制 API
|
||
- `routes/stop-simulation.js` - 仿真终止 API
|
||
- `routes/simulation-output.js` - SSE 实时输出 API
|
||
- `routes/filesystem.js` - 日志文件读取 API
|
||
- **工具类**：
|
||
|
||
- `utils/xnengine-process-utils.js` - 仿真进程管理工具
|
||
- `utils/db-utils.js` - 数据库操作工具
|
||
|
||
### 1.2 技术架构
|
||
|
||
```
|
||
┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐
|
||
│ 前端组件层 │ │ 后端API层 │ │ 底层服务/存储层 │
|
||
│ run-sim.js │<--►│ run-simulation │<--►│ XNEngine │
|
||
│ │ │ configurations │ │ DDS │
|
||
│ │ │ dds-monitor │ │ SQLite │
|
||
│ │ │ system-control │ │ 日志文件 │
|
||
│ │ │ simulation-output │ │ │
|
||
└────────────────────┘ └────────────────────┘ └────────────────────┘
|
||
```
|
||
|
||
## 2. 功能
|
||
|
||
### 2.1 核心功能
|
||
|
||
1. **模型组与服务加载**
|
||
|
||
- 自动加载当前构型下的模型组及其模型
|
||
- 自动加载当前构型下的服务及其版本
|
||
2. **仿真任务管理**
|
||
|
||
- 启动仿真/测试
|
||
- 暂停/继续仿真
|
||
- 终止仿真
|
||
- 进程状态检测与自动重连
|
||
3. **实时输出与日志**
|
||
|
||
- SSE 实时输出仿真日志
|
||
- 日志文件轮询与增量读取
|
||
- ANSI 终端颜色转 HTML
|
||
4. **状态监控与反馈**
|
||
|
||
- DDS 监控初始化与状态检测
|
||
- 仿真进程状态轮询
|
||
- UI 状态与按钮联动
|
||
|
||
### 2.2 辅助功能
|
||
|
||
- 错误与成功提示
|
||
- 自动重连机制
|
||
- 资源清理与事件解绑
|
||
|
||
## 3. 性能
|
||
|
||
### 3.1 性能指标
|
||
|
||
- **仿真启动响应**：< 2s
|
||
- **日志输出延迟**：< 200ms
|
||
- **并发仿真支持**：支持多用户独立仿真
|
||
- **内存占用**：前端 < 50MB
|
||
|
||
### 3.2 性能优化策略
|
||
|
||
- SSE 实时推送减少轮询压力
|
||
- 日志文件增量读取
|
||
- 按需加载模型组/服务
|
||
- 进程状态本地缓存与重连
|
||
|
||
## 4. 输入
|
||
|
||
### 4.1 用户输入
|
||
|
||
- 构型选择（localStorage）
|
||
- 仿真操作（启动、暂停、终止按钮）
|
||
- 运行参数（自动从构型获取）
|
||
|
||
### 4.2 系统输入
|
||
|
||
- 当前构型 ID
|
||
- 模型组与服务列表
|
||
- 仿真进程状态
|
||
- 日志文件路径
|
||
|
||
## 5. 输出
|
||
|
||
### 5.1 数据输出
|
||
|
||
- **模型组与服务列表**
|
||
```json
|
||
[
|
||
{
|
||
"name": "模型组名",
|
||
"groupId": "组ID",
|
||
"freq": 100,
|
||
"priority": 1,
|
||
"cpuAff": 0,
|
||
"models": [
|
||
{ "className": "模型类名", "version": "1.0.0" }
|
||
]
|
||
}
|
||
]
|
||
```
|
||
- **服务列表**
|
||
```json
|
||
[
|
||
{ "className": "服务类名", "version": "1.0.0" }
|
||
]
|
||
```
|
||
- **仿真运行结果**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"simulationId": "进程ID",
|
||
"logFile": "日志文件路径",
|
||
"message": "仿真启动成功"
|
||
}
|
||
```
|
||
- **日志内容**
|
||
```json
|
||
{ "content": "日志文本" }
|
||
```
|
||
|
||
### 5.2 界面输出
|
||
|
||
- 模型组/服务列表卡片
|
||
- 仿真运行输出（带颜色）
|
||
- 状态提示（成功/错误/信息）
|
||
|
||
## 6. 算法
|
||
|
||
### 6.1 日志文件增量读取算法
|
||
|
||
```
|
||
1. 记录上次读取的文件位置
|
||
2. 定时（100ms）请求后端读取新内容
|
||
3. 拼接到前端输出区
|
||
4. 若进程结束，读取剩余内容并停止轮询
|
||
```
|
||
|
||
### 6.2 SSE 实时输出处理算法
|
||
|
||
```
|
||
1. 建立 EventSource 连接
|
||
2. 监听 output/status/completed/error/terminated 事件
|
||
3. 解析数据并更新 UI
|
||
4. 断线自动重连（最多3次）
|
||
```
|
||
|
||
### 6.3 仿真进程状态检测算法
|
||
|
||
```
|
||
1. 定时请求 /api/check-process/:id
|
||
2. 若 running=false，重置UI
|
||
3. 若 running=true，保持连接
|
||
```
|
||
|
||
## 7. 流程
|
||
|
||
### 7.1 仿真运行主流程
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[用户点击运行仿真] --> B[获取构型参数]
|
||
B --> C[初始化DDS监控]
|
||
C --> D[初始化引擎控制]
|
||
D --> E[启动仿真进程]
|
||
E --> F[建立SSE连接]
|
||
F --> G[实时输出日志]
|
||
G --> H{仿真状态}
|
||
H -->|运行中| G
|
||
H -->|结束| I[重置UI]
|
||
```
|
||
|
||
### 7.2 日志输出流程
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[仿真进程启动] --> B[生成日志文件]
|
||
B --> C[前端定时请求日志内容]
|
||
C --> D[后端返回新内容]
|
||
D --> E[前端拼接显示]
|
||
E --> F{进程状态}
|
||
F -->|运行| C
|
||
F -->|结束| G[停止轮询]
|
||
```
|
||
|
||
## 8. 接口
|
||
|
||
所有接口均以/api 为前缀，数据格式为 JSON，采用 HTTP/HTTPS 协议。具体接口有：
|
||
|
||
1. GET /api/configurations/:confID/model-groups1）功能：获取指定构型下的模型组列表；2）输入：confID（路径参数）；3）输出：JSON 对象{ success: boolean, message: string, data: array }；4）说明：返回所有模型组及其基本信息。
|
||
2. GET /api/model-groups/:groupId/models1）功能：获取指定模型组下的模型列表；2）输入：groupId（路径参数）；3）输出：JSON 对象{ success: boolean, message: string, data: array }；4）说明：返回指定模型组下的所有模型及其版本。
|
||
3. GET /api/configurations/:confID/services1）功能：获取指定构型下的服务列表；2）输入：confID（路径参数）；3）输出：JSON 对象{ success: boolean, message: string, data: array }；4）说明：返回所有服务及其版本信息。
|
||
4. POST /api/run-simulation1）功能：启动仿真或测试任务；2）输入：JSON 对象{ args: array, timeout?: number }；3）输出：JSON 对象{ success: boolean, simulationId: string, logFile: string, message: string }；4）说明：启动仿真进程，返回进程ID和日志文件路径。
|
||
5. GET /api/check-process/:id1）功能：检查仿真进程状态；2）输入：id（路径参数，仿真进程ID）；3）输出：JSON 对象{ running: boolean, success: boolean, message: string }；4）说明：返回指定进程是否仍在运行。
|
||
6. GET /api/read-log-file1）功能：读取仿真日志文件内容；2）输入：file（查询参数，日志文件路径），position（查询参数，起始位置）；3）输出：JSON 对象{ content: string }；4）说明：返回日志文件从指定位置开始的新内容。
|
||
7. GET /api/check-xnengine1）功能：检测是否有正在运行的仿真进程；2）输入：无参数；3）输出：JSON 对象{ running: boolean, pid: string, message: string }；4）说明：用于前端自动重连仿真。
|
||
8. GET /api/configurations/:confID1）功能：获取指定构型的详细参数；2）输入：confID（路径参数）；3）输出：JSON 对象{ success: boolean, message: string, data: object }；4）说明：返回构型的详细参数（如DomainID等）。
|
||
9. POST /api/dds-monitor/initialize1）功能：初始化 DDS 监控；2）输入：JSON 对象{ domainId, confID, forceGen? }；3）输出：JSON 对象{ success: boolean, message: string }；4）说明：初始化 DDS 监控环境。
|
||
10. POST /api/system-control/initialize1）功能：初始化仿真引擎控制；2）输入：无参数；3）输出：JSON 对象{ success: boolean, message: string }；4）说明：初始化仿真引擎控制环境。
|
||
11. POST /api/system-control/pause1）功能：暂停仿真；2）输入：无参数；3）输出：JSON 对象{ success: boolean, message: string }；4）说明：暂停仿真进程。
|
||
12. POST /api/system-control/resume1）功能：继续仿真；2）输入：无参数；3）输出：JSON 对象{ success: boolean, message: string }；4）说明：恢复仿真进程。
|
||
13. POST /api/system-control/stop1）功能：停止仿真；2）输入：无参数；3）输出：JSON 对象{ success: boolean, message: string }；4）说明：停止仿真进程。
|
||
14. POST /api/stop-simulation1）功能：终止仿真并清理资源；2）输入：JSON 对象{ id: string }；3）输出：JSON 对象{ success: boolean, message: string }；4）说明：终止仿真进程并清理相关记录。
|
||
15. GET /api/simulation-output/:simulationId
|
||
1）功能：获取仿真实时输出（SSE）；
|
||
2）输入：simulationId（路径参数）；
|
||
3）输出：SSE 事件流（output/status/completed/error/terminated）；
|
||
4）说明：用于前端实时显示仿真输出。
|
||
|
||
---
|
||
|
||
如需补充参数字段或详细说明，请告知！
|