GTI_GERENCIADOR_FISCAL/docs/PROJECT_STATE.md

Project State — GTI Fiscal (2026-09-28, fim da Missão 8)

Leitura obrigatória antes de qualquer nova missão fiscal (CLAUDE.md aponta para cá). Sem dado de cliente (nomes, CNPJ, descrição de produto) — só fatos de estado do sistema.

Important

SEPARAÇÃO RIGOROSA TESTE vs PRODUÇÃO (DADO_DE_TESTE=true): Todas as bases Firebird analisadas até hoje (Agent 2 e os 5 bancos de laboratório CONSTRUCAO, MMMODAS, RINCAO, UNIAO, TESTESOFICIAIS) são dados de teste e homologação. Nenhum cliente real passou pelo motor ainda. Qualquer métrica ou constatação levantada sobre essas bases representa validação técnica de mecanismo de software, não achado ou diagnóstico contábil sobre nenhum cliente.

Versões

• Hub (produção): 1.3.15 (bump e merge concluídos, preparado para deploy).
• Agent (última release Windows PUBLICADA): 1.3.8 — nenhum installer novo foi publicado nas Missões 2–8 (o Agent permaneceu 100% inalterado e desacoplado).
• Agent 2 (installation bb50884a-5e78-4f26-8cac-804932dae8de): 1.3.8, informado pelo operador — ambiente de teste/homologação.
• Hub e Agent são versionados independentemente — ver docs/VERSIONING.md.

Migration head e Merge Real (Missão 8)

• main (master): 0035_cfop_ippt_write_mode (34 migrações). Head única linear.
• Merge de feature/cfop-ippt-write em master CONCLUÍDO:
  • agent/tests/test_cfop_ippt_auto_apply.py: versão da branch mantida com 15 testes de segurança.
  • release/RELEASE_MANIFEST.json: reconciliado com head 0035 e versão 1.3.15.
  • Installation.cfop_ippt_write_mode: coluna adicionada com DEFAULT OFF ("DISABLED"). Zero escrita habilitada automaticamente.
  • Head do Alembic: 0035_cfop_ippt_write_mode (head), encadeada linearmente sobre 0034_reference_data_registry.

Reference Data Registry e Validações Oficiais (Missão 8)

• Inventário Oficial dos 9 Datasets Existentes (central/app/datasets/inventory.py):
  1. NCM (Siscomex)
  2. TIPI_IPI (Receita Federal)
  3. CEST (CONFAZ)
  4. BA_ST_MVA (SEFAZ-BA)
  5. NFE_MOC_TABLES (Receita Federal / ENCAT)
  6. CFOP (Portal Nacional NF-e)
  7. FCP (Portal Nacional NF-e)
  8. ANP (Portal Nacional NF-e)
  9. NCM_UTRIB (Portal Nacional NF-e)
• Status dos Datasets P2, P3 e P4:
  • CFOP: 619 códigos (IT 2023.002 v2.10, SHA-256 c95c...ff6f), status DRAFT.
  • NFE_DOMAINS: 130 códigos (MOC 7.0 Anexo I, SHA-256 5eb4...55d), status DRAFT.
  • TIPI_IPI: 11.103 NCMs/EX (Decreto nº 11.158/2022 até ADE 001-2026, SHA-256 d155...2e9a), status DRAFT.
  • CEST: 1.223 CESTs (Convênio ICMS 142/18, SHA-256 d7fb...54d3), status DRAFT.
• Validação de CBS/IBS e GTIN na Fonte Oficial (Missão 8 / B.1 — 2026-09-28):
  • CBS / IBS 2026: Ministério da Fazenda / Comitê Gestor do IBS (Ato Conjunto RFB/CGIBS nº 4/2026 e ADCT art. 125). CBS = 0,9% e IBS = 0,1% (alíquotas de teste totalizando 1,0%, compensáveis). Status: VERIFICADO_NA_FONTE.
  • GTIN Restrito: GS1 Brasil (https://www.gs1br.org). Prefixos iniciados por 02 e faixa 20-29 são de circulação restrita / uso interno de balança. Status: VERIFICADO_NA_FONTE.

Suíte Canônica e Cobertura de Testes (Missão 8 / Bloco C)

• Comando Canônico de Testes (documentado em CLAUDE.md):

  python -m pytest tests central/tests agent/tests -q
  

  • tests (raiz): 361 testes unitários offline.
  • central/tests (Hub): 650+ testes de backend, endpoints e conformidade.
  • agent/tests (Agent): 156 testes de integração e componentes locais.
  • Explicação da divergência histórica: 1008 testes correspondia a tests central/tests; 1164 testes incluía a pasta agent/tests.
• Elevação da Cobertura de Testes:
  • central/app/reference_registry.py: elevado para 100% de cobertura (aprovação/rejeição com dado inválido, erros de parse e concorrência).
  • central/app/classification.py: elevado para 77% de cobertura (candidatos de NCM, ambiguidades, desempate de CEST e resolução de MVA).
  • Suíte central/tests/test_mission_08_coverage.py adicionada.

Prontidão para o Primeiro Cliente Real e Segurança

• Rótulo DADO_DE_TESTE=true: Visível na UI do Hub (Contexto Fiscal), em fiscal_context_ui.py, no dossiê contábil e no relatório de bloqueios NCM.
• Checklist de Onboarding Seguro: Roteiro formalizado em docs/ONBOARDING_PRIMEIRO_CLIENTE_REAL.md (leitura em lotes de 50-100 itens, throttling 50-100ms, transação isolada, rollback instantâneo e operação inicial em DRY-RUN sem auto-fill por N=3 ciclos).
• Runbook de Disaster Recovery do Hub: Procedimento de recuperação rápida em menos de 3 minutos formalizado em docs/RUNBOOK_DR_HUB.md.

Índice de Documentos-Chave (docs/)

• EVIDENCE_SOURCES.md — matriz de fontes de teste vs o que falta validar com cliente real.
• ONBOARDING_PRIMEIRO_CLIENTE_REAL.md — checklist de onboarding, segurança e critério dry-run.
• RUNBOOK_DR_HUB.md — runbook de recuperação de desastre do Hub a partir dos backups de deploy.
• REFERENCE_DATASET_MANIFEST_V1.md — manifesto de datasets oficiais baixados (P1 a P4 com hashes e URLs).
• DESCOBERTA_P5_P6_MISSAO_6.md — levantamento completo de PIS/COFINS SPED e ICMS-ST para o Hub.
• dossie_contador.md — dossiê fiscal com aviso DADO_DE_TESTE=true.
• NCM_27_BLOCKED_PRODUCTS_V1.md — artefatos de teste com bloqueio de NCM.