群属性与角色管理方法
group.update
owner 修改群名称、简介、成员容量或邀请策略。
| 项目 | 约定 |
|---|---|
| HTTP | PATCH /meshline/v1/group/update |
| 会话要求 | 设备会话 |
| WSS | group.update |
| HTTP 成功状态 | 204 No Content |
请求参数
| 字段 | 类型 | 必需 | 语义与约束 |
|---|---|---|---|
$type |
string | 是 | 固定为 meshline.group.update |
group_id |
string | 是 | 要修改群属性的群 ID；群必须仍处于 active 状态 |
prev_hash |
string | 是 | 上一项管理链摘要；提交时必须仍是当前链头 |
name |
string | 否 | 出现时替换当前群名称；必须至少包含一个非空白字符，UTF-8 编码后最多 256 bytes；省略表示名称保持不变 |
description |
string | 否 | 出现时替换当前简介；非空时不得仅包含空白字符且最多 4,096 UTF-8 bytes；省略表示简介保持不变 |
member_capacity |
integer | 否 | 出现时替换当前容量，必须为正；增加容量时不得超过中继当前 max_group_members，保持或降低既有容量不受后来调低的上限限制；省略表示容量保持不变 |
invite_policy |
string | 否 | 出现时替换成员邀请策略，取值与含义见 GroupState.invite_policy；省略表示策略保持不变 |
device_signature |
string | 是 | 由当前 owner 使用本次调用设备签署，签名输入是排除本字段后的完整更新对象 |
必须至少提供一个可修改字段。新容量可以低于当前成员数；批准入群后的成员总数不得超过该容量。
本方法只修改 name、description、member_capacity 和 invite_policy。更新对象的未知属性仍参与签名，并在事件中原样保留，但不合并到 GroupState，也不改变成员或事件外层字段；未知属性不能代替可修改字段满足必填条件。
响应对象
无。
处理与错误
固定值、名称、简介、容量或邀请策略不合法时返回 bad_request；群不存在时返回 not_found；调用账户不是当前 owner 或已被封禁时返回 forbidden；并发状态冲突时返回 state_conflict。
校验通过后，中继以本次提供的字段更新群属性；完整更新对象作为新事件的 payload 追加到时间线，并更新管理链头。相关状态成功持久化后发送 group.timeline.changed。密钥版本不变。
group.role.update
owner 设置一名当前非 owner 成员的角色。
| 项目 | 约定 |
|---|---|
| HTTP | PUT /meshline/v1/group/role/update |
| 会话要求 | 设备会话 |
| WSS | group.role.update |
| HTTP 成功状态 | 204 No Content |
请求参数
| 字段 | 类型 | 必需 | 语义与约束 |
|---|---|---|---|
$type |
string | 是 | 固定为 meshline.group.role.update |
group_id |
string | 是 | 目标成员所在的群 ID |
prev_hash |
string | 是 | 上一项管理链摘要；提交时必须仍是当前链头 |
account |
string | 是 | 要设置角色的当前非 owner 成员账户 |
role |
string | 是 | 目标成员更新后的角色，只能是 administrator 或 member |
device_signature |
string | 是 | 由当前 owner 使用本次调用设备签署，签名输入是排除本字段后的完整角色更新对象 |
响应对象
无。
处理与错误
角色值或固定字段非法时返回 bad_request；群不存在时返回 not_found；调用账户不是当前 owner 或已被封禁时返回 forbidden；目标不是当前非 owner 成员或发生并发成员变化时返回 state_conflict。
校验通过后，中继以请求指定的角色更新目标成员记录，将完整签名的角色更新对象作为新事件的 payload 追加到时间线，并更新管理链头。相关状态成功持久化后发送 group.timeline.changed。成员资格、公钥、访问区间和密钥版本不变。
group.owner.transfer
当前 owner 把群组所有权转让给另一名未被封禁的当前成员。
| 项目 | 约定 |
|---|---|
| HTTP | POST /meshline/v1/group/owner/transfer |
| 会话要求 | 设备会话 |
| WSS | group.owner.transfer |
| HTTP 成功状态 | 204 No Content |
请求参数
| 字段 | 类型 | 必需 | 语义与约束 |
|---|---|---|---|
$type |
string | 是 | 固定为 meshline.group.owner.transfer |
group_id |
string | 是 | 要转让所有权的群 ID |
prev_hash |
string | 是 | 上一项管理链摘要；提交时必须仍是当前链头 |
new_owner_account |
string | 是 | 当前 owner 指定的接任账户，必须是该群另一名未被封禁的当前成员 |
device_signature |
string | 是 | 当前 owner 使用本次调用设备对排除本字段后的完整请求所作网络绑定签名 |
响应对象
无。
处理与错误
固定字段、prev_hash 或账户格式非法时返回 bad_request；群不存在时返回 not_found；调用账户不是当前 owner、目标不是另一当前成员、目标已被封禁，或者调用方已被封禁时返回 forbidden；通过权限校验但 prev_hash 已不是当前管理链头，或者发生并发成员状态冲突时返回 state_conflict。
操作成功时把目标成员改为 owner、原 owner 改为普通 member、更新 owner，追加完整签名转让事件并更新管理链头，同时删除原 owner 的暂存轮换。该操作不改变成员集合、访问区间或密钥版本。