@baruk/core 0.1.0 → 0.3.0

package/src/db/migrations/0012_vault.sql

@@ -0,0 +1,51 @@
+-- 0012 — Vault Engine: cofre de credenciais por tenant. Todo segredo (API keys,
+-- OAuth, SMTP, certificados, tokens gov/receita, billing) é armazenado
+-- CRIPTOGRAFADO (AES-256-GCM) — a coluna `ciphertext` é bytea; a chave-mestra
+-- NUNCA vive no banco, apenas no ambiente da aplicação. O papel `baruk_app` só
+-- enxerga o texto cifrado; a decifração exige a permissão `vault.credential.decrypt`
+-- na camada de aplicação. Tenant-scoped com RLS FORCE (motor agnóstico — o Core
+-- não conhece "certificado A1 contábil"; isso é apenas uma `category`).
+
+CREATE TABLE vault_credential (
+  id           uuid PRIMARY KEY,
+  tenant_id    uuid NOT NULL REFERENCES tenant(id),
+  -- Opcionalmente amarra a credencial a um cliente do escritório (ex.: certificado
+  -- digital do cliente). NULL = credencial do próprio tenant (ex.: SMTP do escritório).
+  client_id    uuid,
+  name         text NOT NULL,                 -- rótulo humano ("SMTP Resend", "Cert A1 Cliente X")
+  category     text NOT NULL DEFAULT 'generic'
+                 CHECK (category IN ('api_key','oauth','smtp','certificate','token',
+                                     'gov','billing','database','webhook','generic')),
+  provider     text,                          -- 'asaas','openai','google','resend','gov_br'…
+  -- Envelope AES-256-GCM: nonce (iv) + tag de autenticação + texto cifrado + versão
+  -- da chave-mestra (permite rotação de KEK sem re-cifrar tudo de uma vez).
+  ciphertext   bytea NOT NULL,
+  iv           bytea NOT NULL,
+  auth_tag     bytea NOT NULL,
+  key_version  int  NOT NULL DEFAULT 1,
+  metadata     jsonb NOT NULL DEFAULT '{}'::jsonb,   -- campos não sensíveis (usuário, host, escopo)
+  expires_at   timestamptz,                          -- vencimento (certificados, tokens)
+  rotated_at   timestamptz,
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  updated_at   timestamptz NOT NULL DEFAULT now(),
+  deleted_at   timestamptz,
+  created_by   uuid REFERENCES "user"(id),
+  updated_by   uuid REFERENCES "user"(id),
+  version      int NOT NULL DEFAULT 1,
+  CONSTRAINT vault_credential_tenant_id_uq UNIQUE (tenant_id, id),
+  -- Se amarrada a um cliente, garante mesmo-tenant por integridade referencial.
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id)
+);
+-- Nome único por tenant (+client) enquanto não deletada.
+CREATE UNIQUE INDEX vault_credential_name_uq
+  ON vault_credential (tenant_id, coalesce(client_id, '00000000-0000-0000-0000-000000000000'::uuid), lower(name))
+  WHERE deleted_at IS NULL;
+CREATE INDEX vault_credential_tenant_idx ON vault_credential (tenant_id, category);
+CREATE INDEX vault_credential_expiry_idx ON vault_credential (tenant_id, expires_at)
+  WHERE deleted_at IS NULL AND expires_at IS NOT NULL;
+
+ALTER TABLE vault_credential ENABLE ROW LEVEL SECURITY;
+ALTER TABLE vault_credential FORCE ROW LEVEL SECURITY;
+CREATE POLICY vault_credential_tenant_isolation ON vault_credential
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);

package/src/db/migrations/0013_crm.sql

