@baruk/core 0.1.0 → 0.3.0

package/src/db/migrations/0018_office_onboarding_portal_actions.sql

@@ -0,0 +1,60 @@
+-- 0018 — Interações públicas controladas do Portal no onboarding.
+-- Não representa upload, validação documental ou workflow interno.
+
+CREATE TABLE onboarding_portal_interaction (
+  id uuid PRIMARY KEY,
+  tenant_id uuid NOT NULL REFERENCES tenant(id),
+  onboarding_id uuid NOT NULL,
+  client_id uuid NOT NULL,
+  item_id uuid,
+  document_requirement_id uuid,
+  author_user_id uuid NOT NULL REFERENCES "user"(id),
+  kind text NOT NULL CHECK (kind IN ('response', 'comment', 'external_delivery_confirmation')),
+  status text NOT NULL CHECK (status IN ('submitted', 'under_review', 'needs_clarification', 'accepted', 'superseded')) DEFAULT 'submitted',
+  visibility text NOT NULL CHECK (visibility = 'public_to_client'),
+  body text,
+  external_channel text CHECK (external_channel IS NULL OR external_channel IN ('email', 'whatsapp', 'in_person', 'other')),
+  external_delivered_at date,
+  supersedes_id uuid REFERENCES onboarding_portal_interaction(id),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT onboarding_portal_interaction_onboarding_fk
+    FOREIGN KEY (tenant_id, onboarding_id)
+    REFERENCES onboarding_instance(tenant_id, id),
+  CONSTRAINT onboarding_portal_interaction_item_fk
+    FOREIGN KEY (tenant_id, item_id)
+    REFERENCES onboarding_item(tenant_id, id),
+  CONSTRAINT onboarding_portal_interaction_document_fk
+    FOREIGN KEY (tenant_id, document_requirement_id)
+    REFERENCES onboarding_document_requirement(tenant_id, id),
+  CONSTRAINT onboarding_portal_interaction_target_ck CHECK (
+    (kind = 'response' AND item_id IS NOT NULL AND document_requirement_id IS NULL AND body IS NOT NULL AND external_channel IS NULL AND external_delivered_at IS NULL)
+    OR (kind = 'comment' AND item_id IS NULL AND document_requirement_id IS NULL AND body IS NOT NULL AND external_channel IS NULL AND external_delivered_at IS NULL)
+    OR (kind = 'external_delivery_confirmation' AND item_id IS NULL AND document_requirement_id IS NOT NULL AND external_channel IS NOT NULL AND external_delivered_at IS NOT NULL)
+  )
+);
+
+CREATE INDEX onboarding_portal_interaction_scope_idx
+  ON onboarding_portal_interaction (tenant_id, client_id, onboarding_id, created_at);
+CREATE INDEX onboarding_portal_interaction_item_idx
+  ON onboarding_portal_interaction (tenant_id, item_id, created_at);
+CREATE INDEX onboarding_portal_interaction_document_idx
+  ON onboarding_portal_interaction (tenant_id, document_requirement_id, created_at);
+
+ALTER TABLE onboarding_portal_interaction ENABLE ROW LEVEL SECURITY;
+ALTER TABLE onboarding_portal_interaction FORCE ROW LEVEL SECURITY;
+CREATE POLICY onboarding_portal_interaction_scope ON onboarding_portal_interaction
+  USING (
+    tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid
+    AND (
+      NULLIF(current_setting('app.current_client', true), '') IS NULL
+      OR client_id = NULLIF(current_setting('app.current_client', true), '')::uuid
+    )
+  )
+  WITH CHECK (
+    tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid
+    AND (
+      NULLIF(current_setting('app.current_client', true), '') IS NULL
+      OR client_id = NULLIF(current_setting('app.current_client', true), '')::uuid
+    )
+  );

package/src/db/migrations/0019_office_onboarding_interaction_review.sql

