The first commit

docs/project_class_interaction.md

@@ -0,0 +1,133 @@
+# 项目功能类调用关系说明 (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*