@baruk/core 0.3.1 → 0.5.0

package/src/db/migrations/0032_settlement_reversal.sql

@@ -0,0 +1,76 @@
+-- 0032 — Reversão de liquidação (dívida L da Onda 1B.4.2)
+--
+-- O gateway pode desfazer uma baixa que ele próprio registrou: o caso concreto é
+-- o "recebimento em dinheiro" informado à mão no painel e depois cancelado. Até
+-- aqui o sistema não tinha como representar isso. A cobrança continuava `paid`,
+-- o `payment` continuava `confirmed`, o recebível continuava quitado — e a régua
+-- de cobrança ficava desligada para sempre. Um dinheiro que nunca entrou saía do
+-- sistema como recebido.
+--
+-- A distinção que este schema passa a suportar é financeira, não cosmética:
+--
+--   `refunded`  — o dinheiro ENTROU e depois SAIU. Dois fatos, duas linhas na
+--                 história do caixa. A dívida foi quitada; o estorno é evento
+--                 novo, e não desfaz a quitação.
+--   `reversed`  — o dinheiro NUNCA ENTROU. O registro de liquidação estava
+--                 errado e foi anulado na origem. Não há fato novo de caixa: há
+--                 um fato anterior que deixou de valer.
+--
+-- Reaproveitar `refunded` para o segundo caso poria no extrato do escritório uma
+-- devolução que nunca aconteceu.
+--
+-- NADA é apagado. A linha de `payment` permanece, com o valor, o método e a data
+-- em que se acreditou ter recebido; ela apenas deixa de contar no saldo, e passa
+-- a carregar quando e por que foi anulada. `charge.paid_at` também permanece: é
+-- o registro de quando a cobrança esteve liquidada.
+
+-- ── payment ────────────────────────────────────────────────────────────────
+ALTER TABLE payment DROP CONSTRAINT IF EXISTS payment_status_check;
+ALTER TABLE payment ADD CONSTRAINT payment_status_check
+  CHECK (status IN ('detected', 'confirmed', 'refunded', 'reversed'));
+
+ALTER TABLE payment ADD COLUMN IF NOT EXISTS reversed_at timestamptz;
+-- Motivo em texto curto e estável (`settlement_undone`, …), não prosa livre:
+-- quem for auditar precisa agrupar, e não ler.
+ALTER TABLE payment ADD COLUMN IF NOT EXISTS reversal_reason text;
+
+-- Um pagamento revertido tem de dizer QUANDO. Sem isto a anulação vira um
+-- status sem data, e a pergunta "desde quando este dinheiro deixou de contar?"
+-- deixa de ter resposta.
+ALTER TABLE payment DROP CONSTRAINT IF EXISTS payment_reversed_at_check;
+ALTER TABLE payment ADD CONSTRAINT payment_reversed_at_check
+  CHECK ((status = 'reversed') = (reversed_at IS NOT NULL));
+
+-- ── charge ─────────────────────────────────────────────────────────────────
+ALTER TABLE charge DROP CONSTRAINT IF EXISTS charge_status_check;
+ALTER TABLE charge ADD CONSTRAINT charge_status_check
+  CHECK (status IN ('pending', 'sent', 'paid', 'overdue', 'canceled', 'refunded', 'reversed'));
+
+ALTER TABLE charge ADD COLUMN IF NOT EXISTS reversed_at timestamptz;
+
+-- `reversed` NÃO entra na lista de cobranças mortas do índice único parcial de
+-- `charge (tenant_id, receivable_id)`, e isso é deliberado: o boleto ou o PIX
+-- continuam válidos no gateway e continuam pagáveis. A cobrança revertida segue
+-- sendo A cobrança viva do recebível — emitir uma segunda para a mesma dívida é
+-- que produziria duplicidade. Pela mesma razão, a régua de cobrança volta a
+-- alcançá-la: `dunning` só ignora `paid`, `canceled` e `refunded`.
+
+-- ── Unicidade do id de pagamento no provider ───────────────────────────────
+--
+-- O índice da 0029 impede que o MESMO pagamento do gateway vire duas baixas —
+-- webhook duplicado é a regra, não a exceção. Ele continua valendo.
+--
+-- O que muda é o alcance: uma linha ANULADA deixa de ocupar o id. A cobrança
+-- revertida continua pagável, e quando o cliente de fato paga, o gateway usa o
+-- mesmo `pay_…`. Com o índice cobrindo linhas anuladas, essa baixa legítima
+-- estouraria unicidade, a transação inteira do webhook falharia, e o gateway
+-- reenviaria para sempre um pagamento que o sistema nunca conseguiria registrar.
+-- Dinheiro real entrando e não sendo baixado — o defeito que esta onda existe
+-- para eliminar, reaparecendo pela porta oposta.
+--
+-- Duas linhas CONFIRMADAS com o mesmo id continuam impossíveis, que é o que o
+-- índice protege.
+DROP INDEX IF EXISTS payment_provider_payment_uq;
+CREATE UNIQUE INDEX payment_provider_payment_uq
+  ON payment (tenant_id, provider, provider_payment_id)
+  WHERE provider_payment_id IS NOT NULL AND status <> 'reversed';