@@ -0,0 +1,134 @@
+-- 0019 — Revisão administrativa das interações públicas de onboarding.
+-- Não altera workflow do onboarding, Storage, Billing ou Communication.
+
+-- 0018 tinha PK simples; esta chave composta permite manter a mesma defesa de
+-- tenant nas FKs das tabelas de revisão sem editar a migration histórica.
+ALTER TABLE onboarding_portal_interaction
+  ADD CONSTRAINT onboarding_portal_interaction_tenant_id_uq UNIQUE (tenant_id, id);
+
+CREATE TABLE onboarding_interaction_review (
+  interaction_id uuid PRIMARY KEY,
+  tenant_id uuid NOT NULL,
+  client_id uuid NOT NULL,
+  onboarding_id uuid NOT NULL,
+  status text NOT NULL DEFAULT 'pending_review'
+    CHECK (status IN ('pending_review', 'in_review', 'accepted', 'clarification_requested', 'resolved', 'dismissed')),
+  reviewer_id uuid REFERENCES "user"(id),
+  assigned_to uuid REFERENCES "user"(id),
+  priority text NOT NULL DEFAULT 'normal'
+    CHECK (priority IN ('low', 'normal', 'high', 'urgent')),
+  due_at timestamptz NOT NULL,
+  breached_at timestamptz,
+  reviewed_at timestamptz,
+  resolved_at timestamptz,
+  resolution_type text CHECK (resolution_type IS NULL OR resolution_type IN ('information_accepted', 'clarification_requested', 'duplicate', 'no_action_required', 'handled_manually', 'superseded')),
+  internal_summary text,
+  version int NOT NULL DEFAULT 1 CHECK (version > 0),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT onboarding_interaction_review_scope_fk
+    FOREIGN KEY (tenant_id, interaction_id) REFERENCES onboarding_portal_interaction(tenant_id, id) ON DELETE CASCADE,
+  CONSTRAINT onboarding_interaction_review_onboarding_fk
+    FOREIGN KEY (tenant_id, onboarding_id) REFERENCES onboarding_instance(tenant_id, id) ON DELETE CASCADE,
+  CONSTRAINT onboarding_interaction_review_client_fk
+    FOREIGN KEY (tenant_id, client_id) REFERENCES client(tenant_id, id),
+  CHECK (due_at >= created_at)
+);
+
+CREATE INDEX onboarding_interaction_review_queue_idx
+  ON onboarding_interaction_review (tenant_id, status, due_at, priority, created_at DESC);
+CREATE INDEX onboarding_interaction_review_assignee_idx
+  ON onboarding_interaction_review (tenant_id, assigned_to, status, due_at);
+
+CREATE TABLE onboarding_interaction_internal_note (
+  id uuid PRIMARY KEY,
+  tenant_id uuid NOT NULL,
+  client_id uuid NOT NULL,
+  onboarding_id uuid NOT NULL,
+  interaction_id uuid NOT NULL,
+  author_id uuid NOT NULL REFERENCES "user"(id),
+  body text NOT NULL CHECK (length(body) BETWEEN 1 AND 4000),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT onboarding_interaction_note_scope_fk
+    FOREIGN KEY (tenant_id, interaction_id) REFERENCES onboarding_portal_interaction(tenant_id, id) ON DELETE CASCADE,
+  CONSTRAINT onboarding_interaction_note_onboarding_fk
+    FOREIGN KEY (tenant_id, onboarding_id) REFERENCES onboarding_instance(tenant_id, id) ON DELETE CASCADE,
+  CONSTRAINT onboarding_interaction_note_client_fk
+    FOREIGN KEY (tenant_id, client_id) REFERENCES client(tenant_id, id)
+);
+
+CREATE INDEX onboarding_interaction_note_idx
+  ON onboarding_interaction_internal_note (tenant_id, interaction_id, created_at);
+
+CREATE TABLE onboarding_interaction_public_reply (
+  id uuid PRIMARY KEY,
+  tenant_id uuid NOT NULL,
+  client_id uuid NOT NULL,
+  onboarding_id uuid NOT NULL,
+  interaction_id uuid NOT NULL,
+  author_id uuid NOT NULL REFERENCES "user"(id),
+  body text NOT NULL CHECK (length(body) BETWEEN 1 AND 2000),
+  visibility text NOT NULL CHECK (visibility = 'public_to_client'),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT onboarding_interaction_reply_scope_fk
+    FOREIGN KEY (tenant_id, interaction_id) REFERENCES onboarding_portal_interaction(tenant_id, id) ON DELETE CASCADE,
+  CONSTRAINT onboarding_interaction_reply_onboarding_fk
+    FOREIGN KEY (tenant_id, onboarding_id) REFERENCES onboarding_instance(tenant_id, id) ON DELETE CASCADE,
+  CONSTRAINT onboarding_interaction_reply_client_fk
+    FOREIGN KEY (tenant_id, client_id) REFERENCES client(tenant_id, id)
+);
+
+CREATE INDEX onboarding_interaction_reply_idx
+  ON onboarding_interaction_public_reply (tenant_id, onboarding_id, created_at);
+
+-- Interações existentes entram na fila sem alterar o histórico público.
+INSERT INTO onboarding_interaction_review (interaction_id, tenant_id, client_id, onboarding_id, due_at)
+SELECT id, tenant_id, client_id, onboarding_id, created_at + interval '2 days'
+FROM onboarding_portal_interaction
+ON CONFLICT (interaction_id) DO NOTHING;
+
+-- Novas interações públicas entram automaticamente na fila administrativa.
+CREATE OR REPLACE FUNCTION create_onboarding_interaction_review()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = public, pg_temp AS $$
+BEGIN
+  INSERT INTO onboarding_interaction_review (interaction_id, tenant_id, client_id, onboarding_id, due_at)
+  VALUES (NEW.id, NEW.tenant_id, NEW.client_id, NEW.onboarding_id, NEW.created_at + interval '2 days')
+  ON CONFLICT (interaction_id) DO NOTHING;
+  RETURN NEW;
+END;
+$$;
+
+CREATE TRIGGER onboarding_interaction_review_after_insert
+AFTER INSERT ON onboarding_portal_interaction
+FOR EACH ROW EXECUTE FUNCTION create_onboarding_interaction_review();
+
+ALTER TABLE onboarding_interaction_review ENABLE ROW LEVEL SECURITY;
+ALTER TABLE onboarding_interaction_review FORCE ROW LEVEL SECURITY;
+ALTER TABLE onboarding_interaction_internal_note ENABLE ROW LEVEL SECURITY;
+ALTER TABLE onboarding_interaction_internal_note FORCE ROW LEVEL SECURITY;
+ALTER TABLE onboarding_interaction_public_reply ENABLE ROW LEVEL SECURITY;
+ALTER TABLE onboarding_interaction_public_reply FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY onboarding_interaction_review_staff_scope ON onboarding_interaction_review
+  USING (
+    tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid
+    AND current_setting('app.current_surface', true) <> 'portal'
+  )
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+CREATE POLICY onboarding_interaction_note_staff_scope ON onboarding_interaction_internal_note
+  USING (
+    tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid
+    AND current_setting('app.current_surface', true) <> 'portal'
+  )
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+CREATE POLICY onboarding_interaction_reply_scope ON onboarding_interaction_public_reply
+  USING (
+    tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid
+    AND (
+      current_setting('app.current_surface', true) <> 'portal'
+      OR client_id = NULLIF(current_setting('app.current_client', true), '')::uuid
+    )
+  )
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);

