# RPA 设备、应用与任务

阅读本文件处理 RPA 设备、应用购买与转移、设备分组、消息转发和群管任务。这里的 `deviceId`/`deviceID` 都指 RPA 设备 ID，不是微号 `botId`；请求字段名必须按各接口表格使用。

## 目录

- [设备](#设备)
- [应用](#应用)
- [设备分组](#设备分组)
- [消息转发](#消息转发)
- [群管](#群管)
- [常用示例](#常用示例)

## 设备

| 目标 | 接口 | 请求字段 | 常用返回字段 |
| --- | --- | --- | --- |
| 设备列表 | `POST /api/rpa/device/list` | `page`(int64, 必填)；`pageSize`(int64, 必填)；`userId`(int64, 可选，主账号按用户筛选)；`appId`(int64, 可选，执行应用 ID)；`name`(string, 可选，设备名称)；`groupID`(int64, 可选，`-1` 未分组、`0` 全部、正数为指定分组) | `items`(repeated DeviceItem，含 `id`, `name`, `execApplicationId`, `expireTime`, `userID`, `userName`, `botType`, `botName`, `botStatus`, `execAppName`)；`page`；`pageSize`；`total`；`last` |
| 设备详情 | `POST /api/rpa/device/info` | `id`(int64, 必填，设备 ID) | `id`；`name`；`execApplicationId`；`expireTime`(毫秒)；`ip`；`port`；`guid`；`botType`；`botName`；`botStatus`；`appInfo`(应用名称、可执行文件、图标、版本、32/64 位下载地址及自动更新配置) |
| 更新设备应用配置 | `POST /api/rpa/device/appUpdate` | `deviceID`(int64, 必填)；`applicationID`(int64, 必填)；`autoUpdate`(bool, 必填)；`updateStart`(string, 必填，`HH:mm:ss`)；`updateEnd`(string, 必填，`HH:mm:ss`)；`forceSystemBit`(int32, 必填，`32`/`64`，`0` 不强制) | 空对象或无业务数据 |
| 删除设备 | `POST /api/rpa/device/delete` | `deviceIDs`(repeated int64, 必填，只能删除没有应用的设备) | 空对象或无业务数据 |
| 切换执行应用 | `POST /api/rpa/device/switchExecApplicationId` | `deviceID`(int64, 必填)；`applicationID`(int64, 必填) | 空对象或无业务数据 |
| RPA 客户端信息 | `POST /api/rpa/client/info` | `{}` | `version`(版本号)；`download`(下载地址)；`updateInfo`(更新信息) |
| 设备执行状态 | `POST /api/rpa/device/status` | `deviceIds`(repeated int64, 必填) | `list`(repeated Status，含 `deviceId`, `appType`, `targetGroupNum`, `successGroupNum`, `failGroupNum`, `updateAt`, `logType`, `logMsg`, `status`) |

设备状态中的 `logType`：`0` 信息、`1` 警告、`2` 错误。`status` 的协议类型是 string，当前说明值为 `0` 等待中、`1` 运行中、`2` 完成，不要改成 JSON 数字。

## 应用

| 目标 | 接口 | 请求字段 | 常用返回字段 |
| --- | --- | --- | --- |
| 应用列表 | `POST /api/rpa/application/list` | `deviceId`(int64, 可选；传入后返回该设备的购买和执行状态) | `items`(repeated ApplicationItem，含 `id`, `name`, `priceByMonth`, `priceByYear`, `isBuy`, `expireTime`, `isExec`, `autoUpdate`, `updateStart`, `updateEnd`, `forceSystemBit`) |
| 购买应用 | `POST /api/rpa/application/buy` | `deviceID`(int64, 必填)；`applicationID`(int64, 必填)；`payMode`(string, 必填，支付方式)；`expireNum`(int64, 必填，购买年/月数量) | `deviceID`；`endDate`(到期时间) |
| 转移应用权限 | `POST /api/rpa/device/application/transfer` | `sourceDeviceID`(int64, 必填)；`targetDeviceID`(int64, 必填)；`applicationIDs`(repeated int64, 必填) | 空对象或无业务数据 |
| 未购买指定应用的设备 | `POST /api/rpa/application/notExistDeviceList` | `applicationID`(int64, 必填)；`name`(string, 必填，设备名称模糊查询)；`groupID`(int64, 必填)；`page`(int64, 必填)；`pageSize`(int64, 必填) | `list`(repeated DeviceItem)；`page`；`pageSize`；`total`；`last` |

## 设备分组

| 目标 | 接口 | 请求字段 | 常用返回字段 |
| --- | --- | --- | --- |
| 分组列表 | `POST /api/rpa/group/list` | `{}` | `items`(repeated GroupItem，含 `id`, `name`) |
| 添加分组 | `POST /api/rpa/group/add` | `name`(string, 必填) | 空对象或无业务数据 |
| 删除分组 | `POST /api/rpa/group/del` | `id`(int64, 必填) | 空对象或无业务数据 |
| 更新分组名称 | `POST /api/rpa/group/update` | `id`(int64, 必填)；`name`(string, 必填) | 空对象或无业务数据 |
| 移动设备 | `POST /api/rpa/group/device/move` | `deviceIDs`(repeated int64, 必填)；`groupID`(int64, 必填，目标分组 ID) | 空对象或无业务数据 |

## 消息转发

| 目标 | 接口 | 请求字段 | 常用返回字段 |
| --- | --- | --- | --- |
| 转发配置详情 | `POST /api/rpa/msgforward/info` | `deviceId`(int64, 必填) | `id`(转发配置 ID)；`sendRate`(最高 1 倍，向下递减)；`groupNames`(目标群名)；`listenGroupName`(监听群名) |
| 更新转发配置 | `POST /api/rpa/msgforward/update` | `deviceId`(int64, 必填)；`sendRate`(float, 可选，最高 1 倍)；`groupNames`(repeated string, 可选)；`listenGroupName`(string, 可选) | 空对象或无业务数据 |
| 转发执行状态 | `POST /api/rpa/msgforward/status` | `deviceIds`(repeated int64, 必填) | `list`(repeated Status，含 `deviceId`, `targetGroupNum`, `successGroupNum`, `failGroupNum`, `updateAt`, `logType`, `logMsg`, `status`) |

转发状态中的 `logType` 和 `status` 取值与设备执行状态相同。

## 群管

| 目标 | 接口 | 请求字段 | 常用返回字段 |
| --- | --- | --- | --- |
| 群管配置详情 | `POST /api/rpa/qunguan/info` | `deviceId`(int64, 必填) | `deviceId`；`sendRate`(最高 1 倍，向下递减)；`groupNames`(群名列表) |
| 更新群管配置 | `POST /api/rpa/qunguan/update` | `deviceId`(int64, 必填)；`sendRate`(float, 可选，最高 1 倍)；`groupNames`(repeated string, 可选) | 空对象或无业务数据 |
| 待执行任务列表 | `POST /api/rpa/qunguan/taskList` | `deviceId`(int64, 必填) | `taskInfos`(repeated TaskInfo，含 `taskId`, `methodType`, `content`, `isAtAll`) |
| 发送任务 | `POST /api/rpa/qunguan/sendTask` | `deviceId`(int64, 必填)；`methodType`(int32, 必填)；`content`(string, 必填)；`isAtAll`(bool, 可选，仅方式 2、3 生效) | 空对象或无业务数据 |
| 删除任务 | `POST /api/rpa/qunguan/delTask` | `deviceId`(int64, 必填)；`taskIds`(repeated string, 必填) | 空对象或无业务数据 |

群管 `methodType`：`1` 修改群名，`2` 群发消息，`3` 修改群公告，`4` 邀请进群。`content` 随类型分别填写群名规则、群发内容、公告内容或受邀者名称。

## 常用示例

```bash
# 查看全部 RPA 设备
htsy-cli call /api/rpa/device/list -d '{"page":1,"pageSize":20,"groupID":0}'

# 查看指定设备已购买和正在执行的应用
htsy-cli call /api/rpa/application/list -d '{"deviceId":1001}'

# 配置消息转发
htsy-cli call /api/rpa/msgforward/update -d '{"deviceId":1001,"sendRate":1,"listenGroupName":"订单群","groupNames":["客户群A","客户群B"]}'

# 向群管设备下发群公告任务
htsy-cli call /api/rpa/qunguan/sendTask -d '{"deviceId":1001,"methodType":3,"content":"今日活动已开始","isAtAll":true}'
```

设备注册、设备拉取任务和设备执行数据上报是 RPA 客户端内部流程，不作为常规业务 API 调用。