VWED_server/README.md

# VWED任务模块

## 项目概述

VWED任务模块是AMR（自主移动机器人）调度系统的核心组件之一，用于管理和监控机器人任务的全生命周期。该模块提供了低代码配置工具，使用户能够通过可视化界面设计和配置复杂的机器人任务流程，无需编写大量代码。系统支持任务版本控制、流程编辑、测试执行和源代码生成等功能，大幅提高了机器人任务配置的效率和灵活性。

## 项目架构

VWED任务模块采用分层架构设计，遵循关注点分离原则，各层次职责明确，便于维护和扩展：

### 1. 架构层次

- **表现层（API层）**：处理HTTP请求和响应，提供RESTful API接口
- **中间件层（Middlewares层）**：提供请求日志记录、错误处理、认证等横切关注点
- **业务逻辑层（Services层）**：实现核心业务逻辑，包含任务执行、智能调度、设备控制等服务
- **智能代理层（Agents层）**：提供智能代理服务，支持任务自动化和优化（已设计，部分实现）
- **领域层（Core层）**：定义核心领域模型和业务规则，包含智能服务等核心功能
- **数据层（Data层）**：提供数据模型定义和数据访问功能，支持任务、流程、组件等数据的持久化
- **组件层（Components层）**：提供可扩展的组件系统，支持任务流程的模块化构建
- **工具层（Utils层）**：提供日志记录、数据验证、加密、数据库迁移等基础工具
- **配置层（Config层）**：提供系统配置管理，包含数据库、组件、错误信息等配置

### 2. 设计模式

- **工厂模式**：用于组件的创建和注册
- **策略模式**：用于实现不同类型组件的执行逻辑
- **观察者模式**：用于任务状态变更通知
- **命令模式**：用于任务执行和撤销操作
- **组合模式**：用于构建组件树和工作流结构
- **仓储模式**：用于数据访问和持久化
- **中间件模式**：用于请求处理的横切关注点

### 3. 系统架构图

```
                                    +-------------------+
                                    |    用户界面       |
                                    +--------+----------+
                                             |
                                             v
+------------------+              +----------+---------+
|                  |              |                    |
|   外部知识库      +------------->+    API层          |
|                  |              |  (routes模块)     |
+------------------+              +----+------+--------+
                                       |      |
                                       |      |
          +----------------------------+      |
          |                                   |
          v                                   v
+----------+---------+              +---------+----------+
|                    |              |                    |
|   中间件层         |<------------>|    业务服务层      |
|  (请求日志/错误    |              | (services模块)    |
|   处理/认证)       |              |                    |
+----+---------------+              +--------+-----------+
     |                                       |
     |                                       |
     |                                       v
     |                              +--------+-----------+
     |                              |                    |
     |                              |   任务执行引擎     |
     |                              | (execution模块)   |
     |                              +--------+-----------+
     |                                       |
     |                                       |
     |                                       v
     |                              +--------+-----------+
     |                              |                    |
     +----------------------------->+   智能代理系统     |
     |                              | (agents模块)      |
     |                              +--------+-----------+
     |                                       |
     v                                       v
+----+---------------+              +--------+-----------+
|                    |              |                    |
|   智能服务层       |              |   外部系统/设备    |
| (intelligence模块) |              |  (calldevice)     |
+----+---------------+              +--------------------+
     |
     |
     v
+----+---+
|        |
|数据存储层|
| (data)  |
+--------+
```

> **注意**：智能代理系统和智能服务层已完成基础架构设计，正在逐步实现相关功能。

## 项目结构

