Permission Model

Deep Understanding of NextJS Base RBAC Permission System

Model Design · Permission Check · Best Practices

🎯 Overview

NextJS Base adopts the RBAC (Role-Based Access Control) permission model, managing user access permissions through roles.

Core Concepts

Concept	Description	Example
User	System User	Admin, Editor, Viewer
Role	Role, Collection of Permissions	admin, editor, viewer
Permission	Permission, Executable Operation	Create User, Edit Article
Menu	Menu, Page Access Entry	User Management, Article Management

Relationship Diagram

┌─────────────────────────────────────────────────────────────────────┐
│                           RBAC Model                                 │
└─────────────────────────────────────────────────────────────────────┘

                    ┌─────────────┐
                    │    User     │
                    │   User      │
                    └──────┬──────┘
                           │
                           │ roles: String[]
                           │ (Role ID Array)
                           ▼
                    ┌─────────────┐
                    │    Role     │
                    │   Role      │
                    └──────┬──────┘
                           │
           ┌───────────────┼───────────────┐
           │               │               │
           │ permission    │ menu          │ inheritMenuPermissions
           │ String[]      │ String[]      │ Boolean
           ▼               ▼               │
    ┌─────────────┐ ┌─────────────┐       │
    │ Permission  │ │    Menu     │◄──────┘
    │ Permission  │ │   Menu      │
    └─────────────┘ └──────┬──────┘
                           │
                           │ permission: String[]
                           │ (Menu Associated Permissions)
                           ▼
                    ┌─────────────┐
                    │ Permission  │
                    │ Permission  │
                    └─────────────┘

📊 Model Design

User Model

model User {
  id                String    @id @default(cuid())
  email             String    @unique
  name              String?
  
  // Role Association
  roles             String[]  @default([])    // Role ID Array
  
  // Admin Access Permission
  hasBackendAccess  Boolean   @default(false)
  
  // Other Fields...
}

Role Model

model Role {
  id                      String    @id @default(cuid())
  name                    String    @unique        // Role Name
  remark                  String?                  // Remarks
  enable                  Boolean   @default(true) // Enabled
  
  // Permission Association
  permission              String[]  @default([])   // Permission ID Array
  
  // Menu Association
  menu                    String[]  @default([])   // Menu ID Array
  inheritMenuPermissions  Boolean   @default(true) // Inherit Menu Permissions
  
  // Timestamps
  createdAt               DateTime  @default(now())
  updatedAt               DateTime  @updatedAt
}

Permission Model

model Permission {
  id           String    @id @default(cuid())
  name         String                          // Permission Name
  parentId     String?                         // Parent ID (Supports Tree)
  
  // Category and Level
  crudCategory String?                         // CRUD Category
  level        Int       @default(0)           // Level
  
  // Associated Actions
  actions      String[]  @default([])          // Server Action Name Array
  
  // Associated APIs
  apis         String[]  @default([])          // API Path Array
  
  // Sort and Status
  sort         Int       @default(0)
  enable       Boolean   @default(true)
  remark       String?
  
  // Soft Delete
  deletedAt    DateTime?
  
  // Timestamps
  createdAt    DateTime  @default(now())
  updatedAt    DateTime  @updatedAt
}

model Menu {
  id         String    @id @default(cuid())
  name       String                          // Menu Name
  parentId   String?                         // Parent ID (Supports Tree)
  
  // Route Configuration
  url        String?                         // Page Path
  icon       String?                         // Icon
  
  // Associated Permissions
  permission String[]  @default([])          // Associated Permission ID Array
  
  // Display Control
  sort       Int       @default(0)
  enable     Boolean   @default(true)
  hidden     Boolean   @default(false)       // Hidden
  
  remark     String?
  
  // Timestamps
  createdAt  DateTime  @default(now())
  updatedAt  DateTime  @updatedAt
}

🔐 Permission Check

Action Permission Check Flow

