# GetAuditSummary

## Overview

GetAuditSummary returns aggregated audit statistics without exposing field-level change details. It provides counts of audit entries grouped by configurable dimensions such as entityType, operationType, actorType, and time period. This query is designed for compliance dashboards and operational oversight where administrators need a high-level view of audit activity without access to sensitive before/after field values.

This query requires the `viewAuditSummary` permission at the appropriate scope — a lower-privilege alternative to `viewAuditHistory` which grants access to full audit entry details.

## Business Rules

- Caller must hold `viewAuditSummary` permission at the appropriate scope
- A caller with company-scoped `viewAuditSummary` can only retrieve summaries for their assigned companies
- A caller with global-scoped `viewAuditSummary` can retrieve summaries for global (company-unscoped) entries
- At least one grouping dimension must be specified (entityType, operationType, actorType, or timePeriod)
- Optional filters: entityType, operationType, actorType, companyId, date range
- An optional `scope` parameter accepts COMPANY, GLOBAL, or ALL to control which entries are summarized
- When `scope` is COMPANY (or companyId is provided without explicit scope), returns summary counts scoped to that company only; companyId is required in this case
- When `scope` is GLOBAL (or companyId is omitted without explicit scope), returns summary counts for global entries only
- When `scope` is ALL, returns combined summary counts for all scopes the caller is authorized for; if companyId is also provided, it acts as an additional filter within the combined results
- When both company and global scope are requested via `scope=ALL`, the caller must hold `viewAuditSummary` at each scope they wish to see — unauthorized scopes are silently excluded from the result
- Response contains only aggregate counts — no eventId, entityId, actorId, change details, or other entry-level data is returned
- Time period grouping supports DAY, WEEK, and MONTH granularities

## Process Flow

```mermaid
flowchart TD
    A[Receive summary request] --> B{Caller has viewAuditSummary?}
    B -->|No| C[Return error: INSUFFICIENT_PERMISSION]
    B -->|Yes| D{At least one grouping dimension?}
    D -->|No| E[Return error: VALIDATION_ERROR]
    D -->|Yes| F[Apply scope and filter criteria]
    F --> G{Determine scope}
    G -->|scope=COMPANY or companyId provided| H[Scope to company entries]
    G -->|scope=GLOBAL or no companyId| I[Scope to global entries]
    G -->|scope=ALL| I2[Combine company + global entries\nfor scopes caller is authorized for]
    H --> J[Aggregate counts by grouping dimensions]
    I --> J
    I2 --> J
    J --> K[Return summary results]
```

## External Dependencies

- None

## Error Scenarios

- **INSUFFICIENT_PERMISSION**: Caller lacks `viewAuditSummary` permission
- **UNAUTHORIZED**: Caller's permission scope does not cover the requested company scope
- **VALIDATION_ERROR**: No grouping dimension specified (at least one of entityType, operationType, actorType, or timePeriod is required)
- **VALIDATION_ERROR**: `scope` is COMPANY but no companyId is provided
- **INVALID_SCOPE**: `scope` is not one of COMPANY, GLOBAL, or ALL

## Test Cases

- returns entry counts grouped by entityType
- returns entry counts grouped by operationType
- returns entry counts grouped by actorType
- returns entry counts grouped by time period (DAY)
- returns entry counts grouped by time period (WEEK)
- returns entry counts grouped by time period (MONTH)
- combines multiple grouping dimensions
- filters by entityType before aggregation
- filters by operationType before aggregation
- filters by date range before aggregation
- filters by companyId returning only company-scoped counts
- returns global entry counts when companyId is omitted
- returns combined company and global counts when scope is ALL
- restricts combined results to scopes the caller is authorized for
- returns only company counts in combined scope when caller lacks global permission
- returns only global counts in combined scope when caller lacks company permission
- filters combined scope results by companyId when both scope=ALL and companyId are provided
- rejects scope=COMPANY when companyId is not provided
- rejects invalid scope value
- returns zero counts when no entries match filters
- rejects when no grouping dimension is specified
- rejects when caller lacks viewAuditSummary permission
- rejects when caller lacks permission for requested company scope
- restricts company-scoped caller to their company even when scope=GLOBAL
- restricts company-scoped caller to their company even when scope=ALL
- restricts global-scoped caller to global entries even when scope=COMPANY
- restricts global-scoped caller to global entries even when scope=ALL
- does not expose field-level change details in response