@@ -0,0 +1,67 @@
+-- 0013 — CRM Engine: funil comercial agnóstico de segmento. Um `lead` percorre
+-- estágios (Lead → Contato → Proposta → Ganho/Perdido) e, ao ser ganho, pode ser
+-- convertido em `client` (FK composta same-tenant). `crm_activity` é a timeline
+-- imutável de histórico/tarefas/comentários. Tenant-scoped com RLS FORCE.
+-- O Core não conhece "regime tributário" — o lead é um contato comercial genérico.
+
+CREATE TABLE lead (
+  id                uuid PRIMARY KEY,
+  tenant_id         uuid NOT NULL REFERENCES tenant(id),
+  name              text NOT NULL,
+  company           text,
+  email             citext,
+  phone             text,
+  source            text,                          -- origem: 'site','indicacao','ads','inbound'…
+  stage             text NOT NULL DEFAULT 'lead'
+                      CHECK (stage IN ('lead','contact','proposal','won','lost')),
+  status            text NOT NULL DEFAULT 'open'
+                      CHECK (status IN ('open','won','lost')),
+  estimated_value   numeric(14,2),                 -- valor esperado do negócio
+  probability       int NOT NULL DEFAULT 0 CHECK (probability BETWEEN 0 AND 100),
+  owner_user_id     uuid REFERENCES "user"(id),    -- responsável comercial
+  tags              jsonb NOT NULL DEFAULT '[]'::jsonb,
+  notes             text,
+  lost_reason       text,
+  -- Ao converter (won), amarra ao cliente criado (same-tenant por integridade).
+  client_id         uuid,
+  created_by        uuid REFERENCES "user"(id),
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  updated_at        timestamptz NOT NULL DEFAULT now(),
+  deleted_at        timestamptz,
+  version           int NOT NULL DEFAULT 1,
+  CONSTRAINT lead_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id)
+);
+CREATE INDEX lead_tenant_stage_idx ON lead (tenant_id, stage, status);
+CREATE INDEX lead_tenant_owner_idx ON lead (tenant_id, owner_user_id);
+
+-- Timeline do lead: notas, ligações, e-mails, mudanças de estágio, TAREFAS (due_date).
+CREATE TABLE crm_activity (
+  id             uuid PRIMARY KEY,
+  tenant_id      uuid NOT NULL REFERENCES tenant(id),
+  lead_id        uuid NOT NULL,
+  kind           text NOT NULL DEFAULT 'note'
+                   CHECK (kind IN ('note','call','email','meeting','task','stage_change','system')),
+  body           text,
+  due_date       timestamptz,                      -- para kind='task'
+  done_at        timestamptz,
+  author_user_id uuid REFERENCES "user"(id),
+  metadata       jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at     timestamptz NOT NULL DEFAULT now(),
+  FOREIGN KEY (tenant_id, lead_id) REFERENCES lead (tenant_id, id)
+);
+CREATE INDEX crm_activity_lead_idx ON crm_activity (tenant_id, lead_id, created_at DESC);
+CREATE INDEX crm_activity_task_idx ON crm_activity (tenant_id, due_date)
+  WHERE kind = 'task' AND done_at IS NULL;
+
+ALTER TABLE lead ENABLE ROW LEVEL SECURITY;
+ALTER TABLE lead FORCE ROW LEVEL SECURITY;
+CREATE POLICY lead_tenant_isolation ON lead
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+ALTER TABLE crm_activity ENABLE ROW LEVEL SECURITY;
+ALTER TABLE crm_activity FORCE ROW LEVEL SECURITY;
+CREATE POLICY crm_activity_tenant_isolation ON crm_activity
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);

package/src/db/migrations/0014_billing.sql

