# Role Lifecycle Management

## Overview

Role Lifecycle Management adds a status field (ACTIVE/INACTIVE) to the Role model, defaulting to ACTIVE on creation. Administrators can deactivate roles that are no longer needed and reactivate them when required again. Deactivated roles stop granting permissions but remain in the system for audit and potential reactivation.

This mirrors the User lifecycle pattern already in the module, applying the same soft-delete approach to roles. When a role is deactivated, effective permissions are recomputed for all affected users to ensure no stale access remains.

## Business Purpose

Organizations need safe role retirement that preserves historical data:

- **Organizational restructuring**: Obsolete roles can be disabled without losing historical assignments or audit records
- **Compliance**: SOC 2 and ISO 27001 require audit trails for access control changes — soft delete preserves records that hard delete would destroy
- **Least privilege**: Unused roles should be disabled to reduce the attack surface and simplify access reviews
- **Reversibility**: Deactivated roles can be restored, unlike hard deletion, supporting temporary suspension during security audits

## Process Flow

```mermaid
flowchart TD
    A[Create Role] --> B[Status: ACTIVE]
    B --> C{Deactivate Role?}
    C -->|Yes| D{Has Active UserRole Assignments?}
    D -->|Yes| E[Return Error: ROLE_HAS_ACTIVE_ASSIGNMENTS]
    D -->|No| F[Deactivate Role]
    F --> G[Status: INACTIVE]
    G --> H{Reactivate Role?}
    H -->|Yes| I[Reactivate Role]
    I --> B

    subgraph Valid Transitions
    B -->|deactivateRole| G
    G -->|reactivateRole| B
    end

    subgraph Guards on Inactive Roles
    G -->|assignRoleToUser| J[Return Error: ROLE_NOT_ACTIVE]
    G -->|grantPermissionToRole| K[Return Error: ROLE_NOT_ACTIVE]
    end
```

DeactivateRole follows the "require cleanup first" pattern: if the role still has active UserRole assignments, the command fails with a ROLE_HAS_ACTIVE_ASSIGNMENTS error listing the assigned users. The administrator must first revoke all user assignments via RevokeRoleFromUser. This prevents silent permission removal and forces explicit review of affected users before deactivation.

## Scenario Patterns

- **Role Retirement**: Organization restructures departments. "Legacy Sales Rep" role is no longer needed. Admin revokes all user assignments, then deactivates the role. Role remains visible in history and audit views.
- **Temporary Deactivation**: A role's permissions are under review due to a security audit. Admin deactivates the role during review, then reactivates it after validation.
- **Reactivation After Restructuring**: Previously deactivated "Regional Manager" role is needed again for a new business unit. Admin reactivates the role and assigns it to users.
- **Blocked Deactivation**: Admin attempts to deactivate "Administrator" role that is still assigned to 3 users. System returns ROLE_HAS_ACTIVE_ASSIGNMENTS error listing the assigned users.
- **Deactivation of Already Inactive Role**: Admin attempts to deactivate an already inactive role. System returns INVALID_STATUS_TRANSITION error.
- **Reactivation of Already Active Role**: Admin attempts to reactivate an already active role. System returns INVALID_STATUS_TRANSITION error.
- **New Role Assignment to Inactive Role**: Attempt to assign an inactive role to a user fails with ROLE_NOT_ACTIVE error.
- **Permission Grant to Inactive Role**: Attempt to grant a permission to an inactive role fails with ROLE_NOT_ACTIVE error.

## Test Cases

- Creating a role should set status to ACTIVE by default
- Deactivating an ACTIVE role with no user assignments should succeed and set status to INACTIVE
- Deactivating an ACTIVE role with active user assignments should fail with ROLE_HAS_ACTIVE_ASSIGNMENTS error
- Deactivating an already INACTIVE role should fail with INVALID_STATUS_TRANSITION error
- Reactivating an INACTIVE role should succeed and set status to ACTIVE
- Reactivating an already ACTIVE role should fail with INVALID_STATUS_TRANSITION error
- Assigning an INACTIVE role to a user should fail with ROLE_NOT_ACTIVE error
- Granting a permission to an INACTIVE role should fail with ROLE_NOT_ACTIVE error
- Deactivating a role should trigger recomputation of effective permissions for all users previously assigned that role
- Reactivating a role should trigger recomputation of effective permissions for users still assigned that role
- Role status field should be queryable and filterable in list queries

## Reference Links

- [Odoo User Management - Archive/Unarchive](https://www.odoo.com/documentation/19.0/applications/general/users.html)
- [Oracle ERP Cloud - Terminate User Accounts](https://docs.oracle.com/en/cloud/saas/applications-common/25a/faser/terminate-user-accounts.html)
- [AWS IAM - Delete Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage_delete.html)
- [NIST RBAC Model](https://csrc.nist.gov/projects/role-based-access-control)