XNSim/XNSimPortal/doc/模型开发模块设计文档.md

# 模型开发模块设计文档

## 1. 概述

模型开发模块是 XNSimPortal 系统的核心组件之一，负责管理仿真系统中的模型开发全生命周期。该模块提供了从 ATA 章节管理、模型创建、版本控制到代码生成、编译发布的完整工作流程。模块采用前后端分离架构，前端使用 Web Components 技术构建用户界面，后端提供 RESTful API 接口，并与 XNCore 底层服务进行集成。

### 1.1 模块组成

- **前端组件**：`model-development.js` - 主组件
- **后端路由**：
  - `routes/model-dev.js` - 模型开发 API
- **工具类**：
  - `utils/model-utils.js` - 模型数据操作工具
  - `utils/xnCoreService.js` - XNCore 服务集成工具

### 1.2 技术架构

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   前端组件层     │    │   后端API层      │    │   数据存储层     │    │   XNCore服务层   │
│                 │    │                 │    │                 │    │                 │
│ model-development│◄──►│ model-dev       │◄──►│ SQLite数据库    │◄──►│ XNModelGenServer│
│                 │    │                 │    │ ATAChapters     │    │                 │
│                 │    │                 │    │ XNModels        │    │                 │
│                 │    │                 │    │ XNModelsVersion │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘    └─────────────────┘
```

## 2. 功能

### 2.1 核心功能

1. **ATA 章节管理**

   - ATA 章节浏览和选择
   - 章节层级导航
   - 章节信息展示

2. **模型管理**

   - 模型创建和编辑
   - 模型版本控制
   - 模型信息维护

3. **版本管理**

   - 版本创建和编辑
   - 版本比较功能
   - 版本历史追踪

4. **代码生成**

   - 模板代码生成
   - 代码下载
   - 代码编译

5. **数据包管理**
   - 数据包上传
   - 数据包配置
   - 接口映射

### 2.2 辅助功能

1. **配置管理**

   - 运行节点配置
   - 优先级设置
   - 运行频率配置

2. **开发工具**

   - 命令列表编辑
   - 时间选择器
   - 结构体映射

3. **用户体验**
   - 多级导航
   - 卡片式布局
   - 实时状态反馈

## 3. 性能

### 3.1 性能指标

- **响应时间**：页面加载 < 1s，数据查询 < 500ms
- **并发处理**：支持多用户同时开发
- **数据量支持**：支持大量模型和版本数据
- **内存使用**：前端组件内存占用 < 100MB

### 3.2 性能优化策略

1. **前端优化**

   - 虚拟滚动处理大量数据
   - 懒加载组件
   - 防抖处理用户输入

2. **后端优化**

   - 数据库索引优化
   - 缓存机制
   - 异步处理

3. **代码生成优化**
   - 增量编译
   - 并行处理
   - 资源复用

## 4. 输入

### 4.1 用户输入

1. **模型版本数据**

   ```
   {
     ClassName: "模型类名",
     Name: "版本名称",
     Version: "版本号",
     Author: "作者",
     PlaneName: "机型名称",
     ConfID: "构型ID",
     Description: "描述",
     RunFreqGroup: "运行频率组",
     RunNode: "运行节点",
     Priority: "优先级",
     DataPackagePath: "数据包路径",
     DataPackageName: "数据包名称",
     DataPackageHeaderName: "数据包头文件名",
     DataPackageEntryPoint: "数据包入口点",
     DataPackageInterfaceName: "数据包接口名",
     InputStruct: "输入结构体",
     OutputStruct: "输出结构体",
     HeartStruct: "心跳结构体",
     CmdList: "命令列表JSON"
   }
   ```

2. **代码生成参数**

   - className：模型类名
   - version：版本号
   - planeName：机型名称

3. **文件输入**
   - 数据包文件
   - 包装代码文件
   - 配置文件

### 4.2 系统输入

1. **构型选择**

   - 从 localStorage 获取当前选择的构型 ID
   - 机型信息

2. **配置数据**
   - ATA 章节列表
   - 模型列表
   - 版本列表

## 5. 输出

### 5.1 数据输出

1. **ATA 章节列表**

   ```json
   [
     {
       "ID": "章节ID",
       "Name": "章节名称",
       "Name_CN": "章节中文名称"
     }
   ]
   ```

2. **模型列表**

   ```json
   [
     {
       "PlaneName": "机型名称",
       "Chapters_ID": "章节ID",
       "ModelName": "模型名称",
       "ModelName_CN": "模型中文名称",
       "Description": "描述",
       "ClassName": "类名"
     }
   ]
   ```

3. **版本列表**

   ```json
   [
     {
       "PlaneName": "机型名称",
       "ClassName": "类名",
       "Name": "版本名称",
       "ConfID": "构型ID",
       "Version": "版本号",
       "Author": "作者",
       "Description": "描述",
       "CreatTime": "创建时间",
       "ChangeTime": "修改时间",
       "RunFreqGroup": "运行频率组",
       "RunNode": "运行节点",
       "Priority": "优先级",
       "DataPackagePath": "数据包路径",
       "DataPackageName": "数据包名称",
       "DataPackageHeaderName": "数据包头文件名",
       "DataPackageEntryPoint": "数据包入口点",
       "DataPackageInterfaceName": "数据包接口名",
       "InputStruct": "输入结构体",
       "OutputStruct": "输出结构体",
       "HeartStruct": "心跳结构体",
       "CmdList": "命令列表"
     }
   ]
   ```

4. **操作结果**
   ```json
   {
     "success": true,
     "message": "操作成功",
     "data": {}
   }
   ```

### 5.2 界面输出

1. **章节卡片**：显示 ATA 章节信息
2. **模型卡片**：显示模型基本信息
3. **版本卡片**：显示版本详细信息
4. **版本编辑器**：版本信息编辑表单
5. **代码生成结果**：生成状态和下载链接

## 6. 算法

### 6.1 版本号生成算法

```
输入：现有版本列表
输出：下一个版本号

