Files
julian 17c08e6392 chore: initial monorepo scaffold + WDS Phase 1+2 artifacts
- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24)
- apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004)
- apps/web: React 19 + Vite 8 (ESM)
- libs/shared/api-interface: Zod contract base
- Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit
- WDS artifacts:
  - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs)
  - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact)
- Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md
- AGENTS.md + README.md como entrada para devs/agentes

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-27 14:34:20 +00:00

13 KiB
Raw Permalink Blame History

Target Users — SAR (Força de Vendas)

Confirmed: 2026-05-26 Step: 07 — Target Users Primary persona: Rafael (Representante)

4 user personas no produto. Buyer persona (dono empresário) já documentado em business-customers.md — overlap real com Daniel (User Dono+IA) em empresas pequenas.


Hierarquia de prioridade no design

Prioridade Persona Justificativa
PRIMÁRIA (MVP focus) Rafael (Rep) 70-90% do volume de uso; mobile-first; SAR ganha ou perde aqui
Secundária — alto impacto Sandra (Supervisora) Influenciadora-chave da compra; demo vitrine
Secundária — alto valor Daniel (Dono) Buyer overlap; IA é diferencial declarado
Terciária — operacional Alice (Admin) Backoffice de pautas/promoções; baixo volume mas crítica para o produto rodar

Implicação de design: mobile-first para Rafael, desktop-first para Sandra/Daniel/Alice. SAR não é "responsivo um-tamanho-só" — são duas paradigmas de UI no mesmo produto.


🟢 Rafael — Representante (PERSONA PRIMÁRIA)

Quem é

  • 30-50 anos, vendedor B2B externo
  • Atende 50-200 clientes ativos numa região definida
  • Comissionado, meta mensal pesa muito na renda
  • Trabalha no carro, no posto, no escritório do cliente — raramente na frente de um computador

Cenário típico (8h da manhã, segunda)

"No carro entre 2 clientes. Quer abrir o SAR no celular e ver: meta do mês, quem visitar hoje, status do último pedido da OPENFRIOS, se já chegou pedido novo, e se a Distribuidora Norte respondeu o orçamento."

Frustrações (no legado)

  • Lança pedido pelo app e não sabe se entrou; precisa ligar pro escritório pra confirmar
  • Comissão é mistério até fechar o mês — calcula no Excel próprio "pra não confiar cego"
  • Cliente que parou de comprar passa despercebido até ele perceber sozinho
  • Atualizou número de WhatsApp do contato? Ninguém vai saber, vai esquecer
  • Não vê pipeline: tem 3 propostas em aberto e não lembra qual é mais quente
  • App lento, trava no 3G/4G ruim, perde formulário cheio

Goals

  • Bater meta (sempre — define o salário)
  • Vender mais com menos esforço administrativo
  • Não levar bronca do supervisor por algo que ele já sabia
  • Ter resposta rápida quando cliente pede algo no campo

Current solution (composição)

  • App Android JCS legado (lançamento de pedido)
  • WhatsApp pessoal (contato cliente)
  • Planilha Excel/Google Sheet própria (comissão, anotações)
  • Ligação pro escritório (confirmação)
  • Agenda física ou Google Agenda (visitas)

O que ele precisa do SAR

  1. Lançamento de pedido em < 60 segundos no celular, mesmo com sinal ruim
  2. Visão 360° do cliente — histórico, pedidos, contatos, timeline
  3. Comissão visível em tempo real (não fechamento de mês)
  4. Funil de propostas/oportunidades (kanban simples)
  5. Lista de clientes inativos com alerta proativo
  6. WhatsApp integrado (não sair do app para conversar)
  7. Agenda + check-in GPS para roteiro do dia

Implicações de design

  • Mobile-first OBRIGATÓRIO (Rafael abre o SAR no celular >80% do tempo)
  • Offline-first parcial ou ao menos resiliente — lançamento de pedido não pode perder por sinal ruim
  • Touch-friendly: botões grandes, gestos simples, sem dropdown aninhado
  • Latência percebida baixa: ack imediato do que ele faz, sync em background
  • Dark mode desejável (carro, posto à noite)

🟡 Sandra — Supervisora de Vendas

Quem é

  • 35-55 anos, gerente comercial ou gerente regional
  • Coordena 5-30 representantes
  • Reporta para dono/diretor comercial
  • Trabalha em escritório com desktop/notebook a maior parte do dia

Cenário típico (segunda 9h, na sala)

"Café na mão, abre o SAR no notebook. Quer ver: quais reps já fizeram check-in essa manhã, pedidos aguardando aprovação de desconto, top 5 clientes da carteira que não compram há 30+ dias, e se tem alguma anomalia (queda brusca de faturamento, rep parado, cliente reclamando)."

