Hub por módulos: landing pages, onboarding com Stripe e assistente MCP

Versão 1 · 11/09/2026 · acompanha o protótipo navegável (artefato "EcomSmart Hub Módulos")

1. Modelo comercial

Preço e regra comercial, iguais para os 5 módulos:

• Teste grátis de 7 dias, sem cobrança (cartão opcional no cadastro, obrigatório para continuar após o trial).
• R$ 99/mês nos 3 primeiros ciclos pagos, depois R$ 299/mês.
• Cota de 10.000 mensagens/mês por módulo. Custo Meta por conversa repassado a preço de tabela (já existe em CustoMensagemWhatsapp).
• Cada módulo é contratado, testado e cancelado de forma independente.

2. Revisão da arquitetura atual

2.1 Django (ecomsmart-hub-django)

O que já existe e será reaproveitado:

• Planos e assinatura: models/planos.py com Plano, PlanoPreco, Assinatura (status trial/ativa/suspensa/cancelada, trial_ate, referencia_externa, origem), Pagamento (append-only, idempotente por referencia_externa), ConsumoMensal. Services em services/planos.py (garantir_assinatura, assinatura_vigente, modulos_efetivos, sincronizar_modulos, registrar_consumo_mensagem, pode_enviar).
• Catálogo de módulos: MODULOS_CATALOGO em models/tenant.py (hoje principal, prospeccao, meta_leads, agentes_ia) e Empresa.modulos_habilitados.
• Onboarding self-service: só via Shopify (services/shopify_onboarding.py, ShopifyOnboardingService.bootstrap/confirmar/status/retry) e provisionamento por MCP (/api/admin/empresas/provisionar/, tool criar_empresa).
• SmartConversas: ContaSmartConversas → ApiSmartConversas → CanalSmartConversas, endpoints smartconversas/associar, apis/criar, canais; status por polling (30 min).
• Chokepoint de envio: services/whatsapp_dispatch.enviar_mensagem_canal (único lugar para aplicar cota).
• MCP: mcp_server/server.py (FastMCP, ~70 tools, quase todas de leitura), MCPToken por usuário, MCPMultiTenantMiddleware.
• IA: core/ai/claude_client.py, core/agentes/runtime.py, prompts versionados por nó.

Lacunas (zero ocorrências no repositório): Stripe; lookup de CNPJ; WhatsApp Flows; matching/inferência fuzzy; signup fora da Shopify; enforcement de cota (pode_enviar devolve sempre True); gating de endpoint por módulo (o JSON modulos_habilitados só monta menu).

Pontos de refatoração obrigatórios:

1. MODULOS_CATALOGO → 5 keys comerciais. Migração de dados traduz principal em carrinho + disparo + retencao para empresas atuais. Consumidores a ajustar: Plano.clean, Assinatura.clean, /api/admin/modulos/, tool modulos_disponiveis, modulos.config.ts no Angular.
2. TemplateWhatsapp.MODULOS_CHOICES (11 valores) passa a ser sub-uso dentro de um módulo comercial (ex.: aniversario e boas-vindas pertencem a retencao). Criar mapa SUBMODULO → MODULO em models/tenant.py e usá-lo no gating de templates.
3. Constraint uma_assinatura_vigente_por_empresa deixa de valer: ver §3.

2.2 Angular (ecomsmart-hub-angular)

Existe e será reaproveitado: Angular 21 standalone + signals + Tailwind 4 + biblioteca própria (~60 componentes em shared/components/, incluindo bottom-sheet, responsive-table, rfm-gate, funil, stat-card); infra de módulos (ModuloKey, MODULOS, ModuleService, moduleGuard, switcher, modulos_habilitados); telas de negócio dos 5 módulos dentro de features/comunicacoes/, analise-rfv/, agentes-ia/; layout com sidebar off-canvas em telas menores que 1024px; onboarding embutido da Shopify (features/shopify/shopify-app.component.ts) como molde de máquina de estados.

Lacunas: nenhuma rota pública além de login e nova-senha; sem cadastro; sem landing; zero referências a Stripe; moduleGuard redireciona com toast em vez de mostrar tela bloqueada; os 5 módulos comerciais não existem como ModuloKey; sem assistente conversacional embutido nas telas; sem layout público.

Tokens a manter: brand-600 #4f54e4, brand-950 #1d1e4c (sidebar), superfícies surface-50 #f8f9fc, texto #0f1117 / #5b6478 / #9aa3b2, fonte Inter. O protótipo introduz Sora apenas para títulos de landing/painel (opcional) e uma cor por módulo: carrinho #E8890C, disparo #3B6FE0, retenção #D64C8C, flow #7C3AED, campanhas #0E9F8A.