package/src/db/migrations/0033_receivable_idempotency.sql

@@ -0,0 +1,28 @@
+-- 0033 — Idempotência do lançamento avulso
+--
+-- A emissão da COBRANÇA já era idempotente: o índice único parcial de
+-- `charge (tenant_id, receivable_id)` garante uma cobrança viva por recebível.
+-- O RECEBÍVEL não era. Um duplo clique no formulário, um retry de HTTP ou um
+-- refresh depois do POST criavam dois recebíveis para o mesmo serviço — e, com
+-- dois recebíveis, duas cobranças legítimas, cada uma com o seu PIX. O cliente
+-- receberia dois pedidos de pagamento do mesmo trabalho.
+--
+-- O fluxo por competência nunca teve esse problema porque a idempotência dele é
+-- semântica: o único `(tenant, fee_agreement, competence)` diz "esta dívida já
+-- existe". No avulso não há chave semântica — dois honorários avulsos de mesmo
+-- valor, mesma descrição e mesmo vencimento podem ser dois serviços de verdade,
+-- e recusar o segundo seria um defeito pior.
+--
+-- Daí a chave vir de FORA: quem inicia a operação declara um identificador da
+-- TENTATIVA. Reenviar a mesma tentativa devolve o mesmo recebível; um novo
+-- lançamento tem chave nova e é criado normalmente. A distinção entre "de novo" e
+-- "outra vez" passa a ser do chamador, que é quem realmente sabe.
+ALTER TABLE receivable ADD COLUMN IF NOT EXISTS idempotency_key text;
+
+-- Parcial: só as linhas que declararam chave participam. Sem o `WHERE`, todo
+-- recebível gerado por competência (chave nula) colidiria com o primeiro —
+-- porque em índice único comum `NULL` não colide, mas a intenção aqui é explícita
+-- e vale registrá-la.
+CREATE UNIQUE INDEX IF NOT EXISTS receivable_idempotency_uq
+  ON receivable (tenant_id, idempotency_key)
+  WHERE idempotency_key IS NOT NULL;

package/src/db/migrations/0034_payment_customer_reconcile.sql

@@ -0,0 +1,30 @@
+-- 0034 — Reconciliação cadastral do pagador no provedor (dívida R)
+--
+-- `payment_customer` guardava o id do pagador no gateway e nada mais. O efeito
+-- prático era uma afirmação que o schema nunca fez, mas o código assumia:
+-- *"este cliente já existe lá, logo os dados dele estão corretos para sempre"*.
+--
+-- Não estão. Um cliente cadastrado no Office SEM CPF/CNPJ produzia um pagador
+-- sem documento no gateway. Corrigir o documento no Office não mudava nada lá —
+-- o cache devolvia o id e o adapter sequer era chamado — e a emissão continuava
+-- sendo recusada pelo provedor. O escritório corrigia no lugar certo e o sistema
+-- seguia dizendo não.
+--
+-- A coluna nova responde outra pergunta: não "existe?", mas **"o que está lá
+-- corresponde ao que temos aqui?"**.
+ALTER TABLE payment_customer ADD COLUMN IF NOT EXISTS synced_fingerprint text;
+ALTER TABLE payment_customer ADD COLUMN IF NOT EXISTS synced_at timestamptz;
+
+-- É um DIGEST, nunca os dados.
+--
+-- Guardar nome, documento, e-mail e telefone aqui duplicaria dado pessoal que já
+-- vive em `client`, com uma segunda cópia para manter em dia e vazar. O digest
+-- responde exatamente a pergunta que interessa — "mudou desde a última
+-- sincronização?" — e não responde nenhuma outra.
+COMMENT ON COLUMN payment_customer.synced_fingerprint IS
+  'sha256 dos campos cadastrais enviados ao provedor. Digest, nunca os valores.';
+
+-- Linhas antigas ficam com `NULL` de propósito: nulo significa "nunca
+-- reconciliado", e a primeira emissão de cada cliente existente vai reconciliar.
+-- É assim que a dívida R se cura sozinha na base atual, sem backfill adivinhando
+-- o que o gateway tem.

package/src/db/migrations/0035_payment_account_environments.sql

