Release v4928.1.4.2 stable

docs/CLIENTFLOW_V4926_8_2_NOTES.md

@@ -0,0 +1,52 @@
+# ClientFlow v4926.8.2
+
+## Objetivo
+
+Evitar que uma oportunidade associe/importa um orçamento Jasmin antigo, fechado, convertido ou anulado quando existe um orçamento/proforma aberto mais recente para o mesmo cliente fiscal.
+
+## Alterações
+
+- Classificação de ciclo de vida dos documentos Jasmin a partir de `payload.record`:
+  - `documentStatusDescription`
+  - `documentStatus`
+  - `documentLineStatusDescription`
+  - `statusWasCompleted`
+  - `isDeleted`
+  - `isDraft`
+- Candidatos Jasmin agora são ordenados por:
+  1. aberto/válido primeiro;
+  2. quotation/proforma antes de invoice;
+  3. data/série mais recente;
+  4. score de match fiscal.
+- Documentos fechados/convertidos/anulados aparecem apenas como auditoria e o botão fica desativado.
+- `link_and_import_jasmin_candidate_async` rejeita importação de candidato não aberto/válido.
+- Novo botão na UI: **Sincronizar Jasmin** para buscar documentos recentes antes de escolher candidato.
+- Novo botão na UI: **Substituir atual**, para trocar um orçamento/proforma importado por engano por um candidato aberto mais recente.
+- Novo script de inspeção:
+  - `scripts/inspect_jasmin_candidates_for_opportunity.py`
+- Novo script de reparação:
+  - `scripts/replace_jasmin_document_for_opportunity.py`
+
+## Operação segura
+
+Para diagnosticar:
+
+```bash
+PYTHONPATH=. python scripts/inspect_jasmin_candidates_for_opportunity.py \
+  --opportunity-id <OPPORTUNITY_ID> \
+  --sync \
+  --days 30
+```
+
+Para substituir por um candidato válido:
+
+```bash
+PYTHONPATH=. python scripts/replace_jasmin_document_for_opportunity.py \
+  --opportunity-id <OPPORTUNITY_ID> \
+  --item-id <RECONCILIATION_ITEM_ID> \
+  --dry-run
+
+PYTHONPATH=. python scripts/replace_jasmin_document_for_opportunity.py \
+  --opportunity-id <OPPORTUNITY_ID> \
+  --item-id <RECONCILIATION_ITEM_ID>
+```