# UpdateRole

## Permission Scope

role

## Overview

UpdateRole modifies the name and/or description of an existing role. All existing UserRole and RolePermission associations remain intact — only the role's metadata is changed.

Only ACTIVE roles can be updated. Inactive roles must be reactivated before modification.

## Business Rules

- Role must exist in the system
- Role must be in ACTIVE status
- New name must be unique across all roles (if name is being changed)
- New name is required and cannot be empty

## Process Flow

```mermaid
flowchart TD
    A[Receive update request] --> B{Role exists?}
    B -->|No| C[Return error: ROLE_NOT_FOUND]
    B -->|Yes| D{Status is ACTIVE?}
    D -->|No| E[Return error: ROLE_NOT_ACTIVE]
    D -->|Yes| F{Name non-empty?}
    F -->|No| F1[Return error: MISSING_REQUIRED_FIELD]
    F -->|Yes| G{New name unique?}
    G -->|No| H[Return error: ROLE_ALREADY_EXISTS]
    G -->|Yes| I[Update role record]
    I --> J[Return updated role]
```

## External Dependencies

- None

## Error Scenarios

- **ROLE_NOT_FOUND**: Specified role ID does not exist
- **ROLE_NOT_ACTIVE**: Role is not in ACTIVE status and cannot be used for this operation
- **ROLE_ALREADY_EXISTS**: A role with the same name already exists
- **MISSING_REQUIRED_FIELD**: One or more required fields are missing or empty
- **INVALID_PERMISSION**: Permission key has an invalid format

## Test Cases

- throws when role does not exist
- throws when role is INACTIVE
- throws when new name already exists
- throws when new name is empty
- updates role name successfully
- updates role description successfully
- clears role description when null is passed
- does not touch description when undefined is passed
- updates role permissions
- throws when permissions contain invalid format
- does not affect existing UserRole or RolePermission assignments