3. Modelo de domínio (novo e alterado)

Empresa (existente)
  + cnpj validado, razao_social, nome_fantasia, cnae, endereco_json   (preenchidos pelo lookup)
  + onboarding = JSON { passo, modulo_origem, utm, flags: {whatsapp, loja, stripe, smartconversas} }
  + stripe_customer_id

Assinatura (existente)  → passa a ser a CONTA DE COBRANÇA da empresa
  origem: direta | shopify | stripe        (+ 'stripe' em METODO_PAGAMENTO_CHOICES)
  (remover constraint uma_assinatura_vigente_por_empresa OU manter 1 Assinatura e mover
   o ciclo de vida para o item — recomendação: manter 1 Assinatura, ciclo de vida no item)

AssinaturaModulo (NOVO)
  assinatura FK · modulo (5 keys) · status: trial | ativa | inadimplente | cancelada
  trial_ate · fase: intro (3 ciclos R$99) | cheia (R$299) · ciclos_pagos
  stripe_subscription_id (UMA Subscription Stripe por módulo)
  cota_mensagens_mes = 10000 · cancelada_em
  UniqueConstraint (assinatura, modulo) WHERE status != cancelada

ConsumoMensal (existente) + coluna modulo  → UniqueConstraint (empresa, competencia, modulo)

Pagamento (existente) · referencia_externa = id do evento/invoice Stripe

MCPToken (existente) → key_hash (SHA-256), prefixo visível, escopos JSON, revogado_em
LogMcp (NOVO) usuario · origem (painel|claude_desktop|claude_ai|chatgpt) · tool · args · resultado · duracao

OnboardingEvento (NOVO) empresa · etapa · status · detalhe · criado_em   (auditoria do provisionamento)

Regra de gating (fonte única): services/modulos.py::modulos_ativos(empresa) -> set[key] lendo AssinaturaModulo com status trial|ativa. Cache por empresa (@cache_empresa), invalidado pelos webhooks Stripe.

4. Fluxo de cadastro e onboarding

Mobile first: uma decisão por tela, estado persistido em Empresa.onboarding, retomável.

1. Landing /lp/:slug → CTA grava modulo_origem + UTM → /cadastro?modulo=carrinho.
2. Cadastro: CNPJ com autocomplete (GET /api/publica/cnpj/?q=, proxy para o serviço listacnpj já em produção no cluster; debounce 300 ms, mínimo 8 dígitos), nome, WhatsApp, e-mail, senha ou Google. POST /api/auth/cadastro/ cria User + Empresa + UserPerfil(admin_empresa) + Assinatura + AssinaturaModulo(trial); loga por sessão.
3. Passo Empresa: confirma razão social, fantasia, endereço, CNAE, plataforma da loja, faixa de faturamento.
4. Passo Módulos: o módulo de origem já incluído; oferta dos outros 4 com uma linha de argumento cada; qualquer um pode ser adicionado ao trial.
5. Passo Pagamento (Stripe): POST /api/billing/setup-intent/ → Stripe Elements salva o cartão sem cobrar → POST /api/billing/assinar/ cria as Subscriptions (§5). Pode ser pulado ("Cadastrar cartão depois"); nesse caso o trial segue e o painel mostra aviso a partir do dia 5.
6. Passo WhatsApp (roda em paralelo com o provisionamento): Meta Embedded Signup via JS SDK → POST /api/canais-whatsapp/embedded-signup/ troca o code por token, cria CanalWhatsapp(tipo=oficial). Alternativa: informar WABA ID + Phone Number ID.
7. Passo Loja: escolha da Integracao (Shopify em 1 clique pelo app existente; Magazord/Nuvemshop/VTEX/Woo/CSV) → sync_integration backfill 24 meses. RFV nasce após o primeiro sync completo (guard já existente).
8. Pronto: três atalhos que acionam o assistente ("Ativar régua padrão", "Só capturar", "Personalizar").

Provisionamento SmartConversas (task Celery provisionar_smartconversas, fila express_queue, idempotente por etapa, registra OnboardingEvento):

1 login super → 2 criar estabelecimento → 3 créditos iniciais → 4 buscar/cadastrar usuário admin
5 autenticar → 6 usuário do cliente → 7 depto "Vendas" → 8 depto "Atendimento" → 9 pipeline padrão
10 campo customizado lead_id → 11 origem do lead → 12 senha padrão
13 (Hub) smartconversas/associar → 14 apis/criar (webhook_token) → 15 canais sync → 16 templates padrão do módulo enviados à Meta

