417 lines
12 KiB
Markdown
417 lines
12 KiB
Markdown
# 模型开发模块设计文档
|
||
|
||
## 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）说明：下载生成的代码压缩包文件。
|