# 接口配置模块设计文档

## 1. 概述

接口配置模块是 XNSimPortal 系统的核心组件之一，负责管理仿真系统中的数据接口定义。该模块提供了完整的接口生命周期管理功能，包括接口的创建、编辑、删除、查询、导入导出等操作。模块采用前后端分离架构，前端使用 Web Components 技术构建用户界面，后端提供 RESTful API 接口。

### 1.1 模块组成

- **前端组件**：`interface-config.js` - 主组件
- **子组件**：
  - `toolbar.js` - 工具栏组件
  - `data-table.js` - 数据表格组件
  - `variable-form.js` - 变量表单组件
  - `import-dialog.js` - 导入对话框组件
- **后端路由**：
  - `routes/interface-config.js` - 接口管理 API
  - `routes/icd-import.js` - ICD 文件导入 API
- **工具类**：
  - `utils/data-interface-utils.js` - 数据接口操作工具
  - `utils/icd-parser.js` - ICD 文件解析工具

### 1.2 技术架构

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   前端组件层     │    │   后端API层      │    │   数据存储层     │
│                 │    │                 │    │                 │
│ interface-config│◄──►│ interface-config│◄──►│ SQLite数据库    │
│ toolbar         │    │ icd-import      │    │ DataInterface_* │
│ data-table      │    │                 │    │ 表              │
│ variable-form   │    │                 │    │                 │
│ import-dialog   │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

## 2. 功能

### 2.1 核心功能

1. **接口管理**

   - 接口的增删改查操作
   - 批量删除接口
   - 接口数据验证
2. **数据导入**

   - ICD Excel 文件导入
   - 批量数据导入
   - 导入数据预览和确认
3. **数据展示**

   - 分页表格显示
   - 搜索和过滤
   - 高级搜索（多条件组合）
4. **配置管理**

   - 构型关联管理
   - ATA 章节管理
   - 机型管理

### 2.2 辅助功能

1. **数据验证**

   - 必填字段验证
   - 数据类型验证
   - 唯一性验证
2. **用户体验**

   - 加载状态提示
   - 错误信息展示
   - 操作确认对话框

## 3. 性能

### 3.1 性能指标

- **响应时间**：接口查询 < 500ms，数据导入 < 5s
- **并发处理**：支持多用户同时操作
- **数据量支持**：单次导入支持 1000+条记录
- **内存使用**：前端组件内存占用 < 50MB

### 3.2 性能优化策略

1. **数据库优化**

   - 使用索引优化查询性能
   - 批量操作减少数据库交互次数
2. **前端优化**

   - 虚拟滚动处理大量数据
   - 分页加载减少初始渲染时间
   - 防抖处理搜索输入
3. **文件处理优化**

   - 流式处理大文件
   - 临时文件及时清理

## 4. 输入

### 4.1 用户输入

1. **接口定义数据**

   ```
   {
     SystemName: "XNSim",
     PlaneName: "机型名称",
     ATAName: "ATA章节",
     ModelStructName: "模型结构名称",
     InterfaceName: "接口名称",
     InterfaceType: "接口类型",
     InterfaceOption: 1,
     InterfaceIsArray: true/false,
     InterfaceArraySize_1: 10,
     InterfaceArraySize_2: 0,
     InterfaceNotes: "备注信息",
     ConfID: "构型ID"
   }
   ```
2. **搜索条件**

   - 关键词搜索
   - 高级搜索条件（机型、ATA 章节、结构体名称）
3. **文件输入**

   - ICD Excel 文件（.xlsx 格式）
   - 文件大小限制：< 10MB

### 4.2 系统输入

1. **构型选择**

   - 从 localStorage 获取当前选择的构型 ID
   - 构型信息包含 configurationId
2. **配置数据**

   - ATA 章节列表
   - 机型列表
   - 结构体列表

## 5. 输出

### 5.1 数据输出

1. **接口列表**

   ```json
   [
     {
       "SystemName": "XNSim",
       "PlaneName": "机型名称",
       "ATAName": "ATA章节",
       "ModelStructName": "模型结构名称",
       "InterfaceName": "接口名称",
       "InterfaceType": "接口类型",
       "InterfaceOption": 1,
       "InterfaceIsArray": true,
       "InterfaceArraySize_1": 10,
       "InterfaceArraySize_2": 0,
       "InterfaceNotes": "备注信息"
     }
   ]
   ```
2. **操作结果**

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

   ```json
   {
     "success": true,
     "results": [
       { "success": true, "data": {} },
       { "success": false, "error": "错误信息", "data": {} }
     ],
     "message": "导入完成，成功: 10, 失败: 2"
   }
   ```

### 5.2 界面输出

1. **数据表格**：分页显示接口列表
2. **表单界面**：接口编辑表单
3. **导入对话框**：导入数据预览和确认
4. **状态提示**：操作成功/失败提示