@@ -0,0 +1,61 @@
+-- 0035 — Sandbox e produção deixam de ser excludentes (dívida U)
+--
+-- O único por `(tenant_id, provider)` dizia, na prática: *um escritório tem UMA
+-- conta Asaas*. Ambiente não fazia parte da identidade lógica, então ativar
+-- produção exigia **revogar o laboratório** — e a decisão "vou cobrar de
+-- verdade" ficava amarrada a "vou perder onde ensaio".
+--
+-- Duas contas do mesmo provedor em ambientes diferentes não são a mesma conta.
+-- Elas têm credencial distinta, endpoint distinto, dinheiro distinto — e a 0031
+-- já reconhecia isso ao pôr `environment` na unicidade da referência externa. O
+-- que faltava era reconhecer o mesmo no único por tenant.
+ALTER TABLE payment_provider_account
+  ADD COLUMN IF NOT EXISTS is_primary boolean NOT NULL DEFAULT false;
+
+-- ── 1. Uma conta por (tenant, provider, AMBIENTE) ──────────────────────────
+DROP INDEX IF EXISTS payment_provider_account_provider_uq;
+CREATE UNIQUE INDEX IF NOT EXISTS payment_provider_account_env_uq
+  ON payment_provider_account (tenant_id, provider, environment)
+  WHERE status <> 'revoked';
+
+-- ── 2. Exatamente UMA conta operacional por (tenant, provider) ─────────────
+--
+-- Coexistir não pode virar ambiguidade. Sem esta trava, "qual conta emite?"
+-- passaria a depender de ordem de criação ou de um `LIMIT 1` — que é
+-- exatamente a escolha implícita que não se pode ter quando o assunto é
+-- para onde vai o dinheiro.
+--
+-- A promoção desta marca é o ato de "entrar em produção": explícito, auditável
+-- e reversível, em vez de um efeito colateral de revogar o sandbox.
+CREATE UNIQUE INDEX IF NOT EXISTS payment_provider_account_primary_uq
+  ON payment_provider_account (tenant_id, provider)
+  WHERE is_primary AND status <> 'revoked';
+
+-- ── 3. Classificação dos registros existentes ──────────────────────────────
+--
+-- Toda conta viva hoje É a conta operacional do seu escritório — era a única
+-- que podia existir. Marcá-la mantém o comportamento atual EXATAMENTE como
+-- está: quem já emitia pelo sandbox continua emitindo pelo sandbox.
+--
+-- Nada é reinterpretado: nenhum `sandbox` vira `live`, nenhum ambiente é
+-- adivinhado. `environment` já existia preenchido e NOT NULL desde a 0015.
+UPDATE payment_provider_account SET is_primary = true WHERE status <> 'revoked';
+
+-- ── 4. Isolamento do identificador externo da cobrança ─────────────────────
+--
+-- `charge_external_uq` era `(tenant_id, provider, external_id)` — cego ao
+-- ambiente. Com as duas contas coexistindo, um `pay_…` de sandbox e um de
+-- produção que coincidissem colidiriam, e a emissão legítima seria recusada.
+--
+-- Passa a incluir a CONTA. Cobrança anterior ao Payment Rail não tem conta;
+-- `COALESCE` para o uuid nulo preserva a proteção dessas linhas entre si, em
+-- vez de deixá-las fora do índice como `NULL` faria.
+DROP INDEX IF EXISTS charge_external_uq;
+CREATE UNIQUE INDEX IF NOT EXISTS charge_external_uq
+  ON charge (tenant_id, provider,
+             COALESCE(provider_account_id, '00000000-0000-0000-0000-000000000000'::uuid),
+             external_id)
+  WHERE external_id IS NOT NULL AND deleted_at IS NULL;
+
+COMMENT ON COLUMN payment_provider_account.is_primary IS
+  'A conta que o escritório OPERA. Exatamente uma por (tenant, provider). Promover é o ato de entrar em produção.';

package/src/db/migrations/0036_primary_backfill_under_force_rls.sql

@@ -0,0 +1,41 @@
+-- 0036 — refazer o backfill de `is_primary` que a 0035 não conseguiu aplicar.
+--
+-- `payment_provider_account` tem FORCE ROW LEVEL SECURITY: a política vale
+-- inclusive para o DONO da tabela, que é quem roda as migrations. O UPDATE da
+-- 0035 rodou sem `app.current_tenant` definida, a política não casou com linha
+-- nenhuma e o comando afetou ZERO linhas — sem erro, sem aviso, com a migration
+-- registrada como aplicada.
+--
+-- A consequência não é cosmética. `getActiveProviderAccount` passou a exigir
+-- `is_primary`; com o backfill vazio, um escritório que já tinha conta conectada
+-- ficava sem conta operacional e simplesmente não conseguia emitir — um sistema
+-- financeiro mudo por causa de um UPDATE que "deu certo".
+--
+-- A 0035 é imutável (o migrador confere checksum), então a correção vem adiante.
+-- `NO FORCE` só vale dentro desta transação; se qualquer passo falhar, o ALTER
+-- volta atrás junto com o resto.
+
+ALTER TABLE payment_provider_account NO FORCE ROW LEVEL SECURITY;
+
+-- Uma primária por (tenant, provider). `created_at` decide: a conta mais antiga
+-- é a que o escritório vinha usando, e promover a mais nova trocaria silen-
+-- ciosamente para onde o dinheiro vai — exatamente o que esta migration não
+-- pode fazer. Tenant que já tem primária não é tocado.
+WITH escolhida AS (
+  SELECT DISTINCT ON (tenant_id, provider) id
+    FROM payment_provider_account
+   WHERE status <> 'revoked'
+     AND NOT EXISTS (
+           SELECT 1 FROM payment_provider_account outra
+            WHERE outra.tenant_id = payment_provider_account.tenant_id
+              AND outra.provider  = payment_provider_account.provider
+              AND outra.is_primary
+              AND outra.status <> 'revoked')
+   ORDER BY tenant_id, provider, created_at
+)
+UPDATE payment_provider_account
+   SET is_primary = true, updated_at = now()
+  FROM escolhida
+ WHERE payment_provider_account.id = escolhida.id;
+
+ALTER TABLE payment_provider_account FORCE ROW LEVEL SECURITY;

