From bca2e3ebb35745b5aa08987319eee086a53e370e Mon Sep 17 00:00:00 2001 From: julian Date: Wed, 27 May 2026 21:07:53 +0000 Subject: [PATCH] =?UTF-8?q?docs(docs):=20prd=20MVP=20SAR=20finalizado=20?= =?UTF-8?q?=E2=80=94=20Rafael=20+=20Sandra=20(C1=E2=80=93C9,=2045=20FRs)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fast path sobre Phase 1+2. Escopo: consulta de clientes, histórico de pedidos, lançamento offline com Idempotency-Key e aprovação de desconto. Reviewer gate aplicado: 3 fixes (offline/crédito, falha de sync, OQ-2). 6 OQs abertas; OQ-1/OQ-4 bloqueiam C2/C4 até primeiro cliente confirmar. Co-Authored-By: Claude Sonnet 4.6 --- .../prds/prd-sar-2026-05-27/.decision-log.md | 74 ++++ .../prds/prd-sar-2026-05-27/prd.md | 416 ++++++++++++++++++ design-artifacts/_progress/00-design-log.md | 19 + 3 files changed, 509 insertions(+) create mode 100644 _bmad-output/planning-artifacts/prds/prd-sar-2026-05-27/.decision-log.md create mode 100644 _bmad-output/planning-artifacts/prds/prd-sar-2026-05-27/prd.md diff --git a/_bmad-output/planning-artifacts/prds/prd-sar-2026-05-27/.decision-log.md b/_bmad-output/planning-artifacts/prds/prd-sar-2026-05-27/.decision-log.md new file mode 100644 index 0000000..0c3d8e5 --- /dev/null +++ b/_bmad-output/planning-artifacts/prds/prd-sar-2026-05-27/.decision-log.md @@ -0,0 +1,74 @@ +# Decision Log — SAR PRD MVP + +**Workspace:** `_bmad-output/planning-artifacts/prds/prd-sar-2026-05-27/` +**Iniciado:** 2026-05-27 +**Facilitador:** bmad-prd (Create · Fast Path) + +--- + +## Decisões + +### D-001 — Escopo MVP: Rafael + Sandra apenas +**Data:** 2026-05-27 +**Decisão:** MVP cobre cockpits Rafael (Representante) e Sandra (Supervisora). Daniel e Alice têm telas placeholder. +**Justificativa:** Julian definiu explicitamente: consulta de clientes, pedidos históricos, lançamento de pedido novo. Sandra foi incluída porque aprovação de desconto é inseparável do fluxo de pedido do Rafael. +**Impacto:** Cockpits Daniel e Alice ficam fora do escopo funcional. + +### D-002 — Aprovação de desconto inclusa no MVP +**Data:** 2026-05-27 +**Decisão:** Fluxo completo de aprovação (Rafael solicita → Sandra aprova/recusa) está no MVP (C5). +**Justificativa:** Julian confirmou explicitamente ao ser perguntado. +**Impacto:** Sandra precisa de cockpit funcional (painel + fila de aprovações + push). + +### D-003 — WhatsApp via Share API nativa no MVP +**Data:** 2026-05-27 +**Decisão:** Sem Meta Cloud API no MVP. Compartilhamento via Web Share API (abre WhatsApp nativo do device). +**Justificativa:** Reduz complexidade e custo de integração para o MVP. Meta Cloud API entra na próxima iteração. +**Impacto:** Nenhuma mensagem programática para clientes finais no MVP. + +### D-004 — ERP: importação manual no MVP +**Data:** 2026-05-27 +**Decisão:** Catálogo, pautas e clientes importados via arquivo (CSV/JSON) ou endpoint simples. Sem integração automática bidirecional no MVP. +**Justificativa:** Reduz escopo e depende do ERP específico do primeiro cliente (a definir). +**Impacto:** OQ-1 precisa ser resolvido com o primeiro cliente antes de C4. + +### D-005 — Working mode: Fast Path +**Data:** 2026-05-27 +**Decisão:** Julian optou por Fast Path (terse brief, referência a documentos existentes como fonte de verdade). +**Justificativa:** Documentos do Phase 1+2 (Brief + Trigger Map) estavam completos e detalhados. Extração via subagentes foi suficiente para draft completo. + +--- + +### D-006 — Fixes do reviewer gate aplicados +**Data:** 2026-05-27 +**Decisão:** 3 achados críticos do reviewer incorporados no PRD antes do `status: final`: +1. FR-2.4/FR-2.5 + NFR-3.3 — contradição sobre offline resolvida: situação resumida cacheada; limite numérico e inadimplência requerem conexão com disclaimer. +2. FR-4.11 (renumerado para FR-4.12) — adicionado FR para falha de sync: Pedido retorna ao Rep com status `falha de sync` + motivo legível, nunca descartado silenciosamente. +3. FR-4.7 — adicionada nota [OQ-2] para alçada por linha de produto. + +### D-007 — OQs triadas: non-blockers para PRD final +**Data:** 2026-05-27 +**Decisão:** PRD finalizado com todas as 6 OQs abertas. Classificação: +- **Phase-blockers para epics específicos** (não para o PRD): OQ-1 (C4), OQ-2 (C4/C5), OQ-4 (C2/C4), OQ-5 (C5) +- **Non-blockers**: OQ-3 (C7 — comissão FLEX pode ser placeholder), OQ-6 (TTL configurável) +- OQ-1 e OQ-4 dependem do primeiro cliente — devem ser resolvidas antes do início do design de C2/C4. + +### D-008 — PRD finalizado +**Data:** 2026-05-27 +**Status:** `final` +**Artefatos:** `prd.md` + `.decision-log.md` + `addendum.md` (não gerado — sem overflow de conteúdo) + +--- + +## Assumptions abertas (a confirmar com Julian) + +| ID | Assumption | Seção | +|----|-----------|-------| +| A-001 | Criação de usuários feita por admin JCS (sem self-service) | FR-1.5 | +| A-002 | Thresholds de inatividade (30/60d) configuráveis por workspace | FR-2.3 | +| A-003 | Catálogo de clientes sincronizado do ERP; Rafael não cria/edita | FR-2.6 | +| A-004 | Sync de catálogo com TTL de 4h | FR-4.4 | +| A-005 | Alçada de desconto default: 5% | FR-4.11 | +| A-006 | Qualquer supervisor do workspace pode aprovar qualquer pedido da equipe | FR-5.6 | +| A-007 | Sandra não acessa fichas de clientes individuais no MVP | FR-8.3 | +| A-008 | Sem suporte a browsers legados (IE etc.) | NFR-5.3 | diff --git a/_bmad-output/planning-artifacts/prds/prd-sar-2026-05-27/prd.md b/_bmad-output/planning-artifacts/prds/prd-sar-2026-05-27/prd.md new file mode 100644 index 0000000..9e7769b --- /dev/null +++ b/_bmad-output/planning-artifacts/prds/prd-sar-2026-05-27/prd.md @@ -0,0 +1,416 @@ +--- +title: "SAR — Força de Vendas: PRD MVP" +status: final +created: 2026-05-27 +updated: 2026-05-27 +project: sar +version: "0.1" +--- + +# SAR — Força de Vendas: PRD MVP + +## 1. Visão Geral + +**SAR** é uma plataforma SaaS web de força de vendas para PMEs brasileiras com 5–50 Representantes externos. Substitui o app Android/Desktop legado da JCS e resolve a dor central: **donos e supervisores decidem no escuro** enquanto 5–10% da Carteira esfria silenciosamente na rua. + +O produto entrega **quatro cockpits especializados** (Representante · Supervisor · Dono · Admin) compartilhando um único dado em tempo real. O MVP valida os dois cockpits de maior impacto operacional imediato: **Rafael** (Rep em campo) e **Sandra** (supervisora que aprova e monitora). + +**Por que agora:** janela de mercado de 2–3 anos antes de concorrentes se modernizarem. O primeiro cliente pagante em 3–4 meses valida o modelo e financia as próximas iterações. + +--- + +## 2. Objetivos e Métricas de Sucesso + +### North Star +> Primeiro cliente paga e **renova** nos primeiros 3 meses após go-live. + +### Métricas de comportamento (MVP) + +| Métrica | Alvo MVP | Sinal de problema | +|---------|----------|-------------------| +| Pedidos lançados pelo Rep no SAR vs. total | ≥ 90% | < 70% = adoção baixa | +| Tempo médio de lançamento de Pedido | < 2 min | > 5 min = UX ruim | +| Taxa de sincronização offline bem-sucedida | ≥ 99,5% | < 99% = risco de perda | +| Aprovações respondidas em < 30 min | ≥ 80% | < 60% = gargalo | +| Clientes Inativos >60 d visualizados/semana | ≥ 30% da lista | < 10% = feature ignorada | + +### Métricas de negócio JCS (Y1) +- 10–20 clientes pagantes até o mês 12 +- ARR R$ 200k–600k +- NPS donos > 50 + +### Counter-métricas +- Pedidos duplicados por falha de sync → alvo: 0 +- Reclamações de dado incorreto no histórico → alvo: < 2/mês/cliente + +--- + +## 3. Personas MVP + +### Rafael — Representante *(cockpit primário)* + +- **Perfil:** 30–50 anos, vendedor B2B externo, comissionado, atende 50–200 Clientes ativos +- **Device:** Mobile-first · PWA iOS (Android legado continua em paralelo) +- **Contexto de uso:** No carro, no posto, no fundo da loja. Conexão instável 3G/4G. Raramente na mesa. +- **Goals prioritários:** + - Bater meta mensal sem depender do escritório para informações + - Ter clareza absoluta da Carteira — saber sem pensar quem comprou, quando e quanto + - Lançar Pedido em menos de 60 segundos, mesmo sem sinal +- **Frustrações que o produto resolve:** + - Perde Pedido por bug ou ausência de sinal no app legado + - Comissão é mistério até o fechamento do mês + - Não sabe quais Clientes estão esfriando antes que seja tarde demais + - Precisa ligar para o escritório para consultar histórico de Cliente + +### Sandra — Supervisora *(cockpit secundário)* + +- **Perfil:** 35–55 anos, gerente comercial, coordena 5–30 Representantes, desktop o dia todo +- **Device:** Desktop-first · PWA mobile-light (Aprovações em reuniões/almoço) +- **Contexto de uso:** Abre o SAR às 8h30. Checagem diária, Aprovações durante reuniões, fechamento de semana. +- **Goals prioritários:** + - Saber o que está acontecendo na rua sem precisar ligar para os Reps + - Aprovar descontos com contexto real (histórico, margem, alçada) em segundos + - Identificar problemas no time antes que virem perda de Cliente +- **Frustrações que o produto resolve:** + - Aprova desconto no WhatsApp sem nenhum contexto + - Descobre tarde demais que um Cliente-chave parou de comprar + - Não tem visão consolidada dos Pedidos do dia em tempo real + +--- + +## 4. Escopo do MVP + +### Dentro do escopo + +| # | Capacidade | Cockpit | +|---|-----------|---------| +| C1 | Autenticação e acesso por papel | Todos | +| C2 | Consulta de Clientes (lista + ficha) | Rafael | +| C3 | Consulta de Pedidos históricos | Rafael | +| C4 | Lançamento de Pedido novo (online + offline) | Rafael | +| C5 | Fluxo de Aprovação de desconto | Rafael → Sandra | +| C6 | Push notification de Aprovação | Sandra → Rafael | +| C7 | Painel Rafael (meta, KPIs, alertas de Inativo) | Rafael | +| C8 | Painel Sandra (Pedidos do dia, fila de Aprovações) | Sandra | +| C9 | Onboarding de workspace (admin interno JCS) | — | + +### Fora do escopo (MVP) + +- Cockpit Daniel (BI + IA estratégica) → placeholder de tela apenas +- Cockpit Alice (campanhas, ICMS-ST, pautas) → placeholder de tela apenas +- Editor visual de campanhas no-code +- Assistente IA por NCM/UF para ICMS-ST +- WhatsApp conversacional bidirecional (apenas Share API nativo) +- App nativo iOS/Android +- Integração automática com ERPs externos +- Benchmark cross-tenant +- Agenda + check-in GPS *(desejável; entra se não comprometer prazo)* + +--- + +## 5. Jornadas de Usuário + +### UJ-1 — Rafael lança Pedido em campo (fluxo principal) + +> Rafael está na frente do comprador na distribuidora. Abre o SAR no celular (4G fraco). + +1. Rafael abre a ficha do Cliente pelo nome — vê histórico e limite de crédito disponível +2. Toca em "Novo Pedido" — catálogo carrega do cache offline +3. Adiciona produtos por busca ou lista de favoritos +4. O sistema sugere o desconto máximo dentro da alçada de Rafael +5. Rafael aplica desconto de 8% (dentro da alçada de 10%) — Pedido vai direto para confirmação +6. Rafael confirma — Pedido entra na fila offline com Idempotency-Key +7. Ao recuperar sinal, o Pedido sincroniza automaticamente — Rafael recebe confirmação silenciosa +8. Cliente recebe resumo via Share API (WhatsApp nativo do celular de Rafael) + +*Variação offline:* os passos 6 e 7 ocorrem com delay. O Pedido aparece como "pendente sincronização" na lista. + +### UJ-2 — Rafael solicita Aprovação de desconto acima da alçada + +> Rafael quer dar 15% de desconto; sua alçada é 10%. + +1. Rafael digita 15% — o sistema avisa "acima da sua alçada (10%). Enviar para Aprovação?" +2. Rafael confirma — Pedido vai para Sandra com status `aprovação pendente` +3. Sandra recebe push notification com contexto: Cliente, valor, desconto solicitado, histórico +4. Sandra abre a notificação no celular (ou no Painel desktop) — vê histórico do Cliente +5. Sandra aprova ou recusa com um toque, podendo ajustar o percentual +6. Rafael recebe push notification: "Pedido #1234 aprovado — 13%" e o Pedido entra em sincronização + +### UJ-3 — Sandra monitora o dia (fluxo diário) + +> Sandra chega às 8h30 e abre o SAR no notebook. + +1. Painel mostra: Pedidos do dia, fila de Aprovações pendentes, alertas de Inativos por Rep +2. Sandra vê que o Rep Marcos tem 3 Clientes Inativos há mais de 60 dias — acessa a lista +3. Abre a fila de Aprovações: 2 Pedidos aguardando. Resolve os dois com contexto visível +4. À tarde: recebe push no celular durante o almoço — Aprovação urgente. Resolve em segundos + +--- + +## 6. Requisitos Funcionais + +### C1 — Autenticação e Acesso + +**FR-1.1** O sistema autentica usuários via master-login (IdP OAuth2/OIDC próprio da JCS). + +**FR-1.2** Cada usuário tem exatamente um papel no workspace: `representante` · `supervisor` · `dono` · `admin`. O papel define qual cockpit é exibido e quais operações são permitidas. + +**FR-1.3** O acesso a workspaces é isolado fisicamente por banco de dados (BD-por-workspace, ADR 0006). Nenhum usuário acessa dados de outro workspace, nem mesmo administradores da JCS. + +**FR-1.4** O sistema bloqueia acesso e retorna HTTP 404 (não 403) quando o usuário autenticado não tem permissão sobre um recurso — para não vazar a existência do recurso. + +**FR-1.5** [ASSUMPTION] Criação de usuários e workspaces é feita por administrador interno da JCS (não self-service no MVP). Onboarding assistido. + +--- + +### C2 — Consulta de Clientes + +**FR-2.1** O Rep lista todos os Clientes da sua Carteira com busca por nome, razão social e CNPJ/CPF. + +**FR-2.2** A lista exibe, para cada Cliente: nome, última compra (data + valor), status de atividade (`ativo` · `em alerta` · `inativo`) e se há Pedidos em aberto. + +**FR-2.3** O status de atividade é calculado automaticamente: `inativo` = sem Pedido Faturado há mais de 60 dias; `em alerta` = 30–60 dias; `ativo` = menos de 30 dias. [ASSUMPTION] Thresholds configuráveis por workspace pelo admin. + +**FR-2.4** Ao abrir a ficha do Cliente, o Rep vê: +- Dados cadastrais: nome, CNPJ/CPF, endereço de entrega, telefone, e-mail +- Situação financeira resumida (`regular` · `atenção` · `bloqueado`) — disponível offline (cacheada) +- Limite de crédito disponível (valor numérico) — **requer conexão**; exibido com disclaimer "dados de até [hora da última sync]" quando offline +- Histórico de inadimplência — **requer conexão**; não cacheado offline +- Últimos 10 Pedidos com status e valor +- Comissão gerada pelo Cliente no mês atual e no mês anterior + +**FR-2.5** A lista de Clientes, dados cadastrais, situação financeira resumida e os últimos 10 Pedidos estão disponíveis offline após a última sincronização. Dados financeiros sensíveis (limite de crédito numérico, inadimplência) requerem conexão. + +**FR-2.6** [ASSUMPTION] O cadastro de Clientes é sincronizado do ERP legado da empresa. O Rep não cria nem edita Clientes no MVP. + +--- + +### C3 — Consulta de Pedidos Históricos + +**FR-3.1** O Rep visualiza todos os Pedidos da sua Carteira com filtros por: Cliente, status, período (padrão: últimos 90 dias) e número do Pedido. + +**FR-3.2** Cada Pedido exibe: número, Cliente, data de emissão, status (`orçamento` · `aprovação pendente` · `aprovado` · `faturado` · `cancelado`), valor total e desconto aplicado. + +**FR-3.3** Ao abrir um Pedido, o Rep vê: itens (produto, quantidade, preço unitário, desconto, subtotal), status de Aprovação (com quem está e desde quando, se pendente) e histórico de alterações de status. + +**FR-3.4** Pedidos com status `aprovação pendente` têm indicador visual destacado na lista. + +**FR-3.5** O histórico dos últimos 90 dias está disponível offline após sincronização. Pedidos mais antigos requerem conexão. + +--- + +### C4 — Lançamento de Pedido Novo + +**FR-4.1** O Rep inicia um novo Pedido a partir da ficha do Cliente ou da tela inicial. + +**FR-4.2** O fluxo de lançamento funciona completamente offline. Pedidos criados sem conexão são enfileirados localmente (IndexedDB) e sincronizados automaticamente quando o sinal é restaurado. + +**FR-4.3** Cada Pedido é identificado por um `Idempotency-Key` gerado localmente antes do envio, garantindo que retentativas de sync não criem Pedidos duplicados. + +**FR-4.4** O catálogo de produtos (código, descrição, preço de tabela, estoque disponível, foto) fica cacheado localmente para uso offline. [ASSUMPTION] A sincronização do catálogo ocorre ao abrir o app com conexão ativa, com TTL de 4h. + +**FR-4.5** O Rep adiciona produtos ao Pedido por: busca por nome/código, lista de favoritos pessoais ou lista dos produtos mais comprados pelo Cliente. + +**FR-4.6** Para cada item, o Rep define quantidade e percentual de desconto. O sistema exibe o preço resultante e o subtotal em tempo real. + +**FR-4.7** O sistema valida o desconto contra a alçada do Rep **antes** da submissão: + - Dentro da alçada: Pedido segue direto para confirmação (FR-4.8) + - Acima da alçada: Pedido entra no fluxo de Aprovação (C5) + - [OQ-2] Se a alçada variar por linha de produto, a validação ocorre item a item; o Pedido só vai para Aprovação se ao menos um item exceder a alçada da sua linha. + +**FR-4.8** Na tela de confirmação, o Rep vê: resumo dos itens, valor total, desconto médio, status do limite de crédito do Cliente e botão "Confirmar Pedido". + +**FR-4.9** Após confirmação, o sistema: + - Registra o Pedido com status `orçamento` (dentro da alçada) ou `aprovação pendente` (acima da alçada) + - Exibe confirmação imediata ao Rep, mesmo que a sincronização ainda não tenha ocorrido + - Disponibiliza opção de compartilhar resumo do Pedido via Share API (WhatsApp nativo) + +**FR-4.10** O Rep visualiza Pedidos pendentes de sync em uma lista local, com indicação clara de "aguardando conexão". + +**FR-4.11** Se o servidor rejeitar um Pedido da fila offline (produto inativo, Cliente bloqueado, pauta vencida), o Pedido retorna ao Rep com status `falha de sync` e motivo legível em linguagem humana. O Pedido nunca é descartado silenciosamente — fica visível na fila com opção de editar e reenviar ou cancelar. + +**FR-4.12** [ASSUMPTION] A alçada de desconto é configurada por Rep pelo admin do workspace. Default: 5%. + +--- + +### C5 — Fluxo de Aprovação de Desconto + +**FR-5.1** Quando um Pedido exige Aprovação, o supervisor responsável recebe push notification e o Pedido é incluído na fila de Aprovações. + +**FR-5.2** A fila de Aprovações exibe, para cada Pedido pendente: Rep, Cliente, valor total, desconto solicitado vs. alçada, tempo aguardando e indicador de urgência (> 2h sem resposta). + +**FR-5.3** Ao abrir um Pedido para aprovar, o supervisor vê: + - Resumo do Pedido (itens, valores, desconto) + - Histórico do Cliente: últimas compras, inadimplência, volume no período + - Alçada do Rep e justificativa do desconto (campo livre, opcional) + +**FR-5.4** O supervisor pode: **aprovar** (com o desconto solicitado), **aprovar com ajuste** (definir percentual diferente) ou **recusar** (com motivo obrigatório). + +**FR-5.5** Após a decisão: + - O Rep recebe push notification com o resultado + - O status do Pedido é atualizado em tempo real no Painel de ambos + - Se aprovado, o Pedido avança para status `aprovado`; se recusado, retorna ao Rep com o motivo + +**FR-5.6** [ASSUMPTION] No MVP, qualquer supervisor do workspace pode aprovar qualquer Pedido da sua equipe. Hierarquia de Aprovação com múltiplos níveis é pós-MVP. + +--- + +### C6 — Notificações e Push + +**FR-6.1** O sistema envia Web Push Notification para: + - Sandra: novo Pedido aguardando Aprovação (com preview: Rep, Cliente, valor) + - Rafael: Aprovação concedida ou recusada (com resultado e eventual ajuste) + +**FR-6.2** Notificações push funcionam com o navegador em background (PWA). + +**FR-6.3** O sistema exibe um badge de contagem no ícone de notificações na Topbar com o total de itens pendentes de ação. + +**FR-6.4** O Rep compartilha o resumo de um Pedido confirmado via Share API do browser (abre o WhatsApp nativo ou qualquer app de mensagens do dispositivo). [ASSUMPTION] O conteúdo compartilhado é texto formatado com os itens e o valor total; link para visualização futura é pós-MVP. + +--- + +### C7 — Painel Rafael + +**FR-7.1** O Painel do Rep exibe, ao abrir o app: + - Saudação com nome e data atual + - Meta do mês (valor atingido / valor total, percentual e progresso visual) + - Valor faltante para atingir a meta + - Comissão acumulada no mês (valor fixo + FLEX, quando aplicável) + +**FR-7.2** O Painel lista os Clientes Inativos da Carteira do Rep, ordenados por dias sem compra (decrescente). Clientes com mais de 60 dias têm destaque visual. + +**FR-7.3** O Painel exibe os Pedidos recentes (últimos 7 dias) com status e indicação de pendentes de sync. + +**FR-7.4** Todos os dados do Painel são acessíveis offline após a última sincronização. A data e hora da última sync são visíveis. + +--- + +### C8 — Painel Sandra + +**FR-8.1** O Painel da supervisora exibe, ao abrir o app: + - Fila de Aprovações pendentes (ordenada por tempo aguardando) + - Resumo dos Pedidos do dia da equipe: total de Pedidos, valor consolidado e comparativo com a mesma semana do mês anterior + - Alertas de Clientes Inativos por Rep (top 3 Reps com maior número de Inativos) + +**FR-8.2** O Painel atualiza em tempo real via Socket.IO/SSE: novos Pedidos, mudanças de status e novas Aprovações pendentes. + +**FR-8.3** [ASSUMPTION] No MVP, Sandra não acessa fichas de Clientes individuais nem histórico de Pedidos por Rep diretamente — apenas o que aparece no Painel e na fila de Aprovações. Drill-down por Rep é próxima iteração. + +--- + +## 7. Requisitos Não-Funcionais + +### Performance + +**NFR-1.1** Operações CRUD (consulta de Cliente, histórico de Pedidos, confirmação de Pedido): p99 < 800 ms. + +**NFR-1.2** Carregamento inicial do Painel (dados do dia): p99 < 2 s com conexão 4G. + +**NFR-1.3** Sincronização de Pedido offline pendente após retorno de conexão: início do envio em menos de 5 s. + +**NFR-1.4** Atualização em tempo real no Painel da Sandra (novo Pedido aparece): menos de 3 s após o evento. + +### Offline (Rafael) + +**NFR-2.1** Rafael consulta Clientes, visualiza histórico e lança Pedidos completos sem nenhuma conexão de rede, usando os dados da última sincronização. + +**NFR-2.2** Pedidos criados offline são persistidos no IndexedDB com `Idempotency-Key` gerado localmente, garantindo envio único quando a conexão é restaurada. + +**NFR-2.3** O app detecta automaticamente a perda e o retorno de conexão e sincroniza a fila sem ação do usuário. + +**NFR-2.4** Em nenhuma circunstância um Pedido pode ser perdido silenciosamente. Falhas de sync devem ser exibidas visivelmente para o Rep. + +### Segurança e LGPD + +**NFR-3.1** PII de Clientes (CPF/CNPJ, telefone, e-mail) é redactada nos logs de aplicação. + +**NFR-3.2** Dados de Clientes e Pedidos são fisicamente isolados por workspace (BD-por-workspace, ADR 0006). Nenhuma query atravessa workspaces. + +**NFR-3.3** O armazenamento offline (IndexedDB) contém apenas os dados mínimos necessários para o fluxo de lançamento de Pedido. Dados financeiros sensíveis (limite de crédito completo, histórico de inadimplência) requerem conexão. + +**NFR-3.4** Tokens JWT são armazenados em memória (nunca em localStorage). Refresh token em cookie `httpOnly; Secure; SameSite=Lax`. + +**NFR-3.5** Rate limit em endpoints de autenticação: 5 tentativas/min/IP. + +**NFR-3.6** Todo opt-in para Web Push é explícito, com possibilidade de revogar a qualquer momento. + +### Acessibilidade + +**NFR-4.1** Interfaces seguem WCAG AA para contraste, tamanho de alvo touch (mínimo 44 px) e suporte a leitor de tela. + +**NFR-4.2** Score Lighthouse ≥ 90 em Performance, Acessibilidade e Best Practices — gate obrigatório de CI. + +### Compatibilidade + +**NFR-5.1** Rafael: Safari iOS 17+ e Chrome Android 120+ (PWA com offline, Web Push, Share API, Geolocation). + +**NFR-5.2** Sandra: Chrome 120+ e Safari 17+ em desktop. Layout responsivo até 1280 px. + +**NFR-5.3** [ASSUMPTION] Sem suporte a IE ou browsers legados. + +### Disponibilidade + +**NFR-6.1** SLA de disponibilidade: 99,5% em horário comercial (7h–21h BRT, seg–sáb). + +**NFR-6.2** Janela de manutenção: domingos das 2h–6h BRT, comunicada com 48h de antecedência. + +--- + +## 8. Integrações + +### 8.1 Master-login (IdP JCS) — *Obrigatório* +Autenticação e gestão de usuários/workspaces via OAuth2/OIDC. Usuários e papéis são gerenciados pelo IdP; o SAR atua como resource server. + +### 8.2 WhatsApp — *Share API nativa (MVP)* +O compartilhamento de Pedidos usa a Web Share API nativa do device (abre WhatsApp ou qualquer app de mensagens). Nenhuma integração com Meta Cloud API no MVP. [ASSUMPTION] WhatsApp Business API (mensagens programáticas) entra na próxima iteração. + +### 8.3 ERP Legado — *Sync via importação* +[ASSUMPTION] Catálogo de produtos, pautas de preço e cadastro de Clientes são importados do ERP legado via arquivo (CSV/JSON) ou endpoint configurável pelo admin. O SAR é o sistema de registro dos Pedidos novos; o ERP continua sendo o sistema de faturamento. Integração bidirecional automática é pós-MVP. + +### 8.4 Web Push — *Nativo* +Via Push API do browser + Service Worker. Sem provedor SaaS externo de push no MVP. + +--- + +## 9. Restrições Técnicas e de Design + +- **Stack:** STACK.md v2.2 é canônica e imutável sem RFC. Node 24 · Nest 11 · Prisma 7 · React 19.2 · AntD 6.4 · PostgreSQL 18 · multi-tenancy BD-por-workspace. +- **Brand:** `brand.md` é canônico. Paleta JCS Blue `#004a99`, Plus Jakarta Sans, Topbar 80 px + Sidebar 260 px, radius 12/20 px. +- **Vocabulário do produto:** Cliente · Representante/Rep · Orçamento · Pedido · Faturado · Visita · Carteira · Inativo · Painel · Aprovação. Nunca "Lead", "Prospect" ou "Ticket". +- **Infraestrutura:** Proxmox on-prem Brasil. Sem AWS/GCP/Azure. Cloudflare como CDN/proxy. +- **LGPD by design:** datacenter BR, PII criptografada, redact em logs, Art. 18 implementado. +- **Ambiente de desenvolvimento:** Docker Compose dev com Postgres 18, Valkey 8, MinIO e Mailpit — todos com healthcheck validado. + +--- + +## 10. Questões Abertas + +| # | Questão | Impacto | Responsável | Prazo | +|---|---------|---------|-------------|-------| +| OQ-1 | Catálogo de produtos e pautas de preço: formato e frequência de importação do ERP legado? | Alto — bloqueia FR-4.4 | Julian + primeiro cliente | Antes do design de C4 | +| OQ-2 | Alçada de desconto: é fixa por Rep ou pode variar por linha de produto? | Médio — impacta FR-4.7 e FR-4.11 | Julian | Antes de C4/C5 | +| OQ-3 | Comissão FLEX: a fórmula de cálculo está documentada? | Médio — impacta FR-7.1 | Julian | Antes de C7 | +| OQ-4 | Limite de crédito: é calculado no SAR ou importado do ERP? | Alto — impacta FR-2.4 e FR-4.8 | Julian + primeiro cliente | Antes de C2/C4 | +| OQ-5 | Múltiplos supervisores: se houver mais de um no workspace, como se distribui a fila de Aprovações? | Médio — impacta FR-5.1 | Julian | Antes de C5 | +| OQ-6 | Catálogo offline: TTL de 4h é aceitável para o primeiro cliente? Há risco de Rep vender produto fora de pauta? | Médio — impacta FR-4.4 | Julian + primeiro cliente | Antes de C4 | + +--- + +## 11. Fora do Escopo (explícito) + +- Cockpit Daniel (dashboard executivo + IA estratégica) — tela placeholder apenas +- Cockpit Alice (campanhas, ICMS-ST, pautas, cadastros) — tela placeholder apenas +- Editor visual de campanhas no-code +- Assistente IA por NCM/UF +- WhatsApp conversacional bidirecional (Meta Cloud API) +- Agenda e roteamento de visitas com GPS +- App nativo iOS ou Android +- Integração automática bidirecional com ERP +- Multi-empresa por workspace (uma empresa por workspace no MVP) +- Benchmark cross-tenant anonimizado +- Dark mode *(desejável, não bloqueante)* +- Relatórios exportáveis (PDF/Excel) + +--- + +*Documento gerado em 2026-05-27 via bmad-prd (Fast Path). Assumptions marcados — revisar com Julian antes do início de C4 e C5.* diff --git a/design-artifacts/_progress/00-design-log.md b/design-artifacts/_progress/00-design-log.md index dcf5fbe..844abda 100644 --- a/design-artifacts/_progress/00-design-log.md +++ b/design-artifacts/_progress/00-design-log.md @@ -369,6 +369,25 @@ 2. **Master-login stub + WorkspacePrismaPool** (frente arquitetural pesada — depende do PRD). 3. **OpenTelemetry SDK** plugar quando entrar no catálogo. +### 2026-05-27 — PRD MVP FINALIZADO ✅ (`status: final`) +- **Workspace:** `_bmad-output/planning-artifacts/prds/prd-sar-2026-05-27/` +- **Artefatos:** `prd.md` (final) + `.decision-log.md` (8 decisões registradas) +- **Working mode:** Fast Path — Julian definiu escopo em uma frase; documentos Phase 1+2 foram fonte de verdade via extração por subagentes. +- **Escopo MVP fechado:** 9 capacidades (C1–C9) · 45 FRs · 3 jornadas de usuário · 6 NFRs — cockpits Rafael + Sandra. +- **Cockpits fora do MVP:** Daniel e Alice → telas placeholder apenas. +- **Decisões chave:** + - WhatsApp = Share API nativa (sem Meta Cloud API no MVP) + - ERP = importação manual (CSV/JSON); sem integração automática + - Aprovação de desconto inclusa no MVP (confirmado explicitamente) + - Limite de crédito numérico e inadimplência requerem conexão (não cacheados offline) + - Falha de sync: Pedido retorna com status `falha de sync` + motivo; nunca descartado silenciosamente +- **OQs abertas (6):** OQ-1/OQ-4 são phase-blockers para C2/C4 — dependem do primeiro cliente. OQ-3/OQ-6 são non-blockers. +- **Reviewer gate:** 1 revisor subagente — veredito "Aprovado com Ressalvas"; 3 achados incorporados antes do `final`. +- **Pendente próxima sessão (ordem atualizada):** + 1. **Master-login stub + WorkspacePrismaPool** — frente arquitetural pesada. PRD está pronto; pode iniciar modelagem de domínio. + 2. **OpenTelemetry SDK** plugar quando entrar no catálogo. + 3. **Design C2/C4** (Consulta de Clientes + Lançamento de Pedido) — após resolver OQ-1 e OQ-4 com o primeiro cliente. + --- ## About This Folder