# 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": { ... }   // 业务载荷
}
```