# 用户分组接口与权限说明

适用项目：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 提供迁移文件，但本次专项测试不代表这两种数据库已完成真实环境升级验收。