VWED_server/README.md

# VWED任务模块

## 项目概述

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

## 项目架构

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

### 1. 架构层次

- **表现层（API层）**：处理HTTP请求和响应，提供RESTful API接口
- **业务逻辑层（Service层）**：实现核心业务逻辑，处理任务和工作流的创建、执行和管理
- **代理层（Agents层）**：提供智能代理服务，支持任务自动化和优化（已设计，尚未实现）
- **领域层（Core层）**：定义核心领域模型和业务规则，包含工作流引擎和组件系统
- **数据层（Data层）**：提供数据模型定义和数据访问功能，支持任务、流程、组件等数据的持久化
- **智能服务层**：提供向量化和向量存储服务，支持知识检索和智能决策（已设计，尚未实现）
- **基础设施层**：提供数据持久化、日志记录、配置管理等基础服务

### 2. 设计模式

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

### 3. 系统架构图

```
                                    +-------------------+
                                    |    用户界面       |
                                    +--------+----------+
                                             |
                                             v
+------------------+              +----------+---------+
|                  |              |                    |
|   外部知识库      +------------->+    API层          |
|                  |              |                    |
+------------------+              +----+------+--------+
                                       |      |
                                       |      |
          +----------------------------+      |
          |                                   |
          v                                   v
+----------+---------+              +---------+----------+
|                    |              |                    |
|    Agent系统       |<------------>|    业务服务层      |
|  (包含LLM功能)     |              |                    |
+----+---------------+              +--------+-----------+
     |                                       |
     |                                       |
     |                                       v
     |                              +--------+-----------+
     |                              |                    |
     |                              |    工作流引擎      |
     |                              |                    |
     |                              +--------+-----------+
     |                                       |
     |                                       |
     |                                       v
     |                              +--------+-----------+
     |                              |                    |
     +----------------------------->+    组件系统        |
     |                              |                    |
     |                              +--------+-----------+
     |                                       |
     v                                       v
+----+---------------+              +--------+-----------+
|                    |              |                    |
|   智能服务层       |              |   外部系统/设备    |
| (向量化和向量存储) |              |                    |
+----+---------------+              +--------------------+
     |
     |
     v
+----+---+
|        |
|向量数据库|
|        |
+--------+
```

> **注意**：架构图中的Agent系统、外部知识库、智能服务层和向量数据库部分已完成设计，但尚未实现。这些组件将在后续版本中逐步开发和集成。

## 项目结构

```
VWED_task/
├── routes/                  # API路由定义
│   ├── task_api.py          # 任务相关API
│   ├── task_edit_api.py     # 任务编辑API
│   ├── script_api.py        # 脚本相关API
│   ├── template_api.py      # 模板相关API
│   ├── common_api.py        # 通用API
│   ├── database.py          # 数据库API
│   └── model/               # API模型定义
├── services/                # 业务服务层
│   ├── task_service.py      # 任务服务
├── agents/                  # 智能代理层（已设计，尚未实现）
│   ├── base_agent.py        # 代理基类
│   ├── llm/                 # 大语言模型集成
│   ├── prompts/             # 提示词模板
│   ├── tools/               # 代理工具集
│   └── teams/               # 代理团队协作
├── components/              # 组件实现
│   ├── base_components.py   # 基础组件
├── core/                    # 核心功能模块
│   ├── component.py         # 组件基类定义
│   ├── context.py           # 执行上下文
│   ├── exceptions.py        # 异常定义
│   └── workflow.py          # 工作流引擎
├── data/                    # 数据存储
│   ├── models/              # 数据模型定义
│   │   ├── base.py          # 基础模型
│   ├── session.py           # 数据库会话管理
│   └── repositories/        # 数据仓储实现
├── migrations/              # 数据库迁移
│   ├── versions/            # 迁移版本
│   ├── env.py               # 迁移环境配置
│   ├── script.py.mako       # 迁移脚本模板
│   └── alembic.ini          # Alembic配置
├── scripts/                 # 脚本工具
│   ├── generate_migration.py # 生成迁移脚本
│   └── run_migration.py     # 执行迁移脚本
├── utils/                   # 工具函数
│   ├── logger.py            # 日志工具
│   ├── validators.py        # 数据验证工具
│   └── helpers.py           # 辅助函数
├── config/                  # 配置文件
│   ├── database.py          # 数据库配置
├── logs/                    # 日志文件
├── docs/                    # 文档
├── tests/                   # 测试代码
│   ├── unit/                # 单元测试
│   ├── integration/         # 集成测试
│   └── fixtures/            # 测试数据
├── app.py                   # 应用入口
├── Dockerfile               # Docker配置文件
├── docker-compose.yml       # Docker Compose配置
└── requirements.txt         # 依赖包列表
```

## 核心功能

### 1. 任务管理

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

### 2. 任务编辑器

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

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

### 3. 组件库

VWED任务模块提供了丰富的组件库，用户可以通过拖拽组件和配置参数的方式设计复杂的任务流程：

