From 14bc2e6cdab2897f275293bc2a880c05a51dea40 Mon Sep 17 00:00:00 2001 From: Junhan Chang Date: Thu, 21 Aug 2025 10:09:57 +0800 Subject: [PATCH] Create workstation_architecture.md --- .../workstation_architecture.md | 378 ++++++++++++++++++ 1 file changed, 378 insertions(+) create mode 100644 docs/developer_guide/workstation_architecture.md diff --git a/docs/developer_guide/workstation_architecture.md b/docs/developer_guide/workstation_architecture.md new file mode 100644 index 00000000..3bdb52e2 --- /dev/null +++ b/docs/developer_guide/workstation_architecture.md @@ -0,0 +1,378 @@ +# 工作站基础架构设计文档 + +## 1. 整体架构图 + +```mermaid +graph TB + subgraph "工作站基础架构" + WB[WorkstationBase] + WB --> |继承| RPN[ROS2ProtocolNode] + WB --> |组合| WCB[WorkstationCommunicationBase] + WB --> |组合| MMB[MaterialManagementBase] + WB --> |组合| WHS[WorkstationHTTPService] + end + + subgraph "通信层实现" + WCB --> |实现| PLC[PLCCommunication] + WCB --> |实现| SER[SerialCommunication] + WCB --> |实现| ETH[EthernetCommunication] + end + + subgraph "物料管理实现" + MMB --> |实现| PLR[PyLabRobotMaterialManager] + MMB --> |实现| BIO[BioyondMaterialManager] + MMB --> |实现| SIM[SimpleMaterialManager] + end + + subgraph "HTTP服务" + WHS --> |处理| LIMS[LIMS协议报送] + WHS --> |处理| MAT[物料变更报送] + WHS --> |处理| ERR[错误处理报送] + end + + subgraph "具体工作站实现" + WB --> |继承| WS1[PLCWorkstation] + WB --> |继承| WS2[ReportingWorkstation] + WB --> |继承| WS3[HybridWorkstation] + end + + subgraph "外部系统" + EXT1[PLC设备] --> |通信| PLC + EXT2[外部工作站] --> |HTTP报送| WHS + EXT3[LIMS系统] --> |HTTP报送| WHS + EXT4[Bioyond物料系统] --> |查询| BIO + end +``` + +## 2. 类关系图 + +```mermaid +classDiagram + class WorkstationBase { + <> + +device_id: str + +communication: WorkstationCommunicationBase + +material_management: MaterialManagementBase + +http_service: WorkstationHTTPService + +workflow_status: WorkflowStatus + +supported_workflows: Dict + + +_create_communication_module()* + +_create_material_management_module()* + +_register_supported_workflows()* + + +process_step_finish_report() + +process_sample_finish_report() + +process_order_finish_report() + +process_material_change_report() + +handle_external_error() + + +start_workflow() + +stop_workflow() + +get_workflow_status() + +get_device_status() + } + + class ROS2ProtocolNode { + +sub_devices: Dict + +protocol_names: List + +execute_single_action() + +create_ros_action_server() + +initialize_device() + } + + class WorkstationCommunicationBase { + <> + +config: CommunicationConfig + +is_connected: bool + +connect() + +disconnect() + +start_workflow()* + +stop_workflow()* + +get_device_status()* + +write_register() + +read_register() + } + + class MaterialManagementBase { + <> + +device_id: str + +deck_config: Dict + +resource_tracker: DeviceNodeResourceTracker + +plr_deck: Deck + +find_materials_by_type() + +update_material_location() + +convert_to_unilab_format() + +_create_resource_by_type()* + } + + class WorkstationHTTPService { + +workstation_instance: WorkstationBase + +host: str + +port: int + +start() + +stop() + +_handle_step_finish_report() + +_handle_material_change_report() + } + + class PLCWorkstation { + +plc_config: Dict + +modbus_client: ModbusTCPClient + +_create_communication_module() + +_create_material_management_module() + +_register_supported_workflows() + } + + class ReportingWorkstation { + +report_handlers: Dict + +_create_communication_module() + +_create_material_management_module() + +_register_supported_workflows() + } + + WorkstationBase --|> ROS2ProtocolNode + WorkstationBase *-- WorkstationCommunicationBase + WorkstationBase *-- MaterialManagementBase + WorkstationBase *-- WorkstationHTTPService + + PLCWorkstation --|> WorkstationBase + ReportingWorkstation --|> WorkstationBase + + WorkstationCommunicationBase <|-- PLCCommunication + WorkstationCommunicationBase <|-- DummyCommunication + + MaterialManagementBase <|-- PyLabRobotMaterialManager + MaterialManagementBase <|-- SimpleMaterialManager +``` + +## 3. 工作站启动时序图 + +```mermaid +sequenceDiagram + participant APP as Application + participant WS as WorkstationBase + participant COMM as CommunicationModule + participant MAT as MaterialManager + participant HTTP as HTTPService + participant ROS as ROS2ProtocolNode + + APP->>WS: 创建工作站实例 + WS->>ROS: 初始化ROS2ProtocolNode + ROS->>ROS: 初始化子设备 + ROS->>ROS: 设置硬件接口代理 + + WS->>COMM: _create_communication_module() + COMM->>COMM: 初始化通信配置 + COMM->>COMM: 建立PLC/串口连接 + COMM-->>WS: 返回通信模块实例 + + WS->>MAT: _create_material_management_module() + MAT->>MAT: 创建PyLabRobot Deck + MAT->>MAT: 初始化物料资源 + MAT->>MAT: 注册到ResourceTracker + MAT-->>WS: 返回物料管理实例 + + WS->>WS: _register_supported_workflows() + WS->>WS: _create_workstation_services() + WS->>HTTP: _start_http_service() + HTTP->>HTTP: 创建HTTP服务器 + HTTP->>HTTP: 启动监听线程 + HTTP-->>WS: HTTP服务启动完成 + + WS-->>APP: 工作站初始化完成 +``` + +## 4. 工作流执行时序图 + +```mermaid +sequenceDiagram + participant EXT as ExternalSystem + participant WS as WorkstationBase + participant COMM as CommunicationModule + participant MAT as MaterialManager + participant ROS as ROS2ProtocolNode + participant DEV as SubDevice + + EXT->>WS: start_workflow(type, params) + WS->>WS: 验证工作流类型 + WS->>COMM: start_workflow(type, params) + COMM->>COMM: 发送启动命令到PLC + COMM-->>WS: 启动成功 + + WS->>WS: 更新workflow_status = RUNNING + + loop 工作流步骤执行 + WS->>ROS: execute_single_action(device_id, action, params) + ROS->>DEV: 发送ROS Action请求 + DEV->>DEV: 执行设备动作 + DEV-->>ROS: 返回执行结果 + ROS-->>WS: 返回动作结果 + + WS->>MAT: update_material_location(material_id, location) + MAT->>MAT: 更新PyLabRobot资源状态 + MAT-->>WS: 更新完成 + end + + WS->>COMM: get_workflow_status() + COMM->>COMM: 查询PLC状态寄存器 + COMM-->>WS: 返回状态信息 + + WS->>WS: 更新workflow_status = COMPLETED + WS-->>EXT: 工作流执行完成 +``` + +## 5. HTTP报送处理时序图 + +```mermaid +sequenceDiagram + participant EXT as ExternalWorkstation + participant HTTP as HTTPService + participant WS as WorkstationBase + participant MAT as MaterialManager + participant DB as DataStorage + + EXT->>HTTP: POST /report/step_finish + HTTP->>HTTP: 解析请求数据 + HTTP->>HTTP: 验证LIMS协议字段 + HTTP->>WS: process_step_finish_report(request) + + WS->>WS: 增加接收计数 + WS->>WS: 记录步骤完成事件 + WS->>MAT: 更新相关物料状态 + MAT->>MAT: 更新PyLabRobot资源 + MAT-->>WS: 更新完成 + + WS->>DB: 保存报送记录 + DB-->>WS: 保存完成 + + WS-->>HTTP: 返回处理结果 + HTTP->>HTTP: 构造HTTP响应 + HTTP-->>EXT: 200 OK + acknowledgment_id + + Note over EXT,DB: 类似处理sample_finish, order_finish, material_change等报送 +``` + +## 6. 错误处理时序图 + +```mermaid +sequenceDiagram + participant DEV as Device + participant WS as WorkstationBase + participant COMM as CommunicationModule + participant HTTP as HTTPService + participant EXT as ExternalSystem + + DEV->>WS: 设备错误事件 + WS->>WS: handle_external_error(error_data) + WS->>WS: 记录错误历史 + + alt 关键错误 + WS->>COMM: emergency_stop() + COMM->>COMM: 发送紧急停止命令 + WS->>WS: 更新workflow_status = ERROR + else 普通错误 + WS->>WS: 标记动作失败 + WS->>WS: 触发重试逻辑 + end + + WS->>HTTP: 记录错误报送 + HTTP->>EXT: 主动通知错误状态 + + WS-->>DEV: 错误处理完成 +``` + +## 7. 典型工作站实现示例 + +### 7.1 PLC工作站实现 + +```python +class PLCWorkstation(WorkstationBase): + def _create_communication_module(self): + return PLCCommunication(self.communication_config) + + def _create_material_management_module(self): + return PyLabRobotMaterialManager( + self.device_id, + self.deck_config, + self.resource_tracker + ) + + def _register_supported_workflows(self): + self.supported_workflows = { + "battery_assembly": WorkflowInfo(...), + "quality_check": WorkflowInfo(...) + } +``` + +### 7.2 报送接收工作站实现 + +```python +class ReportingWorkstation(WorkstationBase): + def _create_communication_module(self): + return DummyCommunication(self.communication_config) + + def _create_material_management_module(self): + return SimpleMaterialManager( + self.device_id, + self.deck_config, + self.resource_tracker + ) + + def _register_supported_workflows(self): + self.supported_workflows = { + "data_collection": WorkflowInfo(...), + "report_processing": WorkflowInfo(...) + } +``` + +## 8. 核心接口说明 + +### 8.1 必须实现的抽象方法 +- `_create_communication_module()`: 创建通信模块 +- `_create_material_management_module()`: 创建物料管理模块 +- `_register_supported_workflows()`: 注册支持的工作流 + +### 8.2 可重写的报送处理方法 +- `process_step_finish_report()`: 步骤完成处理 +- `process_sample_finish_report()`: 样本完成处理 +- `process_order_finish_report()`: 订单完成处理 +- `process_material_change_report()`: 物料变更处理 +- `handle_external_error()`: 错误处理 + +### 8.3 工作流控制接口 +- `start_workflow()`: 启动工作流 +- `stop_workflow()`: 停止工作流 +- `get_workflow_status()`: 获取状态 + +## 9. 配置参数说明 + +```python +workstation_config = { + "communication_config": { + "protocol": "modbus_tcp", + "host": "192.168.1.100", + "port": 502 + }, + "deck_config": { + "size_x": 1000.0, + "size_y": 1000.0, + "size_z": 500.0 + }, + "http_service_config": { + "enabled": True, + "host": "127.0.0.1", + "port": 8081 + }, + "communication_interfaces": { + "logical_device_1": CommunicationInterface(...) + } +} +``` + +这个架构设计支持： +1. **灵活的通信方式**: 通过CommunicationBase支持PLC、串口、以太网等 +2. **多样的物料管理**: 支持PyLabRobot、Bioyond、简单物料系统 +3. **统一的HTTP报送**: 基于LIMS协议的标准化报送接口 +4. **完整的工作流控制**: 支持动态和静态工作流 +5. **强大的错误处理**: 多层次的错误处理和恢复机制