Import ClientFlow production v4928.1.5.132.4

RELEASE_NOTES_v4928_1_4_6.md

@@ -0,0 +1,65 @@
+# ClientFlow backend v4928.1.4.6 — auto-create Jasmin customer before quotation
+
+Hotfix/feature curta para o fluxo Jasmin `create_quotation`.
+
+## Problema
+
+O worker Jasmin passou a processar corretamente a outbox, mas falhava ao criar orçamento quando o cliente fiscal validado no ClientFlow ainda não existia como Customer no Jasmin:
+
+```text
+Jasmin error 400 em GET /salesCore/customerParties/getCustomerByCompanyTaxId/<NIF>:
+The company tax id provided does not correspond to an existing Customer.
+```
+
+## Alteração
+
+- `app/jasmin_service.py`
+  - Reconhece esse erro específico de Customer inexistente como caso esperado.
+  - Quando o cliente fiscal local está validado e tem dados mínimos, cria automaticamente o Customer no Jasmin antes do orçamento.
+  - Mantém erro explícito se faltarem dados obrigatórios para criar Customer: NIF, nome fiscal, morada, código postal ou cidade.
+  - A confirmação pós-criação por NIF deixa de bloquear o fluxo se o Jasmin ainda não indexou imediatamente o novo Customer; nesses casos usa a `partyKey` enviada e grava `confirm_warning` em metadata.
+
+## Guardrails
+
+- Outros erros Jasmin continuam a falhar normalmente.
+- Não cria Customer sem NIF.
+- Não cria Customer sem nome fiscal.
+- Não cria Customer sem morada fiscal mínima.
+- O orçamento só é criado depois de existir `jasmin_customer_party_key` local.
+
+## Validação local
+
+```bash
+python3 -m compileall -q app scripts tests
+pytest -q tests/test_v4928_1_4_6_jasmin_autocustomer_static.py
+```
+
+Resultado local:
+
+```text
+3 passed
+```
+
+## Teste recomendado em produção
+
+Reprocessar o item que falhou por Customer inexistente:
+
+```bash
+sudo -u postgres psql -d clientflow -c "
+UPDATE integration_outbox
+SET status='pending',
+    retry_count=0,
+    last_error=NULL,
+    locked_at=NULL,
+    lock_owner=NULL,
+    updated_at=now()
+WHERE id='97a36017-4ff1-4ace-a1b0-b90cc5c5cf84';
+"
+
+OUTBOX_TARGET_SYSTEM=jasmin \
+JASMIN_OUTBOX_ENABLED=true \
+OUTBOX_DRY_RUN=false \
+.venv/bin/python scripts/process_outbox.py
+```
+
+Depois confirmar se o item fica `sent` e se foi criado o documento Jasmin na oportunidade.