JIAP/suggest.md

# RPA 函数规范化定义建议
以下是经过规范化和统一化后的 RPA 函数定义。主要规范化的方面包括：

1. **方法名**：统一为驼峰命名法，前缀统一为模块名（`Lan`）+ 功能描述 + 动作。
2. **参数名**：统一使用小写字母+下划线命名法。
3. **可选参数**：明确标注可选参数，并使用一致的命名和格式。
4. **参数命名与描述**：确保参数名简洁、描述一致且直观。
5. **返回值统一**：移除冗余的变量接收参数，通过响应中返回。

---

### 规范化后的定义

#### 1. 文件复制操作

```plaintext
**方法名**：Lan.Core.CopyFile  
**描述**：复制文件并粘贴到指定目标路径。

**参数**：
- source_file_path (String, 必填)：原始文件的完整路径。
- target_file_path (String, 必填)：目标文件夹路径。
- target_file_name (String, 可选)：目标文件名，默认使用原始文件名。
- overwrite (Boolean, 必填)：是否覆盖目标路径中的同名文件。可选值：true/false。
```

---

#### 2. 读取 Excel 单元格

```plaintext
**方法名**：Lan.Excel.ReadCell  
**描述**：读取 Excel 表格中指定单元格的内容。

**参数**：
- file_path (String, 必填)：Excel 文件的完整路径。
- sheet_name (String, 必填)：工作表名称。
- cell_name (String, 必填)：单元格名称（如 A1、B2）。
- password (String, 可选)：Excel 文件密码。
```

---

#### 3. 写入 Excel 单元格

```plaintext
**方法名**：Lan.Excel.WriteCell  
**描述**：向 Excel 表格中指定单元格写入内容。

**参数**：
- file_path (String, 必填)：Excel 文件的完整路径。
- sheet_name (String, 必填)：工作表名称。
- cell_name (String, 必填)：单元格名称（如 A1、B2）。
- cell_value (Object, 必填)：要写入的内容。
- password (String, 可选)：Excel 文件密码。
```

---

#### 4. 合并/取消合并单元格

```plaintext
**方法名**：Lan.Excel.MergeCells  
**描述**：合并或取消合并 Excel 表格中的单元格。

**参数**：
- file_path (String, 必填)：Excel 文件的完整路径。
- sheet_name (String, 必填)：工作表名称。
- range_name (String, 必填)：单元格区域名称（如 A1:C3）。
- option (String, 必填)：操作类型，可选值："merge"（合并）或 "unmerge"（取消合并）。
- password (String, 可选)：Excel 文件密码。
```

---

#### 5. 关闭 Word 文档

```plaintext
**方法名**：Lan.Word.CloseDocument  
**描述**：关闭指定路径下的 Word 文档。

**参数**：
- file_path (String, 必填)：Word 文档的完整路径。
- visible (Boolean, 必填)：文档是否可见。可选值：true/false。
```

---

#### 6. 读取 Word 文档内容

```plaintext
**方法名**：Lan.Word.ReadDocument  
**描述**：读取 Word 文档中的所有文本内容。

**参数**：
- file_path (String, 必填)：Word 文档的完整路径。
- visible (Boolean, 必填)：文档是否可见。可选值：true/false。
```

---

#### 7. 生成二维码

```plaintext
**方法名**：Lan.QRCode.Generate  
**描述**：将输入文本生成二维码图像并保存到指定路径。

**参数**：
- save_file_path (String, 必填)：二维码图像的保存路径（需指定格式，如 example.jpg）。
- text (String, 必填)：要存储在二维码中的文本或 URL。
- width (Int, 必填)：二维码图像的宽度。
- height (Int, 必填)：二维码图像的高度。
```

---

#### 8. 解析二维码

```plaintext
**方法名**：Lan.QRCode.Parse  
**描述**：解析二维码图像并提取其中的文本数据。

**参数**：
- file_path (String, 必填)：二维码图像的完整路径。
```

---

#### 9. ASCII 转字符串

```plaintext
**方法名**：Lan.Core.ASCIIToString  
**描述**：将 ASCII 编码转换为字符串。

**参数**：
- ascii_code (String, 必填)：需要转换的 ASCII 编码字符串。
```

---

#### 10. 字符串转 ASCII

```plaintext
**方法名**：Lan.Core.StringToASCII  
**描述**：将字符串转换为 ASCII 编码格式。

**参数**：
- input_string (String, 必填)：需要转换的字符串。
```

---

### 规范总结

1. **方法名**：采用模块前缀（如 `Lan.Core`、`Lan.Excel`）+ 功能描述 + 动作，保持一致。
2. **参数命名**：统一为小写字母+下划线的命名方式，确保易读和规范。
3. **参数顺序**：必填参数在前，可选参数在后。
4. **参数类型**：明确标注类型（如 String、Boolean、Int）。
5. **选项值标准化**：将布尔值统一为 `true/false`，其他选项如操作类型明确约束（如 "merge"、"unmerge"）。
6. **描述**：方法描述简洁清晰，参数的功能和用法明确统一。 

## 返回值
以下是为 RPA 函数定义提供的**统一规范返回值**。返回值结构简洁、统一，确保每个方法在执行后能够清晰地传达执行状态、结果和相关信息。 

### 返回值统一格式

所有函数返回值将遵循以下 JSON 格式：

