sar/design-artifacts/A-Product-Brief/dialog/decisions.md

# Decisões — Phase 1 (Project Brief)

> Log de decisões-chave tomadas durante a Phase 1. Append-only.

---

## 2026-05-26 — Step 1a (Client Profile)

### Organização
- **JCS Sistemas** é PME estabelecida (software house), 11-50 pessoas, alta maturidade técnica, design ainda iniciante.
- SAR é o **1º projeto da JCS com processo UX formal**.

### People & decisão
- **Julian** acumula 3 papéis: Product Owner + Tech Lead + único Champion.
- **Autonomia total** para decidir escopo/prazo/design.
- **Cultura fast-individual:** sem comitê, sem signoff externo, decisões saem rápido.

### Driver
- SAR **não é "consertar legado"**. É **upgrade de tier**: unificar força de vendas (app Android) + ERP (Desktop) num **SaaS web vendável**.
- **Sucesso = JCS competitiva como SaaS de força de vendas regional/nacional.**
- SAR funciona como **vitrine de marca JCS** — vai além de produto, é posicionamento.

### Working style
- Sem deadline rígido.
- Sessões longas focadas no chat.
- Velocidade > formalismo (mas qualidade > velocidade quando conflitam).

### Implicações
- Posso ser direto em recomendações (sem precisar embalar politicamente).
- Steps 27-32 (Platform) vão ser **consolidação documental** via STACK.md, não descoberta.
- Steps 1-12 (Brief estratégico) e 13-18 (Content) são onde há trabalho real.
- Phase 2 (Trigger Map) precisa considerar **clientes-empresa potenciais** como persona implícita, além dos 3 perfis usuários (rep / supervisor / admin).

---

## 2026-05-26 — Step 2 (Vision)

### Vision statement aprovada
> SAR é a plataforma de força de vendas que dá clareza para o representante, ferramenta de decisão para o supervisor, e IA estratégica para o dono — entregue como SaaS web, vendável e escalável, posicionando a JCS Sistemas como fornecedora de software moderno para o mercado B2B brasileiro.

### Decisões-chave reveladas
1. **3 experiências distintas, não 3 telas iguais.** Rep, Supervisor e Dono usam o SAR de modos qualitativamente diferentes (operacional ↔ tático ↔ estratégico).
2. **WhatsApp é canal nativo, não integração anexa.** Implica API WhatsApp Business no escopo desde o início.
3. **IA estratégica para o dono é diferencial declarado.** Implica decidir cedo o escopo de IA (insights generativos? alertas? recomendações?).
4. **Inteligência de carteira ativa** (inativos, ciclo, oportunidades) — não é "relatório", é parte do produto-base.
5. **SaaS multi-tenant é o pulo qualitativo**, não "ter mais features que o legado". Distribuição/instalação é o gargalo que o web resolve.

### Implicações para próximos steps
- Step 3 (Positioning): diferenciais já mapeados (6 itens), prontos para virar positioning statement.
- Step 7 (Target Users): rep / supervisor / dono (não "admin" do brand.md — o dono é uma persona estratégica distinta).
- Step 9 (Competitive Landscape): SaaS força de vendas regional/nacional — Mercos, Promosoft, Workforce, etc.
- Step 10 (Constraints): IA + WhatsApp + multi-tenant impõem escolhas técnicas e regulatórias (LGPD reforçada).

