# DeactivateRole

## Permission Scope

role

## Overview

DeactivateRole transitions a role from ACTIVE status to INACTIVE status. Deactivated roles stop granting permissions but remain in the system for audit and potential reactivation.

Deactivation is blocked if the role still has active UserRole assignments. The administrator must first revoke all user assignments via RevokeRoleFromUser. This prevents silent permission removal and forces explicit review of affected users.

## Business Rules

- Role must exist in the system
- Role must be in ACTIVE status
- Role must have no active UserRole assignments
- Transitions role status from ACTIVE to INACTIVE
- Triggers recomputation of effective permissions for previously assigned users

## Process Flow

```mermaid
flowchart TD
    A[Receive deactivate request] --> B{Role exists?}
    B -->|No| C[Return error: ROLE_NOT_FOUND]
    B -->|Yes| D{Status is ACTIVE?}
    D -->|No| E[Return error: INVALID_STATUS_TRANSITION]
    D -->|Yes| F{Has active UserRole assignments?}
    F -->|Yes| G[Return error: ROLE_HAS_ACTIVE_ASSIGNMENTS]
    F -->|No| H[Update status to INACTIVE]
    H --> I[Recompute effective permissions for affected users]
    I --> J[Return updated role]
```

## External Dependencies

- None

## Error Scenarios

- **ROLE_NOT_FOUND**: Specified role ID does not exist
- **INVALID_STATUS_TRANSITION**: Requested status transition is not allowed from the current status
- **ROLE_HAS_ACTIVE_ASSIGNMENTS**: Role still has active UserRole assignments — must revoke all assignments first

## Test Cases

- throws when role does not exist
- throws when role is already INACTIVE
- throws when role has active user assignments
- deactivates ACTIVE role with no assignments to INACTIVE
- triggers recomputation of effective permissions
