sistema-de-chamados/docs/RETENTION-HEALTH.md

Retencao, observabilidade e consulta a longo prazo

Este documento resume as decisoes aplicadas agora para manter o sistema saudavel sem perder dados de negocio (tickets).

Politica de retencao (alvo)

• Tickets: sem expiracao automatica. Antes de mover para storage frio, exportar e manter copia integra; nao apagar tickets direto.
• Telemetria de maquinas (inventory/metrics): manter 90 dias.
• Alertas de postura de maquinas: manter 180 dias.
• Runs/artefatos de export de relatorios: manter 30 dias.

Estrategia: nenhuma limpeza automatica ligada. Usamos apenas monitoramento e, se necessario no futuro, GC preguicoso em handlers de alto volume ou rotinas manuais com janela de manutencao + backup.

O que foi ajustado no codigo

• Heartbeat: inventario e metrics agora sao saneados, tem hash estavel e so geram nova versao quando o hash muda (evita JSON.stringify pesado e escrita redundante).
• Hashes guardados em metadata para comparacao barata; campos volumosos (software/extended) continuam bloqueados.
• Query interna ops.healthSnapshot (Convex) para expor contagem de maquinas/heartbeats por faixa de idade; protegida por INTERNAL_HEALTH_TOKEN (cai no REPORTS_CRON_SECRET se nao setado).
• Dashboard /admin/health (Next) usa Prisma + Convex para consolidar tickets, cadastros, estado de heartbeat e a politica de retencao.
• Export/backup local de tickets: endpoint POST /api/admin/tickets/archive-local (staff) grava tickets resolvidos mais antigos que N dias em JSONL dentro de ARCHIVE_DIR (padrão ./archives). Usa exportResolvedTicketsToDisk com segredo interno (INTERNAL_HEALTH_TOKEN/REPORTS_CRON_SECRET).

Como acessar tickets antigos sem perda

• Base quente: Prisma (PostgreSQL) guarda todos os tickets; nenhuma rotina remove ou trunca tickets.
• Se um dia for preciso offload (ex.: >50k tickets):
  • Exportar em lotes (ex.: JSONL mensais) para storage frio (S3/compat).
  • Gravar um marcador de offload no DB quente (ex.: ticket_archived_at, archive_key).
  • Endpoint de leitura pode, ao nao encontrar o ticket no DB quente, baixar/consultar o arquivo frio com base no archive_key e exibir em modo somente leitura.
• Com isso, mesmo tickets muito antigos continuam consultaveis, apenas com caminho de leitura mais lento quando estiverem fora do DB principal.

Dashboard interno de saude

• Caminho: /admin/health (somente staff).
• Mostra: contagem total/abertos de tickets, cadastros (usuarios/empresas), conectividade de dispositivos (online/atencao/offline), idade do ultimo e do mais antigo heartbeat, politica de retencao.
• Protecao da query Convex: defina INTERNAL_HEALTH_TOKEN (ou reutilize REPORTS_CRON_SECRET) no ambiente do Convex e do Next. Se o token faltar ou o Convex nao responder, o card exibe aviso.

Checks operacionais sugeridos (manuais)

• Tamanho do banco do Convex: ssh -i ~/.ssh/codex_ed25519 root@154.12.253.40 "ls -lh /var/lib/docker/volumes/sistema_convex_data/_data/db.sqlite3"
• Memoria do Convex: ssh -i ~/.ssh/codex_ed25519 root@154.12.253.40 "docker stats --no-stream | grep convex"
• Alvos: <100-200 MB para o SQLite do Convex e <5 GB de RAM. Acima disso, abrir janela curta, fazer backup e avaliar limpeza ou arquivamento pontual.

Estado atual e proximos passos

• Cron de limpeza segue desativado. Prioridade: monitorar 2-4 semanas para validar estabilidade pos-correcoes.
• Se o volume crescer: habilitar GC preguicoso em handlers de alto volume (ex.: heartbeat) com limites pequenos, ou acionar rotina manual/HTTP para deletar apenas telemetria fora da retenao.
• Tickets permanecem integrais; qualquer offload futuro deve ser acompanhado de export completo + marcador para leitura em modo arquivo frio.