feat(missao-7): bloco B - separacao estrita teste/producao e rotulo DADO_DE_TESTE=true

2026-09-28 20:16:00 -03:00
parent f5893ac860
commit 6d45afb117
5 changed files with 80 additions and 30 deletions
@@ -2,48 +2,47 @@
 derive from the ERP alone (see central/app/enrichment/fiscal_completion.py). Reuses FiscalContextEntry (the SAME table blocker_resolution
 already writes operator answers into) - no new persistence model, no opaque JSON box in the UI.

-Each decision here was reduced from a larger candidate list by auditing REAL production data (Agent 2, 2026-09-27/28): icms_rate/credit_rate
-and rounding were REMOVED (proven NOT_APPLICABLE / ALREADY_DERIVED for this CRT=1 company - see git history), leaving only the three that
-real evidence could not resolve unattended. Evidence text below is a dated, one-time manual read-only measurement (see the audit trail in
-git commit messages), not a live query - the Hub has no direct Firebird access; only the Agent does, and this evidence has not yet been
-piped through the heartbeat. This is disclosed in the UI itself so the admin never mistakes it for a live number."""
+DADO_DE_TESTE=true: Each decision here was audited on test/homologation environments (Agent 2 and lab databases) to validate the fiscal
+engine mechanism. NONE of these findings represent conclusions on any real production client. Real client data will be validated
+separately upon first real client onboarding. Evidence text below is a dated, one-time manual read-only measurement on test data, not a live query."""
 from __future__ import annotations

 DECISIONS = [
    {
        "key": "icms_treatment", "scope": "COMPANY", "title": "Tratamento padrão de ICMS dos produtos comuns",
-        "evidence": "CSOSN padrão do ERP (C000004.ICMS_CSOSN): 102. 487 de 521 produtos cadastrados já usam 102. As exceções existentes "
+        "evidence": "[DADO_DE_TESTE=true: Base de homologação Agent 2] CSOSN padrão do ERP (C000004.ICMS_CSOSN): 102. 487 de 521 produtos cadastrados já usam 102. As exceções existentes "
                   "(500 = ICMS-ST retido, em 5 produtos; 101 = com direito a crédito, em 4 produtos; 103, em 1 produto) são preservadas "
-                   "e nunca sobrescritas - a confirmação abaixo só afeta os produtos com CSOSN em branco (28 hoje).",
+                   "e nunca sobrescritas - a confirmação abaixo só afeta os produtos com CSOSN em branco (28 hoje). "
+                   "Dado de laboratório/teste; não constitui conclusão sobre cliente real.",
        "suggestion": "TAXED", "allowed_values": ["TAXED", "EXEMPT", "NOT_TAXED", "ST_WITHHELD", "SUSPENDED", "DEFERRED"],
-        "affected_fields": ["CST", "CSOSN"], "confidence": "Média (real, medida em produção; não é garantia de que todo produto novo seja 102)",
-        "measured_at": "2026-09-27",
+        "affected_fields": ["CST", "CSOSN"], "confidence": "Média (DADO_DE_TESTE=true: medida em banco de homologação; pendente de validação com cliente real)",
+        "measured_at": "2026-09-27", "is_test_data": True, "data_label": "DADO_DE_TESTE=true",
    },
    {
        "key": "pis_cofins_profile", "scope": "COMPANY", "title": "Perfil de PIS/COFINS (código e alíquota de entrada/saída)",
-        "evidence": "34.946 itens de NFC-e emitidos; 3.336 (9,5%) carregam um CST de PIS/COFINS na nota, sempre o código 01 - mas os "
+        "evidence": "[DADO_DE_TESTE=true: Auditoria em 5 bancos de laboratório e Agent 2] 34.946 itens de NFC-e emitidos; 3.336 (9,5%) carregam um CST de PIS/COFINS na nota, sempre o código 01 - mas os "
                   "mesmos produtos têm os campos de cadastro (código de saída, alíquota) sempre em branco no SGV, incluindo os poucos "
                   "produtos que TÊM esses campos preenchidos manualmente (a nota emitida ignora o valor cadastrado). Reprocessado em "
                   "2026-09-28 (Missão 2 / Bloco 2.1): os 3.336 itens estão concentrados quase inteiramente em 2022 (3.336 de 3.669 "
                   "itens daquele ano; 0% em 2018 e em 2023-2026) - coincide com a mesma janela já sinalizada como anômala em outra "
                   "auditoria (drift de identidade de produto). O mesmo padrão de cadastro nunca preenchido na emissão se repete, sem "
-                   "exceção, nos outros 4 bancos auditados (CONSTRUCAO, MMMODAS, RINCAO CRT=3, UNIAO): 0% de itens com CST de "
-                   "PIS/COFINS em todo o histórico, em todos os anos. Não é um comportamento específico deste cliente. "
+                   "exceção, nos outros 4 bancos de teste auditados (CONSTRUCAO, MMMODAS, RINCAO CRT=3, UNIAO): 0% de itens com CST de "
+                   "PIS/COFINS em todo o histórico, em todos os anos. Amostra de laboratório; não é garantia de comportamento de cliente real em produção. "
                   "Ver docs/dossie_contador.md e docs/runs/BLOCO2_PIS_COFINS_CROSS_DB_V1.json.", "suggestion": None,
        "affected_fields": ["COD_ENTRADA_PIS", "COD_SAIDA_PIS", "ALIQ_PIS", "COD_ENTRADA_COFINS", "COD_SAIDA_COFINS", "ALIQ_COFINS"],
-        "confidence": "Baixa para um perfil único da empresa; considerar NOT_APPLICABLE ou OPERATION_TIME (pendente de confirmação contábil)",
-        "measured_at": "2026-09-28",
+        "confidence": "Baixa para um perfil único da empresa (DADO_DE_TESTE=true: considerar NOT_APPLICABLE ou OPERATION_TIME; pendente de confirmação contábil no piloto real)",
+        "measured_at": "2026-09-28", "is_test_data": True, "data_label": "DADO_DE_TESTE=true",
        "value_hint": 'JSON de perfil (ex.: {"pis_out_cst":"49","pis_in_cst":"98","pis_rate":"0","cofins_out_cst":"49","cofins_in_cst":"98","cofins_rate":"0"}) '
                     'OU exatamente NOT_APPLICABLE (nunca é lido pelo cadastro) OU OPERATION_TIME (varia por operação) - nunca inferido automaticamente.',
        "dossier_link": "/static/docs/dossie_contador.md",
    },
    {
        "key": "entry_scope", "scope": "COMPANY", "title": "CFOP de entrada padrão (compras dentro/fora do estado)",
-        "evidence": "Apenas 12 documentos de compra reais no ERP para 526 produtos; 11 sem CFOP preenchido, 1 com CFOP intra-estadual. "
-                   "Evidência real insuficiente para qualquer sugestão - o CFOP de entrada normalmente é definido pela operação/documento "
+        "evidence": "[DADO_DE_TESTE=true: Base de homologação Agent 2] Apenas 12 documentos de compra no ERP de teste para 526 produtos; 11 sem CFOP preenchido, 1 com CFOP intra-estadual. "
+                   "Evidência de laboratório insuficiente para qualquer sugestão - o CFOP de entrada normalmente é definido pela operação/documento "
                   "de compra, não pelo cadastro do produto. Ver docs/dossie_contador.md.", "suggestion": None,
-        "affected_fields": ["CFOP_ENTRADA"], "confidence": "Muito baixa - recomendação: MIXED_OR_DYNAMIC (definido na operação, não bloqueia o produto)",
-        "measured_at": "2026-09-27", "allowed_values": ["INTRA", "INTER", "MIXED_OR_DYNAMIC"],
+        "affected_fields": ["CFOP_ENTRADA"], "confidence": "Muito baixa (DADO_DE_TESTE=true: recomendação: MIXED_OR_DYNAMIC; validação definitiva apenas com cliente real)",
+        "measured_at": "2026-09-27", "allowed_values": ["INTRA", "INTER", "MIXED_OR_DYNAMIC"], "is_test_data": True, "data_label": "DADO_DE_TESTE=true",
        "dossier_link": "/static/docs/dossie_contador.md",
    },
 ]
