gtiandClaude Sonnet 5
21e8282224
Missão 5: Fase 1 (Reference Data Registry): migration 0034 adds licence_terms, valid_from/ valid_to, file_size_bytes, raw_file_path, parse_errors, submitted_by/approved_by/ approved_at to the existing `datasets` table (additive only - the 9 pre-existing dataset kinds keep their current auto-activate behavior in central/app/datasets/service.py, completely untouched, so this changes nothing about the currently-running engine). New central/app/reference_registry.py is a separate, NEW ingestion workflow: register_draft() always lands as DRAFT (never auto-activates), diff_against_vigente() summarizes a draft against the current VIGENTE of the same kind for admin review, approve_draft()/reject_draft() are the only way to promote a DRAFT (refuses non-DRAFT rows and refuses a draft with recorded parse_errors). New admin screen "Tabelas oficiais" (/admin/reference-datasets, ADMIN only, CSRF, every decision audited as REFERENCE_DATASET_APPROVE/REJECT) lists the registry with a diff view and approve/reject buttons. New CLI (scripts/ingest_reference_dataset.py) downloads an official source (currently: NCM/Siscomex, no login/captcha), validates (minimum row count, a known-sample spot check), and registers a DRAFT - --dry-run never writes anything. P1 (NCM) validated for real: downloaded the live official Siscomex NCM JSON (2026-09-28, sha256 8a3bf89a..., 15,156 entries) with an identifiable User-Agent, one request. Its hash is IDENTICAL to the NCM dataset already ACTIVE in the Hub - confirms the currently loaded table is already current against the official source today. Raw file kept out of git (.gitignore: sources/raw/reference_registry/); manifest (URL, date, hash, size) recorded in docs/REFERENCE_DATASET_MANIFEST_V1.md, including P2-P6 sources still pending URL confirmation. Fase 5 (feasibility studies, no code): docs/VIABILIDADE_CCG_DFE_V1.md - CCG/SEFAZ GTIN lookup and Distribuição DF-e both require the client's own ICP-Brasil certificate; recommendation is NOT to implement now (would require either the Hub holding a client certificate - breaks the project's core security model - or the Agent making new outbound internet calls, against this mission's fixed rules). Reading the already-authorized purchase-NFe XML from disk via the Agent (path already stored in XML_MES) is recommended as the next concrete step instead: no certificate, no new internet call, opt-in per installation, result always tagged DECLARADO (never auto-promoted - consensus across purchase invoices is not fiscal truth). Open Food Facts stays identity-only, unchanged. 21 new tests, all passing. Full suite: 1147 passed, 1 skipped. No write to any Firebird database anywhere. No Agent code touched. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
5.4 KiB
Estudos de viabilidade (Missão 5, Fase 5) — decisão recomendada, sem código
5.1 — CCG/SEFAZ (consulta de GTIN com certificado) e Distribuição DF-e (XML de compras)
O que cada serviço exige
- CCG (Consulta Cadastro de Contribuintes)/consulta de GTIN via SEFAZ: exige certificado digital ICP-Brasil do cliente (e-CNPJ ou e-CPF do contador/contribuinte) para autenticar a chamada ao webservice estadual/nacional. Não existe uma chave "genérica" do GTI para isso — cada cliente autenticaria com o certificado dele.
- Distribuição DF-e (
NFeDistribuicaoDFe): mesmo requisito de certificado ICP-Brasil do destinatário (o CNPJ que recebeu a nota), usado para baixar XMLs de compra que o Fisco já sabe que aquele CNPJ recebeu — não depende do fornecedor ter enviado nada manualmente.
Risco de segurança da chave privada
O desenho atual do projeto é deliberado e documentado (docs/rtc_auto_apply.md): o Hub nunca
tem acesso a nada local do cliente (sem chave, sem certificado, sem execução remota). Um
certificado ICP-Brasil é, na prática, mais sensível que uma senha — normalmente um arquivo .pfx
protegido por senha, ou um token/smartcard físico. Usar isso a partir do Hub (nuvem, fora do
controle do cliente) exigiria:
- Ou o cliente enviar o certificado para o Hub (nunca deveria acontecer — quebra o modelo de confiança do projeto inteiro, e um vazamento do Hub comprometeria a identidade fiscal de todos os clientes que fizeram isso);
- Ou o Agent local (que já roda na máquina do cliente) fazer a consulta usando o certificado já instalado ali, e devolver ao Hub só o resultado relevante (NCM/GTIN do fornecedor, nunca o XML completo nem o certificado). Isso é tecnicamente viável e é o único desenho que não quebra "o Hub nunca acessa nada local do cliente" — mas ainda é uma consulta à internet feita pelo Agent, o que hoje é proibido por regra fixa desta missão ("Só o Hub acessa a internet externa. O Agent não recebe nenhuma chamada externa nova"). Ou seja: incompatível com o desenho atual sem uma decisão explícita de abrir uma exceção para o Agent.
Opt-in por cliente
Mesmo que se decida abrir essa exceção no futuro, o consentimento tem que ser por instalação, nunca automático — cada cliente tem que decidir explicitamente confiar sua chave/certificado a essa finalidade, com escopo claro (o que é consultado, quando, o que é armazenado).
Esforço estimado (ordem de grandeza, não um cronograma)
- Alto: implica mexer no modelo de segurança do Agent (hoje só lê Firebird local e fala com o Hub), criar um fluxo de configuração de certificado por cliente, tratar renovação/expiração de certificado, e novo tipo de erro/retentativa (SEFAZ indisponível, certificado vencido, etc.). Não é um parser a mais — é uma superfície de segurança nova.
Decisão recomendada
Não implementar agora. O ganho (GTIN/NCM do fornecedor mais confiável) não justifica o aumento de superfície de risco e a mudança de desenho ("só o Hub acessa a internet") sem uma necessidade concreta e urgente de algum cliente. Reavaliar se/quando um cliente pedir explicitamente e aceitar o modelo "o Agent consulta, o Hub nunca vê o certificado".
5.2 — XML de NF-e de compra já armazenado nos bancos (evidência declarada)
Como já mapeado (docs/PISCOFINS_TRANSMITTED_SOURCE_V1.md), o SGV não guarda o XML em si no
Firebird — só o caminho do arquivo no disco local (XML_MES.CAMINHO_XML). Isso muda o desenho
possível:
- Viável, com opt-in por cliente: o Agent (que já roda na máquina, já lê Firebird local) pode ler o arquivo XML autorizado do disco (caminho já registrado no banco) — isso não é uma chamada à internet, é leitura de arquivo local, compatível com "o Agent não recebe chamada externa nova" desde que o Hub não peça isso via internet, só o Agent decida ler o que já está no disco dele mesmo.
- O Agent extrairia apenas NCM/CEST/EAN do fornecedor (campos declarados na nota de compra, identificados como DECLARADO — nunca VERIFICADO), agregados, sem dado pessoal (nunca nome do fornecedor, CNPJ, endereço, valores) — um novo "tier" de evidência na KB, mais forte que uma simples observação de cadastro, mas ainda não uma fonte oficial de classificação fiscal: consenso entre notas de compra não é verdade fiscal (o fornecedor pode errar o NCM tanto quanto o cliente).
- Esforço: médio — parser de XML de NF-e (schema já público/estável), sem certificado nem internet nova; o risco real é performance (muitos arquivos por cliente) e tratamento de arquivo ausente/corrompido (comum em bases antigas).
Decisão recomendada
Viável como próxima etapa concreta, com opt-in explícito por instalação (o Agent só lê os XMLs se o cliente autorizar), e resultado tratado sempre como evidência DECLARADA (nunca promovida automaticamente a VERIFIED_KB). Recomendo priorizar isso sobre CCG/Distribuição DF-e — mesmo ganho de evidência, risco de segurança muito menor (sem certificado, sem chamada externa nova).
5.3 — Open Food Facts
Confirmado: continua útil só como identidade de produto (nome/marca/unidade a partir do GTIN), nunca como fonte de classificação fiscal (NCM/CEST/CST) — a base não tem esse dado e não deveria ser tratada como se tivesse. Nenhuma mudança de uso recomendada.