```
VWED_task/
├── routes/                     # API路由定义
│   ├── task_api.py             # 任务相关API
│   ├── task_edit_api.py        # 任务编辑API
│   ├── task_record_api.py      # 任务记录API
│   ├── script_api.py           # 脚本相关API
│   ├── template_api.py         # 模板相关API
│   ├── calldevice_api.py       # 设备调用API
│   ├── modbus_config_api.py    # Modbus配置API
│   ├── common_api.py           # 通用API
│   ├── database.py             # 数据库API
│   ├── __init__.py             # 路由模块初始化
│   └── model/                  # API模型定义
├── services/                   # 业务服务层
│   ├── task_service.py         # 任务服务
│   ├── task_edit_service.py    # 任务编辑服务
│   ├── task_record_service.py  # 任务记录服务
│   ├── script_service.py       # 脚本服务
│   ├── template_service.py     # 模板服务
│   ├── calldevice_service.py   # 设备调用服务
│   ├── modbus_config_service.py# Modbus配置服务
│   ├── sync_service.py         # 同步服务
│   ├── execution/              # 任务执行模块
│   │   ├── task_executor.py    # 任务执行器
│   │   ├── block_executor.py   # 任务块执行器
│   │   ├── task_context.py     # 执行上下文
│   │   ├── block_handlers.py   # 任务块处理器
│   │   └── handlers/           # 处理器集合
│   ├── enhanced_scheduler/     # 增强版任务调度器
│   ├── intelligence/           # 智能服务模块
│   │   └── embedding.py        # 嵌入模型服务
│   ├── agent/                  # 代理服务模块
│   └── __init__.py             # 服务模块初始化
├── middlewares/                # 中间件层
│   ├── request_logger.py       # 请求日志中间件
│   ├── error_handlers.py       # 错误处理中间件
│   └── __init__.py             # 中间件初始化
├── agents/                     # 智能代理层
│   ├── base_agent.py           # 代理基类（规划中）
│   ├── llm/                    # 大语言模型集成
│   ├── prompts/                # 提示词模板
│   ├── tools/                  # 代理工具集
│   ├── teams/                  # 代理团队协作
│   └── __init__.py             # 代理模块初始化
├── components/                 # 组件实现
│   ├── base_components.py      # 基础组件
│   └── __init__.py             # 组件模块初始化
├── core/                       # 核心功能模块
│   ├── intelligence/           # 智能服务核心
│   └── __init__.py             # 核心模块初始化
├── data/                       # 数据存储
│   ├── models/                 # 数据模型定义
│   │   ├── base.py             # 基础模型
│   │   ├── taskdef.py          # 任务定义模型
│   │   ├── taskrecord.py       # 任务记录模型
│   │   ├── blockrecord.py      # 任务块记录模型
│   │   ├── script.py           # 脚本模型
│   │   ├── tasktemplate.py     # 任务模板模型
│   │   ├── calldevice.py       # 设备调用模型
│   │   ├── modbusconfig.py     # Modbus配置模型
│   │   ├── interfacedef.py     # 接口定义模型
│   │   ├── tasklog.py          # 任务日志模型
│   │   ├── datacache.py        # 数据缓存模型
│   │   ├── datacachesplit.py   # 数据缓存分片模型
│   │   └── __init__.py         # 模型模块初始化
│   ├── enum/                   # 枚举定义
│   ├── task_backups/           # 任务备份存储
│   ├── session.py              # 数据库会话管理
│   ├── cache.py                # 缓存服务
│   └── __init__.py             # 数据模块初始化
├── migrations/                 # 数据库迁移
│   ├── versions/               # 迁移版本
│   ├── env.py                  # 迁移环境配置
│   ├── script.py.mako          # 迁移脚本模板
│   └── alembic.ini             # Alembic配置
├── scripts/                    # 脚本工具
│   ├── generate_migration.py   # 生成迁移脚本
│   └── run_migration.py        # 执行迁移脚本
├── utils/                      # 工具函数
│   ├── logger.py               # 日志工具
│   ├── validator.py            # 数据验证工具
│   ├── helpers.py              # 辅助函数
│   ├── api_response.py         # API响应工具
│   ├── component_manager.py    # 组件管理器
│   ├── built_in_functions.py   # 内置函数
│   ├── crypto_utils.py         # 加密工具
│   ├── db_migration.py         # 数据库迁移工具
│   ├── string_utils/           # 字符串处理工具
│   └── __init__.py             # 工具模块初始化
├── config/                     # 配置文件
│   ├── settings.py             # 系统设置
│   ├── database_config.py      # 数据库配置
│   ├── tf_api_config.py        # TF API配置
│   ├── error_messages.py       # 错误信息配置
│   ├── components/             # 组件配置
│   └── __init__.py             # 配置模块初始化
├── exports/                    # 导出文件存储
├── logs/                       # 日志文件
├── docs/                       # 文档
├── tests/                      # 测试代码
│   ├── unit/                   # 单元测试
│   ├── integration/            # 集成测试
│   └── fixtures/               # 测试数据
├── VWED任务模块接口文档/        # API接口文档
├── app.py                      # 应用入口
├── Dockerfile                  # Docker配置文件
├── docker-compose.yml          # Docker Compose配置
├── requirements.txt            # 依赖包列表
├── VWED任务系统模块数据详情表.md # 数据表详情文档
├── VWED任务模块系统架构图文件.md # 系统架构详细文档
└── README.md                   # 项目说明文档
```

