JIAP/JIAP_Develop.md

# 九鑫智能自动化协议 (JiuXin Intelligent Automation Protocol, JIAP) 开发文档

**JIAP** 是“九鑫智能自动化协议 (JiuXin Intelligent Automation Protocol)”的缩写，它定义了一套统一、高效、可扩展的机器人流程自动化（RPA）框架。该协议旨在实现跨多种自动化工具和平台的无缝集成，同时确保与主流标准兼容。
 

## 开发文档

### 九鑫智能自动化协议 (JIAP) 开发文档

---

### 目录

1. [简介](#1-简介)
2. [系统架构](#2-系统架构)
3. [API 设计与通信标准](#3-api-设计与通信标准)
4. [模块与方法](#4-模块与方法)
5. [数据模型](#5-数据模型)
6. [认证与安全](#6-认证与安全)
7. [错误处理](#7-错误处理)
8. [可扩展性](#8-可扩展性)
9. [示例与使用场景](#9-示例与使用场景)
10. [常见问题](#10-常见问题)

---

## 1. 简介

**九鑫智能自动化协议 (JiuXin Intelligent Automation Protocol, JIAP)** 提供了一套标准化框架，用于设计、执行和管理 RPA 工作流。目标如下：
- **实现无缝集成**：支持多样化的系统。
- **简化自动化任务**：通过统一的接口执行操作。
- **确保兼容性**：与主流 RPA 平台和协议兼容。

### 核心特点：
- **模块化**：提供文件操作、数据处理、系统任务等功能模块。
- **可扩展性**：支持动态添加新模块及定制化工作流。
- **兼容性**：支持 RESTful API、WebSocket 等主流协议的集成。
- **安全性**：高级认证机制与加密数据传输。

---

## 2. 系统架构

### 核心组件

1. **RPA 控制器**：
   - 负责任务调度、机器人协调及资源分配。
   - 提供外部系统可调用的 API 接口。

2. **机器人代理**：
   - 执行由控制器分配的自动化任务。
   - 与控制器通信，报告任务状态和结果。

3. **活动模块**：
   - 独立的功能单元，例如文件处理、Excel 操作、数据库访问等。
   - 易于扩展，可根据需求添加新功能。

4. **日志与监控系统**：
   - 记录任务执行日志。
   - 提供性能分析与故障排查信息。

---

## 3. API 设计与通信标准

### 3.1 通信协议

- **RESTful API**：
  - 基础 URL: `https://api.jiuxinai.com/v1/jiap`
  - 用于同步任务请求与查询操作。

- **WebSocket**：
  - URL: `wss://api.jiuxinai.com/ws`
  - 支持异步任务执行与实时通信。

### 3.2 标准请求格式

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

### 3.3 标准响应格式

```json
{
  "status": "success",  // success 或 error
  "message": "操作描述",
  "data": {
    "key1": "value1",
    "key2": "value2"
  },
  "timestamp": "2024-04-28T12:00:00Z"
}
```

---

## 4. 模块与方法

### 4.1 文件操作模块

| 方法名             | 描述                   | 参数                                  |
|-------------------|----------------------|-------------------------------------|
| `File.Copy`       | 复制文件               | `source_path`, `destination_path`, `overwrite` |
| `File.Delete`     | 删除文件               | `file_path`                           |
| `File.Rename`     | 重命名文件             | `file_path`, `new_name`               |
| `File.ListFiles`  | 列出目录中的文件        | `directory_path`, `filter_by_extension` |

---

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

---

### 4.3 网络模块

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

---

### 4.4 OCR 模块

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

---

### 4.5 扩展模块

其他模块（如数据库操作、系统命令）可根据需要动态添加。有关详细信息，请参考可扩展性部分。

---

## 5. 数据模型

### 文件元数据模型

```json
{
  "path": "/path/to/file.txt",
  "size": 1024,
  "created_at": "2024-04-01T10:00:00Z",
  "modified_at": "2024-04-28T10:00:00Z"
}
```

### Excel 单元格数据模型

```json
{
  "file_path": "/path/to/excel.xlsx",
  "sheet_name": "Sheet1",
  "cell_name": "A1",
  "value": "123"
}
```

---

## 6. 认证与安全

### 6.1 认证

- **OAuth 2.0**：
  - 使用访问令牌进行 API 请求。
  - 认证端点: `https://api.jiuxinai.com/auth/token`

- **API 密钥**：
  - 简化认证流程，适用于内部场景。

### 6.2 数据安全

- 使用 HTTPS 和 WSS 进行加密通信。
- 敏感数据（如密码）采用行业标准加密存储。

---

## 7. 错误处理

标准化错误响应，确保交互可预测且易于调试。

### 示例错误响应

```json
{
  "status": "error",
  "message": "文件未找到",
  "data": null,
  "timestamp": "2024-04-28T12:00:00Z"
}
```

---

## 8. 可扩展性

### 添加新模块

1. 在配置文件中定义模块和方法。
2. 在后端实现模块逻辑。
3. 通过控制器公开新模块。

### 自定义操作

开发者可通过配置文件或脚本添加自定义工作流，从而扩展协议的功能。

---

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

---

## 10. 常见问题

1. **如何进行 API 请求认证？**  
   使用 OAuth 2.0 令牌或 API 密钥。

2. **JIAP 是否支持主流 RPA 平台集成？**  
   是的，JIAP 通过 RESTful API 实现了与主流 RPA 工具的兼容。

---

以上文档为实现和集成 **九鑫智能自动化协议 (JIAP)** 提供了全面指导。如需更多信息，请联系 **九鑫智能技术支持**：[xiaoyigong@9xin.ai]。

## 协议英文名称

**JiuXin Intelligent Automation Protocol (JIAP)**

**JIAP** stands for "JiuXin Intelligent Automation Protocol," which defines a unified, efficient, and extensible framework for robotic process automation (RPA). The protocol is designed for seamless integration across various automation tools and platforms while ensuring compatibility with mainstream standards.

---

## 开发文档

### JiuXin Intelligent Automation Protocol (JIAP) Developer Documentation

---

### Table of Contents

1. [Introduction](#1-introduction)
2. [System Architecture](#2-system-architecture)
3. [API Design and Communication Standards](#3-api-design-and-communication-standards)
4. [Modules and Methods](#4-modules-and-methods)
5. [Data Models](#5-data-models)
6. [Authentication and Security](#6-authentication-and-security)
7. [Error Handling](#7-error-handling)
8. [Extensibility](#8-extensibility)
9. [Examples and Use Cases](#9-examples-and-use-cases)
10. [FAQ](#10-faq)

---

## 1. Introduction

**JiuXin Intelligent Automation Protocol (JIAP)** provides a standardized framework for designing, executing, and managing RPA workflows. It aims to:
- Enable seamless integration across diverse systems.
- Simplify automation tasks through a unified interface.
- Ensure compatibility with mainstream RPA platforms and protocols.

Key Features:
- **Modularity**: Functional modules for file operations, data processing, system tasks, etc.
- **Extensibility**: Support for adding new modules and customizing workflows.
- **Compatibility**: Integration with RESTful APIs, WebSocket, and other widely adopted protocols.
- **Security**: Advanced authentication and encrypted data transmission.

---

## 2. System Architecture

### Core Components

1. **RPA Controller**:
   - Manages task scheduling, robot orchestration, and resource allocation.
   - Exposes APIs for external systems to interact with RPA workflows.

2. **Robot Agents**:
   - Executes automation tasks assigned by the controller.
   - Communicates with the controller to report task status and results.

3. **Activity Modules**:
   - Encapsulated units for performing specific operations (e.g., file handling, Excel processing, database access).
   - Easily extendable to accommodate new requirements.

4. **Logging and Monitoring System**:
   - Records task execution logs.
   - Provides insights into performance and troubleshooting information.

---

## 3. API Design and Communication Standards

### 3.1 Communication Protocols

- **RESTful API**:
  - Base URL: `https://api.jiuxinai.com/v1/jiap`
  - Used for synchronous task requests and query operations.

- **WebSocket**:
  - URL: `wss://api.jiuxinai.com/ws`
  - Supports asynchronous task execution and real-time communication.

### 3.2 Standard Request Format

```json
{
  "method": "<module>.<operation>",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}
```

### 3.3 Standard Response Format

```json
{
  "status": "success",  // success or error
  "message": "Operation description",
  "data": {
    "key1": "value1",
    "key2": "value2"
  },
  "timestamp": "2024-04-28T12:00:00Z"
}
```

---

## 4. Modules and Methods

### 4.1 File Operations Module

| Method            | Description            | Parameters                              |
|-------------------|------------------------|-----------------------------------------|
| `File.Copy`       | Copy a file            | `source_path`, `destination_path`, `overwrite` |
| `File.Delete`     | Delete a file          | `file_path`                             |
| `File.Rename`     | Rename a file          | `file_path`, `new_name`                 |
| `File.ListFiles`  | List files in a folder | `directory_path`, `filter_by_extension` |

---

### 4.2 Excel Operations Module

| Method                | Description                  | Parameters                                  |
|-----------------------|------------------------------|--------------------------------------------|
| `Excel.ReadCell`      | Read data from a cell        | `file_path`, `sheet_name`, `cell_name`, `password` |
| `Excel.WriteCell`     | Write data to a cell         | `file_path`, `sheet_name`, `cell_name`, `value`, `password` |
| `Excel.MergeCells`    | Merge or unmerge cells       | `file_path`, `sheet_name`, `range_name`, `action` |

---

### 4.3 Network Module

| Method              | Description            | Parameters                     |
|---------------------|------------------------|---------------------------------|
| `Network.HttpGet`   | Perform HTTP GET       | `url`, `headers`               |
| `Network.HttpPost`  | Perform HTTP POST      | `url`, `headers`, `body`       |
| `Network.DownloadFile` | Download a file      | `url`, `save_path`             |

---

### 4.4 OCR Module

| Method                | Description                 | Parameters                     |
|-----------------------|-----------------------------|---------------------------------|
| `OCR.ExtractText`     | Extract text from an image  | `image_path`                   |
| `OCR.ExtractFromPDF`  | Extract text from a PDF     | `pdf_path`                     |

---

### 4.5 Extended Modules

Additional modules such as database operations, system commands, and more can be added dynamically. See the extensibility section for details.

---

## 5. Data Models

### File Metadata Model

```json
{
  "path": "/path/to/file.txt",
  "size": 1024,
  "created_at": "2024-04-01T10:00:00Z",
  "modified_at": "2024-04-28T10:00:00Z"
}
```

### Excel Cell Data Model

```json
{
  "file_path": "/path/to/excel.xlsx",
  "sheet_name": "Sheet1",
  "cell_name": "A1",
  "value": "123"
}
```

---

## 6. Authentication and Security

### 6.1 Authentication

- **OAuth 2.0**:
  - Obtain access tokens for API requests.
  - Endpoint: `https://api.jiuxinai.com/auth/token`

- **API Key**:
  - Simplified authentication for internal use cases.

### 6.2 Data Security

- Encrypted communication using HTTPS and WSS.
- Sensitive data (e.g., passwords) stored securely using industry-standard encryption.

---

## 7. Error Handling

Standardized error responses to ensure predictable and debuggable interactions.

### Example Error Response

```json
{
  "status": "error",
  "message": "File not found",
  "data": null,
  "timestamp": "2024-04-28T12:00:00Z"
}
```

---

## 8. Extensibility

### Adding New Modules

1. Define the module and methods in the configuration file.
2. Implement the module logic in the backend.
3. Expose the module through the controller.

### Custom Operations

Developers can add custom workflows using configuration files or scripts, extending the protocol to meet specific needs.

---

## 9. Examples and Use Cases

### Example: File Copy Operation

**Request**:

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

**Response**:

```json
{
  "status": "success",
  "message": "File copied successfully",
  "data": {
    "source_path": "/source/file.txt",
    "destination_path": "/destination/file.txt",
    "overwrite": true
  },
  "timestamp": "2024-04-28T12:00:00Z"
}
```

---

## 10. FAQ

1. **How do I authenticate API requests?**  
   Use OAuth 2.0 tokens or API keys depending on your deployment.

2. **Can I integrate JIAP with other RPA platforms?**  
   Yes, JIAP is designed to be compatible with mainstream RPA tools through RESTful APIs.

---

This documentation provides a foundation for implementing and integrating **JIAP** in a wide range of automation scenarios. For more information, contact **JiuXin Intelligent Support** at [xiaoyigong@9xin.ai].