Auditoria de dados (AUD-01)

Trilha de auditoria CUD nas APIs Java do eCosif via Hibernate Event Listeners.
Milestone: #6 · Plano: AUD-01 · Branch: feature/AUD-01-auditoria-dados

1. Objetivo

Registrar quem alterou o quê, quando e (quando configurado) o diff de campos, com:

1. Nível configurável por tabela (OFF / OPS / DIFF)
2. Opt-in via sys_audit_config (tabela ausente ou OFF → não audita)
3. Operações I / U / D
4. Em DIFF, JSON [{column, old, new}]

FULL (snapshot completo) fica fora desta entrega (PII/volume).

2. Decisões de arquitetura

Tema	Decisão
Captura	Hibernate PostInsert / PostUpdate / PostDelete
Onde	Lib ecosif-database (io.ecosif.database.audit)
DDL	Somente Flyway — sem trigger / função PL/pgSQL
Envers	Não utilizado
Transação	Evento na mesma TX do negócio
Recursão	Entidades sys_audit_* ignoradas
Ator	SecurityContext / LocalUser (reflexão) + ecosif.audit.service-name
Default	Sem linha em config ou level=OFF → silêncio

Por que não trigger?

• Política unificada em Java (diff, exclusão de password, ator da sessão).
• Evita divergência entre ambientes e lógica duplicada no banco.
• SQL nativo / JdbcTemplate / Python não são capturados — limite explícito.

vs ct_histo_*

	sys_audit_*	ct_histo_*
Propósito	Auditoria de cadastro/config (quem mudou)	Histórico/arquivo contábil de negócio
Mecanismo	Hibernate listeners	Fluxos contábeis existentes
Substitui?	Não	Não

3. Modelo de dados

sys_audit_config

Coluna	Papel
table_name	Nome físico (UK)
level	OFF | OPS | DIFF | FULL
ops	Subconjunto de IUD (ex.: IU)
excluded_columns	CSV (ex.: password)
enabled	Soft-off sem apagar config

sys_audit_event

Coluna	Papel
occurred_at	Instantâneo
table_name / operation	Tabela e I/U/D
entity_pk	PK como string
empresa / filial	Se presentes na entidade
actor_username / actor_user_id	Ator autenticado
service_name	Ex.: ecosif-masterdata
changes	JSONB (só DIFF/FULL)

Índices: (table_name, occurred_at), (empresa, filial, occurred_at).

Flyway

