lc_frontend/README_API_MOCK.md

大屏数据模拟接口系统

概述

本项目实现了一个完整的大屏数据模拟接口系统，用于替代硬编码的数据，实现数据的动态获取和更新。

文件结构

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. 初始化数据

// 在组件挂载时初始化
onMounted(async () => {
  try {
    await initDashboardData()
    // 初始化图表等其他操作
  } catch (error) {
    console.error('初始化失败:', error)
  }
})

2. 定期更新数据

// 设置定时器，定期从API获取新数据
setInterval(async () => {
  await updateDashboardDataFromAPI()
}, 15000) // 每15秒更新一次

3. 数据绑定

<template>
  <!-- 使用可选链操作符安全访问数据 -->
  <span>{{ dashboardData?.totalCount || 0 }}</span>
  <span>{{ dashboardData?.alertData.total || 0 }}</span>
</template>

数据结构

DashboardData 接口

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调用

示例

添加新的数据字段

// 在 DashboardData 接口中添加
interface DashboardData {
  // ... 现有字段
  newField: string
}

// 在模拟数据中添加
const mockData: DashboardData = {
  // ... 现有数据
  newField: '示例值'
}

// 在组件中使用
<span>{{ dashboardData?.newField || '' }}</span>

添加新的API接口

// 在 dashboard.ts 中添加
export const getNewData = async (): Promise<string> => {
  await delay(200)
  return '新数据'
}

// 在组件中调用
const newData = await getNewData()

这个模拟接口系统为后续的真实API集成提供了良好的基础，同时保持了代码的可维护性和扩展性。