@baruk/core 0.3.1 → 0.5.0

package/src/db/migrations/0026_documents_and_competence.sql

@@ -0,0 +1,353 @@
+-- 0026 — Documents + Competência (ADR 0007 e ADR 0008).
+--
+-- Fecha a lacuna central do produto: até aqui nenhuma tabela guardava arquivo, e
+-- "competência" era texto livre em três colunas com três nomes. O ciclo
+-- "pedir → receber → conferir → provar" não fechava porque o documento trafegava
+-- fora do sistema e só a declaração de entrega era registrada.
+--
+-- Invariantes (ADR 0007):
+--   documento (registro de negócio) ≠ versão (imutável) ≠ blob (bytes).
+--   Nada é sobrescrito: substituir é criar versão nova e mover o ponteiro.
+--   Dedup de bytes é POR TENANT — nunca global, senão o checksum vira oráculo
+--   de existência de arquivo alheio.
+--
+-- Invariante (ADR 0008):
+--   a unicidade É a garantia de idempotência, não o código. Mesmo princípio já
+--   aplicado em receivable_fee_competence_uq (0015).
+
+-- ---------------------------------------------------------------------------
+-- Competência
+-- ---------------------------------------------------------------------------
+
+CREATE TABLE competence (
+  id uuid PRIMARY KEY,
+  tenant_id uuid NOT NULL REFERENCES tenant(id),
+  client_id uuid NOT NULL,
+  -- Rótulo canônico YYYY-MM (ADR 0008 D2). text + regex, não date nem par de
+  -- inteiros: ordenável lexicograficamente, comparável com <=, imune a fuso.
+  label text NOT NULL CHECK (label ~ '^\d{4}-\d{2}$'),
+  status text NOT NULL DEFAULT 'open'
+    CHECK (status IN ('open', 'in_progress', 'awaiting_client', 'review', 'closed', 'reopened')),
+  opened_at timestamptz NOT NULL DEFAULT now(),
+  closed_at timestamptz,
+  closed_by uuid REFERENCES "user"(id),
+  reopened_at timestamptz,
+  reopened_by uuid REFERENCES "user"(id),
+  notes text,
+  version int NOT NULL DEFAULT 1 CHECK (version > 0),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  deleted_at timestamptz,
+  CONSTRAINT competence_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  CHECK ((status <> 'closed') OR closed_at IS NOT NULL)
+);
+
+-- Uma competência por cliente por mês. É o que impede abrir julho/2026 duas vezes.
+CREATE UNIQUE INDEX competence_client_label_uq
+  ON competence (tenant_id, client_id, label)
+  WHERE deleted_at IS NULL;
+CREATE INDEX competence_tenant_status_idx ON competence (tenant_id, status, label DESC);
+
+-- ---------------------------------------------------------------------------
+-- Catálogo de itens recorrentes (ADR 0008 D3)
+-- ---------------------------------------------------------------------------
+
+-- tenant_id NULL = template do sistema; preenchido = override do escritório.
+-- Mesma forma que `role` já usa para papéis de sistema (0003).
+CREATE TABLE recurring_item_type (
+  id uuid PRIMARY KEY,
+  tenant_id uuid REFERENCES tenant(id),
+  key text NOT NULL,
+  label text NOT NULL,
+  -- obrigação = dever externo com prazo legal e risco de penalidade.
+  -- tarefa    = trabalho interno com prazo acordado (ADR 0008 D6).
+  nature text NOT NULL CHECK (nature IN ('obligation', 'task')),
+  sphere text CHECK (sphere IN ('federal', 'estadual', 'municipal', 'trabalhista')),
+  category text,
+  periodicity text NOT NULL DEFAULT 'monthly'
+    CHECK (periodicity IN ('monthly', 'quarterly', 'yearly', 'eventual')),
+  -- Ex.: {"kind":"day_of_next_month","day":20}. Interpretada na aplicação.
+  due_rule jsonb NOT NULL DEFAULT '{}'::jsonb,
+  -- Regimes aos quais se aplica; [] = todos (ADR 0008 D5).
+  applies_to_regime jsonb NOT NULL DEFAULT '[]'::jsonb,
+  requires_document boolean NOT NULL DEFAULT false,
+  active boolean NOT NULL DEFAULT true,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  deleted_at timestamptz,
+  CONSTRAINT recurring_item_type_tenant_id_uq UNIQUE (tenant_id, id)
+);
+
+CREATE UNIQUE INDEX recurring_item_type_system_key_uq
+  ON recurring_item_type (key) WHERE tenant_id IS NULL AND deleted_at IS NULL;
+CREATE UNIQUE INDEX recurring_item_type_tenant_key_uq
+  ON recurring_item_type (tenant_id, key) WHERE tenant_id IS NOT NULL AND deleted_at IS NULL;
+
+CREATE TABLE recurring_instance (
+  id uuid PRIMARY KEY,
+  tenant_id uuid NOT NULL REFERENCES tenant(id),
+  client_id uuid NOT NULL,
+  competence_id uuid NOT NULL,
+  item_type_id uuid NOT NULL REFERENCES recurring_item_type(id),
+  label text NOT NULL,
+  nature text NOT NULL CHECK (nature IN ('obligation', 'task')),
+  due_date date,
+  responsible_user_id uuid REFERENCES "user"(id),
+  status text NOT NULL DEFAULT 'pending'
+    CHECK (status IN ('pending', 'in_progress', 'awaiting_client', 'done', 'not_applicable', 'canceled')),
+  completed_at timestamptz,
+  completed_by uuid REFERENCES "user"(id),
+  amount numeric(14, 2),
+  notes text,
+  version int NOT NULL DEFAULT 1 CHECK (version > 0),
+  -- Preservação da origem quando a linha vem da migração de fiscal_obligation
+  -- (ADR 0008 D8). Nunca é preenchido por criação normal.
+  legacy_source text,
+  legacy_source_id uuid,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  deleted_at timestamptz,
+  CONSTRAINT recurring_instance_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  FOREIGN KEY (tenant_id, competence_id) REFERENCES competence (tenant_id, id),
+  CHECK ((status <> 'done') OR completed_at IS NOT NULL)
+);
+
+-- A GARANTIA de idempotência da geração (ADR 0008 D4). O gerador roda
+-- ON CONFLICT DO NOTHING; executá-lo N vezes produz exatamente uma instância.
+-- É o que hoje falta e permite lançar a mesma DAS de julho três vezes.
+CREATE UNIQUE INDEX recurring_instance_competence_type_uq
+  ON recurring_instance (tenant_id, client_id, competence_id, item_type_id)
+  WHERE deleted_at IS NULL;
+CREATE INDEX recurring_instance_due_idx
+  ON recurring_instance (tenant_id, status, due_date)
+  WHERE deleted_at IS NULL;
+CREATE INDEX recurring_instance_client_idx
+  ON recurring_instance (tenant_id, client_id, competence_id);
+
+-- ---------------------------------------------------------------------------
+-- Documentos (ADR 0007)
+-- ---------------------------------------------------------------------------
+
+-- Taxonomia configurável por tenant, semeada pela vertical. O Core não sabe o
+-- que é "DARF" (ADR 0007 D3).
+CREATE TABLE document_category (
+  id uuid PRIMARY KEY,
+  tenant_id uuid REFERENCES tenant(id),
+  key text NOT NULL,
+  label text NOT NULL,
+  retention_months int CHECK (retention_months IS NULL OR retention_months > 0),
+  active boolean NOT NULL DEFAULT true,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT document_category_tenant_id_uq UNIQUE (tenant_id, id)
+);
+CREATE UNIQUE INDEX document_category_system_key_uq
+  ON document_category (key) WHERE tenant_id IS NULL;
+CREATE UNIQUE INDEX document_category_tenant_key_uq
+  ON document_category (tenant_id, key) WHERE tenant_id IS NOT NULL;
+
+-- Bytes físicos. Imutável: nunca sofre UPDATE de conteúdo.
+-- Dedup por (tenant, checksum) — jamais global, ver cabeçalho.
+CREATE TABLE blob (
+  id uuid PRIMARY KEY,
+  tenant_id uuid NOT NULL REFERENCES tenant(id),
+  checksum_sha256 text NOT NULL CHECK (checksum_sha256 ~ '^[a-f0-9]{64}$'),
+  size_bytes bigint NOT NULL CHECK (size_bytes > 0),
+  mime_type text NOT NULL,
+  storage_provider text NOT NULL CHECK (storage_provider IN ('local', 'r2', 's3')),
+  storage_key text NOT NULL,
+  -- Antivírus assíncrono: o download é bloqueado enquanto não estiver clean
+  -- (ADR 0007 D8). O pipeline em si é fase posterior.
+  av_status text NOT NULL DEFAULT 'pending'
+    CHECK (av_status IN ('pending', 'clean', 'infected', 'skipped')),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT blob_tenant_id_uq UNIQUE (tenant_id, id)
+);
+CREATE UNIQUE INDEX blob_tenant_checksum_uq ON blob (tenant_id, checksum_sha256);
+
+CREATE TABLE document (
+  id uuid PRIMARY KEY,
+  tenant_id uuid NOT NULL REFERENCES tenant(id),
+  client_id uuid NOT NULL,
+  competence_id uuid,
+  category_id uuid,
+  title text NOT NULL,
+  status text NOT NULL DEFAULT 'active'
+    CHECK (status IN ('active', 'superseded', 'archived')),
+  current_version_id uuid,
+  version int NOT NULL DEFAULT 1 CHECK (version > 0),
+  created_by uuid REFERENCES "user"(id),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  deleted_at timestamptz,
+  deleted_by uuid REFERENCES "user"(id),
+  CONSTRAINT document_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  FOREIGN KEY (tenant_id, competence_id) REFERENCES competence (tenant_id, id)
+);
+CREATE INDEX document_client_idx
+  ON document (tenant_id, client_id, created_at DESC) WHERE deleted_at IS NULL;
+CREATE INDEX document_competence_idx
+  ON document (tenant_id, competence_id) WHERE deleted_at IS NULL;
+
+-- Versão imutável. version_no monotônico por documento.
+CREATE TABLE document_version (
+  id uuid PRIMARY KEY,
+  tenant_id uuid NOT NULL REFERENCES tenant(id),
+  document_id uuid NOT NULL,
+  blob_id uuid NOT NULL,
+  version_no int NOT NULL CHECK (version_no > 0),
+  original_filename text NOT NULL,
+  uploaded_by uuid REFERENCES "user"(id),
+  -- De onde veio: quem enviou pelo portal é o cliente; pelo console, o escritório.
+  uploaded_via text NOT NULL DEFAULT 'console'
+    CHECK (uploaded_via IN ('console', 'portal', 'import', 'system')),
+  uploaded_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT document_version_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, document_id) REFERENCES document (tenant_id, id),
+  FOREIGN KEY (tenant_id, blob_id) REFERENCES blob (tenant_id, id)
+);
+CREATE UNIQUE INDEX document_version_no_uq
+  ON document_version (tenant_id, document_id, version_no);
+
+ALTER TABLE document
+  ADD CONSTRAINT document_current_version_fk
+  FOREIGN KEY (tenant_id, current_version_id) REFERENCES document_version (tenant_id, id)
+  DEFERRABLE INITIALLY DEFERRED;
+
+-- ---------------------------------------------------------------------------
+-- Pedido de documento (o que destrava o ciclo)
+-- ---------------------------------------------------------------------------
+
+-- Difere de onboarding_document_requirement por NÃO exigir um onboarding: o
+-- pedido vive por cliente e competência, que é o eixo do trabalho recorrente.
+CREATE TABLE document_request (
+  id uuid PRIMARY KEY,
+  tenant_id uuid NOT NULL REFERENCES tenant(id),
+  client_id uuid NOT NULL,
+  competence_id uuid,
+  recurring_instance_id uuid,
+  category_id uuid,
+  title text NOT NULL,
+  description text,
+  status text NOT NULL DEFAULT 'requested'
+    CHECK (status IN ('requested', 'received', 'validated', 'rejected', 'canceled')),
+  due_date date,
+  requested_by uuid REFERENCES "user"(id),
+  requested_at timestamptz NOT NULL DEFAULT now(),
+  received_at timestamptz,
+  validated_at timestamptz,
+  validated_by uuid REFERENCES "user"(id),
+  rejected_at timestamptz,
+  rejected_by uuid REFERENCES "user"(id),
+  rejection_reason text,
+  -- O documento que satisfez o pedido. Diferente do ponteiro órfão que existia
+  -- em onboarding_document_requirement, este tem FK de verdade.
+  document_id uuid,
+  version int NOT NULL DEFAULT 1 CHECK (version > 0),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  deleted_at timestamptz,
+  CONSTRAINT document_request_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  FOREIGN KEY (tenant_id, competence_id) REFERENCES competence (tenant_id, id),
+  FOREIGN KEY (tenant_id, recurring_instance_id) REFERENCES recurring_instance (tenant_id, id),
+  FOREIGN KEY (tenant_id, document_id) REFERENCES document (tenant_id, id),
+  CHECK ((status <> 'rejected') OR rejection_reason IS NOT NULL),
+  CHECK ((status NOT IN ('received', 'validated')) OR document_id IS NOT NULL)
+);
+CREATE INDEX document_request_client_idx
+  ON document_request (tenant_id, client_id, status) WHERE deleted_at IS NULL;
+CREATE INDEX document_request_due_idx
+  ON document_request (tenant_id, status, due_date) WHERE deleted_at IS NULL;
+CREATE INDEX document_request_competence_idx
+  ON document_request (tenant_id, competence_id) WHERE deleted_at IS NULL;
+
+-- ---------------------------------------------------------------------------
+-- O ponteiro órfão do onboarding ganha destino (ADR 0007)
+-- ---------------------------------------------------------------------------
+
+-- canonical_document_id existia desde 0016 como uuid sem FK e sempre nulo.
+-- Agora aponta para document de verdade. Nenhuma linha existente é alterada:
+-- todas têm o campo nulo, então a constraint é satisfeita de imediato.
+ALTER TABLE onboarding_document_requirement
+  ADD CONSTRAINT onboarding_document_requirement_canonical_document_fk
+  FOREIGN KEY (tenant_id, canonical_document_id) REFERENCES document (tenant_id, id);
+
+-- ---------------------------------------------------------------------------
+-- RLS — FORCE em todas, com escopo de cliente onde a tabela é por-cliente
+-- ---------------------------------------------------------------------------
+
+-- Tabelas por-cliente: o portal enxerga apenas o próprio cliente.
+DO $$
+DECLARE
+  t text;
+BEGIN
+  FOREACH t IN ARRAY ARRAY[
+    'competence', 'recurring_instance', 'document', 'document_request'
+  ] LOOP
+    EXECUTE format('ALTER TABLE %I ENABLE ROW LEVEL SECURITY', t);
+    EXECUTE format('ALTER TABLE %I FORCE ROW LEVEL SECURITY', t);
+    EXECUTE format($policy$
+      CREATE POLICY %I_tenant_client_isolation ON %I
+        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
+          )
+        )
+    $policy$, t, t);
+  END LOOP;
+END $$;
+
+-- Tabelas sem client_id: isolamento apenas por tenant.
+-- document_version e blob são alcançados por FK composta a partir de document,
+-- que já é client-scoped — o escopo de cliente é herdado por navegação.
+DO $$
+DECLARE
+  t text;
+BEGIN
+  FOREACH t IN ARRAY ARRAY['blob', 'document_version'] LOOP
+    EXECUTE format('ALTER TABLE %I ENABLE ROW LEVEL SECURITY', t);
+    EXECUTE format('ALTER TABLE %I FORCE ROW LEVEL SECURITY', t);
+    EXECUTE format($policy$
+      CREATE POLICY %I_tenant_isolation ON %I
+        USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+        WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+    $policy$, t, t);
+  END LOOP;
+END $$;
+
+-- Catálogos: template do sistema (tenant_id NULL) é visível a todos; override
+-- só ao dono. Mesma forma da policy de `role` (0006).
+ALTER TABLE recurring_item_type ENABLE ROW LEVEL SECURITY;
+ALTER TABLE recurring_item_type FORCE ROW LEVEL SECURITY;
+CREATE POLICY recurring_item_type_visibility ON recurring_item_type
+  USING (tenant_id IS NULL OR tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+ALTER TABLE document_category ENABLE ROW LEVEL SECURITY;
+ALTER TABLE document_category FORCE ROW LEVEL SECURITY;
+CREATE POLICY document_category_visibility ON document_category
+  USING (tenant_id IS NULL OR tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- Versão é imutável: nenhum UPDATE/DELETE, no mesmo padrão de audit_log (0005).
+CREATE OR REPLACE FUNCTION document_version_immutable() RETURNS trigger AS $$
+BEGIN
+  RAISE EXCEPTION 'document_version é imutável: crie uma nova versão';
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER document_version_no_update
+  BEFORE UPDATE OR DELETE ON document_version
+  FOR EACH ROW EXECUTE FUNCTION document_version_immutable();

package/src/db/migrations/0027_receivable_client_isolation.sql

@@ -0,0 +1,58 @@
+-- 0027 — Isolamento por CLIENTE nas tabelas de Accounts Receivable.
+--
+-- O M0 (0015) criou as policies de AR filtrando apenas por tenant. Enquanto o AR
+-- não tinha leitura pelo Portal, isso bastava. Ao abrir a visão financeira do
+-- contribuinte (Onda 1A), a lacuna vira vazamento: um usuário de portal com o id
+-- de um recebível alheio recebia HTTP 200 — o mesmo formato do defeito corrigido
+-- na PR #69, agora numa tabela diferente.
+--
+-- O predicado adotado é o mesmo já usado em `document`/`service_request`:
+--
+--     current_client IS NULL  → staff, vê o tenant inteiro
+--     current_client = X      → portal, vê apenas o cliente X
+--
+-- `receivable_item` e `payment` não carregam `client_id`; herdam o recorte do
+-- `receivable` a que pertencem, via EXISTS. É mais caro que uma comparação
+-- direta, mas evita desnormalizar `client_id` em três tabelas só para a policy —
+-- e o índice `receivable_client_idx` já cobre o lookup.
+
+-- ── receivable ───────────────────────────────────────────────────────────────
+DROP POLICY IF EXISTS receivable_tenant_isolation ON receivable;
+CREATE POLICY receivable_tenant_client_isolation ON receivable
+  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
+    )
+  );
+
+-- ── receivable_item ──────────────────────────────────────────────────────────
+DROP POLICY IF EXISTS receivable_item_tenant_isolation ON receivable_item;
+CREATE POLICY receivable_item_tenant_client_isolation ON receivable_item
+  USING (
+    tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid
+    AND (
+      NULLIF(current_setting('app.current_client', true), '') IS NULL
+      OR EXISTS (
+        SELECT 1 FROM receivable r
+         WHERE r.id = receivable_item.receivable_id
+           AND r.client_id = NULLIF(current_setting('app.current_client', true), '')::uuid
+      )
+    )
+  );
+
+-- ── payment ──────────────────────────────────────────────────────────────────
+DROP POLICY IF EXISTS payment_tenant_isolation ON payment;
+CREATE POLICY payment_tenant_client_isolation ON payment
+  USING (
+    tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid
+    AND (
+      NULLIF(current_setting('app.current_client', true), '') IS NULL
+      OR EXISTS (
+        SELECT 1 FROM receivable r
+         WHERE r.id = payment.receivable_id
+           AND r.client_id = NULLIF(current_setting('app.current_client', true), '')::uuid
+      )
+    )
+  );

