# Phase 3 界面重构技术设计文档

## 文档信息
- **创建日期**: 2024年12月
- **版本**: 1.0
- **作者**: CasualtySightPlus Team
- **状态**: 设计阶段

## 1. 界面架构分析

### 1.1 现有架构概述

**布局结构**:
```
┌──────────────────────────────────────────────────────────────┐
│                    Header (80px)                           │
│                 ◉ UBEES LOGO                              │
├───────────────┬─────────────────────┬──────────────────────┤
│ Left Panel    │    Center Panel     │    Right Panel       │
│ (250px)       │    (Dynamic)        │    (280px)           │
│               │                     │                      │
│ 🤖 机器人管理   │    🗺️ 地图显示      │  🎯 战场探索模块        │
│               │                     │                      │
│ - 机器人列表   │    (地图/背景)       │  - 无人机视角          │
│ - 机器人位置   │                     │  - 机器狗视角          │
│ - 添加机器人   │                     │  - 机器狗建图          │
│ - 显示地图     │                     │  - 智能导航           │
│ - 添加无人机   │                     │  - 情报传达           │
│ - 无人机列表   │                     │  - 人脸识别           │
│               │                     │  - 人脸跟随           │
└───────────────┴─────────────────────┴──────────────────────┘
```

### 1.2 现有代码架构

**文件结构**:
- `MainWindow.h/cpp`: 主界面逻辑
- `MainWindow.ui`: 界面布局定义
- 数据存储: `QVector<QPair<QString, QString>>` (内存中)

**主要问题**:
1. **数据持久化缺失**: 设备信息未与数据库集成
2. **界面陈旧**: 按钮式列表，缺乏现代化设备卡片设计
3. **状态显示不足**: 无法显示设备实时状态
4. **用户体验**: 缺乏直观的设备管理界面

## 2. 重构目标与设计原则

### 2.1 重构目标

1. **现代化设备卡片界面**: 实现类似参考图的设备卡片设计
2. **数据库集成**: 连接统一设备管理系统
3. **实时状态监控**: 显示设备在线状态、信号强度、位置信息
4. **用户体验提升**: 直观的操作界面和流畅的交互

### 2.2 设计原则

1. **保持现有布局**: 三栏式布局保持不变
2. **渐进式改进**: 逐步替换组件，确保系统稳定
3. **数据驱动**: 所有界面数据来源于数据库
4. **响应式设计**: 适配不同分辨率

## 3. 设备卡片组件设计

### 3.1 设备卡片UI设计

**设计规格**:
```
┌─────────────────────────────────────┐
│ 🚁 侦察机-01               [●在线]  │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ 📍 位置: N39.90, E116.40          │
│ 🌐 网络: 192.168.1.101:8080       │
│ 📶 信号: ████████░░ 80%           │
│ 🔋 电量: ██████████ 100%          │
│ ─────────────────────────────────── │
│ [📊 详情] [🎮 控制] [📍 定位]      │
└─────────────────────────────────────┘
```

**卡片属性**:
- 尺寸: 220px × 160px
- 圆角: 8px
- 阴影: 轻微投影效果
- 状态指示: 颜色编码的在线状态

### 3.2 设备状态指示系统

**状态色彩方案**:
```cpp
enum class DeviceStatus {
    Online,     // 绿色 #00FF7F
    Warning,    // 黄色 #FFD700  
    Offline,    // 红色 #FF4444
    Unknown     // 灰色 #888888
};
```

**信号强度显示**:
- 进度条式显示 (0-100%)
- 动态颜色: 强(绿) → 中(黄) → 弱(红)

## 4. 组件架构设计

### 4.1 新增组件结构

```
src/ui/components/
├── DeviceCard.h/cpp           # 设备卡片组件
├── DeviceCardWidget.h/cpp     # 设备卡片容器
├── DeviceStatusIndicator.h/cpp # 状态指示器组件
└── DeviceListPanel.h/cpp      # 设备列表面板
```

### 4.2 DeviceCard 组件设计

**类定义**:
```cpp
class DeviceCard : public QWidget
{
    Q_OBJECT
    
public:
    explicit DeviceCard(const DeviceInfo &device, QWidget *parent = nullptr);
    
    void updateDeviceStatus(const DeviceStatus &status);
    void updateSignalStrength(int strength);
    void updateBatteryLevel(int level);
    
signals:
    void deviceSelected(const QString &deviceId);
    void deviceControlRequested(const QString &deviceId);
    void deviceLocationRequested(const QString &deviceId);
    
private slots:
    void onDetailsClicked();
    void onControlClicked();
    void onLocationClicked();
    
private:
    void setupUI();
    void setupStyle();
    void updateStatusColor();
    
    DeviceInfo m_deviceInfo;
    DeviceStatus m_status;
    // UI components...
};
```

### 4.3 数据模型集成

**DeviceInfo 结构体**:
```cpp
struct DeviceInfo {
    QString id;
    QString name;
    QString type;        // "uav" or "dog"
    QString ipAddress;
    int port;
    double longitude;
    double latitude;
    DeviceStatus status;
    int signalStrength;
    int batteryLevel;
    QDateTime lastHeartbeat;
};
```