package/src/db/migrations/0020_saas_billing.sql

@@ -0,0 +1,157 @@
+-- 0020 — Billing SaaS (Concern A): a Baruk cobra o TENANT pela assinatura da
+-- plataforma. Persistência do domínio puro `subscription-billing/` (RFC-CAPABILITY-
+-- BILLING-001 v0.1). NUNCA mistura com Merchant Billing (0014/0015, Concern B):
+-- contratos de domínio separados por ADR-ECO-0007.
+
+-- ── Catálogo de planos do SaaS (global, como `product`: read-only p/ app) ────
+-- Preço vive no plano nesta v0.1 (pricingModel 'flat'); a CommercialPriceTable
+-- versionada do commercial-catalog é evolução prevista, não regressão.
+CREATE TABLE saas_plan (
+  id            uuid PRIMARY KEY,
+  key           text NOT NULL,                     -- starter | pro | enterprise
+  name          text NOT NULL,
+  description   text,
+  amount_cents  integer NOT NULL CHECK (amount_cents >= 0),
+  currency      text NOT NULL DEFAULT 'BRL',
+  periodicity   text NOT NULL DEFAULT 'monthly'
+                  CHECK (periodicity IN ('monthly', 'quarterly', 'yearly')),
+  trial_days    integer NOT NULL DEFAULT 0 CHECK (trial_days >= 0),
+  -- Módulos inclusos (codes) e limites/franquias — consumidos pelos Entitlements
+  -- finos (EntitlementSource 'PLAN') e pela página comercial.
+  modules       jsonb NOT NULL DEFAULT '[]'::jsonb,
+  limits        jsonb NOT NULL DEFAULT '{}'::jsonb,
+  is_public     boolean NOT NULL DEFAULT true,     -- aparece na página de planos
+  is_active     boolean NOT NULL DEFAULT true,     -- contratável
+  sort_order    integer NOT NULL DEFAULT 0,
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX saas_plan_key_uq ON saas_plan (key);
+
+-- ── Assinatura do tenant (fonte de verdade interna; gateway é espelho) ───────
+-- Cardinalidade v0.1: exatamente UMA assinatura por tenant (reconcile.ts usa
+-- `sub_<tenantId>`); o UNIQUE em tenant_id materializa a invariante.
+CREATE TABLE saas_subscription (
+  id                        uuid PRIMARY KEY,
+  tenant_id                 uuid NOT NULL REFERENCES tenant(id),
+  plan_key                  text NOT NULL REFERENCES saas_plan(key),
+  status                    text NOT NULL
+                              CHECK (status IN ('trialing','active','past_due','canceled','paused')),
+  current_period_end        date,
+  trial_ends_at             date,
+  canceled_at               timestamptz,
+  sequence                  integer NOT NULL DEFAULT 0,
+  provider                  text,                  -- gateway pedido (ex.: 'asaas')
+  provider_customer_id      text,
+  provider_subscription_id  text,
+  created_at                timestamptz NOT NULL DEFAULT now(),
+  updated_at                timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX saas_subscription_tenant_uq ON saas_subscription (tenant_id);
+CREATE INDEX saas_subscription_status_idx ON saas_subscription (status);
+
+-- ── Faturas do SaaS (espelho normalizado das cobranças do gateway) ───────────
+CREATE TABLE saas_invoice (
+  id               uuid PRIMARY KEY,
+  tenant_id        uuid NOT NULL REFERENCES tenant(id),
+  subscription_id  uuid REFERENCES saas_subscription(id),
+  provider         text NOT NULL,
+  external_id      text NOT NULL,
+  status           text NOT NULL
+                     CHECK (status IN ('pending','confirmed','received','overdue','refunded','canceled','failed')),
+  amount_cents     integer NOT NULL CHECK (amount_cents >= 0),
+  due_date         date,
+  paid_at          timestamptz,
+  invoice_url      text,
+  description      text,
+  created_at       timestamptz NOT NULL DEFAULT now(),
+  updated_at       timestamptz NOT NULL DEFAULT now()
+);
+-- Idempotência de espelho: 1 cobrança no gateway ↔ 1 fatura interna.
+CREATE UNIQUE INDEX saas_invoice_external_uq ON saas_invoice (provider, external_id);
+CREATE INDEX saas_invoice_tenant_idx ON saas_invoice (tenant_id);
+
+-- ── Eventos de domínio (envelope events.ts; sequence monotônica por assinatura) ──
+CREATE TABLE saas_billing_event (
+  id                  uuid PRIMARY KEY,            -- eventId (idempotência do consumidor)
+  subscription_id     uuid NOT NULL REFERENCES saas_subscription(id),
+  tenant_id           uuid NOT NULL REFERENCES tenant(id),
+  type                text NOT NULL,
+  sequence            integer NOT NULL,
+  occurred_at         timestamptz NOT NULL,
+  causation_event_id  text,
+  data                jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at          timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX saas_billing_event_seq_uq ON saas_billing_event (subscription_id, sequence);
+CREATE INDEX saas_billing_event_tenant_idx ON saas_billing_event (tenant_id);
+
+-- ── Régua de inadimplência: passos já executados (stepKey idempotente) ───────
+CREATE TABLE saas_dunning_event (
+  id               uuid PRIMARY KEY,
+  tenant_id        uuid NOT NULL REFERENCES tenant(id),
+  subscription_id  uuid NOT NULL REFERENCES saas_subscription(id),
+  step_key         text NOT NULL,                  -- ex.: 'D+7:email'
+  reference_date   date NOT NULL,                  -- currentPeriodEnd do ciclo em atraso
+  executed_at      timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX saas_dunning_step_uq ON saas_dunning_event (subscription_id, reference_date, step_key);
+
+-- ── Webhook inbound (CROSS-TENANT de propósito — mesmo padrão do 0015) ───────
+-- Dedup por (provider, external_event_id) ANTES de resolver tenant; tenant_id é
+-- preenchido depois. Sem RLS: escrita em contexto de sistema, pré-`current_tenant`.
+CREATE TABLE saas_webhook_event (
+  id                 uuid PRIMARY KEY,
+  tenant_id          uuid REFERENCES tenant(id),
+  provider           text NOT NULL,
+  external_event_id  text NOT NULL,
+  event_type         text NOT NULL,
+  status             text NOT NULL DEFAULT 'received'
+                       CHECK (status IN ('received','processed','ignored','failed')),
+  payload            jsonb,
+  error              text,
+  processed_at       timestamptz,
+  created_at         timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX saas_webhook_event_idempotency_uq ON saas_webhook_event (provider, external_event_id);
+CREATE INDEX saas_webhook_event_tenant_idx ON saas_webhook_event (tenant_id) WHERE tenant_id IS NOT NULL;
+
+-- ── RLS FORCE nas tabelas tenant-scoped ──────────────────────────────────────
+-- Política dupla: (a) isolamento por tenant via GUC `app.current_tenant`;
+-- (b) acesso de operadora (backoffice Baruk) via GUC `app.platform_operator`,
+-- setada EXCLUSIVAMENTE pelas rotas de backoffice após verificação de operador.
+ALTER TABLE saas_subscription ENABLE ROW LEVEL SECURITY;
+ALTER TABLE saas_subscription FORCE ROW LEVEL SECURITY;
+CREATE POLICY saas_subscription_tenant_isolation ON saas_subscription
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+CREATE POLICY saas_subscription_operator ON saas_subscription
+  USING (current_setting('app.platform_operator', true) = 'true')
+  WITH CHECK (current_setting('app.platform_operator', true) = 'true');
+
+ALTER TABLE saas_invoice ENABLE ROW LEVEL SECURITY;
+ALTER TABLE saas_invoice FORCE ROW LEVEL SECURITY;
+CREATE POLICY saas_invoice_tenant_isolation ON saas_invoice
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+CREATE POLICY saas_invoice_operator ON saas_invoice
+  USING (current_setting('app.platform_operator', true) = 'true')
+  WITH CHECK (current_setting('app.platform_operator', true) = 'true');
+
+ALTER TABLE saas_billing_event ENABLE ROW LEVEL SECURITY;
+ALTER TABLE saas_billing_event FORCE ROW LEVEL SECURITY;
+CREATE POLICY saas_billing_event_tenant_isolation ON saas_billing_event
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+CREATE POLICY saas_billing_event_operator ON saas_billing_event
+  USING (current_setting('app.platform_operator', true) = 'true')
+  WITH CHECK (current_setting('app.platform_operator', true) = 'true');
+
+ALTER TABLE saas_dunning_event ENABLE ROW LEVEL SECURITY;
+ALTER TABLE saas_dunning_event FORCE ROW LEVEL SECURITY;
+CREATE POLICY saas_dunning_event_tenant_isolation ON saas_dunning_event
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+CREATE POLICY saas_dunning_event_operator ON saas_dunning_event
+  USING (current_setting('app.platform_operator', true) = 'true')
+  WITH CHECK (current_setting('app.platform_operator', true) = 'true');

package/src/db/migrations/0021_saas_billing_indexes.sql

@@ -0,0 +1,23 @@
+-- 0021 — Índices do Billing SaaS para as queries reais (achados da revisão
+-- adversarial BILL-01): scan do cron (índices parciais por status), ordenações
+-- do backoffice e FKs usadas em JOIN.
+
+-- Cron: listSubscriptionsForCron usa OR de 3 predicados por status.
+CREATE INDEX saas_subscription_trialing_idx
+  ON saas_subscription (trial_ends_at) WHERE status = 'trialing';
+CREATE INDEX saas_subscription_active_period_idx
+  ON saas_subscription (current_period_end) WHERE status = 'active';
+CREATE INDEX saas_subscription_past_due_idx
+  ON saas_subscription (updated_at) WHERE status = 'past_due';
+
+-- Backoffice: ordenações por recência.
+CREATE INDEX saas_subscription_updated_idx ON saas_subscription (updated_at DESC);
+CREATE INDEX saas_webhook_event_created_idx ON saas_webhook_event (created_at DESC);
+-- Reprocessamento de failed pelo cron.
+CREATE INDEX saas_webhook_event_failed_idx
+  ON saas_webhook_event (created_at) WHERE status = 'failed';
+
+-- FKs usadas em JOIN/queries.
+CREATE INDEX saas_subscription_plan_key_idx ON saas_subscription (plan_key);
+CREATE INDEX saas_invoice_subscription_idx ON saas_invoice (subscription_id);
+CREATE INDEX saas_dunning_event_tenant_idx ON saas_dunning_event (tenant_id);

package/src/db/migrations/0022_saas_billing_multi_product.sql

@@ -0,0 +1,75 @@
+-- BILL-01 / Multi-produto — o motor de Billing é infraestrutura compartilhada do
+-- ecossistema, mas cada PRODUTO (Baruk Contábil/Office, Rep, Ind, futuro Varejo,
+-- Dental) tem catálogo de planos, módulos e superfície comercial próprios.
+--
+-- Antes desta migração o billing era single-product por construção:
+--   · `saas_plan.key` era UNIQUE global   → dois produtos não podiam ter "pro";
+--   · `saas_subscription` era UNIQUE por tenant → um tenant não podia assinar
+--     dois produtos, e um webhook de qualquer produto aterrissava na mesma linha.
+--
+-- O catálogo `product` (0010) já é a fonte de verdade de produtos e já tem N:N
+-- com tenant (`tenant_product`). Esta migração conecta o billing a ele.
+--
+-- Compatibilidade: tudo que existe hoje é do Contábil, então o default
+-- 'contabil' preserva os dados atuais sem backfill manual.
+
+-- ── saas_plan: plano pertence a um produto ───────────────────────────────────
+ALTER TABLE saas_plan
+  ADD COLUMN IF NOT EXISTS product_key TEXT NOT NULL DEFAULT 'contabil';
+
+-- A chave do plano passa a ser única DENTRO do produto: 'pro' do Office e 'pro'
+-- do Rep são planos distintos.
+--
+-- `saas_subscription.plan_key` referencia `saas_plan(key)` (0020:37), e essa FK
+-- depende do índice único global. A ordem obrigatória é: soltar a FK → trocar o
+-- índice → recriar a FK apontando para o novo par (product_key, key).
+ALTER TABLE saas_subscription
+  DROP CONSTRAINT IF EXISTS saas_subscription_plan_key_fkey;
+
+DROP INDEX IF EXISTS saas_plan_key_uq;
+CREATE UNIQUE INDEX IF NOT EXISTS saas_plan_product_key_uq
+  ON saas_plan (product_key, key);
+
+-- Integridade referencial contra o catálogo de produtos (0010).
+ALTER TABLE saas_plan
+  DROP CONSTRAINT IF EXISTS saas_plan_product_fk;
+ALTER TABLE saas_plan
+  ADD CONSTRAINT saas_plan_product_fk
+  FOREIGN KEY (product_key) REFERENCES product (key) ON UPDATE CASCADE;
+
+-- ── saas_subscription: uma assinatura por (tenant, produto) ──────────────────
+ALTER TABLE saas_subscription
+  ADD COLUMN IF NOT EXISTS product_key TEXT NOT NULL DEFAULT 'contabil';
+
+DROP INDEX IF EXISTS saas_subscription_tenant_uq;
+CREATE UNIQUE INDEX IF NOT EXISTS saas_subscription_tenant_product_uq
+  ON saas_subscription (tenant_id, product_key);
+
+ALTER TABLE saas_subscription
+  DROP CONSTRAINT IF EXISTS saas_subscription_product_fk;
+ALTER TABLE saas_subscription
+  ADD CONSTRAINT saas_subscription_product_fk
+  FOREIGN KEY (product_key) REFERENCES product (key) ON UPDATE CASCADE;
+
+-- Recria a FK do plano no par completo: uma assinatura só pode apontar para um
+-- plano DO SEU PRÓPRIO produto. É esta constraint que torna impossível, no
+-- banco, um tenant do Office assinar um plano do Rep.
+ALTER TABLE saas_subscription
+  DROP CONSTRAINT IF EXISTS saas_subscription_product_plan_fk;
+ALTER TABLE saas_subscription
+  ADD CONSTRAINT saas_subscription_product_plan_fk
+  FOREIGN KEY (product_key, plan_key) REFERENCES saas_plan (product_key, key)
+  ON UPDATE CASCADE;
+
+-- ── Rastros: produto explícito onde a atribuição do evento é decidida ────────
+-- Fatura e evento de webhook carregam o produto para que a conciliação e o
+-- backoffice nunca precisem inferi-lo a partir do tenant.
+ALTER TABLE saas_invoice
+  ADD COLUMN IF NOT EXISTS product_key TEXT NOT NULL DEFAULT 'contabil';
+
+ALTER TABLE saas_webhook_event
+  ADD COLUMN IF NOT EXISTS product_key TEXT;
+
+CREATE INDEX IF NOT EXISTS saas_plan_product_idx ON saas_plan (product_key, sort_order);
+CREATE INDEX IF NOT EXISTS saas_subscription_product_idx ON saas_subscription (product_key, status);
+CREATE INDEX IF NOT EXISTS saas_invoice_product_idx ON saas_invoice (product_key, status);