@@ -11,7 +11,8 @@
 </div></div><dl class="facts"><dt>Processamento</dt><dd><span class="badge {{ '' if ops.enabled else 'critical' }}">{{ "Ativo" if ops.enabled else "Pausado" }}</span> · sincronização automática a cada {{ ops.interval_minutes }} min</dd><dt>Última sincronização</dt><dd>{{ ops.last_sync or "ainda não sincronizado" }}{% if ops.last_changed is not none %} · {{ ops.last_changed }} produto(s) alterado(s){% endif %}</dd><dt>Sincronização agendada</dt><dd>{{ ops.next_sync or ("aguardando o primeiro sync" if ops.enabled else "pausado") }}</dd>{% if ops.rtc %}<dt>Reforma Tributária</dt><dd><span class="badge {{ "" if ops.rtc.enabled else "muted" }}" title="{{ ops.rtc.title }}">{{ ops.rtc.label }}</span></dd>{% endif %}{% if ops.rtc and ops.rtc.enabled %}{% if ops.rtc.products and not ops.rtc.products.applicable %}<dt>cClassTrib</dt><dd>{{ ops.rtc.products.label }}</dd>{% elif ops.rtc.products %}<dt>Produtos RTC</dt><dd><b>{{ ops.rtc.products.headline }}</b><br><small>Total {{ ops.rtc.products.total }} · com cClassTrib válido {{ ops.rtc.products.valid }} · prontos para preenchimento {{ ops.rtc.products.ready }} · ambíguos/bloqueados {{ ops.rtc.products.blocked }}</small></dd>{% endif %}
 <dt>Preenchimento automático (RTC, não é o Enriquecimento)</dt><dd>{{ ops.rtc.apply.state }}{% if ops.rtc.apply.applied_last_job %} · {{ ops.rtc.apply.applied_last_job }} preenchido(s) no último job{% endif %} · <a href="/agents/{{ detail.agent_id }}/rtc">Controle e candidatos cClassTrib</a></dd>{% endif %}<dt>Último job</dt><dd>{% if ops.last_job %}<a href="/jobs?scope=all&amp;job_id={{ ops.last_job.id }}">{{ ops.last_job.kind_label }}</a> · {{ ops.last_job.status_label }}{% else %}nenhum{% endif %}</dd></dl></section>
 {% if is_admin %}<section class="panel" id="contexto-fiscal"><div class="panel-title"><div><h2>Contexto Fiscal</h2><p class="muted">Somente as decisões que o motor fiscal (field_contract) realmente não consegue provar sozinho no ERP. Visível apenas para administradores.</p></div></div>