```json
{
  "status": "success",  // 执行状态: success / error
  "message": "操作成功",  // 简要描述执行结果
  "data": {  // 执行结果的具体数据
    "key": "value"
  },
  "timestamp": "2024-04-28T12:00:00Z"  // 服务器响应的时间戳
}
```

#### 字段解释：
1. **status**：  
   - `success`：操作成功。  
   - `error`：操作失败。  

2. **message**：简要描述执行结果的文本信息。  

3. **data**：返回的具体数据，结构根据方法的实际执行结果而定。  

4. **timestamp**：操作完成的时间，ISO8601 格式。

---

### 各方法返回值定义

#### 1. 文件复制操作 - `Lan.Core.CopyFile`

##### 返回值示例（成功）：

```json
{
  "status": "success",
  "message": "文件复制成功",
  "data": {
    "source_file_path": "/path/to/source/fileA.txt",
    "target_file_path": "/path/to/destination/fileA_copy.txt",
    "overwrite": true
  },
  "timestamp": "2024-04-28T12:00:00Z"
}
```

---

### 2. 读取 Excel 单元格 - `Lan.Excel.ReadCell`

##### 返回值示例（成功）：

```json
{
  "status": "success",
  "message": "单元格读取成功",
  "data": {
    "file_path": "/path/to/excel.xlsx",
    "sheet_name": "Sheet1",
    "cell_name": "A1",
    "cell_value": "123"
  },
  "timestamp": "2024-04-28T12:00:00Z"
}
```

---

#### 3. 写入 Excel 单元格 - `Lan.Excel.WriteCell`

##### 返回值示例（成功）：

```json
{
  "status": "success",
  "message": "单元格写入成功",
  "data": {
    "file_path": "/path/to/excel.xlsx",
    "sheet_name": "Sheet1",
    "cell_name": "A1",
    "cell_value": "Hello World"
  },
  "timestamp": "2024-04-28T12:00:00Z"
}
```

---

### 4. 合并/取消合并单元格 - `Lan.Excel.MergeCells`

##### 返回值示例（成功）：

```json
{
  "status": "success",
  "message": "单元格合并成功",
  "data": {
    "file_path": "/path/to/excel.xlsx",
    "sheet_name": "Sheet1",
    "range_name": "A1:C3",
    "operation": "merge"
  },
  "timestamp": "2024-04-28T12:00:00Z"
}
```

---

#### 5. 关闭 Word 文档 - `Lan.Word.CloseDocument`

##### 返回值示例（成功）：

```json
{
  "status": "success",
  "message": "Word 文档关闭成功",
  "data": {
    "file_path": "/path/to/document.docx",
    "visible": false
  },
  "timestamp": "2024-04-28T12:00:00Z"
}
```

---

### 6. 读取 Word 文档内容 - `Lan.Word.ReadDocument`

##### 返回值示例（成功）：

```json
{
  "status": "success",
  "message": "文档读取成功",
  "data": {
    "file_path": "/path/to/document.docx",
    "content": "这是文档的全部内容。"
  },
  "timestamp": "2024-04-28T12:00:00Z"
}
```

---

#### 7. 生成二维码 - `Lan.QRCode.Generate`

##### 返回值示例（成功）：

```json
{
  "status": "success",
  "message": "二维码生成成功",
  "data": {
    "save_file_path": "/path/to/qrcode.jpg",
    "text": "https://example.com",
    "width": 200,
    "height": 200
  },
  "timestamp": "2024-04-28T12:00:00Z"
}
```

---

#### 8. 解析二维码 - `Lan.QRCode.Parse`

##### 返回值示例（成功）：

```json
{
  "status": "success",
  "message": "二维码解析成功",
  "data": {
    "file_path": "/path/to/qrcode.jpg",
    "text": "https://example.com"
  },
  "timestamp": "2024-04-28T12:00:00Z"
}
```

---

#### 9. ASCII 转字符串 - `Lan.Core.ASCIIToString`

##### 返回值示例（成功）：

```json
{
  "status": "success",
  "message": "ASCII 转换成功",
  "data": {
    "ascii_code": "65 66 67",
    "result": "ABC"
  },
  "timestamp": "2024-04-28T12:00:00Z"
}
```

---

#### 10. 字符串转 ASCII - `Lan.Core.StringToASCII`

##### 返回值示例（成功）：

```json
{
  "status": "success",
  "message": "字符串转换为 ASCII 成功",
  "data": {
    "input_string": "ABC",
    "ascii_code": "65 66 67"
  },
  "timestamp": "2024-04-28T12:00:00Z"
}
```

---

#### 统一错误返回值示例

如果操作失败，返回以下格式的错误信息：

```json
{
  "status": "error",
  "message": "文件路径不存在",
  "data": null,
  "timestamp": "2024-04-28T12:00:00Z"
}
```

#### 字段说明：
1. **status**：`error` 表示操作失败。
2. **message**：包含错误原因的简要描述。
3. **data**：失败时为 `null`。
4. **timestamp**：错误发生的时间。

---

## 总结

### 统一规范总结：
1. **方法返回值**：统一格式，包含 `status`、`message`、`data` 和 `timestamp` 字段。
2. **成功返回**：返回详细的操作数据，易于跟踪和验证。
3. **失败返回**：提供明确的错误消息，方便调试和处理。
4. **一致性**：所有方法均遵循相同的返回值结构，增强了接口的可维护性和标准化。