## 5. 数据库集成方案

### 5.1 数据获取策略

1. **初始加载**: 启动时从数据库加载所有设备
2. **实时更新**: 定时查询设备状态变化
3. **事件驱动**: 设备操作后立即更新界面

### 5.2 数据库接口设计

**DeviceManager 类**:
```cpp
class DeviceManager : public QObject
{
    Q_OBJECT
    
public:
    static DeviceManager* instance();
    
    QList<DeviceInfo> getAllDevices();
    DeviceInfo getDevice(const QString &deviceId);
    bool addDevice(const DeviceInfo &device);
    bool updateDevice(const DeviceInfo &device);
    bool removeDevice(const QString &deviceId);
    
signals:
    void deviceAdded(const DeviceInfo &device);
    void deviceUpdated(const DeviceInfo &device);
    void deviceRemoved(const QString &deviceId);
    void deviceStatusChanged(const QString &deviceId, DeviceStatus status);
    
private slots:
    void checkDeviceStatus();
    
private:
    QTimer *m_statusCheckTimer;
    UAVDatabase *m_uavDb;
    DogDatabase *m_dogDb;
};
```

## 6. 界面重构实施计划

### 6.1 实施阶段

**阶段1**: 设备卡片组件开发
- 创建 DeviceCard 组件
- 实现基本UI和样式
- 实现状态指示功能

**阶段2**: 数据库集成
- 创建 DeviceManager 类
- 集成现有数据库类
- 实现数据同步机制

**阶段3**: 左侧面板重构
- 替换现有按钮列表
- 实现设备卡片列表
- 添加搜索和过滤功能

**阶段4**: 交互功能完善
- 实现设备操作功能
- 添加上下文菜单
- 完善用户反馈

### 6.2 兼容性保证

1. **渐进式替换**: 保持现有功能正常运行
2. **数据兼容**: 兼容现有数据库结构
3. **接口保持**: 保持公有接口不变

## 7. 样式系统设计

### 7.1 设备卡片样式

**CSS样式定义**:
```css
/* 设备卡片基础样式 */
.device-card {
    background: qlineargradient(x1:0, y1:0, x2:0, y2:1,
                stop:0 rgba(45, 65, 95, 0.9),
                stop:1 rgba(25, 40, 65, 0.9));
    border: 2px solid rgba(82, 194, 242, 0.4);
    border-radius: 8px;
    padding: 12px;
    margin: 8px;
}

/* 在线状态 */
.device-card.online {
    border-color: rgba(0, 255, 127, 0.6);
}

/* 离线状态 */
.device-card.offline {
    border-color: rgba(255, 68, 68, 0.6);
}

/* 悬停效果 */
.device-card:hover {
    background: qlineargradient(x1:0, y1:0, x2:0, y2:1,
                stop:0 rgba(82, 194, 242, 0.3),
                stop:1 rgba(45, 120, 180, 0.3));
    border-color: rgba(82, 194, 242, 0.8);
}
```

### 7.2 状态指示器样式

**进度条样式**:
```css
QProgressBar {
    border: 1px solid rgba(82, 194, 242, 0.5);
    border-radius: 3px;
    background-color: rgba(25, 35, 45, 0.8);
    height: 8px;
}

QProgressBar::chunk {
    background: qlineargradient(x1:0, y1:0, x2:1, y2:0,
                stop:0 #00FF7F, stop:0.7 #FFD700, stop:1 #FF4444);
    border-radius: 3px;
}
```

## 8. 测试计划

### 8.1 单元测试

1. **设备卡片组件测试**: UI渲染、状态更新、事件响应
2. **数据管理器测试**: 数据库CRUD操作、状态同步
3. **样式系统测试**: 主题切换、响应式布局

### 8.2 集成测试

1. **界面交互测试**: 设备选择、操作响应、状态更新
2. **数据一致性测试**: 界面与数据库同步
3. **性能测试**: 大量设备时的渲染性能

## 9. 风险评估

### 9.1 技术风险

1. **性能风险**: 大量设备卡片的渲染性能
2. **兼容性风险**: 与现有代码的集成
3. **数据同步风险**: 实时状态更新的准确性

### 9.2 缓解策略

1. **虚拟滚动**: 对于大量设备使用虚拟列表
2. **增量更新**: 只更新变化的设备状态
3. **错误处理**: 完善的错误处理和用户提示

## 10. 后续扩展

### 10.1 高级功能

1. **设备分组**: 按类型、状态、位置分组显示
2. **搜索过滤**: 实时搜索和多条件过滤
3. **批量操作**: 选中多设备进行批量操作
4. **自定义视图**: 用户可定制的设备显示方式

### 10.2 移动端适配

1. **响应式设计**: 适配不同屏幕尺寸
2. **触摸优化**: 触摸友好的交互设计
3. **手势支持**: 滑动、缩放等手势操作

---

**备注**: 本设计文档将根据开发进度和用户反馈进行持续更新和优化。