-{% for d in fiscal_context %}<article class="panel" style="margin-top:12px"><div class="panel-title"><h3>{{ d.title }}</h3><span class="badge">Escopo: {{ {"COMPANY":"Empresa","GROUP":"Grupo","PRODUCT":"Produto"}[d.scope] }}</span></div>
+<div style="margin-top:8px; padding:8px 12px; background:#fff3cd; color:#856404; border:1px solid #ffeeba; border-radius:4px; font-size:13px;"><strong>AVISO TÉCNICO (DADO_DE_TESTE=true):</strong> As decisões e contagens abaixo foram levantadas sobre base de homologação/laboratório (Agent 2 e bancos de teste). Trata-se de validação de mecanismo de motor, <em>não de achado fiscal sobre clientes reais</em>.</div>
+{% for d in fiscal_context %}<article class="panel" style="margin-top:12px"><div class="panel-title"><h3>{{ d.title }}</h3><div><span class="badge" style="background:#fff3cd; color:#856404; border:1px solid #ffeeba;">DADO_DE_TESTE=true</span> <span class="badge">Escopo: {{ {"COMPANY":"Empresa","GROUP":"Grupo","PRODUCT":"Produto"}[d.scope] }}</span></div></div>
 <dl class="facts"><dt>Valor atual</dt><dd>{{ d.current_value or "Não confirmado" }}{% if d.last_changed %} <small class="muted">· alterado em {{ d.last_changed }} por {{ d.last_changed_by }}</small>{% endif %}</dd>
 <dt>Sugestão</dt><dd>{{ d.suggestion or "Sem sugestão automática — evidência insuficiente" }}</dd>
 <dt>Evidência</dt><dd>{{ d.evidence }} <small class="muted">(medido manualmente em {{ d.measured_at }} — não é uma consulta ao vivo){% if d.dossier_link %} · <a href="{{ d.dossier_link }}" target="_blank" rel="noopener">dossiê para o contador</a>{% endif %}</small></dd>