@@ -0,0 +1,146 @@
+-- 0014 — Billing Engine: honorários, cobranças, assinaturas e régua de
+-- inadimplência. AGNÓSTICO de gateway: a coluna `provider` guarda apenas o
+-- identificador do adapter ('manual','asaas','stripe',…) e `external_id` o id no
+-- gateway. O Core NUNCA conhece a API de um provider específico — isso vive nos
+-- adapters (Provider Pattern). Tenant-scoped com RLS FORCE.
+
+-- ── fee_agreement (acordo de honorários) ────────────────────────────────────
+CREATE TABLE fee_agreement (
+  id             uuid PRIMARY KEY,
+  tenant_id      uuid NOT NULL REFERENCES tenant(id),
+  client_id      uuid NOT NULL,
+  description    text NOT NULL DEFAULT 'Honorários',
+  amount         numeric(14,2) NOT NULL,
+  periodicity    text NOT NULL DEFAULT 'monthly'
+                   CHECK (periodicity IN ('monthly','quarterly','yearly','one_time')),
+  due_day        int CHECK (due_day BETWEEN 1 AND 28),
+  billing_method text NOT NULL DEFAULT 'pix'
+                   CHECK (billing_method IN ('pix','boleto','card','manual')),
+  discount       numeric(14,2) NOT NULL DEFAULT 0,
+  fine_percent   numeric(6,3) NOT NULL DEFAULT 0,     -- multa por atraso (%)
+  interest_percent numeric(6,3) NOT NULL DEFAULT 0,   -- juros ao mês (%)
+  status         text NOT NULL DEFAULT 'active'
+                   CHECK (status IN ('active','suspended','canceled')),
+  starts_on      date,
+  ends_on        date,
+  metadata       jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_by     uuid REFERENCES "user"(id),
+  created_at     timestamptz NOT NULL DEFAULT now(),
+  updated_at     timestamptz NOT NULL DEFAULT now(),
+  deleted_at     timestamptz,
+  version        int NOT NULL DEFAULT 1,
+  CONSTRAINT fee_agreement_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id)
+);
+CREATE INDEX fee_agreement_client_idx ON fee_agreement (tenant_id, client_id, status);
+
+-- ── charge (cobrança individual) ────────────────────────────────────────────
+CREATE TABLE charge (
+  id                uuid PRIMARY KEY,
+  tenant_id         uuid NOT NULL REFERENCES tenant(id),
+  client_id         uuid NOT NULL,
+  fee_agreement_id  uuid,
+  provider          text NOT NULL DEFAULT 'manual',  -- adapter que emitiu ('manual','asaas',…)
+  external_id       text,                            -- id no gateway (idempotência)
+  method            text NOT NULL DEFAULT 'pix'
+                      CHECK (method IN ('pix','boleto','card','manual')),
+  amount            numeric(14,2) NOT NULL,
+  status            text NOT NULL DEFAULT 'pending'
+                      CHECK (status IN ('pending','sent','paid','overdue','canceled','refunded')),
+  description       text,
+  due_date          date,
+  paid_at           timestamptz,
+  -- Dados do gateway não sensíveis: url do boleto, payload PIX copia-e-cola, etc.
+  metadata          jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_by        uuid REFERENCES "user"(id),
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  updated_at        timestamptz NOT NULL DEFAULT now(),
+  deleted_at        timestamptz,
+  version           int NOT NULL DEFAULT 1,
+  CONSTRAINT charge_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  FOREIGN KEY (tenant_id, fee_agreement_id) REFERENCES fee_agreement (tenant_id, id)
+);
+CREATE INDEX charge_client_idx ON charge (tenant_id, client_id, status);
+CREATE INDEX charge_status_due_idx ON charge (tenant_id, status, due_date);
+-- Idempotência por gateway: um external_id não repete por provider/tenant.
+CREATE UNIQUE INDEX charge_external_uq ON charge (tenant_id, provider, external_id)
+  WHERE external_id IS NOT NULL AND deleted_at IS NULL;
+
+-- ── subscription (recorrência delegada ao gateway) ──────────────────────────
+CREATE TABLE subscription (
+  id                uuid PRIMARY KEY,
+  tenant_id         uuid NOT NULL REFERENCES tenant(id),
+  client_id         uuid NOT NULL,
+  fee_agreement_id  uuid,
+  provider          text NOT NULL DEFAULT 'manual',
+  external_id       text,
+  status            text NOT NULL DEFAULT 'active'
+                      CHECK (status IN ('active','paused','canceled')),
+  next_charge_on    date,
+  metadata          jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  updated_at        timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT subscription_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  FOREIGN KEY (tenant_id, fee_agreement_id) REFERENCES fee_agreement (tenant_id, id)
+);
+CREATE INDEX subscription_client_idx ON subscription (tenant_id, client_id, status);
+
+-- ── dunning_rule (régua de inadimplência) ───────────────────────────────────
+-- `steps` é um array de passos: [{ "offsetDays": -3, "channel": "whatsapp", "template": "lembrete" }, …]
+-- offsetDays negativo = antes do vencimento; 0 = no dia; positivo = após.
+CREATE TABLE dunning_rule (
+  id          uuid PRIMARY KEY,
+  tenant_id   uuid NOT NULL REFERENCES tenant(id),
+  name        text NOT NULL,
+  steps       jsonb NOT NULL DEFAULT '[]'::jsonb,
+  active      boolean NOT NULL DEFAULT true,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  updated_at  timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT dunning_rule_tenant_id_uq UNIQUE (tenant_id, id)
+);
+CREATE INDEX dunning_rule_tenant_idx ON dunning_rule (tenant_id, active);
+
+-- Log de passos de dunning já executados por cobrança (idempotência do disparo).
+CREATE TABLE dunning_event (
+  id          uuid PRIMARY KEY,
+  tenant_id   uuid NOT NULL REFERENCES tenant(id),
+  charge_id   uuid NOT NULL,
+  step_key    text NOT NULL,                       -- ex.: 'D-3:whatsapp'
+  channel     text NOT NULL,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  FOREIGN KEY (tenant_id, charge_id) REFERENCES charge (tenant_id, id)
+);
+CREATE UNIQUE INDEX dunning_event_uq ON dunning_event (tenant_id, charge_id, step_key);
+
+-- ── RLS FORCE em todas ──────────────────────────────────────────────────────
+ALTER TABLE fee_agreement ENABLE ROW LEVEL SECURITY;
+ALTER TABLE fee_agreement FORCE ROW LEVEL SECURITY;
+CREATE POLICY fee_agreement_tenant_isolation ON fee_agreement
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+ALTER TABLE charge ENABLE ROW LEVEL SECURITY;
+ALTER TABLE charge FORCE ROW LEVEL SECURITY;
+CREATE POLICY charge_tenant_isolation ON charge
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+ALTER TABLE subscription ENABLE ROW LEVEL SECURITY;
+ALTER TABLE subscription FORCE ROW LEVEL SECURITY;
+CREATE POLICY subscription_tenant_isolation ON subscription
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+ALTER TABLE dunning_rule ENABLE ROW LEVEL SECURITY;
+ALTER TABLE dunning_rule FORCE ROW LEVEL SECURITY;
+CREATE POLICY dunning_rule_tenant_isolation ON dunning_rule
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+ALTER TABLE dunning_event ENABLE ROW LEVEL SECURITY;
+ALTER TABLE dunning_event FORCE ROW LEVEL SECURITY;
+CREATE POLICY dunning_event_tenant_isolation ON 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);