package/src/db/migrations/0037_receivable_generation_source.sql

@@ -0,0 +1,29 @@
+-- 0037 — Quem criou o recebível: a pessoa ou o relógio
+--
+-- A geração por competência passa a acontecer sozinha, todo dia, para todo
+-- honorário ativo (AUTO_RECURRING_RECEIVABLE_GENERATION). O motor é o MESMO da
+-- ação "Gerar competência manualmente" — deliberadamente, para que não existam
+-- duas regras discordando sobre quanto o cliente deve. O que muda é só quem
+-- puxou o gatilho.
+--
+-- E é essa distinção que precisa sobreviver na linha. Sem ela, "por que este
+-- cliente tem recebível de agosto se ninguém gerou agosto?" não tem resposta
+-- consultável: `created_by` fica nulo tanto no automático quanto num script, e
+-- a trilha de auditoria responde por LOTE, não por recebível. Quando alguém
+-- contestar uma dívida — e alguém vai —, a pergunta será sobre UMA linha.
+--
+-- `generated_by` NÃO é natureza financeira. Um recebível automático e um manual
+-- da mesma competência são a mesma dívida, com o mesmo valor, o mesmo
+-- vencimento e a mesma régua. A coluna é procedência, não classificação: nada
+-- no domínio pode decidir cobrar diferente por causa dela.
+ALTER TABLE receivable
+  ADD COLUMN IF NOT EXISTS generated_by text NOT NULL DEFAULT 'manual'
+    CHECK (generated_by IN ('manual', 'automatic'));
+
+-- Default 'manual' e não 'unknown': tudo que existe hoje foi criado por uma
+-- pessoa apertando um botão ou por um script que uma pessoa rodou. Marcar o
+-- acervo como desconhecido descreveria pior a realidade do que descrevê-lo como
+-- manual, e obrigaria toda leitura futura a tratar um terceiro caso que só
+-- existiria por causa desta migração.
+COMMENT ON COLUMN receivable.generated_by IS
+  'Procedência: manual (operador/rota) ou automatic (scheduler). Nunca altera a natureza financeira.';

package/src/db/migrations/0038_notification_channels.sql

