Julian/sar

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

7.7 KiB

Raw Permalink Blame History

Product Concept — SAR (Força de Vendas)

Confirmed: 2026-05-26 Step: 07a — Product Concept

Concept ≠ feature list. É o princípio organizador estrutural que define como o produto funciona — não o que ele faz.

A ideia em uma frase

SAR é uma plataforma de 4 cockpits especializados (Rep / Supervisor / Dono / Admin) compartilhando um dado único em tempo real, atravessado por WhatsApp nativo e IA contextual.

Mental model (metáfora canônica)

Como uma equipe de Fórmula 1: cada papel (piloto, engenheiro, estrategista, mecânico) tem seu próprio dashboard, suas próprias decisões e seu próprio ritmo — mas todos veem o mesmo carro em tempo real, com a mesma telemetria. WhatsApp e IA são o rádio que conecta todos.

Por que ESTA estrutura (não outra)

Alternativa considerada	Por que rejeitada
"Um produto único, RBAC esconde o que cada um não usa"	Modelo Mercos/Promosoft. Tela do rep cheia de coisa irrelevante e vice-versa. Não diferencia.
"4 produtos separados (4 logins, 4 contas)"	Quebra o tempo real. Quando rep lança pedido, supervisor não vê na hora. Fragmenta a marca.
"Web genérico responsivo igual pra todos"	Rafael precisa mobile-first (carro/posto/3G ruim). Daniel precisa desktop/iPad. Forçar igualdade penaliza ambos.
"4 cockpits especializados sobre dado único em tempo real" ✅	Cada papel ganha o produto ideal para ele, sem fragmentar dado nem perder consistência.

Princípios de implementação

1. Cada cockpit tem sua própria UX, navegação e device-target

Cockpit	Device-target	Padrão UX
Rafael (Rep)	Mobile-first	Touch-friendly, offline-resiliente, latência percebida baixa, dark mode
Sandra (Supervisora)	Desktop-dense + mobile-light	Dense information, ações 1-clique, push notifications
Daniel (Dono)	Desktop/iPad	Visualização > tabela, tom executivo, claro/escuro elegante
Alice (Admin)	Desktop-only	Dense forms com assistentes, bulk operations, auditoria visível

2. Camada de dados única em tempo real

Socket.IO + SSE (já previsto em STACK.md §13)
Mudança no Cockpit X aparece em Cockpit Y em <2 segundos
Sem batch noturno, sem refresh manual, sem polling

3. WhatsApp e IA atravessam os 4 cockpits

Não são módulos isolados — são fios condutores horizontais
WhatsApp: mensagem do cliente vira notificação no Rep, alerta no Supervisor, log no Dono, configuração na Admin
IA: gera alertas para Supervisor (operacional), recomendações para Dono (estratégico), sugestões para Admin (campanhas)

4. Multi-tenancy BD-por-workspace (ADR 0006)

Cada empresa-cliente tem cluster Postgres dedicado
Cockpits compartilham fonte de verdade dentro de um workspace
Isolamento físico entre clientes (LGPD, segurança)
Onboarding/trial: workspace sandbox provisionado automaticamente

Exemplo concreto (fluxo que materializa o concept)

Cenário: Rafael lança um pedido com 15% de desconto (acima da alçada dele de 10%).

  [Cockpit Rafael — mobile, 14:32]
     │
     │ 1. Lança pedido R$ 12.000 c/ 15% desconto
     │    → toca "Enviar"
     │
     ▼
  Backend: cria pedido status="aguardando_aprovacao"
     │ broadcast WebSocket → workspace
     │
     ├─→  [Cockpit Sandra — desktop, 14:32]
     │       Fila de aprovações: +1 (animação suave)
     │       Push notification no celular dela
     │
     ├─→  [WhatsApp do cliente — 14:32]
     │       "Olá! Seu pedido #1234 está em análise.
     │        Acompanhe: link..."
     │
     │
  [Sandra aprova com 1 clique, 14:34]
     │ broadcast WebSocket
     │
     ├─→  [Cockpit Rafael — mobile, 14:34]
     │       Pedido muda de "aguardando" → "aprovado"
     │       Toast: "✅ Sandra aprovou seu desconto"
     │
     ├─→  [WhatsApp do cliente — 14:34]
     │       "Pedido #1234 confirmado!"
     │
     │
  [Cockpit Daniel — desktop, 22:30 mesmo dia]
       IA: "Hoje você aprovou 3 descontos acima de 10%,
            todos para o cliente OPENFRIOS.
            Considere reavaliar a tabela base para eles."

