# RegisterAuditableEntity

## Permission Scope

auditEvent

## Overview

RegisterAuditableEntity registers an entity for audit tracking within the audit module. Other modules call this command at initialization time to declare which of their entities are eligible for auditing, specifying the entity name, scope (COMPANY_BOUND or GLOBAL), and the list of auditable fields. Each field can be specified as a plain string (field name only) or as an object `{ fieldName, fieldType? }` where fieldType must be one of the eligible types: scalar, richtext, array, relation, or file. Any other fieldType is rejected as ineligible. Once registered, entity scope is immutable.

## Business Rules

- entityName is required, must be non-empty, and must be unique across all registrations
- entityScope is required and must be one of COMPANY_BOUND or GLOBAL
- auditableFields is required and must contain at least one entry
- Each entry in auditableFields is either a non-empty string or an object with a non-empty `fieldName` and an optional `fieldType`
- Only the following fieldType values are eligible: `scalar`, `richtext`, `array`, `relation`, `file`. Any other fieldType (e.g. `binary`, `computed`) is rejected with INVALID_AUDITABLE_FIELDS
- If an entity with the same name is already registered, the command is rejected
- Entity scope is immutable once registered — it cannot be changed after initial registration

## Process Flow

```mermaid
flowchart TD
    A[Receive registration request] --> A2{Caller has registerAuditableEntity permission?}
    A2 -->|No| A3[Return error: INSUFFICIENT_PERMISSION]
    A2 -->|Yes| B{entityName non-empty?}
    B -->|No| C[Return error: INVALID_ENTITY_NAME]
    B -->|Yes| D{entityScope valid?}
    D -->|No| G[Return error: INVALID_ENTITY_SCOPE]
    D -->|Yes| E{auditableFields non-empty?}
    E -->|No| I[Return error: INVALID_AUDITABLE_FIELDS]
    E -->|Yes| F{All field names non-empty and fieldTypes eligible?}
    F -->|No| I2[Return error: INVALID_AUDITABLE_FIELDS]
    F -->|Yes| H{entityName already registered?}
    H -->|Yes| J[Return error: DUPLICATE_ENTITY_NAME]
    H -->|No| K[Create AuditableEntity record]
    K --> L[Return success]
```

## External Dependencies

- None

## Error Scenarios

- **INSUFFICIENT_PERMISSION**: Caller lacks the required permission for this operation
- **INVALID_ENTITY_NAME**: entityName is empty or not provided
- **DUPLICATE_ENTITY_NAME**: An entity with the same name is already registered
- **INVALID_ENTITY_SCOPE**: entityScope is missing or not one of COMPANY_BOUND, GLOBAL
- **INVALID_AUDITABLE_FIELDS**: auditableFields is empty, contains an empty field name, or contains a field with an ineligible fieldType (any type outside scalar, richtext, array, relation, file)

## Test Cases

- registers entity with COMPANY_BOUND scope
- registers entity with GLOBAL scope
- accepts mixed string and object field definitions in auditableFields
- rejects registration with empty entityName
- rejects registration with duplicate entityName
- rejects registration with invalid entityScope
- rejects registration with empty auditableFields
- rejects registration with empty field name in auditableFields
- rejects registration with binary field type in auditableFields
- rejects registration with computed field type in auditableFields
- rejects registration with unknown field type in auditableFields
- rejects caller without registerAuditableEntity permission
