jinchao/XNSim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
XNSim/XNSimPortal/doc/模型开发模块设计文档.md
jinchao 2c394d7ab8 文档更新
2025-07-25 13:42:20 +08:00

12 KiB
Raw Blame History

模型开发模块设计文档

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 章节列表

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

  2. 模型列表

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

  3. 版本列表

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

  4. 操作结果

    {
  "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 模型开发主流程

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 版本创建流程

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 代码生成流程

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）说明：下载生成的代码压缩包文件。