init

2025-10-17 10:31:13 +08:00
commit e6e86f2ce0
1043 changed files with 1031839 additions and 0 deletions
--- a/README_API_MOCK.md
+++ b/README_API_MOCK.md
@@ -0,0 +1,206 @@
+# 大屏数据模拟接口系统
+
+## 概述
+
+本项目实现了一个完整的大屏数据模拟接口系统，用于替代硬编码的数据，实现数据的动态获取和更新。
+
+## 文件结构
+
+```
+src/
+├── api/
+│   └── dashboard.ts          # 模拟接口定义和数据
+└── views/screen/
+    └── mainScreenV1.vue      # 主大屏组件
+```
+
+## 核心功能
+
+### 1. 模拟接口 (`src/api/dashboard.ts`)
+
+#### 数据类型定义
+- `DashboardData`: 完整的大屏数据结构
+- 包含总计数量、园区统计、风险统计、告警数据、超时工单、隐患治理等
+
+#### 主要接口
+- `getDashboardData()`: 获取初始大屏数据
+- `updateDashboardData()`: 获取更新的随机数据（用于动画演示）
+- `getAlertDetails(type)`: 获取告警详情数据
+- `getParkStatistics()`: 获取园区统计数据
+- `getRiskStatistics()`: 获取风险统计数据
+- `getHiddenDangerData()`: 获取隐患治理数据
+
+### 2. 主组件集成 (`src/views/screen/mainScreenV1.vue`)
+
+#### 数据管理
+- 使用 `dashboardData` ref 存储从API获取的完整数据
+- 通过 `initDashboardData()` 初始化数据
+- 通过 `updateDashboardDataFromAPI()` 定期更新数据
+
+#### 图表集成
+- 所有图表数据都从 `dashboardData` 获取
+- 支持数据更新后的图表自动刷新
+- 保持原有的动画效果
+
+## 使用方法
+
+### 1. 初始化数据
+
+```typescript
+// 在组件挂载时初始化
+onMounted(async () => {
+  try {
+    await initDashboardData()
+    // 初始化图表等其他操作
+  } catch (error) {
+    console.error('初始化失败:', error)
+  }
+})
+```
+
+### 2. 定期更新数据
+
+```typescript
+// 设置定时器，定期从API获取新数据
+setInterval(async () => {
+  await updateDashboardDataFromAPI()
+}, 15000) // 每15秒更新一次
+```
+
+### 3. 数据绑定
+
+```vue
+<template>
+  <!-- 使用可选链操作符安全访问数据 -->
+  <span>{{ dashboardData?.totalCount || 0 }}</span>
+  <span>{{ dashboardData?.alertData.total || 0 }}</span>
+</template>
+```
+
+## 数据结构
+
+### DashboardData 接口
+
+```typescript
+interface DashboardData {
+  totalCount: number                    // 总计数量
+  formalEmployeeCount: number           // 正式员工数量
+  externalStaffCount: number            // 外协人员数量
+  visitorCount: number                  // 访客数量
+  
+  parkStatistics: {                     // 园区统计
+    name: string
+    formal: number
+    external: number
+    visitor: number
+  }[]
+  
+  riskStatistics: {                     // 风险统计
+    overdue: number                      // 已逾期
+    processed: number                    // 已处理
+    pending: number                      // 待排查
+    processing: number                   // 处理中
+    other: number                        // 其他
+  }
+  
+  alertData: {                          // 告警数据
+    total: number
+    processed: number
+    pending: number
+    details: AlertItem[]
+  }
+  
+  timeoutWorkOrders: {                  // 超时工单
+    total: number
+    details: AlertItem[]
+  }
+  
+  hiddenDangerData: {                   // 隐患治理数据
+    general: number                      // 一般隐患
+    major: number                        // 重大隐患
+    progress: {                          // 处理进度
+      overdue: number
+      processed: number
+      pending: number
+      processing: number
+    }
+    top3Types: {                         // Top3隐患类型
+      access: number                     // 门禁
+      consumption: number                // 消费
+      inspection: number                 // 巡检
+    }
+    safetyIndex: number                  // 安全指数
+  }
+}
+```
+
+## 优势
+
+### 1. 数据解耦
+- 将数据逻辑从组件中分离
+- 便于后续替换为真实API
+
+### 2. 类型安全
+- 完整的TypeScript类型定义
+- 编译时错误检查
+
+### 3. 模拟真实环境
+- 模拟网络延迟
+- 随机数据生成
+- 错误处理机制
+
+### 4. 易于扩展
+- 可以轻松添加新的数据字段
+- 支持多种数据更新策略
+
+## 替换为真实API
+
+当需要连接真实API时，只需要：
+
+1. 修改 `src/api/dashboard.ts` 中的接口调用
+2. 将模拟数据替换为真实的HTTP请求
+3. 保持接口签名不变
+4. 组件代码无需修改
+
+## 注意事项
+
+1. **数据加载状态**: 建议添加loading状态管理
+2. **错误处理**: 完善错误处理和用户提示
+3. **数据缓存**: 考虑添加数据缓存机制
+4. **性能优化**: 避免频繁的API调用
+
+## 示例
+
+### 添加新的数据字段
+
+```typescript
+// 在 DashboardData 接口中添加
+interface DashboardData {
+  // ... 现有字段
+  newField: string
+}
+
+// 在模拟数据中添加
+const mockData: DashboardData = {
+  // ... 现有数据
+  newField: '示例值'
+}
+
+// 在组件中使用
+<span>{{ dashboardData?.newField || '' }}</span>
+```
+
+### 添加新的API接口
+
+```typescript
+// 在 dashboard.ts 中添加
+export const getNewData = async (): Promise<string> => {
+  await delay(200)
+  return '新数据'
+}
+
+// 在组件中调用
+const newData = await getNewData()
+```
+
+这个模拟接口系统为后续的真实API集成提供了良好的基础，同时保持了代码的可维护性和扩展性。