bxztApp/packages/screen/src/views/3DSituationalAwarenessRefactor/README.md

# 3D态势感知应急驾驶舱 - 重构版

## 📋 项目概述

这是对从蓝湖导出的 `3DSituationalAwarenessCopy` 页面的完整重构版本，解决了原始代码的可维护性问题。

## ✨ 重构成果

### 改进前（原始代码）
- ❌ 792 行代码全在一个文件
- ❌ 使用 `group_1`、`block_1` 等无意义命名
- ❌ 硬编码像素值，不支持响应式
- ❌ 深层嵌套的 div 结构
- ❌ 绝对定位 + margin 混乱布局

### 改进后（重构代码）
- ✅ 拆分为 20+ 个独立组件
- ✅ 语义化命名，一目了然
- ✅ 使用 vw/vh/fs 响应式单位
- ✅ 清晰的组件层次结构
- ✅ CSS Grid + Flexbox 现代布局
- ✅ Vue 3 Composition API + `<script setup>`

## 📁 目录结构

```
3DSituationalAwarenessRefactor/
├── index.vue                          # 主页面入口
├── components/                        # 组件目录
│   ├── PageHeader.vue                 # 顶部导航栏
│   ├── LeftPanel/                     # 左侧面板
│   │   ├── index.vue                  # 面板容器
│   │   ├── DisasterAnalysis.vue       # 灾害分析
│   │   ├── ForcePreset.vue            # 力量预置
│   │   ├── ForceDispatch.vue          # 力量调度
│   │   └── CollaborationInfo.vue      # 协同信息
│   ├── MapViewer/                     # 地图区域
│   │   ├── index.vue                  # 地图容器
│   │   └── MapControls.vue            # 地图控制工具
│   ├── RightPanel/                    # 右侧面板
│   │   ├── index.vue                  # 面板容器
│   │   ├── DispatchCommand.vue        # 调度指挥
│   │   ├── VideoMonitorGrid.vue       # 视频监控网格
│   │   ├── VideoMonitorItem.vue       # 视频监控卡片
│   │   └── DispatchSuggestion.vue     # 调度建议
│   ├── shared/                        # 公共组件
│   │   ├── PanelHeader.vue            # 面板标题
│   │   ├── DataField.vue              # 数据字段
│   │   └── ActionButton.vue           # 操作按钮
│   └── Popups/                        # 弹窗组件
│       ├── PersonnelDetail.vue        # 应急人员详情
│       └── EmergencyCenterDetail.vue  # 应急中心详情
├── composables/                       # 组合式函数
│   ├── useDisasterData.js             # 灾害数据管理
│   ├── useForceDispatch.js            # 力量调度逻辑
│   └── useVideoMonitor.js             # 视频监控状态
├── assets/                            # 资源文件
│   ├── styles/
│   │   └── common.scss                # 公共样式
│   └── images/                        # 图片资源（需从Copy目录迁移）
├── constants.js                       # 常量定义
└── README.md                          # 本文档
```

## 🎯 核心功能模块

### 1. 顶部导航栏
- 返回驾驶舱按钮
- 系统标题
- 灾后现场实景入口
- 设置按钮

### 2. 左侧面板（灾害分析与调度）
- **快速感知（灾害分析）**：灾害类型、损坏方量、滑坡体尺寸、人员伤亡等
- **快速匹配（力量预置）**：应急装备、基地、人员统计，附近养护站列表
- **快速响应（力量调度）**：响应等级、智能应急方案、预计抢通时间
- **协同信息**：气象预警、公安部门、融媒体中心的实时信息

### 3. 中央地图区域
- 3D 地图展示（支持接入 Cesium、Mapbox GL JS 等）
- 地图标记点（应急人员、应急中心）
- 测量工具栏（模型对比、测量方量、测量位置/距离）

### 4. 右侧面板（现场处置）
- **调度指挥**：现场单兵/设备/无人机列表（标签页切换）
- **视频监控网格**：4 视角视频监控（单兵、无人机、指挥车外部/会议）
- **调度建议**：智能调度力量建议卡片

### 5. 弹窗组件
- **应急人员详情**：姓名、部门、位置、预计到达时间、联动操作
- **应急中心详情**：名称、行政等级、隶属单位、位置信息

## 🔧 技术栈

- **Vue 3**：Composition API + `<script setup>` 语法
- **SCSS**：样式预处理器
- **响应式设计**：vw/vh/fs 函数（项目统一方案）
- **状态管理**：Composables（组合式函数）
- **组件通信**：Props/Emits + Provide/Inject

