176 lines
6.5 KiB
Markdown
176 lines
6.5 KiB
Markdown
# PTT 平台外部接口详细文档
|
|
|
|
**基础路径**: `/api/external/ptt`
|
|
**说明**: 该控制器是与第三方 PTT 语音平台对接的核心入口，涵盖了频道管理、成员状态、录音存取及语音识别等全量功能。
|
|
|
|
---
|
|
|
|
## 1. 频道与会话管理
|
|
|
|
### 三、创建频道
|
|
* **接口**: `POST /group`
|
|
* **描述**: 在平台创建一个新的普通频道，支持邀请账号列表或用户 UID 列表。
|
|
* **参数**:
|
|
* `gname` (Query, 必填): 群组/频道名称。
|
|
* `accounts` (Body, 可选): 参与成员账号列表 (`List<String>`)。
|
|
* `uids` (Query, 可选): 参与成员 UID 列表 (`List<Integer>`)。
|
|
* **返回**: `Result<PttModels.OpData>`
|
|
|
|
### 四、删除频道
|
|
* **接口**: `DELETE /group/{gid}`
|
|
* **描述**: 删除指定的普通频道。
|
|
* **参数**:
|
|
* `gid` (Path, 必填): 频道 ID。
|
|
* **返回**: `Result<Boolean>`
|
|
|
|
### 五、修改频道
|
|
* **接口**: `PUT /group/{gid}`
|
|
* **描述**: 修改频道的名称信息。
|
|
* **参数**:
|
|
* `gid` (Path, 必填): 频道 ID。
|
|
* `newName` (Query, 必填): 新的频道名称。
|
|
* **返回**: `Result<Boolean>`
|
|
|
|
### 六、拉成员入频道
|
|
* **接口**: `POST /group/{gid}/members`
|
|
* **描述**: 将指定的账号列表加入到特定的频道中。
|
|
* **参数**:
|
|
* `gid` (Path, 必填): 频道 ID。
|
|
* `accounts` (Body, 必填): 待加入的成员账号列表 (`List<String>`)。
|
|
* **返回**: `Result<Boolean>`
|
|
|
|
### 七、成员踢出频道
|
|
* **接口**: `DELETE /group/{gid}/members`
|
|
* **描述**: 将指定的账号列表从频道中移除。
|
|
* **参数**:
|
|
* `gid` (Path, 必填): 频道 ID。
|
|
* `accounts` (Body, 必填): 待移除的成员账号列表 (`List<String>`)。
|
|
* **返回**: `Result<Boolean>`
|
|
|
|
### 二十、创建临时会话
|
|
* **接口**: `POST /temp-group`
|
|
* **描述**: 发起一个新的临时群组通话。
|
|
* **参数**:
|
|
* `gname` (Query, 必填): 群组名称。
|
|
* `accounts` (Body, 必填): 参与成员账号列表 (`List<String>`)。
|
|
* `creatorid` (Query, 必填): 创建者 UID。
|
|
* **返回**: `Result<PttModels.OpData>`
|
|
|
|
### 二十一、删除临时会话
|
|
* **接口**: `DELETE /temp-group/{gid}`
|
|
* **描述**: 注销/结束一个临时群组。
|
|
* **参数**:
|
|
* `gid` (Path, 必填): 临时群组 ID。
|
|
* **返回**: `Result<Boolean>`
|
|
|
|
---
|
|
|
|
## 2. 列表与成员查询
|
|
|
|
### 八、频道成员列表
|
|
* **接口**: `GET /group/{gid}/members`
|
|
* **描述**: 查询指定普通频道内的成员列表，支持搜索和分页。
|
|
* **参数**:
|
|
* `gid` (Path, 必填): 频道 ID。
|
|
* `page`, `limit` (Query, 可选): 分页参数。
|
|
* `search` (Query, 可选): 搜索关键词（用户名/账号）。
|
|
* **返回**: `Result<PttResult<List<PttModels.Member>>>`
|
|
|
|
### 九、频道列表查询
|
|
* **接口**: `GET /groups`
|
|
* **描述**: 获取系统内所有的普通频道列表。
|
|
* **参数**: `page`, `limit` (Query, 可选)。
|
|
* **返回**: `Result<PttResult<List<PttModels.Group>>>`
|
|
|
|
### 十、临时会话列表查询
|
|
* **接口**: `GET /temp-groups`
|
|
* **描述**: 获取所有的临时群组列表。
|
|
* **参数**: `page`, `limit` (Query, 可选)。
|
|
* **返回**: `Result<PttResult<List<PttModels.Group>>>`
|
|
|
|
### 十一、成员可见频道列表查询
|
|
* **接口**: `GET /user/groups`
|
|
* **描述**: 查询指定成员有权限查看的频道。
|
|
* **参数**: `account`, `uid`, `search` (Query, 可选)。
|
|
* **返回**: `Result<List<PttModels.Group>>`
|
|
|
|
### 二十九、查询某个临时群组下的成员
|
|
* **接口**: `GET /temp-group/{tempgid}/members`
|
|
* **描述**: 获取指定临时群组内的所有成员详情。
|
|
* **参数**: `tempgid` (Path, 必填)。
|
|
* **返回**: `Result<List<PttModels.Member>>`
|
|
|
|
### 三十一、分页查询群组成员
|
|
* **接口**: `GET /group/{gid}/members-paged`
|
|
* **描述**: 按在线状态分页查询群组成员。
|
|
* **参数**:
|
|
* `gid` (Path, 必填)。
|
|
* `condition` (Query, 可选): 在线状态筛选 (1:在线, 2:离线, 3:在线不在组)。
|
|
* `page`, `limit` (Query, 可选)。
|
|
* **返回**: `Result<PttResult<List<PttModels.Member>>>`
|
|
|
|
---
|
|
|
|
## 3. 录音记录与处理 (核心功能)
|
|
|
|
### 十二、查询频道内成员ptt录音
|
|
* **接口**: `POST /group/{gid}/records`
|
|
* **描述**: 获取普通频道内指定成员在特定时间段的 PTT 录音记录。
|
|
* **参数**:
|
|
* `gid` (Path, 必填)。
|
|
* `uids` (Body, 可选): 筛选的成员 UID 列表。
|
|
* `start`, `end` (Query, 可选): 时间范围 (yyyy-MM-dd HH:mm:ss)。
|
|
* `page`, `limit` (Query, 可选)。
|
|
* **返回**: `Result<PttResult<List<PttModels.Record>>>`
|
|
|
|
### 十三、查询临时会话下的录音
|
|
* **接口**: `POST /temp-group/{tempgid}/records`
|
|
* **描述**: 获取临时会话下特定时间段的 PTT 录音记录。
|
|
* **参数**: 同上，针对临时群组 ID。
|
|
* **返回**: `Result<PttResult<List<PttModels.Record>>>`
|
|
|
|
### 获取录音转文字 (新增集成)
|
|
* **接口**: `GET /record/text`
|
|
* **描述**: 根据录音地址获取并转为文字。
|
|
* **特性**:
|
|
1. 内部自动处理音频下载与本地缓存。
|
|
2. 已转义过的记录将直接从数据库返回，避免重复调用 ASR。
|
|
* **参数**: `path` (Query, 必填): 录音文件远程相对路径。
|
|
* **返回**: `Result<String>` (识别后的文本内容)。
|
|
|
|
### 播放录音 (流式处理)
|
|
* **接口**: `GET /record/play`
|
|
* **描述**: 在线播放录音文件，首次播放会自动缓存到服务器本地。
|
|
* **特性**:
|
|
1. **流式输出**: 直接写入 Response 输出流，无内存占用压力。
|
|
2. **拖动支持**: 支持 HTTP Range 请求，可在浏览器进度条中任意拖动。
|
|
3. **优先播放**: 默认 `inline` 模式，谷歌浏览器直接调用内置播放器。
|
|
* **参数**: `path` (Query, 必填): 录音文件远程相对路径。
|
|
* **返回**: 二进制音频流 (`audio/wav`)。
|
|
|
|
---
|
|
|
|
## 4. 系统工具
|
|
|
|
### 手动执行平台登录
|
|
* **接口**: `POST /login`
|
|
* **描述**: 刷新 PTT 平台的会话 Token 并重新登录。用于故障恢复或手动同步。
|
|
* **返回**: `Result<String>`
|
|
|
|
### 二、退出登录
|
|
* **接口**: `POST /logout`
|
|
* **描述**: 注销当前 PTT 会话。
|
|
* **返回**: `Result<Boolean>`
|
|
|
|
---
|
|
|
|
## 响应规范
|
|
除 `playRecord` 这种流式接口外，所有接口均遵循统一响应体：
|
|
```json
|
|
{
|
|
"code": 200, // 状态码 (200: 成功)
|
|
"msg": "操作成功", // 提示信息
|
|
"data": { ... } // 业务载荷
|
|
}
|
|
```
|