package/src/db/migrations/0028_collection_engine.sql

@@ -0,0 +1,94 @@
+-- 0028 — Motor de cobrança: `dunning_event` passa a ancorar no Receivable.
+--
+-- O NÓ: `dunning_event` nasceu (0014) amarrada a `charge` — FK composta
+-- `(tenant_id, charge_id) → charge` e único `(tenant_id, charge_id, step_key)`.
+-- Mas `charge` é o INSTRUMENTO (boleto/pix), e a Onda 1A criou os recebíveis
+-- deliberadamente SEM instrumento. Resultado: a régua não tinha em que se
+-- ancorar, e a idempotência apontava para uma linha que não existe.
+--
+-- POR QUE ESTENDER EM VEZ DE CRIAR TABELA NOVA: a semântica de `dunning_event`
+-- ("este passo da régua já foi executado para esta dívida") é exatamente a que o
+-- motor precisa, e a FK composta já é tenant-safe. Criar uma segunda tabela
+-- deixaria duas fontes de verdade para idempotência de cobrança — que é
+-- precisamente o tipo de ambiguidade que produz cobrança duplicada.
+--
+-- A âncora vira exclusiva: OU `charge_id` OU `receivable_id`, nunca ambos, nunca
+-- nenhum. Os índices únicos são PARCIAIS, um por caso, porque um único índice
+-- sobre colunas nulas não impede duplicata (NULL nunca é igual a NULL).
+
+ALTER TABLE dunning_event ADD COLUMN IF NOT EXISTS receivable_id uuid;
+ALTER TABLE dunning_event ALTER COLUMN charge_id DROP NOT NULL;
+
+ALTER TABLE dunning_event
+  ADD CONSTRAINT dunning_event_receivable_fk
+  FOREIGN KEY (tenant_id, receivable_id) REFERENCES receivable (tenant_id, id);
+
+ALTER TABLE dunning_event
+  ADD CONSTRAINT dunning_event_anchor_ck
+  CHECK ((charge_id IS NULL) <> (receivable_id IS NULL));
+
+-- O único original cobria `(tenant, charge, step)` com charge NOT NULL. Agora
+-- que charge é nulo no caminho novo, ele deixa de proteger — daí os parciais.
+DROP INDEX IF EXISTS dunning_event_uq;
+CREATE UNIQUE INDEX dunning_event_charge_uq
+  ON dunning_event (tenant_id, charge_id, step_key) WHERE charge_id IS NOT NULL;
+CREATE UNIQUE INDEX dunning_event_receivable_uq
+  ON dunning_event (tenant_id, receivable_id, step_key) WHERE receivable_id IS NOT NULL;
+
+-- ── Ciclo de vida da ação ───────────────────────────────────────────────────
+--
+-- A tabela deixa de ser só um log do que saiu e passa a carregar o que está
+-- AGENDADO. Sem isso não há como responder "o que vou cobrar hoje" nem como
+-- cancelar o que ainda não foi enviado quando o cliente paga.
+ALTER TABLE dunning_event ADD COLUMN IF NOT EXISTS status text NOT NULL DEFAULT 'sent'
+  CHECK (status IN ('scheduled','sent','failed','canceled','escalated'));
+ALTER TABLE dunning_event ADD COLUMN IF NOT EXISTS scheduled_for date;
+ALTER TABLE dunning_event ADD COLUMN IF NOT EXISTS template text;
+ALTER TABLE dunning_event ADD COLUMN IF NOT EXISTS attempts int NOT NULL DEFAULT 0;
+ALTER TABLE dunning_event ADD COLUMN IF NOT EXISTS last_error text;
+ALTER TABLE dunning_event ADD COLUMN IF NOT EXISTS sent_at timestamptz;
+ALTER TABLE dunning_event ADD COLUMN IF NOT EXISTS closed_at timestamptz;
+-- Motivo em vocabulário fechado: 'paid', 'canceled', 'rule_disabled',
+-- 'permanent_failure', 'escalated'. Texto livre aqui viraria relatório que
+-- ninguém consegue agregar.
+ALTER TABLE dunning_event ADD COLUMN IF NOT EXISTS closed_reason text;
+-- Referência LÓGICA do destinatário (e-mail do contato, telefone). Guardada para
+-- a trilha responder "para onde foi" sem depender de o cadastro do cliente
+-- continuar igual seis meses depois.
+ALTER TABLE dunning_event ADD COLUMN IF NOT EXISTS recipient_ref text;
+-- Saldo no momento do disparo. Uma cobrança precisa poder provar QUAL valor
+-- anunciou — depois de uma baixa parcial, o saldo de hoje não é o de ontem.
+ALTER TABLE dunning_event ADD COLUMN IF NOT EXISTS amount_at_send numeric(14,2);
+
+CREATE INDEX IF NOT EXISTS dunning_event_due_idx
+  ON dunning_event (tenant_id, status, scheduled_for);
+CREATE INDEX IF NOT EXISTS dunning_event_receivable_idx
+  ON dunning_event (tenant_id, receivable_id, status);
+
+-- ── RLS: tenant E cliente ───────────────────────────────────────────────────
+--
+-- Mesmo padrão da 0027. A tabela não carrega `client_id`; herda o recorte do
+-- receivable. O caminho `charge` mantém só o corte por tenant, porque `charge`
+-- não é exposto ao Portal.
+DROP POLICY IF EXISTS dunning_event_tenant_isolation ON dunning_event;
+CREATE POLICY dunning_event_tenant_client_isolation ON dunning_event
+  USING (
+    tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid
+    AND (
+      NULLIF(current_setting('app.current_client', true), '') IS NULL
+      OR EXISTS (
+        SELECT 1 FROM receivable r
+         WHERE r.id = dunning_event.receivable_id
+           AND r.client_id = NULLIF(current_setting('app.current_client', true), '')::uuid
+      )
+    )
+  );
+
+-- ── Política de cobrança por tenant ─────────────────────────────────────────
+--
+-- `dunning_rule` (0014) já guarda `steps jsonb` por tenant e é reaproveitada —
+-- não há tabela nova de política. Só falta marcar qual é a padrão do escritório
+-- quando houver mais de uma.
+ALTER TABLE dunning_rule ADD COLUMN IF NOT EXISTS is_default boolean NOT NULL DEFAULT false;
+CREATE UNIQUE INDEX IF NOT EXISTS dunning_rule_default_uq
+  ON dunning_rule (tenant_id) WHERE is_default AND active;

