# 九鑫智能 RPA 协议与定义

## 1. 协议目标
- **统一性**：所有功能使用统一的接口、参数和返回值结构，保证一致性。
- **高效性**：设计轻量化的协议格式和高性能的执行方式，减少网络和系统资源开销。
- **可扩展性**：支持动态扩展新的功能模块和操作类型，兼容未来需求。
- **互操作性**：协议与主流 RPA 平台的 API 和方法兼容，便于集成。
- **安全性**：数据传输和存储中提供安全性保障，支持身份认证和权限控制。

---

## 2. 总体架构

```mermaid
graph TD
    A[Client/用户] -->|API请求| B[RPA控制器]
    B -->|任务分配| C[机器人代理]
    C -->|调用| D[活动模块]
    D -->|执行操作| C
    C -->|任务结果| B
    B -->|响应| A
    B --> E[日志与监控系统]
    C --> E
    D --> E
```

### 2.1 系统组件

1. **RPA 控制器（Controller）**：
   - 管理任务调度、运行状态监控。
   - 提供 API 接口供客户端调用。

2. **RPA 机器人（Robot Agent）**：
   - 执行具体任务的独立运行单元。
   - 接收控制器的指令，调用底层操作模块完成任务。

3. **RPA 操作模块（Activity Modules）**：
   - 独立的功能模块，每个模块对应特定任务类型（如文件操作、OCR、Excel 操作等）。
   - 提供通用接口供机器人调用。

4. **日志与监控系统**：
   - 实时记录任务状态、执行日志。
   - 支持追溯与错误排查。

```mermaid 
sequenceDiagram
    participant Client as 客户端
    participant Controller as 控制器
    participant Robot as 机器人代理
    participant Module as 活动模块

    Client->>Controller: 发送任务请求
    Controller->>Controller: 分析任务类型
    Controller->>Robot: 分配任务
    Robot->>Module: 调用相关操作模块
    Module->>Robot: 返回操作结果
    Robot->>Controller: 返回任务结果
    Controller->>Client: 响应任务结果
``` 

---

### 2.2 数据流设计

1. **客户端请求**：
   - 客户端通过 RESTful API 或 WebSocket 向控制器发送请求。
2. **任务调度**：
   - 控制器接收请求后，根据任务类型和资源情况，将任务分配给适当的机器人。
3. **任务执行**：
   - 机器人执行具体任务，并调用操作模块完成工作。
4. **结果返回**：
   - 机器人将任务结果返回给控制器，由控制器统一响应客户端请求。
  
  
```mermaid
flowchart TD
    A[客户端请求] -->|RESTful API/WebSocket| B[控制器]
    B -->|任务调度| C[机器人代理]
    C -->|调用活动模块| D[活动模块]
    D -->|执行结果| C
    C -->|任务结果| B
    B -->|响应| E[客户端]
    B --> F[日志与监控系统]
    C --> F
    D --> F
``` 
---

## 3. 接口协议规范

### 3.1 通信协议
- **协议类型**：支持 RESTful API（同步）和 WebSocket（异步）。
- **数据格式**：使用 JSON 作为数据交互格式，支持 UTF-8 编码。

### 3.2 API 基础结构

1. **基础 URL**：
   - RESTful API 基础 URL: `https://api.jiuxinai.com/v1/rpa`
   - WebSocket URL: `wss://api.jiuxinai.com/ws`

2. **HTTP 请求方法**：
   - `GET`：查询资源。
   - `POST`：创建资源或发送任务。
   - `PUT`：更新资源。
   - `DELETE`：删除资源。

3. **HTTP 状态码**：
   - `200`：请求成功。
   - `400`：客户端请求错误。
   - `401`：认证失败。
   - `404`：资源未找到。
   - `500`：服务器错误。

---

## 4. 方法定义与参数

### 4.1 标准方法格式

所有方法名称采用统一格式：`<模块>.<操作>`，例如 `File.Copy`、`Excel.ReadCell`。

**接口格式**：