Versão	Conteúdo
V0.7.00.11	DDL sys_audit_config + sys_audit_event
V0.7.00.12	Seed Onda 1 (6 tabelas piloto)
V0.7.00.13	Seed Onda 2 (inventário DIFF restante)
V0.7.00.14	Seed OPS ct_lote/ct_documentos (disabled; Onda 3 cancelada nesta entrega — #48)

Canônico: flyway-ecosif/sql/. Espelho: ecosif-auth/.../db/migration/.

4. Níveis

Nível	Grava
OFF	Nada
OPS	Quem, quando, tabela, op, PK, empresa/filial
DIFF	OPS + changes
FULL	Fora de escopo nesta entrega

5. Runtime Java

CRUD JPA
  → PostInsert/Update/Delete
  → AuditConfigCache (TTL)
  → se ativo e ops permite
  → AuditDiffService (se DIFF)
  → AuditActorResolver (SecurityContext)
  → persist AuditEvent (mesma Session/TX)

Pacote

io.ecosif.database.audit — enums, model, repository, AuditHibernateEventListener, AuditListenerRegistrar, cache, diff, JsonbStringType, auto-config ecosif.audit.*.

Properties

ecosif:
  audit:
    enabled: true
    service-name: ecosif-masterdata   # ou ecosif-auth
    config-cache-ttl-seconds: 60

Desligar sem redeploy de schema: ecosif.audit.enabled=false ou UPDATE sys_audit_config SET enabled=false.

Wiring por serviço

Serviço	Status	Nota
ecosif-masterdata	Ativo	@EntityScan + repos audit + API /audit/*
ecosif-auth	Ativo	EntityScan só audit.model (evita conflito User local)
ecosif-moviments	Wiring preparado	Seed OPS permanece enabled=false (Onda 3 cancelada nesta entrega — #48)
Demais APIs	Sob demanda	Mesmo padrão do masterdata

6. Inventário (política)

DIFF (Ondas 1–2)

gr_empresa, gr_filial, gr_user (excl. password), gr_filial_usuario, gr_grupo, gr_grupo_usuario, gr_rotina, gr_rotina_grupo, roles, businessaccount, ct_tipo_fundo, ct_conta_patrimonio, ct_calendario, ct_plano, ct_historico, ct_plano_referencial, ct_plano_referencial_detalhes, ct_plano_referencial_equivalencias, ct_padronizado, ct_padronizado_dados, ct_controle, ct_controle_cosif, ct_parametro_fundo, ct_encerramento, ct_encerramento_config, ct_demostracao, ct_demostracao_dados

OPS (Onda 3 — cancelada nesta entrega)

ct_lote, ct_documentos: seed V0.7.00.14 com enabled=false. No-go para volume em produção nesta release; reabrir em plano futuro se necessário. ct_lancamento / saldos só com aprovação explícita.

OFF (nunca auditar nesta entrega)

ct_histo_*, *_tmp / temp_*, gr_cidades, ct_retorna_lancto, preferencias_usuario, sys_audit_*.

7. Limites (Java-only)

Não gera evento:

• Python (ecosif-automations / compliance / IPL)
• SQL nativo / JdbcTemplate / procedures
• Leituras (SELECT)
• Soft-delete “universal” (só o que o JPA emitir como delete/update)

8. Segurança e LGPD

• password e colunas em excluded_columns nunca entram em changes.
• Não logar JWT/senha no logger do listener.
• Fase 2 (API consulta) deve filtrar por empresa/filial e role admin.

9. Operação

1. Aplicar Flyway até a versão desejada.
2. Confirmar log: AUD-01: listeners Hibernate de auditoria registrados.
3. Amostrar: SELECT * FROM sys_audit_event ORDER BY occurred_at DESC LIMIT 20.
4. Homolog Onda 1: checklist.
5. API admin (masterdata): GET /audit/events, GET|POST /audit/config, DELETE /audit/config/{id}.
6. UI: Angular /#/audit-data (AdminGuard) — AUD-01.12.
7. Testes: teste-aud01.md · ./scripts/test-aud01.sh · Playwright e2e-auditoria-dados.md.

Invalidar cache de config: reinício da app, TTL, ou alteração via API admin (invalida cache).

Cache e PostInsert IDENTITY

AuditConfigCache carrega configs com FlushModeType.COMMIT para não disparar auto-flush no meio de insert IDENTITY (HHH000099).

10. Roadmap do epic

Issue	Entrega	Status (2026-08-26)
#39–#42	Onda 0 — DDL + lib + wiring masterdata	concluído
#43–#44	Onda 1 seed + wiring auth	concluído
#45	Homolog Onda 1 (QA + evidência automatizada)	concluído
#46	Onda 2 seed DIFF	concluído
#47	Documentação de arquitetura	concluído
#48	OPS lote/documento (opcional)	cancelado (no-go nesta entrega; seed disabled)
#49	API admin consulta/config	concluído
#50	UI Angular /audit-data + E2E Playwright	concluído

Artefato alinhado: 0.7.08.202608252 (database, masterdata, auth, moviments, angular).

Referências

• Plano: .internal_docs/tasks-plan/done/20260825_AUD-01_auditoria-dados-hibernate.md
• Flyway notes: V0.7.00.11, V0.7.00.12, V0.7.00.13
• Auth wiring: ecosif-auth/docs/release-notes/AUD-01.6-wiring-auditoria-auth.md
• Release: 0.7.08.202608252