# Granular Permission Matrix

This document outlines the granular page-specific permissions available in the system and the default permissions assigned to each role.

## Permission Categories

- **View**: Access to view data and information
- **Create**: Ability to create new records
- **Edit**: Ability to modify existing records
- **Delete**: Ability to remove records
- **Approve**: Ability to approve or reject applications
- **Export**: Ability to export data in various formats
- **Manage**: Administrative functions and configuration
- **Process**: Execute business processes and workflows

## Loans Page Permissions

| Permission Code | Permission Name | Description | Category | Critical |
|----------------|-----------------|-------------|----------|----------|
| loans.view_applications | View Loan Applications | View and browse loan applications | View | No |
| loans.view_active | View Active Loans | View active loan details and status | View | No |
| loans.view_defaulted | View Defaulted Loans | View loans that are in default status | View | No |
| loans.view_calculations | View Loan Calculations | View loan interest calculations and payment schedules | View | No |
| loans.create_application | Create Loan Application | Create new loan applications for clients | Create | No |
| loans.edit_application | Edit Loan Application | Edit existing loan applications before approval | Edit | No |
| loans.edit_terms | Edit Loan Terms | Modify loan terms and conditions | Edit | Yes |
| loans.modify_interest | Modify Interest Rates | Change interest rates on loans | Edit | Yes |
| loans.delete_application | Delete Loan Application | Delete loan applications | Delete | Yes |
| loans.approve_application | Approve Loan Application | Approve loan applications for disbursement | Approve | Yes |
| loans.reject_application | Reject Loan Application | Reject loan applications with reasons | Approve | No |
| loans.process_rollover | Process Loan Rollover | Process loan rollovers and extensions | Process | Yes |
| loans.mark_complete | Mark Loan Complete | Mark loans as completed when fully paid | Process | No |
| loans.generate_reports | Generate Loan Reports | Generate various loan reports and analytics | Export | No |
| loans.export_data | Export Loan Data | Export loan data to Excel, PDF, or CSV formats | Export | No |

## Clients Page Permissions

| Permission Code | Permission Name | Description | Category | Critical |
|----------------|-----------------|-------------|----------|----------|
| clients.view_list | View Client List | View the list of all clients | View | No |
| clients.view_history | View Client Loan History | View client loan history and past transactions | View | No |
| clients.view_pending | View Pending Client Approvals | View clients pending approval | View | No |
| clients.view_rejected | View Rejected Clients | View clients that have been rejected | View | No |
| clients.create_new | Add New Client | Add new clients to the system | Create | No |
| clients.edit_info | Edit Client Information | Edit client personal and business information | Edit | No |
| clients.delete_client | Delete Client | Delete client records from the system | Delete | Yes |
| clients.manage_documents | Manage Client Documents | Upload, view, and manage client documents | Manage | No |
| clients.assign_manager | Assign Portfolio Manager | Assign or change client portfolio manager | Manage | No |
| clients.approve_client | Approve Client Application | Approve new client applications | Approve | Yes |
| clients.reject_client | Reject Client Application | Reject client applications with reasons | Approve | No |
| clients.export_data | Export Client Data | Export client data to various formats | Export | No |
| clients.generate_reports | Generate Client Reports | Generate client analytics and reports | Export | No |

## Reports Page Permissions

| Permission Code | Permission Name | Description | Category | Critical |
|----------------|-----------------|-------------|----------|----------|
| reports.view_dashboard | View Reports Dashboard | Access the main reports dashboard | View | No |
| reports.loan_performance | Access Loan Performance Reports | View loan performance and analytics reports | View | No |
| reports.client_analytics | Access Client Analytics | View client analytics and demographic reports | View | No |
| reports.portfolio_summary | Access Portfolio Summary Reports | View portfolio summary and performance reports | View | No |
| reports.financial_statements | Access Financial Statements | View financial statements and accounting reports | View | Yes |
| reports.regulatory_reports | Access Regulatory Reports | View regulatory compliance and audit reports | View | Yes |
| reports.collection_reports | Access Collection Reports | View collection performance and overdue reports | View | No |
| reports.branch_performance | Access Branch Performance Reports | View branch-wise performance and comparison reports | View | No |
| reports.officer_performance | Access Officer Performance Reports | View loan officer performance and productivity reports | View | No |
| reports.custom_reports | Create Custom Reports | Create and save custom report configurations | Create | No |
| reports.export_pdf | Export Reports as PDF | Export reports in PDF format | Export | No |
| reports.export_excel | Export Reports as Excel | Export reports in Excel format | Export | No |
| reports.export_csv | Export Reports as CSV | Export reports in CSV format | Export | No |
| reports.schedule_reports | Schedule Automated Reports | Schedule reports for automatic generation and delivery | Manage | No |
| reports.share_reports | Share Reports | Share reports with other users or external parties | Manage | No |
| reports.manage_templates | Manage Report Templates | Create and modify report templates | Manage | No |

