0024 兼容 Blessing Skin 的管理类资源 API
- 状态:已接受(2026-10-30)
- 相关:设计文档 02 §2.6;03(A01、C07、C15、§7.4);ADR 0016、0020、0023
背景
M3 第三部分。ADR 0023 做了 OAuth 2.0 与用户级的兼容接口,BS 的 /api/admin/* 留到这里:管理员的脚本和面板用它管理用户、角色、衣柜、举报和发通知。BS 的问题:
- 管理端、用户端、OAuth API 三处各写一份逻辑,行为不一致(A01):OAuth API 给角色换材质时不检查类型、不要求在衣柜里(C07),发通知返回 302 跳转到
/admin(C15)。 - 列表的
q用 search-string 语法,分页没有总量控制。
决策
- 接口与 scope(
internal/httpapi/bsadmin.go):- 用户
GET /api/admin/users、PUT /api/admin/users/{uid}/email|verification|nickname|password|score|permission、DELETE /api/admin/users/{uid}(UsersManagement.*); - 角色
GET /api/admin/players、PUT /api/admin/players/{pid}/name|owner|textures、DELETE /api/admin/players/{pid}(PlayersManagement.*); - 衣柜
GET|POST|DELETE /api/admin/closet/{uid}(ClosetManagement.*,tid在请求体里); - 举报
GET /api/admin/reports、PUT /api/admin/reports/{id}(ReportsManagement.*); - 通知
POST /api/admin/notifications(Notification.ReadWrite)。 - 管理类 scope 只有管理员能授予;令牌主人不再是管理员时,令牌对这些接口立即失效(ADR 0023)。
- 用户
- 同一套规则与服务:
- 权限规则与后台页面相同:管理员只能管理普通用户,超级管理员管理所有人,谁都不能改自己的权限(
account.AdminUpdateUser、MayManageOwned)。 - 处理举报、发通知、改名与转移角色原来写在
/api/v1的处理函数里,抽成reviewReport、sendNotification、updatePlayerAsAdmin、managedPlayer、adminAudit,两套接口都调用它们,写同样的审计记录(修 A01)。 - 换材质:材质必须在主人的衣柜里、类型要对(修 C07);
tid为 0 表示脱下。 - 发通知返回
{"code": 0}(修 C15)。receiver的all、normal写一条公告,uid、email发给一个人(ADR 0021)。
- 权限规则与后台页面相同:管理员只能管理普通用户,超级管理员管理所有人,谁都不能改自己的权限(
- BS 的格式:
- 列表是 Laravel 分页(用户和角色每页 10 条,举报 9 条),按
page翻页;用户对象多一个ip(注册地址);举报带texture、texture_uploader、informer,status是 0 / 1 / 2。 permission:-1 封禁,0 普通用户,1 管理员;2(超级管理员)不能通过接口设置(同 BS)。verification切换邮箱验证状态(同 BS);score设为给定值,差额记入积分流水。- 没有权限是 403
{"code": 1, "message"};处理举报时没有权限封禁上传者、举报已处理、上传者已不存在,与 BS 一样是 HTTP 200、code为 1。 - 一个用户的衣柜一次返回全部(同 BS),最多 1000 条。
- 列表是 Laravel 分页(用户和角色每页 10 条,举报 9 条),按
q搜索:只认第一个字段:值,其余当作普通文字:- 用户:值(或整个
q)匹配邮箱、昵称或 ID; - 角色:
uid:N是这个用户的角色,其它值匹配角色 ID、UUID 或名字开头; - 举报:
status:0|1|2、reporter:N、uploader:N、tid:N。 - BS 完整的 search-string 语法(排序、比较、多个条件)不支持。
- 用户:值(或整个
- 分页:
account.ListUsers、player.Search、report.List的过滤条件增加Offset,并新增CountUsers、player.Count、report.Count(同一个条件构造函数),report.Filter增加UploaderID、TextureID。后台页面仍用游标翻页。
备选方案
- 在兼容层里直接查数据库:最快,但会把 BS 的问题(三处各写一份)原样搬过来。
- 实现完整的 search-string 语法:使用的人很少,规则多,容易出错;常见的
uid:N、status:0和普通文字已覆盖。
影响
- 没有新表和迁移,也没有新设置。
internal/httpapi:新文件bsadmin.go;reports.go、notifications.go、admin_players.go的处理函数改为调用抽出的共用函数,/api/v1的行为不变。- 至此 BS 的 OAuth 资源 API(02 §2.6)全部可用;M3 还剩社交登录。