Esse fluxo único toca: 4 cockpits + tempo real + WhatsApp nativo + IA proativa. É o produto-concept em ação — não é demo, é o dia-a-dia.

Features que DECORREM (não definem) do concept

Cockpit	Features pilares
Rep	Lançamento de pedido em <60s · Visão 360° cliente · Comissão tempo real · Funil pessoal · WhatsApp integrado · Agenda + GPS check-in
Supervisor	Fila de aprovações com contexto · Mapa de calor da equipe · Alertas proativos · Comparativo entre reps · Dashboard "apertar parafusos"
Dono	Faturamento vs meta · Top/bottom clientes e produtos · IA estratégica explicável · Análise de carteira/concentração de risco
Admin	Cadastros (produto/cliente/rep) · Pautas versionadas · Editor de campanhas no-code · Assistente ICMS-ST · Auditoria · Bulk operations
Atravessando	WhatsApp Business API nativo · IA contextual · Multi-tenancy BD-por-workspace · Real-time Socket.IO/SSE · Mobile+Desktop paradigmas distintos

Tensões deliberadas (decisões que custam, mas valem)

Construir 4 UX paradigmas em vez de 1 responsivo
- Custo: mais código, mais design, mais teste, mais complexidade
- Ganho: cada persona ganha experiência adequada; diferencial vs concorrentes
- Mitigação: Design System compartilhado (Phase 6) garante tokens/componentes consistentes mesmo com paradigmas distintos
Tempo real over batch
- Custo: infraestrutura Socket.IO + SSE + Valkey adapter; complexidade de estado client-side
- Ganho: promessa-mãe "visibilidade em tempo real" cumprida; demos brilham
- Mitigação: STACK.md §13 já previu; multi-tenancy BD-por-workspace facilita escopo de broadcast (por workspace, não global)
WhatsApp e IA como pilares horizontais, não módulos
- Custo: acoplamento entre cockpits via filas e eventos; precisa pensar arquitetura desde o MVP
- Ganho: diferenciais declarados não são afterthought; entram no produto coerentemente
- Mitigação: event-driven via BullMQ (já no STACK.md §11); contrato de evento padronizado

Implicações para Phase 2 / 3 / 4

Phase 2 (Trigger Map): as 4 personas já são os Target Groups. Trigger Map vai aprofundar driving forces × feature impact por cockpit.
Phase 3 (PRD): cada cockpit pode virar um epic. Atravessadores (WhatsApp, IA, real-time, multi-tenancy) viram epics horizontais.
Phase 4 (UX Specs): cada cockpit gera scenarios separados. Páginas dentro de cada cockpit seguem o paradigma de device-target dele.
Phase 6 (Design System): tokens compartilhados, mas variantes por cockpit (mobile vs desktop dense vs visualização-first vs forms-first). Phase 6 não é opcional para o SAR.

Relação com o concept e o positioning (sanity check)

O concept reforça o positioning:

Positioning claim	Como o concept entrega
"3 (4) experiências distintas no mesmo produto"	Princípio estrutural #1: 4 cockpits especializados
"Visibilidade em tempo real"	Princípio #2: dado único em tempo real entre cockpits
"WhatsApp como canal nativo"	Princípio #3: WhatsApp como fio condutor horizontal
"IA estratégica não decorativa"	Princípio #3: IA atravessando 4 cockpits, não cosmética
"Coexistência com ERPs existentes"	Princípio #4: multi-tenancy BD-por-workspace facilita integração heterogênea
"SaaS web distribuível"	Multi-tenancy + provisioning automatizado de workspace

Positioning declara promessas. Concept estrutura a entrega.

7.7 KiB Raw Permalink Blame History Unescape Escape