Release v4928.1.4.2 stable

docs/CLIENTFLOW_V32_NOTES.md

@@ -0,0 +1,78 @@
+# ClientFlow v3.2 — HTMX, validações e operação sem terminal
+
+Esta versão é incremental em cima da v3.1. O objetivo é tornar o fluxo Jasmin/Packlink mais visível e operável pela UI, sem reescrever o dashboard inteiro.
+
+## Principais alterações
+
+### HTMX progressivo na oportunidade
+
+A página de oportunidade passa a usar HTMX em blocos específicos:
+
+- cartão **Documentos Jasmin**;
+- cartão **Produtos**;
+- ações de outbox associadas à oportunidade.
+
+O comportamento esperado é:
+
+```text
+[Criar orçamento]
+→ cria item pending na outbox
+→ atualiza apenas o cartão Documentos Jasmin
+→ mostra estado pending/sent/failed
+→ polling atualiza o cartão a cada 10 segundos
+```
+
+Isto reduz a sensação de que “não aconteceu nada” depois de clicar num botão.
+
+### Validação antes de criar orçamento
+
+Antes de criar outbox `jasmin.create_quotation`, o sistema valida:
+
+- oportunidade com cliente local associado;
+- cliente com nome fiscal;
+- cliente com NIF;
+- morada/código postal/cidade quando ainda não existe `jasmin_customer_party_key`;
+- pelo menos uma linha de produto ativa;
+- todas as linhas com `jasmin_sales_item` preenchido;
+- preços unitários maiores que zero.
+
+Se faltar algo, a UI mostra o erro diretamente no cartão Jasmin e não cria outbox inválida.
+
+### Produtos por HTMX
+
+No cartão **Produtos** da oportunidade:
+
+- adicionar produto atualiza apenas o cartão;
+- remover produto atualiza apenas o cartão;
+- total é recalculado no bloco;
+- produtos sem `jasmin_sales_item` aparecem como bloqueio visual para orçamento.
+
+### Outbox visível na oportunidade
+
+O cartão **Documentos Jasmin** mostra as ações recentes Jasmin relacionadas com a oportunidade:
+
+- `create_quotation`;
+- `convert_quotation_to_invoice`;
+- estado `pending`, `sent`, `failed`;
+- último erro;
+- botão **Reprocessar** para itens `failed`/`pending`.
+
+### Filtro de produtos sem Artigo Jasmin
+
+Em `/products`, o filtro de estado ganhou a opção:
+
+```text
+Ativos sem Artigo Jasmin
+```
+
+Serve para encontrar rapidamente produtos que ainda bloqueiam emissão de orçamento Jasmin.
+
+## Continuação recomendada
+
+Para v3.3:
+
+1. Obter PDF de orçamento/fatura.
+2. Mostrar link/número real do documento quando o GET Jasmin devolver `documentType`, `serie` e `seriesNumber`.
+3. Adicionar ações HTMX em `/integrations` para testar Jasmin/Packlink.
+4. Implementar painel de Packlink semelhante ao painel Jasmin.
+5. Refatorar `admin_dashboard.py` para `app/admin_ui/pages/` por etapas.