## 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)

- clinic_free
- clinic_pro
- therapist_free
- therapist_pro

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

## 3. Governança de Guardrails

- Impedem alterar key de plano core
- Impedem alterar target de plano core
- Impedem deletar plano com subscription ativa

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

- Tenant clinic → clinic_free
- Tenant therapist → therapist_free