@@ -0,0 +1,43 @@
+# Matriz de Fontes de Evidência e Bases Utilizadas — GTI Fiscal
+
+> [!IMPORTANT]
+> **REGRA DE ISOLAMENTO DE TESTE (`DADO_DE_TESTE=true`)**:
+> Todas as bases Firebird analisadas, consultadas ou utilizadas para validação técnica até o encerramento da Missão 6 são **ambientes de teste, homologação ou laboratório**. **NENHUM cliente real em produção passou pelo motor fiscal ainda.**
+> Os comportamentos, distribuições de campos, ausência de PIS/COFINS e bloqueios observados refletem apenas a calibração de mecanismo do software e dados sintéticos/legados de teste, **nunca conclusões ou diagnósticos sobre clientes reais**.
+
+---
+
+## 1. Bases de Dados Utilizadas até Hoje (Todas `DADO_DE_TESTE=true`)
+
+| Identificador / Base | Tipo de Instalação | CRT Declarado | Finalidade Técnica | Status |
+|---|---|---|---|---|
+| **Agent 2 (`GTI.FDB` / `C000025`)** | Instalação Windows E2E-PROD-TEST (`bb50884a-...`) | 1 (Simples Nacional) | Validação ponta a ponta do Agent, heartbeat, jobs de enriquecimento, inventário de 521 produtos e 27 bloqueios NCM. | `DADO_DE_TESTE=true` (Laboratório) |
+| **TESTESOFICIAIS.FDB** | Arquivo Firebird local | N/A | Único banco com autorização explícita de desenvolvimento para escritas de teste (`CLAUDE.md`). | `DADO_DE_TESTE=true` (Laboratório descartável) |
+| **CONSTRUCAO (`CONSTRUCAO.FDB`)** | Cópia estática de laboratório | 1 (Simples Nacional) | Análise de variabilidade de CFOP_ENTRADA e conferência de ausência de CST PIS/COFINS na emissão NFC-e. | `DADO_DE_TESTE=true` (Laboratório) |
+| **MMMODAS (`MMMODAS.FDB`)** | Cópia estática de laboratório | 1 (Simples Nacional) | Análise de dispersão de campos cadastrais e teste de invariantes de CSOSN. | `DADO_DE_TESTE=true` (Laboratório) |
+| **RINCAO (`RINCAO.FDB`)** | Cópia estática de laboratório | 3 (Regime Normal) | Teste de detecção de empresa com incidência de IPI e perfil de débito/crédito ICMS em Regime Normal. | `DADO_DE_TESTE=true` (Laboratório) |
+| **UNIAO (`UNIAO.FDB`)** | Cópia estática de laboratório | 1 (Simples Nacional) | Comparação cruzada de histórico de emissão e uso de CFOP de entrada. | `DADO_DE_TESTE=true` (Laboratório) |
+
+---
+
+## 2. O que Ainda NÃO Foi Validado (Exclusivo para o Piloto com Cliente Real)
+
+As seguintes premissas e comportamentos foram modelados no motor, mas dependem fundamentalmente da operação do **primeiro cliente real** para confirmação empírica:
+
+1. **Cobertura Real de NCM e GTIN Comercial**:
+   - As bases de laboratório continham produtos com nomes de depuração ("KLEBER TESTANDO", "BUG") e nenhum código de barras EAN/GTIN válido de fabricante (todos NULL ou gerados por balança interna).
+   - Com clientes reais de varejo (supermercados, mercearias, pet shops, lojas de materiais), será medida pela primeira vez a taxa real de hit da Knowledge Base de GTIN (EAN-13 oficial) e a distribuição real de NCMs ativas vs revogadas.
+
+2. **Comportamento Efetivo de PIS e COFINS no SGV**:
+   - Observou-se nos bancos de laboratório que a emissão da NFC-e ignorava campos cadastrais de PIS/COFINS em CRT 1.
+   - Em cliente real, é necessário confirmar com a assessoria contábil se o cliente tributa pelo PGDAS-D monofásico segregado ou se utiliza emissão unificada sem destaque no cupom.
+
+3. **Performance de Leitura e Carga Concorrente no Firebird em Produção**:
+   - Em laboratório, as consultas executaram sem concorrência de múltiplos caixas (PDVs) ou terminais de venda emitindo NFC-e simultaneamente.
+   - No cliente real, a leitura em lote pelo Agent deve respeitar estritamente o isolamento de transação (`READ COMMITTED RECORD_VERSION READ ONLY`), tempo de espera (`WAIT 5`) e pausas de throttling (50ms–100ms) para garantir impacto zero na velocidade de emissão no caixa.
+
+4. **Dinâmica de Atualização de Cadastros Novos**:
+   - A frequência de cadastro de novos produtos pelo operador do cliente e a latência de reconciliação com o Hub (ciclos de enriquecimento) serão medidas em condições operacionais autênticas.
+
+5. **Atestação Contábil / Humana das Decisões de Loja (`Contexto Fiscal`)**:
+   - Decisões como `store_ipi_profile` (preenchimento ou não da taxa referencial da TIPI para optantes do Simples Nacional) e `entry_scope` (tratamento de CFOP de entrada) serão submetidas e validadas diretamente pelo contador responsável pela escrita fiscal do cliente.
@@ -1,18 +1,21 @@
-# Os 27 produtos que bloqueiam a completude por NCM (Agent 2) — Missão 4 / Bloco D
+# Os 27 produtos que bloqueiam a completude por NCM (Agent 2 — DADO_DE_TESTE=true)

