Capacidades

Antes de pensar em telas, pense em capacidades. Cada capability é um verbo + outcome testável, executável em qualquer surface — tela web, app mobile, API REST, ferramenta MCP pra agente, chatbot, voz. São 16 capacidades agrupadas em 6 grupos. Pra mapeamento UI legado, veja Mapa de Telas.

Por que capability-first? Telas eram o default de escopo de SaaS entre 2000–2010 porque cliente fechava contrato por número de telas entregues. Hoje a mesma capability “Cliente assina recorrência” se manifesta em 5 surfaces: web, mobile, MCP tool para agente, chatbot, voz. Modelar por capability é futureproof — a tela vira uma manifestação possível, não o unit de escopo.

🟦 capability🟨 atores🟥 hotspot / TBD

G1 · Aquisição (Visitante)

G1Visitante

C1Descobrir catálogo e montar cestaVisitante

Outcome visitante seleciona produtos e quantidade; vê resumo parcial em tempo real

Critério carrinho persiste itens; total atualiza <200ms após mudança

SurfacesTela: T1, T2, T3API REST: —MCP: —Voz / Bot: —

Eventos “Item adicionado ao carrinho”, “Resumo parcial atualizado” → Process #t1

C2Escolher máquina de espresso (condicional)Visitante (novo)

Outcome novo cliente seleciona modelo; cliente existente pula etapa

Critério lógica “novo cliente” testável; skip implementado

SurfacesTela: T4API REST: —MCP: —Voz: —

Eventos “Modelo de máquina selecionado” → Process #t4

EC-02: critério “novo cliente” ambíguo

C3Aceitar termos e submeter pedidoVisitante

Outcome pedido submetido com termos aceitos

Critério checkbox bloqueia submit; texto dos termos versionado

SurfacesTela: T5API REST: —MCP: —Voz: —

Eventos “Termos aceitos”, “Pedido submetido” → Process #t5

G2 · Conversão em Cliente (Visitante → Cliente)

G2Visitante → Cliente

C4Validar endereço de entregaVisitante

Outcome CEP da Grande SP confirmado e armazenado

Critério integração ViaCEP + lista municípios elegíveis

SurfacesTela: T6 (parte CEP)API REST: —MCP: —Voz: —

Eventos “CEP validado”, “Pedido bloqueado fora Grande SP” → Process #t6

ViaCEP sem SLA; RN-01 base Grande SP indefinida

C5Criar conta de clienteVisitante → Cliente

Outcome visitante vira cliente autenticado

Critério email único, senha hash, token de sessão

SurfacesTela: T6 (parte cadastro)API REST: —MCP: —Voz: —

Eventos “Conta de cliente criada”

C6Pagar e ativar assinatura recorrenteCliente

Outcome gateway autoriza débito recorrente; assinatura entra em estado Ativa

Critério tokenização do cartão; webhook do gateway → ativação idempotente

SurfacesTela: T7API REST: —MCP: —Voz: —

Eventos “Pagamento autorizado”, “Assinatura ativada”, “Número do pedido gerado”, “E-mail boas-vindas enviado” → Process #t7

EC-02: gateway Stripe vs Asaas indefinido

G3 · Autoatendimento (Cliente)

G3Cliente

C7Visualizar status da assinaturaCliente

Outcome cliente vê estado (Ativa / Suspensa / Aguardando), próxima cobrança, data de envio

SurfacesTela: T8 DashboardAPI REST: —MCP: —Voz: —

Eventos “Dashboard de assinatura visualizado” → Process #t8-t10

C8Atualizar dados cadastraisCliente

Outcome email, senha, cartão e endereço atualizados; CEP re-validado

Critério cartão re-tokenizado; endereço passa por C4 antes de gravar

SurfacesTela: T9API REST: —MCP: —Voz: —

Eventos “Dados cadastrais atualizados”, “Cartão atualizado”, “Endereço atualizado”

C9Alterar cesta para próximo cicloCliente

Outcome cliente edita cesta; alteração agendada para próximo ciclo (corte D-3)

Critério reuso de C1 (catálogo + carrinho); janela de corte respeitada

SurfacesTela: T10API REST: —MCP: —Voz: —

Eventos “Cesta alterada”, “Alteração agendada próximo ciclo”

EC-05: data de corte do ciclo indefinida

G4 · Operação Recorrente (Sistema)

G4Sistema

C10Processar cobrança mensalSistema

Outcome dia X (corte) → gateway debita; sucesso = ciclo OK; falha → retry; 3 falhas → suspende

