Billing — Arquitetura Oficial v1.1

Versão 1.1 inclui procedimento formal de migração controlada para planos core, mantendo guardrails ativos e auditáveis.

1. Fundamentos do Domínio

Billing define recursos e limites do produto. Não é camada de UI. É camada estrutural.

Princípio: Role (RBAC) ≠ Plano (Billing). Plano dirige features e limites; role dirige acesso.

2. Planos Core (MVP)

Política: Planos core são estruturalmente protegidos por triggers.

3. Governança de Guardrails

Proibido: desabilitar triggers diretamente em produção.

4. Procedimento Oficial de Correção de Plano Core

Correções estruturais devem ocorrer via função administrativa controlada.

create or replace function admin_fix_plan_target(
  p_plan_key text,
  p_new_target text
) returns void
language plpgsql
security definer
as $$
declare
  v_plan_id uuid;
begin
  select id into v_plan_id
  from plans
  where key = p_plan_key
  for update;

  if v_plan_id is null then
    raise exception 'Plano não encontrado.';
  end if;

  if exists (
    select 1 from subscriptions where plan_id = v_plan_id
  ) then
    raise exception 'Plano possui subscriptions ativas.';
  end if;

  update plans
  set target = p_new_target
  where id = v_plan_id;

end;
$$;
Esta função deve ser executada apenas por role administrativa e registrada em log de auditoria.

5. Entitlements (Contrato Oficial)

Entitlements são derivados exclusivamente de plan_features.

plan_features (
  plan_id uuid,
  feature_id uuid,
  enabled boolean,
  limits jsonb
)
Formato oficial de limits: {"max": 30} {"per_month": 40} {"max_users": 1}

6. Preço Vigente

create unique index uq_plan_price_active
on plan_prices (plan_id, interval, currency)
where is_active = true and active_to is null;

7. Onboarding