## 核心功能

### 1. 任务管理

- **任务创建**：支持创建普通任务和定时任务
- **任务监控**：实时监控任务执行状态和进度
- **任务操作**：支持启动、暂停、取消、重试等操作
- **任务历史**：记录任务执行历史和结果
- **版本控制**：支持任务版本管理，可以回滚到历史版本
- **任务测试**：支持在测试环境中执行任务，验证任务配置

### 2. 任务编辑器

VWED任务模块提供了强大的可视化编辑器，支持以下功能：

- **流程图设计**：通过拖拽方式设计任务流程图
- **属性配置**：配置组件和连接的属性
- **变量管理**：定义和管理任务执行过程中的变量
- **撤销/重做**：支持编辑操作的撤销和重做
- **源代码生成**：自动生成任务执行的源代码
- **版本备份**：支持任务配置的版本备份和恢复

### 3. 任务执行引擎

系统提供了完整的任务执行引擎，包含以下组件：

- **任务执行器（TaskExecutor）**：负责任务的整体执行控制
- **任务块执行器（BlockExecutor）**：处理任务中各个执行块的执行逻辑
- **执行上下文（TaskContext）**：管理任务执行过程中的变量和状态
- **任务块处理器（BlockHandlers）**：提供各种类型任务块的具体执行逻辑
- **增强版调度器（EnhancedScheduler）**：提供高性能的任务调度服务

### 4. 设备集成与控制

- **设备调用服务**：统一的设备调用接口，支持与各种外部设备通信
- **Modbus配置管理**：支持Modbus协议设备的配置和通信
- **接口定义管理**：灵活的接口定义系统，支持自定义设备接口

### 5. 智能代理系统（部分实现）

- **代理基础架构**：提供代理系统的基础框架
- **LLM集成**：集成大语言模型，提供智能决策支持
- **代理工具**：提供丰富的工具集，支持代理执行各种操作
- **团队协作**：支持多代理协作完成复杂任务

### 6. 智能服务层（部分实现）

- **嵌入模型服务**：提供文本向量化和语义分析能力
- **知识检索**：基于语义相似度进行知识检索（规划中）
- **智能决策支持**：基于AI模型的智能决策辅助（规划中）

### 7. 中间件系统

- **请求日志中间件**：自动记录API请求日志，便于调试和监控
- **错误处理中间件**：统一的错误处理机制，提供友好的错误信息
- **认证中间件**：用户认证和权限控制（规划中）

### 8. 数据模型

系统提供了完善的数据模型，支持任务管理的各个方面：

- **任务定义模型（TaskDef）**：存储任务基本信息和配置
- **任务记录模型（TaskRecord）**：记录任务的执行情况
- **任务块记录模型（BlockRecord）**：存储任务执行过程中各个块的记录
- **脚本模型（Script）**：管理自定义脚本
- **任务模板模型（TaskTemplate）**：支持任务模板功能
- **设备调用模型（CallDevice）**：管理设备调用配置
- **Modbus配置模型（ModbusConfig）**：管理Modbus设备配置
- **数据缓存模型（DataCache）**：提供数据缓存功能

## 执行业务流程

### 系统启动流程

1. 应用启动（app.py）
2. 加载配置信息（config模块）
3. 初始化日志系统（utils.logger）
4. 初始化数据库连接（data.session）
5. 初始化中间件（middlewares模块）
6. 注册API路由（routes模块）
7. 启动增强版任务调度器（services.enhanced_scheduler）
8. 启动HTTP服务（uvicorn）

### 任务创建流程

