Release v4928.1.4.2 stable

2026-06-09 22:55:58 +01:00
commit 6445044ac6
280 changed files with 41775 additions and 0 deletions
--- a/docs/CLIENTFLOW_V492_EXTERNAL_API_SYNC.md
+++ b/docs/CLIENTFLOW_V492_EXTERNAL_API_SYNC.md
@@ -0,0 +1,130 @@
+# ClientFlow v4.9.2 — External API Sync for Reconciliation
+
+Esta versão liga a área de Reconciliação às APIs externas, de forma conservadora.
+
+## Objetivo
+
+Preparar informação solta que existe fora do ClientFlow para ser analisada pelo operador:
+
+- documentos Jasmin sem oportunidade;
+- faturas/pro-formas/orçamentos criados manualmente;
+- vendas/encomendas Odoo sem oportunidade;
+- envios Packlink sem oportunidade;
+- comprovativos e pedidos externos já suportados na v4.9.1.
+
+## Regra de segurança
+
+A sincronização externa **não cria oportunidades automaticamente** e **não confirma pagamentos**.
+
+Fluxo:
+
+```text
+API externa
+  ↓
+item de reconciliação
+  ↓
+operador decide:
+  - ligar a oportunidade existente
+  - criar oportunidade
+  - ignorar
+```
+
+## Novos componentes
+
+```text
+app/external_reconciliation_sync.py
+scripts/sync_external_reconciliation.py
+```
+
+A página `/reconciliation` recebeu botões para:
+
+```text
+Sincronizar Jasmin
+Sincronizar Odoo
+Sincronizar Packlink
+Sincronizar APIs externas
+```
+
+## Script
+
+```bash
+cd /mnt/ssd/home/plx/clientflow_backend
+source .venv/bin/activate 2>/dev/null || true
+
+PYTHONPATH=. python scripts/sync_external_reconciliation.py --all
+PYTHONPATH=. python scripts/sync_external_reconciliation.py --jasmin --limit 100
+PYTHONPATH=. python scripts/sync_external_reconciliation.py --odoo --days 90
+PYTHONPATH=. python scripts/sync_external_reconciliation.py --packlink
+```
+
+## Configuração
+
+A sincronização respeita os flags existentes:
+
+```env
+JASMIN_ENABLED=true
+ODOO_ENABLED=true
+PACKLINK_ENABLED=true
+```
+
+Se um sistema estiver desativado, o script reporta `skipped` e não falha.
+
+## Frequência sugerida
+
+```text
+Jasmin documentos       15 min
+Odoo vendas             15-30 min
+Packlink envios         30 min
+Reconciliação completa  1 vez por dia
+```
+
+Exemplo systemd timer para execução geral:
+
+```ini
+[Unit]
+Description=ClientFlow external reconciliation sync
+
+[Service]
+Type=oneshot
+WorkingDirectory=/mnt/ssd/home/plx/clientflow_backend
+Environment=PYTHONPATH=.
+ExecStart=/mnt/ssd/home/plx/clientflow_backend/.venv/bin/python scripts/sync_external_reconciliation.py --all
+```
+
+Timer:
+
+```ini
+[Unit]
+Description=Run ClientFlow external reconciliation sync every 15 minutes
+
+[Timer]
+OnBootSec=2min
+OnUnitActiveSec=15min
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+```
+
+## O que não faz
+
+```text
+Não apaga documentos.
+Não substitui orçamentos.
+Não emite faturas.
+Não confirma pagamentos.
+Não fecha oportunidades.
+Não cria oportunidades automaticamente.
+```
+
+## Validação
+
+Depois do deploy:
+
+```bash
+PYTHONPATH=. python -m compileall app scripts tests
+PYTHONPATH=. pytest -q
+PYTHONPATH=. python scripts/sync_external_reconciliation.py --all
+```
+
+Depois abrir `/reconciliation` e confirmar os candidatos.