# ListAuditPolicies

## Overview

ListAuditPolicies retrieves a list of audit policies with optional filters by entity name, status, company scope, and operation type. Returns policies with their associated PolicyFieldRule records. This query supports administrative views for managing audit configurations across entities and companies.

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

## Business Rules

- All filter parameters are optional
- Filtering by entityName returns only policies targeting that entity
- Filtering by status returns only policies in the specified status (DRAFT, ACTIVE, INACTIVE)
- Filtering by companyId returns only policies scoped to that company
- Filtering by companyId explicitly set to null returns only global policies (companyId = null)
- Omitting the companyId filter entirely returns policies of all scopes (global and company-scoped), subject to the caller's permission scope
- Filtering by operationType returns only policies for that operation
- Caller must hold `manageAuditPolicies` permission at the appropriate scope
- A caller with company-scoped `manageAuditPolicies` can only retrieve policies for their assigned companies
- A caller with global-scoped `manageAuditPolicies` can only retrieve global policies

## Process Flow

```mermaid
flowchart TD
    A[Receive list request] --> B{Caller has manageAuditPolicies?}
    B -->|No| C[Return error: INSUFFICIENT_PERMISSION]
    B -->|Yes| D[Build query from filter criteria]
    D --> E[Apply scope restrictions based on caller's permissions]
    E --> F[Load matching policies with PolicyFieldRules]
    F --> G[Return list of policies]
```

## 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

## Test Cases

- returns all policies when no filters applied
- returns policies filtered by entityName
- returns policies filtered by status
- returns policies filtered by companyId
- returns only global policies when companyId filter is explicitly null
- returns policies filtered by operationType
- combines multiple filter criteria
- returns policy objects with expected fields
- returns empty list when no policies match
- paginates results correctly
- rejects when caller lacks manageAuditPolicies permission
- rejects when caller with company-scoped permission requests policies for a different company
- returns only global policies when caller has global-scoped permission
- rejects when global-scoped caller requests company-scoped policies
