Trilha de Auditoria
A trilha de auditoria registra automaticamente toda acao relevante realizada no sistema. Cada criacao, edicao ou exclusao de dados gera um registro imutavel que pode ser consultado a qualquer momento para fins de compliance, investigacao e transparencia.
Por que Auditar?
A auditoria e essencial para:
- Compliance — Atender requisitos de LGPD, GDPR e normas contabeis (IFRS, USALI)
- Seguranca — Detectar acessos indevidos ou acoes suspeitas
- Investigacao — Rastrear quem fez o que e quando em caso de incidentes
- Transparencia — Dar visibilidade a gestores sobre acoes da equipe
- Reversao — Entender o estado anterior de um registro antes de uma alteracao
O que e Registrado
Toda mutacao (criacao, atualizacao ou exclusao) em entidades de negocio gera um registro de auditoria. Alguns exemplos:
| Acao | Entidade | Exemplo |
|---|---|---|
| CREATE | Reserva | ”Usuario Maria criou a reserva #RES-2026-001847” |
| UPDATE | Hospede | ”Usuario Joao atualizou o telefone do hospede Carlos Silva” |
| DELETE | Lancamento | ”Usuario Ana excluiu o lancamento contabil #LC-00412” |
| REVERSE | Movimentacao | ”Usuario Pedro estornou a movimentacao de caixa #MV-00198” |
| READ | Tenant (N2) | “Superuser N2 acessou dados do tenant Hotel Solar” |
Nota: Leituras normais (GET) nao sao registradas para evitar volume excessivo. A excecao sao acessos de suporte (N2), que registram toda leitura cross-tenant.
Campos do Registro
Cada entrada na trilha de auditoria contem:
| Campo | Descricao | Exemplo |
|---|---|---|
id | Identificador unico do registro (UUIDv7, ordenavel por tempo) | 019...abc |
tenantId | Tenant onde a acao ocorreu (nulo para acoes cross-tenant N2) | tenant-uuid |
tableName | Nome da tabela/entidade afetada | reservations |
recordId | ID do registro criado, editado ou excluido | record-uuid |
action | Tipo da acao | CREATE, UPDATE, DELETE, REVERSE, READ |
userId | ID do usuario que realizou a acao | user-uuid |
superuserLevel | Se a acao foi de um superuser: n1 ou n2 | n1 |
origin | Origem da acao | API, INTEGRATION, AUTOMATION, SYSTEM, SUPERUSER |
oldValue | Estado anterior do registro (para UPDATE e DELETE) | { "status": "pending" } |
newValue | Novo estado do registro (para CREATE e UPDATE) | { "status": "confirmed" } |
ipAddress | IP de origem da requisicao | 189.40.72.15 |
userAgent | Navegador/cliente que realizou a acao | Mozilla/5.0... |
createdAt | Data/hora exata da acao | 2026-05-26T14:30:00Z |
Protecao de Dados Pessoais (PII)
Os registros de auditoria nao armazenam dados pessoais em texto plano. Informacoes sensiveis como nomes, emails, telefones e documentos sao sanitizados antes de serem gravados:
| Dado Original | Como e Armazenado na Auditoria |
|---|---|
maria.silva@email.com | m***@email.com |
CPF: 123.456.789-00 | CPF: ***.456.***-** |
Tel: (21) 99999-1234 | Tel: (21) ****-1234 |
| Numero do cartao | Nunca registrado |
Isso garante conformidade com LGPD/GDPR sem comprometer a utilidade da trilha para investigacoes.
Imutabilidade
Registros de auditoria sao imutaveis por design:
- Nao podem ser editados, nem por administradores
- Nao podem ser excluidos, nem por superusuarios N1
- A tabela nao possui operacao UPDATE nem DELETE na API
- IDs usam UUIDv7 (ordenados por tempo), garantindo sequenciamento
Importante: A imutabilidade da trilha de auditoria e uma garantia de compliance. Mesmo em caso de exclusao de dados do tenant (LGPD), os registros de auditoria sao retidos pelo periodo legal obrigatorio com dados pessoais anonimizados.
Como Consultar
Via Interface
- Acesse Configuracoes > Trilha de Auditoria (requer papel Admin)
- Use os filtros disponiveis:
| Filtro | Descricao |
|---|---|
| Periodo | Data inicial e final |
| Usuario | Quem realizou a acao |
| Entidade | Tabela afetada (reservas, hospedes, financeiro, etc.) |
| Acao | CREATE, UPDATE, DELETE, REVERSE |
| Origem | API, Interface, Integracao, Sistema |
| Registro | ID especifico do registro afetado |
- Clique em uma linha para expandir os detalhes (valores anteriores e novos)
Via API
GET /api/audit-logs?tableName=reservations&action=UPDATE&from=2026-05-01&to=2026-05-31
Authorization: Bearer <token>Origens das Acoes
| Origem | Descricao |
|---|---|
API | Acao realizada via interface web (dashboard) |
INTEGRATION | Acao originada por integracao via chave de API |
AUTOMATION | Acao automatica do sistema (ex: no-show automatico, depreciacao programada) |
SYSTEM | Operacao interna do sistema (ex: seed de dados, migracoes) |
SUPERUSER | Acao de um superuser N1 ou N2 |
Casos de Uso Comuns
Quem cancelou uma reserva?
Filtre por tableName = reservations, action = UPDATE, e procure por registros onde newValue.status = "cancelled". O campo userId mostra quem fez a acao e createdAt mostra quando.
Quando um usuario foi alterado?
Filtre por tableName = users e recordId = <id-do-usuario>. A trilha mostra todas as alteracoes, incluindo mudanca de papel (role).
O suporte Opero acessou meus dados?
Filtre por origin = SUPERUSER. Toda acao de N1/N2 e registrada com o campo superuserLevel preenchido.
Rastrear alteracoes financeiras
Filtre por tableName em (accrual_entries, cash_movements, accounts_payable, etc.) para ver todas as operacoes financeiras e quem as realizou.
Retencao
Os registros de auditoria sao mantidos por 5 anos (configuravel por tenant para periodos maiores). Apos o periodo de retencao, registros antigos sao arquivados.
Permissoes
| Papel | Acesso a Trilha de Auditoria |
|---|---|
| Admin / Tenant Admin | Leitura completa |
| Financeiro | Leitura de registros financeiros |
| Operacional | Sem acesso |
| POS / Fornecedores | Sem acesso |
| Superuser N1 | Leitura completa (cross-tenant) |
| Superuser N2 | Leitura (se acesso de suporte aprovado) |