Pular para conteúdo

Notas e histórico do negócio

O que é

O registro do que já aconteceu com um negocio: um diário de bordo (Notas) e uma timeline de movimentações (Histórico). São as abas "Notas" e "Histórico" do drawer de detalhe do card (CardDetalheSheet), aberto ao clicar no nome do card no kanban-comercial — ao lado da aba "Detalhe" e do atalho "Abrir perfil do contato" (leva à ficha-do-contato).

Como funciona

Notas

  • Append-only: só adiciona, nunca edita/apaga uma nota existente.
  • Autor é sempre o usuário logado (req.user.id no backend — o corpo da requisição nunca dita quem escreveu).
  • Mostradas mais recente primeiro; o número de notas aparece no título da aba ("Notas (N)").
  • Algumas ações do card forçam uma nota: Pendenciar (nota obrigatória, ver pendencia) e Arquivar (motivo obrigatório, ver arquivar-negocio) também entram nesse mesmo registro de notas do negócio.
  • GET/POST /v2/comercial/negocios/:id/notas.

Histórico (timeline)

  • Lista as movimentações de etapa/pipe do negócio, mais recente primeiro — cada linha tem um TipoMovimentacao: manual (via mover-negocio), automatica (via evento de domínio), regressao, arquivamento, reatribuicao, pendencia, despendencia. É a materialização, por negócio, do princípio board-read-only-orientado-a-eventos: cada entrada é rastreável a uma ação real ou a um evento de domínio, nunca a um arrasto de tela.
  • GET /v2/comercial/negocios/:id/historico.

Regras de negócio

⚠️ A documentar. Esta tela ainda não tem as regras de negócio levantadas do código.

O que entra aqui: invariante (o que nunca pode acontecer), permissão (quem pode fazer o quê), bloqueio (o que impede a ação e a mensagem que o usuário vê), cálculo (fórmula e arredondamento) e efeito colateral (o que mais muda quando isso acontece).

Regra só entra aqui com origem no código — arquivo e linha. Regra que alguém "acha que é assim" é pior que seção vazia, porque vira decisão de produto baseada em memória.

Onde vive no código

  • Front: pages/comercial/kanban/components/CardDetalheSheet.tsx (AbaHistorico, AbaNotas), domains/comercial/negocios/hooks/{use-historico-negocio,use-notas-negocio}.ts.
  • API: rotas :id/historico e :id/notas em negocios.controller.ts.
  • DB: tabelas negocio_movimentacao (append-only) e negocio_nota.

Relacionado

kanban-comercial · negocio · pendencia · arquivar-negocio · mover-negocio · board-read-only-orientado-a-eventos · ficha-do-contato · comercial

Histórico

  • 2026-07-10: primeira ingestão, a partir do código atual (CardDetalheSheet.tsx + controller).