XNSim/XNSimPortal/doc/仿真运行模块设计文档.md

# 仿真运行模块设计文档

## 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）说明：用于前端实时显示仿真输出。

---

如需补充参数字段或详细说明，请告知！