fatsand/JIAP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
03100cab08
JIAP/suggest.md
fatsand c036c8c168 first commit
2024-12-19 10:15:23 +08:00

9.6 KiB
Raw Blame History

RPA 函数规范化定义建议

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

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

规范化后的定义

1. 文件复制操作

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

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

2. 读取 Excel 单元格

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

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

3. 写入 Excel 单元格

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

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

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

**方法名**：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 文档

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

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

6. 读取 Word 文档内容

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

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

7. 生成二维码

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

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

8. 解析二维码

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

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

9. ASCII 转字符串

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

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

10. 字符串转 ASCII

**方法名**：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 格式：

{
  "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

返回值示例（成功）：
{
  "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

返回值示例（成功）：
{
  "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

返回值示例（成功）：
{
  "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

返回值示例（成功）：
{
  "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

返回值示例（成功）：
{
  "status": "success",
  "message": "Word 文档关闭成功",
  "data": {
    "file_path": "/path/to/document.docx",
    "visible": false
  },
  "timestamp": "2024-04-28T12:00:00Z"
}

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

返回值示例（成功）：
{
  "status": "success",
  "message": "文档读取成功",
  "data": {
    "file_path": "/path/to/document.docx",
    "content": "这是文档的全部内容。"
  },
  "timestamp": "2024-04-28T12:00:00Z"
}

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

返回值示例（成功）：
{
  "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

返回值示例（成功）：
{
  "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

返回值示例（成功）：
{
  "status": "success",
  "message": "ASCII 转换成功",
  "data": {
    "ascii_code": "65 66 67",
    "result": "ABC"
  },
  "timestamp": "2024-04-28T12:00:00Z"
}

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

返回值示例（成功）：
{
  "status": "success",
  "message": "字符串转换为 ASCII 成功",
  "data": {
    "input_string": "ABC",
    "ascii_code": "65 66 67"
  },
  "timestamp": "2024-04-28T12:00:00Z"
}

统一错误返回值示例

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

{
  "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. 一致性：所有方法均遵循相同的返回值结构，增强了接口的可维护性和标准化。