04. 群组与互联¶
1. 群组查询与基础操作（JWT + Approved）¶
GET /api/groups¶
参数：page、page_size、keyword
返回示例：
{
"code": 200,
"message": "成功",
"data": {
"items": [
{
"id": 1001,
"name": "深圳应急群",
"type": 1,
"is_joined": true,
"is_owner": false,
"online_count": 12,
"total_count": 53
}
],
"total": 1,
"page": 1,
"page_size": 20
}
}
GET /api/group/list（兼容）¶
GET /api/groups/:id¶
GET /api/groups/:id/devices¶
返回设备列表含 disable_send/disable_recv（仅设备级状态）。
POST /api/groups¶
POST /api/group/create（兼容）¶
群组自身的旧 callsign 字段和设备准入白名单已经停用；请求中的旧字段会被忽略，响应也不再返回。
请求：
{
"name": "深圳私有群",
"type": 2,
"password": "123456",
"note": "内部使用"
}
POST /api/groups/search¶
请求：
{ "keyword": "深圳", "page": 1, "page_size": 20 }
POST /api/groups/:id/join¶
请求：
{ "password": "123456" }
GET /api/groups/:id/members¶
说明：管理员或群主可查看。
返回的成员摘要包含用户名、昵称、呼号、加入时间和当前仍在本群组的普通设备数， 不返回邮箱、电话等用户私密字段。
{
"code": 200,
"message": "成功",
"data": {
"items": [
{
"id": 7,
"group_id": 1001,
"user_id": 42,
"username": "radio-user",
"nickname": "值守一组",
"callsign": "BG7ABC",
"is_verified": true,
"join_time": "2026-08-06T10:00:00Z",
"last_verify": "2026-08-06T10:00:00Z",
"device_count": 2
}
],
"total": 1
}
}
POST /api/groups/:id/leave¶
说明：仅私有群支持退出，群主不能退出自己创建的群。
2. 群组管理（Admin/GroupOwner）¶
说明：群组不提供设备准入名单或永久封禁；群主可以临时调整当前组内普通设备的设备级收发状态。
PUT /api/groups/:id¶
请求：
{
"name": "深圳私有群-新",
"type": 2,
"password": "654321",
"status": 1,
"note": "更新备注"
}
DELETE /api/groups/:id¶
DELETE /api/groups/:id/members/:userId¶
功能：管理员或群主从私有群组中移除一名成员。目标用户必须是当前成员， 且不能是群主本人；公开群组和虚拟互联组不支持该操作。
成功后，服务端在同一事务中删除成员关系、将该用户仍在本群组的所有普通
设备迁移到默认群组 999，并清除设备默认值和幽灵客户端中对本群组的发送、
接收偏好。在线普通设备、在线幽灵 Session 和边缘路由会在提交后立即同步；
该用户随后的实时收发和频道消息历史查询也会立即失去本群组权限。
返回示例：
{
"code": 200,
"message": "移除成功",
"data": {
"group_id": 1001,
"user_id": 42,
"moved_device_count": 2
}
}
DELETE /api/groups/:id/devices/:deviceId¶
功能：踢出设备并移入默认群组。
PUT /api/groups/:id/devices/:deviceId/comm-control¶
权限：管理员或当前群主。设备必须仍然属于路径指定的群组。
{
"disable_send": true,
"disable_recv": false
}
两个状态均为设备级全局状态，设备切换群组后仍然生效。接口只修改明确提交的字段； 设备所有者仍可在自己的设备管理接口中恢复状态。
设备所有者或管理员也可使用设备接口：
PUT /api/devices/:id¶
请求体可包含：
{ "disable_send": true, "disable_recv": false }
3. 兼容旧接口说明¶
POST /api/group/updatePOST /api/group/delete
旧更新路径从 JSON 请求体读取 id，旧删除路径从 JSON 请求体或查询参数读取 id。
两者继续执行“管理员或群主”对象级权限校验；新客户端仍建议使用
PUT/DELETE /api/groups/:id。
4. 虚拟互联组（Admin）¶
POST /api/group-links¶
创建请求可同时保存自动播报策略：
{
"name": "华南互联组",
"note": "跨群互联",
"status": 1,
"target_group_ids": [1001, 1002],
"broadcast_policy": {
"mode": "allow_single_source",
"allowed_source_group_id": 1001
}
}
broadcast_policy.mode 可以是：
suspend_all：虚拟组开启期间，全部成员实体组的自动播报暂停。allow_single_source：仅allowed_source_group_id指定的一个成员实体组可播报。
策略始终持久化，但只在虚拟组实际 status=1 时生效。关闭虚拟组会恢复未来
计划，不补发互联期间错过的轮次；普通状态开关只应用已保存策略，不额外要求确认。
GET /api/group-links¶
GET /api/group-links/:id¶
PUT /api/group-links/:id¶
DELETE /api/group-links/:id¶
GET /api/group-links/available-targets¶
功能：获取可被关联的目标群组。只返回已启用的公开或私有实体群组， 并排除虚拟群组及已被任一互联组占用的实体群组。
GET /api/group-links/:id/targets¶
POST /api/group-links/:id/targets¶
请求：
{ "target_group_id": 1001 }
目标群组必须处于启用状态，且为公开或私有的非虚拟实体群组。接口会在 写入前重新校验，不能通过直接提交候选列表之外的 ID 绕过限制。
返回：
{ "code": 200, "message": "添加成功", "data": { "link_group_id": 2001, "target_group_id": 1001, "target_count": 3 } }
DELETE /api/group-links/:id/targets/:targetId¶
若目标正是 allow_single_source 的保留来源，请在删除请求体中提交移除后策略，成员
关系与策略会在同一事务内保存：
{ "broadcast_policy": { "mode": "allow_single_source", "allowed_source_group_id": 1002 } }
也可以提交 { "broadcast_policy": { "mode": "suspend_all" } }。未提交策略时保持向后
兼容；如果被移除目标恰好是当前保留来源，则返回
409 virtual_broadcast_source_must_change。新来源必须属于移除后的成员集合，校验失败时
成员关系和原策略均不改变。
PUT /api/group-links/:id/broadcast-policy¶
权限：管理员。请求体与创建时的 broadcast_policy 相同：
{ "mode": "suspend_all" }
或：
{ "mode": "allow_single_source", "allowed_source_group_id": 1001 }
切换策略、增删成员或开关虚拟组时，服务端会取消受影响域内正在播放的自动播报并
等待其释放话权，再完成拓扑切换。虚拟组详情和列表返回 broadcast_policy；详情还
返回每个成员的 broadcast_members（启用计划数及当前允许/挂起状态）。