# Roles & Permissions System This document describes the newly redesigned Roles & Permissions system for the NestJS application. ## 📋 Overview The system provides a comprehensive role-based access control (RBAC) with grouped permissions that match the UI requirements. Each permission belongs to a feature group, and roles can be assigned multiple permissions across different groups. ## 🗄️ Database Structure ### Tables Created 1. **roles** - Existing table (updated with new relationships) - `id` (PK) - `company_id` (FK, nullable) - `name` (string) - `status` (smallint, default 1) - `created_by`, `updated_by`, `deleted_by` (from BaseEntity) - `created_at`, `updated_at`, `deleted_at` (from BaseEntity) 2. **permissions** - New table - `id` (PK) - `group_key` (string) - e.g., "dashboard", "time_tracking" - `permission_key` (string) - e.g., "view_dashboard", "manage_activities" - `label` (string) - Human readable name - `description` (string) - Description of the permission - `status` (smallint, default 1) - `created_by`, `updated_by`, `deleted_by` (from BaseEntity) - `created_at`, `updated_at`, `deleted_at` (from BaseEntity) 3. **role_permissions** - New junction table - `id` (PK) - `role_id` (FK to roles) - `permission_id` (FK to permissions) - `company_id` (FK to companies) - `status` (smallint, default 1) - `created_by`, `updated_by`, `deleted_by` (from BaseEntity) - `created_at`, `updated_at`, `deleted_at` (from BaseEntity) ## 🔧 Setup Instructions ### 1. Run Database Migrations ```bash # Generate migration for new entities npm run migration:generate -- -n CreatePermissionsAndRolePermissions # Run the migration npm run migration:run ``` ### 2. Seed Permissions ```bash # Run the permissions seeder npx ts-node src/database/seeders/run-permissions-seeder.ts ``` ## 📁 File Structure ``` src/ ├── constants/ │ └── permissions.constant.ts # Permission constants and helpers ├── modules/ │ ├── permissions/ │ │ ├── dto/ │ │ │ ├── create-permission.dto.ts │ │ │ └── update-permission.dto.ts │ │ ├── entities/ │ │ │ └── permission.entity.ts │ │ ├── repositories/ │ │ │ └── permission.repository.ts │ │ ├── permissions.controller.ts │ │ ├── permissions.service.ts │ │ └── permissions.module.ts │ ├── role-permissions/ │ │ ├── dto/ │ │ │ ├── create-role-permission.dto.ts │ │ │ ├── update-role-permission.dto.ts │ │ │ └── assign-permissions.dto.ts │ │ ├── entities/ │ │ │ └── role-permission.entity.ts │ │ ├── repositories/ │ │ │ └── role-permission.repository.ts │ │ ├── role-permissions.controller.ts │ │ ├── role-permissions.service.ts │ │ └── role-permissions.module.ts │ └── role/ # Updated existing module │ ├── dto/ │ │ └── update-role.dto.ts # New file │ ├── entities/ │ │ └── role.entity.ts # Updated with relationships │ ├── role.controller.ts # Updated with new endpoints │ ├── role.service.ts # Updated with permission methods │ └── role.module.ts # Updated with dependencies ├── common/ │ ├── guards/ │ │ └── permission.guard.ts # Permission checking guard │ └── decorators/ │ └── permissions.decorator.ts # Permission decorator └── database/ └── seeders/ ├── permissions.seeder.ts # Permission seeder class └── run-permissions-seeder.ts # Seeder runner script ``` ## 🚀 API Endpoints ### Roles - `GET /roles` - Get all roles - `GET /roles/:id` - Get role by ID (includes permissions) - `POST /roles` - Create new role - `PUT /roles/:id` - Update role - `DELETE /roles/:id` - Delete role (soft delete) - `PATCH /roles/active-inactive/:id` - Toggle role status ### Permissions - `GET /permissions` - Get all permissions - `GET /permissions/grouped` - Get permissions grouped by feature - `GET /permissions/:id` - Get permission by ID - `POST /permissions` - Create new permission - `PUT /permissions/:id` - Update permission - `DELETE /permissions/:id` - Delete permission (soft delete) - `PATCH /permissions/active-inactive/:id` - Toggle permission status ### Role Permissions - `GET /role-permissions` - Get all role-permission assignments - `POST /role-permissions` - Create single role-permission assignment - `POST /role-permissions/assign` - Assign multiple permissions to a role - `GET /role-permissions/role/:roleId/company/:companyId` - Get permissions for a role - `DELETE /role-permissions/:id` - Remove role-permission assignment ## 🔐 Permission System Usage ### 1. Using Permission Guard ```typescript import { UseGuards } from '@nestjs/common' import { PermissionGuard } from '../common/guards/permission.guard' import { RequirePermissions } from '../common/decorators/permissions.decorator' import { PERMISSIONS } from '../constants/permissions.constant' @Controller('employees') @UseGuards(PermissionGuard) export class EmployeesController { @Get() @RequirePermissions(PERMISSIONS.EMPLOYEES.VIEW) findAll() { // Only users with 'view_employees' permission can access } @Post() @RequirePermissions(PERMISSIONS.EMPLOYEES.MANAGE) create() { // Only users with 'manage_employees' permission can access } @Delete(':id') @RequirePermissions(PERMISSIONS.EMPLOYEES.MANAGE, PERMISSIONS.DEPARTMENTS.MANAGE) remove() { // User needs BOTH permissions to access } } ``` ### 2. Available Permission Constants ```typescript import { PERMISSIONS } from '../constants/permissions.constant' // Usage examples: PERMISSIONS.DASHBOARD.VIEW // "view_dashboard" PERMISSIONS.TIME_TRACKING.VIEW // "view_time_tracking" PERMISSIONS.TIME_TRACKING.MANAGE_ACTIVITIES // "manage_activities" PERMISSIONS.EMPLOYEES.VIEW // "view_employees" PERMISSIONS.EMPLOYEES.MANAGE // "manage_employees" // ... and many more ``` ### 3. Login Response Structure The login API now returns permissions in a grouped format: ```json { "status": true, "code": 200, "message": "Login successful", "data": { "user": { "id": 1, "first_name": "John", "last_name": "Doe", "email": "john@example.com", "company_id": 1, "role_id": 2, "permissions": { "dashboard": [ { "id": 1, "permission_key": "view_dashboard", "label": "View Dashboard", "description": "Permission to view dashboard" } ], "employees": [ { "id": 5, "permission_key": "view_employees", "label": "View Employees", "description": "Permission to view employees" }, { "id": 6, "permission_key": "manage_employees", "label": "Manage Employees", "description": "Permission to manage employees" } ] } }, "tokens": { "access_token": "...", "refresh_token": "..." } } } ``` ## 🔄 Assigning Permissions to Roles ### Using the API ```bash # Assign multiple permissions to a role POST /role-permissions/assign { "role_id": 2, "permission_ids": [1, 5, 6, 10, 15] } ``` ### Using the Service ```typescript import { RolePermissionsService } from '../modules/role-permissions/role-permissions.service' // In your service await this.rolePermissionsService.assignPermissionsToRole({ role_id: 2, permission_ids: [1, 5, 6, 10, 15] }, authToken) ``` ## 🎯 Permission Groups The system includes the following permission groups: - **dashboard** - Dashboard access - **time_tracking** - Time tracking and activities - **leaves** - Leave management - **employees** - Employee management - **departments** - Department management - **consultants** - Consultant management - **contractors** - Contractor management - **vendors** - Vendor management - **activity_types** - Activity type management - **clients** - Client management - **projects** - Project management - **categories** - Category management - **roles** - Role management - **permissions** - Permission management - **company** - Company settings - **salary_settings** - Salary configuration - **leave_types** - Leave type management - **party_types** - Party type management ## 🛠️ Development Notes 1. **Adding New Permissions**: Update `src/constants/permissions.constant.ts` and run the seeder 2. **Custom Permission Logic**: Extend the `PermissionGuard` for complex permission checks 3. **Database Relations**: All entities properly extend `BaseEntity` for audit trails 4. **Soft Deletes**: All entities support soft deletion through the `status` field 5. **Company Isolation**: Role permissions are scoped by company for multi-tenancy ## 🔍 Testing the System 1. **Seed the permissions**: Run the seeder script 2. **Create a role**: Use the roles API 3. **Assign permissions**: Use the role-permissions API 4. **Test login**: Verify permissions are returned 5. **Test guards**: Try accessing protected endpoints ## 📝 Migration Notes - Existing roles table is preserved and enhanced - New permission system is backward compatible - All existing user roles will continue to work - Permissions need to be assigned to existing roles after setup This system provides a robust, scalable foundation for managing user permissions across your application while maintaining clean separation of concerns and following NestJS best practices.