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

```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集成提供了良好的基础，同时保持了代码的可维护性和扩展性。