Definição do Projeto — Master Espresso
Status: v0.3 — 5 assumptions aplicadas, aguardam confirmação de Gabriel
Projeto: 19245 — Sistema de Assinatura Master Expresso
Data: 2026-06-05
O que é este sistema
Seção intitulada “O que é este sistema”Master Espresso é uma plataforma de assinatura mensal de cápsulas e grãos de café. O cliente monta sua cesta de produtos mês a mês, recebe em casa e pode incluir uma máquina de espresso no contrato.
Modelo de negócio em 4 etapas:
- Cliente monta cesta de cafés, bebidas e complementos online
- Escolhe máquina (comodato ou assinatura adicional) — apenas novos assinantes
- Confirma endereço de entrega (somente Grande São Paulo — 39 municípios da RMSP)
- Assina com Pix Automático ou cartão recorrente automático (gateway Pagar.me) → entrega mensal, cobrança todo dia 10
Escopo: 13 telas
Seção intitulada “Escopo: 13 telas”Funil de aquisição — 7 telas
Seção intitulada “Funil de aquisição — telas”Fluxo público. Converte visitante em assinante.
| Tela | Nome | Obrigatória |
|---|---|---|
| T1 | Seleção de Cafés | Sim |
| T2 | Capuccinos, Chás e Chocolates | Sim |
| T3 | Açúcar, Adoçantes e Complementos | Sim |
| T4 | Escolha da Máquina | Condicional — só para quem não tem assinatura ativa |
| T5 | Revisão e Termos da Assinatura | Sim |
| T6 | Cadastro e Endereço de Entrega | Sim |
| T7 | Pagamento e Confirmação | Sim |
T4: Aparece para visitante não logado ou usuário logado sem assinatura ativa/suspensa. Cliente com assinatura existente pula direto para T5. (ASSUMPTION-02)
Painel do Cliente — 3 telas
Seção intitulada “Painel do Cliente — telas”Área logada. Assinante gerencia plano sem acionar suporte.
| Tela | O que faz |
|---|---|
| Dashboard | Status da assinatura, próxima cobrança (dia 10) e data de envio |
| Dados Cadastrais | Atualiza e-mail, senha, cartão e endereço de entrega |
| Alteração de Recorrência | Modifica cesta — aplica no próximo ciclo (corte D-3) |
Painel Administrativo — 3 telas
Seção intitulada “Painel Administrativo — telas”Área interna para a equipe da Master Expresso.
| Tela | O que faz |
|---|---|
| Dashboard Administrativo | KPIs: assinantes ativos, novas assinaturas, churn, faturamento estimado |
| Gestão de Assinaturas | Lista filtrada + ações: suspender, cancelar, forçar cobrança |
| Gestão de Clientes | Histórico de interações e logs de alteração de endereço |
Stack tecnológica
Seção intitulada “Stack tecnológica”6 de 7 componentes decididos. Gateway Pagar.me ratificado em 2026-06-09 (Pix Automático + cartão recorrente).
| Componente | Tecnologia | Status |
|---|---|---|
| Next.js + TypeScript | Next.js | ✅ Decidido |
| Tailwind CSS | Tailwind CSS | ✅ Decidido |
| Shadcn/ui | Shadcn/ui | ✅ Decidido |
| Supabase | PostgreSQL + Auth | ✅ Decidido |
| Gateway | Pagar.me (Pix Automático + cartão recorrente) | ✅ Decidido (ratificado 2026-06-09) |
| ViaCEP | ViaCEP API | ✅ Decidido |
Cronograma — 7 a 8 semanas
Seção intitulada “Cronograma — 7 a 8 semanas”- Semanas 1-2 — Setup, Arquitetura, BD e Frontend Fluxo Principal
Entregáveis: arquitetura_definida, modelagem_bd, telas_fluxo_principal_T01_T07 - Semanas 3-4 — Regras de Negócio, CEP, Checkout e Pagamento
Entregáveis: validacao_cep_grande_sp, integracao_gateway_pagamento, captura_recorrencia_mensal - Semanas 5-6 — Painel Cliente e Painel Admin
Entregáveis: painel_cliente_T08_T10, painel_admin_T11_T13 - Semanas 7-8 — Testes, Homologação, Ajustes e Deploy
Entregáveis: testes_cobranca_recorrente, responsividade_mobile, deploy_producao
Regras de negócio
Seção intitulada “Regras de negócio”11 regras — 3 com critério claro.
| Regra | Quando aplica | Critério claro? |
|---|---|---|
| Validação de CEP restrito à Grande SP | usuario submete CEP no cadastro ou edição de endereço de entrega | ❌ Requer validação |
| Tela 4 só para novo cliente | usuario avança do step 3 no fluxo de onboarding | ❌ Requer validação |
| Checkbox de termos obrigatório | usuario tenta clicar em Fechar Pedido sem marcar termos | ✅ Sim |
| Pagamento recorrente via Pix ou cartão | usuario escolhe método (Pix ou cartão) e confirma em T07 | ✅ Sim |
| Alteração de recorrência aplica no próximo mês | cliente salva alteração de recorrência em Tela 10 | ❌ Requer validação |
| Admin pode Suspender/Cancelar/Forçar Cobrança | usuario acessa Gestão de Assinaturas | ❌ Requer validação |
| Prazo mínimo de assinatura (comodato) | cliente solicita cancelamento via T8' Self-service ou Admin via T12 | ❌ Requer validação |
| Seguro de máquina em comodato | cliente reporta sinistro ou máquina não devolvida pós-cancelamento | ❌ Requer validação |
| Substituição/troca de modelo de máquina | cliente solicita troca de modelo via T8' Self-service | ❌ Requer validação |
| Prazo de devolução pós-cancelamento | evento `Assinatura cancelada` dispara timer de devolução | ❌ Requer validação |
| Cesta vazia bloqueia checkout | usuario tenta avançar de T05 para T06 com cesta sem café | ✅ Sim |
Riscos identificados
Seção intitulada “Riscos identificados”4 riscos mapeados (ausentes no BRIEF original):
| Risco | Prob. | Impacto | Mitigação |
|---|---|---|---|
| Pagar.me Pix Automático ainda em estabilização Bacen — fallback cartão recorrente caso fluxo Pix recorrente sofra mudança regulatória | baixa | medio | Adapter PaymentGateway expõe Pix + cartão; checkout default oferece ambas; caso Pix falhe, fluxo continua via cartão sem retrabalho de schema |
| Restrição de CEP à Grande SP com critério não definido pode bloquear usuários válidos | media | alto | Definir lista de municípios ou faixas de CEP autorizadas antes de implementar validação ViaCEP |
| ViaCEP é API externa gratuita sem SLA → risco de indisponibilidade afeta T06 e T09 | baixa | medio | Cache local de CEPs válidos + fallback de entrada manual de endereço |
| 'Forçar Cobrança' sem política de retry/idempotência → risco de cobrança dupla | media | alto | Definir máquina de estados de assinatura + idempotency key no gateway antes de implementar ação admin |
Assumptions aplicadas (aguardam confirmação de Gabriel)
Seção intitulada “Assumptions aplicadas (aguardam confirmação de Gabriel)”O BRIEF deixou 5 decisões em aberto. O time técnico adotou as opções de maior confiança para não bloquear o desenvolvimento. Gabriel pode sobrescrever qualquer item antes das semanas indicadas.
ASSUMPTION-01 — Gateway: Pagar.me (Pix Automático + cartão recorrente) ✅ RATIFICADA
Seção intitulada “ASSUMPTION-01 — Gateway: Pagar.me (Pix Automático + cartão recorrente) ✅ RATIFICADA”Status atualizado 2026-06-09: Gabriel ratificou Pagar.me como gateway oficial após Lane X research. Não aguarda mais sponsor.
Decidido: Pagar.me como gateway único, com Pix Automático (cobrança recorrente Bacen) e cartão recorrente tokenizado disponíveis no checkout. Assinante escolhe o método.
Por que Pagar.me: (a) Gateway brasileiro (BRL nativo, regulado pelo BACEN); (b) suporta nativamente os dois métodos must-have do produto — Pix Automático e cartão recorrente — na mesma API; (c) score 8/10 agentic (sandbox instantâneo, docs API-first, NF-e via integração com provider fiscal); (d) custo competitivo (~0,99% Pix · 2,99% + R$0,29 cartão).
Alternativas rejeitadas:
- Stripe — descartado por não suportar Pix Automático recorrente em BR (hard blocker per research 2026-06-09) + USD-fee + NF-e externa.
- Asaas — era o default anterior, mas perdeu pra Pagar.me em DX agentic (sandbox + API-first).
- MercadoPago — viável mas DX agentic inferior; mantido como fallback se Pagar.me sandbox falhar em S2.
O que ainda precisa do Cliente Master Espresso: abrir conta produção Pagar.me + habilitar Pix Automático + nos liberar credenciais antes de S3.
ASSUMPTION-02 — “Novo cliente”: cheque duplo (sessão + banco)
Seção intitulada “ASSUMPTION-02 — “Novo cliente”: cheque duplo (sessão + banco)”Assumido: Tela 4 (escolha de máquina) renderiza quando:
- Usuário não está logado (visitante anônimo), OU
- Usuário está logado mas não tem assinatura com status
ativaoususpensa
Cliente com assinatura cancelada recebe nova máquina pelo fluxo de novo cliente.
Por que: Status cancelada não implica máquina em casa — cliente pode ter devolvido. Tratar como novo cliente é a opção mais segura para conversão.
Janela para mudar: antes das Semanas 1-2 (modelagem de autenticação). Mudança de baixo custo se feita cedo.
ASSUMPTION-03 — Grande SP: 39 municípios da RMSP/IBGE
Seção intitulada “ASSUMPTION-03 — Grande SP: 39 municípios da RMSP/IBGE”Assumido: Lista estática dos 39 municípios da Região Metropolitana de São Paulo (RMSP, conforme IBGE/Decreto Estadual 52.052/2007). Validação via ViaCEP — campo localidade comparado contra a lista.
Municípios incluídos: São Paulo, Guarulhos, Osasco, Santo André, São Bernardo do Campo, São Caetano do Sul, Diadema, Mauá, Barueri, Carapicuíba, Taboão da Serra, Cotia, Embu das Artes, Mogi das Cruzes, Suzano e outros 24 da RMSP oficial.
Campinas NÃO está incluída (pertence à Região Metropolitana de Campinas, distinta).
Janela para mudar: antes das Semanas 3-4. Adicionar municípios = uma linha no código, zero refatoração.
ASSUMPTION-04 — Máquina: modelar ambos (comodato + assinatura adicional)
Seção intitulada “ASSUMPTION-04 — Máquina: modelar ambos (comodato + assinatura adicional)”Assumido: Sistema suporta dois modelos de contrato de máquina:
- Comodato: máquina incluída no plano, com fidelidade mínima de 12 meses e multa por rescisão antecipada. Manutenção por conta da Master Expresso.
- Assinatura adicional: máquina cobrada mensalmente (valor a definir), sem fidelidade obrigatória.
O BRIEF menciona “comodato ou assinatura” — modelar ambos permite que a Master Expresso decida qual oferecer na Tela 4 sem retrabalho de banco de dados.
Ponto crítico ainda em aberto: prazo de fidelidade (assumido 12 meses) e valor mensal da assinatura adicional precisam de confirmação antes do deploy em produção.
Janela para mudar: antes das Semanas 1-2 (modelagem do banco).
ASSUMPTION-05 — Recorrência: mensal fixa, cobrança todo dia 10, corte D-3
Seção intitulada “ASSUMPTION-05 — Recorrência: mensal fixa, cobrança todo dia 10, corte D-3”Assumido:
- Ciclo: mensal fixo (sem quinzenal ou bimestral no v1)
- Dia de cobrança: dia 10 de cada mês para todos os clientes
- Corte para alterações: D-3 (até o dia 7 → aplica no próximo mês; após dia 7 → aplica no mês subsequente)
Por que dia 10: Dia fixo facilita monitoramento operacional (pico concentrado, fácil de auditar). Dia 10 é distante do início e fim de mês, reduz conflitos com folha de pagamento dos clientes.
Alternativa: cobrança na data de cadastro (distribuído). Menos pico operacional, mas relatórios financeiros mais complexos.
Janela para mudar: antes das Semanas 3-4. Mudança de dia = uma linha na config; mudança de ciclo (ex: quinzenal) = mudança de schema.
Resumo das assumptions
Seção intitulada “Resumo das assumptions”| # | Assumption | Confiança | Bloqueia se errado |
|---|---|---|---|
| ASSUMPTION-01 ✅ | Gateway: Pagar.me (Pix Automático + cartão recorrente) — ratificado 2026-06-09 | Alta | — (decidido) |
| ASSUMPTION-02 | ”Novo cliente”: cheque duplo sessão+BD | Alta | Semanas 1-2 |
| ASSUMPTION-03 | Grande SP: 39 municípios RMSP/IBGE | Alta | Semanas 3-4 |
| ASSUMPTION-04 | Máquina: modelar comodato + assinatura_adicional | Média | Semanas 1-2 |
| ASSUMPTION-05 | Recorrência: mensal, dia 10, corte D-3 | Média | Semanas 3-4 |
Ação para Gabriel: revisar e marcar cada item como ✅ confirmado ou ❌ corrigir com a decisão correta. Sem feedback, o Builder avança com estas assumptions.
Gerado por joyous-triceratops (A1 Analyst v0.3) | 2026-06-05 | Tensão #133 + Task #9 — Para validação de Gabriel e apresentação a Cliente Master Espresso