GTI_GERENCIADOR_FISCAL/docs/PROJECT_STATE.md

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

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 (preparado para deploy), deploy anterior 1.3.14 confirmado (DEPLOY_OK, health 200).
• Agent (última release Windows PUBLICADA): 1.3.8 — nenhum installer novo foi publicado nas Missões 2–7 (o Agent permaneceu 100% inalterado).
• 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

• main (master): 0034_reference_data_registry (33 migrações). Head única linear.
• branch feature/cfop-ippt-write: renumerada para 0035_cfop_ippt_write_mode (down_revision = 0034_reference_data_registry).
• Teste de Merge Real (Missão 7 / A.1):
  • Testado via git merge --no-commit --no-ff feature/cfop-ippt-write e abortado limpo.
  • Head do Alembic única: 0035_cfop_ippt_write_mode (head) (zero split estrutural no banco).
  • Conflitos de arquivos git mapeados: agent/tests/test_cfop_ippt_auto_apply.py e release/RELEASE_MANIFEST.json.

Reference Data Registry e Datasets P2–P4 (Missão 7)

• 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) (Esclarecimento A.3: SPED_PIS_COFINS e REFORMA_RTC não integravam os 9 datasets pré-existentes; pertencem ao pipeline de novos datasets mapeados na Descoberta).
• Métricas 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 (A.4 - 2026-09-28):
  • CBS 2026: 0,9% (ADCT art. 125, II / LC Reforma Tributária).
  • IBS 2026: 0,1% (ADCT art. 125, I / LC Reforma Tributária).
  • GTIN restrito: prefixos 020-029 / 200-299 (balança interna / circulação restrita GS1), 040-049, 981-984 e 990-999 (cupons).

Separação Teste vs Produção e Artefatos (Missão 7 / Bloco B)

• Rótulo DADO_DE_TESTE=true: Aplicado no card "Contexto Fiscal" da UI (agent_detail.html), no módulo de decisões (fiscal_context_ui.py), no dossiê contábil (dossie_contador.md) e em todos os relatórios.
• Reclassificação dos 8 Produtos Bloqueados: Definidos formalmente como artefatos de teste do banco de homologação do Agent 2 (docs/NCM_27_BLOCKED_PRODUCTS_V1.md), nunca achados fiscais sobre clientes reais.
• Catálogo de Fontes de Evidência: Formalizado em docs/EVIDENCE_SOURCES.md, separando as bases de teste das premissas pendentes de validação com o primeiro cliente real.

Prontidão para o Primeiro Cliente Real (Missão 7 / Bloco C)

• Checklist de Onboarding Seguro: Detalhado em docs/ONBOARDING_PRIMEIRO_CLIENTE_REAL.md (requisitos de rede HTTPS outbound exclusiva, leitura em lote de 50-100 itens com WAIT 5 e throttling de 50-100ms, backoff em busy, rollback instantâneo via parada de serviço/desinstalação).
• Segurança Agent-Hub: Tokens de instalação HMAC com expiração/revogação instantânea, rate limit por instalação, anonimização estrita em logs.
• Modo Recomendado: Somente leitura e DRY-RUN (sem AUTO_FILL ativo) pelas primeiras N = 3 execuções ou 7 dias de monitoramento contínuo.
• Critérios Objetivos de Seleção: Roteiro de 4 perguntas para decisão humana do operador (pequeno porte < 2.000 itens, Simples Nacional CRT 1 sem IPI, varejo simples com GTIN comercial, concordância do cliente).

Endurecimento do Hub e Disaster Recovery (Missão 7 / Bloco D)

• Segurança HTTP: Middleware implementado em central/app/main.py injetando X-Content-Type-Options: nosniff, X-Frame-Options: SAMEORIGIN, X-XSS-Protection e Referrer-Policy.
• Cobertura de Testes: Suíte central/tests/test_mission_07_hardening.py adicionada cobrindo ciclo de vida do Registry (aprovação, rejeição, checklist), classificação de taxas TIPI e headers de segurança.
• Runbook de DR do Hub: Passo a passo de restauração do Postgres em menos de 3 minutos e teste isolado documentados 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.