Critério idempotência; trilha de auditoria; janela de retry configurável

SurfacesBackground jobAPI: webhook gatewayMCP: —Voz: —

Eventos “Ciclo iniciado”, “Cobrança processada”, “Retry iniciado”, “Assinatura suspensa por inadimplência” → Process #rec

C11Despachar pedido para logísticaSistema

Outcome pedido vai pra fila logística; NF-e emitida

SurfacesBackground jobAPI: provider logísticaMCP: —Voz: —

Eventos “Pedido despachado”, “NF-e emitida (placeholder)”, “Entrega confirmada”

Provider logística + sistema fiscal NF-e TBD

C12Enviar e-mails transacionaisSistema

Outcome boas-vindas, falha de cobrança, lembrete pré-cobrança, suspensão enviados

SurfacesBackground jobAPI: provider e-mailMCP: —Voz: —

Eventos “E-mail enviado”

Provider e-mail TBD (Resend? SendGrid?)

G5 · Governança (Admin)

G5Admin

C13Operar ciclo de vida da assinaturaAdmin

Outcome admin suspende, cancela ou força cobrança de uma assinatura específica

Critério máquina de estados definida (Ativa / Suspensa / Cancelada); idempotência em “forçar cobrança”

SurfacesTela: T12API REST: —MCP: —Voz: —

Eventos “Assinatura suspensa”, “Assinatura cancelada”, “Cobrança forçada”, “Log de auditoria gerado” → Process #t11-t13

EC-10: Suspensa ≠ Cancelada + “Forçar Cobrança” não-idempotente

C14Visualizar métricas operacionaisAdmin

Outcome admin vê KPIs (assinantes ativos, novas assinaturas mês, churn, faturamento recorrente estimado)

SurfacesTela: T11 Dashboard AdminAPI REST: —MCP: —Voz: —

Eventos “Dashboard de métricas administrativas visualizado”

C15Consultar clientes e auditoriaAdmin

Outcome admin busca cliente, vê histórico de interações e logs de alteração de endereço

SurfacesTela: T13API REST: —MCP: —Voz: —

Eventos “Lista de clientes consultada”, “Log de alteração visualizado”

G6 · Backstage (TBD — 🟥 crítico)

G6 🟥TBD — crítico

C16Gerenciar catálogo de produtosAdmin (provável)

Outcome a definir — gestão de cafés, bebidas, complementos, máquinas, preços, fotos, categorias

Critério a definir após resposta de Cliente Master Espresso às 5 perguntas

SurfacesCMS UI? TBDSeed estático? TBDSheet / API? TBD

EC-11 BACKSTAGE-CATALOG — ver Big Picture · Hotspot Crítico e Questões Abertas · catalogo

Grupo	Capacidades	Telas mapeadas
G1 · Aquisição	3 (C1–C3)	T1, T2, T3, T4, T5
G2 · Conversão	3 (C4–C6)	T6, T7
G3 · Autoatendimento	3 (C7–C9)	T8, T9, T10
G4 · Operação Recorrente	3 (C10–C12)	— (background)
G5 · Governança	3 (C13–C15)	T11, T12, T13
G6 · Backstage	1 (C16)	🟥 TBD
Total	16	13 telas

13 telas servem 12 das 16 capacidades. 4 capacidades operam sem tela (cronjobs/background) ou aguardam definição. Cada capability é independente da surface — pode ganhar exposição via API, MCP tool, voz no roadmap.

Arquitetura — Application Layer por capability

Premissa sênior: cada capability acima vira um use-case independente na pasta application/. Cada provider externo (gateway, CEP, e-mail, logística, catálogo) vira uma interface em infrastructure/ com um adapter default. Isso converte 3 dos 21 edge cases abertos (gateway · provider e-mail · provider logística) de “blockers de produto” em “swap de adapter” — reversível em ~1 dia cada.