GET /api/onboarding/status/ devolve a lista de etapas com done|running|todo|erro para a tela de progresso; POST /api/onboarding/retry/ reexecuta a etapa que falhou.

5. Stripe

Catálogo (criado uma vez, ids guardados em ParametroSistema):

• 5 Products (um por módulo) · 1 Price recorrente mensal R$ 299 BRL cada.
• 1 Coupon INTRO-99: R$ 200 off, duration=repeating, duration_in_months=3.
• Uma Subscription por módulo com trial_period_days=7 e o coupon aplicado. Vantagens: trial independente por módulo, cancelamento sem prorrata cruzada, fatura mostra um item por módulo. Cliente Stripe único por Empresa.

Endpoints:

Webhooks → efeito:

• customer.subscription.trial_will_end → notificação no painel + e-mail (dia 5).
• customer.subscription.updated → sincroniza status, fase (conta ciclos pagos para virar cheia após 3), trial_ate.
• invoice.paid → grava Pagamento (idempotente), status=ativa.
• invoice.payment_failed → status=inadimplente, grace de 7 dias, depois módulo bloqueado (as automações pausam via guard de task).
• customer.subscription.deleted → status=cancelada, tools MCP do módulo saem do registro.

Shopify continua como origem alternativa de cobrança (origem=shopify): a empresa vinda da Shopify recebe AssinaturaModulo conforme o shopify_plan_handle.

6. Gating por módulo

Backend:

• Decorator @require_modulo('carrinho') em api_admin/_helpers.py, ao lado de _require_empresa_admin; aplicado por família de rota em core/urls.py (tabela rota → módulo). Resposta 403 {codigo:'modulo_bloqueado', modulo, argumento}.
• Guard nas tasks: tasks/_guards.py::modulo_ativo_ou_pula(empresa, modulo) chamado no início de cada task de disparo; campanha agendada de módulo cancelado vira pausada com motivo.
• Cota: pode_enviar(empresa, modulo) passa a comparar ConsumoMensal(modulo) com a cota; ao atingir 100% bloqueia com codigo='cota_excedida'; 80% e 100% geram notificação.
• Templates: filtro ?modulo= usa o mapa submódulo → módulo comercial.

Frontend:

• moduleGuard(key) deixa de redirecionar e resolve para a mesma rota com bloqueado=true; o componente do módulo renderiza KPIs de exemplo + overlay de paywall contextual (GET /api/modulos/:key/argumento/ devolve um insight real da base, ex.: "610 clientes a recuperar").
• GET /api/auth/me/ devolve modulos: [{key, status, trial_fim, uso_ciclo, cota}].

7. Frontend Angular: nova estrutura

src/app/
  layouts/
    public-layout/        header marketing (links dos 5 módulos, Entrar, Testar grátis) + footer
    onboarding-layout/    barra de passos, sem sidebar, mobile first
    app-shell/            layout atual, sidebar = Início · Assistente · Meus módulos (5, com lock) · Minha base · Conta
  features/
    public/               landing/:slug (pré-render estático p/ SEO) · cadastro · login
    onboarding/           empresa · modulos · pagamento · whatsapp · loja · pronto  (+ status polling)
    home/                 início: KPIs consolidados, cards dos 5 módulos, sugestão do assistente
    modulos/
      carrinho/           dashboard · configurar · mensagens · historico   (move recuperacao-carrinho + cancelados)
      disparo/            dashboard · campanhas (reativação/sazonal/informativo/novidades/giftback/manual) · rfv · mensagens · historico
      retencao/           dashboard · boas-vindas · aniversario · mensagens · historico
      flow/               dashboard · catalogo · ia-vendedora (nós B2C) · flows · conversas
      campanhas/          dashboard · objetivos (O1–O14) · cupons · aprovacoes · historico
      _shared/            modulo-shell (cabeçalho, abas, banner de trial, painel do assistente) · modulo-bloqueado · modulo-checkout
    assistente/           hub-assistente (painel dockado à direita / bottom-sheet no mobile; contexto = módulo ativo)
    conta/                assinatura-uso (Stripe) · conectar-mcp · configuracoes (existente)
  core/
    config/modulos.config.ts   ModuloKey = 'carrinho'|'disparo'|'retencao'|'flow'|'campanhas'
                               ModuloDef += cor, slugLanding, argumentoCurto, feats[], preco
    services/billing.service.ts · assistente.service.ts (SSE) · cnpj.service.ts · onboarding.service.ts