```json
{
  "method": "<模块>.<操作>",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}
```

**返回值格式**：

```json
{
  "status": "success",  // success 或 error
  "message": "操作描述",
  "data": {
    // 返回的具体数据
  },
  "timestamp": "2024-04-28T12:00:00Z"
}
```

---

### 4.2 功能模块定义

#### 文件操作模块

| 方法名       | 描述                  | 参数                              |
|-------------|-----------------------|-----------------------------------|
| File.Copy   | 复制文件               | source_path, destination_path, overwrite |
| File.Delete | 删除文件               | file_path                        |
| File.Rename | 重命名文件             | file_path, new_name              |

#### Excel 操作模块

| 方法名              | 描述                 | 参数                              |
|--------------------|----------------------|-----------------------------------|
| Excel.ReadCell     | 读取 Excel 单元格值   | file_path, sheet_name, cell_name, password |
| Excel.WriteCell    | 写入 Excel 单元格值   | file_path, sheet_name, cell_name, value, password |
| Excel.MergeCells   | 合并单元格            | file_path, sheet_name, range_name, action |

#### 二维码模块

| 方法名                 | 描述                  | 参数                              |
|-----------------------|-----------------------|-----------------------------------|
| QRCode.Generate       | 生成二维码             | text, save_path, width, height   |
| QRCode.Parse          | 解析二维码             | file_path                        |

#### 时间模块

| 方法名              | 描述                  | 参数       |
|--------------------|-----------------------|-----------|
| Time.GetCurrentTime| 获取当前时间            | 无        |
| Time.Format         | 格式化时间              | time, format |

#### 网络请求模块

| 方法名            | 描述                  | 参数                              |
|------------------|-----------------------|-----------------------------------|
| Network.HttpGet  | 发送 HTTP GET 请求     | url, headers                     |
| Network.HttpPost | 发送 HTTP POST 请求    | url, headers, body               |

---

## 5. 数据模型定义

1. **文件模型**：
   - **文件路径**：`path` (String)
   - **文件大小**：`size` (Int)
   - **创建时间**：`created_at` (String, ISO 8601)
   - **修改时间**：`modified_at` (String, ISO 8601)

2. **Excel 单元格模型**：
   - **单元格值**：`value` (String 或 Number)
   - **工作表名称**：`sheet_name` (String)
   - **单元格位置**：`cell_name` (String)

3. **二维码模型**：
   - **文本内容**：`text` (String)
   - **二维码路径**：`file_path` (String)
   - **二维码大小**：`width`, `height` (Int)

---

## 6. 扩展能力

- **动态模块加载**：
  - 使用插件机制动态加载新的功能模块，例如 OCR、数据库操作模块等。
- **自定义操作定义**：
  - 支持用户通过配置文件自定义新的操作定义，增加灵活性。

---

## 7. 兼容性设计

- **主流 RPA 平台支持**：
  - 方法命名参考主流平台（如 UiPath）保持一致，便于迁移。
- **协议兼容**：
  - 使用开放协议（如 RESTful 和 WebSocket），确保与外部系统集成的便捷性。
- **多语言支持**：
  - 数据交互统一采用 UTF-8 编码，支持多语言输入和输出。

---

## 8. 安全性规范

1. **身份认证**：
   - 使用 OAuth2 或 JWT 进行访问控制。
2. **权限管理**：
   - 基于角色（Role-Based Access Control, RBAC）设计权限。
3. **数据加密**：
   - 传输过程中使用 HTTPS，敏感数据存储时加密。

---

## 9. 协议示例

### 任务请求示例

```json
{
  "method": "File.Copy",
  "params": {
    "source_path": "/source/file.txt",
    "destination_path": "/destination/file.txt",
    "overwrite": true
  }
}
```

### 返回值示例

```json
{
  "status": "success",
  "message": "文件复制成功",
  "data": {
    "source_path": "/source/file.txt",
    "destination_path": "/destination/file.txt",
    "overwrite": true
  },
  "timestamp": "2024-04-28T12:00:00Z"
}
```

