# Etapa 17 — Área Tenant: Vendas e Financeiro

## Contexto do projeto

Continuação do frontend do **SeConectai Vendas**. Já existem: setup,
design system, autenticação/tema, layout/navegação, área master
completa, e clientes/produtos no painel do tenant. Esta é a etapa mais
crítica do painel do tenant — o fluxo de vendas e o controle financeiro
— consumindo os endpoints da Etapa 6 do backend.

## Objetivo desta etapa

Registro completo de vendas (com itens e parcelas), listagem e ação
sobre recebimentos, e os dashboards financeiros/semana-mês.

## Tarefas

1. **`/app/vendas`**
   - Listagem (`Table`) com filtro por status (`orcamento`,
     `confirmada`, `concluida`, `cancelada`), por cliente, por período
     de `data_venda`, paginação.
   - Colunas/cards: número da venda, cliente, valor total, status
     (`StatusPill`), data.
   - Botão "Nova venda" → `/app/vendas/nova`.

2. **`/app/vendas/nova`** — a tela mais complexa do projeto
   - Seleção de cliente (`Select` com busca, puxando de `/app/clientes`)
     — se o cliente não existir ainda, oferecer atalho para cadastrar
     rápido sem sair do fluxo (modal com o formulário mínimo de
     cliente).
   - Lista de itens da venda: adicionar produto/serviço (busca por
     nome/SKU), quantidade, valor unitário (pré-preenchido do catálogo,
     editável para casos de desconto pontual — deixar claro visualmente
     quando o valor foi alterado do catálogo). Cálculo automático do
     subtotal por item e do total geral, considerando o campo de
     desconto geral da venda.
   - Definição das parcelas: opção "gerar parcelas automaticamente"
     (informar número de parcelas e primeira data de vencimento, o
     sistema calcula o resto) ou "definir manualmente" (lista editável
     de valor+vencimento por parcela). Validação em tempo real: soma das
     parcelas precisa bater com o valor total da venda antes de permitir
     salvar (mostrar a diferença, se houver, de forma clara).
   - Layout responsivo: no desktop, itens da venda e resumo/parcelas
     podem ficar lado a lado (2 colunas); no mobile, tudo empilhado com
     o resumo total sempre visível (ex: barra fixa no rodapé mostrando o
     total atualizado enquanto o usuário edita os itens).
   - Salvar como `orcamento` ou já como `confirmada` (duas ações
     distintas, não um único botão "Salvar").

3. **`/app/vendas/:id`**
   - Detalhe com `Tabs`: Itens (somente leitura se a venda estiver
     `confirmada`/`concluida`, editável se `orcamento`), Parcelas (lista
     com status e ação de marcar como paga por parcela), Histórico
     (mudanças de status, se o backend expuser isso via `audit_logs`).
   - Ações de topo: mudar status (confirmar orçamento, cancelar venda —
     com confirmação explícita explicando que isso cancela as parcelas
     pendentes associadas).

4. **`/app/recebimentos`**
   - Listagem de parcelas (`sale_payments`) via a view/endpoint do
     backend, com filtro por status, por cliente, por período de
     vencimento. Parcelas atrasadas destacadas visualmente (cor de
     alerta) e, se possível, ordenadas por padrão com as mais urgentes
     no topo.
   - Ação "Marcar como pago" por linha, com seleção de forma de
     pagamento — se o backend suportar ação em lote, oferecer seleção
     múltipla de linhas com ação "Marcar selecionadas como pagas".

5. **Dashboards financeiros (complementando `/app/dashboard` da Etapa
   16, se ainda não coberto)**
   - Gráfico de resumo semanal e mensal lado a lado ou alternável (toggle
     de período), usando as views `vw_resumo_vendas_semanal` /
     `vw_resumo_vendas_mensal` do backend.
   - Bloco "Financeiro": total recebido, total a receber, total
     atrasado, com cores semânticas consistentes com o `StatusPill`.

## Critérios de aceite

- [ ] Criar venda completa (cliente + itens + parcelas) funciona ponta a
      ponta e reflete corretamente no backend
- [ ] Validação de soma das parcelas vs. valor total impede salvar
      quando não bate, com mensagem clara da diferença
- [ ] Cadastro rápido de cliente dentro do fluxo de nova venda funciona
      sem perder o que já foi preenchido na venda
- [ ] Venda confirmada não permite editar itens/valores na tela de
      detalhe (reflete a regra do backend)
- [ ] Cancelar venda pede confirmação e reflete o cancelamento das
      parcelas pendentes na tela de recebimentos
- [ ] Marcar parcela como paga atualiza corretamente o dashboard
      financeiro sem precisar recarregar a página manualmente
      (invalidação de cache do React Query)
- [ ] Parcelas atrasadas visualmente destacadas na listagem de
      recebimentos
- [ ] Barra de total fixa no mobile durante a montagem de uma venda
      funciona corretamente e não sobrepõe conteúdo importante
- [ ] Todas as telas testadas em 375px, 768px e 1280px, com atenção
      especial à tela de nova venda (a mais densa de informação)