## Dashboard Page Permissions

| Permission Code | Permission Name | Description | Category | Critical |
|----------------|-----------------|-------------|----------|----------|
| dashboard.view_overview | View Dashboard Overview | Access the main dashboard overview | View | No |
| dashboard.view_loan_metrics | View Loan Metrics Widget | View loan performance metrics on dashboard | View | No |
| dashboard.view_client_metrics | View Client Metrics Widget | View client statistics and growth metrics | View | No |
| dashboard.view_financial_summary | View Financial Summary Widget | View financial summary and revenue metrics | View | No |
| dashboard.view_portfolio_performance | View Portfolio Performance Widget | View portfolio performance charts and metrics | View | No |
| dashboard.view_collection_status | View Collection Status Widget | View collection status and overdue metrics | View | No |
| dashboard.view_alerts | View System Alerts | View system alerts and notifications on dashboard | View | No |
| dashboard.view_quick_actions | View Quick Actions | Access quick action buttons on dashboard | View | No |
| dashboard.customize_layout | Customize Dashboard Layout | Customize dashboard widget layout and preferences | Manage | No |
| dashboard.export_dashboard | Export Dashboard Data | Export dashboard data and charts | Export | No |

## Repayments Page Permissions

| Permission Code | Permission Name | Description | Category | Critical |
|----------------|-----------------|-------------|----------|----------|
| repayments.view_payments | View Payment Records | View payment history and records | View | No |
| repayments.view_outstanding | View Outstanding Balances | View outstanding loan balances and due amounts | View | No |
| repayments.view_overdue | View Overdue Payments | View overdue payments and collection status | View | No |
| repayments.record_payment | Record Payment | Record new loan payments and repayments | Create | No |
| repayments.process_refund | Process Refunds | Process payment refunds and adjustments | Process | Yes |
| repayments.reverse_payment | Reverse Payment | Reverse incorrect or duplicate payments | Process | Yes |
| repayments.generate_receipts | Generate Payment Receipts | Generate and print payment receipts | Export | No |
| repayments.export_payment_data | Export Payment Data | Export payment data to various formats | Export | No |

## Documents Page Permissions

| Permission Code | Permission Name | Description | Category | Critical |
|----------------|-----------------|-------------|----------|----------|
| documents.view_documents | View Documents | View uploaded documents and files | View | No |
| documents.view_templates | View Document Templates | View available document templates | View | No |
| documents.upload_documents | Upload Documents | Upload new documents and files | Create | No |
| documents.create_templates | Create Document Templates | Create new document templates | Create | No |
| documents.edit_documents | Edit Document Information | Edit document metadata and information | Edit | No |
| documents.delete_documents | Delete Documents | Delete documents and files | Delete | Yes |
| documents.manage_categories | Manage Document Categories | Create and manage document categories | Manage | No |
| documents.approve_documents | Approve Documents | Approve uploaded documents for official use | Approve | No |

## Settings Page Permissions

