next-rbac-admin-demo

English

一个面向 Next.js 学习者和后台原型开发者的前端 RBAC 参考实现：用合成数据演示“用户 → 角色 → 模块权限 → 动态菜单与路由守卫”的完整交互链路。

[!IMPORTANT] 这是参考 Demo，不是生产鉴权系统。登录、角色判断和业务数据全部运行在浏览器端；项目不包含服务端身份认证、数据库、加密会话、审计日志或真正的安全隔离。任何人都能在浏览器开发者工具中修改客户端状态，请勿直接用于真实业务。

管理员视角	普通员工视角

为什么有这个项目

很多 RBAC 教程只展示一张权限表，或者只隐藏几个按钮。本项目把权限模型放进一个可操作的管理后台中，让你可以切换三种演示角色，观察同一份模块授权数据如何同时影响：

• 登录后的角色上下文；
• 侧边栏的父子菜单；
• 直接输入受限 URL 时的拒绝页面；
• 用户、人力资源、进销存和个人中心等 Mock 业务模块。

它适合作为课程设计参考、前端权限建模实验或接入真实后端前的交互原型。

能力与边界

已实现

• 用户、角色、模块、角色授权四类合成数据；
• 管理员、部门经理、普通员工三种权限集合；
• 基于授权表构建的动态树形导航；
• 未登录跳转和无权限路由提示；
• 内存中的用户、人事、库存、订单和待办交互；
• 权限纯函数、登录状态和守卫判定的 Node.js 测试；
• Chromium 端到端角色切换和直达路由冒烟测试。

明确不包含

• 服务端认证与授权、密码哈希、Token 或 Cookie 会话；
• 数据库、API、多人协作或刷新后的业务数据持久化；
• 防止客户端篡改的安全边界；
• 可直接投入生产的用户、角色和权限管理能力。

如果要用于真实系统，应由服务端在每次数据访问时重新验证会话与权限，前端守卫只能改善用户体验，不能代替安全控制。

快速开始

环境要求

• Node.js 22 LTS（最低支持 22.0.0）；
• npm 10 或更高版本；
• 现代 Chromium、Firefox 或 Safari 浏览器。

安装和启动

git clone <your-repository-url>
cd next-rbac-admin-demo
npm ci
npm run dev

打开 http://127.0.0.1:3000。Windows 用户也可以双击相对路径运行的 start-dev.bat，但跨平台文档始终以 npm 命令为准。

演示账号

所有账号只存在于 src/lib/mock-data.ts，统一演示密码为 123456。

用户名	角色	主要可见区域
admin	超级管理员	全部模块
manager	部门经理	人力资源、进销存、个人中心
staff	普通员工	采购、销售、个人资料、待办

建议先用 staff 登录并直接访问 /admin/system/users，确认出现“无权访问”；再切换 admin 验证用户管理页面可见。

权限模型

flowchart LR
  U["合成用户"] --> R["角色"]
  R --> P["角色授权表"]
  P --> M["模块集合"]
  M --> N["动态菜单"]
  M --> G["客户端路由守卫"]

能力域	管理员	部门经理	普通员工
控制台	✓	✓	✓
系统管理	✓	—	—
人力资源	✓	✓	—
采购 / 销售	✓	✓	✓
库存盘点	✓	✓	—
个人中心	✓	✓	✓

权限判断的纯逻辑位于 src/lib/rbac.ts。浏览器只在 localStorage 中保存合成用户 ID，恢复时会从内存数据重新读取角色，不保存密码或信任持久化的角色字段。业务数据变更只保存在 React 内存中，刷新页面即重置。

项目结构

src/
├─ app/                         # Next.js App Router 页面
│  ├─ login/                    # 演示角色选择与登录
│  └─ admin/                    # 受客户端守卫保护的后台模块
├─ components/admin/            # PermissionGuard
├─ components/ui/               # 通用展示组件
└─ lib/
   ├─ mock-data.ts              # 明确标注的合成数据
   ├─ demo-auth.ts              # 演示登录与本地状态恢复
   ├─ rbac.ts                   # 权限查询和菜单树纯函数
   ├─ auth-context.tsx          # 浏览器端演示会话
   └─ data-store.tsx            # 内存业务数据
tests/e2e/                      # Playwright 角色与路由冒烟测试
docs/                           # 架构、演示数据与发布审计

更详细的设计见 docs/architecture.md。

质量检查

npm run format:check   # 格式
npm run lint           # ESLint
npm run typecheck      # TypeScript
npm test               # Node.js 单元与 AuthProvider 行为测试
npm run test:coverage  # 核心逻辑覆盖率
npm run build          # 生产构建
npx playwright install chromium
npm run test:e2e       # 浏览器端冒烟测试
npm run capture:screenshots # 重新生成 README 的真实界面截图

npm run check 会依次执行格式、Lint、类型、单元测试和构建。CI 还会在独立任务中运行 Chromium E2E；测试不访问外部 API，也不需要秘密配置。

配置和安全

当前版本没有必需环境变量，也不需要 API Key。仓库会忽略所有 .env*（仅允许未来的 .env.example）。如你扩展真实后端：

1. 不要把密钥或真实用户数据提交到仓库；
2. 将认证、授权和数据校验放在可信服务端；
3. 不要把客户端 localStorage 角色视为授权依据；
4. 按 SECURITY.md 私下报告安全问题。

合成数据的来源与使用范围见 docs/demo-data.md。

Roadmap

• 增加可替换的数据访问接口示例；
• 展示服务端授权与前端菜单投影的边界；
• 补充无障碍和移动端交互回归测试；
• 在确定公开仓库地址后启用正式 CI/安全徽章。

Roadmap 不代表发布时间承诺。欢迎先通过 Issue 讨论设计，再提交小而可验证的修改。

参与贡献

请阅读 CONTRIBUTING.md 和 CODE_OF_CONDUCT.md。Bug、文档改进和适合初学者的测试补充都受欢迎。安全问题请不要公开提交 Issue。

项目来源与许可证

本项目由课程型 RBAC 作业整理而来，公开版本重新定义为教学和原型参考实现。课程报告、旧固定盘符脚本和来源待确认的二进制材料不属于公开仓库内容。

代码计划按 MIT License 发布；仓库所有者仍须在首次公开前完成 docs/release-audit.md 中的源码与素材权利确认。