用户与权限管理

先确认身份和操作对象

只有服务端认定的管理员可以访问 /admin/users 及对应管理 API。401 表示身份无效，403 表示不是管理员；不应通过修改页面状态或 access token 内容尝试获得权限。

用户列表 API GET /api/v1/admin/users 支持 query 或 q 搜索、page、pageSize；默认每页 20 条，最多 100 条。详情接口为 GET /api/v1/admin/users/{userId}。按明确的 userId 操作，不要只凭列表顺序或相似邮箱决定目标。

查看文件与额度

用户详情可辅助核对角色和空间。管理员查指定用户文件使用 GET /api/v1/admin/users/{userId}/files，仍需遵循 cursor 分页；查看记录不代表取得了所有者专用的分享和发布权限。

配额调整使用 PATCH /api/v1/admin/users/{userId}/quota，传字符串 limitBytes。服务端拒绝低于当前已记账与预留之和的上限。调整前读当前值，调整后重新读取确认；不要把空缺、请求失败或 null 当成零。具体含义见配额。

角色变更

PATCH /api/v1/admin/users/{userId}/role 接受 {"role":"user"} 或 {"role":"admin"}。这是权限变更，确认目标和目的后再执行。变更后重新读取用户详情，必要时让目标用户重新进入管理页面。

CORE_ADMIN_EMAILS 在首次创建用户时决定是否初始化为 admin，不是每次登录都会重写现有账户的角色。不要仅修改环境中的邮箱列表就假定已有用户角色已经改变。

当前不应承诺的操作

活跃的用户路由没有通用删除用户、封禁/解封状态切换、密码重置或全设备退出的管理 API。数据表拥有 status 字段，不等于公开接口提供其全部生命周期。旧归档管理文档或演示组件也不能作为当前可用操作的依据。

服务器权限变更不等于删除浏览器已取得的信息；管理员应避免把用户邮箱、文件记录、Cookie 或授权值放入截图和公共报告。报告问题时使用操作类型、脱敏状态码、时间和经过处理的关联标识。

验证管理操作

先在可丢弃测试实例、专门测试账户上验证查询、翻页和额度冲突。角色变更会影响后续权限检查，避免在唯一管理账户上进行试验。管理指标和通知分别阅读仪表盘与通知。