1. 用户在VWED任务主页面点击"定义新任务"按钮
2. 前端发送创建任务请求到API层（/api/tasks）
3. API层调用任务服务（task_service.py）创建任务记录
4. 系统创建任务并返回任务ID
5. 前端跳转到任务编辑页面
6. 用户通过拖拽组件设计任务流程
7. 前端发送保存流程请求到API层（/api/workflows）
8. API层调用任务编辑服务（task_edit_service.py）保存流程配置
9. 系统将流程配置保存到数据库，创建新版本

### 任务执行流程

1. 用户在任务列表中选择任务并点击"执行"按钮
2. 前端发送执行任务请求到API层（/api/tasks/{id}/execute）
3. API层调用任务服务（task_service.py）创建任务记录
4. 任务服务将任务提交到增强版调度器
5. 调度器分配工作线程，初始化任务执行器
6. 任务执行器加载任务配置，创建执行上下文
7. 任务执行器调用任务块执行器执行各个任务块
8. 任务块执行器根据任务块类型调用相应的处理器
9. 系统实时更新任务状态和进度
10. 任务执行完成后，系统记录执行结果和日志

### 设备控制流程

1. 任务执行过程中遇到设备控制任务块
2. 任务块执行器调用设备调用服务
3. 设备调用服务根据配置选择相应的通信协议
4. 通过Modbus、HTTP等协议与设备通信
5. 接收设备响应并更新任务执行状态
6. 将设备操作结果记录到任务日志

## 交互方式

VWED任务模块提供多种交互方式，满足不同场景的需求：

### 1. 用户界面交互

- **任务列表界面**：
  - 展示所有任务及其状态
  - 提供任务筛选、搜索和排序功能
  - 支持任务的创建、编辑、删除、执行等操作
  - 显示任务执行状态和进度

- **任务编辑界面**：
  - 提供可视化的流程设计工具
  - 左侧组件面板：展示可用组件
  - 中央流程图编辑区：通过拖拽设计任务流程
  - 右侧属性面板：配置组件参数
  - 顶部工具栏：保存、运行、测试、撤销、重做等操作

- **任务监控界面**：
  - 实时显示任务执行状态和进度
  - 展示任务执行日志和变量值
  - 提供任务暂停、取消、重试等操作

## 技术栈

- **后端**：FastAPI (Python 3.11+)
- **数据库**：SQLAlchemy ORM，支持MySQL、PostgreSQL等
- **前端**：React + Ant Design（低代码编辑器）
- **API文档**：Swagger UI（自动生成）
- **任务调度**：自研增强版异步任务调度器
- **组件系统**：可扩展的组件注册和执行系统
- **数据迁移**：Alembic
- **智能代理**：基于大语言模型的智能代理系统（部分实现）
- **设备通信**：支持Modbus、HTTP等多种协议
- **缓存系统**：基于内存和数据库的多级缓存

## 部署说明

### 环境要求

- Python 3.11+
- 数据库（MySQL/PostgreSQL）
- Node.js 14+（前端开发）

### 详细运行方法

#### 方法一：使用Docker运行（推荐）

Docker是最简单的部署方式，可以避免环境配置问题。

##### 1. 构建并运行Docker镜像

```bash
# 克隆代码仓库
git clone http://192.168.1.2:8418/jzw/vwed_task_modules.git
cd vwed_task

# 构建Docker镜像
docker build -t vwed-task:latest .

# 运行Docker容器
docker run -d -p 8000:8000 --name vwed-task-container vwed-task:latest
```

##### 2. 使用Docker Compose运行（包含数据库和缓存）

```bash
# 克隆代码仓库
git clone http://192.168.1.2:8418/jzw/vwed_task_modules.git
cd vwed_task

# 使用Docker Compose构建并启动所有服务
docker-compose up -d
```

##### 3. 验证服务是否正常运行

```bash
# 查看容器状态
docker ps

# 或者使用Docker Compose查看
docker-compose ps

# 查看应用日志
docker logs vwed-task-container
# 或者
docker-compose logs app
```

##### 4. 停止和删除容器

```bash
# 停止容器
docker stop vwed-task-container
docker rm vwed-task-container

# 或者使用Docker Compose
docker-compose down
```

#### 方法二：本地运行（不同操作系统）

##### 前提条件
- 安装Conda（Miniconda或Anaconda）
- 安装Git
- 安装数据库（MySQL或PostgreSQL）