- **子任务组件**：支持任务的模块化和复用
- **脚本组件**：支持编写自定义JavaScript脚本
- **HTTP请求组件**：支持与外部系统进行通信
- **任务组件**：提供任务数据管理和状态控制功能
- **流程组件**：提供条件判断、循环、并行执行等流程控制功能
- **基础组件**：提供数据验证、ID生成、时间处理等基础功能
- **库位组件**：提供库位管理和操作功能
- **机器人调度组件**：提供机器人选择、控制和状态监控功能
- **设备组件**：提供与外部设备通信的功能

### 4. 智能代理系统（已设计，尚未实现）

- **任务代理**：自动分析和优化任务流程
- **LLM集成**：集成大语言模型，提供智能决策支持
- **代理工具**：提供丰富的工具集，支持代理执行各种操作
- **团队协作**：支持多代理协作完成复杂任务
- **知识检索**：从外部知识库中检索相关信息，辅助决策

### 5. 智能服务层（已设计，尚未实现）

- **向量化服务**：将文本、图像等数据转换为向量表示
- **知识检索**：基于语义相似度进行知识检索
- **嵌入模型**：提供多种嵌入模型，支持不同类型数据的向量化
- **向量存储**：高效存储和检索向量数据

### 6. 工作流引擎

- **流程执行**：解析和执行任务流程图
- **上下文管理**：管理任务执行过程中的变量和状态
- **错误处理**：提供异常捕获和处理机制
- **并行执行**：支持多分支并行执行
- **动态加载**：支持动态加载和执行组件

### 7. 数据模型

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

- **任务模型**：存储任务基本信息和配置
- **任务版本**：管理任务的不同版本
- **任务记录**：记录任务的执行情况
- **任务流程节点**：存储流程图中的节点信息
- **任务流程连接**：存储流程图中的连接信息
- **任务变量定义**：管理任务中使用的变量
- **任务编辑历史**：记录编辑操作，支持撤销/重做
- **任务备份**：存储任务的备份数据

## 执行业务流程

### 系统启动流程

1. 应用启动（app.py）
2. 加载配置信息（config模块）
3. 初始化日志系统（utils.logger）
4. 初始化数据库连接（data.session）
5. 注册所有组件（config.component_registry）
6. 注册API路由（api模块）
7. 启动HTTP服务（uvicorn）

### 任务创建流程

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

### 任务编辑流程

1. 用户打开任务编辑页面
2. 系统加载任务的最新版本和流程图数据
3. 用户通过拖拽组件和连接设计流程图
4. 用户配置组件属性和变量
5. 系统记录每一步编辑操作，支持撤销/重做
6. 用户点击保存按钮，系统创建新版本
7. 用户可以点击测试按钮，在测试环境中执行任务
8. 用户可以点击生成源码按钮，系统生成任务执行代码

### 任务执行流程

1. 用户在任务列表中选择任务并点击"执行"按钮
2. 前端发送执行任务请求到API层（/api/tasks/{id}/execute）
3. API层调用任务服务（task_service.py）创建任务记录
4. 任务服务加载任务配置和工作流定义
5. 任务服务初始化执行上下文（context.py）
6. 任务服务调用工作流引擎（workflow.py）执行任务
7. 工作流引擎解析任务流程图并按顺序执行各组件
8. 组件执行结果存储在上下文中，供后续组件使用
9. 系统实时更新任务状态和进度
10. 任务执行完成后，系统记录执行结果和日志

### 智能任务执行流程（已设计，尚未实现）

1. 用户在任务列表中选择任务并点击"智能执行"按钮
2. 前端发送智能执行任务请求到API层
3. API层调用Agent系统进行任务分析和优化
4. Agent系统从外部知识库检索相关知识
5. Agent系统基于LLM和检索到的知识生成执行计划
6. Agent系统调用业务服务层执行优化后的任务
7. 业务服务层调用工作流引擎执行任务
8. 执行过程中，Agent系统持续监控任务状态
9. 遇到异常情况时，Agent系统自动调整执行策略
10. 任务执行完成后，Agent系统生成执行报告和优化建议

## 交互方式

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

### 1. 用户界面交互

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

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

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

## 技术栈

- **后端**：FastAPI (Python)
- **数据库**：SQLAlchemy ORM，支持MySQL、PostgreSQL等
- **前端**：React + Ant Design（低代码编辑器）
- **API文档**：Swagger UI（自动生成）
- **工作流引擎**：自研基于DAG的工作流引擎
- **组件系统**：可扩展的组件注册和执行系统
- **数据迁移**：Alembic
- **智能代理**：基于大语言模型的智能代理系统（已设计，尚未实现）
- **向量数据库**：支持高效的向量存储和检索（已设计，尚未实现）
- **嵌入模型**：支持文本、图像等数据的向量化（已设计，尚未实现）

## 部署说明

### 环境要求

- 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.py 文件，设置正确的数据库连接信息

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

### 数据库配置说明

在运行应用前，需要修改`config/database.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.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.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.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.py 文件

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

### 安装步骤

1. 克隆代码库
2. 安装依赖：`pip install -r requirements.txt`
3. 配置数据库连接：修改`config/database.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. **如何管理大量任务？**
   - 使用任务模板功能创建可复用的任务模板
   - 使用子任务功能将复杂任务拆分为多个子任务
   - 使用标签和分类功能组织任务

## 联系方式

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

# 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
```