package/src/db/migrations/0029_payment_rail.sql

@@ -0,0 +1,107 @@
+-- 0029 — Payment Rail: o elo entre o recebível interno e a cobrança no provider.
+--
+-- O M0 (0015) já modelou `payment_provider_account` por tenant, `receivable`,
+-- `payment` e `webhook_event`. O que faltava era ligar a ponta: uma `charge`
+-- não sabia a qual recebível pertencia nem por qual conta foi emitida — e sem
+-- isso o webhook do provider não tem como achar o recebível a dar baixa.
+--
+-- Aditiva e reversível: nenhuma coluna existente muda de tipo ou de nulidade,
+-- nenhuma linha é reescrita. Cobranças antigas ficam com os campos novos nulos,
+-- que é a verdade sobre elas — nasceram sem recebível.
+
+-- ── Segredo de webhook, ao lado da credencial de API ─────────────────────────
+--
+-- `credential_ref` guarda a chave que EMITE cobrança. O token que AUTENTICA o
+-- webhook é outro segredo, com outro ciclo de rotação, e precisa de referência
+-- própria — sem ela a rota pública não tem como se fechar.
+ALTER TABLE payment_provider_account
+  ADD COLUMN IF NOT EXISTS webhook_credential_ref text;
+
+-- ── charge → receivable ──────────────────────────────────────────────────────
+ALTER TABLE charge ADD COLUMN IF NOT EXISTS receivable_id uuid;
+ALTER TABLE charge ADD COLUMN IF NOT EXISTS provider_account_id uuid;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'charge_receivable_fk') THEN
+    ALTER TABLE charge ADD CONSTRAINT charge_receivable_fk
+      FOREIGN KEY (tenant_id, receivable_id) REFERENCES receivable (tenant_id, id);
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'charge_provider_account_fk') THEN
+    ALTER TABLE charge ADD CONSTRAINT charge_provider_account_fk
+      FOREIGN KEY (tenant_id, provider_account_id)
+      REFERENCES payment_provider_account (tenant_id, id);
+  END IF;
+END $$;
+
+-- Idempotência estrutural: no máximo UMA cobrança viva por recebível.
+--
+-- O código também protege, mas retry, job repetido, deploy no meio da chamada e
+-- clique duplo são exatamente os casos em que o código perde. Aqui o banco
+-- recusa a segunda cobrança, e o chamador trata a violação buscando a que já
+-- existe. Cobrança cancelada/estornada não conta — depois de cancelar, o
+-- escritório precisa poder emitir outra.
+CREATE UNIQUE INDEX IF NOT EXISTS charge_active_per_receivable_uq
+  ON charge (tenant_id, receivable_id)
+  WHERE receivable_id IS NOT NULL
+    AND deleted_at IS NULL
+    AND status NOT IN ('canceled', 'refunded');
+
+CREATE INDEX IF NOT EXISTS charge_receivable_idx
+  ON charge (tenant_id, receivable_id) WHERE receivable_id IS NOT NULL;
+
+-- ── Cliente do tenant ↔ customer no provider ─────────────────────────────────
+--
+-- O Asaas (como todo gateway) exige um `customer` próprio antes de aceitar uma
+-- cobrança. Recriá-lo a cada emissão produziria clientes duplicados na conta do
+-- escritório e quebraria o histórico dele lá dentro. Este mapa é a memória de
+-- "quem já foi provisionado", e é POR CONTA: o mesmo cliente pode existir em
+-- duas contas diferentes com ids diferentes.
+CREATE TABLE IF NOT EXISTS payment_customer (
+  id                  uuid PRIMARY KEY,
+  tenant_id           uuid NOT NULL REFERENCES tenant(id),
+  client_id           uuid NOT NULL,
+  provider_account_id uuid NOT NULL,
+  provider            text NOT NULL,
+  external_id         text NOT NULL,
+  created_at          timestamptz NOT NULL DEFAULT now(),
+  updated_at          timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT payment_customer_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  FOREIGN KEY (tenant_id, provider_account_id)
+    REFERENCES payment_provider_account (tenant_id, id)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS payment_customer_account_client_uq
+  ON payment_customer (tenant_id, provider_account_id, client_id);
+
+ALTER TABLE payment_customer ENABLE ROW LEVEL SECURITY;
+ALTER TABLE payment_customer FORCE ROW LEVEL SECURITY;
+DROP POLICY IF EXISTS payment_customer_tenant_isolation ON payment_customer;
+CREATE POLICY payment_customer_tenant_isolation ON payment_customer
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ── Pagamento: de onde veio a confirmação ────────────────────────────────────
+--
+-- `payment.metadata` já guardaria isso, mas o id do pagamento no provider é a
+-- chave de reconciliação e de investigação — merece coluna, índice e unicidade.
+-- Webhook duplicado é a regra, não a exceção: o gateway reenvia até receber 200.
+ALTER TABLE payment ADD COLUMN IF NOT EXISTS provider text;
+ALTER TABLE payment ADD COLUMN IF NOT EXISTS provider_payment_id text;
+
+CREATE UNIQUE INDEX IF NOT EXISTS payment_provider_payment_uq
+  ON payment (tenant_id, provider, provider_payment_id)
+  WHERE provider_payment_id IS NOT NULL;
+
+-- ── Dedup de webhook por conta ───────────────────────────────────────────────
+--
+-- `webhook_event` já tinha unicidade por (provider, external_event_id). Falta
+-- saber QUAL conta recebeu o evento: dois escritórios no mesmo provider podem,
+-- em tese, receber ids que só são únicos dentro da própria conta. Sem esta
+-- coluna, o evento de um tenant poderia bloquear o de outro pelo índice.
+ALTER TABLE webhook_event ADD COLUMN IF NOT EXISTS provider_account_id uuid;
+
+DROP INDEX IF EXISTS webhook_event_idempotency_uq;
+CREATE UNIQUE INDEX IF NOT EXISTS webhook_event_idempotency_uq
+  ON webhook_event (provider, COALESCE(provider_account_id, '00000000-0000-0000-0000-000000000000'::uuid), external_event_id);

package/src/db/migrations/0030_provider_account_uniqueness.sql

@@ -0,0 +1,22 @@
+-- 0030 — Duas organizações não podem receber na mesma conta.
+--
+-- Esta regra nasceu como uma consulta em código, e a consulta não funcionava:
+-- `payment_provider_account` tem RLS FORCE, então um `SELECT ... WHERE
+-- tenant_id <> $atual` devolve **sempre zero linhas** — a política esconde
+-- exatamente as linhas que a checagem precisava encontrar. O guard parecia
+-- proteger e não protegia.
+--
+-- Índice único opera acima da RLS: ele enxerga a tabela inteira e recusa o
+-- INSERT mesmo quando quem insere não pode ver a linha conflitante. É a única
+-- forma de a garantia ser real aqui.
+--
+-- Por que a regra importa: `account_reference` identifica a conta no gateway.
+-- Dois escritórios apontando para a mesma conta significa o dinheiro de um
+-- caindo na conta do outro — o pior desfecho possível deste produto.
+--
+-- Conta revogada não ocupa a vaga: depois de desconectar, a mesma conta pode
+-- ser reconectada, inclusive por outra organização (troca de contador, por
+-- exemplo).
+CREATE UNIQUE INDEX IF NOT EXISTS payment_provider_account_reference_uq
+  ON payment_provider_account (provider, account_reference)
+  WHERE account_reference IS NOT NULL AND status <> 'revoked';

package/src/db/migrations/0031_provider_account_environment_scope.sql

@@ -0,0 +1,21 @@
+-- 0031 — A unicidade da conta financeira precisa incluir o AMBIENTE.
+--
+-- Dois problemas encontrados ao revalidar a conta sandbox da SC:
+--
+-- 1. `account_reference` ficou NULL, porque o `/myAccount` do Asaas não expõe
+--    `walletId` nem `id` nessa conta. O índice de unicidade é PARCIAL
+--    (`WHERE account_reference IS NOT NULL`), então o guard que impede duas
+--    organizações de receberem na mesma conta estava **inativo na configuração
+--    real** — parecia proteger e não protegia.
+--
+--    O adapter passa a derivar a referência do documento quando o gateway não
+--    dá id próprio. Documento é o que identifica o titular do dinheiro, que é
+--    justamente o que o guard precisa comparar.
+--
+-- 2. Sem o ambiente na chave, a mesma empresa não conseguiria conectar `live`
+--    tendo passado por `sandbox` com a referência derivada do mesmo documento.
+--    A "mesma conta" em ambientes diferentes é conta diferente.
+DROP INDEX IF EXISTS payment_provider_account_reference_uq;
+CREATE UNIQUE INDEX IF NOT EXISTS payment_provider_account_reference_uq
+  ON payment_provider_account (provider, environment, account_reference)
+  WHERE account_reference IS NOT NULL AND status <> 'revoked';