以下是扩展后的 RPA 功能模块设计，尽可能涵盖各类常见的 RPA 操作，包括文件管理、办公自动化、数据处理、网络操作、图像处理、系统操作等功能。每个模块都包含操作方法和对应的参数定义。

---

## 扩展后的功能模块

### 1. 文件操作模块

**描述**：提供文件管理相关操作。

| 方法名             | 描述                     | 参数                                    |
|-------------------|--------------------------|---------------------------------------|
| File.Copy         | 复制文件                 | source_path, destination_path, overwrite |
| File.Delete       | 删除文件                 | file_path                              |
| File.Rename       | 重命名文件               | file_path, new_name                    |
| File.Create       | 创建新文件               | file_path, content                     |
| File.ReadContent  | 读取文件内容             | file_path                              |
| File.WriteContent | 写入文件内容             | file_path, content, overwrite          |
| File.ListFiles    | 列出目录中的所有文件     | directory_path, filter_by_extension    |
| File.GetInfo      | 获取文件信息             | file_path                              |

---

### 2. 目录操作模块

**描述**：提供目录管理相关操作。

| 方法名               | 描述                     | 参数                                |
|---------------------|--------------------------|------------------------------------|
| Directory.Create    | 创建目录                 | directory_path                     |
| Directory.Delete    | 删除目录（可递归删除）   | directory_path, recursive          |
| Directory.ListFiles | 列出目录中的文件         | directory_path                     |
| Directory.ListDirs  | 列出子目录               | directory_path                     |

---

## 3. Excel 操作模块

**描述**：支持对 Excel 文件的各种操作。

| 方法名                | 描述                     | 参数                                      |
|----------------------|--------------------------|-----------------------------------------|
| Excel.ReadCell       | 读取 Excel 单元格值       | file_path, sheet_name, cell_name, password |
| Excel.WriteCell      | 写入 Excel 单元格值       | file_path, sheet_name, cell_name, value, password |
| Excel.MergeCells     | 合并或取消合并单元格       | file_path, sheet_name, range_name, action |
| Excel.ReadRange      | 读取指定范围的单元格数据   | file_path, sheet_name, range_name        |
| Excel.WriteRange     | 写入指定范围的单元格数据   | file_path, sheet_name, range_name, values |
| Excel.AddSheet       | 添加新的工作表            | file_path, sheet_name                   |
| Excel.DeleteSheet    | 删除指定的工作表          | file_path, sheet_name                   |
| Excel.ListSheets     | 列出所有工作表            | file_path                               |

---

### 4. Word 操作模块

**描述**：支持对 Word 文档的各种操作。

| 方法名                    | 描述                     | 参数                              |
|--------------------------|--------------------------|----------------------------------|
| Word.ReadContent         | 读取文档内容             | file_path, visible               |
| Word.WriteContent        | 写入文档内容             | file_path, content, overwrite    |
| Word.ReplaceText         | 替换文档中的指定文本      | file_path, find_text, replace_text |
| Word.AddTable            | 向文档添加表格           | file_path, rows, columns         |
| Word.AddImage            | 向文档插入图片           | file_path, image_path, position  |
| Word.CloseDocument       | 关闭文档                 | file_path, visible               |

---

### 5. 图像处理模块

**描述**：支持对图像的基本处理操作。

| 方法名                  | 描述                     | 参数                                |
|------------------------|--------------------------|------------------------------------|
| Image.Resize           | 调整图像大小             | image_path, width, height         |
| Image.ConvertFormat    | 转换图像格式             | image_path, target_format         |
| Image.Rotate           | 旋转图像                 | image_path, angle                 |
| Image.Crop             | 裁剪图像                 | image_path, x, y, width, height   |
| Image.AddWatermark     | 向图像添加水印           | image_path, watermark_text, position |
| Image.ParseQRCode      | 从图像解析二维码          | image_path                        |
| Image.GenerateQRCode   | 生成二维码图像           | content, save_path, size          |

