bxztApp/packages/screen/src/views/cockpit/README.md

安全保通服务大屏 - 重构说明

📦 重构概览

本次重构将原来 567 行的单一组件拆分为模块化的组件架构，提高了代码的可维护性和可扩展性。

🎯 主要改进

1. 组件化架构

• ✅ 将单一大文件拆分为 7 个独立组件
• ✅ 每个组件职责单一,易于维护
• ✅ 组件可复用,便于扩展

2. 布局方式优化

• ❌ 重构前: 大量使用 position: absolute 和固定像素定位
• ✅ 重构后: 使用 CSS Grid 和 Flexbox 实现响应式布局
• ✅ 更易调整和适配不同屏幕尺寸

3. 数据驱动

• ❌ 重构前: 数据硬编码在模板中
• ✅ 重构后: 使用 Vue 3 Composition API,数据驱动渲染
• ✅ 便于后续接入真实 API 数据

4. 样式管理

• ❌ 重构前: 类名混乱 (box_1, group_3 等)
• ✅ 重构后: 语义化类名,易于理解
• ✅ 样式模块化,避免全局污染

📁 目录结构

cockpit/
├── index.vue                     # 主入口文件
├── components/                   # 组件目录
│   ├── CockpitLayout.vue         # 主布局组件
│   ├── PageHeader.vue            # 页面头部
│   ├── WeatherWarning.vue        # 气象预警 (左上)
│   ├── EmergencyResources.vue    # 应急资源 (左下)
│   ├── BlockEvent.vue            # 阻断事件 (右上)
│   ├── YearStatistics.vue        # 往年统计 (右下)
│   └── MapCenter.vue             # 中间地图区域
└── assets/                       # 资源文件
    └── img/                      # 图片资源

🔧 组件说明

1. CockpitLayout.vue (主布局)

使用 CSS Grid 三列布局:

grid-template-columns: 580px 1fr 580px;

• 左侧面板: 固定 580px
• 中间地图: 自适应剩余空间
• 右侧面板: 固定 580px

2. PageHeader.vue (页面头部)

• 居中显示标题 "安全保通服务"
• 右侧应用按钮
• 使用 Flexbox 布局

3. WeatherWarning.vue (气象预警)

数据结构:

{
  warningLevels: [
    { id, name, count, color, icon }
  ],
  districts: [
    { id, name, km, warning, warningColor }
  ]
}

功能:

• 四级预警图标展示 (蓝/黄/橙/红)
• 海拔800米以上气象情况
• 区县预警列表

4. EmergencyResources.vue (应急资源)

数据结构:

{
  resources: [
    { id, name, stations, supplies, equipment, equipmentClass, hasAlert }
  ]
}

功能:

• 展示各区县应急资源数量
• 服务站点、应急物资、应急设备统计
• 异常状态图标提示

5. BlockEvent.vue (阻断事件)

数据结构:

{
  stats: [
    { id, title, value }
  ]
}

功能:

• 统计卡片展示 (2列网格布局)
• 当前封闭交通、限速通行、抢通等数据

6. YearStatistics.vue (往年统计)

功能:

• 冰雪事件趋势图 (当前使用静态图片)
• 图表图例
• 坐标轴标签

TODO: 集成 ECharts 实现动态图表

7. MapCenter.vue (中间地图)

功能:

• 顶部功能按钮 (服务站点/预警路段/气象预警)
• 地图标记点
• 底部菜单 (应急体系/重大事件处置等)
• 中央功能菜单

TODO: 集成实际地图 API (如高德地图/百度地图)

🚀 使用方式

1. 基础使用

<template>
  <CockpitLayout />
</template>

<script setup>
import CockpitLayout from './components/CockpitLayout.vue'
</script>

2. 修改数据

每个组件都使用 ref 定义响应式数据,可以直接修改:

// WeatherWarning.vue
const districts = ref([
  { id: 1, name: '万州区', km: 32, warning: '红色预警', warningColor: 'rgba(229, 37, 42, 1)' }
])

3. 接入 API

将静态数据改为 API 调用:

import { ref, onMounted } from 'vue'
import { fetchDistricts } from '@/api/weather'

const districts = ref([])

onMounted(async () => {
  districts.value = await fetchDistricts()
})

📊 后续优化建议

1. 集成真实地图

推荐使用:

• 高德地图 API
• 百度地图 API
• Mapbox GL

2. 集成图表库

推荐使用:

• ECharts (功能强大,配置灵活)
• Chart.js
• D3.js

示例代码:

import * as echarts from 'echarts'

onMounted(() => {
  const chart = echarts.init(chartRef.value)
  chart.setOption({
    xAxis: { data: xAxisYears.value },
    yAxis: {},
    series: [
      { type: 'line', data: [1000, 2000, 3000, 4000, 5000] }
    ]
  })
})

3. 添加响应式适配

使用媒体查询或 vw/vh 单位适配不同屏幕:

@media (max-width: 1920px) {
  .cockpit-main {
    grid-template-columns: 450px 1fr 450px;
  }
}

4. 添加数据刷新

使用定时器或 WebSocket 实现实时数据更新:

import { useIntervalFn } from '@vueuse/core'

useIntervalFn(() => {
  refreshData()
}, 30000) // 每30秒刷新

5. 添加交互功能

• 地图标记点击事件
• 表格行点击查看详情
• 图表数据筛选
• 时间范围选择

6. 性能优化

• 使用虚拟滚动处理大量数据
• 图片懒加载
• 组件懒加载

const MapCenter = defineAsyncComponent(() =>
  import('./components/MapCenter.vue')
)

⚠️ 注意事项

1. 图片路径: 确保所有图片资源存在于 assets/img/ 目录中
2. 字体文件: 部分组件使用自定义字体,需要确保字体文件已引入
3. 浏览器兼容: Grid 布局需要现代浏览器支持 (IE11+ 需要 polyfill)

🎨 布局对比

重构前

├── 嵌套10层+ div
├── position: absolute 定位超过50处
├── 固定 margin/left/top 值
└── 567行单文件

重构后

├── 语义化组件结构
├── Grid + Flexbox 布局
├── 响应式设计理念
└── 7个模块化组件,平均每个约150行

📝 版本历史

• v2.0 (2025-01-XX) - 组件化重构,使用 Grid 布局
• v1.0 (之前) - 原始版本,单文件实现

🤝 贡献指南

1. 修改组件时保持单一职责原则
2. 新增功能优先考虑组件复用
3. 样式使用 scoped,避免全局污染
4. 数据结构清晰,便于接入 API

---

如有问题或建议,请联系开发团队。