## 📦 安装与使用

### 1. 图片资源迁移

**重要**：由于图片资源仍在原始目录，需要手动迁移或更新引用路径：

```bash
# 方案 1：复制图片到新目录
cp -r ../3DSituationalAwarenessCopy/assets/img/* ./assets/images/

# 方案 2：创建符号链接（开发环境）
ln -s ../3DSituationalAwarenessCopy/assets/img ./assets/images
```

### 2. 图片命名优化（可选）

原始图片命名为 `SketchPng...`，建议重命名为语义化名称：

```
SketchPng6e14... → map-background.png
SketchPng7ba5... → left-panel-bg.png
SketchPng9eb4... → disaster-type-icon.png
...
```

可以使用脚本批量重命名，或手动整理。

### 3. 启动项目

```bash
# 在项目根目录
pnpm dev:screen
```

访问路由：`/3d-situational-awareness-refactor`

## 🎨 样式规范

### CSS 变量（定义在 common.scss）
```scss
--primary-color: rgba(28, 161, 255, 1);      // 主色
--bg-dark: rgba(9, 22, 40, 1);               // 深色背景
--bg-panel: rgba(20, 53, 118, 1);            // 面板背景
--text-white: rgba(255, 255, 255, 1);        // 白色文字
--success-color: rgba(17, 187, 119, 1);      // 成功色
--warning-color: rgba(255, 128, 11, 1);      // 警告色
--danger-color: rgba(255, 6, 36, 1);         // 危险色
```

### 响应式单位
```scss
width: vw(564);      // 宽度
height: vh(200);     // 高度
font-size: fs(16);   // 字体大小
```

### BEM 命名规范
```scss
.disaster-analysis {
  &__content { }       // 元素
  &__row { }           // 元素
  &--active { }        // 修饰符
}
```

## 🚀 后续工作

### 必须完成
1. **图片资源迁移**：将原始图片复制到新目录并更新引用
2. **真实图片替换**：替换占位图片为设计稿中的实际图片
3. **API 对接**：实现真实数据接口对接

### 建议优化
1. **3D 地图集成**：接入 Cesium 或 Mapbox GL JS
2. **视频流接入**：实现真实视频流播放
3. **动画效果**：添加过渡动画和交互反馈
4. **性能优化**：按需加载、虚拟滚动等
5. **单元测试**：编写组件单元测试

## 📝 组件使用示例

### 使用 DataField 组件
```vue
<DataField
  label="灾害类型"
  value="边坡垮塌"
  icon="path/to/icon.png"
  color-type="danger"
/>
```

### 使用 ActionButton 组件
```vue
<ActionButton
  text="一键启动"
  type="primary"
  size="medium"
  icon="path/to/icon.png"
  @click="handleClick"
/>
```

### 使用 PanelHeader 组件
```vue
<PanelHeader title="快速感知" subtitle="「灾害分析」">
  <template #extra>
    <button>额外操作</button>
  </template>
</PanelHeader>
```

## 🔍 对比原始代码

### 原始代码片段（不可维护）
```vue
<div class="group_3 flex-col">
  <div class="section_1 flex-row">
    <div class="block_1 flex-row justify-between">
      <img class="thumbnail_1" src="..." />
      <span class="text_1">返回驾驶舱</span>
    </div>
  </div>
</div>
```

### 重构后代码（清晰可维护）
```vue
<PageHeader @back="handleBack">
  <template #left>
    <button class="back-btn">
      <img class="back-icon" src="..." />
      <span class="back-text">返回驾驶舱</span>
    </button>
  </template>
</PageHeader>
```

## 📊 重构统计

| 指标 | 改进前 | 改进后 | 提升 |
|------|--------|--------|------|
| 单文件行数 | 792 行 | < 200 行/组件 | 75% ↓ |
| 组件数量 | 1 个 | 20+ 个 | - |
| 样式可读性 | 低 | 高 | 显著提升 |
| 代码可维护性 | 差 | 优 | 显著提升 |
| 响应式支持 | 无 | 完整 | 新增 |

## 👥 团队协作建议

1. **组件开发**：每个组件由独立开发者维护
2. **样式规范**：严格遵循 BEM 命名和响应式单位
3. **代码审查**：确保组件职责单一，可复用性高
4. **文档更新**：新增组件或修改 API 时及时更新文档

## 📞 联系方式

如有问题或建议，请联系项目负责人。

---

**重构完成日期**：2025-11-14
**重构版本**：v1.0.0