┌─────────────────────────────────────────────────────────────────────┐
│                    Call Server Action                                │
│                    sysGetRoleListAction()                             │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Step 1: Parse Action Name                          │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ actionName: 'sysGetRoleList'                                 │   │
│  │                                                              │   │
│  │ Parse Result:                                                │   │
│  │ - prefix: 'sys' → SYSTEM Level                              │   │
│  │ - action: 'Get'                                              │   │
│  │ - resource: 'RoleList'                                       │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Step 2: Authentication Check                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ const session = await auth()                                 │   │
│  │                                                              │   │
│  │ if (!session?.user) {                                       │   │
│  │   throw new Error('Please login first')                     │   │
│  │ }                                                            │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Step 3: Admin Access Check                        │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ // Check if user has admin access permission                │   │
│  │ if (!user.hasBackendAccess) {                               │   │
│  │   throw new Error('No admin access permission')              │   │
│  │ }                                                            │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Step 4: RBAC Permission Check                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ // 1. Get all user roles                                     │   │
│  │ const roles = await getRolesByIds(user.roles)               │   │
│  │                                                              │   │
│  │ // 2. Aggregate all permission IDs                          │   │
│  │ let permissionIds = roles.flatMap(r => r.permission)        │   │
│  │                                                              │   │
│  │ // 3. If role has menu permission inheritance enabled        │   │
│  │ for (const role of roles) {                                 │   │
│  │   if (role.inheritMenuPermissions) {                        │   │
│  │     const menus = await getMenusByIds(role.menu)            │   │
│  │     permissionIds.push(...menus.flatMap(m => m.permission)) │   │
│  │   }                                                          │   │
│  │ }                                                            │   │
│  │                                                              │   │
│  │ // 4. Get permission details                                │   │
│  │ const permissions = await getPermissionsByIds(permissionIds)│   │
│  │                                                              │   │
│  │ // 5. Aggregate all allowed Actions                         │   │
│  │ const allowedActions = permissions.flatMap(p => p.actions)  │   │
│  │                                                              │   │
│  │ // 6. Check if current Action is in allowed list            │   │
│  │ if (!allowedActions.includes('sysGetRoleList')) {           │   │
│  │   throw new Error('No permission to execute this operation')│   │
│  │ }                                                            │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Step 5: Execute Business Logic                    │
│                    ✅ Permission Check Passed                         │
└─────────────────────────────────────────────────────────────────────┘

Menu permissions are used to control sidebar display in the admin panel:

// Get user accessible menus
async function getUserMenus(userId) {
  // 1. Get user
  const user = await getUser(userId)
  
  // 2. Get user roles
  const roles = await getRolesByIds(user.roles)
  
  // 3. Aggregate all menu IDs
  const menuIds = [...new Set(roles.flatMap(r => r.menu))]
  
  // 4. Get menu details
  const menus = await getMenusByIds(menuIds)
  
  // 5. Filter enabled and non-hidden menus
  const visibleMenus = menus.filter(m => m.enable && !m.hidden)
  
  // 6. Build menu tree
  return buildMenuTree(visibleMenus)
}

🎨 Permission Configuration Example

Example: Article Management Permissions

1. Create Permissions

// Article Management - Parent Permission
{
  name: 'Article Management',
  parentId: null,
  crudCategory: 'post',
  level: 0,
  actions: [],
  apis: [],
}

// Article Management - View
{
  name: 'View Article',
  parentId: 'Article Management ID',
  crudCategory: 'post',
  level: 1,
  actions: ['sysGetPostList', 'sysGetPostDetail'],
  apis: [],
}

// Article Management - Create
{
  name: 'Create Article',
  parentId: 'Article Management ID',
  crudCategory: 'post',
  level: 1,
  actions: ['sysCreatePost'],
  apis: [],
}

// Article Management - Edit
{
  name: 'Edit Article',
  parentId: 'Article Management ID',
  crudCategory: 'post',
  level: 1,
  actions: ['sysUpdatePost'],
  apis: [],
}

// Article Management - Delete
{
  name: 'Delete Article',
  parentId: 'Article Management ID',
  crudCategory: 'post',
  level: 1,
  actions: ['sysDeletePost', 'sysBatchDeletePost'],
  apis: [],
}

{
  name: 'Article Management',
  parentId: 'Content Management ID',
  url: '/admin/content/posts',
  icon: 'FileTextOutlined',
  permission: ['View Article ID', 'Create Article ID', 'Edit Article ID', 'Delete Article ID'],
  sort: 10,
  enable: true,
}

