# ActivateAuditPolicy

## Permission Scope

auditPolicy

## Overview

ActivateAuditPolicy transitions an audit policy from DRAFT to ACTIVE status, enabling audit capture for the specified entity, operation type, and scope. Activation is rejected if a conflicting ACTIVE policy already exists for the same (entityName, companyId, operationType) combination. The policy must have a valid entity name and an operation type before activation.

This command requires the `manageAuditPolicies` permission at the appropriate scope.

## Business Rules

- Only policies in DRAFT status can be activated
- At most one ACTIVE policy can exist for a given (entityName, companyId, operationType) combination
- If a conflicting ACTIVE policy exists, activation is rejected with guidance to deactivate the existing policy first or use replaceAuditPolicy
- Target entity name must be non-empty and reference a registered entity
- Exactly one operation type must be specified
- Caller must hold `manageAuditPolicies` permission at the appropriate scope
- A caller with company-scoped `manageAuditPolicies` can only activate policies for their assigned companies
- A caller with global-scoped `manageAuditPolicies` can only activate global policies

## Process Flow

```mermaid
flowchart TD
    A[Receive activate request] --> B{Caller has manageAuditPolicies?}
    B -->|No| C[Return error: INSUFFICIENT_PERMISSION]
    B -->|Yes| D{Policy exists?}
    D -->|No| E[Return error: POLICY_NOT_FOUND]
    D -->|Yes| D2{Caller scope covers this policy?}
    D2 -->|No| D3[Return error: UNAUTHORIZED]
    D2 -->|Yes| F{Policy in DRAFT status?}
    F -->|No| G[Return error: INVALID_STATE]
    F -->|Yes| H{Entity name and operation type valid?}
    H -->|No| I[Return error: INCOMPLETE_POLICY]
    H -->|Yes| I2{Entity still registered?}
    I2 -->|No| I3[Return error: ENTITY_TYPE_NOT_REGISTERED]
    I2 -->|Yes| J{Conflicting ACTIVE policy exists?}
    J -->|Yes| K[Return error: CONFLICTING_ACTIVE_POLICY]
    J -->|No| L[Set status to ACTIVE]
    L --> M[Return activated policy]
```

## External Dependencies

- None

## Error Scenarios

- **INSUFFICIENT_PERMISSION**: Caller lacks the required permission for this operation
- **UNAUTHORIZED**: Caller's permission scope does not cover the target resource
- **POLICY_NOT_FOUND**: Specified policy ID does not exist
- **INVALID_STATE**: Target entity is not in a valid status for this operation
- **INCOMPLETE_POLICY**: Policy is missing entity name or operation type
- **ENTITY_TYPE_NOT_REGISTERED**: Provided entityName/entityType does not match any currently registered auditable entity
- **CONFLICTING_ACTIVE_POLICY**: An ACTIVE policy already exists for the same (entityName, companyId, operationType)

## Test Cases

- activates DRAFT policy to ACTIVE
- begins audit capture after activation
- rejects activation of ACTIVE policy
- rejects activation of INACTIVE policy
- rejects activation when conflicting ACTIVE policy exists
- rejects activation when entity name is missing
- rejects activation when operation type is missing
- rejects when policy does not exist
- rejects when caller lacks manageAuditPolicies permission
- rejects when company-scoped caller activates policy for a different company
- rejects when global-scoped caller activates company-scoped policy
- rejects when target entity is no longer registered
