# travel-management

**Repository Path**: notimpossible/travel-management

## Basic Information

- **Project Name**: travel-management
- **Description**: UBML低代码软件构建系统，帮你结合UBML创建业务功能
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-06
- **Last Updated**: 2025-11-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能软自购系统技术架构文档

## 系统概述

本系统是一个基于浏览器插件和后端服务的多智能体软自购平台，通过MCP（浏览器控制协议）技术实现从用户输入到浏览器界面自动操作的完整流程。系统采用WebSocket实时通信为主、HTTP通信为辅的双重通信机制，确保操作的可靠性和实时性。

## 技术架构

### 整体架构图

```
┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│                 │      │                 │      │                 │
│  浏览器插件      │<────>│  后端服务API     │<────>│  智能体系统      │
│                 │      │                 │      │                 │
└─────────────────┘      └────────┬────────┘      └─────────────────┘
                                  │
                                  ▼
                        ┌─────────────────┐
                        │                 │
                        │  MCP工具执行     │   
                        │                 │
                        └─────────────────┘
```

### 核心组件

#### 1. 浏览器插件

- **用户输入接口**：接收用户输入的指令和请求
- **操作执行引擎**：执行从后端发送的MCP操作指令
- **消息通信模块**：通过WebSocket和HTTP与后端服务通信
- **扩展注册机制**：向后端服务注册扩展信息

#### 2. 后端服务

##### WebSocket配置与处理器 (`WebSocketConfig`)  
**<mcfile name="WebSocketConfig.java" path="d:/aubml/travel-management/back/src/main/java/com/gz/iom/iomqwen/webconfig/WebSocketConfig.java"></mcfile>**
- **连接管理**：维护WebSocket会话，支持多个浏览器扩展同时连接
- **消息处理**：处理不同类型的消息（操作结果、扩展注册、页面信息等）
- **操作分发**：将MCP操作指令精确发送到指定的浏览器扩展
- **状态追踪**：跟踪活动标签页和扩展连接状态

##### MCP服务接口与实现

- **服务接口** (`McpService`) **<mcfile name="McpService.java" path="d:/aubml/travel-management/back/src/main/java/com/gz/iom/iomqwen/mcp/McpService.java"></mcfile>**
  - 定义MCP操作执行的核心接口

- **NodeJS实现** (`NodeMcpServiceImpl`) **<mcfile name="NodeMcpServiceImpl.java" path="d:/aubml/travel-management/back/src/main/java/com/gz/iom/iomqwen/mcp/impl/NodeMcpServiceImpl.java"></mcfile>**
  - **双模式执行**：支持在新浏览器和当前标签页中执行操作
  - **WebSocket优先**：优先通过WebSocket发送操作到浏览器扩展
  - **HTTP回退**：WebSocket失败时自动切换到HTTP通信
  - **命令行执行**：支持通过NodeJS脚本在独立浏览器中执行操作

##### REST API控制器 (`McpRest`) **<mcfile name="McpRest.java" path="d:/aubml/travel-management/back/src/main/java/com/gz/iom/iomqwen/rest/McpRest.java"></mcfile>**
- **操作执行接口**：接收MCP操作请求并转发给服务层
- **扩展注册接口**：处理浏览器扩展的注册请求
- **操作列表接口**：提供当前支持的操作类型和目标类型
- **参数验证**：对请求参数进行严格验证，确保安全性

#### 3. 智能体系统

- **意图识别**：分析用户输入的自然语言指令，识别操作意图
- **任务规划**：规划操作流程，生成MCP操作序列
- **调用接口**：通过REST API调用后端服务执行操作
- **结果分析**：处理操作执行结果，向用户提供反馈

## 工作流程详解

### 1. 浏览器插件注册流程

1. 浏览器插件加载时，通过REST API向后端服务注册
2. 后端记录扩展ID和版本信息
3. 浏览器插件与后端建立WebSocket连接
4. 后端将WebSocket会话与扩展ID关联

### 2. 用户输入处理流程

```
用户输入 → 浏览器插件 → 智能体分析 → 后端API → MCP服务 → 浏览器执行 → 返回结果
```

### 3. MCP操作执行流程

