# Baseline Role Permissions - Required for All Users

**Date**: November 30, 2025  
**Status**: ✅ Implemented

## Problem

Users assigned to roles without basic permissions cannot:
- Access the dashboard after login
- View or edit their profile
- Send/receive emails
- Use messaging system
- Perform essential self-service tasks

**Example**: User `test@mavrix.one` could log in but saw a blank screen because Test Role lacked baseline permissions.

## Solution

Every role MUST have these baseline permissions for basic system functionality:

### Essential Baseline Permissions

#### 1. Dashboard Access
```
dashboard.view - View main dashboard
```
Without this, users land on a blank page after login.

#### 2. Profile Management
```
profile.view - View own profile
profile.edit - Edit own profile settings
```
Users need to manage their own information, change passwords, update preferences.

#### 3. Email System
```
email.view      - View email interface
email.read      - Read emails
email.compose   - Compose new emails
email.send      - Send emails
email.reply     - Reply to emails
email.forward   - Forward emails
email.delete    - Delete own emails
email.attachments - Handle attachments
email.folders   - Manage email folders
```
Email is essential for internal/external communication.

#### 4. Messaging System
```
messaging.view     - View messaging interface
messaging.send     - Send messages
messaging.channels - Access team channels
messaging.direct   - Direct messages with colleagues
```
Internal team communication is a basic need.

## Implementation

### For Existing Roles

To add baseline permissions to an existing role:

```sql
-- Replace 134 with your role_id
INSERT IGNORE INTO role_permissions (role_id, permission_id)
SELECT 134, id FROM permissions 
WHERE name IN (
    'dashboard.view',
    'profile.view', 
    'profile.edit',
    'email.view',
    'email.compose',
    'email.send',
    'email.read',
    'email.reply',
    'email.forward',
    'email.delete',
    'email.attachments',
    'email.folders',
    'messaging.view',
    'messaging.send',
    'messaging.channels',
    'messaging.direct'
);
```

### For New Roles

When creating roles through the UI:
1. Go to **Settings > Security > Roles & Access Management**
2. Select the role
3. Click **Menu Permissions** tab
4. Ensure the following are enabled:
   - ✅ Dashboard
   - ✅ Profile (under Settings)
   - ✅ Email
   - ✅ Messaging

### Automatic Enforcement (Future Enhancement)

Ideally, the role creation process should automatically grant these baseline permissions. This could be implemented in:
- `RoleAccessController::createRole()` method
- Add default permissions after role creation
- Or create a "Basic User" template role that all new roles inherit from

## Permission Count

**Total baseline permissions**: 16 permissions

This represents the minimum viable set for a user to:
- Log in
- Navigate the system
- Communicate
- Manage their own account

## Testing Checklist

When testing a new role:
- [ ] User can log in successfully
- [ ] User sees dashboard after login (not blank screen)
- [ ] User can access their profile
- [ ] User can change their password
- [ ] User can compose and send emails
- [ ] User can send messages to colleagues
- [ ] User sees appropriate menu items (at minimum: Dashboard, Email, Messaging, Profile)

## Best Practices

### 1. Start with Baseline
When creating a new role, **ALWAYS** start by granting baseline permissions, then add module-specific permissions.

### 2. Test with Restricted User
After creating a role, test it with a non-admin user account to ensure they can access basic functionality.

### 3. Document Role Purpose
In the role description, clearly state what the role is intended for beyond baseline access.

**Example**:
```
Role: Warehouse Staff
Description: Baseline access plus inventory management, 
stock movements, and goods receipt permissions. 
Cannot access financial or HR data.
```

### 4. Role Naming Convention
Suggest clear role names:
- ✅ Good: "Sales Representative", "Warehouse Manager", "Accountant"
- ❌ Bad: "Test Role", "User123", "Temp"

## Common Role Templates

### Basic Employee (Baseline Only)
- Dashboard, Profile, Email, Messaging
- **Use case**: New hire, contractor, temporary staff

### Department Staff (Baseline + Module)
- Baseline permissions
- + Specific module permissions (Sales, HR, Accounting, etc.)
- **Use case**: Department-specific employees

### Department Manager (Staff + Management)
- Baseline permissions
- + Module view/create/edit permissions
- + Reports and analytics
- **Use case**: Team leads, supervisors

### Department Director (Manager + Admin)
- Baseline permissions
- + Full module permissions
- + User management within department
- + Budget and approval permissions
- **Use case**: Department heads, VPs

### System Administrator
- All permissions (or `admin` permission)
- **Use case**: IT staff, system admins

## Troubleshooting

### User sees blank screen after login
**Cause**: Role lacks `dashboard.view` permission  
**Fix**: Add baseline permissions to the role

### User can't access profile
**Cause**: Role lacks `profile.view` permission  
**Fix**: Add `profile.view` and `profile.edit`

### User can't see email
**Cause**: Role lacks email permissions  
**Fix**: Add email baseline permissions

### User sees "Access Denied" everywhere
**Cause**: Role has no permissions except maybe dashboard  
**Fix**: Add baseline permissions + appropriate module permissions

## SQL Query: Check Missing Baseline

To check which roles are missing baseline permissions:

```sql
-- Find roles without dashboard.view
SELECT r.id, r.name, 'Missing dashboard.view' as issue
FROM roles r
LEFT JOIN role_permissions rp ON r.id = rp.role_id
LEFT JOIN permissions p ON rp.permission_id = p.id AND p.name = 'dashboard.view'
WHERE p.id IS NULL;

-- Find roles without profile.view
SELECT r.id, r.name, 'Missing profile.view' as issue
FROM roles r
LEFT JOIN role_permissions rp ON r.id = rp.role_id
LEFT JOIN permissions p ON rp.permission_id = p.id AND p.name = 'profile.view'
WHERE p.id IS NULL;

-- Find roles without email.view
SELECT r.id, r.name, 'Missing email.view' as issue
FROM roles r
LEFT JOIN role_permissions rp ON r.id = rp.role_id
LEFT JOIN permissions p ON rp.permission_id = p.id AND p.name = 'email.view'
WHERE p.id IS NULL;
```

## Related Documentation

- **Security Setup Guide**: `/documentation/security-guide` (in app)
- **Role & Access Management**: Main interface at `/security/roles`
- **User Management**: `/users` for assigning users to roles

---

**Summary**: All roles must have baseline permissions for dashboard, profile, email, and messaging. Without these, users cannot perform basic functions after login.

*Updated: November 30, 2025*