##### Windows系统

```bash
# 1. 克隆代码仓库
git clone http://192.168.1.2:8418/jzw/vwed_task_modules.git
cd vwed_task

# 2. 创建并激活Conda环境 推荐使用3.11
conda create -n pytf python=3.11
conda activate pytf

# 3. 安装依赖
pip install -r requirements.txt

# 4. 配置数据库连接
# 编辑 config/database_config.py 文件，设置正确的数据库连接信息

# 5. 启动应用
python app.py
```

### 数据库配置说明

在运行应用前，需要修改`config/database_config.py`文件中的数据库配置，将默认的数据库连接信息替换为您自己的本地或云上的MySQL数据库：

```python
# 数据库连接配置
DB_CONFIG = ConfigDict(
    default=dict(
        dialect='mysql',
        driver='pymysql',
        username='your_username',  # 修改为您的数据库用户名
        password='your_password',  # 修改为您的数据库密码
        host='your_host',          # 修改为您的数据库主机地址，本地通常为localhost或127.0.0.1，云数据库使用对应的连接地址
        port=3306,                 # 修改为您的数据库端口，默认MySQL为3306
        database='vwed_task',  # 数据库名称，可以保持不变或修改为您想使用的数据库名
        charset='utf8mb4'
    ),
    test=dict(
        dialect='sqlite',
        database=':memory:'
    )
)
```

如果您使用的是云数据库（如阿里云RDS、AWS RDS等），请确保：
1. 数据库已创建并可以访问
2. 数据库用户有足够的权限（至少需要CREATE、ALTER、SELECT、INSERT、UPDATE、DELETE权限）
3. 数据库服务器的防火墙允许从您的应用服务器访问

您也可以通过环境变量来设置数据库连接信息，这样就不需要修改源代码：

```bash
# Windows
set VWED_ENV=default
set DB_HOST=your_host
set DB_PORT=3306
set DB_USER=your_username
set DB_PASSWORD=your_password
set DB_NAME=vwed_task

# macOS/Linux
export VWED_ENV=default
export DB_HOST=your_host
export DB_PORT=3306
export DB_USER=your_username
export DB_PASSWORD=your_password
export DB_NAME=vwed_task
```

系统启动时会自动检查数据库是否存在，如果不存在会自动创建数据库和所需的表结构。

##### macOS系统

```bash
# 1. 克隆代码仓库
git clone http://192.168.1.2:8418/jzw/vwed_task_modules.git
cd vwed_task

# 2. 创建并激活Conda环境
conda create -n pytf python=3.11
conda activate pytf

# 3. 安装依赖
pip install -r requirements.txt

# 4. 配置数据库连接
# 编辑 config/database_config.py 文件，设置正确的数据库连接信息

# 5. 启动应用
python app.py
```

##### Linux系统

```bash
# 1. 克隆代码仓库
git clone http://192.168.1.2:8418/jzw/vwed_task_modules.git
cd vwed_task

# 2. 创建并激活Conda环境
conda create -n pytf python=3.11
conda activate pytf

# 3. 安装依赖
pip install -r requirements.txt

# 4. 配置数据库连接
# 编辑 config/database_config.py 文件，设置正确的数据库连接信息

# 5. 启动应用
python app.py
```

#### 方法三：使用虚拟环境（不使用Conda）（不推荐）

**注意：此方法不推荐使用**，因为项目依赖复杂，使用Conda可以更好地管理依赖关系和解决潜在的兼容性问题。此外，某些依赖可能需要特定的编译环境，Conda能更好地处理这些情况。如果您仍然希望使用此方法，请按照以下步骤操作：

##### Windows系统

```bash
# 1. 克隆代码仓库
git clone http://192.168.1.2:8418/jzw/vwed_task_modules.git
cd vwed_task

# 2. 创建并激活虚拟环境
python -m venv venv
.\venv\Scripts\activate

# 3. 安装依赖
pip install -r requirements.txt

# 4. 配置数据库连接
# 编辑 config/database_config.py 文件

# 5. 启动应用
python app.py
```

##### macOS/Linux系统

