# Nextjs Admin Base 后台管理系统基础模板

**Repository Path**: Z568_568/AdminBase

## Basic Information

- **Project Name**: Nextjs Admin Base 后台管理系统基础模板
- **Description**: 基于 Next.js 14 与 React 18 的中后台管理前端模板，内置角色与权限体系、统一列表布局与 UI 组件，可直接作为二次开发的基础或学习 RBAC 实现参考
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-10
- **Last Updated**: 2026-03-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: React, tailwindcss, TypeScript, nextjs, ShadcnUI

## README

# Admin Base — 后台管理系统基础模板

基于 **Next.js 14** 与 **React 18** 的中后台管理前端模板，内置**角色与权限体系**、统一列表布局与 UI 组件，可直接作为二次开发的基础或学习 RBAC 实现参考。

<img src="./IMG/2.png" alt="Admin Base" >

## 特性

- **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
```

## 快速开始

```bash
cd ADMIN
npm install
npm run dev
```

浏览器访问 `http://localhost:3000`。默认无真实登录接口，可在登录页任意输入后进入（见 `app/login/page.tsx`），当前用户角色可通过本地存储或后续对接接口修改。

## 角色与权限（重要）

本模板的权限体系分为：**角色**、**权限树**、**菜单可见性**、**操作按钮可见性**。扩展或对接后端时，建议先通读本节与 `lib/permission*.ts`、`lib/role-config-context.tsx`。

### 1. 内置角色

| 角色 code | 说明     | 典型用途           |
|-----------|----------|--------------------|
| `super`   | 超级管理员 | 全部菜单与操作     |
| `admin`   | 管理员   | 系统设置、权限/角色；不含「管理员管理」 |
| `operator`| 操作员   | 客户、项目、日志等业务；不含删除/系统配置 |

角色列表与增删改在 **角色管理** 页面维护（`lib/roles-list-context.tsx`，默认持久化在 localStorage）。内置 `super` / `admin` / `operator` 不可删除，可新增自定义角色（如 `sales`、`finance`）。

### 2. 权限树与 key 规范

所有「可配置的权限」用一棵树表示，定义在 `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）。

### 3. 菜单权限

- 侧栏菜单项与 `MenuKey` 对应，映射关系在 `lib/permission.ts` 的 `PATH_MENU_KEYS`、`getMenuKeyByPath`。
- 是否展示某菜单：`canAccessMenu(role, menuKey, customMenu?, flatConfig?)`。若使用树形配置，则通过 `flatConfig`（即角色-权限配置）与 `permission-tree` 中 key 的映射得到「该菜单是否对当前角色开放」。
- 侧栏在 `components/layout/sidebar.tsx` 中根据 `canAccessMenu` 过滤 `navConfig`。

### 4. 操作权限（按钮级）

- 操作与 `ActionKey` 对应（如 `customer:create`、`admin:manage`），在 `lib/permission.ts` 中定义。
- `ActionKey` 与权限树 key 的映射见 `ACTION_KEY_TO_PERMISSION`，用于在「使用树形配置」时判断是否允许。
- 页面内使用方式：用 `<Can action="customer:create">...</Can>` 包裹按钮或区域，内部调用 `canDo(role, actionKey, ...)`，无权限则不渲染子节点。

```tsx
import { Can } from "@/components/auth/can";

<Can action="customer:create">
  <Button onClick={openCreate}>新增客户</Button>
</Can>
```

### 5. 默认权限配置

- **菜单默认**：`lib/permission.ts` 中 `DEFAULT_MENU_ROLES`、`DEFAULT_ACTION_ROLES` 为「未使用树形覆盖」时的默认值。
- **树形默认**：`DEFAULT_PERMISSION_ROLES` 为每个权限 key 的默认允许角色；系统相关（如 `system`、`system:admins`）多为 `["super"]` 或 `["super","admin"]`，业务模块多为 `"all"`。
- 角色管理里保存的配置会覆盖上述默认，形成当前生效的 `flatConfig`。

### 6. 扩展角色与权限

1. **新增菜单/页面**：在 `permission-tree.ts` 的树中增加节点（及子操作），在 `permission.ts` 中补充 `MenuKey`、`PATH_MENU_KEYS`、必要时 `ActionKey` 与 `ACTION_KEY_TO_PERMISSION`，侧栏 `navConfig` 增加一项并指定 `menuKey`。
2. **新增操作**：在权限树中加叶子（如 `xxx:opt-export`），在 `ActionKey` 与 `ACTION_KEY_TO_PERMISSION` 中增加对应项，页面中用 `<Can action="xxx:export">` 控制。
3. **对接后端**：将当前「从 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，便于直接跑通与演示。
- 生产环境请对接真实登录、用户信息与权限接口，并视需求将角色与权限配置改为服务端存储。

## 演示截图
<img src="./IMG/1.png" width="49%">
<img src="./IMG/6.png" width="49%">
<img src="./IMG/2.png" width="49%">
<img src="./IMG/3.png" width="49%">
<img src="./IMG/4.png" width="49%">
<img src="./IMG/5.png" width="49%">