# 上位机控制程序设计文档

## 1. 程序架构设计

采用MVC模式设计，主要分为以下模块：

### 1.0 系统架构图
```mermaid
graph TD
    A[用户界面] -->|控制指令| B[控制器]
    B -->|发送命令| C[通信模块]
    C -->|UDP协议| D[下位机]
    D -->|状态反馈| C
    C -->|解析数据| B
    B -->|更新状态| A
    B -->|记录数据| E[数据库]
```

### 1.1 消息处理流程
1. 接收原始UDP数据
2. 根据消息ID选择解析器
3. 验证校验码
4. 解析为结构化数据
5. 触发状态更新事件
6. 存储到数据库

### 1.1 通信模块 (Model) - 详细设计

#### 消息类型映射表
| 消息ID | 消息名称 | 处理函数 | 更新频率 |
|--------|----------|----------|----------|
| 0x0005 | 高压母线状态 | parse_high_vol_bus | 1Hz |
| 0x0006 | 高压A母线状态 | parse_high_a_vol_bus | 1Hz |
| 0x0007 | 低压主母线状态 | parse_low_main_bus | 1Hz |
| 0x0008 | 低压汇流排状态 | parse_low_bus | 1Hz |

#### 异常处理机制
1. 校验失败：丢弃数据并记录错误日志
2. 超时处理：3次重试后标记设备离线
3. 数据异常：触发告警并显示在界面
```python
class UDPMessageHandler:
    """UDP消息处理基类"""
    def __init__(self, ip, port):
        self.ip = ip
        self.port = port
        self.socket = None
        
    def connect(self):
        """建立UDP连接"""
        pass
        
    def send_message(self, msg):
        """发送消息"""
        pass
        
    def receive_message(self):
        """接收消息"""
        pass
        
    def close(self):
        """关闭连接"""
        pass

class PowerMessageHandler(UDPMessageHandler):
    """电源管理专用消息处理器"""
    def __init__(self, ip, port):
        super().__init__(ip, port)
        self.message_parsers = {
            0x0005: self.parse_high_vol_bus,
            0x0006: self.parse_high_a_vol_bus,
            # 其他消息类型...
        }
        
    def parse_high_vol_bus(self, data):
        """解析高压母线消息"""
        pass
        
    # 其他消息解析方法...
```

### 1.2 界面模块 (View) - 详细设计

#### 主界面布局
```mermaid
graph LR
    A[标题栏] --> B[状态区]
    B --> C[电压电流仪表盘]
    B --> D[断路器状态指示灯]
    A --> E[控制区]
    E --> F[电源控制按钮组]
    E --> G[参数设置面板]
    A --> H[日志区]
    H --> I[实时消息列表]
    H --> J[历史记录查询]
```

#### 组件说明
1. 电压电流仪表盘：实时显示各母线电压电流值
2. 断路器状态指示灯：绿色-闭合，红色-断开
3. 电源控制按钮组：带防误触保护(需长按3秒)
4. 参数设置面板：输入验证和范围检查
```python
class MainWindow(tk.Tk):
    """主窗口"""
    def __init__(self):
        super().__init__()
        self.title("电源管理系统")
        self.geometry("1200x800")
        
        self.create_widgets()
        
    def create_widgets(self):
        """创建界面组件"""
        self.status_frame = StatusFrame(self)
        self.control_frame = ControlFrame(self)
        self.log_frame = LogFrame(self)
        
        # 布局管理
        self.status_frame.pack(side=tk.TOP, fill=tk.X)
        self.control_frame.pack(side=tk.LEFT, fill=tk.Y)
        self.log_frame.pack(side=tk.RIGHT, expand=True, fill=tk.BOTH)

class StatusFrame(tk.Frame):
    """状态显示面板"""
    def update_status(self, data):
        """更新状态显示"""
        pass

class ControlFrame(tk.Frame):
    """控制面板"""
    def create_buttons(self):
        """创建控制按钮"""
        pass
```

### 1.3 控制器模块 (Controller) - 详细设计

#### 状态管理机制
1. 使用有限状态机(FSM)管理电源系统状态
2. 状态转换规则：
   - 仅当所有预检通过才允许上电
   - 故障时自动进入安全状态
   - 人工确认后才能复位

#### 命令处理流程
```mermaid
sequenceDiagram
    用户->>界面: 点击控制按钮
    界面->>控制器: 发送控制命令
    控制器->>业务逻辑: 验证命令有效性
    业务逻辑->>通信模块: 发送UDP指令
    通信模块->>下位机: 传输控制报文
    下位机-->>通信模块: 返回应答
    通信模块->>控制器: 更新命令状态
    控制器->>界面: 显示操作结果
    控制器->>数据库: 记录操作日志
```
```python
class PowerManagerController:
    """主控制器"""
    def __init__(self):
        self.message_handler = PowerMessageHandler("192.168.1.100", 5000)
        self.view = MainWindow()
        
        # 绑定事件
        self.bind_events()
        
    def bind_events(self):
        """绑定UI事件"""
        self.view.control_frame.on_button_click = self.handle_control_command
        
    def handle_control_command(self, cmd):
        """处理控制命令"""
        pass
        
    def start(self):
        """启动应用程序"""
        self.message_handler.connect()
        self.view.mainloop()
```

## 2. 接口规范

### 2.1 模块交互架构
```mermaid
classDiagram
    class Communication {
        +send_command(cmd: dict) bool
        +get_status() dict
        +subscribe(callback: function)
        +on_message_received(data: bytes)
    }
    
    class Controller {
        +handle_ui_event(event: dict)
        +update_system_status(status: dict)
        +log_operation(log: dict)
    }
    
    class UI {
        +update_status(data: dict)
        +show_alert(level: int, msg: str)
        +log_message(source: str, msg: str)
    }
    
    Communication --> Controller : 状态更新通知
    Controller --> UI : 界面更新指令
    UI --> Controller : 用户操作事件
```

### 2.2 详细接口定义

#### 通信模块 → 控制器
```python
# 状态更新通知
{
    "msg_type": "status_update",
    "timestamp": "2025-05-04T10:20:00",
    "data": {
        "voltage": 220.5,
        "current": 15.2,
        "breaker_state": True
    }
}

# 错误通知
{
    "msg_type": "error",
    "code": 1001,
    "message": "校验失败"
}
```

#### 控制器 → 界面
```python
# 状态显示更新
{
    "component": "voltage_meter",
    "value": 220.5,
    "unit": "V",
    "normal_range": [210, 230]
}

# 告警信息
{
    "level": 2,  # 1-警告 2-错误 3-严重
    "message": "A相电压过高",
    "suggestion": "检查A相负载"
}
```

#### 界面 → 控制器
```python
# 按钮操作事件
{
    "event_type": "button_click",
    "button_id": "power_on",
    "timestamp": "2025-05-04T10:20:01"
}

# 参数设置事件
{
    "event_type": "param_set",
    "param": "voltage_limit",
    "value": 230,
    "unit": "V"
}
```

### 2.3 错误处理规范
1. 通信错误：自动重试3次后通知控制器
2. 业务逻辑错误：记录详细日志并通知界面
3. 界面错误：显示友好提示并保持最后正常状态

## 3. 数据库设计
(之前已完成的数据库表结构...)