```bash
# 1. 克隆代码仓库
git clone http://192.168.1.2:8418/jzw/vwed_task_modules.git
cd vwed_task

# 2. 创建并激活虚拟环境
python -m venv venv
source venv/bin/activate

# 3. 安装依赖
pip install -r requirements.txt

# 4. 配置数据库连接
# 编辑 config/database_config.py 文件

# 5. 启动应用
python app.py
```

### 安装步骤

1. 克隆代码库
2. 安装依赖：`pip install -r requirements.txt`
3. 配置数据库连接：修改`config/database_config.py`
4. 启动应用：`python app.py`

## 使用示例

### 创建简单任务

1. 进入VWED任务主页面
2. 点击"定义新任务"按钮
3. 输入任务名称"测试任务"，选择"普通任务"类型
4. 在编辑页面拖入"选择执行机器人"组件
5. 配置机器人选择参数
6. 拖入"机器人通用动作"组件，配置目标站点
7. 连接组件，形成执行流程
8. 保存任务并执行

### 使用版本控制

1. 打开现有任务的编辑页面
2. 修改任务流程或组件配置
3. 点击"保存"按钮，系统自动创建新版本
4. 在版本历史中可以查看所有历史版本
5. 可以选择任意历史版本进行查看或恢复

### 使用撤销/重做功能

1. 在编辑页面进行操作（如添加节点、移动节点等）
2. 如需撤销操作，点击工具栏中的"撤销"按钮
3. 如需重做已撤销的操作，点击"重做"按钮
4. 系统会记录编辑会话中的所有操作历史

## 常见问题

1. **任务执行失败怎么办？**
   - 查看任务执行日志，定位失败原因
   - 在测试环境中验证任务配置
   - 修改任务配置，解决问题后重试

2. **如何调试复杂任务？**
   - 使用测试功能验证任务配置
   - 查看执行日志和变量值
   - 使用条件断点和单步执行

3. **如何管理大量任务？**
   - 使用任务模板功能创建可复用的任务模板
   - 使用子任务功能将复杂任务拆分为多个子任务
   - 使用标签和分类功能组织任务

4. **设备通信问题怎么解决？**
   - 检查设备配置参数是否正确
   - 验证网络连接和防火墙设置
   - 查看设备通信日志，定位通信故障

## 联系方式

如有问题或建议，请联系系统管理员或开发团队。

# Docker部署说明

## 使用Docker部署VWED任务模块

本项目支持使用Docker进行部署，以下是部署步骤：

### 前提条件

- 安装Docker和Docker Compose
- 确保端口8000、3306和6379未被占用

### 部署步骤

1. 克隆代码仓库

```bash
git clone http://192.168.1.2:8418/jzw/vwed_task_modules.git
cd vwed_task
```

2. 使用Docker Compose构建并启动服务

```bash
docker-compose up -d
```

这将启动三个容器：
- vwed-task: 应用服务
- vwed-mysql: MySQL数据库
- vwed-redis: Redis缓存

3. 验证服务是否正常运行

```bash
docker-compose ps
```

4. 访问API文档

打开浏览器，访问 http://localhost:8000/docs 查看API文档。

### 环境变量配置

可以通过修改`docker-compose.yml`文件中的环境变量来配置应用：

```yaml
environment:
  - VWED_ENV=default  # 环境名称
  - DEBUG=false           # 是否开启调试模式
  - DB_HOST=db            # 数据库主机
  - DB_PORT=3306          # 数据库端口
  - DB_USER=root          # 数据库用户名
  - DB_PASSWORD=password  # 数据库密码
  - DB_NAME=vwed_task # 数据库名称
  - REDIS_HOST=redis      # Redis主机
  - REDIS_PORT=6379       # Redis端口
  - REDIS_DB=0            # Redis数据库索引
```

### 单独构建Docker镜像

如果需要单独构建Docker镜像，可以使用以下命令：

```bash
docker build -t vwed-task:latest .
```

### 停止服务

```bash
docker-compose down
```

如果需要同时删除数据卷（会删除所有数据）：

```bash
docker-compose down -v
```

### 查看日志

```bash
# 查看所有服务的日志
docker-compose logs

# 查看特定服务的日志
docker-compose logs app
docker-compose logs db
docker-compose logs redis

# 实时查看日志
docker-compose logs -f app
```