Initial_commit_SecMPS_v2

warehouse/docs/钥匙管理组件/DESIGN_钥匙管理组件.md

@@ -0,0 +1,126 @@
+# 钥匙管理组件 - 设计文档
+
+## 整体架构图
+
+```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. **用户操作错误**：
+   - 提供友好的错误提示
+   - 限制用户的非法操作