### Lacuna documentada
- "Cena concreta do dia típico" (pergunta #1) ficou em aberto, será retomada na Phase 2 (Trigger Map).

---

## 2026-05-26 — Step 3 (Positioning)

### Target customer
- 4 perfis válidos: Distribuidoras, Indústrias, RCAs, PMEs com vendas externas
- **Sweet spot:** 5-50 representantes na rua (mid-SMB)

### Categoria
- Plataforma SaaS de Força de Vendas (SFA)

### Dor central
- **Donos e supervisores decidem no escuro** — não têm visibilidade em tempo real do que acontece na rua

### Concorrência
- Apps verticais: Mercos, Promosoft, MaxFV, Workforce, Mobits
- ERPs com módulo: TOTVS, Sankhya, Senior
- Stack improvisado: Excel + WhatsApp + ERP
- Apps caseiros sob medida

### Implicações estratégicas chave
1. **Coexistência com ERPs como diferencial** — multi-tenancy BD-por-workspace facilita integração heterogênea por cliente
2. **WhatsApp nativo e IA estão no MVP**, não em roadmap futuro
3. **3 experiências distintas** é pilar de marca, não detalhe
4. **"Visibilidade em tempo real" é promessa-mãe** — implica websockets/SSE no produto desde o lançamento
5. **Pricing range** definido pelo sweet spot 5-50 reps (mid-SMB, não enterprise nem micro)

### 4 estratégias de aquisição por origem
- App vertical concorrente → ganho de IA + 3 experiências + WhatsApp
- Módulo de ERP → coexistência, não migração
- Stack improvisado → primeira ferramenta de verdade
- App caseiro → fim do pesadelo de manutenção

---

## 2026-05-26 — Step 5 (Business Model)

### Modelo escolhido
- **B2B SaaS multi-tenant, per-seat, sales-led, com trial real**
- Cobrança: **per-seat** (por rep ativo/mês)
- Sales motion: **sales-led** (demo + proposta + acompanhamento comercial)
- Trial: **14-30 dias** com dados reais (workspace sandbox)
- Contrato: **híbrido** — mensal sem fidelização OU anual prepago com desconto (10-20%)

### Ticket médio estimado (R$ 150/rep referência)
- Pequeno (5-10 reps): R$ 750-1.500/mês → ARR R$ 9k-18k
- Médio baixo (11-25): R$ 1.650-3.750/mês → ARR R$ 20k-45k
- Médio alto (26-50): R$ 3.900-7.500/mês → ARR R$ 47k-90k

### Implicações técnicas chave
1. Precisa **active rep counter** no produto (define cobrança)
2. Trial exige **provisioning automatizado** de workspace + seed opcional
3. Billing suporta **cobrança mensal recorrente + cobrança anual única** (provider a decidir em Step 29 — Iugu/Pagar.me/Gerencianet/Stripe)
4. Workspace sandbox de trial reusa arquitetura BD-por-workspace (ADR 0006) — não é caso especial

### Implicações de marketing
- **CTA principal do site:** "Agende demo", não "Sign up free"
- **Trial é gated:** form → SDR qualifica → demo → liberação
- **Pricing page** explícita no site

### Lacunas conscientemente adiadas
- Preço exato/rep (validar com mercado)
- Setup fee / implantação paga (não decidido)
- Add-ons premium (WhatsApp tier? IA tier?) — futuro

---

## 2026-05-26 — Step 6 (Business Customers)

### Buyer persona — "O Dono Empresário B2B"
- 35-60 anos, sócio-fundador ou herdeiro, gerencia "no peito"
- Critério: **fé que vai funcionar**, não TCO planilhado
- Convence: demo concreta + boca-a-boca + cases
- Assusta: aprendizagem do time, complexidade, custo

### Estrutura de decisão
- **Decisor:** dono OU diretor comercial (varia por porte)
- **Influenciadores que matam o deal:** supervisor de vendas + reps champions
- **Ausentes:** financeiro, TI, jurídico (venda operacional-emocional, não técnico-financeira)

### Canais de aquisição (4 ativos)
- Indicação boca-a-boca + Google/SEO + feiras setoriais + parceiros (contadores, revendedores ERP)
- Implica: programa de referral, blog SEO, calendário de feiras, página de parceiros

### Ciclo por porte
- Pequeno (5-10 reps): 2-4 semanas
- Médio baixo (11-25): 1-2 meses
- Médio alto (26-50): 2-4 meses (POC possível)

### Implicações chave
1. **Demo-friendliness obrigatória** — produto precisa brilhar em 5 min, sem hand-holding
2. **Site precisa 3 páginas por papel** (`/para-donos`, `/para-supervisores`, `/para-representantes`)
3. **Comparativos diretos** com Mercos/TOTVS no site (combate frontal)
4. **WhatsApp visível na primeira tela** do produto (diferencial declarado)
5. **JCS precisa de CRM próprio** para venda — possível dogfood (vender SAR com SAR)
6. **Conteúdo SEO:** controle de rep externo, força de vendas para distribuidora, WhatsApp + B2B

---

## 2026-05-26 — Step 7 (Target Users)

### 4 user personas confirmados
1. **Rafael Representante (PRIMÁRIA — MVP focus)** — 30-50a, mobile-first, 70-90% do volume de uso
2. **Sandra Supervisora** — 35-55a, desktop+mobile, "apertar parafusos diários"
3. **Daniel Dono** — 40-65a, desktop/iPad, IA estratégica, overlap com buyer persona
4. **Alice Admin (nova)** — 25-45a, desktop-only, pautas/promoções/tributação

### Decisão crítica de design
- **Mobile-first para Rafael, desktop-first para os outros 3.** SAR não é "responsivo único" — são paradigmas de UI distintos no mesmo produto.
- App do Rafael deve funcionar com sinal 3G/4G ruim (offline-resiliente parcial)
- Touch-friendly + dark mode desejável

### Insights de produto (entram em Phase 3/4)
- **Editor de campanhas/promoções no-code** vira diferencial declarado (foi mencionado como responsabilidade Alice)
- **Assistente de tributação ICMS-ST** por NCM+UF — diferencial vs ERP-modules
- **Auditoria/trilha de mudanças** em pautas, produtos, cadastros (Alice precisa, regulatório também)
- **WhatsApp integrado** + **comissão em tempo real** + **funil kanban** são fundamentos do Rafael
- **IA explicável** para Daniel (não black box; alertas com contexto)

### Insight de venda (refina Step 6)
- Demo precisa: **brilhar para Sandra** (influenciadora), **vender para Daniel** (decisor), **encantar Rafael** (champion)
- Alice é benefício mostrado, não argumento de venda

---

## 2026-05-26 — Step 7a (Product Concept)

### Concept estrutural canônico
> **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.**

### Metáfora canônica
- "Equipe de Fórmula 1" — cada papel tem seu próprio dashboard, mas todos veem o mesmo carro em tempo real

### 4 princípios de implementação
1. **Cada cockpit tem UX/device-target próprios** (Rafael mobile-first, outros desktop-first)
2. **Camada de dados única em tempo real** (Socket.IO + SSE, <2s entre cockpits)
3. **WhatsApp e IA são fios horizontais**, não módulos isolados
4. **Multi-tenancy BD-por-workspace** garante isolamento físico + facilita integração ERP heterogênea

### Tensões deliberadas aceitas
- Construir 4 UX paradigmas em vez de 1 responsivo (custo alto, diferencial alto)
- Tempo real obrigatório (custo de infra, ganho de promessa)
- WhatsApp/IA como pilares horizontais desde MVP (não roadmap)

### Implicações arquiteturais
- **Phase 6 (Design System) não é opcional** — tokens compartilhados + variantes por cockpit
- Cada cockpit possível epic na PRD; atravessadores (WhatsApp/IA/real-time/multi-tenant) viram epics horizontais
- Broadcast WebSocket sempre escopado a workspace (não global) — alinha com BD-por-workspace

---

## 2026-05-26 — Step 8 (Success Criteria)

### North Star MVP
- **1º cliente real paga e renova sem cancelar nos primeiros 3 meses após go-live**
- Critério: retenção provada > tração massiva

### Y1 comercial (12 meses pós-GA)
- **10-20 clientes pagantes** (conservador) | NPS donos > 50 | ARR R$ 200k-600k

### Timeline-chave
- **MVP em produção com 1º cliente real: 3-4 meses** (a partir de 2026-05-26)
- MVP validado: mês 6-7 (1º cliente renova)
- 10 clientes pagantes: mês 12
- Premissa: Julian + 1-2 devs adicionais

### Targets críticos por camada
- **Negócio JCS:** logo churn < 3%/mês · NPS > 50 · CAC payback < 12m · NRR > 110%
- **Cliente:** +15-30% pedidos/rep/mês · 10-20% inativos recuperados · aprovação desconto < 30 min · DAU/MAU reps > 80%
- **Comportamento usuário:** Rafael > 95% pedidos no SAR + DAU/MAU > 70% · Sandra > 90% aprovações pelo SAR · Daniel > 2x/sem IA · Alice > 80% campanhas no-code
- **Qualidade:** p95 tela < 800ms · p95 pedido < 60s · uptime 99.5% · pedidos perdidos = 0 · workspace provisionado < 5 min

### Implicação técnica chave
- **Instrumentação de produto no MVP, não em Phase 2 de roadmap**:
  - OTel + Pino + Grafana (já em STACK.md §09)
  - Analytics de produto (PostHog/Amplitude/self-host)
  - Módulo de feedback in-app para NPS

### Riscos definidos
- Rafael não adota → DAU/MAU < 50% em 60d
- Sandra não confia → aprovações por WhatsApp > 30%
- Daniel ignora IA → < 1x/semana
- North star falha → cliente cancela em 3m
- P0 imediato: qualquer pedido perdido por bug

---

## 2026-05-26 — Step 9 (Competitive Landscape)

### 5 grupos de alternativa analisados
1. Apps verticais (Mercos, Promosoft, MaxFV, Workforce, Mobits) — SAR ataca via 4 cockpits + IA + WhatsApp nativo
2. ERPs com módulo (TOTVS, Sankhya, Senior, Bling, Tiny, Omie) — SAR ataca via **coexistência** (não migração)
3. Stack improvisado (Excel + WhatsApp + ERP sem módulo) — SAR ataca via "primeira ferramenta de verdade"
4. Apps caseiros — SAR ataca via roadmap contínuo + fim do pesadelo de manutenção
5. **Do nothing** (50%+ dos prospects) — SAR ataca via choque "5-10% carteira/ano perdida silenciosamente"

### 5 unfair advantages estruturais (alto moat, >2 anos para concorrente neutralizar)
1. **Concept estrutural "4 cockpits"** — reescrita completa para copiar
2. **Multi-tenancy BD-por-workspace (ADR 0006)** — arquitetura desde dia 0
3. **Stack moderna JCS** — Node 24 + Nest 11 + Prisma 7 + React 19.2 (~3x velocidade vs PHP/Java/Delphi)
4. **IA desenhada desde concept** — não bolt-on
5. **Velocidade de iteração JCS** — equipe pequena + decisão fast-individual → iteração mensal vs anual

### Vantagens não-sustentáveis (copiáveis em 6-24 meses)
- WhatsApp nativo, editor no-code, UX moderna, real-time
- **Defesa estratégica: a combinação estrutural** dos 5 itens resistentes, não feature individual

### Posição estratégica alvo
- **Vendas-first + baixo atrito de implantação** — quadrante semi-vazio do mapa competitivo

### Implicações estratégicas
1. **Demo ataca do-nothing primeiro**, não Mercos — urgência vende mais que comparativo
2. **Coexistência com ERP é mensagem-chave** para Grupo 2
3. **IA precisa ser explicável desde MVP** — black box não convence donos
4. **WhatsApp via arquitetura plug-in** (não acoplado) — proteção contra mudanças Meta
5. **Janela de 2-3 anos para entrincheirar** — velocidade do MVP (3-4 meses) é decisão estratégica
6. **Foco em referenciabilidade** > tração massiva — primeiros 10 clientes viram cases públicos

---

## 2026-05-26 — Step 10 (Constraints)

### ⚠️ Tensão estratégica explícita (flagueada)
**Combo decidido:** concept ambicioso + MVP 3-4 meses + **solo founder mode** (Julian full-time até 1º cliente).
**A matemática não fecha sem trade-off.**

### Resolução proposta (refinar em Phase 3 PRD)
**MVP mínimo defensível:**
- ✅ Rep cockpit (Rafael) — obrigatório
- ✅ Supervisor cockpit (Sandra) — obrigatório, simplificado
- ✅ Multi-tenant BD-por-workspace — fundacional
- ✅ WhatsApp — versão básica (notificações; conversa bidirecional pós-MVP)
- 🟡 Dono cockpit (Daniel) — dashboard simples; **IA estratégica entra pós-MVP**
- 🟡 Admin cockpit (Alice) — cadastros essenciais; **editor no-code de campanhas entra pós-MVP**

**Premissa:** 1º cliente é referência interna/parceiro próximo, aceita limitações em troca de condições especiais. Quando renova (north star), Julian contrata 1-2 devs e completa.

### Constraints fixos
- **Timeline:** MVP 3-4 meses, janela mercado 2-3 anos
- **Budget:** small-business, CAC payback < 12m
- **Time:** **solo founder mode até 1º cliente** (Julian acumula tudo)
- **Stack:** STACK.md v2.2 é fonte da verdade (RFC para mudanças)
- **Brand:** brand.md (paleta JCS + Plus Jakarta + AntD 6.4 + topbar/sidebar + tom Apple)
- **Regulatório:** LGPD by design (isolamento físico multi-tenant, redact, criptografia PII)

### Constraints flexíveis (decisão pós-Brief)
- Provider de pagamento (Step 29)
- Provider de IA (Step 29)
- WhatsApp Business API provider (Step 29)
- Analytics de produto (Step 8 já flagueado)
- Dark mode (desejável especialmente Rafael)

### LGPD adicional para WhatsApp + IA
- DPA com Meta e OpenAI/Anthropic obrigatório
- Hashar dados antes de enviar para IA (sem nome/CPF/telefone real)
- Opt-in explícito do contato final no WhatsApp

---

## 2026-05-26 — Step 10a (Platform Strategy)

### Plataforma primária
- **Web SaaS** (React 19.2 SPA + Vite 8 + Nginx + Cloudflare) — STACK.md
- Sem app store; deploy = rolling docker-compose em VMs Proxmox

### Device strategy por cockpit
- **Rafael (Rep):** **PWA mobile-first** com foco primário em **iOS** (gap onde JCS não tem app native). Android secundário (existe legado, mas reps podem optar pelo PWA).
- **Sandra (Supervisora):** Desktop + PWA mobile-light para consultas/aprovações rápidas.
- **Daniel (Dono):** Desktop + **iPad first-class** (otimização dedicada).
- **Alice (Admin):** Desktop-only.

### Coexistência com app Android legado
- **MVP:** SAR PWA + backend SAR construídos do zero. Android legado intocado.
- **Pós-MVP (Y1+):** Adaptar app Android legado para consumir backend SAR (unificar fonte da verdade).
- **Futuro (Y1-Y2):** Avaliar native iOS + native Android sobre backend SAR (Capacitor/React Native).

### Offline strategy (Rafael)
- **Nível:** Read + Write com sync
- Lançamento de pedido offline → IndexedDB queue → Service Worker sync quando volta online
- Conflict resolution: Last-write-wins para rascunho; pedido submetido imutável
- Idempotency-Key por pedido (UUID local) protege contra duplicação no sync

### Native features no MVP
- ✅ Geolocation (check-in Rafael)
- ✅ Web Push (Sandra aprovação, Rafael pedido aprovado) — exige PWA + VAPID
- ✅ Share API (Rafael compartilha pedido via WhatsApp do celular dele)
- ✅ Notification API desktop (Sandra)
- 🟡 Pós-MVP: Camera, File System Access, Voice (este descartado por segurança rodoviária)

### Acessibilidade
- WCAG AA mínimo desde MVP

### Implicação de execução
- PWA exige investimento explícito ~1-2 semanas no MVP
- iPad first-class implica testes regulares em iPad Safari durante Phase 4
- Web Push backend reusa BullMQ jobs (alinha com STACK.md §11)

---

## 2026-05-26 — Step 11 (Tone of Voice)

### 5 atributos canônicos
1. **Direto** — sem floreio
2. **Profissional sem ser frio** — sério, mas humano (não burocratês)
3. **Confiante** — afirmativo, não tentativo
4. **Específico** — números/dados sempre que possível
5. **Empático nos momentos difíceis** — problema + caminho para resolver

### Variações por cockpit (mesmos atributos, registros distintos)
- Rafael: informal, frases curtas
- Sandra: direto + decisivo
- Daniel: executivo, foco em insight
- Alice: técnico-preciso

### Don'ts
- Emoji em produção (brand clean Apple)
- Caps lock para erros
- Burocratês ("operação", "registro", "movimentação")
- "Por favor"/"obrigado" excessivo
- Anglicismos onde tem pt-BR (Submit→Enviar)
- Frases dúbias ("Talvez", "Possivelmente")

### Vocabulário canônico (padrão único)
- Cliente · Representante/Rep · Orçamento · Pedido · Faturado · Visita · Carteira · Inativo · Painel · Aprovação

### Implicação
- Vocabulário vira tokens i18n centralizados (não strings espalhadas)
- Phase 6 Design System inclui guia de microcopy
- Prompt de IA generativa precisa incluir esses 5 atributos + vocabulário canônico

---

## 2026-05-26 — Step 12 (Create Product Brief) — BLOCK A COMPLETO

### Product Brief synthesis
- **Narrativa estratégica apresentada** como história coerente (não checklist)
- **User confirmation:** confirmado sem ajustes
- **Brief gerado:** `design-artifacts/A-Product-Brief/01-product-brief.md`

### Conteúdo do brief canônico
- Resumo estratégico
- Vision + 3 experiências + 7 diferenciais
- Positioning (framework Geoffrey Moore) + mapa estratégico
- 4 personas (Rafael primária + Sandra + Daniel + Alice)
- Buyer × User mapping
- Business model (per-seat sales-led trial + contrato híbrido)
- Buyer persona "Dono Empresário B2B"
- Canais de aquisição (4) + ciclo por porte
- Success criteria (North Star MVP + 4 camadas de métricas)
- Competitive landscape (5 grupos + 5 unfair advantages + janela de mercado)
- Constraints (tensão solo + 3-4 meses + concept ambicioso flagueada)
- Platform strategy (PWA iOS + offline + native features)
- Tone of voice (5 atributos + vocabulário canônico + don'ts)
- Riscos + mitigações
- Próximos passos (Blocks B, C, D, E)

### Status do Block A
- **CONCLUÍDO** — Steps 1, 1a, 2, 3, 5, 6, 7, 7a, 8, 9, 10, 10a, 11, 12 (14 steps)
- Tempo decorrido: ~2-3 horas em uma sessão
- Próximo: Block B (Content & Language) — Steps 13-18

---

## 2026-05-26 — Step 13 (Content Init) — BLOCK B INICIADO

### Materiais herdados
- `brand.md` — identidade visual + tom visual "Apple-inspired"
- `01-product-brief.md` — Block A canônico
- `dialog/tone-of-voice.md` — 5 atributos + vocabulário canônico (Step 11)

### Q: Tem brand guidelines existentes?
**A: Sim** — brand.md + tone-of-voice.md cobrem visual e microcopy. Block B vai expandir para:
- Personalidade (Step 14)
- Tom refinado (Step 15)
- Idiomas (Step 16)
- SEO (Step 17)
- Content structure (Step 17a)
- Documento final (Step 18)

### Output inicializado
- `design-artifacts/A-Product-Brief/02-content-language.md`

---

## 2026-05-26 — Step 14 (Personality)

### Metáfora canônica
- **"Consultor sênior brasileiro de vendas B2B"** — 40-50a, ex-rep que virou consultor, conhece a rua e o ERP, sem firula

### 5 atributos de personalidade
1. **Confiável** — não erra, não some
2. **Especialista prático** — conhece o setor, fala como amigo, não acadêmico
3. **Decidido** — diz o que é, aponta caminho
4. **Discreto** — não atrapalha, Apple-inspired
5. **Aliado** — do lado do usuário, não vigiando

### Conexão por persona
- Rafael: colega mais experiente
- Sandra: assessor de confiança
- Daniel: consultor estratégico
- Alice: técnico-parceiro

### O que NÃO é
- Vendedor barulhento, burocrata, coach motivacional, espião, filósofo, jovem descolado

---

## 2026-05-27 — Step 15 (Tone refinement)

### Posicionamento nos 4 espectros (1-5)
- **Formality: 3** (levemente formal)
- **Mood: 2** (sério-com-leveza)
- **Complexity: 3** (vocabulário do setor + acessível)
- **Energy: 2** (reservado, Apple-inspired calm)

### Centro de gravidade
"Levemente formal, sério-com-leveza, tecnicamente acessível, energia contida."

### We Say / Don't Say expandidos
- 5 categorias com 3 colunas (✅ SAR / ❌ formal demais / ❌ casual demais)
- Cobre: cumprimentos · sucesso · erro · empty states · IA/sugestão

---

## 2026-05-27 — Step 16 (Languages)

### Estratégia canônica
- **pt-BR only no MVP, arquitetura i18n-ready**
- en preparado no código (chaves i18n) mas sem tradução no MVP
- es (LatAm) fora de escopo (requer adaptação fiscal por país)

### IA generativa
- **Sempre pt-BR** — prompts em pt-BR + validação de output (rejeitar respostas em en, fallback)
- Vocabulário canônico naturalmente vira chaves i18n estruturadas

### Localização (BR-only)
- BRL · DD/MM/AAAA · 24h · fuso `America/Sao_Paulo` por workspace · telefone `+55 (XX) XXXXX-XXXX` · CEP/CNPJ/CPF padrão BR · sistema métrico

### Implicação para STACK
- Validators Zod para CPF/CNPJ/CEP/telefone BR
- Date-fns/Day.js com locale pt-BR
- `Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' })`
- Fuso por workspace no master-login

---

## 2026-05-27 — Step 17 (SEO Strategy)

### Keywords nos 6 intents
- Service/Solução · Problem · Comparison · Brand · Informational · Long-tail setor

### Domínio
- **A definir** — recomendação: `sarjcs.com.br` (brandable + JCS-link)

### URL pattern
- pt-BR: `<dominio>/<slug>` · en futuro: `<dominio>/en/<slug>`
- Slug: lowercase, hífen, sem especiais, ASCII

### Sitemap
- `/` · `/funcionalidades/<cockpit|whatsapp|ia|carteira>` · `/para/<setor>` · `/comparativos/<concorrente>` · `/precos` · `/recursos/<blog|calculadora|kit>` · `/cases` · `/parceiros` · `/sobre` · `/contato` · `/app/`

### Structured data
- `Organization` (todas) · `SoftwareApplication` (home) · `Product`+`Offer` (preços) · `Article`+`Review` (cases) · `Article`+`BreadcrumbList` (blog) · `FAQPage`

### Local SEO
- Reivindicar Google Business Profile da JCS Sistemas
- NAP consistente no footer

### Implicação técnica
- Vite + plugin React Helmet para meta dinâmico
- JSON-LD para structured data (não microdata)
- Sitemap.xml gerado por script no build
- robots.txt + meta noindex em `/app/`

---

## 2026-05-27 — Step 17a (Content Structure)

### Site Marketing (10 princípios)
- Hero em <5s · vídeo não tour · prova social pesada · 3 jornadas por persona · setor dedicado · CTA único · pricing visible · comparativos acessíveis (não em destaque) · `/recursos/` separado · cases viram peça central com 3+ clientes

### Produto / 4 cockpits (11 princípios)
- Cada cockpit tem home própria · hierarquia por urgência · navegação por device (bottom nav rep / sidebar 260px outros) · max 3 níveis · WhatsApp+IA no caminho principal · empty states informativos · notificações só pra decisão · tempo real com micro-animação · admin fora do path · auditoria em cada entidade · onboarding discreto

### Exclusões explícitas (8)
- Tutorial agressivo · gamificação gritante · chat-com-cliente in-app · marketing email · NF/SPED · wallet · CMS blog · mobile-first para Daniel/Alice

### Latitude Phase 4
- Visão alta no produto, restrições claras de tom/estilo

---

## 2026-05-27 — Step 18 (Create Content Document) — BLOCK B COMPLETO

### Output finalizado
- `design-artifacts/A-Product-Brief/02-content-language.md` — documento canônico de comunicação

### Conteúdo adicional ao doc
- **Content Type Guidelines:** UI microcopy · Marketing · Informational · Notificações transacionais · WhatsApp programático · IA generativa
- **Content Ownership** (MVP solo + Y1+ contratações)
- **Writing Checklist** (13 itens; entra em todo PR de microcopy/artigo/email)
- **Resumo executivo** (snapshot completo)

### Status do Block B
- **CONCLUÍDO** — Steps 13, 14, 15, 16, 17, 17a, 18 (7 steps)
- Próximo: Block C (Visual Direction) — Steps 19-26 (fast-track via brand.md)

---

## 2026-05-27 — Step 19 (Inspiration Workshop) — BLOCK C INICIADO

### 🌟 Insight estratégico chave revelado
> "Não acho nada que tem no mercado de identidade como inspirador — mais uma das coisas que nos trouxe para esse projeto." (Julian)
- Mercado B2B força de vendas BR é visualmente medíocre
- **Estética moderna é parte do diferencial fundacional do SAR**, não detalhe
- **Adicionar como 6º unfair advantage estrutural** no Brief (refinamento ao Step 9)

### 4 referências externas confirmadas
1. **Apple iCloud** — Apple-inspired clean canon
2. **Linear** — SaaS B2B moderno, dense + clean, atalhos, dark mode
3. **Stripe Dashboard** — densidade + acessibilidade, dados com contexto
4. **Notion** — flexibilidade, empty states, hierarquia tipográfica

### 7 padrões destilados (entram em Design Style)
- Sidebar fixa + área limpa · Tipografia hierarquia · Único accent · Densidade respirável · Animações sutis · Dark mode · Empty states informativos

### Referência por cockpit (alimenta Phase 4)
- Rafael: Linear mobile + Apple Notes
- Sandra: Linear + Stripe Dashboard
- Daniel: Stripe Dashboard + Apple iCloud
- Alice: Notion + Linear

### Output
- `dialog/inspiration-analysis.md`

---

## 2026-05-27 — Step 21 (Existing Brand)

### Inventário
- Logo SAR: PNG existe (`frontend/img/`) — refresh para SVG + variantes
- Logo JCS: 4 PNGs colocados em `design-artifacts/_references/jcs-logo/` — refresh para SVG
- Paleta JCS: canônica (brand.md), Keep as-is
- Plus Jakarta Sans: canônica, Keep as-is + self-host produção
- FA 6.4 + Chart.js + tokens radius/sombra: canônicos, Keep as-is
- Layout topbar+sidebar: Keep + adaptar Rafael (mobile bottom nav)

### Análise visual da logo JCS
- "JCS." em bold JCS Blue + seta/swoosh no "C" (movimento, precisão)
- "sistemas" em peso light, lowercase, mesmo azul
- Layout horizontal clean — Apple-inspired confirmado

### Análise visual da logo SAR
- Ícone JCS Blue com gráfico de barras crescente em branco (metáfora analytics)
- "SAR" em bold sans-serif cinza/preto
- "FORÇA DE VENDAS" em letterspaced caps cinza médio
- Hierarquia deliberada: SAR como produto distinto, JCS como marca-mãe

### Afiliações declaradas
- ✅ "Powered by JCS Sistemas" no footer/login/sobre
- ✅ Selos LGPD compliant + futuras certificações
- Nenhuma franquia, nenhuma associação setorial obrigatória

### Brand constraints (não negociáveis)
- JCS Blue `#004a99` único accent
- Plus Jakarta única família
- SAR coexiste visualmente com JCS sempre (parental link)
- Tom Apple-inspired clean — sem decoração desnecessária

---

## 2026-05-27 — Step 22 (Visual References)

### 9 categorias destiladas das 4 referências positivas
- Layout · Cor · Tipografia · Densidade · Imagery · Efeitos · Estados · Dark mode · Mobile

### 7 estilos a evitar (referências negativas)
- Burocrata corporativo legado · apps verticais BR (Mercos/Promosoft) · SaaS "fofo" · Material Design pesado · BI 2010-2015 · sites BR "exuberantes" · tour interativo agressivo

### 5 mood keywords canônicos
- **Clean · Confident · Specific · Serene · Modern**

### Frase âncora
"clean, confident, specific, serene, modern — como um consultor sênior que apareceu na sua empresa e abriu o notebook"

---

## 2026-05-27 — Step 23 (Design Style)

### 4 decisões canônicas
1. **UI Visual Style:** Modern Flat + Minimal (Apple/Linear/Stripe/Notion family) — sem skeumorfismo, sem 3D, radius 12/20px, sombra sutil
2. **Design Aesthetic:** Minimalism contemporâneo / Digital-native modern — post-Apple, sem ilustrações ornamentais
3. **Color Direction:** Monochromatic + functional accents — JCS Blue protagonista, cool, light + dark mode, distribuição 60/30/10
4. **Typography Direction:** Plus Jakarta Sans Geometric Humanist — tabular numerals em dashboards, hierarquia preliminar h1 32-40 / body 14-16 / caption 12-13

---

## 2026-05-27 — Step 24 (Layout & Effects)

### Site Marketing
- **Hero: Split** (texto + vídeo play-on-click)
- Layouts variados por tipo de página (single column / card grid / side-by-side / 3-column tier)
- Top nav sticky · hamburger mobile-only · mega menu em Funcionalidades/Para · CTA demo sempre visível

### Produto — pattern por cockpit
- **Rafael:** single column + cards verticais + bottom nav
- **Sandra:** sidebar + grid de cards + tabelas (Linear-like dense+decisão)
- **Daniel:** sidebar + **bento box** dashboard (Stripe-like KPIs)
- **Alice:** sidebar + **table-first** + forms drawer lateral

### Visual Effects (nível canônico)
- Shadows: sutil (brand.md)
- Animations: sutis funcionais 150-250ms ease-out
- Parallax: **none** (gimmick em B2B)
- Hover: sutil (background/opacity, sem transform 3D)
- Loading: skeleton (não spinner)
- Real-time: micro-animação 200ms, sem toast intrusivo
- Focus rings WCAG AA + reduced motion respeitado

### Performance targets
- Lighthouse mobile > 90 · TTI Rafael 3G < 3s · FCP < 1.5s
- Bundle inicial < 200KB gzipped por entry
- Code-split por cockpit · WebP/AVIF + lazy + sharp · Service Worker para Rafael offline · vídeo hero sem autoplay

---

## 2026-05-27 — Step 25 (Imagery)

### Estratégia canônica: **Apple-style produto-primário**
- MVP usa **screenshots do produto + ilustrações minimíssimas**
- **Sem stock humano** — sai do mainstream B2B saturado
- Fotos reais entram pós-MVP quando houver cases/permissões

### Photography style (quando aplicar)
- Authentic/Documentary — pós-MVP em cases
- **Product-focused — MVP** (screenshots reais)
- Lifestyle moderado pós-MVP (sem "team smiling")
- Polished/staged **NUNCA**

### Anti-padrões absolutos
- Executive shaking hands · diverse team smiling · UI hologram · gráficos 3D flutuando · senhor preocupado com planilha · cidade + barra sobreposta

### Icons
- FA 6.4 subset · **Regular/Outline padrão**, Solid só em estados · sistema 16/20/24px · cor inherit + JCS Blue em ações primárias · ícone SAR como signature visual

### Illustrations
- **Quase nenhuma no MVP** — Apple-clean prefere ausência
- Permitido: empty states (line art mono JCS Blue) e erro 404/500
- EVITAR: isométrico hipster · gradiente saturado · diversity blob people

### Image guidelines
- 16:9 / 4:3 / 1:1 ratios · alt obrigatório WCAG AA · WebP/AVIF + JPG fallback q80-85 · lazy load · srcset 1x/2x/3x · Cloudflare CDN · sharp pipeline

---

## 2026-05-27 — Step 26 (Create Visual Document) — BLOCK C COMPLETO

### Visual DNA Summary
```
Style:       Modern Flat + Minimal (Apple/Linear/Stripe/Notion family)
Aesthetic:   Minimalism contemporâneo / Digital-native modern
Colors:      Monochromatic JCS Blue + functional accents · cool · light + dark mode · 60/30/10
Typography:  Plus Jakarta Sans Geometric Humanist · tabular numerals
Mood:        Clean · Confident · Specific · Serene · Modern
Layout:      Split hero (site) · cards/grid/bento/table por cockpit
Effects:     Sutis funcionais 150-250ms · sombra única brand.md · sem parallax
Imagery:     Screenshots-only Apple-style · sem stock humano · FA outline
Key element: 4 cockpits sobre dado único em tempo real (ícone do gráfico crescente da logo SAR como símbolo)
```

### Status do Block C
- **CONCLUÍDO** — Steps 19, 20, 21, 22, 23, 24, 25, 26 (8 steps)
- Documento canônico: `design-artifacts/A-Product-Brief/03-visual-direction.md`
- Próximo: Block D (Platform Requirements) — fast-track via STACK.md (Steps 27-32)

---

## 2026-05-27 — Block D (Platform Requirements) — CONCLUÍDO ✅

### Steps 27-32 batched
- Step 27 (Init) · Step 28 (Tech Stack — espelho STACK.md v2.2) · Step 29 (Integrations) · Step 30 (Contact Strategy) · Step 31 (Multilingual & SEO) · Step 32 (Final synthesis)
- Documento canônico: `design-artifacts/A-Product-Brief/04-platform-requirements.md`

### Decisões fechadas no Step 29
- **Pagamento:** Iugu (boleto/PIX/cartão + assinaturas recorrentes BR)
- **WhatsApp:** Oficial Meta (WhatsApp Cloud API)
- **Analytics produto:** PostHog self-host em Proxmox
- **Email, Storage, Secrets, CDN, Obs:** já cobertos por STACK.md (Resend, MinIO, Vault, Cloudflare, Grafana+Sentry)

### Decisão ABERTA — IA generativa
- Julian quer estudar todas as opções (Anthropic / OpenAI / Local Ollama / Multi-provider)
- **Resolução estratégica:** abstração multi-provider via Vercel AI SDK ou LiteLLM desde dia 1 — código fica provider-agnostic
- **Default temporário:** Anthropic Claude (Sonnet/Opus) por explicabilidade e força em pt-BR, escondido atrás de interface JCS
- Decisão definitiva: quando 1º cliente fechar e Julian tiver tempo para benchmark

### Contact Strategy
- **Form de demo** como CTA único (sem chat ao vivo no MVP)
- 8 campos obrigatórios + 2 opcionais (qualifica origem + porte + ERP)
- Anti-spam: hCaptcha/Turnstile (não Google reCAPTCHA — LGPD)
- Rate limit 5/h email + 10/h IP
- SDR JCS (Julian no início) responde em até 4h úteis

### Multilingual & SEO técnico
- pt-BR only MVP, i18n-ready
- Domínio recomendado: `sarjcs.com.br`
- JSON-LD structured data plan completo
- noindex em `/app/` (produto privado)
- Lighthouse > 90 mobile como CI gate

### Maintenance
- Solo founder mode até 1º cliente; depois +1-2 devs JCS
- Documentação extensiva (CODING-RULES.md) como mitigação de bus factor