@@ -0,0 +1,175 @@
+-- 0038 — Canais de cobrança além do e-mail: WhatsApp e SMS
+--
+-- O motor de cobrança (0028) já era agnóstico de canal: a política declara o
+-- canal por etapa, o adapter entrega, o desfecho volta normalizado. O que não
+-- existia era o que um canal de TELEFONE exige e o e-mail não: um número em
+-- formato canônico, permissão para usá-lo, e correlação com o identificador que
+-- o provider devolve.
+--
+-- Esta migração acrescenta só isso. Nenhuma regra financeira muda.
+
+-- ── Telefone canônico do cliente ────────────────────────────────────────────
+--
+-- `client.phone` continua sendo o que o operador digitou — "(62) 99999-8888",
+-- "62 9 9999 8888", "+55 62 99999-8888". Deliberadamente: é o que ele reconhece
+-- na tela, e reescrever o campo do usuário para caber num provider é o tipo de
+-- "melhoria" que faz alguém perder o ramal anotado no fim da linha.
+--
+-- O que os providers exigem é E.164, e essa é uma DERIVAÇÃO. Guardá-la separada
+-- permite responder três perguntas que hoje não têm resposta: este cliente tem
+-- número utilizável? é celular (WhatsApp/SMS) ou fixo? e o que exatamente foi
+-- enviado ao provider, seis meses depois, quando o cadastro já mudou.
+ALTER TABLE client ADD COLUMN IF NOT EXISTS phone_e164 text;
+
+-- Parcial e não único: dois clientes do mesmo escritório podem legitimamente
+-- compartilhar um telefone (marido e mulher, matriz e filial, o contador da
+-- empresa). Unicidade aqui recusaria cadastro válido.
+CREATE INDEX IF NOT EXISTS client_phone_e164_idx
+  ON client (tenant_id, phone_e164)
+  WHERE phone_e164 IS NOT NULL AND deleted_at IS NULL;
+
+-- ── Permissão de canal ──────────────────────────────────────────────────────
+--
+-- Uma linha por (cliente, canal). A AUSÊNCIA de linha não é "pode": é
+-- "ninguém decidiu ainda", e quem decide o que fazer com a ausência é a
+-- política do tenant, não esta tabela.
+--
+-- Por que uma tabela e não uma coluna booleana em `client`: opt-out precisa
+-- registrar QUANDO e POR QUEM. "Este cliente pediu para não receber WhatsApp"
+-- vira uma discussão desagradável no dia em que ele recebe assim mesmo, e uma
+-- coluna `whatsapp_ok = false` não tem como responder quando ele pediu, se
+-- pediu ou se alguém desmarcou por engano.
+CREATE TABLE IF NOT EXISTS client_channel_consent (
+  id          uuid PRIMARY KEY,
+  tenant_id   uuid NOT NULL REFERENCES tenant(id),
+  client_id   uuid NOT NULL,
+  channel     text NOT NULL CHECK (channel IN ('email', 'whatsapp', 'sms')),
+  -- `granted`  = pode enviar (consentimento registrado ou relação contratual)
+  -- `denied`   = opt-out. NUNCA enviar, por nenhuma via — nem manual.
+  -- `unknown`  = registro existe mas ninguém decidiu; a política resolve.
+  state       text NOT NULL DEFAULT 'unknown'
+                CHECK (state IN ('granted', 'denied', 'unknown')),
+  -- Como a decisão chegou. `customer_reply` é o opt-out que o próprio cliente
+  -- pediu (responder SAIR no WhatsApp, por exemplo) e é o mais forte de todos:
+  -- ninguém no escritório deveria poder reverter isso por engano na tela.
+  source      text NOT NULL DEFAULT 'staff'
+                CHECK (source IN ('staff', 'customer_reply', 'import', 'contract', 'provider')),
+  -- Texto curto do operador. Nunca conteúdo de mensagem, nunca PII extra.
+  note        text,
+  decided_at  timestamptz NOT NULL DEFAULT now(),
+  decided_by  uuid REFERENCES "user"(id),
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  updated_at  timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT client_channel_consent_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id)
+);
+
+-- Uma decisão viva por (cliente, canal). Sem isto, dois opt-outs concorrentes
+-- criariam duas linhas e a leitura teria de escolher uma — e escolher errado
+-- significa enviar para quem pediu para não receber.
+CREATE UNIQUE INDEX IF NOT EXISTS client_channel_consent_uq
+  ON client_channel_consent (tenant_id, client_id, channel);
+
+CREATE INDEX IF NOT EXISTS client_channel_consent_denied_idx
+  ON client_channel_consent (tenant_id, channel)
+  WHERE state = 'denied';
+
+-- ── RLS: tenant E cliente ───────────────────────────────────────────────────
+--
+-- Mesmo padrão das tabelas client-scoped (0026/0027). Sem isto a tabela seria a
+-- única com `tenant_id` do schema sem política — e não falharia em teste
+-- nenhum, porque não existe guard que varra cobertura de RLS. Passaria verde,
+-- e a permissão de contato de um escritório ficaria legível por outro.
+--
+-- FORCE porque a política precisa valer inclusive para o dono da tabela: é o
+-- papel que roda migration, e é exatamente onde a armadilha da 0035/0036 mora.
+ALTER TABLE client_channel_consent ENABLE ROW LEVEL SECURITY;
+ALTER TABLE client_channel_consent FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY client_channel_consent_tenant_client_isolation ON client_channel_consent
+  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
+    )
+  );
+
+-- ── Correlação com o provider ───────────────────────────────────────────────
+--
+-- CORREÇÃO DE DEFEITO. `markSent` gravava o identificador do provider em
+-- `template`, com `COALESCE(template, provider_ref)` — ou seja, quando o
+-- template já estava preenchido (sempre, pois `scheduleAction` o grava), o id
+-- do provider era descartado em silêncio; e se estivesse nulo, o id ocuparia o
+-- lugar do nome do template e corromperia o relatório da régua.
+--
+-- Nunca deu problema porque o adapter de e-mail não devolve identificador.
+-- WhatsApp e SMS devolvem sempre, e o webhook de entrega chega trazendo APENAS
+-- esse id — sem uma coluna própria e indexada, não há como achar a ação que ele
+-- descreve, e todo status de entrega se perderia.
+ALTER TABLE dunning_event ADD COLUMN IF NOT EXISTS provider_ref text;
+
+-- O webhook chega com o id do provider e nada mais. Esta é a via de acesso.
+CREATE INDEX IF NOT EXISTS dunning_event_provider_ref_idx
+  ON dunning_event (tenant_id, provider_ref)
+  WHERE provider_ref IS NOT NULL;
+
+-- ── Estados de entrega ──────────────────────────────────────────────────────
+--
+-- `sent` significa "o provider aceitou", que é o único desfecho que o e-mail
+-- consegue afirmar. WhatsApp e SMS informam depois, por webhook, se a mensagem
+-- chegou ao aparelho (`delivered`) e — só o WhatsApp — se foi aberta (`read`).
+--
+-- São estados NOVOS, não uma renomeação: `sent` continua querendo dizer
+-- exatamente o que dizia, e nenhuma linha existente muda de valor. Colapsar
+-- "aceito pelo provider" e "chegou ao cliente" faria a tela afirmar entrega que
+-- ninguém confirmou — que é precisamente a pergunta que o escritório faz quando
+-- o cliente diz "não recebi nada".
+--
+-- Não há `read` para SMS, e não se inventa: o canal simplesmente nunca alcança
+-- esse estado. Ver a nota sobre equivalência falsa no adapter.
+ALTER TABLE dunning_event DROP CONSTRAINT IF EXISTS dunning_event_status_check;
+ALTER TABLE dunning_event ADD CONSTRAINT dunning_event_status_check
+  CHECK (status IN ('scheduled', 'sent', 'delivered', 'read', 'failed', 'canceled', 'escalated'));
+
+-- Quando o provider confirmou a entrega no aparelho. Separado de `sent_at`
+-- porque a distância entre os dois é a informação útil: aceito às 9h e entregue
+-- às 14h significa aparelho desligado, não falha.
+ALTER TABLE dunning_event ADD COLUMN IF NOT EXISTS delivered_at timestamptz;
+ALTER TABLE dunning_event ADD COLUMN IF NOT EXISTS read_at timestamptz;
+
+COMMENT ON COLUMN dunning_event.provider_ref IS
+  'Identificador da mensagem no provider. Nunca uma credencial. Via de acesso do webhook de entrega.';
+COMMENT ON TABLE client_channel_consent IS
+  'Permissão de contato por canal. Ausência de linha = indefinido; a política do tenant decide.';
+
+-- ── Idempotência com contexto ───────────────────────────────────────────────
+--
+-- A chave de `(receivable, step_key)` protege o AGENDAMENTO: o índice único de
+-- `dunning_event` já impede duas ações para a mesma etapa do mesmo recebível.
+-- O que ela não protege é o ENVIO feito pelo motor compartilhado, cuja chave
+-- carrega tenant, produto, marca, canal, evento e versão de template — porque
+-- lá o mesmo aviso pode sair legitimamente por dois canais, e um template
+-- corrigido é um envio novo.
+--
+-- Sem esta coluna, "já enviei isto?" só teria como ser respondido por
+-- aproximação, e aproximação numa régua de cobrança erra para os dois lados:
+-- cala um aviso devido, ou repete um que já saiu.
+ALTER TABLE dunning_event ADD COLUMN IF NOT EXISTS idempotency_key text;
+
+-- Único por tenant. Parcial porque as ações do caminho legado (e todas as
+-- criadas antes desta migração) não têm chave — e NULL não deve colidir com
+-- NULL.
+CREATE UNIQUE INDEX IF NOT EXISTS dunning_event_idempotency_key_uq
+  ON dunning_event (tenant_id, idempotency_key)
+  WHERE idempotency_key IS NOT NULL;
+
+COMMENT ON COLUMN dunning_event.idempotency_key IS
+  'Chave do motor compartilhado (sha256 de tenant/produto/marca/canal/evento/assunto/versão). NULL no caminho legado.';

