clientflow_backend/docs/CLIENTFLOW_V480_OPERATIONAL_AUTOMATION_AUDIT_RECOVERY.md

ClientFlow v4.8.0 — Operational Automation, Audit & Recovery

Esta versão avança de uma UI HTMX estável para segurança operacional: recuperação de outbox presa, auditoria de ações manuais e confirmações para ações sensíveis.

Objetivo

• Recuperar ou expor itens de outbox presos em processing.
• Registar ações críticas do operador como eventos auditáveis.
• Evitar cliques acidentais em ações sensíveis.
• Melhorar /system/health e /operations com métricas operacionais reais.

Outbox stale recovery

Novas funções:

• outbox_stale_minutes()
• recover_stale_processing_outbox()

Novos ENV:

OUTBOX_STALE_PROCESSING_MINUTES=30
OUTBOX_STALE_RECOVERY_MODE=manual_only
OUTBOX_RECOVER_STALE_BEFORE_PROCESS=true

Modos disponíveis:

• manual_only: marca processing antigo como stale para decisão humana.
• mark_failed: marca como failed com erro explicativo.
• retry_pending: devolve para pending e incrementa retry.

O worker scripts/process_outbox.py chama a recuperação antes de fazer claim de novos itens, por defeito em modo manual_only.

Também foi criado:

python scripts/recover_stale_outbox.py

Auditoria operacional

Novo módulo:

app/operator_audit_service.py

Regista eventos operator_action em business_events sem criar nova tabela. Quando existe task_id, também espelha em task_events.

Ações auditadas:

• concluir task manualmente
• concluir task com nota
• ignorar task
• reclassificar task
• reprocessar outbox
• marcar outbox como sent/failed/ignored
• recuperação de outbox stale

Confirmações para ações sensíveis

Foram adicionados hx-confirm nas ações HTMX sensíveis:

• concluir task
• ignorar task
• reclassificar task
• reprocessar outbox
• ignorar outbox
• marcar outbox como failed

Saúde operacional

/system/health passa a destacar:

• tasks pendentes
• tasks concluídas 24h
• tasks auto-completed 24h
• tasks com associação ambígua
• outbox processing
• outbox stale
• outbox failed/blocked/stale
• ações do operador nas últimas 24h
• configuração de stale recovery

Operations

O Centro de trabalho ganha filtros de foco operacional:

• A fazer
• Bloqueadas
• Ambíguas
• Atrasadas
• Vendas
• Financeiro
• Logística
• Revisão
• Concluídas hoje

Base de dados

Não há nova tabela obrigatória. A auditoria usa business_events e task_events, já existentes.

Validação

PYTHONPATH=. python -m compileall app scripts tests
PYTHONPATH=. pytest -q