用户管理
Admin 用户搜索筛选、角色权限、封禁、CRUD、自我保护与 correlated audit。
用户管理位于 Admin Worker，复用 Web Authentication 写入的 D1 用户、account 和 session 事实。Admin 自身要求 Authentication；Projects 和 Web Authentication 不因 Admin 以外的部署选择互相强制。
访问条件
Admin API 同时要求：
- 当前请求有有效的 Admin origin Session；
- 对应 D1 用户已经验证邮箱且未被封禁；
user.role的逗号分隔角色集合包含admin；- 用户管理操作通过 Better Auth Admin plugin 的对应 permission 检查。
ADMIN_EMAILS 只限制 bootstrap/recovery 可以选择的目标邮箱，不参与运行时授权。公开注册白名单邮箱不会自动获得管理员权限。/api/auth/me 直接返回持久化角色，不维护第二张 role 表。Web 与 Admin 使用不同 origin 和 Cookie prefix，Web Session 不能直接当作 Admin Session。
浏览器只调用同源 /api/admin/users。共享 Auth Core 对公开 /api/auth/admin/* 固定返回 404，Admin 服务端才可调用 Better Auth Admin handler，从而不能绕过自我保护和 correlated audit。
用户表
用户管理页提供：
- 按姓名或邮箱联合搜索；
- 按
admin | user角色和active | banned状态筛选； - 角色、状态、邮箱验证、Session、最近登录和创建时间列显隐；
10、20、30、40、50五档页大小及服务端分页；- 创建、编辑、删除、设置角色、封禁和解封操作。
用户列和操作列固定保留，其他列可从列菜单切换。页大小、角色和状态都在服务端按 allowlist 校验，不能通过手写 query 注入任意值。
角色与权限
模板产品层暴露 admin 和 user 两种角色。Better Auth 可把多个角色保存为逗号分隔字符串；授权、路由守卫、列表筛选和 DTO 都按角色集合解析，其中包含 admin 即视为管理员，管理页仍只投影为 admin | user。
默认权限来自 Better Auth Admin plugin：
| 操作 | 所需 permission |
|---|---|
| 用户列表 | user:list |
| 创建用户 | user:create 与设置默认角色所需权限 |
| 更新用户 | user:update |
| 删除用户 | user:delete |
| 设置角色 | user:set-role |
| 封禁/解封 | user:ban |
当前没有自定义权限矩阵 UI。若产品增加自定义角色，必须在 Better Auth 服务端配置同一 access control/roles 映射，并同步扩展 Admin DTO、表单 allowlist 和测试；客户端角色判断不能替代服务端 permission。
管理操作
| 方法 | 路径 | 作用 |
| -------------------------- | ------------------ | --------------------------------------- | ---------- |
| GET | /api/admin/users | 搜索、角色/状态筛选、分页与会话统计 |
| POST | /api/admin/users | 创建用户与 Better Auth credential |
| PATCH | /api/admin/users | 更新名称、邮箱和验证状态 |
| DELETE | /api/admin/users | 删除用户并级联 account/session |
| POST + action=set-role | /api/admin/users | 设置 admin | user 角色 |
| POST + action=ban | /api/admin/users | 保存原因/可选到期秒数并撤销全部 Session |
| POST + action=unban | /api/admin/users | 清除封禁、原因和到期时间 |
输入由服务端 Zod schema 规范化。封禁后目标用户的全部现有 Session 立即撤销，后续登录返回 BANNED_USER；解封后可重新登录。当前管理员不能删除、封禁或降权自己，也不能修改自己的邮箱或验证状态；UI 禁用只用于反馈，服务端仍是权威门禁。
Audit
每次已授权 create/update/delete/set-role/ban/unban 尝试都写六字段 correlated audit：actor ID、固定 action、受限 target ID、typed result、UUID correlation ID 和服务端时间。
Audit 禁止保存 request body、email、password、Cookie、token、Session、secret 或自由错误文本。写入是 best effort；失败会记录受限 observation，但不会重试已完成 mutation。
自定义字段
新增用户字段、角色或权限需要同时修改 Better Auth/Drizzle schema、迁移、服务端 access control、Admin DTO、校验、CRUD policy、列表/表单、audit target 规则和测试。不要只扩展客户端表格。
认证和 Session 细节见 Authentication，数据迁移见 Database。