From 8f3dcaada902068e68bdd255f132a9738a9afb07 Mon Sep 17 00:00:00 2001 From: gti Date: Mon, 28 Sep 2026 15:03:22 -0300 Subject: [PATCH] =?UTF-8?q?docs:=20Miss=C3=A3o=205=20addendum=20(Z.1-Z.6)?= =?UTF-8?q?=20-=20correct=20labels,=20add=20tables,=20adopt=20VERSIONING.m?= =?UTF-8?q?d?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Z.1: KB conflict counts were reported as ROW counts (kb_knowledge rows), not DISTINCT GTIN counts - a single conflicted product with 2 competing NCM candidates produces 2 rows, doubling the apparent conflict count. Real number, measured directly in production: 262 distinct GTINs in CONFLICT (all under knowledge_key=ncm), matching the ~264 baseline closely - no real growth, just a row-vs-GTIN counting mismatch in the earlier report. Z.3: corrected the Missão 4 claim that NFCE_ITENS was the "fonte encontrada" for what PIS/COFINS was actually transmitted - that overstated certainty. Relabeled PISCOFINS_FONTE_TRANSMITIDA = NÃO_CONCLUSIVO in docs/PISCOFINS_TRANSMITTED_SOURCE_V1.md and both dossiê copies: a blank NFCE_ITENS column is equally consistent with "nothing was transmitted" and "the SGV transmitted a value in the XML but never wrote it back to that column" - we cannot tell without the actual XML. Z.4: docs/AUTOFILL_SAFE_3_CELULAS_V1.md - table of the 3 real AUTO_FILL_SAFE cells (000801/000802 CFOP, 000697 IPPT) with proposed value, field_contract rule and concrete evidence for each. Z.5: docs/NCM_27_BLOCKED_PRODUCTS_V1.md now marks the 15 test/garbage-named products as "produto de teste" in the kb.attest queue (still counted in coverage, just lower priority); the 3 legacy + 5 out-of-table NCMs are flagged for reclassification once the official NCM catalog (Fase 2 of this mission) is loaded and approved. Z.6: CLAUDE.md records independent Hub/Agent versioning (docs/VERSIONING.md) as the adopted standard going forward. No schema/migration change. No Firebird write anywhere. Co-Authored-By: Claude Sonnet 5 --- CLAUDE.md | 9 +++++++++ central/static/docs/dossie_contador.md | 13 +++++++------ docs/AUTOFILL_SAFE_3_CELULAS_V1.md | 14 ++++++++++++++ docs/NCM_27_BLOCKED_PRODUCTS_V1.md | 8 ++++++++ docs/PISCOFINS_TRANSMITTED_SOURCE_V1.md | 22 ++++++++++++++-------- docs/dossie_contador.md | 15 +++++++++------ 6 files changed, 61 insertions(+), 20 deletions(-) create mode 100644 docs/AUTOFILL_SAFE_3_CELULAS_V1.md diff --git a/CLAUDE.md b/CLAUDE.md index 1c7adda..a5e2a77 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -80,6 +80,15 @@ guarded executor (path allowlist, company-context guard, schema/type/length guar ## Production deploy rule (Hub) Normal deploy = `powershell -ExecutionPolicy Bypass -File .\scripts\deploy_hub.ps1 [-PublishAgent -Version X]` (docs/DEPLOY_HUB.md). Do not recreate ad-hoc deploy scripts (deploy115.py etc.) and do not improvise SSH/docker against 10.0.10.117. The script handles VPN/SSH retry, backup, upload, migrations, rebuild, health, release publish, download verification, and automatic rollback; the real error is in `logs/last_deploy_result.json` and the log. +## Versioning (adopted standard, see docs/VERSIONING.md) + +Hub and Agent are versioned and released independently — never assume they share a version +number, and never make the Hub's `GTI_FISCAL_VERSION` bump touch the Agent's own version files +(`agent/pyproject.toml`, the `AGENT_VERSION` defaults) or vice versa. The panel's "Atualização +disponível" already compares an Agent's reported version against the highest **PUBLISHED** +Windows `AgentRelease`, never against the Hub's version — see `docs/VERSIONING.md` for the exact +mechanism and the current (informal) compatibility matrix. + ## Permanent mission rules (fiscal completion missions, recorded 2026-09-28) - No AI/LLM/embeddings, no paid API, no scraping — every rule/decision is derived from real ERP diff --git a/central/static/docs/dossie_contador.md b/central/static/docs/dossie_contador.md index afd69d7..cd9b1a4 100644 --- a/central/static/docs/dossie_contador.md +++ b/central/static/docs/dossie_contador.md @@ -63,14 +63,15 @@ reconhece esse episódio. ICMS" no card correspondente, e mesmo assim o motor consulta o tratamento antes de propor o código (nunca aplica um padrão cegamente). -## Atualização: onde exatamente está guardado o que foi transmitido +## Atualização: o que foi realmente transmitido é NÃO_CONCLUSIVO Procuramos por XML/documento fiscal armazenado nos bancos auditados: não existe — o sistema só -guarda o caminho do arquivo no disco da loja, nunca o conteúdo. A fonte real e mais próxima do que -foi transmitido são as próprias colunas de PIS/COFINS por item de venda (código, base, alíquota, -valor) — os mesmos valores usados para montar a nota fiscal eletrônica. Isso não muda a conclusão -da pergunta (a): mesmo sendo a fonte real, essas colunas confirmam que o cadastro do produto nunca -é consultado. +guarda o caminho do arquivo no disco da loja, nunca o conteúdo. As colunas de PIS/COFINS por item +de venda são a melhor evidência disponível no banco, mas essas colunas estão em branco para quase +todos os itens, e sem o XML de verdade não sabemos se "em branco" significa que nada foi +transmitido ou que o sistema transmitiu um valor sem gravá-lo de volta no banco — as duas +explicações combinam com os mesmos dados. O que continua certo: o cadastro do produto nunca é +consultado (também em branco). ## Como usar este dossiê diff --git a/docs/AUTOFILL_SAFE_3_CELULAS_V1.md b/docs/AUTOFILL_SAFE_3_CELULAS_V1.md new file mode 100644 index 0000000..5ffea2e --- /dev/null +++ b/docs/AUTOFILL_SAFE_3_CELULAS_V1.md @@ -0,0 +1,14 @@ +# As 3 células AUTO_FILL_SAFE reais (Agent 2, pós-correção do motor) — Missão 5 / Z.4 + +Evidência: `docs/runs/GTI_dryrun_universe.ndjson.gz` (dry-run read-only, pós-fix Bloco A.1). + +| Produto | Campo | Valor atual | Valor proposto | Regra (`field_contract`) | Evidência concreta | +|---|---|---|---|---|---| +| 000801 PEIXE TILAPIA FILE S/ ESPINHAS | CFOP | (em branco) | 5102 | `DERIVED_FROM_ROLE_AND_ST_FILLING_BLANK` | `C000025.TIPO=VENDA` + documento de compra em `C000088`/estoque em `C000100` comprovam papel RESALE; sem substituição tributária (ST) declarada para este item — 5102 é o CFOP de venda de mercadoria de revenda, intra-UF, sem ST. Campo estava vazio (preenche, nunca sobrescreve). | +| 000802 PEIXE CORVINA POSTA | CFOP | (em branco) | 5102 | `DERIVED_FROM_ROLE_AND_ST_FILLING_BLANK` | Mesma evidência do item acima (RESALE + sem ST), mesmo produto-tipo (peixe fresco vendido a granel). | +| 000697 SUCO DE GRAVIOLA GTI | IPPT | T (terceiros) | P (própria produção) | `DERIVED_FROM_PRODUCT_ROLE:PROD_COZINHA=1,RECEITA_INGREDIENTES` | Evidência **direta**, não estatística: `C000025.PROD_COZINHA=1` (produto roteado para a cozinha) **e** existe uma linha em `RECEITA_INGREDIENTES` ligando este código a uma receita real — as duas evidências, juntas, não dependem do limiar de maioria de `C000032.TIPO=COMPOSICAO` (que é só para o caso mais fraco, estatístico). | + +Nenhuma das 3 depende de interpretação fiscal — são derivações determinísticas de papel do +produto (revenda/produção própria) já comprovado por dados do próprio ERP (documento de compra, +estoque, receita), não por regra fiscal inventada. Continuam sujeitas ao roteiro de acceptance com +produtos de teste antes de qualquer escrita real (`docs/CFOP_IPPT_WRITE_CAPABILITY_V1.md`). diff --git a/docs/NCM_27_BLOCKED_PRODUCTS_V1.md b/docs/NCM_27_BLOCKED_PRODUCTS_V1.md index 9e5b0bb..a6c7acf 100644 --- a/docs/NCM_27_BLOCKED_PRODUCTS_V1.md +++ b/docs/NCM_27_BLOCKED_PRODUCTS_V1.md @@ -48,6 +48,14 @@ por último): prioridade baixa: parecem lixo de cadastro de teste deste ambiente, candidatos a limpeza/ desativação em vez de correção fiscal (fora do escopo desta missão decidir isso). +**Atualização (Missão 5 / Z.5)**: os 15 produtos de nome/NCM obviamente de teste (item 8 acima + +000761/762/763) ficam marcados como **"produto de teste"** nesta fila — continuam contados na +cobertura (não são excluídos automaticamente da métrica de completude), só recebem prioridade mais +baixa de atestação real. Os 3 vencidos (`02071400`) e os 5 fora da tabela vigente +(`02071200`/`21069091`/`03061300`) serão reclassificados assim que o catálogo oficial de NCM (P1, +Fase 2 desta missão) estiver carregado e aprovado — sucessor só será aplicado se a tabela de +correlação for unívoca; sem isso, continuam bloqueando exatamente como hoje. + ## D.3 — caminho mais curto para o humano, sem GTIN Como nenhum tem GTIN, o caminho mais curto é sempre o mesmo, em ordem de esforço: diff --git a/docs/PISCOFINS_TRANSMITTED_SOURCE_V1.md b/docs/PISCOFINS_TRANSMITTED_SOURCE_V1.md index 361f806..3f66019 100644 --- a/docs/PISCOFINS_TRANSMITTED_SOURCE_V1.md +++ b/docs/PISCOFINS_TRANSMITTED_SOURCE_V1.md @@ -15,15 +15,21 @@ nos 5 bancos (GTI/Agent 2, CONSTRUCAO, MMMODAS, RINCAO, UNIAO) — mesmo schema - `DEOLHONOIMPOSTO` é a tabela oficial da Lei "De Olho no Imposto" (IBPT) — uma tabela de **referência nacional** por NCM (carga tributária aproximada nacional/importada/estadual/ municipal, para exibir no rodapé do cupom), não o PIS/COFINS realmente aplicado por item. -- **NFCE_ITENS já é a fonte real**: `CST_PIS_COFINS`, `ALIQUOTA_PIS`, `BASE_CALCULO_PIS`, - `VALOR_PIS`, `ALIQUOTA_COFINS`, `BASE_CALCULO_COFINS`, `VALOR_COFINS` são colunas simples - (não BLOB) já preenchidas pelo próprio SGV ao montar cada nota — são os mesmos valores que vão - para o XML enviado à SEFAZ. Sem o XML em si para conferência cruzada, esta é a melhor evidência - disponível do que foi realmente transmitido. +- `NFCE_ITENS` tem as colunas `CST_PIS_COFINS`, `ALIQUOTA_PIS`, `BASE_CALCULO_PIS`, `VALOR_PIS`, + `ALIQUOTA_COFINS`, `BASE_CALCULO_COFINS`, `VALOR_COFINS` — colunas simples (não BLOB), + presumivelmente preenchidas pelo SGV ao montar a nota. **Mas isso é uma suposição sobre como o + SGV funciona internamente, não uma prova**: essas colunas estão em branco para praticamente + todos os itens (exceto o episódio isolado de dezembro/2022 no Agent 2), e sem o XML de verdade + para comparar, não sabemos se a coluna em branco significa "nada foi transmitido naquele item" + ou "o SGV calculou e transmitiu um valor no XML mas nunca gravou de volta nessa coluna do + banco". As duas explicações são compatíveis com os mesmos dados. -**FONTE_ENCONTRADA**: `NFCE_ITENS` (colunas de PIS/COFINS por item), não um XML/BLOB. -Tabelas inspecionadas e descartadas: `XML_MES` (só caminho de arquivo), `CARTA_CORRECAO`, -`MDFES`/`MDFES_XML`, `DEOLHONOIMPOSTO` (referência nacional, não por item). +**PISCOFINS_FONTE_TRANSMITIDA = NÃO_CONCLUSIVO** (corrigido nesta missão — a Missão 4 chamou +`NFCE_ITENS` de "fonte encontrada", o que superestimava a certeza: é a *melhor evidência +disponível no banco*, não uma confirmação do que foi de fato transmitido). Tabelas inspecionadas +e descartadas como fonte de XML: `XML_MES` (só caminho de arquivo), `CARTA_CORRECAO`, +`MDFES`/`MDFES_XML`, `DEOLHONOIMPOSTO` (referência nacional, não por item). Ver Fase 5 (Missão 5) +para o estudo de viabilidade de ler o XML autorizado no disco via Agent, com opt-in por cliente. ## C.3 — cobertura, padrão por CRT, relação com o cadastro diff --git a/docs/dossie_contador.md b/docs/dossie_contador.md index e52c595..ef5e94e 100644 --- a/docs/dossie_contador.md +++ b/docs/dossie_contador.md @@ -71,14 +71,17 @@ dezembro/2022. confirmação do "Tratamento padrão de ICMS" no card correspondente, e mesmo assim o motor consulta o tratamento antes de propor o código (nunca aplica 102 cegamente). -## Atualização (Missão 4): onde exatamente está guardado o que foi transmitido +## Atualização (Missão 5): o que foi realmente transmitido é NÃO_CONCLUSIVO Procuramos por XML/BLOB armazenado nos 5 bancos: **não existe** — o SGV só guarda o *caminho* do -arquivo XML no disco da máquina, nunca o conteúdo. A fonte real e mais próxima do que foi -transmitido são as próprias colunas de PIS/COFINS de `NFCE_ITENS` (CST, base, alíquota, valor por -item) — os mesmos valores que o SGV usa para montar o XML. Isso não muda a conclusão da pergunta -(a): mesmo sendo a fonte real, essas colunas confirmam que o cadastro do produto nunca é -consultado. Ver `docs/PISCOFINS_TRANSMITTED_SOURCE_V1.md`. +arquivo XML no disco da máquina, nunca o conteúdo. As colunas de PIS/COFINS de `NFCE_ITENS` (CST, +base, alíquota, valor por item) são a melhor evidência disponível no banco, mas **corrigimos aqui +uma afirmação forte demais da Missão 4**: essas colunas estão em branco para quase todos os itens, +e sem o XML de verdade não sabemos se "em branco" significa "nada foi transmitido" ou "o SGV +transmitiu um valor no XML mas nunca gravou de volta no banco". As duas explicações são compatíveis +com os mesmos dados — por isso a fonte do que foi *efetivamente* transmitido continua +**NÃO_CONCLUSIVO**. O que continua de pé, com certeza: o cadastro do produto nunca é consultado +(branco também). Ver `docs/PISCOFINS_TRANSMITTED_SOURCE_V1.md`. ## Como usar este dossiê