Release v4928.1.4.2 stable

docs/CLIENTFLOW_V493_JASMIN_RECENT_SYNC.md

@@ -0,0 +1,39 @@
+# ClientFlow v4.9.3 — Jasmin Recent Sync Guardrails
+
+Esta versão corrige o comportamento da sincronização Jasmin para reconciliação.
+
+## Problema corrigido
+
+Na v4.9.2, o comando:
+
+```bash
+PYTHONPATH=. python scripts/sync_external_reconciliation.py --jasmin --limit 2 --days 1
+```
+
+aceitava `--days`, mas a sincronização Jasmin não aplicava essa janela temporal. Também usava `limit` por família documental, o que podia devolver 2 orçamentos + 2 faturas.
+
+Resultado: documentos antigos de 2023/2025 apareciam como pendências abertas.
+
+## Comportamento novo
+
+- `--days` é aplicado ao sync Jasmin.
+- A API Jasmin é chamada com `$orderby=documentDate desc` e `$filter=documentDate ge <data>` quando possível.
+- Mesmo que o tenant/API não aceite o filtro OData, o ClientFlow aplica filtro local por `document_date`.
+- `--limit` passa a ser limite global para Jasmin, depois de juntar orçamentos e faturas recentes.
+- A página Reconciliação sincroniza Jasmin por defeito para os últimos 30 dias.
+
+## Limpeza de itens antigos já criados
+
+A v4.9.2 pode já ter criado candidatos antigos. Usar primeiro dry-run:
+
+```bash
+PYTHONPATH=. python scripts/cleanup_stale_reconciliation_items.py --jasmin --days 30
+```
+
+Se a lista estiver correta:
+
+```bash
+PYTHONPATH=. python scripts/cleanup_stale_reconciliation_items.py --jasmin --days 30 --apply
+```
+
+Isto marca os candidatos antigos como `ignored`. Não apaga documentos, oportunidades, mensagens ou registos externos.