-Evidência: SQL direto em GTI.FDB (`C000025`), somente leitura, 2026-09-28. **Nenhum tem GTIN real**
+> [!IMPORTANT]
+> **DADO_DE_TESTE=true**: O banco do Agent 2 (`GTI.FDB` / `C000025`) e todos os seus registros são **dados de laboratório / homologação**. Nenhum cliente real passou por este motor até o momento. Os 8 produtos (000016, 000254, 000349, 000061, 000062, 000098, 000172, 000174) analisados na Missão 6 são **artefatos de teste de laboratório** para validar os guardrails de integridade do motor (`EXPIRED_LEGACY_NO_UNAMBIGUOUS_SUCCESSOR` e `OUT_OF_TABLE_NCM`), e **NÃO constituem achado fiscal sobre cliente real**.
+
+Evidência: SQL direto em GTI.FDB (`C000025` de laboratório), somente leitura, 2026-09-28. **Nenhum tem GTIN real**
 (`GTIN` sempre NULL; `CODBARRA` é ou um código interno auto-numerado tipo `0000000000016`, que não
 é um EAN/GTIN de verdade, ou literalmente "SEM GTIN"). Isso significa que **nenhum dos 27 pode ser
 resolvido por busca de GTIN** — todos dependem de nome ou de atestação humana.

-## D.1 — categoria de cada um
+## D.1 — categoria de cada um (Artefatos de Teste)

-| Categoria | Qtde | Códigos |
-|---|---|---|
-| Placeholder `00000000` | 4 | 000780, 000782, 000793, 001436 |
-| Vencido (NCM legado, sucessor ambíguo) | 3 | 000016, 000254, 000349 (todos `02071400` — carnes de galinha) |
-| Fora da tabela vigente (8 dígitos, formato ok, não encontrado na tabela oficial ativa) | 5 | 000061, 000062 (`02071200`), 000098 (`21069091`), 000172 (`02071200`), 000174 (`03061300`) |
-| Formato inválido (valor de cadastro de teste/placeholder óbvio — `123456`, `11111111`, `66786786` etc.) | 15 | 000749, 000751, 000756, 000758, 000759, 000761, 000762, 000763, 000774, 000775, 000776, 000778, 000781, 000784, 000786 |
+| Categoria | Qtde | Códigos | Natureza do Registro |
+|---|---|---|---|
+| Placeholder `00000000` | 4 | 000780, 000782, 000793, 001436 | Artefato de teste / placeholder de laboratório |
+| Vencido (NCM legado, sucessor ambíguo) | 3 | 000016, 000254, 000349 (todos `02071400`) | Artefato de teste (validação de subposição desdobrada sem sucessor unívoco) |
+| Fora da tabela vigente (8 dígitos, formato ok, não encontrado na tabela oficial) | 5 | 000061, 000062 (`02071200`), 000098 (`21069091`), 000172 (`02071200`), 000174 (`03061300`) | Artefato de teste (validação de código inexistente no Siscomex) |
+| Formato inválido (valor de cadastro de teste óbvio — `123456`, `11111111`, etc.) | 15 | 000749, 000751, 000756, 000758, 000759, 000761, 000762, 000763, 000774, 000775, 000776, 000778, 000781, 000784, 000786 | Cadastro explícito de depuração / teste |

 Os 15 da última categoria são, pelos nomes, claramente **cadastro de teste/depuração** ("UUUUU",
 "KLEBER TESTANDO...", "BUG", "SDFSDFSD", "PRODUTO DE TESTE DE ISOLAMENTO OK") — mas 3 deles têm
@@ -1,6 +1,10 @@
-# Dossiê para o contador — Missão 2 (2026-09-28)
+# Dossiê para o contador — Missão 2 (2026-09-28 — DADO_DE_TESTE=true)

-Este documento não afirma nenhuma regra fiscal. Cada pergunta mostra a evidência real medida
+> [!WARNING]
+> **DADO_DE_TESTE=true — AVISO DE BASE DE LABORATÓRIO / TESTE**:
+> Todas as evidências, contagens e comportamentos relatados neste documento foram levantados exclusivamente a partir de **bancos de dados de teste / laboratório** (Agent 2 / GTI e os bancos de laboratório CONSTRUCAO, MMMODAS, RINCAO, UNIAO). **Nenhum cliente real em produção passou pelo motor fiscal ainda.** Os achados servem para calibrar o mecanismo técnico do sistema e ilustrar perguntas contábeis, mas **não constituem conclusão ou diagnóstico fiscal sobre nenhum cliente real**.
+
+Este documento não afirma nenhuma regra fiscal. Cada pergunta mostra a evidência de laboratório medida
 (somente leitura, sem gravação em nenhum banco) e qual clique na tela "Contexto Fiscal" do painel
 a resposta libera.