# CreateUser

## Permission Scope

user

## Overview

CreateUser establishes a new user account in the system with the provided name and email address. The user is created in PENDING status, awaiting activation by an administrator after verification is complete. This command supports the user onboarding process where new accounts must be verified before gaining system access.

This command enforces email uniqueness across all users (active and inactive) to prevent duplicate accounts.

## Business Rules

- Email must be unique across all users (active and inactive)
- Email must follow valid email format
- Name is required and cannot be empty
- New users are created in PENDING status
- Generates USER_CREATED audit event with actor ID and timestamp

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B{Validate email format}
    B -->|Invalid| C[Return error: INVALID_EMAIL]
    B -->|Valid| D{Email unique?}
    D -->|No| E[Return error: USER_ALREADY_EXISTS]
    D -->|Yes| F{Name provided?}
    F -->|No| G[Return error: MISSING_REQUIRED_FIELD]
    F -->|Yes| H[Create user record]
    H --> I[Set status: PENDING]
    I --> J[Log USER_CREATED audit event]
    J --> K[Return created user]
```

## External Dependencies

- None

## Error Scenarios

- **USER_ALREADY_EXISTS**: Email address is already registered by another user
- **INVALID_EMAIL**: Email does not follow valid email format
- **MISSING_REQUIRED_FIELD**: One or more required fields are missing or empty

## Test Cases

- throws when email is empty
- throws when name is empty
- throws when name is whitespace only
- throws when email format is invalid (no @)
- throws when email format is invalid (no domain)
- throws when email already exists
- creates user with PENDING status
- passes custom fields through to insert