nuxt-app/docs/superpowers/specs/2026-05-25-admin-users-management-design.md

Admin Users Management — Design Spec

概述

后台管理系统的用户管理模块，提供管理员增删改查用户的能力。

路由与布局

• 布局：app/layouts/admin.vue — 左侧边栏 + 右侧 <NuxtPage /> 内容区
• 边栏菜单：用户管理、Scheduled Tasks
• 访问控制：所有 /admin/* 路由需要 admin 角色（requireAdmin）
• 边栏宽度：240px 固定，内容区 flex-1

页面：用户列表 /admin/users

路由

• app/pages/admin/users/index.vue

顶部操作栏

• 搜索框（按 username / email 过滤，客户端筛选）
• 新建用户按钮（coral CTA）

表格列

列	来源
ID	users.id
Username	users.username
Email	users.email
Role	users.role（badge 显示：user=蓝/ admin=珊瑚色）
Status	users.status（badge 显示：active=绿 / inactive=灰）
Created	users.createdAt（格式化日期）

行操作

• 编辑（打开编辑弹窗）
• 删除（确认对话框后执行）

分页

• 每页 20 条，支持 prev/next

弹窗：新建用户

字段

字段	类型	校验
Username	text	必填，唯一
Email	text	必填，Email 格式
Role	select	user / admin，默认 user
Status	select	active / inactive，默认 active

提交

• POST /api/admin/users
• 成功后关闭弹窗，刷新列表

弹窗：编辑用户

字段（均只读展示）

字段	行为
Username	只读文本
Email	只读文本
Role	select — user / admin
Status	select — active / inactive

提交

• PATCH /api/admin/users/:id
• 成功后关闭弹窗，刷新列表

API 设计

GET /api/admin/users

• 调用 requireAdmin
• 返回用户列表（排除 password 字段）
• Query: page, limit

POST /api/admin/users

• 调用 requireAdmin
• Body: { username, email, role, status }
• 创建用户（初始 password 可随机生成或留空由管理员重置）

PATCH /api/admin/users/:id

• 调用 requireAdmin
• Body: { role, status }

DELETE /api/admin/users/:id

• 调用 requireAdmin
• 删除用户（级联删除 sessions）

视觉风格

遵循 DESIGN.md：

• 页面底色：#faf9f5（canvas）
• 按钮：coral #cc785c
• 表格：白色底 + hairline 边框
• Badge：role 和 status 用小药丸标签

依赖

• 复用 server/utils/admin-guard.ts 的 requireAdmin
• 用户 schema 已有（packages/drizzle-pkg/lib/schema/auth.ts）