Big Picture
Do café no carrinho à assinatura recorrente em 14 eventos pivotais, agrupados em 4 atos narrativos. EventStorming nível 1 (Brandolini): só eventos 🟧, atores 🟨 e hotspots 🟥. Pra comandos, políticas e read models por tela, veja Processo Detalhado.
🟥 Hotspot crítico — Backstage de Catálogo ausente
Seção intitulada “🟥 Hotspot crítico — Backstage de Catálogo ausente”Nenhum ato modela quem carrega o catálogo. Eventos como “Catálogo de cafés exibido” aparecem como read-models, mas sem comando de origem. Bloqueia decisão de stack (CMS sim/não?) e escopo do Painel Admin. 5 perguntas pra Cliente Master Espresso antes de modelar Ato 0 · Backstage:
- Cadastro de produto: quem cadastra novo café, bebida, complemento ou máquina? CMS admin com UI dedicada, seed estático no deploy, ou planilha/CSV integrado?
- Frequência de alteração de preço: mensal, trimestral, ad-hoc? Define se precisa UI de edição em tempo real ou se deploy manual aceita.
- Estoque e disponibilidade: trackeado por SKU? Quando esgota, produto some do catálogo automaticamente ou continua exibido com badge “indisponível”?
- Foto e descrição: upload via admin (Supabase Storage / S3) ou apenas URL externa cadastrada manualmente?
- Categorias dinâmicas: as 3 categorias T1/T2/T3 (cafés, bebidas quentes, complementos) são fixas no código ou admin pode criar/renomear novas categorias e mover produtos entre elas?
→ Ver também Questões Abertas · referência cruzada EC-11 BACKSTAGE-CATALOG.
Funil de Onboarding · T1 → T7 (visão branch)
Seção intitulada “Funil de Onboarding · T1 → T7 (visão branch)”
flowchart TD
T1[T1 · Selecao de cafes] --> T2[T2 · Bebidas quentes]
T2 --> T3[T3 · Complementos]
T3 --> Q{Novo cliente?<br/>sessao + estado assinatura}
Q -->|sim / anonimo| T4[T4 · Escolha da maquina]
Q -->|cliente existente| T5
T4 --> T5[T5 · Revisao e termos]
T5 -->|cesta valida + termos aceitos| T6[T6 · Cadastro + CEP]
T5 -.->|cesta sem cafe RN-11| Block1[Bloqueado]
T6 --> CEP{CEP na Grande SP?}
CEP -->|sim| T7[T7 · Pagamento]
CEP -.->|nao EC-01| Wait[Lista de espera / mailing]
T7 -->|autorizado| Done([Assinatura ativada])
T7 -.->|recusado| Retry[Pendente · retry 24h]
Linhas pontilhadas = unhappy paths (Block / Wait / Retry). Linhas sólidas = happy path.
Ato 0 · Backstage de Catálogo (T0)
Seção intitulada “Ato 0 · Backstage de Catálogo (T0)”Admin do cliente Master Espresso alimenta o catálogo de SKUs (produtos + preços + fotos + categorias) que será exibido no carrinho do Ato 1.
Ato 1 · Descoberta do Catálogo (T1–T5)
Seção intitulada “Ato 1 · Descoberta do Catálogo (T1–T5)”Visitante navega o catálogo, monta a cesta de cafés + bebidas + complementos, escolhe máquina se for novo cliente, aceita os termos e submete o pedido.
EC-02 — critério “novo cliente” ambíguo: 3 personas distintas. Regra de negócio T3 (seleção de máquina) depende de qual persona entra no fluxo.
| Persona | Escolhe máquina (T3)? | Vai pra T6 CEP? | T7 pagamento? |
|---|---|---|---|
| Visitante anônimo (sem conta) | Sim | Sim | Sim |
| Ex-cliente (assinatura Cancelada / Suspensa) | Não (já tem) | Sim | Sim |
| Cliente ativo logado (assinatura Ativa) | N/A | N/A | → T10 |
Ato 2 · Conversão em Cliente (T6–T7)
Seção intitulada “Ato 2 · Conversão em Cliente (T6–T7)”Visitante vira cliente: informa CEP, cria conta, paga, e a assinatura é ativada.
Pagar.me suporta nativamente Pix Automático (cobrança recorrente via Pix conforme Bacen) e cartão recorrente tokenizado na mesma API — score 8/10 agentic (sandbox instantâneo, docs API-first). Pix e cartão são opções gêmeas no checkout: assinante escolhe. Stripe descartado: não suporta Pix Automático recorrente em BR (hard blocker per X research 2026-06-09). Custo estimado: ~0,99% por cobrança Pix Automático · 2,99% + R$0,29 por cobrança cartão recorrente.
✅ Decidido. Cliente Master Espresso só precisa abrir conta produção e nos liberar credenciais antes de S3.Ato 3 · Operação Recorrente (REC + T8–T10)
Seção intitulada “Ato 3 · Operação Recorrente (REC + T8–T10)”Sistema processa a cobrança mensal e despacha pedidos; provider de logística confirma entrega (ou registra falha); cliente acompanha e altera a cesta pelo painel.
NF-e emitida via integração Pagar.me + provider fiscal (eNotas/NFE.io conforme indicação Pagar.me) para MVP. Logística: Correios PAC com etiquetas via Melhor Envio API — sem contrato corporativo, cobertura nativa SP capital + Grande SP, custo estimado ~R$15–25 por caixa.
⚑ Confirmar com Cliente Master Espresso até início Semana 3.Ato 4 · Governança & Admin (T11–T13)
Seção intitulada “Ato 4 · Governança & Admin (T11–T13)”Admin Master Espresso opera o ciclo de vida das assinaturas, com trilha de auditoria.
ops-stack p/ scaffold automático.Ato 5 · Self-service do Cliente (T8’–T9’)
Seção intitulada “Ato 5 · Self-service do Cliente (T8’–T9’)”Cliente opera a própria assinatura — cancela, pausa, atualiza cartão ou endereço — sem precisar contatar Admin. Requisito legal: CDC art. 49 (direito de arrependimento, 7 dias).
Pausada separado, ou reusa Suspensa com flag de origem?Domínio Transversal · Comodato (cross-Atos T3 → REC → T13)
Seção intitulada “Domínio Transversal · Comodato (cross-Atos T3 → REC → T13)”Hardware físico (máquina) cria obrigações contratuais bidirecionais que cruzam todos os atos: despacho inicial em T3, ciclo de manutenção em REC, devolução pós-cancelamento em T13. Domínio ausente do BRIEF — modelo trata máquina como dado-de-graça.
Comunicação Transversal · Notificações ao Cliente
Seção intitulada “Comunicação Transversal · Notificações ao Cliente”Nenhum ato modela explicitamente comunicação — gap crítico em sistema de assinatura recorrente. Tabela abaixo lista os 7 triggers mínimos.
| Trigger (evento) | Notificação | Canal | SLA |
|---|---|---|---|
| Assinatura ativada (T7) | Boas-vindas + confirmação + termos | imediato | |
| Cobrança processada (REC) | Recibo + NF-e anexa | até 24 h | |
| Pagamento recusado (Inadimplente) | Alerta + link para atualizar cartão | EMAILSMS | imediato |
| Pedido despachado (T8) | Código de rastreamento + ETA | até 1 h pós-despacho | |
| Entrega falhou | Comunicado + próximos passos (reentrega / pickup) | EMAILSMS | imediato |
| Assinatura suspensa por SLA | Aviso de suspensão + link reativação | imediato | |
| Cesta alterada (T10) | Confirmação + lembrete data próximo ciclo | imediato |
Padrões de stack para envio: ver skill ops-stack → references/growth.md (Resend é o default Gabriel) + references/observability.md (delivery webhooks pra Sentry).
Máquina de Estados da Assinatura (T11–T13)
Seção intitulada “Máquina de Estados da Assinatura (T11–T13)”A ausência de uma máquina de estados explícita é o núcleo do hotspot EC-10. O diagrama e a tabela abaixo definem os seis estados válidos e todas as transições — incluindo o guard obrigatório em Forçar Cobrança para eliminar o risco de cobrança duplicada.
stateDiagram-v2
[*] --> Pendente: pedido submetido
Pendente --> Ativa: pagamento autorizado
Pendente --> Cancelada: 2 retries falharam (ativacao)
Ativa --> Inadimplente: ciclo mensal recusado
Inadimplente --> Ativa: retry confirmado (webhook)
Inadimplente --> Suspensa: retries esgotados
Ativa --> Suspensa: cliente suspendeu
Suspensa --> Ativa: cliente reativou
Suspensa --> Cancelada: SLA esgotado / cancelou
Ativa --> Cancelada: cancelamento direto
Ativa --> AguardandoConfirmacao: Forcar Cobranca [guard duplo]
AguardandoConfirmacao --> Ativa: webhook confirmou
AguardandoConfirmacao --> Inadimplente: webhook recusou
Cancelada --> [*]
note right of AguardandoConfirmacao
Guard (EC-10): status == Ativa
AND NOT cobranca_em_andamento(ciclo_atual)
Sem guard = cobranca duplicada
end note
| De | Para | Gatilho | Idempotência |
|---|---|---|---|
| Pendente | Ativa | Pagamento autorizado pelo gateway | Guard: event idempotency key único por transação |
| Ativa | Inadimplente | Ciclo mensal falhou (gateway recusou) | Guard: só transita uma vez por ciclo (idempotency key = assinatura + ciclo) |
| Inadimplente | Ativa | Retry bem-sucedido — webhook confirmou pagamento | Guard: webhook idempotency key pelo gateway |
| Inadimplente | Suspensa | Número máximo de retries esgotados (política: N tentativas em X dias) | Guard: só transita se status ainda for Inadimplente |
| Ativa | Suspensa | Cliente pediu suspensão pelo painel | Guard: idempotente (replayable) — status check antes de persistir |
| Suspensa | Ativa | Cliente reativou a assinatura (evento Reativada) | Guard: só transita se status == Suspensa |
| Suspensa | Cancelada | SLA de suspensão esgotado OU cliente cancelou explicitamente | Guard: Cancelada é terminal — sem retorno |
| Ativa | Cancelada | Cliente cancelou diretamente (sem passar por Suspensa) | Guard: Cancelada é terminal — sem retorno |
| Ativa | AguardandoConfirmação | Admin executou Forçar Cobrança — requer guard duplo | CRÍTICO — sem guard = cobrança duplicada (EC-10) |
| AguardandoConfirmação | Ativa | Webhook do gateway confirmou pagamento | Guard: webhook idempotency key pelo gateway |
| AguardandoConfirmação | Inadimplente | Webhook do gateway recusou pagamento | Guard: webhook idempotency key pelo gateway |
Guard obrigatório — Forçar Cobrança: a ação só pode ser disparada quando
assinatura.status == “Ativa” E NOT exists(cobranca_em_andamento(ciclo_atual)).
Sem esse guard duplo, um duplo-clique no painel admin (ou retry de requisição HTTP) cria duas cobranças no gateway para o mesmo ciclo. A flag cobranca_em_andamento deve ser persistida atomicamente junto com a transição para AguardandoConfirmação — nunca em memória.
Unhappy Paths (curto)
Seção intitulada “Unhappy Paths (curto)”Conversão bloqueada antes da criação de conta. Visitante vê cobertura limitada + opção de entrar na lista de espera (mailing). Nenhum evento de conta criada ou assinatura é emitido.
Fluxo completo: Process · unhappy-cep (TBD)
Assinatura criada com status Pendente (nunca Ativa). Retry automático em 24 h; após 2 tentativas sem sucesso, status muda para Cancelada por falha de ativação. Distinto dos retries do Ato 3, que se aplicam apenas a clientes ativos no ciclo recorrente.
Fluxo completo: Process · unhappy-ativacao (TBD)
Sistema aceita a alteração mas agenda para o ciclo seguinte (evento Cesta alterada agendada já existe no happy path). Hotspot: o cliente sabe disso? A UI mostra contagem regressiva até o próximo corte? Sem feedback visual, a expectativa de entrega no ciclo atual é frustrada silenciosamente.
Fluxo completo: Process · unhappy-corte (TBD)
📚 Processo Detalhado · 48 eventos + comandos + políticas + read models (swim lanes T1–T13 + REC)
O modelo Process Modeling (Brandolini nível 2) está em /eventstorming/process/ — visão completa por swim lane com todos os comandos (azul), políticas (lilás), agregados (amarelo) e read models (verde) que disparam cada evento. Página dedicada porque o scroll de 48 eventos é longo e inviabiliza inline.