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>
This commit is contained in:
160
design-artifacts/A-Product-Brief/dialog/product-concept.md
Normal file
160
design-artifacts/A-Product-Brief/dialog/product-concept.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# 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)
|
||||
|
||||
1. **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
|
||||
2. **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)
|
||||
3. **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.
|
||||
Reference in New Issue
Block a user