---

### 6. 压缩与解压模块

**描述**：支持文件或目录的压缩与解压缩。

| 方法名                   | 描述                     | 参数                                |
|-------------------------|--------------------------|------------------------------------|
| Archive.Compress        | 压缩文件或目录           | source_paths, output_path, format |
| Archive.Decompress      | 解压缩文件               | archive_path, destination_path    |

---

### 7. 网络操作模块

**描述**：支持 HTTP 请求和网络下载功能。

| 方法名                | 描述                     | 参数                              |
|----------------------|--------------------------|----------------------------------|
| Network.HttpGet      | 发送 HTTP GET 请求        | url, headers                     |
| Network.HttpPost     | 发送 HTTP POST 请求       | url, headers, body               |
| Network.DownloadFile | 下载文件                 | url, save_path                   |

---

### 8. 数据库操作模块

**描述**：支持基本的数据库查询和修改操作。

| 方法名                   | 描述                     | 参数                                  |
|-------------------------|--------------------------|--------------------------------------|
| Database.Connect        | 连接数据库               | connection_string                    |
| Database.ExecuteQuery   | 执行 SQL 查询            | query, parameters                    |
| Database.Insert         | 插入数据                 | table_name, data                     |
| Database.Update         | 更新数据                 | table_name, data, condition          |
| Database.Delete         | 删除数据                 | table_name, condition                |

---

### 9. 系统操作模块

**描述**：提供系统级别的操作功能。

| 方法名                  | 描述                     | 参数                                |
|------------------------|--------------------------|------------------------------------|
| System.GetEnvironment  | 获取环境变量             | variable_name                      |
| System.SetEnvironment  | 设置环境变量             | variable_name, value               |
| System.ExecuteCommand  | 执行系统命令             | command                            |
| System.GetSystemInfo   | 获取系统信息             | 无                                 |

---

### 10. 时间与日期模块

**描述**：支持时间和日期的处理操作。

| 方法名                 | 描述                     | 参数                                |
|-----------------------|--------------------------|------------------------------------|
| Time.GetCurrentTime   | 获取当前时间             | 无                                 |
| Time.AddTime          | 时间加减运算             | base_time, delta, unit            |
| Time.FormatTime       | 格式化时间               | time, format                      |

---

### 11. OCR（光学字符识别）模块

**描述**：提供 OCR 操作，支持从图像中提取文本。

| 方法名                  | 描述                     | 参数                                |
|------------------------|--------------------------|------------------------------------|
| OCR.ExtractText        | 从图像中提取文本         | image_path                        |
| OCR.ExtractFromPDF     | 从 PDF 文件提取文本       | pdf_path                          |

---

### 12. 邮件操作模块

**描述**：支持邮件发送和接收操作。

| 方法名                  | 描述                     | 参数                                |
|------------------------|--------------------------|------------------------------------|
| Email.SendEmail        | 发送邮件                 | to, subject, body, attachments    |
| Email.ReceiveEmails    | 接收邮件                 | email_address, password, filters  |

---

### 13. API 集成模块

**描述**：提供对外部 API 的集成能力。

| 方法名                | 描述                     | 参数                              |
|----------------------|--------------------------|----------------------------------|
| API.Call             | 调用外部 API             | endpoint, method, headers, body |

---

### 14. 文件传输模块

**描述**：支持文件的上传与下载。

| 方法名                  | 描述                     | 参数                                |
|------------------------|--------------------------|------------------------------------|
| FileTransfer.Upload    | 上传文件到远程服务器     | file_path, server_url, credentials |
| FileTransfer.Download  | 从远程服务器下载文件     | file_url, save_path, credentials   |

---

### 扩展说明

这套设计包含了常见的企业自动化场景，涵盖文件管理、办公自动化、网络操作、系统操作、数据库管理、图像处理等模块。每个模块提供了基础操作和扩展能力，能够满足大部分 RPA 的功能需求，并为未来的业务需求扩展提供了良好的基础。