> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devmob.app.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit Log

> AuditLog: log de auditoria append-only com rastreamento por domain, resource e resourceId.

O **AuditLog** é um log de auditoria **append-only** que registra mutações auditáveis que ocorrem no sistema. Cada registro identifica o tipo de log, o domain, o recurso afetado, o usuário associado à ação e os dados necessários para rastreabilidade.

## Campos

| Campo            | Tipo              | Descrição                                                         |
| ---------------- | ----------------- | ----------------------------------------------------------------- |
| `auditLogId`     | UUID              | Identificador único                                               |
| `organizationId` | UUID?             | Organização onde a mutação ocorreu (opcional)                     |
| `userId`         | UUID?             | Usuário que realizou a ação (opcional — null em ações de sistema) |
| `type`           | AuditLogType      | Tipo do registro de log                                           |
| `domain`         | AuditDomain       | Domain do recurso auditado                                        |
| `resource`       | AuditResource     | Entity ou recurso auditado dentro do domain                       |
| `resourceId`     | string            | ID da instância do recurso afetado                                |
| `action`         | string            | Nome aberto da ação auditada                                      |
| `userAgent`      | string (nullable) | User-Agent do cliente HTTP                                        |
| `ip`             | string (nullable) | Endereço IP de origem                                             |
| `oldData`        | JSON (nullable)   | Estado anterior do recurso (null em CREATE)                       |
| `newData`        | JSON (nullable)   | Estado posterior do recurso (null em DELETE)                      |
| `createdBy`      | UUID?             | Usuário que criou o registro, quando aplicável                    |
| `createdAt`      | datetime          | Data/hora do registro                                             |

## Tipo do registro

`type` separa a origem do registro:

| Tipo              | Uso                                                                               |
| ----------------- | --------------------------------------------------------------------------------- |
| `APPLICATION_LOG` | Registro emitido por fluxo da aplicação, caso de uso, API ou ação de usuário      |
| `SYSTEM_LOG`      | Registro emitido por rotina automática, scheduler, integração ou processo interno |

Esse campo não substitui `action`. Ele apenas classifica a origem do log.

## Rastreamento

O trio `domain` + `resource` + `resourceId` identifica a instância auditada:

```
domain: "IDENTITY"    + resource: "USER"    + resourceId: "abc-123"  → Mutação no User abc-123
domain: "SALES"       + resource: "ORDER"   + resourceId: "def-456"  → Mutação no Order def-456
domain: "OPERATIONS"  + resource: "ROUTE"   + resourceId: "ghi-789"  → Mutação na Route ghi-789
```

Isso permite filtrar o histórico de auditoria por tipo de recurso e identificador.

## Action aberta

`action` não é enum. Ela é uma string aberta, definida pela aplicação no momento do registro.

A convenção recomendada é usar uma combinação legível de recurso + ação de negócio, como:

| Exemplo                         | Uso                                   |
| ------------------------------- | ------------------------------------- |
| `USER_BLOCKED`                  | Usuário bloqueado                     |
| `SESSION_REVOKED`               | Sessão revogada                       |
| `SESSION_REVOKED_AUTOMATICALLY` | Sessão revogada por rotina automática |
| `ROUTE_APPROVED`                | Rota aprovada                         |
| `TICKET_REPRINTED`              | Ticket reimpresso                     |
| `BENEFIT_REQUEST_APPROVED`      | Solicitação de benefício aprovada     |

## Exemplo de Registros

### ORDER\_CREATED

```json theme={null}
{
  "auditLogId": "0197a819-ae6c-7cd6-b872-1f6c898c50d9",
  "type": "APPLICATION_LOG",
  "domain": "SALES",
  "resource": "ORDER",
  "resourceId": "0197a813-0fb9-7d42-9c81-50c0f6d9ae5a",
  "action": "ORDER_CREATED",
  "oldData": null,
  "newData": {
    "orderId": "0197a813-0fb9-7d42-9c81-50c0f6d9ae5a",
    "companyId": "0197a801-6a42-79aa-9e56-d3c85148c0fa",
    "amount": 15000,
    "status": "PENDING"
  },
  "userId": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "ip": "192.168.1.10",
  "createdAt": "2026-07-03T16:00:00.000Z"
}
```

### USER\_BLOCKED

```json theme={null}
{
  "auditLogId": "0197a819-b9b0-7b85-96c5-2bd4a2214e59",
  "type": "APPLICATION_LOG",
  "domain": "IDENTITY",
  "resource": "USER",
  "resourceId": "0197a7f5-2a88-7c1e-9b65-1f6d8f3b3a10",
  "action": "USER_BLOCKED",
  "oldData": {
    "status": "ACTIVE"
  },
  "newData": {
    "status": "BLOCKED"
  },
  "userId": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "ip": "192.168.1.10",
  "createdAt": "2026-07-03T16:02:00.000Z"
}
```

### ROUTE\_APPROVED

```json theme={null}
{
  "auditLogId": "0197a819-c960-75c6-b82e-947c32b4a9c1",
  "type": "APPLICATION_LOG",
  "domain": "OPERATIONS",
  "resource": "ROUTE",
  "resourceId": "0197a80c-4204-7b77-9005-48cc23677587",
  "action": "ROUTE_APPROVED",
  "oldData": {
    "status": "PENDING_APPROVAL"
  },
  "newData": {
    "status": "ACTIVE"
  },
  "userId": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "ip": "192.168.1.20",
  "createdAt": "2026-07-03T17:00:00.000Z"
}
```

### SESSION\_REVOKED\_AUTOMATICALLY

```json theme={null}
{
  "auditLogId": "0197a819-d37f-708d-9c98-a3d51704fbd3",
  "type": "SYSTEM_LOG",
  "domain": "IDENTITY",
  "resource": "USER_SESSION",
  "resourceId": "0197a80c-4204-7b77-9005-48cc23677587",
  "action": "SESSION_REVOKED_AUTOMATICALLY",
  "oldData": {
    "status": "ACTIVE"
  },
  "newData": {
    "status": "REVOKED"
  },
  "userId": null,
  "ip": null,
  "createdAt": "2026-07-03T18:00:00.000Z"
}
```

## Regras de Negócio

<Warning>
  * O AuditLog é **append-only** — registros são permanentes.
  * O `userId` identifica quem disparou a ação, mesmo que tenha sido uma operação automática (nesse caso, pode ser um usuário de sistema).
  * `type = SYSTEM_LOG` pode ter `userId = null` quando não houver ator humano ou usuário de sistema associado.
  * `domain` e `resource` são catálogos fixos. `action` é aberta e não deve virar enum.
</Warning>

## Dados Capturados

| Dado                                 | Propósito                                                             |
| ------------------------------------ | --------------------------------------------------------------------- |
| `type`                               | Classifica se o registro vem da aplicação ou de uma rotina do sistema |
| `domain` / `resource` / `resourceId` | Identifica exatamente a instância auditada                            |
| `action`                             | Nomeia livremente a ação de negócio registrada                        |
| `oldData` / `newData`                | Permite reconstruir o estado da entidade em qualquer ponto no tempo   |
| `userId`                             | Identifica o responsável pela mutação                                 |
| `userAgent`                          | Identifica o cliente utilizado (browser, app, API)                    |
| `ip`                                 | Identifica a origem da requisição                                     |
| `createdAt`                          | Timestamp preciso da mutação                                          |

<Tip>
  O AuditLog pode ser utilizado para gerar relatórios de atividade, detectar padrões anômalos e atender solicitações de auditoria externa.
</Tip>