# 项目功能类调用关系说明 (Project Class Interaction Documentation)

本主要介绍 `image_capture` 项目核心功能类之间的调用关系、数据流向以及模块划分。

## 1. 核心模块概览 (Core Modules Overview)

系统主要由以下几个核心模块组成：

*   **GUI 模块 (`MainWindow`)**: 程序的入口与界面显示，负责系统初始化。
*   **Vision 控制器 (`VisionController`)**: 系统的核心中枢，协调通信与任务管理。
*   **任务管理 (`TaskManager`)**: 负责具体的业务逻辑执行、算法调度和结果处理。
*   **设备管理 (`DeviceManager`)**: 负责相机等硬件设备的统一管理（单例模式）。
*   **通信模块 (`RedisCommunicator`)**: 负责与外部系统（如 WMS）通过 Redis 交互。
*   **算法模块 (`DetectionBase` 及其子类)**: 具体的图像处理算法。

## 2. 类调用关系图 (Class Interaction Diagram)

```mermaid
classDiagram
    class MainWindow {
        +VisionController vision_controller
        +init()
    }

    class VisionController {
        -shared_ptr<RedisCommunicator> redis_comm
        -shared_ptr<TaskManager> task_manager
        +start()
        +stop()
        -onTaskReceived()
    }

    class RedisCommunicator {
        +startListening()
        +writeDetectionResult()
        +setTaskCallback()
    }

    class TaskManager {
        -queue<RedisTaskData> task_queue
        -map detectors
        +handleTask()
        -executeDetectionTask()
        -getDetector(flag)
    }

    class DeviceManager {
        <<Singleton>>
        +getInstance()
        +getLatestImages()
        +startAll()
    }

    class DetectionBase {
        <<Abstract>>
        +execute(depth, color, ...)
    }

    class ConcreteDetection {
        +execute()
    }

    MainWindow --> VisionController : 拥有并管理
    VisionController --> RedisCommunicator : 管理 (监听/发送)
    VisionController --> TaskManager : 分发任务
    RedisCommunicator --> VisionController : 回调通知 (Callback)
    TaskManager ..> DeviceManager : 获取图像数据 (Dependency)
    TaskManager --> DetectionBase : 调用算法
    DetectionBase <|-- ConcreteDetection : 继承
```

## 3. 详细调用流程 (Detailed Call Flow)

### 3.1 系统初始化与启动 (Initialization & Startup)
1.  **Entry Point**: `main.cpp` 创建 `QApplication` 并实例化 `MainWindow`。
2.  **MainWindow**: 
    *   构造函数中初始化界面。
    *   调用 `DeviceManager::getInstance().initialize()` 扫描并初始化相机设备。
    *   实例化 `VisionController` 成员变量。
    *   调用 `VisionController::initialize()`，配置 Redis 连接参数。
    *   调用 `VisionController::start()` 启动后台服务。
3.  **VisionController**:
    *   在 `start()` 中调用 `RedisCommunicator::startListening()` 开启监听线程。

### 3.2 任务触发与执行 (Task Trigger & Execution)
当 Redis 中 `vision_task_flag` 发生变化时，流程如下：

1.  **RedisCommunicator**: 
    *   监听线程检测到 Flag 变化。
    *   通过回调函数 `VisionController::onTaskReceived` 通知控制器。
2.  **VisionController**:
    *   `onTaskReceived` 将接收到的 `RedisTaskData` 传递给 `TaskManager::handleTask`。
3.  **TaskManager**:
    *   `handleTask` 将任务推入内部的任务队列 `task_queue_`。
    *   工作线程 `taskExecutionThreadFunc` 从队列中取出任务。
    *   **获取图像**: 调用 `DeviceManager::getInstance().getLatestImages(...)` 获取当前最新的深度图和彩色图。
    *   **选择算法**: 根据任务 Flag 调用 `getDetector(flag)` 获取对应的算法实例（如 `PalletOffsetDetection`）。
    *   **执行算法**: 调用 `detector->execute(depth_img, color_img, ...)` 进行计算。
    *   **结果封装**: 将算法返回的数据填充到 `DetectionResult` 结构体中。

### 3.3 结果处理 (Result Handling)
算法执行完成后：

1.  **TaskManager**:
    *   调用 `processResult(result)`。
    *   该函数会格式化结果为 JSON 字符串，并计算报警/警告状态。
    *   调用 `redis_result_comm_->writeDetectionResult(json)` 将结果写入 Redis。
2.  **RedisCommunicator**:
    *   执行 Redis SET 命令，将 JSON 数据写入指定的 Key。

## 4. 关键类说明 (Key Class Descriptions)

### VisionController (`src/vision/vision_controller.h`)
*   **职责**: 作为系统的外观（Facade），对外提供统一的 start/stop 接口，对内协调 Redis 和 TaskManager。
*   **特点**: 它是 MainWindow 唯一直接交互的非 GUI 业务类。

### DeviceManager (`src/device/device_manager.h`)
*   **职责**: 屏蔽底层相机 SDK（Percipio / MVS）的差异，提供统一的图像获取接口。
*   **模式**: 单例模式 (Singleton)。确保系统中只有一份硬件控制实例。

### TaskManager (`src/task/task_manager.h`)
*   **职责**: 真正的“大脑”。负责任务的缓冲（队列）、图像获取、算法调度和结果回传。
*   **并发**: 拥有独立的执行线程，避免阻塞 Redis 监听线程或 GUI 线程。

### RedisCommunicator (`src/redis/redis_communicator.h`)
*   **职责**: 封装 Redis 的底层 socket 操作，提供易用的读写接口和异步监听机制。

### DetectionBase (`src/algorithm/core/detection_base.h`)
*   **职责**: 定义所有检测算法的统一接口 `execute`。
*   **扩展**: 新增算法只需继承此类并在 `TaskManager` 中注册即可。

---
*文档生成时间: 2025-12-29*