package/src/db/migrations/0015_merchant_billing_ar.sql

@@ -0,0 +1,201 @@
+-- 0015 — Merchant Billing Core: Accounts Receivable (M0 — RFC-CAPABILITY-
+-- MERCHANT-BILLING-CORE-001 §4/§20). Migração ADITIVA sobre 0014_billing.sql —
+-- não altera fee_agreement/charge/subscription existentes. Adiciona a camada de
+-- AR que faltava: Receivable (conta a receber, NUNCA o instrumento `charge`) →
+-- Payment (dinheiro recebido) → Settlement (liquidação) → Reconciliation
+-- (conciliação). Tenant-scoped com RLS FORCE, mesmo padrão de 0014.
+--
+-- Apenas schema nesta migração (M0) — a lógica de domínio (máquina de estados,
+-- geração por competência, repositório) é M1 ("Merchant Billing Core"), fora
+-- do escopo autorizado nesta sessão.
+
+-- ── receivable (conta a receber — NUNCA o instrumento de cobrança) ──────────
+CREATE TABLE receivable (
+  id                   uuid PRIMARY KEY,
+  tenant_id            uuid NOT NULL REFERENCES tenant(id),
+  client_id            uuid NOT NULL,
+  fee_agreement_id     uuid,                          -- null = cobrança avulsa
+  competence           text CHECK (competence ~ '^\d{4}-\d{2}$'),  -- YYYY-MM
+  amount               numeric(14,2) NOT NULL,
+  status               text NOT NULL DEFAULT 'open'
+                         CHECK (status IN ('open','partially_paid','paid','overdue','canceled','renegotiated','written_off')),
+  due_date             date,
+  issued_at            timestamptz NOT NULL DEFAULT now(),
+  renegotiated_from_id uuid,                          -- aponta para a Receivable original, se houver
+  metadata             jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_by           uuid REFERENCES "user"(id),
+  created_at           timestamptz NOT NULL DEFAULT now(),
+  updated_at           timestamptz NOT NULL DEFAULT now(),
+  deleted_at           timestamptz,
+  version              int NOT NULL DEFAULT 1,
+  CONSTRAINT receivable_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  FOREIGN KEY (tenant_id, fee_agreement_id) REFERENCES fee_agreement (tenant_id, id),
+  FOREIGN KEY (tenant_id, renegotiated_from_id) REFERENCES receivable (tenant_id, id)
+);
+CREATE INDEX receivable_client_idx ON receivable (tenant_id, client_id, status);
+CREATE INDEX receivable_status_due_idx ON receivable (tenant_id, status, due_date);
+CREATE INDEX receivable_competence_idx ON receivable (tenant_id, fee_agreement_id, competence);
+-- Um FeeAgreement gera no máximo 1 Receivable por competência (invariante de
+-- idempotência da geração — a função que gera é M1, mas a garantia é do schema).
+CREATE UNIQUE INDEX receivable_fee_competence_uq ON receivable (tenant_id, fee_agreement_id, competence)
+  WHERE fee_agreement_id IS NOT NULL AND competence IS NOT NULL AND deleted_at IS NULL;
+
+-- ── receivable_item (rastreabilidade: o que compõe a Receivable) ───────────
+CREATE TABLE receivable_item (
+  id                uuid PRIMARY KEY,
+  tenant_id         uuid NOT NULL REFERENCES tenant(id),
+  receivable_id     uuid NOT NULL,
+  description       text NOT NULL,
+  amount            numeric(14,2) NOT NULL,
+  -- Ligação futura ao ServiceItem (dental/contabilidade) — não modelado neste M0
+  -- (RFC §3: preparado pelo contrato, implementado depois). Evita migração de
+  -- forma quando o ServiceItem chegar.
+  service_item_ref  text,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT receivable_item_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, receivable_id) REFERENCES receivable (tenant_id, id)
+);
+CREATE INDEX receivable_item_receivable_idx ON receivable_item (tenant_id, receivable_id);
+
+-- ── payment (dinheiro recebido — pode ser parcial) ─────────────────────────
+CREATE TABLE payment (
+  id             uuid PRIMARY KEY,
+  tenant_id      uuid NOT NULL REFERENCES tenant(id),
+  receivable_id  uuid NOT NULL,
+  charge_id      uuid,                                -- null = baixa manual sem Charge
+  amount         numeric(14,2) NOT NULL,
+  method         text NOT NULL DEFAULT 'pix'
+                   CHECK (method IN ('pix','boleto','card','manual')),
+  status         text NOT NULL DEFAULT 'detected'
+                   CHECK (status IN ('detected','confirmed','refunded')),
+  paid_at        timestamptz NOT NULL DEFAULT now(),
+  metadata       jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at     timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT payment_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, receivable_id) REFERENCES receivable (tenant_id, id),
+  FOREIGN KEY (tenant_id, charge_id) REFERENCES charge (tenant_id, id)
+);
+CREATE INDEX payment_receivable_idx ON payment (tenant_id, receivable_id, status);
+
+-- ── settlement (liquidação — o dinheiro caiu na conta do tenant) ───────────
+CREATE TABLE settlement (
+  id           uuid PRIMARY KEY,
+  tenant_id    uuid NOT NULL REFERENCES tenant(id),
+  payment_id   uuid NOT NULL,
+  provider     text NOT NULL,
+  external_id  text,
+  net_amount   numeric(14,2) NOT NULL,               -- valor líquido após taxas do provider
+  settled_at   timestamptz NOT NULL,
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT settlement_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, payment_id) REFERENCES payment (tenant_id, id)
+);
+CREATE INDEX settlement_payment_idx ON settlement (tenant_id, payment_id);
+
+-- ── reconciliation (casar provider ↔ receivable/charge) ────────────────────
+CREATE TABLE reconciliation (
+  id             uuid PRIMARY KEY,
+  tenant_id      uuid NOT NULL REFERENCES tenant(id),
+  charge_id      uuid,
+  receivable_id  uuid,
+  provider       text NOT NULL,
+  external_id    text,
+  status         text NOT NULL DEFAULT 'pending'
+                   CHECK (status IN ('matched','mismatched','pending')),
+  detail         jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at     timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT reconciliation_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, charge_id) REFERENCES charge (tenant_id, id),
+  FOREIGN KEY (tenant_id, receivable_id) REFERENCES receivable (tenant_id, id)
+);
+CREATE INDEX reconciliation_provider_idx ON reconciliation (tenant_id, provider, external_id);
+
+-- ── payment_provider_account (a conta do TENANT no provider — nunca uma chave global) ──
+-- Hoje o Asaas é uma única chave de plataforma (registry global). Esta tabela
+-- introduz o modelo por-tenant (RFC §9/§20): credencial/carteira/recebedor
+-- pertencem ao tenant. A credencial em si NUNCA vive aqui — só a referência ao
+-- Vault (`ctx.devplatform.vault`).
+CREATE TABLE payment_provider_account (
+  id                     uuid PRIMARY KEY,
+  tenant_id              uuid NOT NULL REFERENCES tenant(id),
+  provider               text NOT NULL,
+  account_reference      text,                        -- recebedor/id da conta no provider
+  environment            text NOT NULL DEFAULT 'sandbox' CHECK (environment IN ('sandbox','live')),
+  supported_capabilities jsonb NOT NULL DEFAULT '[]'::jsonb,  -- ex.: ["pix","boleto"]
+  status                 text NOT NULL DEFAULT 'pending_validation'
+                           CHECK (status IN ('active','disabled','pending_validation','revoked')),
+  credential_ref         text,                        -- referência ao Vault — NUNCA a credencial
+  config_version         int NOT NULL DEFAULT 1,
+  last_validated_at      timestamptz,
+  rotated_at             timestamptz,
+  revoked_at             timestamptz,
+  created_at             timestamptz NOT NULL DEFAULT now(),
+  updated_at             timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT payment_provider_account_tenant_id_uq UNIQUE (tenant_id, id)
+);
+-- No máximo 1 conta ativa/pendente por (tenant, provider) — revogada não conta.
+CREATE UNIQUE INDEX payment_provider_account_provider_uq ON payment_provider_account (tenant_id, provider)
+  WHERE status <> 'revoked';
+CREATE INDEX payment_provider_account_tenant_idx ON payment_provider_account (tenant_id, status);
+
+ALTER TABLE payment_provider_account ENABLE ROW LEVEL SECURITY;
+ALTER TABLE payment_provider_account FORCE ROW LEVEL SECURITY;
+CREATE POLICY payment_provider_account_tenant_isolation ON payment_provider_account
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ── webhook_event (idempotência de webhook — CROSS-TENANT, de propósito) ───
+-- Mesmo padrão do subscription-billing (dental): o webhook chega ANTES de o
+-- tenant ser resolvido (a rota é `/webhooks/:provider`, não por tenant — quem
+-- resolve o tenant é resolveContext, a partir do payload/conta). Por isso:
+-- (a) tenant_id é NULLABLE (preenchido depois de resolvido);
+-- (b) a chave de idempotência é (provider, external_event_id) SEM tenant_id —
+--     não dá para confiar em tenant no momento do dedup;
+-- (c) esta tabela NÃO tem RLS FORCE — é escrita em contexto de sistema
+--     (SystemDb), antes de `current_tenant` existir na sessão.
+CREATE TABLE 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,
+  processed_at       timestamptz,
+  created_at         timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX webhook_event_idempotency_uq ON webhook_event (provider, external_event_id);
+CREATE INDEX webhook_event_tenant_idx ON webhook_event (tenant_id) WHERE tenant_id IS NOT NULL;
+
+-- ── RLS FORCE nas tabelas tenant-scoped novas ────────────────────────────────
+ALTER TABLE receivable ENABLE ROW LEVEL SECURITY;
+ALTER TABLE receivable FORCE ROW LEVEL SECURITY;
+CREATE POLICY receivable_tenant_isolation ON receivable
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+ALTER TABLE receivable_item ENABLE ROW LEVEL SECURITY;
+ALTER TABLE receivable_item FORCE ROW LEVEL SECURITY;
+CREATE POLICY receivable_item_tenant_isolation ON receivable_item
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+ALTER TABLE payment ENABLE ROW LEVEL SECURITY;
+ALTER TABLE payment FORCE ROW LEVEL SECURITY;
+CREATE POLICY payment_tenant_isolation ON payment
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+ALTER TABLE settlement ENABLE ROW LEVEL SECURITY;
+ALTER TABLE settlement FORCE ROW LEVEL SECURITY;
+CREATE POLICY settlement_tenant_isolation ON settlement
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+ALTER TABLE reconciliation ENABLE ROW LEVEL SECURITY;
+ALTER TABLE reconciliation FORCE ROW LEVEL SECURITY;
+CREATE POLICY reconciliation_tenant_isolation ON reconciliation
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);