Frustrações (no legado)

  • Reps "somem" — não sabe quem está em campo, quem está enrolado em casa
  • Aprovação de desconto vira fila de WhatsApp ("preciso de R$ X de desconto pro cliente Y, libera?")
  • Não consegue ver pipeline real, só o que cada rep relata na reunião semanal
  • Quando algo dá errado em pedido (cliente bloqueado, crédito estourado), descobre tarde
  • Relatórios do legado são lentos, exigem export-Excel-pivottable
  • Não tem visão consolidada da meta da equipe em tempo real

Goals

  • Garantir que time bata meta
  • Identificar reps performando mal antes que perca venda
  • Não negligenciar clientes-chave
  • Liberar descontos com critério (não no impulso)
  • Dormir tranquila sabendo que está tudo sob controle

Current solution

  • Desktop JCS legado (relatórios + aprovações)
  • Planilhas (consolidação manual)
  • WhatsApp (aprovação de desconto, comunicação com reps)
  • Reunião semanal presencial/Zoom (90 min, suga tempo)

O que ela precisa do SAR

  1. Dashboard "apertar parafusos" diário — top 5 ações que ela precisa tomar HOJE
  2. Fila de aprovação de descontos com contexto (cliente, histórico, margem)
  3. Mapa de calor da equipe — quem está produzindo, quem precisa empurrão
  4. Alertas proativos — rep sem check-in há 2 dias, cliente top sem pedido há 30+ dias
  5. Comparativo entre reps (sem expor publicamente, só pra ela)
  6. Relatórios sob demanda que carregam em <5 segundos

Implicações de design

  • Desktop-first, mas com mobile útil (consulta rápida)
  • Dense information design — Sandra quer muita informação na mesma tela
  • Ações decisórias com 1-2 cliques (aprovar/negar desconto sem 5 telas)
  • Notificações push para itens que exigem decisão dela

🔵 Daniel — Dono / Diretor Comercial

Quem é

  • 40-65 anos, sócio-fundador ou diretor sênior
  • Já passou pela operação, hoje dirige
  • Tem o caixa, decide investimentos
  • Compra o SAR + usa o SAR (buyer e user — overlap com business-customers.md)
  • Vê o SAR no notebook em casa, no escritório, no celular esporadicamente

Cenário típico (terça à noite, em casa)

"Janta com a família, depois abre o SAR no iPad. Quer ver: faturamento do mês vs. meta, top 5 clientes do mês, top 5 produtos, clientes que estão esfriando, e principalmente o que a IA está sugerindo ('Atenção: cliente X reduziu pedidos 40% nos últimos 60 dias' / 'Oportunidade: produto Y cresceu 25%, considere campanha')."

Frustrações (no legado)

  • Dashboards mostram passado, não próximo passo
  • Recebe planilhas mas não consegue extrair direção
  • Sabe que está perdendo cliente, mas não sabe quais nem por quê
  • Quer delegar pra Sandra mas não confia 100% que ela vai ver o que ele veria
  • Reuniões com supervisor são genéricas, sem dados acionáveis

Goals

  • Dirigir, não operar
  • Ter painel que avisa quando algo desvia (não precisar procurar)
  • Confiar no time + ter visibilidade estratégica
  • Tomar decisões de investimento (contratar mais rep? trocar tabela de preço?) com dados

Current solution

  • Desktop JCS legado para relatórios mensais
  • Excel (consolidação que financeiro/Sandra preparam)
  • Reuniões com supervisor (semanal/quinzenal)
  • Intuição + experiência

O que ele precisa do SAR

  1. Dashboard estratégico (não operacional) — faturamento, top/bottom, tendências
  2. IA estratégica proativa — alertas + sugestões, não relatório passivo (DIFERENCIAL DECLARADO)
  3. Comparativo período a período (este mês vs. mês passado, vs. mesmo mês ano anterior)
  4. Análise de carteira — concentração de risco em 1-2 clientes, churn silencioso
  5. Visão de meta por equipe / por rep
  6. Recomendações de IA (campanhas, alocação de esforço, ajuste de tabela)

Implicações de design

  • Desktop/iPad-first — Daniel quer telas amplas, gráficos grandes
  • Visualização > tabela — gráficos, indicadores, alertas; minimizar listas brutas
  • Tom executivo — sem ruído operacional ("3 pedidos aguardando aprovação" é da Sandra, não dele)
  • IA precisa explicar: "Por que está me dizendo isso?" — alertas com contexto, não black box
  • Modo claro/escuro elegante (uso noturno em casa)