3. Assign to Role

// Editor Role - Only View and Edit Permissions
{
  name: 'editor',
  permission: ['View Article ID', 'Edit Article ID'],
  menu: ['Article Management Menu ID'],
  inheritMenuPermissions: false,  // Don't inherit menu permissions, use explicit assignment
}

// Admin Role - All Permissions
{
  name: 'admin',
  permission: [],  // Can be empty
  menu: ['Article Management Menu ID'],
  inheritMenuPermissions: true,  // Inherit all permissions associated with menu
}

📋 Permission Naming Conventions

Action Naming

Prefix	Level	Description	Example
`pub`	PUBLIC	Public Access	`pubGetConfig`
`auth`	AUTH	Login Required	`authGetUserInfo`
`sys`	SYSTEM	Admin Permission Required	`sysGetRoleList`

Complete Naming Format

{prefix}{Action}{Resource}Action

Examples:
- sysGetRoleListAction      // Get Role List
- sysCreateRoleAction       // Create Role
- sysUpdateRoleAction       // Update Role
- sysDeleteRoleAction       // Delete Role
- sysBatchDeleteRoleAction  // Batch Delete Role

Permission Category (crudCategory)

Category	Description	Associated Actions
`role`	Role Management	`sysGetRoleList`, `sysCreateRole`, ...
`permission`	Permission Management	`sysGetPermissionList`, ...
`menu`	Menu Management	`sysGetMenuList`, ...
`user`	User Management	`sysGetUserList`, ...
`post`	Article Management	`sysGetPostList`, ...

✅ Best Practices

1. Permission Granularity

✅ Recommended: Fine-grained Permissions
- View Role
- Create Role
- Edit Role
- Delete Role

❌ Not Recommended: Coarse-grained Permissions
- Role Management (Includes All Operations)

2. Use crudCategory

// ✅ Recommended: Use crudCategory for Grouping
{
  name: 'View Role',
  crudCategory: 'role',
  actions: ['sysGetRoleList', 'sysGetRoleDetail'],
}

// ❌ Not Recommended: Don't Use Category
{
  name: 'View Role',
  actions: ['sysGetRoleList', 'sysGetRoleDetail'],
}

// ✅ Recommended: For admin roles, use menu permission inheritance
{
  name: 'admin',
  menu: ['All Menu IDs'],
  inheritMenuPermissions: true,  // Automatically get all permissions associated with menu
}

// ✅ Recommended: For regular roles, explicitly assign permissions
{
  name: 'editor',
  permission: ['Specific Permission IDs'],
  menu: ['Edit Related Menu IDs'],
  inheritMenuPermissions: false,  // Don't inherit, use explicit assignment
}

4. Permission Check Location

// ✅ Recommended: Automatic check in wrapAction
export const sysGetRoleListAction = wrapAction(
  'sysGetRoleList',
  async (params) => {
    // Permission already checked automatically
    return await dao.getList(params)
  }
)

// ❌ Not Recommended: Manual check in business logic
export const getRoleListAction = async (params) => {
  // Manually check permission
  if (!await checkPermission('sysGetRoleList')) {
    throw new Error('No Permission')
  }
  return await dao.getList(params)
}

Overall Architecture

System architecture overview and role of permissions

Data Flow Design

Request processing flow and permission check nodes

RBAC Configuration Guide

Configuration methods for roles, permissions, and menus

wrapAction API

Execute permission validation at Action layer

Admin Development Path

Complete implementation path from CRUD to permissions/menus

Permission Model

🎯 Overview

Core Concepts

Relationship Diagram

📊 Model Design

User Model

Role Model

Permission Model

Menu Model

🔐 Permission Check

Action Permission Check Flow

Menu Permission Check

🎨 Permission Configuration Example

Example: Article Management Permissions

1. Create Permissions

2. Create Menu

3. Assign to Role

📋 Permission Naming Conventions

Action Naming

Complete Naming Format

Permission Category (crudCategory)

✅ Best Practices

1. Permission Granularity

2. Use crudCategory

3. Menu Permission Inheritance

4. Permission Check Location

Overall Architecture

Data Flow Design

RBAC Configuration Guide

wrapAction API

Admin Development Path

On this page