1. **请求接收**：后端REST API接收MCP操作请求
2. **目标判断**：根据`targetType`确定操作执行目标（新浏览器或当前标签页）
3. **操作分发**：
   - 对于`currentTab`目标：优先通过WebSocket发送到浏览器扩展
   - 对于`newBrowser`目标：通过NodeJS脚本在新浏览器中执行
4. **失败处理**：
   - WebSocket发送失败时，自动切换到HTTP回退方案
   - HTTP回退也失败时，返回详细错误信息
5. **结果返回**：操作执行结果通过相应渠道返回给调用方

### 4. 消息类型与处理

系统支持的主要消息类型：
- `RESULT_ACK`：操作结果确认消息
- `REGISTRATION_SUCCESS`：扩展注册成功响应
- `PAGE_INFO_ACK`：页面信息确认响应
- `MCP_OPERATION`：MCP操作指令

## 支持的操作类型

- **login**：执行登录操作
- **elementSelect**：选择页面元素
- **fillForm**：填写表单
- **click**：点击操作
- **getElementInfo**：获取元素信息

## 目标类型

- **newBrowser**：在新浏览器窗口中执行操作
- **currentTab**：在当前浏览器标签页中执行操作

## 开发指南

### 环境要求

- JDK 1.8+（项目已配置为Java 8兼容）
- Node.js 14+
- Spring Boot 2.x
- Maven 3.6+

### 项目结构

```
back/
├── src/main/java/com/gz/iom/iomqwen/
│   ├── mcp/               # MCP服务相关
│   │   ├── impl/          # 实现类
│   │   ├── McpRequest.java
│   │   ├── McpResponse.java
│   │   └── McpService.java
│   ├── rest/              # REST API
│   │   └── McpRest.java
│   └── webconfig/         # WebSocket配置
│       └── WebSocketConfig.java
└── pom.xml
```

### 启动步骤

1. **构建后端服务**
   ```bash
   cd back
   mvn clean package
   ```

2. **运行后端服务**
   ```bash
   java -jar target/your-application.jar
   ```

3. **安装浏览器插件**
   - 加载浏览器扩展到Chrome/Firefox等浏览器
   - 确保扩展已正确注册到后端服务

### 浏览器扩展开发

1. **扩展结构**：
   - 主页面：提供用户输入界面
   - 内容脚本：注入到网页中执行操作
   - 后台脚本：处理与后端的通信

2. **通信方式**：
   - WebSocket：用于实时通信
   - HTTP API：用于注册和备用通信

3. **关键接口**：
   - 扩展注册：`POST /api/mcp/register-extension`
   - 操作执行：`POST /api/mcp/execute-in-tab`
   - 操作列表：`GET /api/mcp/supported-operations`

## 故障排除

### 常见问题与解决方案

1. **WebSocket连接失败**
   - 检查网络连接和防火墙设置
   - 确认WebSocket服务器地址正确
   - 查看浏览器扩展是否有权限建立WebSocket连接

2. **MCP操作执行失败**
   - 检查操作参数是否正确
   - 确认目标页面是否已加载完成
   - 验证选择器是否能正确匹配页面元素

3. **HTTP回退方案激活**
   - 检查WebSocket连接状态
   - 查看后端日志中的错误信息
   - 确认浏览器扩展是否正常运行

## 安全注意事项

1. **敏感信息处理**：密码等敏感信息在日志中使用星号替代
2. **参数验证**：所有API请求都进行严格的参数验证
3. **连接管理**：定期清理无效连接，避免资源泄露
4. **错误处理**：不向客户端暴露详细的服务器错误信息

## 扩展开发指南

### 添加新的MCP操作

1. 在`McpRest.getSupportedOperations()`方法中添加新操作类型
2. 在`NodeMcpServiceImpl`中实现相应的操作逻辑
3. 更新浏览器扩展以支持新操作
4. 编写测试用例验证新操作

### 自定义消息类型

1. 在`WebSocketConfig`中定义新的消息类型常量
2. 添加相应的消息处理逻辑
3. 更新浏览器扩展以支持新消息类型

## 总结

本系统通过结合浏览器插件、WebSocket通信、MCP工具和智能体分析，实现了从用户输入到浏览器界面自动操作的完整闭环。系统采用了WebSocket优先、HTTP回退的双重通信机制，确保操作执行的可靠性和实时性，同时提供了灵活的扩展机制，方便开发者进行功能扩展和定制开发。