1. 获取当前版本列表
2. 提取所有版本号
3. 解析版本号格式（如v1.0.0）
4. 找到最大版本号
5. 递增版本号
6. 返回新版本号
```

### 6.2 结构体映射算法

```
输入：源结构体列表，目标结构体列表
输出：映射关系

1. 分析源结构体字段
2. 分析目标结构体字段
3. 根据字段名称和类型进行匹配
4. 生成映射关系
5. 返回映射配置
```

### 6.3 代码生成算法

```
1. 读取模型版本信息
2. 解析数据包配置
3. 生成模板代码
4. 应用用户配置
5. 生成最终代码
6. 返回代码文件
```

## 7. 流程

### 7.1 模型开发主流程

```mermaid
graph TD
    A[用户进入模型开发页面] --> B[加载ATA章节]
    B --> C[显示章节卡片]
    C --> D[用户选择章节]
    D --> E[加载模型列表]
    E --> F[显示模型卡片]
    F --> G[用户选择模型]
    G --> H[加载版本列表]
    H --> I[显示版本卡片]
    I --> J[用户操作]
    J --> K{操作类型}
    K -->|创建版本| L[打开版本编辑器]
    K -->|编辑版本| M[加载版本数据]
    K -->|生成代码| N[调用代码生成]
    K -->|编译发布| O[调用编译服务]
    L --> P[保存版本]
    M --> P
    N --> Q[下载代码]
    O --> R[发布结果]
    P --> S[刷新版本列表]
    Q --> S
    R --> S
    S --> I
```

### 7.2 版本创建流程

```mermaid
graph TD
    A[用户点击创建版本] --> B[获取当前时间]
    B --> C[生成版本号]
    C --> D[初始化版本数据]
    D --> E[显示版本编辑器]
    E --> F[用户填写信息]
    F --> G[验证数据]
    G --> H{数据是否有效?}
    H -->|否| I[显示错误信息]
    H -->|是| J[保存到数据库]
    I --> F
    J --> K[返回成功结果]
    K --> L[刷新版本列表]
