Release v4928.1.4.2 stable

docs/CLIENTFLOW_V491_OPERATIONAL_RECONCILIATION.md

@@ -0,0 +1,124 @@
+# ClientFlow v4.9.1 — Operational Reconciliation & External Intake
+
+Esta versão adiciona uma área de **Reconciliação** para organizar informação que existe fora do ClientFlow antes de a transformar em processo comercial.
+
+## Objetivo
+
+O ClientFlow passa a preparar informação solta de:
+
+- documentos Jasmin criados fora do ClientFlow;
+- faturas/orçamentos sem oportunidade;
+- comprovativos de pagamento recebidos manualmente;
+- pedidos vindos de WhatsApp, telefone, email direto ou presencial;
+- futuras vendas Odoo sem oportunidade.
+
+A regra principal é:
+
+```text
+Sincronizar/detetar automaticamente.
+Criar candidato de reconciliação.
+Operador confirma ligar, criar oportunidade ou ignorar.
+```
+
+## O que mudou
+
+### Nova página
+
+```text
+/reconciliation
+/reconciliacao
+```
+
+A página mostra:
+
+- itens abertos de reconciliação;
+- documentos sem ligação;
+- comprovativos por associar;
+- ações para criar oportunidade, ligar oportunidade existente ou ignorar.
+
+### Novas tabelas aditivas
+
+A versão cria schema adicional no arranque:
+
+```text
+reconciliation_items
+payment_proofs
+```
+
+É uma alteração aditiva: não remove nem altera dados existentes.
+
+### Entrada manual externa
+
+A página permite registar pedidos vindos de canais fora do Chatwoot:
+
+```text
+WhatsApp
+Telefone
+Email direto
+Presencial
+Outro
+```
+
+Ao registar, o sistema cria:
+
+- oportunidade;
+- task com a próxima ação;
+- evento de timeline.
+
+Não cria IDs falsos de Chatwoot.
+
+### Comprovativos de pagamento
+
+Um comprovativo pode ser guardado e ligado a uma oportunidade.
+
+Importante:
+
+```text
+Comprovativo recebido não confirma pagamento.
+```
+
+Quando está ligado a uma oportunidade, cria task `CONFIRM_PAYMENT` para validação humana.
+
+### Sincronização local
+
+Script novo:
+
+```bash
+PYTHONPATH=. python scripts/sync_reconciliation_candidates.py
+```
+
+Ele procura documentos Jasmin locais em `commercial_documents` sem `opportunity_id` e cria candidatos de reconciliação.
+
+## Fluxo operacional recomendado
+
+```text
+Documento/Comprovativo/Pedido externo
+        ↓
+Reconciliação
+        ↓
+Operador decide:
+  - ligar a oportunidade existente
+  - criar oportunidade
+  - ignorar
+        ↓
+ClientFlow cria/atualiza oportunidade e task
+```
+
+## O que esta versão não faz
+
+- Não confirma pagamentos automaticamente.
+- Não emite faturas automaticamente.
+- Não apaga nem substitui documentos Jasmin.
+- Não fecha oportunidades sozinha.
+- Não usa LLM para reorganizar sem confirmação humana.
+
+## Validação
+
+```bash
+PYTHONPATH=. python -m compileall app scripts tests
+PYTHONPATH=. pytest -q
+```
+
+## Rollback
+
+O código pode ser revertido normalmente. As tabelas novas são aditivas e podem ficar sem afetar o fluxo antigo.