Rotas: /lp/:slug · /cadastro · /login · /onboarding/:passo · /app (início) · /app/m/:modulo/(dashboard|configurar|mensagens|historico|assistente) · /app/m/:modulo/ativar (checkout) · /app/assistente · /app/conta/(assinatura|mcp).

Mobile: tab bar inferior (Início · Módulos · Assistente · Conta) usando bottom-sheet existente para o assistente; KPIs em grade 2×2; abas roláveis; formulários de uma coluna. Web: sidebar como hoje, assistente fixo à direita (360 px) em toda tela de módulo.

Regra de UX mantida das telas atuais: toda tela de envio tem Dashboard com KPIs + funil + mensal + histórico, e a aba Configurar segue a sequência de cards numerados (Nome → Canal → Mensagem → Regra → Agendamento → Revisão).

8. Assistente conversacional (MCP)

Arquitetura em duas portas sobre o mesmo servidor de tools:

Angular <hub-assistente [modulo]>  ──SSE──▶  POST /api/assistente/conversar/
                                              │  monta system prompt (empresa, módulo, config atual)
                                              │  tools = mcp_server filtradas por modulos_ativos ∩ escopo do usuário
                                              ▼
                                         Claude API (tool use, streaming)
                                              │  tool de escrita → devolve ToolCard {tool, diff, status:'pendente'}
                                              │  usuário confirma no chat → POST /api/assistente/confirmar/{id}
                                              ▼
                                         executa a tool (mesma função do mcp_server) → LogMcp

Claude Desktop / claude.ai / ChatGPT  ──Streamable HTTP──▶  https://mcp.hub.ecomsmart.com.br/:slug
                                              OAuth 2.1 (Django como authorization server), escopos <modulo>:read|write
                                              lista de tools dinâmica por tenant: módulo bloqueado = tool não registrada

Regras: toda escrita exige confirmação (elicitation); nenhuma tool envia mensagem, só agenda; assinatura.manter_modulo e assinatura.ativar_trial abrem a confirmação de cobrança, nunca cobram sozinhas; MCPToken.key migra para hash.

Tools de escrita a criar (o mcp_server hoje é quase todo leitura):

9. Módulos: telas e reaproveitamento

Cada módulo usa o mesmo modulo-shell: cabeçalho (ícone, nome, status, banner de trial), abas Dashboard · Configurar · Mensagens · Histórico · Assistente, painel do assistente à direita.

• Carrinho: move recuperacao-carrinho/ e recuperacao-cancelados/ para dentro; aba Configurar = régua (3 regras com delay/template/cupom) + origens (webhooks) + canal.
• Disparo RFV: analise-rfv/ vira a aba RFV; as famílias one-shot viram sub-abas de Campanhas; informativos e giftback seguem aqui.
• Retenção: aniversariantes/ e boas-vindas/ como sub-abas; RetencaoAutomacaoState mantido.
• E-commerceFlow: Catálogo (produtos sincronizados, status), IA vendedora (editor de prompts B2C já existente, versionado), Flows (Flow JSON por empresa, publicar/testar, endpoint de dados criptografado /api/publica/flows/data/), Conversas (bate-papo existente filtrado pelo canal do Flow). Pedido criado via provider da Integracao.
• Campanhas Inteligentes: tela "Ofertas sugeridas" (objetivos O1–O14 com clientes elegíveis, tier RFV, horário e mensagem sugerida) migrada para o Hub; aba Cupons (regras por faixa, validade, mínimo); aba Aprovações (fila diária às 07:00). Motor: portar o Mamdani do assistente de marketing para core/campanhas_inteligentes/ (entradas: recência, frequência, valor, afinidade cesta.py, giro de estoque; saída: prioridade por objetivo × cliente).

10. Fases de entrega

11. Decisões abertas

• Trial exige cartão? Protótipo assume opcional (aumenta conversão; risco de trial sem conversão). Alternativa: cartão obrigatório no passo 3.
• Uma Subscription por módulo (recomendado) versus uma Subscription com vários itens (fatura única, mas trial e cancelamento por item ficam complexos).
• Empresas atuais em plano fechado: mapear principal → 3 módulos sem cobrança adicional até renegociação, marcando origem=direta.
• Cota por módulo ou pool compartilhado quando há mais de um módulo? Protótipo mostra por módulo; pool simplifica a leitura para o cliente.
• Fuzzy: portar a lógica que hoje vive no prompt para código determinístico (auditável) e usar a IA só para redigir a mensagem.