apps/master-espresso/
├── src/
│   ├── domain/                      ← entidades + invariantes + state machine
│   │   ├── assinatura.ts            ← Pendente/Ativa/Inadimplente/Suspensa/Cancelada/AguardandoConfirmacao
│   │   ├── cliente.ts               ← persona: Visitante/ExCliente/ClienteAtivo
│   │   ├── pedido.ts                ← ciclo + itens cesta + entrega
│   │   ├── maquina-comodato.ts      ← nº série, status, prazo devolução
│   │   └── catalogo.ts              ← SKU café/bebida/complemento/máquina
│   │
│   ├── application/                 ← 1 use-case por capability (16)
│   │   ├── g1-aquisicao/
│   │   │   ├── adicionar-ao-carrinho.ts             ← C1
│   │   │   ├── escolher-maquina-comodato.ts         ← C2
│   │   │   └── aceitar-termos-e-submeter.ts         ← C3
│   │   ├── g2-conversao/
│   │   │   ├── validar-endereco-entrega.ts          ← C4 (usa CepValidator)
│   │   │   ├── criar-conta-cliente.ts               ← C5 (usa Auth)
│   │   │   └── ativar-assinatura.ts                 ← C6 (usa PaymentGateway)
│   │   ├── g3-autoatendimento/
│   │   │   ├── consultar-status.ts                  ← C7
│   │   │   ├── atualizar-dados-cadastrais.ts        ← C8
│   │   │   └── alterar-cesta-proximo-ciclo.ts       ← C9
│   │   ├── g4-operacao-recorrente/
│   │   │   ├── executar-ciclo-cobranca.ts           ← C10 (PaymentGateway + Notifier)
│   │   │   ├── despachar-pedido.ts                  ← C11 (LogisticsProvider)
│   │   │   └── enviar-notificacoes-recorrentes.ts   ← C12 (Notifier)
│   │   ├── g5-governanca/
│   │   │   ├── suspender-cancelar-assinatura.ts     ← C13
│   │   │   ├── consultar-kpis.ts                    ← C14
│   │   │   └── forcar-cobranca.ts                   ← C15 (guard duplo EC-10)
│   │   └── g6-backstage/
│   │       └── publicar-catalogo.ts                 ← C16 (CatalogStore — TBD)
│   │
│   └── infrastructure/              ← adapters trocáveis
│       ├── payment-gateway/
│       │   ├── interface.ts         ← PaymentGateway
│       │   ├── asaas.ts             ← default (ASSUMPTION-01)
│       │   └── stripe.ts            ← alternativa arquivada
│       ├── cep-validator/
│       │   ├── interface.ts         ← CepValidator
│       │   ├── viacep.ts            ← default
│       │   └── local-fallback.ts    ← cache + manual
│       ├── notifier/
│       │   ├── interface.ts         ← Notifier
│       │   ├── resend.ts            ← default e-mail (EC-17)
│       │   └── twilio-sms.ts        ← deferred
│       ├── logistics-provider/
│       │   ├── interface.ts         ← LogisticsProvider
│       │   ├── melhor-envio.ts      ← default (EC-12)
│       │   └── csv-import.ts        ← MVP fallback manual
│       ├── catalog-store/
│       │   ├── interface.ts         ← CatalogStore
│       │   ├── json-seed.ts         ← default MVP (EC-11)
│       │   └── supabase-cms.ts      ← deferred (CMS futuro)
│       └── auth/
│           ├── interface.ts         ← AuthProvider
│           └── supabase-auth.ts     ← default (magic link)

DOMAIN

Entidades + state machine (já modelada)
Invariantes — checados na entidade, não na DB
Zero deps em provider externo
Test puro com fixtures

APPLICATION

1 use-case = 1 capability
Entrada explícita (DTO) → saída (DTO ou evento)
Orquestra domain + chama interfaces de infra
Testável com mocks dos providers

INFRASTRUCTURE

Adapter por provider externo
interface.ts fixa o contrato
Swap = mudar import + DI; zero mudança em application/
Mocks pra teste em infrastructure/mocks/

Pay-off MVP: dos 21 edge cases, 3 (EC-02 gateway · EC-12 logística · EC-17 e-mail provider) viram “escolha de adapter” em vez de “blocker de produto”. Time pode entregar Fase 1 sem confirmação de Cliente Master Espresso nesses 3 — Asaas/Melhor Envio/Resend são defaults que rodam, troca depois custa ~1 dia cada.

🗂️ Mapa de Telas (auxiliar) — 13 telas por fluxo

Visão UI legada (paradigma 2010 do BRIEF). Mantida como referência para designers/devs. A visão primária é capability-first (acima) porque tela = uma manifestação possível de uma capability — a mesma “Cliente alterou cesta” pode aparecer em tela web, app mobile, MCP, chatbot ou voz. Página completa com funcionalidades por tela: /escopo/.

Fluxo	Telas	Capacidades servidas
E-commerce onboarding	T1, T2, T3, T4, T5, T6, T7	C1–C6
Painel Cliente	Dashboard, Dados Cadastrais, Alteração Recorrência	C7–C9
Painel Admin	Dashboard Admin, Gestão Assinaturas, Gestão Clientes	C13–C15