@baruk/core 0.3.1 → 0.5.0

package/src/db/migrations/0057_fiscal_pending_event_inbox.sql

@@ -0,0 +1,228 @@
+-- 0057 — a caixa de entrada da ingestão fiscal, e a direção que deixa de ser adivinhada.
+--
+-- ═══ O defeito que esta migration existe para fechar ═══════════════════════
+--
+-- A 0056 modelou `fiscal_document_event` como evento DE um documento: a coluna
+-- `fiscal_document_id` é `NOT NULL` e tem chave estrangeira. Está certo — um
+-- cancelamento é, por definição, o cancelamento de uma nota.
+--
+-- O que faltava é o que fazer com o evento que chega ANTES da nota. E ele
+-- chega: o ambiente nacional ordena a distribuição por RECEPÇÃO, não por
+-- emissão, e a NT 2014.002 não promete o contrário em lugar nenhum. Um evento
+-- de NSU 100 sobre um documento que só será entregue no NSU 101 é o caso
+-- normal, não a exceção.
+--
+-- O motor tratava esse evento como "duplicado", contava o item como absorvido e
+-- **avançava o cursor**. O NSU 100 ficava commitado sem que nada de 100
+-- existisse em lugar algum — e quando o documento 101 chegasse, o cancelamento
+-- dele já teria sido perdido para sempre. Uma nota cancelada permaneceria
+-- válida no fechamento, e a única forma de descobrir seria a fiscalização.
+--
+-- ═══ A invariante, escrita de uma vez ══════════════════════════════════════
+--
+--   NENHUM NSU É COMMITADO SEM QUE A INFORMAÇÃO CORRESPONDENTE ESTEJA
+--   DURAVELMENTE PRESERVADA.
+--
+-- "Duravelmente preservada" tem quatro formas, e todas são linha de banco:
+-- documento gravado, evento aplicado, evento GUARDADO À ESPERA do alvo, ou
+-- item ilegível guardado como tal. Não encontrar o alvo não é nenhuma delas.
+--
+-- ═══ Por que uma caixa de entrada, e não `fiscal_document_event` nullable ══
+--
+-- Tornar `fiscal_document_id` nulável custaria mais do que parece:
+--
+--   · a deduplicação é `UNIQUE (tenant_id, fiscal_document_id, dedupe_key)`, e
+--     em índice único NULL não colide com NULL — o mesmo evento pendente
+--     entraria quantas vezes fosse reapresentado, que é exatamente a
+--     propriedade que a dedupe existe para dar;
+--   · a tabela não tem `client_id`, e sem ele não há como provar que o evento
+--     do Cliente A não reconcilia com o documento do Cliente B — a RLS dela é
+--     de tenant apenas, porque o documento-alvo já carregava a fronteira de
+--     cliente;
+--   · e a invariante "todo evento pertence a um documento", que hoje o banco
+--     garante, viraria disciplina de código.
+--
+-- Então a espera vive em tabela própria. Ela NÃO é um domínio paralelo: nada
+-- aqui é consultado como documento fiscal, nada aqui aparece na tela de
+-- documentos, e a vida de uma linha daqui termina virando
+-- `fiscal_document_event`. É uma caixa de entrada, e caixa de entrada é a
+-- estrutura certa para "chegou, é válido, ainda não dá para arquivar".
+--
+-- ═══ Por que o RAW mora aqui dentro, em `bytea` ════════════════════════════
+--
+-- O documento fiscal guarda o XML no `blob` (storage externo, sha256, chave
+-- particionada) e está certo: ele é grande, é permanente e tem valor
+-- probatório. A caixa de entrada é o oposto — pequena, transitória e a única
+-- coisa que separa o cursor de perder informação.
+--
+-- Se a preservação dependesse do storage, existiria uma janela real: gravar o
+-- objeto, o processo morrer, e o cursor commitar depois com base num `PUT` que
+-- não aconteceu. Guardando os bytes na MESMA transação que move o cursor, a
+-- janela não existe — ou as duas coisas acontecem, ou nenhuma. É a diferença
+-- entre uma invariante e uma intenção.
+--
+-- Quando o evento é reconciliado, o `fiscal_document_event` resultante segue o
+-- caminho normal do `blob`; a linha desta caixa mantém os bytes originais como
+-- histórico, e é isso que permite reprocessar um evento aplicado por engano sem
+-- pedir nada ao provedor de novo.
+
+-- ── 1 · A caixa de entrada ─────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS fiscal_ingestion_inbox (
+  id                 uuid PRIMARY KEY,
+  tenant_id          uuid NOT NULL REFERENCES tenant(id),
+  -- Presente e NOT NULL de propósito: é a fronteira que impede o evento de um
+  -- cliente de reconciliar com o documento de outro dentro do mesmo escritório.
+  client_id          uuid NOT NULL,
+
+  source             text NOT NULL,
+  source_environment text NOT NULL
+                       CHECK (source_environment IN ('synthetic', 'homologation', 'production')),
+  -- O NSU que entregou o item. NOT NULL aqui, ao contrário de
+  -- `fiscal_document.source_nsu`: uma linha desta tabela SÓ existe por causa de
+  -- um item de cursor, e sem o NSU não há como responder "o que havia em 100?".
+  source_nsu         text NOT NULL,
+
+  -- Os três estados, e o que cada um significa:
+  --
+  --   pending_target  evento válido cujo documento-alvo ainda não chegou.
+  --   applied         já virou `fiscal_document_event`. Fica como histórico.
+  --   invalid         o item não pôde ser interpretado. Os bytes ficam para
+  --                   recuperação manual (`consNSU`) em vez de sumirem.
+  --
+  -- Não há estado `duplicate`: item repetido não cria linha nenhuma — o índice
+  -- único abaixo o absorve, e a repetição é um DESFECHO da ingestão, não um
+  -- estado do dado. Chamar de duplicata o evento sem alvo foi o defeito
+  -- original, e o vocabulário não vai voltar a permiti-lo.
+  state              text NOT NULL DEFAULT 'pending_target'
+                       CHECK (state IN ('pending_target', 'applied', 'invalid')),
+
+  document_type      text CHECK (document_type IS NULL
+                                 OR document_type IN ('nfse', 'nfe', 'cte', 'nfce')),
+  event_type         text CHECK (event_type IS NULL
+                                 OR event_type IN ('cancellation', 'replacement', 'correction',
+                                                   'manifestation', 'other')),
+  event_code         text,
+  -- `nSeqEvento` do leiaute. Entra na ordem de aplicação quando dois eventos
+  -- do mesmo tipo caem na mesma caixa.
+  event_sequence     text,
+  occurred_at        timestamptz,
+  -- Chave do documento que este evento altera. É por ela que a reconciliação
+  -- encontra o que estava esperando.
+  target_access_key  text,
+
+  raw                bytea NOT NULL CHECK (octet_length(raw) <= 8388608),
+  raw_sha256         text NOT NULL CHECK (raw_sha256 ~ '^[a-f0-9]{64}$'),
+  normalized         jsonb NOT NULL DEFAULT '{}'::jsonb,
+
+  -- Classe do motivo, nunca a mensagem do provedor nem trecho de XML.
+  reject_reason      text,
+
+  received_at        timestamptz NOT NULL DEFAULT now(),
+  applied_at         timestamptz,
+  applied_event_id   uuid,
+
+  dedupe_key         text NOT NULL,
+
+  CONSTRAINT fiscal_ingestion_inbox_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  FOREIGN KEY (tenant_id, applied_event_id) REFERENCES fiscal_document_event (tenant_id, id),
+
+  -- Um evento sem chave-alvo não teria como ser reconciliado nunca: seria
+  -- guardado para sempre sem chance de sair. O banco recusa em vez de deixar a
+  -- caixa acumular linhas inertes.
+  CONSTRAINT fiscal_ingestion_inbox_event_is_addressable
+    CHECK (state = 'invalid' OR (target_access_key IS NOT NULL AND event_type IS NOT NULL)),
+  -- Aplicado sem o evento resultante seria uma afirmação sem lastro — a mesma
+  -- classe do `full` sem RAW da 0056.
+  CONSTRAINT fiscal_ingestion_inbox_applied_has_event
+    CHECK (state <> 'applied' OR (applied_at IS NOT NULL AND applied_event_id IS NOT NULL)),
+  -- E inválido sem motivo seria um item descartado em silêncio com aparência
+  -- de registro.
+  CONSTRAINT fiscal_ingestion_inbox_invalid_has_reason
+    CHECK (state <> 'invalid' OR reject_reason IS NOT NULL)
+);
+
+-- ═══ A deduplicação é do BANCO ═════════════════════════════════════════════
+--
+-- Por (tenant, cliente, chave de dedupe), sem NULL em coluna nenhuma do índice.
+-- É o que faz o replay do mesmo lote, o retry depois de crash e o evento
+-- reapresentado depois do documento existir convergirem para uma linha só.
+CREATE UNIQUE INDEX IF NOT EXISTS fiscal_ingestion_inbox_dedupe_uq
+  ON fiscal_ingestion_inbox (tenant_id, client_id, dedupe_key);
+
+-- A busca da reconciliação: "quem estava esperando por esta chave?". Parcial
+-- porque só o que está pendente interessa a essa pergunta.
+CREATE INDEX IF NOT EXISTS fiscal_ingestion_inbox_pending_idx
+  ON fiscal_ingestion_inbox (tenant_id, client_id, target_access_key)
+  WHERE state = 'pending_target';
+
+CREATE INDEX IF NOT EXISTS fiscal_ingestion_inbox_age_idx
+  ON fiscal_ingestion_inbox (tenant_id, state, received_at);
+
+ALTER TABLE fiscal_ingestion_inbox ENABLE ROW LEVEL SECURITY;
+ALTER TABLE fiscal_ingestion_inbox FORCE ROW LEVEL SECURITY;
+-- Duas fronteiras, como em `fiscal_document`: tenant sempre, cliente quando o
+-- portal define `app.current_client`.
+CREATE POLICY fiscal_ingestion_inbox_tenant_isolation ON fiscal_ingestion_inbox
+  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
+    )
+  );
+
+COMMENT ON TABLE fiscal_ingestion_inbox IS
+  'Itens de NSU que o modelo canônico ainda não pode representar: evento cujo documento-alvo não chegou, e item ilegível. Existe para que o cursor nunca avance sobre informação não preservada.';
+COMMENT ON COLUMN fiscal_ingestion_inbox.raw IS
+  'Bytes originais do item, na MESMA transação que move o cursor. Externalizá-los abriria a janela entre o PUT no storage e o commit do cursor.';
+COMMENT ON COLUMN fiscal_ingestion_inbox.state IS
+  'pending_target | applied | invalid. Não existe `duplicate`: item repetido não cria linha — chamar de duplicata o evento sem alvo foi o defeito que esta tabela corrige.';
+
+-- ── 2 · Direção deixa de ser adivinhada ────────────────────────────────────
+--
+-- Até aqui o parser da NFS-e devolvia `direction: 'issued'` fixo, com um
+-- comentário dizendo que a ingestão resolveria — e a ingestão não resolvia.
+-- Toda nota capturada nascia "emitida pelo cliente", inclusive as em que ele é
+-- o tomador. Num escritório contábil isso não é um rótulo errado: é a diferença
+-- entre receita e despesa.
+--
+-- A direção passa a sair do CONFRONTO entre o documento do ator consultado e os
+-- participantes declarados no leiaute (emitente, tomador, intermediário). E
+-- quando o confronto não decide, o resultado é `unknown` — explícito, visível
+-- na tela e filtrável — em vez de `issued` por omissão.
+--
+-- `unknown` não é um estado de erro: o ADN distribui ao contribuinte documentos
+-- em que ele figura em qualquer dos três papéis, mas nada impede um leiaute
+-- futuro, ou um documento parcial, de não trazer o participante que decidiria.
+-- Um rótulo honesto de "não deu para dizer" é a única resposta que não mente.
+ALTER TABLE fiscal_document DROP CONSTRAINT IF EXISTS fiscal_document_direction_check;
+ALTER TABLE fiscal_document ADD CONSTRAINT fiscal_document_direction_check
+  CHECK (direction IN ('issued', 'received', 'intermediary', 'unknown'));
+
+COMMENT ON COLUMN fiscal_document.direction IS
+  'issued | received | intermediary | unknown. Resultado do confronto entre o documento do ator consultado e os participantes do leiaute. `unknown` quando o confronto não decide — nunca `issued` por omissão.';
+
+-- ── 3 · A capacidade da nova forma ─────────────────────────────────────────
+--
+-- Chave NOVA, não `contract_version` maior: o registro é lido inteiro e versões
+-- divergentes na mesma tabela o tornam ilegível (`probePlatformCapabilities`).
+-- A regra da 0055 é que o registro só CRESCE, e compatibilidade é continência
+-- de conjunto — mudança incompatível ganha `.v2`.
+--
+-- E ela é incompatível de verdade: um worker que escrevesse pela forma nova num
+-- schema sem esta tabela veria o INSERT falhar, o item ficar não preservado e o
+-- cursor parar. Fail-closed por construção — mas o portão explícito diz o
+-- motivo antes, em vez de deixar o job parar sem explicação.
+INSERT INTO platform_capability (key, label, contract_version, declared_by_migration) VALUES
+  ('office.fiscal-ingestion.v2',
+   'Ingestão fiscal com caixa de entrada de evento pendente, reconciliação e direção classificada',
+   1, '0057')
+ON CONFLICT (key) DO NOTHING;