```

### 7.3 代码生成流程

```mermaid
graph TD
    A[用户点击生成代码] --> B[验证模型信息]
    B --> C[调用XNCore服务]
    C --> D[生成模板代码]
    D --> E[应用用户配置]
    E --> F[生成最终代码]
    F --> G[压缩代码包]
    G --> H[返回下载链接]
    H --> I[用户下载代码]
```

## 8. 接口

所有接口均以/api 为前缀，数据格式为 JSON，采用 HTTP/HTTPS 协议。具体接口有：

1. GET /api/ata-chapters  
   1）功能：获取 ATA 章节列表；  
   2）输入：无参数；  
   3）输出：JSON 对象{ success: boolean, message: string, data: array}；  
   4）说明：返回所有 ATA 章节信息，包含章节 ID、名称和中文名称。

2. GET /api/chapter-models/:chapterId  
   1）功能：获取指定章节的模型列表；  
   2）输入：chapterId（路径参数），planeName（查询参数）；  
   3）输出：JSON 对象{ success: boolean, message: string, data: array }；  
   4）说明：返回指定章节和机型下的所有模型信息。

3. GET /api/model-versions/:className  
   1）功能：获取指定模型的版本列表；  
   2）输入：className（路径参数），planeName（查询参数）；  
   3）输出：JSON 对象{ success: boolean, message: string, data: array }；  
   4）说明：返回指定模型的所有版本信息，按版本号降序排列。

4. POST /api/model-versions  
   1）功能：保存模型版本信息；  
   2）输入：JSON 对象，包含版本定义的所有字段；  
   3）输出：JSON 对象{ success: boolean, message: string, id: number }；  
   4）说明：创建新版本或更新现有版本，支持 CmdList JSON 格式。

5. POST /api/model-code-gen  
   1）功能：生成模型代码；  
   2）输入：JSON 对象{ className, version, planeName }；  
   3）输出：JSON 对象{ success: boolean, message: string, result: string }；  
   4）说明：调用 XNCore 服务生成模型模板代码。

6. POST /api/model-code-zip  
   1）功能：压缩模型代码；  
   2）输入：JSON 对象{ className, version, planeName }；  
   3）输出：JSON 对象{ success: boolean, message: string, result: string }；  
   4）说明：将生成的代码压缩成 ZIP 包。

7. POST /api/model-code-unzip  
   1）功能：解压模型代码；  
   2）输入：JSON 对象{ className, version, planeName, srcPath }；  
   3）输出：JSON 对象{ success: boolean, message: string, result: string }；  
   4）说明：解压代码包到指定目录。

8. POST /api/model-code-compile  
   1）功能：编译模型代码；  
   2）输入：JSON 对象{ className, version, planeName }；  
   3）输出：JSON 对象{ success: boolean, message: string, result: string }；  
   4）说明：编译模型代码并生成可执行文件。

9. POST /api/filesystem/upload-package  
   1）功能：上传数据包文件；  
   2）输入：form-data 格式，包含 confName、folderName 和 files；  
   3）输出：JSON 对象{ success: boolean, message: string, packagePath: string, headerFile: string, libraryFile: string, entryPoint: string, paramType: string, memberNames: array }；  
   4）说明：上传数据包文件夹，解析头文件和动态库，返回配置信息。

10. POST /api/filesystem/upload-zip  
    1）功能：上传集成代码 ZIP 文件；  
    2）输入：form-data 格式，包含 confName 和 file；  
    3）输出：JSON 对象{ success: boolean, message: string, file: object }；  
    4）说明：上传集成代码压缩包，支持自动解压功能。

11. POST /api/filesystem/get-struct-members  
    1）功能：获取结构体成员信息；  
    2）输入：JSON 对象{ confName, headerFilePath, structName }；  
    3）输出：JSON 对象{ success: boolean, message: string, memberNames: array }；  
    4）说明：解析头文件中的结构体定义，返回成员名称列表。

12. GET /api/filesystem/download-zip  
    1）功能：下载代码压缩包；  
    2）输入：filePath（查询参数）；  
    3）输出：ZIP 文件流；  
    4）说明：下载生成的代码压缩包文件。