# CreateRole

## Permission Scope

role

## Overview

CreateRole establishes a new role in the system with a unique name and optional description. Roles are containers for permissions that can be assigned to users, providing a level of abstraction that simplifies access management. Examples include "Sales Representative", "Sales Manager", "Administrator".

Roles follow the principle of least privilege, bundling only the permissions necessary for a specific job function.

## Business Rules

- Role name must be unique across all roles
- Role name is required and cannot be empty
- Description is optional but recommended for clarity
- New roles are created with status ACTIVE by default
- New roles start with no permissions assigned

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B{Name provided?}
    B -->|No| C[Return error: MISSING_REQUIRED_FIELD]
    B -->|Yes| D{Name unique?}
    D -->|No| E[Return error: ROLE_ALREADY_EXISTS]
    D -->|Yes| F[Create role record with status ACTIVE]
    F --> G[Return created role]
```

## External Dependencies

- None

## Error Scenarios

- **MISSING_REQUIRED_FIELD**: One or more required fields are missing or empty
- **ROLE_ALREADY_EXISTS**: A role with the same name already exists
- **INVALID_PERMISSION**: Permission key has an invalid format

## Test Cases

- throws when name is empty
- throws when name is whitespace only
- throws when role name already exists
- creates role with valid name
- creates role with description
- creates role with initial permissions
- throws when permissions contain invalid format
- passes custom fields through to insert