Release v4928.1.4.2 stable

docs/CLIENTFLOW_V480_OPERATIONAL_AUTOMATION_AUDIT_RECOVERY.md

@@ -0,0 +1,109 @@
+# 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:
+
+```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:
+
+```bash
+python scripts/recover_stale_outbox.py
+```
+
+## Auditoria operacional
+
+Novo módulo:
+
+```text
+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
+
+```bash
+PYTHONPATH=. python -m compileall app scripts tests
+PYTHONPATH=. pytest -q
+```