Scert/doc/user-groups.md

用户分组接口与权限说明

适用项目：Scert。更新日期：2026-09-25。

页面入口

• 系统设置位于侧栏的系统管理区域，打开已有设置面板。
• 修改密码位于用户管理页面，修改当前登录账号的密码。
• 默认分组置顶并始终展开；命名分组初始折叠。
• 普通用户进入用户中心，只显示本人资料及修改密码，不显示分组。

可见范围

角色	用户读取范围	分组关系	用户新增、编辑、删除
超级管理员	全部用户和分组	主账号保持受保护	允许，主账号保护规则不变
管理员	自己及所属组成员的并集	可加入多个命名分组	不允许
普通用户	仅自己	最多一个命名分组	不允许

没有命名分组的账号属于默认分组。未分组管理员可见默认组成员，但不可见其他超级管理员。管理员读取多组成员时，只返回双方共同的分组，不泄露对方的其他组名。这里限定的是用户列表可见范围，不代表域名、证书、服务器资源已经实现分组隔离。

接口

沿用现有会话认证与同源校验。

方法	路径	说明
GET	/api/v1/users	按角色过滤的用户列表
GET	/api/v1/users/:id	查询可见用户；越权与不存在均返回 404
POST	/api/v1/users	超级管理员创建用户
PUT	/api/v1/users/:id	超级管理员更新用户
DELETE	/api/v1/users/:id	超级管理员删除用户

列表响应增加 current_role、current_user_id。用户对象的 groups 为字符串数组；默认组和普通用户读取时省略该字段。密码摘要不返回。

新增和更新请求支持 groups：省略或传 null 时，新增使用默认组，更新保留原关系；传 [] 清空命名分组、回到默认组。组名去首尾空白、去重并排序，区分大小写，长度为 1 到 32 个字符，不允许控制字符或保留名称“默认分组”。最多 32 个组，普通用户最多 1 个组。多组管理员降级为普通用户时，必须明确保留不超过一个组，否则返回 400，不会静默丢失分组。

分组名称由保存用户时创建；没有独立空组、组重命名或组删除接口。删除最后一个组内成员后，该组不再显示。

数据升级与验证边界

迁移版本 8 为用户表增加可空的 groups_json 文本字段。旧记录的空值解释为默认分组，保留原账号、角色和密码摘要。每次读取用户列表时重新读取当前账号分组，调组不依赖重新登录。

SQLite 的旧版本升级与重复迁移由专项测试覆盖；MySQL 和 PostgreSQL 提供迁移文件，但本次专项测试不代表这两种数据库已完成真实环境升级验收。