Mudança de Plano (Upgrade/Downgrade)
O sistema permite que clientes alterem o plano da assinatura com cálculo automático de proration (rateio proporcional).
Tipos de Mudança
| Tipo | Descrição |
|---|---|
| upgrade | Novo plano mais caro que o atual |
| downgrade | Novo plano mais barato que o atual |
| lateral | Mesmo valor (mudança de features) |
Timing da Mudança
| Timing | Descrição |
|---|---|
| immediate | Aplica imediatamente, cobra/credita a diferença proporcional |
| end_of_period | Agenda a mudança para o início do próximo período |
Proration (Rateio Proporcional)
Métodos de Proration
| Método | Descrição |
|---|---|
full_proration | Credita o plano antigo e cobra o novo pelo tempo restante |
partial_proration | Cobra apenas a diferença (somente para upgrade) |
no_proration | Sem ajuste de valor no meio do ciclo |
Fórmula de Cálculo
dias_restantes = max(0, teto((fim_período - agora) / 86400000))
total_dias_período = teto((fim_período - início_período) / 86400000))
Full proration:
crédito = (preço_antigo × dias_restantes) / total_dias_período
cobrança = (preço_novo × dias_restantes) / total_dias_período
Partial proration (apenas upgrade):
diferença = preço_novo - preço_antigo
cobrança = (diferença × dias_restantes) / total_dias_período
Cobrança líquida = cobrança - crédito
Configuração Padrão
A configuração de mudança de plano define o comportamento padrão:
| Configuração | Padrão |
|---|---|
| Permitir upgrade | Sim |
| Permitir downgrade | Sim |
| Proration no upgrade | full_proration |
| Proration no downgrade | no_proration |
| Timing do upgrade | immediate |
| Timing do downgrade | end_of_period |
| Reembolso no downgrade | Não |
| Crédito no downgrade | Sim |
| Aplicar desconto na mudança | Sim |
Regras de Mudança de Plano
É possível criar regras específicas para controlar transições entre planos:
| Campo | Descrição |
|---|---|
| Plano de origem | Plano atual (null = qualquer) |
| Plano de destino | Novo plano (null = qualquer) |
| Tipo de mudança | upgrade, downgrade ou lateral |
| Permitido | Se a transição é permitida |
| Timing | Sobrescreve o timing padrão |
| Método de proration | Sobrescreve o método padrão |
| Desconto (%) | Desconto percentual na cobrança |
| Dias bônus | Extensão do trial |
| Mensagem | Razão se não permitido |
| Prioridade | Maior prioridade prevalece |
Ordem de Prioridade das Regras
- Regra com plano de origem E plano de destino (mais específica)
- Regra com apenas plano de origem
- Regra com apenas plano de destino
- Regra global (ambos null)
Preview da Mudança
Antes de executar, é possível visualizar:
- Se a mudança é permitida
- Tipo (upgrade/downgrade/lateral)
- Valores de crédito e cobrança proratados
- Cobrança líquida final
- Data efetiva
- Dias restantes no período
Executando a Mudança
Mudança Imediata
- Validação e preview são calculados
- Registro de PlanChange é criado (status:
pending) - Crédito gerado se
prorationCreditSubcents > 0 - Fatura gerada se
netChargeSubcents > 0 - Assinatura atualizada com o novo plano
- PlanChange marcado como
completed
Mudança Agendada
- Registro de PlanChange criado (status:
scheduled) - Na data efetiva, o worker processa a mudança
- Assinatura atualizada com o novo plano
- PlanChange marcado como
completed
Limitação: O sistema mantém apenas uma mudança agendada por vez. Uma nova mudança agendada cancela a anterior.
Cancelar Mudança Agendada
Mudanças agendadas podem ser canceladas antes da data efetiva. O status muda para canceled e o motivo é registrado.
Captura de tela
A tela /dashboard/plan-changes traz o histórico de mudanças de plano da organização, com filtros por status, tipo (upgrade/downgrade/lateral), plano de origem e destino. A aba de configuração centraliza o comportamento padrão de proration e regras por par de planos.