## 6. 算法

### 6.1 ICD 文件解析算法

```
1. 读取Excel文件
2. 验证工作表结构（Inputs/Outputs）
3. 解析每个工作表：
   - 提取变量名称
   - 解析数组维度
   - 处理变量类型映射
   - 生成标准格式数据
4. 合并Inputs和Outputs数据
5. 返回解析结果
```

### 6.2 数组维度解析算法

```
输入：维度字符串（如"[10]"、"[3][2]"、"10"）
输出：{isArray: boolean, arraySize1: number, arraySize2: number}

1. 检查空值或1的情况 → 返回非数组
2. 匹配方括号格式 [数字][数字] → 提取维度
3. 匹配纯数字格式 → 提取一维数组大小
4. 其他情况 → 返回非数组
```

### 6.3 搜索过滤算法

```
1. 关键词搜索：
   - 在接口名称、备注等字段中模糊匹配
   - 支持大小写不敏感搜索

2. 高级搜索：
   - 多条件AND组合
   - 支持机型、ATA章节、结构体名称精确匹配
   - 支持接口类型、数组类型条件过滤
```

## 7. 流程

### 7.1 接口管理主流程

```mermaid
graph TD
    A[用户进入接口配置页面] --> B[检查构型选择]
    B --> C{是否已选择构型?}
    C -->|否| D[提示选择构型]
    C -->|是| E[加载接口数据]
    E --> F[显示数据表格]
    F --> G[用户操作]
    G --> H{操作类型}
    H -->|添加| I[打开添加表单]
    H -->|编辑| J[打开编辑表单]
    H -->|删除| K[确认删除]
    H -->|导入| L[选择文件导入]
    I --> M[保存接口]
    J --> M
    K --> N[删除接口]
    L --> O[解析文件]
    M --> P[刷新数据]
    N --> P
    O --> Q[预览导入数据]
    Q --> R[确认导入]
    R --> P
    P --> F
```

### 7.2 数据导入流程

```mermaid
graph TD
    A[用户选择ICD文件] --> B[上传文件到服务器]
    B --> C[解析Excel文件]
    C --> D[验证数据格式]
    D --> E{数据是否有效?}
    E -->|否| F[返回错误信息]
    E -->|是| G[生成预览数据]
    G --> H[显示导入对话框]
    H --> I[用户确认导入]
    I --> J[批量保存到数据库]
    J --> K[返回导入结果]
    K --> L[刷新界面数据]
```

### 7.3 搜索过滤流程

```mermaid
graph TD
    A[用户输入搜索条件] --> B{搜索类型}
    B -->|关键词搜索| C[模糊匹配过滤]
    B -->|高级搜索| D[多条件组合过滤]
    C --> E[更新表格显示]
    D --> E
    E --> F[显示过滤结果]
    F --> G[更新分页信息]
```

## 8. 接口

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

1. GET /api/planes1）功能：获取机型列表；2）输入：无参数；3）输出：JSON 对象{ success: boolean, message: string, data:array}；4）说明：返回所有可用机型信息，包含机型图标、名称和描述。
2. GET /api/interface/list1）功能：获取接口列表；2）输入：confID（构型 ID，查询参数）；3）输出：JSON 对象{ success: boolean, message: string, data: array }；4）说明：返回指定构型下的所有接口数据。
3. POST /api/interface/add1）功能：添加接口；2）输入：JSON 对象，包含接口定义的所有字段；3）输出：JSON 对象{ success: boolean, message: string, id: number }；4）说明：添加新的接口记录，接口名称需唯一。
4. PUT /api/interface/update1）功能：更新接口；2）输入：JSON 对象，包含 currentData 和 originalData；3）输出：JSON 对象{ success: boolean, message: string }；4）说明：根据原始数据定位并更新接口信息。
5. DELETE /api/interface/delete1）功能：删除接口；2）输入：interfaceName（接口名称，查询参数），confID（构型 ID，查询参数）；3）输出：JSON 对象{ success: boolean, message: string }；4）说明：删除指定接口。
6. POST /api/interface/import1）功能：批量导入接口；2）输入：JSON 数组，每项为接口定义对象；3）输出：JSON 对象{ success: boolean, message: string, results: array }；4）说明：批量导入接口，返回每条数据的处理结果。
7. GET /api/interface/struct/list1）功能：获取接口结构体列表；2）输入：systemName、planeName、ataName、confID（查询参数）；3）输出：JSON 对象{ success: boolean, message: string, data: array }；4）说明：返回符合条件的结构体名称列表。
8. POST /api/icd/import
   1）功能：导入 ICD 文件并解析；
   2）输入：form-data 格式，file 为 Excel 文件；
   3）输出：JSON 对象{ success: boolean, message: string, data: array }；
   4）说明：解析 ICD Excel 文件，返回变量信息预览。