clientflow_backend/docs/CLIENTFLOW_V3_CUSTOMERS_DOCUMENTS.md

ClientFlow v3 — Clientes, documentos e envios

Esta versão separa responsabilidades para evitar que a página da oportunidade fique demasiado pesada.

Princípio de UI

• Clientes: dados fiscais, NIF, morada, contactos e ligação Jasmin.
• Oportunidades: estado da potencial compra, produtos, documentos associados e envios.
• Documentos: orçamentos e faturas em commercial_documents.
• Envios: registos Packlink em shipments.

Páginas principais

/customers

Lista clientes locais normalizados, com pesquisa por nome, NIF, email, telefone ou jasmin_customer_party_key.

Permite criar uma ficha mínima de cliente com nome e NIF.

/customers/{id}

Ficha completa de cliente:

• nome fiscal;
• NIF;
• email;
• telefone;
• morada fiscal;
• código postal;
• cidade;
• país;
• Jasmin customerPartyKey;
• Jasmin ID;
• oportunidades associadas;
• documentos Jasmin;
• envios Packlink.

/opportunities/{id}

A oportunidade mantém apenas um resumo compacto do cliente e um seletor para associar uma ficha local.

Botões operacionais:

• Criar orçamento: cria sempre um novo orçamento Jasmin.
• Converter em fatura: converte o orçamento ativo/mais recente em fatura.

Modelo de dados

Novas tabelas/colunas usadas nesta versão:

• customers
• commercial_documents
• commercial_document_lines
• shipments
• opportunities.local_customer_id

O campo antigo opportunities.customer_id é mantido para compatibilidade com dados legados/Chatwoot. A ligação nova e normalizada usa opportunities.local_customer_id.

Fluxo Jasmin validado

1. Cliente associado à oportunidade.
2. find_or_create_customer_for_opportunity() usa primeiro o cliente local.
3. NIF é enviado para Jasmin sem prefixo PT.
4. Se o cliente não existir no Jasmin, cria cliente com partyKey = CF{NIF}.
5. Cria orçamento ORC / ORC2026.
6. Para faturar, chama POST /billing/invoices/fromQuotation/{quotationId} com body {}.

Regras importantes

• Não enviar electronicMail nem telephone vazios para Jasmin.
• OData Jasmin deve usar $top <= 100.
• Packlink usa API key no header Authorization, sem Bearer.
• Para cotação Packlink em Portugal, normalizar CP para 4 dígitos.

Estratégia de refactor

Esta v3 ainda não reescreve o admin_dashboard.py totalmente. A prioridade foi criar a camada de domínio e a navegação operacional correta. O próximo passo recomendado é extrair progressivamente:

• app/admin_ui/pages/customers.py
• app/admin_ui/pages/opportunities.py
• app/admin_ui/pages/integrations.py
• app/admin_ui/components.py