Pular para conteúdo

App: subscriptions

Gerencia planos, assinaturas, creditos por agente e pacotes avulsos.

Models

Plan

Plano com limites, precos e modelos disponiveis (M2M com AIModel).

Planos atuais: Free, Starter, Pro, Max.

Campos principais: name, slug, price_monthly, stripe_price_id, max_students, max_courses, max_messages_per_month, allowed_file_types, features_list, is_active, is_recommended, order.

AIModel

Modelo de IA com custos e configuracoes. Providers suportados: OpenAI, OpenRouter.

Campos: name, provider, model_code, cost_per_1m_input_tokens, cost_per_1m_output_tokens, minutes_per_100_tokens, is_active, order.

Subscription

Assinatura da escola com trial_ends_at para trial de 14 dias.

  • school -- OneToOne com School
  • plan -- campo legado (CharField)
  • plan_ref -- FK para Plan (referencia principal)
  • stripe_customer_id, stripe_subscription_id
  • subscription_status, current_period_end
  • max_students, max_courses, max_messages_per_month
  • is_active, trial_ends_at

Planos no Subscription: free, starter, pro, max (e enterprise como legado).

Properties de pagamento: is_payment_active, is_payment_past_due, is_payment_blocked, is_free_plan.

StudentMessageCredit

Controle granular de creditos por aluno, por escola, por agente, por periodo.

  • student -- FK para User
  • school -- FK para School
  • agent -- FK para Agent (nullable)
  • messages_used, messages_limit, extra_credits
  • period_start, period_end
  • Constraint unica: (student, school, agent, period_start)

MessagePackage

Pacotes avulsos disponiveis para compra.

Campos: name, messages, price, is_active, is_popular, order.

MessagePurchase

Registro de compra de pacote por um aluno, vinculado a um agente.

  • student -- FK para User
  • school -- FK para School
  • package -- FK para MessagePackage
  • agent -- FK para Agent (nullable)
  • messages_amount, price_paid
  • status, stripe_session_id, stripe_payment_intent_id

StripeWebhookEvent

Log idempotente dos eventos recebidos do webhook da Stripe.

  • stripe_event_id -- ID unico do evento
  • event_type -- tipo recebido
  • status -- processed, failed ou skipped
  • payload_summary, error_message

Creditos por Agente

O campo Agent.credits_per_student (padrao: 50) define quantos creditos cada aluno tem para aquele agente. O StudentMessageCredit tem FK para Agent, com constraint (student, school, agent, period_start).

Trial de 14 Dias

Ao criar uma Subscription Free, trial_ends_at e setado automaticamente:

defaults['trial_ends_at'] = timezone.now() + timedelta(days=14)

Apos expiracao, TrialExpiredMiddleware bloqueia rotas /escola/* e redireciona para upgrade.

Context Processors

  • student_credits -- injeta creditos agregados do aluno (soma de todos os agentes)
  • admin_subscription -- injeta dados de plano/trial para admins

Services (subscriptions/services.py)

  • get_current_billing_period(school) -- retorna (period_start, period_end) do periodo atual
  • get_or_create_student_credit(student, school, agent=None) -- cria ou retorna o credito do periodo atual para o agente especificado. Quando agent e fornecido, usa Agent.credits_per_student como limite padrao.

Stripe (subscriptions/stripe_service.py)

  • get_or_create_stripe_customer(school) -- cria ou reutiliza o customer da escola
  • create_subscription_checkout(school, plan) -- abre checkout de assinatura
  • create_customer_portal_session(school) -- abre portal self-service