🟣 Alice — Administradora / Backoffice

Quem é

  • 25-45 anos, funcionária administrativa da empresa-cliente
  • Trabalha em escritório, desktop o dia todo
  • Reporta para Sandra ou Daniel
  • Domínio: catálogo, pautas, tributação, campanhas, cadastros

Cenário típico (quarta 14h, no escritório)

"Está cadastrando nova linha de produtos que a empresa vai começar a vender em janeiro. Precisa importar planilha do fornecedor, ajustar pauta de preço por região, configurar grupo tributário (ICMS-ST), depois preparar a campanha de lançamento com 15% de desconto na primeira compra."

Frustrações (no legado)

  • Cadastros lentos, telas confusas, muitos campos opcionais sem orientação
  • Pauta de preço é planilha avulsa importada manualmente — propensa a erro
  • Configurar promoção exige "pedir pro dev rodar SQL"
  • Tributação ICMS-ST por UF é um inferno — não tem assistente, tem que conhecer regra
  • Cadastrar rep com permissões/região é processo manual
  • Não tem trilha de auditoria — quem mexeu na tabela de preço ontem?

Goals

  • Manter catálogo + tributação + promoções funcionando sem incidente
  • Não precisar do dono pra cada ajuste
  • Lançar campanhas com agilidade (promoções de fim de mês, sazonais, kit, brinde)
  • Ter confiança de que o sistema não vai "estourar" pedidos por erro de pauta

Current solution

  • Desktop JCS legado (cadastros e pautas)
  • Excel (planilhas de import/conferência)
  • Pede pro dev (JCS ou interno) quando precisa de algo não-coberto pela tela
  • Documentos PDF da legislação ICMS-ST sempre abertos

O que ela precisa do SAR

  1. Cadastro de produto rápido (form inteligente, validação por contexto)
  2. Pauta de preço com versionamento — saber o que mudou, quando, por quem
  3. Editor de campanhas/promoções no-code (não SQL): "Produto X com 15% off para clientes da região Y durante o mês Z"
  4. Assistente de tributação (ICMS-ST/IPI) — sugere grupo correto baseado em NCM + UF de destino
  5. Gestão de representantes — cadastro, região de atuação, hierarquia (rep → supervisor), comissão
  6. Auditoria — quem mexeu em quê, quando, conseguir reverter
  7. Bulk operations — import CSV, edição em lote

Implicações de design

  • Desktop-only (sem investimento mobile prioritário)
  • Dense forms com assistentes — não wizards de 10 passos
  • Confirmação para operações destrutivas (alterar pauta de 500 produtos exige double-check)
  • Trilha de auditoria visível (histórico em cada entidade)
  • Editor visual de campanhas — possível diferencial sobre concorrentes que exigem SQL/script

Comparativo executivo

Persona Device Volume de uso Frequência Frustração #1 Goal #1
Rafael (Rep) Mobile-first 70-90% Várias vezes ao dia Cliente esfria sem ele saber Bater meta
Sandra (Supervisora) Desktop-first + mobile 5-15% Várias vezes ao dia Reps "somem" no campo Time bate meta + dormir tranquila
Daniel (Dono) Desktop/iPad 1-5% Diário/semanal Recebe passado, não próximo passo Dirigir sem operar
Alice (Admin) Desktop-only 1-5% Diário (em ondas) Promoção exige pedir pro dev Lançar campanha sozinha

Buyer × User mapping (atualização do business-customers.md)

Papel na compra User persona overlap
Decisor (Dono) Daniel (alto overlap — buyer = user em PME pequena)
Decisor (Diretor comercial) Sandra (em PME média, diretor comercial é a Sandra subindo na hierarquia)
Influenciador-chave Sandra (sempre) + Rafael (champion interno se já conheceu)
Ausente Alice (não pesa na decisão; só usa depois de comprado)

Insight de venda: a demo precisa brilhar para Sandra (influenciadora), vender para Daniel (decisor), e encantar Rafael (champion). Alice é benefício mostrado, não argumento de venda.


Implicações para Phase 2 (Trigger Map)

As 4 personas viram base para os "Target Groups" do Trigger Map. Cada uma terá:

  • Alliterative persona name confirmado: Rafael Representante / Sandra Supervisora / Daniel Dono / Alice Admin
  • Driving forces positivas + negativas
  • Frequency × Intensity × Fit scoring
  • Feature impact mapping

Lacunas conscientemente adiadas

  • Cena visceral / dia típico com dialogo real (Phase 2)
  • Sub-segmentação dentro de Rafael (rep de distribuidora vs rep de indústria — pode ter dores distintas)
  • Mapa empático completo (Phase 2 Trigger Map)