# 钥匙管理组件 - 设计文档

## 整体架构图

```mermaid
flowchart TD
    A[用户界面] --> B[KeyInfo组件]
    B --> C1[钥匙柜选择模块]
    B --> C2[钥匙矩阵展示模块]
    B --> C3[操作历史Dialog模块]
    B --> D[API请求服务]
    D --> E1[/api/warehouse_keys/GetPageData]
    D --> E2[/api/warehouse_keylog/GetPageData]
```

## 分层设计

### 1. 表现层
- **钥匙柜选择区域**：使用ElementPlus的`<el-select>`组件实现下拉选择功能
- **钥匙矩阵展示区域**：自定义组件实现方格矩阵展示，包含序号和钥匙图标
- **操作历史Dialog**：使用ElementPlus的`<el-dialog>`和`<el-table>`组件展示钥匙操作历史

### 2. 业务逻辑层
- **数据处理逻辑**：处理API返回的数据，提取需要展示的信息
- **状态管理逻辑**：管理组件的各种状态，如选中的钥匙柜、Dialog显示状态等
- **事件处理逻辑**：处理用户交互事件，如选择钥匙柜、点击钥匙图标等

### 3. 数据访问层
- **API请求封装**：封装对后端API的调用，处理请求参数和响应数据

## 模块依赖关系图

```mermaid
flowchart TD
    KeyInfo[KeyInfo组件] --> KeyCabinetSelector[钥匙柜选择器]
    KeyInfo --> KeyMatrix[钥匙矩阵展示]
    KeyInfo --> KeyLogDialog[操作历史Dialog]
    KeyInfo --> HttpService[HTTP请求服务]
    KeyMatrix --> KeyPosition[钥匙位置组件]
    KeyLogDialog --> KeyLogTable[操作历史表格]
```

## 接口契约定义

### 1. 钥匙数据接口

**请求参数**：
```javascript
{
  "page": 0
}
```

**响应格式**：
```javascript
{
  "status": 0,
  "msg": null,
  "total": number,
  "rows": [KeyData],
  "summary": null,
  "extra": null
}
```

### 2. 钥匙操作记录接口

**请求参数**：
```javascript
{
  "page": 0,
  "wheres": "KeyId=1"
}
```

**响应格式**：
```javascript
{
  "status": 0,
  "msg": null,
  "total": number,
  "rows": [KeyLog],
  "summary": null,
  "extra": null
}
```

## 数据流向图

```mermaid
sequenceDiagram
    participant User as 用户
    participant KeyInfo as KeyInfo组件
    participant Http as HTTP服务
    participant API as 后端API
    participant Dialog as 操作历史Dialog

    User->>KeyInfo: 选择钥匙柜
    KeyInfo->>Http: 请求钥匙数据
    Http->>API: POST /api/warehouse_keys/GetPageData
    API-->>Http: 返回钥匙数据
    Http-->>KeyInfo: 处理后的数据
    KeyInfo->>KeyInfo: 更新钥匙矩阵显示
    User->>KeyInfo: 点击钥匙图标
    KeyInfo->>Http: 请求操作记录
    Http->>API: POST /api/warehouse_keylog/GetPageData
    API-->>Http: 返回操作记录
    Http-->>KeyInfo: 处理后的数据
    KeyInfo->>Dialog: 显示操作历史
    Dialog-->>User: 展示操作记录表格
```

## 异常处理策略

1. **API请求失败**：
   - 显示错误提示信息
   - 提供重试机制
   - 记录错误日志

2. **数据格式错误**：
   - 提供默认数据
   - 确保组件不会因为数据问题而崩溃

3. **用户操作错误**：
   - 提供友好的错误提示
   - 限制用户的非法操作