Nova plataforma para cadastro, assinaturas, cobrança recorrente e gestão de acesso aos aplicativos NxPlay.
Escopo proposto · arquitetura e referências visuais
Desenvolvimento do Management e das integrações com sistemas existentes.
Mockups conceituais com dados fictícios. O produto e as integrações ainda não estão implementados ou homologados.
01 / Visão
O que vamos construir
Minha Conta
Um portal web para contratar, pagar, trocar cartão, acompanhar faturas e cancelar.
Admin
Um backoffice para suporte, financeiro, demos e gestão de assinantes.
Streaming
Aplicativos existentes: login, catálogo e reprodução. Não desenvolveremos o app de streaming.
Escopo / Limites do desenvolvimento
OSM e app de streaming já existem
Vamos desenvolverNxPlay Management: portal Minha Conta, backoffice, API de negócio, billing e integrações.
OSM: fora do desenvolvimentoNão vamos desenvolver, substituir ou reformular o OSM. Vamos consumir sua API existente para gerenciar usuários, planos e acesso.
App: fora do desenvolvimentoNão vamos desenvolver o aplicativo de streaming, player, catálogo ou reprodução. O app existente permanece responsável pela experiência de assistir.
O projeto entrega a gestão comercial e a integração de acesso aos sistemas existentes.
02 / Camadas
Arquitetura geral
Next.jsTailwind + shadcn/ui Minha Conta / Admin
→
Management APIFastify + TypeScript Regras e eventos
→
Kill BillPlanos, faturas, recorrência e retries
Mercado PagoCartão, tokenização, processamento
OSM existenteIntegração via API Usuários, acesso e demos
Dados e workersPostgreSQL, Redis, filas, reconciliação
Integraremos o OSM existente via API. OSM e app de streaming não serão desenvolvidos neste projeto. A recorrência pertence exclusivamente ao Kill Bill.
03 / Responsabilidades
Quem decide o quê?
Management APIIdentidade comercial, fluxo do checkout, autorização, decisões de acesso e auditoria.
Kill BillÚnico motor de recorrência: calendário, faturas, renovações, retentativas e estado da assinatura.
Mercado PagoTokenização e processamento de cada pagamento solicitado pelo Kill Bill. Sem Subscription/Preapproval do Mercado Pago.
OSM NxTVSistema existente: aplica usuários, pacote e status de acesso via API. Fora do desenvolvimento do Management.
04 / Primeira venda
Cadastro → pagamento → assistir
Cadastro webPlano, dados, aceite
→
Cartão seguroSDK Mercado Pago e perfil autorizado
→
Kill BillAssinatura + fatura
→
Pagamento confirmadoSem confiar apenas na tela de retorno
→
OSM NxTVCria e ativa usuário no streaming
Pagamento pendente ou com resultado desconhecido não deve ativar automaticamente o plano pago.
05 / Recorrência
Kill Bill controla toda a recorrência
Kill BillAgenda renovação e gera fatura
→
Plugin + AdapterBridge Java e conector TypeScript
→
Mercado PagoProcessa ordem MIT autorizada
→
Kill BillRegistra resultado e agenda retentativas
Gate de viabilidade: confirmar habilitação comercial e técnica de pagamentos MIT e perfil reutilizável no Mercado Pago. Sem isso, não considerar a arquitetura financeira homologada.
Cobrança / Decisão de arquitetura
Sem Subscription do Mercado Pago
Mercado PagoTokenização segura e processamento dos pagamentos. Não usaremos o produto de assinaturas, Subscription/Preapproval, nem seu calendário de recorrência.
Kill BillGerencia a assinatura, emite faturas e determina quando cobrar, renovar, tentar novamente ou cancelar.
Plugin + adaptadorExecuta no Mercado Pago cada cobrança solicitada pelo Kill Bill e devolve o resultado ao motor de billing.
A tokenização protege o cartão. O Kill Bill cuida da recorrência.
A Fase 0 ainda deve comprovar a credencial reutilizável e as cobranças posteriores autorizadas (MIT). Um token temporário não garante renovação.
Mermaid / Fluxo documentado
Contratação e primeira cobrança
Tokenização, primeira cobrança e renovação pelo Kill Bill. Fonte: docs/payments.md.
Kill Bill controla a recorrência. Mercado Pago tokeniza e processa; sem Subscription/Preapproval. Fluxo sujeito à validação da Fase 0.Ampliar diagrama ↗Baixar Mermaid
06 / Segurança
O cartão não passa pela NxPlay
Gateway
Coleta segura do cartão, tokenização e armazenamento da credencial autorizada para pagamentos posteriores.
NxPlay
Armazena referências seguras: cliente, perfil, bandeira e últimos quatro dígitos. Nunca PAN/CVV em banco ou logs.
O token do primeiro checkout pode ser temporário. É necessário validar o mecanismo de credencial reutilizável antes da segunda cobrança.
Não utilizar DELETE para suspender por inadimplência. O acesso deve acompanhar os direitos comerciais e o período já pago.
09 / Demos
Demo tem fluxo próprio
Admin concede demo
→
OSM gera usuário demo
→
Worker controla prazo
→
Suspende ou converte
A API OSM documenta criação de demo sem body, mas não documenta a duração da demonstração. O Management deverá controlar prazo, elegibilidade e expiração.
10 / Minha Conta
Experiência centrada no assinante
Assinatura
Plano, preço, acesso, próxima cobrança e cancelamento.
Pagamentos
Cartão salvo, atualização segura, histórico e recuperação de cobrança.
Perfil
Dados pessoais, segurança e vínculo com o login no app.
11 / Backoffice
Operação sob controle
Suporte
Busca de assinantes, timeline, demos e casos pendentes.
Financeiro
Faturas, inadimplência, tentativa, estornos e conciliação.
Gestão
MRR, churn, renovação, conversão de demos e auditoria.
Referência visual 01 / 08 · M01 · M02 · M03 · M05
Contratação e pagamento
Preço, recorrência e consentimento explícitos antes da contratação.
Conceito visual · dados fictícios · O acesso pago depende da confirmação do pagamento; recorrência exclusiva do Kill Bill; tokenização e processamento Mercado Pago sujeitos à validação MIT.Baixar PNG ↗
Referência visual 02 / 08 · M06 · M08
Minha Conta
Plano, próxima cobrança e situação do acesso em uma visão simples.
Conceito visual · dados fictícios · Assinatura e acesso ao app são estados distintos. O login do aplicativo não pressupõe SSO.Baixar PNG ↗
Referência visual 03 / 08 · M04 · M05 · M06 · M09
Pagamentos e recuperação
Histórico de faturas, atualização do cartão e regularização de cobrança.
Conceito visual · dados fictícios · Recusas, pendências e resultados desconhecidos exigem tratamentos diferentes. A tolerância será definida na Fase 0.Baixar PNG ↗
Referência visual 04 / 08 · M01 · M10
Gestão de assinantes
Busca, filtros e consulta administrativa em uma tabela paginada.
Conceito visual · dados fictícios · As ações e os dados disponíveis dependem das permissões de suporte, financeiro e administração.Baixar PNG ↗
Referência visual 05 / 08 · M04 · M06 · M08 · M10
Detalhe e cancelamento
Assinatura, acesso e histórico auditável no mesmo contexto.
Conceito visual · dados fictícios · O cancelamento agendado mantém o acesso até o fim do período pago, conforme a política prevista.Baixar PNG ↗
Referência visual 06 / 08 · M07 · M08 · M10
Demos e acesso temporário
Concessão com justificativa, término explícito e histórico.
Conceito visual · dados fictícios · Prazo ilustrativo, sujeito à validação da política. Uma demo sem cartão e consentimento não gera cobrança automática.Baixar PNG ↗
Referência visual 07 / 08 · M04 · M05 · M08 · M12
Conciliação e provisionamento
Comparação entre assinatura, pagamento e acesso efetivamente aplicado.
Conceito visual · dados fictícios · O reprocessamento de acesso não equivale a uma nova cobrança. Resultados financeiros desconhecidos devem ser conciliados.Baixar PNG ↗
Referência visual 08 / 08 · M12
Indicadores operacionais
Base ativa, MRR, cobranças e pendências para orientar a operação.
Conceito visual · dados fictícios · Todos os números são fictícios. Definições de MRR, churn e coortes deverão ser aprovadas antes da implementação.Baixar PNG ↗
12 / Independência
Preparado para outros gateways
Contrato de pagamentoSetup, charge, query, refund, eventos
→
Mercado PagoPrimeira implementação
Asaas / StripeAdaptadores futuros
A substituição do gateway não torna automaticamente portáveis os cartões tokenizados. Novos clientes podem usar outro provedor; cartões antigos precisam de estratégia de migração.
Fastify + TypeScript, PostgreSQL, Redis, worker, Kill Bill e plugin Java PaymentPluginApi.
14 / Confiabilidade
Pagamento certo, acesso certo
Idempotência
Proteger contra duplo clique, retries e webhooks duplicados.
Reconciliação
Comparar eventos, status de gateway, Kill Bill e OSM.
Auditoria
Registrar ações, motivos, correlação e falhas sem segredos.
15 / Roadmap
Fases de desenvolvimento
Fase 0Validar MIT, cartão salvo, segunda cobrança e endpoints OSM.
Fase 1–2Management, checkout, Kill Bill e adapter Mercado Pago, sem Subscription/Preapproval.
Fase 3–4Minha Conta, demos, backoffice, integração com o OSM existente, QA e lançamento.
Fase 5Mais gateways, Pix e retenção avançada.
16 / Decisões
O que precisamos validar em equipe
Habilitação real de MIT e pagamentos posteriores no Mercado Pago.
Gestão segura das senhas dos usuários OSM e da identidade do portal.
Política de demos, tolerância, cancelamento e estorno.
Mapeamento dos planos Kill Bill para plan_id da OSM.
Definição dos SLAs de provisionamento e conciliação.
17 / Encerramento
Uma plataforma. Três responsabilidades.
Kill Bill cuida da recorrência. Mercado Pago tokeniza o cartão e processa pagamentos, sem Subscription. Integraremos o OSM existente; não desenvolveremos o OSM nem o aplicativo de streaming.