package/src/db/migrations/0039_communication_dispatch_claim.sql

@@ -0,0 +1,193 @@
+-- 0039 — Reserva atômica de envio e trilha do motor de comunicação
+--
+-- CORREÇÃO DE DEFEITO ESTRUTURAL. A 0038 entregou a chave de idempotência
+-- (`dunning_event.idempotency_key`) e o motor a consultava assim:
+--
+--     alreadySent(key)  →  adapter.send()  →  markSent(key)
+--
+-- Três passos. Entre o primeiro e o terceiro há uma janela em que dois workers
+-- concorrentes — cron e envio manual, duas instâncias durante um redeploy, um
+-- retry sobreposto ao original — recebem os DOIS a resposta "ainda não enviei",
+-- e os dois chamam o provider. O cliente recebe a mesma cobrança duas vezes, e
+-- a coluna de idempotência registra fielmente que houve um envio.
+--
+-- O índice único da 0038 não protege isso: ele impede duas LINHAS com a mesma
+-- chave, e o envio duplo acontece antes de qualquer linha ser escrita. Um índice
+-- é uma restrição sobre o registro; o que faltava é uma restrição sobre o
+-- DIREITO DE AGIR.
+--
+-- Estas duas tabelas são isso. Nenhuma regra financeira muda; `dunning_event`
+-- continua sendo o estado da etapa da régua.
+
+-- ── Reserva de envio ────────────────────────────────────────────────────────
+--
+-- Uma linha por chave de idempotência. A linha É a reserva: quem consegue
+-- gravá-la (ou retomá-la de um titular vencido) tem o direito de chamar o
+-- provider, e mais ninguém.
+--
+-- Tabela do MOTOR, não da cobrança. Um segundo consumidor (Dental, Manga Verde)
+-- reserva aqui sem nenhuma coluna nova — `product` e `brand` já estão na chave,
+-- e é por isso que ela não mora dentro de `dunning_event`: amarrar a reserva à
+-- tabela de uma régua de honorários obrigaria o próximo produto a ter uma régua
+-- de honorários.
+CREATE TABLE IF NOT EXISTS communication_dispatch (
+  id             uuid PRIMARY KEY,
+  tenant_id      uuid NOT NULL REFERENCES tenant(id),
+  product        text NOT NULL,
+  brand          text NOT NULL,
+  channel        text NOT NULL CHECK (channel IN ('email', 'whatsapp', 'sms', 'notification')),
+  event_type     text NOT NULL,
+  -- Referência do assunto no domínio do consumidor (recebível, fatura, pedido).
+  -- Nunca PII.
+  subject_ref    text NOT NULL,
+  -- sha256 composto pelo motor a partir de tenant/produto/marca/canal/evento/
+  -- assunto/versão de template. Ver `communication/idempotency.ts`.
+  idempotency_key text NOT NULL,
+
+  --   in_flight        alguém tem a reserva AGORA e pode estar chamando o provider
+  --   sent             o provider aceitou. Terminal para esta chave.
+  --   failed_retryable falhou de um jeito que vale tentar de novo; a chave volta a ser reservável
+  --   failed_permanent falhou de um jeito que não vale; só ação humana muda isto
+  --
+  -- `sent` NÃO é "entregue": quem afirma entrega é o webhook, e o estado de
+  -- entrega mora em `communication_event`/`dunning_event`. Colapsar os dois
+  -- faria a reserva virar uma segunda fonte de verdade sobre entrega, que
+  -- divergiria da primeira no primeiro callback fora de ordem.
+  status         text NOT NULL DEFAULT 'in_flight'
+                   CHECK (status IN ('in_flight', 'sent', 'failed_retryable', 'failed_permanent')),
+
+  -- Identidade do TITULAR atual da reserva. Sem isto, um processo que ressuscita
+  -- depois do prazo vencido assentaria o desfecho por cima de quem está
+  -- enviando agora — e marcaria como enviada uma mensagem que o titular novo
+  -- ainda não mandou.
+  claim_id       uuid,
+  claimed_at     timestamptz,
+  -- Prazo. Existe porque processo morre: sem ele, um worker que cai segurando a
+  -- reserva calaria a etapa para sempre, e o silêncio de uma régua de cobrança
+  -- é indistinguível de "o cliente não devia nada".
+  claim_expires_at timestamptz,
+  -- A reserva atual foi TOMADA de um titular vencido. Significa risco real de
+  -- duplicata (o anterior pode ter enviado e morrido antes de assentar), e é o
+  -- que permite a um humano explicar "por que chegou duas vezes".
+  recovered_from_expired boolean NOT NULL DEFAULT false,
+
+  attempts       integer NOT NULL DEFAULT 0,
+  provider_ref   text,
+  -- Rótulo curto e estável para métrica. snake_case. Nunca PII, nunca segredo.
+  last_code      text,
+  last_detail    text,
+  sent_at        timestamptz,
+  settled_at     timestamptz,
+  created_at     timestamptz NOT NULL DEFAULT now(),
+  updated_at     timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT communication_dispatch_tenant_id_uq UNIQUE (tenant_id, id)
+);
+
+-- A restrição que faz a reserva existir. Sem ela, `ON CONFLICT` não tem alvo e
+-- todo `claim` viraria um INSERT novo — ou seja, todo mundo ganharia a reserva.
+CREATE UNIQUE INDEX IF NOT EXISTS communication_dispatch_key_uq
+  ON communication_dispatch (tenant_id, idempotency_key);
+
+-- Via de acesso do webhook de entrega: ele chega com o id do provider e nada mais.
+CREATE INDEX IF NOT EXISTS communication_dispatch_provider_ref_idx
+  ON communication_dispatch (tenant_id, provider_ref)
+  WHERE provider_ref IS NOT NULL;
+
+-- Reservas penduradas, para diagnóstico operacional.
+CREATE INDEX IF NOT EXISTS communication_dispatch_in_flight_idx
+  ON communication_dispatch (tenant_id, claim_expires_at)
+  WHERE status = 'in_flight';
+
+CREATE INDEX IF NOT EXISTS communication_dispatch_subject_idx
+  ON communication_dispatch (tenant_id, subject_ref, event_type);
+
+-- FORCE porque a política precisa valer inclusive para o dono da tabela — é o
+-- papel que roda migration, e é onde a armadilha da 0035/0036 morava.
+ALTER TABLE communication_dispatch ENABLE ROW LEVEL SECURITY;
+ALTER TABLE communication_dispatch FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY communication_dispatch_tenant_isolation ON communication_dispatch
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ── Trilha do motor ─────────────────────────────────────────────────────────
+--
+-- Registro estruturado do que o motor decidiu. NÃO é log: log é texto que
+-- alguém talvez leia, isto responde "por que este cliente não recebeu?" seis
+-- meses depois, com filtro por motivo.
+--
+-- Separada de `audit_log` de propósito. `audit_log` registra ATOS DE USUÁRIO —
+-- tem ator, IP, user-agent, e é lida por auditoria de acesso. A maioria dos
+-- eventos daqui não tem ator humano nenhum (cron, webhook), tem volume de outra
+-- ordem de grandeza, e é consultada por chave de idempotência e referência do
+-- provider. Misturá-las tornaria a auditoria de acesso ilegível e esta consulta
+-- lenta.
+--
+-- Também separada de `dunning_event`: lá mora o estado da ETAPA da régua, um por
+-- (recebível, passo). Aqui mora o histórico da INTENÇÃO — várias por etapa,
+-- porque uma etapa pode ter um canal recusado por consentimento, outro por
+-- telefone inválido, e um terceiro entregue.
+CREATE TABLE IF NOT EXISTS communication_event (
+  id             uuid PRIMARY KEY,
+  tenant_id      uuid NOT NULL REFERENCES tenant(id),
+  product        text NOT NULL,
+  -- NULLABLE, e a exceção é real: um callback que chega com um identificador de
+  -- provider que não corresponde a nenhuma mensagem nossa não pertence a marca
+  -- nenhuma. Forçar um valor ali inventaria uma marca — e a trilha passaria a
+  -- afirmar que o escritório X mandou algo que ele não mandou.
+  brand          text,
+  -- Vocabulário FECHADO. Um `text` livre viraria dez grafias do mesmo evento e
+  -- nenhuma métrica agregável.
+  kind           text NOT NULL CHECK (kind IN (
+                   'intent_created', 'dispatch_claimed', 'dispatch_skipped',
+                   'dispatch_sent', 'dispatch_failed', 'consent_blocked',
+                   'invalid_contact', 'callback_delivered', 'callback_read',
+                   'callback_failed', 'opt_out')),
+  channel        text CHECK (channel IS NULL OR channel IN ('email', 'whatsapp', 'sms', 'notification')),
+  event_type     text NOT NULL,
+  subject_ref    text,
+  -- Referência LÓGICA do destinatário (id do cliente). NUNCA telefone, NUNCA
+  -- e-mail: a trilha é consultada por quem opera, e uma trilha que carrega o
+  -- contato transforma toda consulta operacional numa exportação de PII.
+  recipient_ref  text,
+  idempotency_key text,
+  provider_ref   text,
+  skip_reason    text,
+  status         text,
+  code           text,
+  -- Truncado na escrita. Nunca corpo de mensagem, nunca credencial.
+  detail         text,
+  attempt        integer,
+  occurred_at    timestamptz NOT NULL DEFAULT now(),
+  created_at     timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT communication_event_tenant_id_uq UNIQUE (tenant_id, id)
+);
+
+CREATE INDEX IF NOT EXISTS communication_event_key_idx
+  ON communication_event (tenant_id, idempotency_key, occurred_at DESC)
+  WHERE idempotency_key IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS communication_event_subject_idx
+  ON communication_event (tenant_id, subject_ref, occurred_at DESC);
+
+CREATE INDEX IF NOT EXISTS communication_event_recipient_idx
+  ON communication_event (tenant_id, recipient_ref, occurred_at DESC);
+
+CREATE INDEX IF NOT EXISTS communication_event_kind_idx
+  ON communication_event (tenant_id, kind, occurred_at DESC);
+
+ALTER TABLE communication_event ENABLE ROW LEVEL SECURITY;
+ALTER TABLE communication_event FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY communication_event_tenant_isolation ON communication_event
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+COMMENT ON TABLE communication_dispatch IS
+  'Reserva atômica do direito de enviar, por chave de idempotência. A linha É a reserva.';
+COMMENT ON TABLE communication_event IS
+  'Trilha estruturada do motor de comunicação. Sem PII de contato, sem credencial, sem corpo de mensagem.';
+COMMENT ON COLUMN communication_dispatch.recovered_from_expired IS
+  'A reserva foi tomada de um titular vencido — há risco real de o anterior ter enviado antes de morrer.';