@baruk/core 0.5.0 → 0.6.0

package/src/db/migrations/0061_client_official_registry_provenance.sql

@@ -0,0 +1,193 @@
+-- 0061 — de onde veio cada dado cadastral, e quem mandou nele.
+--
+-- ═══ O defeito que a proveniência existe para tornar indizível ═════════════
+--
+-- Sem ela, um cadastro pré-preenchido por fonte oficial e um cadastro digitado
+-- à mão são a MESMA linha. E aí duas coisas ficam impossíveis:
+--
+--   1. atualizar sem destruir. Uma segunda consulta traria o valor oficial, e
+--      sobrescrever apagaria a correção que uma pessoa fez de propósito — o
+--      telefone que o escritório sabe estar certo, o e-mail que mudou e a
+--      Receita ainda não sabe.
+--   2. explicar. "Por que o município deste cliente é Goiânia?" tem respostas
+--      diferentes conforme alguém tenha digitado ou a Receita tenha dito, e a
+--      diferença decide quanto se confia no dado.
+--
+-- A tabela guarda o retrato OFICIAL, ao lado do cadastro — nunca por cima dele.
+-- O cadastro continua sendo o que o escritório afirma; esta linha é o que a
+-- fonte disse, quando disse, e por qual provedor.
+--
+-- ═══ Por que uma tabela, e não colunas em `client` ════════════════════════
+--
+-- Colunas `*_source` em `client` dobrariam a largura da tabela e ainda assim não
+-- guardariam o valor oficial DIVERGENTE — só a etiqueta. É justamente o valor
+-- divergente que a tela de conferência precisa mostrar lado a lado.
+
+CREATE TABLE IF NOT EXISTS client_registry_snapshot (
+  id                    uuid PRIMARY KEY,
+  tenant_id             uuid NOT NULL REFERENCES tenant(id),
+  client_id             uuid NOT NULL,
+
+  -- Quem respondeu, e se é fonte oficial. `official = false` NÃO é proibido —
+  -- é o que permite registrar um provedor de teste sem que ele se disfarce de
+  -- Receita Federal na trilha.
+  provider              text NOT NULL,
+  provider_official     boolean NOT NULL DEFAULT false,
+  fetched_at            timestamptz NOT NULL DEFAULT now(),
+
+  -- O documento consultado, em dígitos. Guardado aqui porque o `client` pode ser
+  -- corrigido depois, e o retrato tem de dizer sobre QUAL número ele fala.
+  document_digits       text NOT NULL CHECK (document_digits ~ '^[0-9]{14}$'),
+
+  -- O retrato normalizado. Todo campo é opcional: toda fonte tem lacuna, e uma
+  -- lacuna precisa ser dizível como ausência — não como string vazia.
+  legal_name            text,
+  trade_name            text,
+  registration_status   text,
+  opened_on             date,
+  legal_nature          text,
+  company_size          text,
+  primary_activity_code text,
+  primary_activity_text text,
+  secondary_activities  jsonb NOT NULL DEFAULT '[]'::jsonb,
+  street                text,
+  street_number         text,
+  complement            text,
+  district              text,
+  postal_code           text,
+  municipality          text,
+  state_uf              text,
+  phone                 text,
+  email                 text,
+  share_capital_cents   bigint,
+
+  -- ═══ O silêncio da fonte NÃO é "não" ════════════════════════════════════
+  -- `NULL` aqui significa "a fonte não informou", e é diferente de `false`.
+  -- Colapsar os dois é como um optante do Simples vira Lucro Presumido por
+  -- omissão — e o regime decide quais obrigações o motor aplica.
+  simples_optant        boolean,
+  mei_optant            boolean,
+
+  created_at            timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT client_registry_snapshot_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id)
+);
+
+COMMENT ON COLUMN client_registry_snapshot.simples_optant IS
+  'NULL = a fonte não informou. NÃO é false. O regime tributário depende disso, e silêncio não é negativa.';
+
+-- Um retrato por (cliente, provedor, momento). O índice serve à pergunta real:
+-- "qual foi o último retrato deste cliente?".
+CREATE INDEX IF NOT EXISTS client_registry_snapshot_latest_idx
+  ON client_registry_snapshot (tenant_id, client_id, fetched_at DESC);
+
+ALTER TABLE client_registry_snapshot ENABLE ROW LEVEL SECURITY;
+ALTER TABLE client_registry_snapshot FORCE ROW LEVEL SECURITY;
+CREATE POLICY client_registry_snapshot_tenant_isolation ON client_registry_snapshot
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ═══ A etiqueta por ATRIBUTO ══════════════════════════════════════════════
+--
+-- O retrato acima diz o que a fonte falou. Esta tabela diz o que aconteceu com
+-- cada campo DO CADASTRO: veio da fonte, ou uma pessoa o escreveu?
+--
+-- É ela que faz `HUMAN_OVERRIDE_PRESERVED` ser verificável: um campo marcado
+-- `human` nunca é sobrescrito por atualização automática, e isso é uma consulta
+-- — não uma convenção que alguém precisa lembrar.
+CREATE TABLE IF NOT EXISTS client_field_provenance (
+  id           uuid PRIMARY KEY,
+  tenant_id    uuid NOT NULL REFERENCES tenant(id),
+  client_id    uuid NOT NULL,
+  field        text NOT NULL,
+  origin       text NOT NULL CHECK (origin IN ('official_lookup', 'human', 'import')),
+  provider     text,
+  verified_at  timestamptz,
+  updated_at   timestamptz NOT NULL DEFAULT now(),
+  updated_by   uuid REFERENCES "user"(id),
+
+  CONSTRAINT client_field_provenance_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  -- Origem oficial sem provedor é afirmação sem autor.
+  CONSTRAINT client_field_provenance_official_needs_provider
+    CHECK (origin <> 'official_lookup' OR (provider IS NOT NULL AND verified_at IS NOT NULL))
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS client_field_provenance_uq
+  ON client_field_provenance (tenant_id, client_id, field);
+
+ALTER TABLE client_field_provenance ENABLE ROW LEVEL SECURITY;
+ALTER TABLE client_field_provenance FORCE ROW LEVEL SECURITY;
+CREATE POLICY client_field_provenance_tenant_isolation ON client_field_provenance
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ═══ O nome fantasia ══════════════════════════════════════════════════════
+--
+-- `client` guarda `display_name` e `legal_name`, e não tinha onde pôr o nome
+-- fantasia — que é o que a fonte oficial devolve e o que a equipe usa para
+-- falar do cliente ("HIPER FESTA", não "OLIVEIRA PRODUTOS PARA FESTAS LTDA").
+ALTER TABLE client ADD COLUMN IF NOT EXISTS trade_name text;
+
+COMMENT ON COLUMN client.trade_name IS
+  'Nome fantasia. Distinto de display_name (como o escritório chama) e de legal_name (razão social).';
+
+INSERT INTO platform_capability (key, label, contract_version, declared_by_migration) VALUES
+  ('office.client-registry-provenance.v1',
+   'Retrato de fonte oficial e proveniência por atributo do cadastro do cliente',
+   1, '0061')
+ON CONFLICT (key) DO NOTHING;
+
+-- ═══ A consulta em si — cota, cache e trilha na MESMA linha ═══════════════
+--
+-- Esta tabela existe por três perguntas que não têm outra fonte:
+--
+--   1. **quantas consultas este escritório já fez na janela?** Sem contagem
+--      persistente, um contador em memória zera a cada redeploy e some quando
+--      há duas instâncias — que é exatamente quando o limite importa.
+--   2. **já perguntamos este CNPJ há pouco?** Uma segunda consulta idêntica em
+--      cinco minutos gasta cota de um contrato pago para reobter o que já se
+--      sabe. O `payload` é o cache; o TTL vive no código.
+--   3. **quem perguntou por qual empresa?** Consulta de CNPJ é rastreável por
+--      dever próprio: é a pergunta "esse escritório andou varrendo documentos?".
+--
+-- **Sem FK para `client`, e é de propósito.** A consulta acontece ANTES de o
+-- cliente existir — o operador digita o CNPJ numa tela de cadastro vazia. Uma FK
+-- aqui tornaria impossível registrar justamente a consulta mais comum.
+CREATE TABLE IF NOT EXISTS client_registry_lookup (
+  id              uuid PRIMARY KEY,
+  tenant_id       uuid NOT NULL REFERENCES tenant(id),
+  document_digits text NOT NULL CHECK (document_digits ~ '^[0-9]{14}$'),
+  provider        text NOT NULL,
+  outcome         text NOT NULL CHECK (outcome IN ('ok', 'failed')),
+  -- O motivo da recusa, quando houve. Vocabulário fechado no código
+  -- (`CompanyLookupFailure`); aqui fica aberto para não travar a migration num
+  -- vocabulário que ainda vai crescer com o primeiro provedor real.
+  failure_reason  text,
+  -- O retrato devolvido, quando houve. É o cache: uma repetição dentro do TTL
+  -- é respondida daqui sem tocar a rede. NULL em toda linha `failed` — falha
+  -- não se cacheia, senão uma indisponibilidade de um minuto ficaria colada
+  -- no CNPJ pelo resto do TTL.
+  payload         jsonb,
+  requested_by    uuid REFERENCES "user"(id),
+  created_at      timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT client_registry_lookup_tenant_id_uq UNIQUE (tenant_id, id),
+  CONSTRAINT client_registry_lookup_failure_has_no_payload
+    CHECK (outcome = 'ok' OR payload IS NULL)
+);
+
+-- A cota pergunta "quantas linhas deste tenant desde X"; o cache pergunta
+-- "qual a última linha `ok` deste documento". Um índice serve às duas.
+CREATE INDEX IF NOT EXISTS client_registry_lookup_quota_idx
+  ON client_registry_lookup (tenant_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS client_registry_lookup_cache_idx
+  ON client_registry_lookup (tenant_id, document_digits, created_at DESC)
+  WHERE outcome = 'ok';
+
+ALTER TABLE client_registry_lookup ENABLE ROW LEVEL SECURITY;
+ALTER TABLE client_registry_lookup FORCE ROW LEVEL SECURITY;
+CREATE POLICY client_registry_lookup_tenant_isolation ON client_registry_lookup
+  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/0062_first_contact_and_capability_truth.sql

@@ -0,0 +1,119 @@
+-- 0062 — o primeiro contato, e a diferença entre "existe" e "nós fizemos".
+--
+-- ═══ Dois defeitos, e por que eles são o mesmo defeito ════════════════════
+--
+-- **1. O impasse.** A execução exigia `verified_at`; `verified_at` significa "o
+-- ambiente oficial já aceitou"; e só uma execução produz esse aceite. A primeira
+-- consulta real era inalcançável por construção — não por configuração, não por
+-- falta de certificado. A auditoria da C2 encontrou o ciclo fechado.
+--
+-- **2. A cobertura mentindo por omissão.** `coverage_status = 'SUPPORTED_OFFICIAL'`
+-- responde "a norma oferece um caminho oficial?". A tela mostrava isso ao lado do
+-- botão de autorizar, e o operador lia "o Baruk já fala com esse serviço". Para
+-- `sefaz_dfe` isso era falso: não existe adaptador, só a string do conector.
+--
+-- Os dois são a mesma confusão — **tratar o que o mundo oferece como o que este
+-- produto construiu**. A correção é a mesma nos dois: separar os fatos em
+-- colunas próprias e obrigar cada portão a citar a sua.
+
+-- ═══ 1 · A verdade da capacidade, por camada ══════════════════════════════
+--
+-- `official_api_available` já respondia "existe API oficial?". Faltavam as duas
+-- perguntas seguintes, e é a ausência delas que produzia a leitura errada.
+ALTER TABLE fiscal_coverage
+  ADD COLUMN IF NOT EXISTS connector_implemented boolean NOT NULL DEFAULT false;
+ALTER TABLE fiscal_coverage
+  ADD COLUMN IF NOT EXISTS protocol_verified boolean NOT NULL DEFAULT false;
+
+COMMENT ON COLUMN fiscal_coverage.official_api_available IS
+  'A NORMA oferece um caminho oficial? Fato do mundo, independente deste produto.';
+COMMENT ON COLUMN fiscal_coverage.connector_implemented IS
+  'ESTE produto tem adaptador para o caminho? Fato do repositório. `sefaz_dfe` era SUPPORTED_OFFICIAL sem uma linha de adaptador — foi o que esta coluna passou a tornar dizível.';
+COMMENT ON COLUMN fiscal_coverage.protocol_verified IS
+  'O envelope/contrato do serviço foi conferido contra o serviço REAL? Ler documentação não conta; para o ADN, os nomes dos campos do envelope não estão publicados em lugar acessível.';
+
+-- Backfill explícito, e não default silencioso.
+--
+-- `DEFAULT false` deixaria toda linha existente afirmando "não implementado", o
+-- que por acaso está certo para `sefaz_dfe` e errado para `nfse_adn`. Um acerto
+-- por acaso é o que some no primeiro conector novo.
+UPDATE fiscal_coverage SET connector_implemented = true
+ WHERE provider = 'nfse_adn';
+UPDATE fiscal_coverage SET connector_implemented = false
+ WHERE provider = 'sefaz_dfe';
+-- Nenhum conector tem o protocolo conferido contra o serviço real hoje. O do
+-- ADN depende de um Swagger servido pelo próprio host que exige mTLS.
+UPDATE fiscal_coverage SET protocol_verified = false;
+
+-- ═══ 2 · A autorização passa a apontar para UM certificado ════════════════
+--
+-- Sem isto, trocar o certificado depois de autorizar mantinha a autorização de
+-- pé — e a execução aconteceria com material que ninguém aprovou. O caso não é
+-- teórico: substituir certificado é a operação normal quando um vence.
+ALTER TABLE fiscal_run_authorization
+  ADD COLUMN IF NOT EXISTS credential_fingerprint text;
+
+COMMENT ON COLUMN fiscal_run_authorization.credential_fingerprint IS
+  'sha256 do DER do certificado vigente quando a autorização foi emitida. O executor recusa quando o certificado atual difere: autorizar é aprovar UM material, não uma intenção.';
+
+-- ═══ 3 · O primeiro contato é um ATO, e ele tem registro próprio ══════════
+--
+-- Por que uma coluna e não um tipo de autorização separado: a autorização já é
+-- one-shot, read-only, escopada e expirável. O primeiro contato não precisa de
+-- outra tabela — precisa de uma DECLARAÇÃO de que quem autorizou sabia que a
+-- credencial ainda não fora aceita por ninguém.
+--
+-- `false` como padrão importa: uma autorização comum continua exigindo
+-- credencial verificada. Só quem marca este campo aceita o risco do bootstrap.
+ALTER TABLE fiscal_run_authorization
+  ADD COLUMN IF NOT EXISTS first_contact boolean NOT NULL DEFAULT false;
+
+COMMENT ON COLUMN fiscal_run_authorization.first_contact IS
+  'Autorização de PRIMEIRO CONTATO: aceita credencial válida localmente e ainda não aceita por nenhum ambiente oficial. É o único caminho que resolve o impasse do verified_at, e nenhum agendador pode emiti-la.';
+
+-- Quem executou, e por qual porta.
+--
+-- `manual` é o único valor que o primeiro contato admite, e o CHECK abaixo é
+-- quem garante isso — não um `if` em TypeScript que alguém remove.
+ALTER TABLE fiscal_run_authorization
+  ADD COLUMN IF NOT EXISTS trigger_kind text NOT NULL DEFAULT 'manual';
+
+ALTER TABLE fiscal_run_authorization
+  DROP CONSTRAINT IF EXISTS fiscal_run_authorization_trigger_kind_check;
+ALTER TABLE fiscal_run_authorization
+  ADD CONSTRAINT fiscal_run_authorization_trigger_kind_check
+  CHECK (trigger_kind IN ('manual', 'scheduled'));
+
+-- ═══ O CHECK que impede o agendador de fazer o bootstrap ══════════════════
+--
+-- Está no banco, e não no orquestrador, porque a regra tem de sobreviver a um
+-- refactor do orquestrador. Um cron que tentasse emitir autorização de primeiro
+-- contato viola a linha abaixo e a transação morre.
+ALTER TABLE fiscal_run_authorization
+  DROP CONSTRAINT IF EXISTS fiscal_run_authorization_first_contact_is_manual;
+ALTER TABLE fiscal_run_authorization
+  ADD CONSTRAINT fiscal_run_authorization_first_contact_is_manual
+  CHECK (first_contact = false OR trigger_kind = 'manual');
+
+COMMENT ON CONSTRAINT fiscal_run_authorization_first_contact_is_manual ON fiscal_run_authorization IS
+  'Primeiro contato é ato de gente. Um agendador que o tentasse estaria decidindo, sozinho, gastar o certificado de um terceiro contra a Receita pela primeira vez.';
+
+-- ═══ 4 · A habilitação fiscal do tenant, com granularidade ════════════════
+--
+-- `tenant_fiscal_automation` já existe (0058) e responde por MODO — qual
+-- ambiente o escritório declarou operar. Ela continua sendo a chave-geral.
+--
+-- O que faltava era o outro lado do par: a matrícula POR CLIENTE já existia em
+-- `client_fiscal_enrollment` (0058), também por `document_type`. Nada disso
+-- precisa de tabela nova — precisa de superfície e de auditoria, que vêm no
+-- código desta mesma frente.
+--
+-- Registrado aqui para quem ler a migration procurando as tabelas e não as
+-- encontrar: elas existem desde a 0058, e esta frente as LIGA, não as cria.
+
+-- ═══ 5 · A capacidade ═════════════════════════════════════════════════════
+INSERT INTO platform_capability (key, label, contract_version, declared_by_migration) VALUES
+  ('office.fiscal-first-contact.v1',
+   'Primeiro contato fiscal: autorização one-shot que aceita credencial válida só localmente',
+   1, '0062')
+ON CONFLICT (key) DO NOTHING;