package/src/db/migrations/0016_office_onboarding.sql

@@ -0,0 +1,162 @@
+-- 0016 — Office onboarding persistence foundation.
+-- Processo operacional tenant-scoped; documentos são apenas referências lógicas.
+
+CREATE TABLE onboarding_instance (
+  id uuid PRIMARY KEY,
+  tenant_id uuid NOT NULL REFERENCES tenant(id),
+  client_id uuid NOT NULL,
+  status text NOT NULL DEFAULT 'draft'
+    CHECK (status IN ('draft', 'active', 'blocked', 'completed', 'cancelled')),
+  owner_id uuid REFERENCES "user"(id),
+  started_at timestamptz,
+  due_at timestamptz,
+  blocked_at timestamptz,
+  completed_at timestamptz,
+  cancelled_at timestamptz,
+  blocked_reason text,
+  cancellation_reason 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_instance_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  CHECK (due_at IS NULL OR due_at >= created_at),
+  CHECK ((status <> 'blocked') OR blocked_reason IS NOT NULL),
+  CHECK ((status <> 'cancelled') OR cancellation_reason IS NOT NULL)
+);
+CREATE INDEX onboarding_instance_tenant_status_idx
+  ON onboarding_instance (tenant_id, status, due_at);
+CREATE INDEX onboarding_instance_tenant_client_idx
+  ON onboarding_instance (tenant_id, client_id, created_at DESC);
+
+CREATE TABLE onboarding_item (
+  id uuid PRIMARY KEY,
+  tenant_id uuid NOT NULL REFERENCES tenant(id),
+  onboarding_id uuid NOT NULL,
+  client_id uuid NOT NULL,
+  title text NOT NULL,
+  description text,
+  status text NOT NULL DEFAULT 'pending'
+    CHECK (status IN ('pending', 'in_progress', 'completed', 'rejected', 'not_applicable')),
+  required boolean NOT NULL DEFAULT true,
+  assigned_to uuid REFERENCES "user"(id),
+  due_at timestamptz,
+  completed_at timestamptz,
+  rejection_reason text,
+  item_order int NOT NULL DEFAULT 0,
+  visibility text NOT NULL DEFAULT 'internal' CHECK (visibility IN ('internal', 'portal')),
+  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_item_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, onboarding_id) REFERENCES onboarding_instance (tenant_id, id)
+    ON DELETE CASCADE,
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  CHECK ((status <> 'rejected') OR rejection_reason IS NOT NULL)
+);
+CREATE INDEX onboarding_item_onboarding_idx
+  ON onboarding_item (tenant_id, onboarding_id, item_order);
+
+CREATE TABLE onboarding_task (
+  id uuid PRIMARY KEY,
+  tenant_id uuid NOT NULL REFERENCES tenant(id),
+  onboarding_id uuid NOT NULL,
+  client_id uuid NOT NULL,
+  title text NOT NULL,
+  description text,
+  status text NOT NULL DEFAULT 'pending'
+    CHECK (status IN ('pending', 'in_progress', 'completed', 'cancelled')),
+  priority text NOT NULL DEFAULT 'normal'
+    CHECK (priority IN ('low', 'normal', 'high', 'urgent')),
+  assigned_to uuid REFERENCES "user"(id),
+  due_at timestamptz,
+  completed_at timestamptz,
+  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_task_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, onboarding_id) REFERENCES onboarding_instance (tenant_id, id)
+    ON DELETE CASCADE,
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id)
+);
+CREATE INDEX onboarding_task_due_idx
+  ON onboarding_task (tenant_id, status, due_at);
+
+CREATE TABLE onboarding_document_requirement (
+  id uuid PRIMARY KEY,
+  tenant_id uuid NOT NULL REFERENCES tenant(id),
+  onboarding_id uuid NOT NULL,
+  client_id uuid NOT NULL,
+  type text NOT NULL,
+  label text NOT NULL,
+  status text NOT NULL DEFAULT 'requested'
+    CHECK (status IN ('requested', 'received', 'validated', 'rejected')),
+  requested_at timestamptz NOT NULL DEFAULT now(),
+  received_at timestamptz,
+  validated_at timestamptz,
+  rejected_at timestamptz,
+  rejection_reason text,
+  expires_at timestamptz,
+  canonical_document_id uuid,
+  CONSTRAINT onboarding_document_requirement_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, onboarding_id) REFERENCES onboarding_instance (tenant_id, id)
+    ON DELETE CASCADE,
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  CHECK ((status <> 'rejected') OR rejection_reason IS NOT NULL)
+);
+CREATE INDEX onboarding_document_requirement_status_idx
+  ON onboarding_document_requirement (tenant_id, onboarding_id, status);
+
+CREATE TABLE onboarding_event (
+  event_id uuid PRIMARY KEY,
+  tenant_id uuid NOT NULL REFERENCES tenant(id),
+  onboarding_id uuid NOT NULL,
+  client_id uuid NOT NULL,
+  actor_id uuid REFERENCES "user"(id),
+  event_type text NOT NULL,
+  event_version int NOT NULL DEFAULT 1 CHECK (event_version = 1),
+  occurred_at timestamptz NOT NULL,
+  correlation_id uuid NOT NULL,
+  causation_id uuid,
+  entity_type text NOT NULL,
+  entity_id uuid NOT NULL,
+  payload jsonb NOT NULL DEFAULT '{}'::jsonb,
+  metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+  FOREIGN KEY (tenant_id, onboarding_id) REFERENCES onboarding_instance (tenant_id, id)
+    ON DELETE CASCADE,
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id)
+);
+CREATE INDEX onboarding_event_timeline_idx
+  ON onboarding_event (tenant_id, onboarding_id, occurred_at, event_id);
+
+-- Todas as tabelas são FORCE RLS. O client scope é resolvido pelo servidor via
+-- app.current_client; sem tenant context nenhuma linha é visível/escrevível.
+DO $$
+DECLARE
+  table_name text;
+BEGIN
+  FOREACH table_name IN ARRAY ARRAY[
+    'onboarding_instance', 'onboarding_item', 'onboarding_task',
+    'onboarding_document_requirement', 'onboarding_event'
+  ] LOOP
+    EXECUTE format('ALTER TABLE %I ENABLE ROW LEVEL SECURITY', table_name);
+    EXECUTE format('ALTER TABLE %I FORCE ROW LEVEL SECURITY', table_name);
+    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$, table_name, table_name);
+  END LOOP;
+END $$;

package/src/db/migrations/0017_office_onboarding_api.sql

@@ -0,0 +1,21 @@
+-- 0017 — Idempotência das mutações da API de onboarding.
+-- Registro tenant-scoped; não substitui os mecanismos de Billing.
+
+CREATE TABLE onboarding_api_idempotency (
+  tenant_id uuid NOT NULL REFERENCES tenant(id),
+  operation text NOT NULL,
+  idempotency_key text NOT NULL,
+  request_fingerprint text NOT NULL,
+  response jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  completed_at timestamptz,
+  PRIMARY KEY (tenant_id, operation, idempotency_key)
+);
+CREATE INDEX onboarding_api_idempotency_created_idx
+  ON onboarding_api_idempotency (tenant_id, created_at);
+
+ALTER TABLE onboarding_api_idempotency ENABLE ROW LEVEL SECURITY;
+ALTER TABLE onboarding_api_idempotency FORCE ROW LEVEL SECURITY;
+CREATE POLICY onboarding_api_idempotency_tenant_isolation ON onboarding_api_idempotency
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);