| Permission Code | Permission Name | Description | Category | Critical |
|----------------|-----------------|-------------|----------|----------|
| settings.view_system_settings | View System Settings | View system configuration and settings | View | No |
| settings.view_user_management | View User Management | View user accounts and role assignments | View | No |
| settings.view_branch_settings | View Branch Settings | View branch configuration and settings | View | No |
| settings.view_loan_settings | View Loan Settings | View loan product configuration and interest rates | View | No |
| settings.edit_system_settings | Edit System Settings | Modify system configuration and settings | Edit | Yes |
| settings.edit_loan_settings | Edit Loan Settings | Modify loan products and interest rate settings | Edit | Yes |
| settings.edit_branch_settings | Edit Branch Settings | Modify branch configuration and settings | Edit | No |
| settings.manage_users | Manage User Accounts | Create, edit, and deactivate user accounts | Manage | Yes |
| settings.manage_permissions | Manage User Permissions | Assign and modify user permissions and roles | Manage | Yes |
| settings.manage_branches | Manage Branches | Create and manage branch locations | Manage | No |
| settings.backup_restore | Backup and Restore | Perform system backup and restore operations | Manage | Yes |

## Role Permission Matrix

### Admin Role
- **Access Level**: Full access to all permissions
- **Override**: Cannot be overridden (security requirement)
- **Description**: Complete system administration capabilities

### Team Leader Role
- **Dashboard**: Full access to all widgets and customization
- **Loans**: Full operational access except critical modifications (edit_terms, modify_interest, delete_application)
- **Clients**: Full access to all client management functions
- **Reports**: Full access to all reports and export functions
- **Repayments**: Full operational access except critical processes (process_refund, reverse_payment)
- **Documents**: Full access to document management
- **Settings**: Limited access (view most, edit branch settings, manage users)

### Loan Officer Role
- **Dashboard**: Basic access to portfolio-relevant widgets
- **Loans**: Operational access (view, create, edit, mark complete, reports)
- **Clients**: Full operational access (no approval/rejection rights)
- **Reports**: Portfolio-focused reporting access
- **Repayments**: Full operational access for payment processing
- **Documents**: Operational document management
- **Settings**: No access

### Secretary Role
- **Dashboard**: Basic overview and client metrics
- **Loans**: Data entry focused (view, create, edit applications)
- **Clients**: Data entry and document management focused
- **Reports**: Basic reporting and export capabilities
- **Repayments**: Basic payment recording and receipt generation
- **Documents**: Full document management capabilities
- **Settings**: No access

### Auditor Role
- **Dashboard**: Full view access with export capabilities
- **Loans**: Read-only access with comprehensive reporting
- **Clients**: Read-only access with full export capabilities
- **Reports**: Full access to all reports including regulatory and financial
- **Repayments**: Read-only access with export capabilities
- **Documents**: Read-only access to documents and templates
- **Settings**: Read-only access to all settings
- **Override**: Cannot override permissions (compliance requirement)

## Usage Instructions

### Seeding Permissions
```bash
# Seed all page permissions
python manage.py seed_page_permissions

# Seed role permission templates
python manage.py seed_role_templates

# Clear and reseed everything
python manage.py seed_page_permissions --clear
python manage.py seed_role_templates --clear
```

### Checking Permissions in Code
```python
# Check if user has specific permission
if user.has_page_permission('loans', 'approve_application'):
    # User can approve loan applications
    pass

# Get all permissions for a page
permissions = user.get_page_permissions('clients')

# Check multiple permissions
required_permissions = ['loans.view_applications', 'loans.create_application']
if user.has_all_permissions(required_permissions):
    # User has all required permissions
    pass
```

### Template Usage
```html
<!-- Check permission in template -->
{% if user.has_page_permission:'loans':'approve_application' %}
    <button class="btn btn-success">Approve Loan</button>
{% endif %}

<!-- Show content based on role -->
{% if user.role == 'team_leader' or user.role == 'admin' %}
    <div class="admin-panel">...</div>
{% endif %}
```

## Security Considerations

1. **Critical Permissions**: Permissions marked as critical require special approval and logging
2. **Role Inheritance**: Users inherit permissions from their role but can have custom overrides
3. **Permission Dependencies**: Some permissions may require other permissions to be effective
4. **Audit Trail**: All permission changes and usage are logged for compliance
5. **Expiration**: Custom permissions can have expiration dates for temporary access
6. **Override Restrictions**: Some roles (like auditor) cannot override their default permissions