基于 Next.js 14 与 React 18 的中后台管理前端模板，内置角色与权限体系、统一列表布局与 UI 组件，可直接作为二次开发的基础或学习 RBAC 实现参考。
- Next.js 14 (App Router) + TypeScript + Tailwind CSS
- 角色与权限：内置角色、树形权限配置、菜单与按钮级控制（见下方「角色与权限」）
- 统一列表规范：查询区 + 操作栏 + 表格（列配置）+ 分页，一屏铺满、表格内滚动
- UI：Radix UI + 少量 shadcn 风格组件
- 鉴权：本地 Token/用户信息（可替换为服务端 Session/JWT）
- 模拟数据：业务接口尚未对接时可用 mock 数据跑通流程
| 类别 | 技术 |
|---|---|
| 框架 | Next.js 14 (App Router) |
| 语言 | TypeScript |
| 样式 | Tailwind CSS |
| 组件 | Radix UI、lucide-react |
| 图表 | recharts（仪表盘） |
ADMIN/
├── app/
│ ├── (dashboard)/ # 需登录的布局
│ │ ├── layout.tsx # 侧栏 + 顶栏 + 权限/水印等 Provider
│ │ ├── page.tsx # 首页 / 仪表盘
│ │ ├── customers/ # 客户管理
│ │ ├── projects/ # 项目管理
│ │ ├── admins/ # 管理员管理
│ │ ├── roles/ # 角色管理
│ │ ├── permissions/ # 权限树配置
│ │ ├── logs/ # 系统日志、操作日志
│ │ └── system/ # 系统设置
│ ├── login/
│ └── layout.tsx
├── components/
│ ├── auth/ # <Can action="..."> 按钮级权限
│ ├── layout/ # 侧栏、顶栏、水印等
│ └── ui/ # 通用 UI 组件
├── lib/
│ ├── permission.ts # 菜单/操作权限校验、默认配置
│ ├── permission-tree.ts # 权限树结构（规范 key）
│ ├── permission-tree-context.tsx
│ ├── role-config-context.tsx # 角色-权限配置（持久化）
│ ├── roles-list-context.tsx # 角色列表（可扩展自定义角色）
│ ├── use-permission.tsx # 当前用户 can(action)
│ ├── auth.ts # Token / 当前用户读写
│ └── api/ # 类型与 mock
└── README.md
cd ADMIN
npm install
npm run dev浏览器访问 http://localhost:3000。默认无真实登录接口，可在登录页任意输入后进入（见 app/login/page.tsx），当前用户角色可通过本地存储或后续对接接口修改。
本模板的权限体系分为：角色、权限树、菜单可见性、操作按钮可见性。扩展或对接后端时，建议先通读本节与 lib/permission*.ts、lib/role-config-context.tsx。
| 角色 code | 说明 | 典型用途 |
|---|---|---|
super |
超级管理员 | 全部菜单与操作 |
admin |
管理员 | 系统设置、权限/角色；不含「管理员管理」 |
operator |
操作员 | 客户、项目、日志等业务；不含删除/系统配置 |
角色列表与增删改在 角色管理 页面维护（lib/roles-list-context.tsx，默认持久化在 localStorage）。内置 super / admin / operator 不可删除，可新增自定义角色（如 sales、finance）。
所有「可配置的权限」用一棵树表示，定义在 lib/permission-tree.ts：
- 层级：一级 = 模块/菜单（如
customers、system），二级 = 子菜单或功能（如system:admins），叶子 = 操作（如customers:opt-create）。 - 命名：用英文、
:分隔，例如system:admins:opt-create。建议：- 模块/菜单：
home、customers、projects、system、logs - 操作：
opt-list、opt-create、opt-edit、opt-delete、opt-view
- 模块/菜单：
示例：
home
customers
customers:opt-list, customers:opt-create, customers:opt-edit, customers:opt-delete
projects
projects:opt-list, projects:opt-create, ...
system
system:settings, system:permissions, system:roles
system:admins
system:admins:opt-list, system:admins:opt-create, ...
logs
logs:system, logs:operation
logs:system:opt-view, logs:operation:opt-view
在 权限管理 页面可增删改树节点（label/key）；角色管理 中为每个角色勾选拥有的权限，配置会覆盖默认值并持久化（当前为 localStorage）。
- 侧栏菜单项与
MenuKey对应，映射关系在lib/permission.ts的PATH_MENU_KEYS、getMenuKeyByPath。 - 是否展示某菜单：
canAccessMenu(role, menuKey, customMenu?, flatConfig?)。若使用树形配置，则通过flatConfig（即角色-权限配置）与permission-tree中 key 的映射得到「该菜单是否对当前角色开放」。 - 侧栏在
components/layout/sidebar.tsx中根据canAccessMenu过滤navConfig。
- 操作与
ActionKey对应（如customer:create、admin:manage），在lib/permission.ts中定义。 ActionKey与权限树 key 的映射见ACTION_KEY_TO_PERMISSION，用于在「使用树形配置」时判断是否允许。- 页面内使用方式：用
<Can action="customer:create">...</Can>包裹按钮或区域，内部调用canDo(role, actionKey, ...)，无权限则不渲染子节点。
import { Can } from "@/components/auth/can";
<Can action="customer:create">
<Button onClick={openCreate}>新增客户</Button>
</Can>- 菜单默认：
lib/permission.ts中DEFAULT_MENU_ROLES、DEFAULT_ACTION_ROLES为「未使用树形覆盖」时的默认值。 - 树形默认：
DEFAULT_PERMISSION_ROLES为每个权限 key 的默认允许角色；系统相关（如system、system:admins）多为["super"]或["super","admin"]，业务模块多为"all"。 - 角色管理里保存的配置会覆盖上述默认，形成当前生效的
flatConfig。
- 新增菜单/页面：在
permission-tree.ts的树中增加节点（及子操作），在permission.ts中补充MenuKey、PATH_MENU_KEYS、必要时ActionKey与ACTION_KEY_TO_PERMISSION，侧栏navConfig增加一项并指定menuKey。 - 新增操作：在权限树中加叶子（如
xxx:opt-export），在ActionKey与ACTION_KEY_TO_PERMISSION中增加对应项，页面中用<Can action="xxx:export">控制。 - 对接后端：将当前「从 localStorage 读角色列表、读权限配置」改为从接口获取；
canAccessMenu/canDo的调用方式可保持不变，仅数据源改为服务端下发的角色与权限列表。
- 登录与用户信息：
lib/auth.ts负责 Token、当前用户读写；登录页app/login/page.tsx可改为调用真实登录接口并写入setToken/setAdmin（含role）。 - 列表页规范：客户/项目/管理员/日志等列表均采用「查询区 + 操作栏 + 表格 + 分页」布局，表格列通过列配置数组渲染，见
app/(dashboard)/customers/page.tsx的CUSTOMER_COLUMNS。 - 主题与样式：Tailwind +
app/globals.css，可按需改主题色或接入设计系统。
- 当前无后端时，客户/项目/管理员/角色/权限等数据均为前端 mock 或 localStorage，便于直接跑通与演示。
- 生产环境请对接真实登录、用户信息与权限接口，并视需求将角色与权限配置改为服务端存储。
