clientflow_backend/docs/CLIENTFLOW_V32_NOTES.md

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 é:

[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:

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.