Skip to content

audit(danfse): mapear conformidade de todos os blocos à NT 008 #119

Closed
Closed
audit(danfse): mapear conformidade de todos os blocos à NT 008#119
Labels
area:fiscalarea:qualitykind:research

Description

@vitormattos
vitormattos
opened on Oct 11, 2026

Objetivo

Realizar a auditoria de conformidade do DANFSe v2 completo diante da Nota Técnica SE/CGNFS-e nº 008/2026, versão 1.02, e de seu Anexo I, para orientar as correções efetivamente necessárias na iniciativa #118.

Entrega desta issue: uma matriz normativa reproduzível, com evidência do comportamento do renderizador atual, testes existentes/ausentes e proposta de agrupamento de correções. Não é uma autorização para refatorar o renderizador inteiro em um único PR.

Abrangência

Percorrer, sem exceções, os blocos e as regras dos itens 2.1 a 2.5:

  • Cabeçalho, identificação da NFS-e/DPS, QR Code e ambiente.
  • Prestador, tomador, destinatário e intermediário (inclusive ausentes, coincidentes e estrangeiros).
  • Serviço prestado, Código IBGE/CEP, município/UF, NBS e descrições.
  • ISSQN, tributos federais, IBS/CBS, totalizadores e informações complementares.
  • Canhoto opcional, documentos cancelados/substituídos e produção restrita.
  • Disposição das células, tipografia, margens, divisórias, sombreamento, condições de supressão, limites de texto e impressão em uma única página.

Matriz de avaliação

Para cada requisito normativo, registrar:

  1. Seção, tabela ou nota da NT 008 e campo/bloco do Anexo I.
  2. Natureza da regra: obrigatória, sugerida ou condicional, sem transformar dimensões sugeridas do item 2.4.5 em obrigações.
  3. Fonte no XML autorizado ou fonte externa de estado explicitamente requerida e justificada.
  4. Comportamento atual (referência ao código/HTML/CSS e, quando necessário, PDF sintético).
  5. Estado: conforme, divergente, não aplicável ou dependente de esclarecimento.
  6. Teste de regressão existente ou necessário e proposta de correção.
  7. Consequências para consumidores apenas quando houver mudança observável de contrato.

Registrar a matriz em comentário da própria issue e/ou na discussão de um PR de auditoria. Não criar nem versionar um arquivo .md de diagnóstico, plano de execução, histórico de PRs ou estados transitórios no repositório.

Pontos de partida já verificados

  • src/Danfse/HTMLTemplate.php: reexaminar a ordem das células de nome, e-mail, município/UF, endereço e Código IBGE/CEP nos blocos de participantes frente ao Anexo I; o campo do intermediário apresenta apenas CEP.
  • O CSS utiliza 0.7pt para determinadas divisórias e borda externa; o item 2.2.3 especifica 0,5 pt para divisórias entre blocos e 1 pt para a borda da página.
  • A NT 008, item 2.2, exige uma única página; a documentação atual em docs/danfse-v2-rendering.md afirma que textos longos podem continuar em páginas posteriores. Classificar como divergência entre garantia documentada e norma e indicar a correção do contrato estável, sem acrescentar diário de desenvolvimento à documentação.
  • tests/Unit/Danfse/DanfseGoldenReferenceTest.php e tests/Unit/Danfse/DanfseTemplateTest.php verificam conteúdo e estilos selecionados; avaliar cobertura faltante de posição/ordem das células, regras condicionais, número de páginas e layout efetivamente renderizado.
  • Conferir com o XML e a NT 008 as condições para destinatário, tributos municipais opcionais, campos efetivos/apurados de IBS/CBS, informações complementares, marca d'água de cancelamento e substituição. Tratar essas áreas como itens a auditar, não como defeitos já demonstrados em todos os cenários.

Como verificar

  • Usar somente XMLs e dados sintéticos, incluindo variações de campos opcionais, participantes distintos/coincidentes, endereços nacionais/estrangeiros, tributações com/sem IBS/CBS, descrições extensas e documentos com estados fiscais diferentes.
  • Inspecionar os dados de DanfseTemplate::buildData(), a estrutura de HTMLTemplate.php, o PDF resultante e a documentação normativa.
  • Considerar também DanfseGenerator::generateFromXml() e os testes de referência existentes.
  • Identificar os testes que devem falhar com o comportamento incorreto (por exemplo, ordem das células, paginação ou espessuras), além de casos negativos.
  • Para problemas visuais, usar evidência gerada com fixtures sintéticas; não exigir igualdade byte a byte de PDFs nem screenshots com dados de contribuintes reais.
  • Não enviar/reemitir DPS nem depender de ambientes fiscais para demonstrar a apresentação do PDF.

Critérios de conclusão

  • Existe uma matriz com rastreabilidade de todos os blocos e requisitos aplicáveis da NT 008, sem lacunas não classificadas.
  • A distinção entre exigência obrigatória, condição, sugestão de dimensão e campo não aplicável foi revisada.
  • As divergências têm evidência técnica e teste reproduzível proposto; resultados inconclusivos estão claramente marcados.
  • A matriz identifica o tratamento de página única, bordas e divisórias, Código IBGE/CEP, participantes e campos fiscais condicionais.
  • Os trabalhos já existentes (Validate DANFSe v2 rendering against official NT 008 reference cases #57, fix(danfse): adequar identificação do município e UF no cabeçalho à NT 008 #117 e PRs relacionados) foram considerados, sem duplicação de correções.
  • As divergências estão agrupadas em entregas independentes passíveis de PR e com critérios de aceitação propostos; novas issues são criadas somente após revisão dessa decomposição.
  • Nenhum arquivo de documentação versionado foi criado ou alterado apenas para registrar a auditoria, seus estágios ou suas pendências.
  • Nenhum dado fiscal real, identificador de contribuinte ou documento de terceiros foi publicado.

Referências

Fora de escopo

  • Alterar dados fiscais, XML, DPS, cálculos tributários ou protocolos de transmissão.
  • Realizar refatoração integral do renderizador nesta issue.
  • Criar documentação de estados transitórios ou arquivos de acompanhamento no repositório.
  • Publicar exemplos reais de empresas, municípios, clientes ou notas fiscais.

Complemento da auditoria de outubro/2026

Incluir na matriz por bloco: (i) caminho exato no XML autorizado, (ii) valor ausente versus zero versus código válido, (iii) origem de cada rótulo/total, (iv) suporte comprovado à versão XSD/ambiente, (v) mutação que faria teste falhar, (vi) custo aproximado da classe de teste. Conferir NT007 (vRetCSLL = conjunto de contribuições retidas conforme tpRetPisCofins) e campos IBS/CBS da NT009 somente para formatos realmente implementados. A equivalência de nomenclatura PHP↔campo XML não prova igualdade de natureza tributária. Testar modelo de dados, DOM/HTML e PDF final separadamente. Matriz e achados continuam na issue/PR, nunca em relatório transitório versionado.

Activity

  1. vitormattos commented on Oct 12, 2026

    @vitormattos
    vitormattos
    on Oct 12, 2026 – with ChatGPT Codex Connector
    MemberAuthor

    Matriz normativa NT 008 v1.02 / Anexo I — revisão inicial do main (12/10/2026)

    Fonte primária identificada: versão oficial 1.02 de 14/07/2026, listada em https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/rtc ; PDF oficial https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/rtc/nt-008-se-cgnfse-danfse-20260714-v1-02.pdf ; cópia integral consultável hospedada pela FENACON https://fenacon.org.br/wp-content/uploads/2026/07/nt-008-se-cgnfse-danfse-20260714-v1-02.pdf . Comparar também a representação gráfica do Anexo I, não apenas a tabela 2.4.5. main = 60c4fad793c6562820e36085eeb8dab2c0f68b1f; #57 e PR #113 já entregues; PR #116 aberto (retenções NT007, país e testes). Sem operações fiscais.

    Legenda: O = obrigatório; C = condicional; S = sugestão (dimensões/quantidade de caracteres 2.4.5); P = parcial; D = divergente; N = não demonstrado. - é representação de ausência, não substituto do zero expresso no XML. Testes ausentes são recomendações, não falsos checks verdes.

    Ref. NT008 Regra/fonte XML e natureza Estado observado no código Teste/verificação de negócio necessária
    2.1; 2.4.5 O: somente XML da NFS-e autorizada; zero expresso preservado; ausência não vira valor. S: dimensões e limites de caracteres D: sumCurrency() refaz total IBS/CBS, exclusões e retenções federais no DanfseTemplate; descontos em tribMun em vez dos caminhos de vDescCondIncond; potencial criação de valores não autorizados XML → buildData() → HTML → PDF, três cenários ausente/0/valor, sem somar por inferência
    2.1.1–2.1.2; 2.4.3 O: chave de 50 dígitos (infNFSe/@Id), DPS número/série/datas, tpEmit, cStat, finNFSe, QR P: campos e QR existem, mas dimensões mínimas/posições e tipografia não provadas; statusLabel mapeia somente 100 DOM de linhas/colunas; formatos/códigos adicionais; QR >=1,52 cm, testes PDF
    2.4.3; 2.4.5 Município/Ambiente O/C: infNFSe/xLocEmi + emit/enderNac/UF; suprimir município se item cTribNac = 99; município 8pt, ambiente 6pt D #117: só município, fonte única 5,7pt e sem supressão municípios/UF diferentes; ausente; item 99; ambientes 1/2; PDF
    2.1.3; 2.4.5 Prestador O/C: infDPS/prest, inclusive endereço, município, IBGE/CEP; linha Nome Município IBGE/CEP, depois Endereço
    2.1.4; 2.3.1; 2.4.5 Tomador O/C: infDPS/toma, identificação completa ou mensagem de ausência D: ordem de células difere; ausência imprime tabela de hífens em vez de supressão específica tomador ausente, NIF, endereço nacional/exterior, município/CEP
    2.1.5; 2.3.1–2.3.2; 2.4.5 Destinatário O/C: infDPS/IBSCBS/dest, distinto/coincidente com tomador; mensagens normativas D: bloco não existe; mensagem de destinatário indevidamente acoplada ao else do intermediário destinatário distinto, igual, ausente, NIF, localização; DOM/PDF
    2.1.6; 2.3.1; 2.4.5 Intermediário O/C: infDPS/interm com município e IBGE/CEP; mensagem específica se ausente D: mostra apenas CEP e linhas na ordem errada; mensagem mistura ausência de destinatário casos presente/ausente, municipal/externo, manter zeros
    2.1.7; 2.4.5 Serviço O: serv/cServ/{cTribNac,cTribMun,cNBS,xDescServ}, xTribMun prefere a xTribNac quando informado; localidade D: sempre mostra descrição nacional truncada a 60 e ignora municipal, embora disponível; verificar país no PR #116 cenários descrição nacional/municipal, NBS, localidade exterior, comprimento, PDF
    2.1.8; 2.3.1; 2.4.5 e nota 4–5 O/C: ISS, incidência, regEspTrib, tpImunidade, exigSusp/{tpSusp,nProcesso}, benefício, deduções/descontos, BC/alíquota/apurado D #120: regime na linha inicial, código 9 não suportado, linhas condicionais/benefícios ausentes; ISS não incidente sem mensagem tabela de combinações ausência/0/9/desconhecido, irmãos presentes, não sujeição; mutação de presença da linha
    2.1.9; 2.4.5 e nota 6 O/C: IRRF, previdência, contribuições sociais, PIS/COFINS e retenções; segunda linha somente competência até 2026 D/P: falta regra de competência; semântica vRetCSLL sendo revista por PR #116; não sobrepor nem inferir CSLL isolada competência 2026/2027 e tpRetPisCofins conforme NT007, coordenar com PR #116
    2.1.10; 2.4.5 IBS/CBS O/C: infDPS/IBSCBS classificação/indicador; infNFSe/IBSCBS valores autorizados: reduções, bases, alíquotas normais/efetivas, apurações municipal/UF/CBS D: reduções fixadas em -; ausentes alíquotas efetivas e montantes UF/MUN; campo exclusões soma tributos sem base normativa completa todos os 14 componentes do bloco (incluindo 0 válido e campos ausentes), testes sem recálculo e DOM/PDF
    2.1.11; 2.4.5 Total O: infNFSe/valores/vTotalRet, vLiq, infNFSe/IBSCBS/totCIBS, vTotNF; descontos do DPS D: total de retenções somado localmente, não usa vTotalRet; combina duas grandezas em uma célula e repete valor total em IBS XML divergente de campos parciais, total do XML invariável, posicionamento células
    2.1.12; 2.4.5 Complementares O/C: dados imóvel/obra/evento/referências/substituição/inf. municipal/total aproximado; ordem e separação D: só xInfComp + percentuais sintéticos - sempre, sem outros campos; fontes aproximadas são responsabilidade do emissor (akaunting-nfse#425) variações apenas XML autorizado, percentuais/valores efetivamente presentes, nenhum fallback
    2.1.13; 2.3.3; Anexo I Canhoto C: bloco opcional; não inventar ciência/assinatura P: canhoto com hífens e posição fixa; PDF final/posicionamento não comprovado opcional presente/ausente, não colisão e uma página
    2.2.1–2.2.4; 2.4 O: uma página A4 retrato, margens 0,15–0,20 cm, divisórias 0,5pt, borda 1pt, fonte Arial rótulos e Microsoft Sans Serif valores; sombras seletivas D: CSS 0,7pt; @page 7pt/65pt; fontes 5,6–6,85pt sem hierarquia; Dompdf sem guard de páginas; CI visual exige pages > 1 PDF sintético em resolução inspecionável, pdfinfo, extrair texto/coordenadas; casos extremos devem falhar explicitamente se impossíveis sem ocultar informação
    2.5.1–2.5.2 O/C: marca d’água de cancelamento/substituição com estado autoritativo, >=50pt D/N: só homologação 45pt; sem integração comprovada a evento fiscal autorizado, não inferir de cStat ou subst isolados testes de estados com origem confiável, sem marcar como cancelado por suposição

    Achado especialmente crítico: .github/workflows/danfse-visual.yml contém test "$pages" -gt 1 para a fixture longa. Esse contrato atual conflita com o item 2.2. O teste de normalidade deve exigir exatamente uma página; conteúdo irredutível deve resultar em falha explícita de geração, não truncamento silencioso ou segunda página. Um limite de texto é sugerido na tabela 2.4.5, não permissão genérica para descartar dados fiscais obrigatórios.

    Decomposição para revisão (sem duplicar o encerrado): #117 cabeçalho; #120 linhas condicionais ISS; entrega própria de participantes e destinatário; entrega própria de fidelidade fiscal/IBS/CBS (coordenada com PR #116); entrega própria de PDF/paginação/CI; matriz/evidências e fechamento integrado em #118. Não declarar esta matriz como prova de PDF: evidências precisam ser anexadas em PR, com teste de renderização real.

    Fronteiras: #57/PR #113 integrados; PR #116 ainda não integrado; akaunting-nfse#424 decide elegibilidade de regime e #425 origem dos tributos aproximados antes da DPS; este repositório apenas apresenta o que o XML autorizado contém. NT009 preview não é fonte para inventar DANFSe autorizado. Nenhum dado ou certificado real utilizado.

  2. vitormattos commented on Oct 12, 2026

    @vitormattos
    vitormattos
    on Oct 12, 2026 – with ChatGPT Codex Connector
    MemberAuthor

    Complemento corretivo à matriz inicial — após leitura integral da NT008 oficial e inspeção de PDFs sintéticos (12/10/2026)

    1. Truncamento não é absolutamente proibido: o item 2.1 autoriza reticências (...) quando o campo não comportar integralmente o texto; o quadro 2.4.5 sugere, por exemplo, 1300 caracteres para descrição do serviço e 2000 para complementares. Preservar íntegro o XML autorizado; apresentar abreviação identificável no PDF, sem suprimir campos obrigatórios, observando os tamanhos mínimos de fonte e a ordem fixa dos tributos aproximados.
    2. Nem toda operação de soma em apresentação é recálculo tributário vedado: a NT008 indica composições específicas de montantes existentes no XML (por exemplo, total IBS/CBS e semântica de contribuições retidas sob condição). A revisão deve distinguir somatório de exibição expressamente normatizado de apuração fiscal/valor fictício ou fallback não autorizado; privilegiar infNFSe/valores/vTotalRet para o total de retenções.
    3. Prova PDF inexistente apesar de CI verde: artefato fix(danfse): respeitar município/UF, item 99 e hierarquia do cabeçalho NT008 (#117) #122 11750842108 e fix(danfse): distinguir ausência e zero em linhas municipais condicionais (#120) #123 11750328988, ambos com PDF de referência = 1 página e PDF longo = 3 páginas, conforme pdfinfo. O workflow atual exige pages > 1 no caso longo, contradizendo NT008 2.2. pdffonts em PDF de referência mostra Helvetica / Helvetica-Bold, não as famílias nomeadas na NT008 2.4.
    4. Matriz adicional zero: XSD 1.01 tem tpImunidade=0 com sentido próprio, embora NT008 2.4.5 descreva 1–5; deve ser registrado como divergência a conciliar com versão/competência, sem equiparar 0 a ausência.
    5. Os PDFs de referência não provam os cenários novos de #120 (ausente, 0, 9, benefícios e não incidência), apenas o exemplo de regime 6. A evidência final deve incluir renderização por caso e inspeção manual/automatizada de células e tipografia.

    Fonte oficial conferida: https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/rtc/nt-008-se-cgnfse-danfse-20260714-v1-02.pdf (itens 2.1, 2.2, 2.4.5, notas 4/5/6, Anexo I). Este complemento corrige qualquer leitura excessivamente absoluta da matriz anterior e permanece somente na issue, não em documentação versionada de andamento.

  3. vitormattos
    added
    area:fiscal
    area:quality
    kind:research
    on Oct 12, 2026
  4. vitormattos
    added a parent issue on Oct 12, 2026

  5. vitormattos commented on Oct 12, 2026

    @vitormattos
    vitormattos
    on Oct 12, 2026 – with ChatGPT Codex Connector
    MemberAuthor

    Matriz final — auditoria NT008 v1.02 e Anexo I (12/10/2026)

    A matriz inicial e o complemento corretivo anteriores permanecem como histórico. Esta atualização classifica o resultado APÓS merge do PR #136 (11fa63d). Fonte oficial: https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/rtc/nt-008-se-cgnfse-danfse-20260714-v1-02.pdf. Legenda: A = implementado/testado, D = divergência comprovada, NA = contrato futuro não suportado.

    Seção Origem e resultado Estado
    2.1.1–2.1.2 / 2.4.3 Chave, DPS, emissão, competência, ambiente, QR e município/UF da NFS-e autorizada; item nacional 99 suprime município A
    2.1.3–2.1.6 Prestador, tomador, destinatário e intermediário conforme DPS autorizada, incluindo ausências, distinção e exterior A
    2.1.7 Serviço, tributação nacional/municipal, NBS, localização e reticências visíveis no texto extenso A
    2.1.8 / notas 4–5 ISSQN, benefício, imunidade, suspensão e regime especial: ausência, zero, 9, desconhecido e não incidência 2/3/4 A
    2.1.9 / nota 6 Retenções federais e competência: aplicar composição especial vRetCSLL + vPis + vCofins para tpRetPisCofins=1 expressamente prevista na tabela NT008 2.4.5; zero exibido em débito próprio; nos demais códigos usar vRetCSLL segundo NT007 A
    2.1.10 Campos IBS/CBS apenas se presentes no XML autorizado; valores e alíquotas não são calculados no DANFSe A
    2.1.11 Totais de infNFSe/valores e IBSCBS autorizados, preservando ausência/zero, inclusive vTotalRet A
    2.1.12 Complementares em ordem normativa, campos XML repetidos e tributos aproximados existentes (valor ou percentual), sem confundir ISS com estimativa A
    2.1.13 / 2.3.3 Canhoto sem inventar ciência ou assinatura, visualmente separado A
    2.2 / 2.3 / Anexo I PDF A4 retrato, uma página, borda e divisórias; supressões permitidas; nove artefatos sintéticos inspecionados A
    2.4 Famílias de fontes estritas: PDF padrão ainda usa Helvetica. Incorporação local comprovada somente com DejaVuSans de teste; Arial e Microsoft Sans Serif não demonstradas. D: pendente #118
    2.5 Marcas de cancelamento/substituição só com evento fiscal externo confiável; teste de marca 50pt A
    NT009 de emissão Preview não equivale a XML autorizado transmissível; fora do escopo atual NA

    Evidência: PR #136, cinco commits assinados/DCO, merge verificado 11fa63d e 10/10 verificações de CI. Artifact GitHub Actions 11759872398, run 38277928235: 9 PDFs sintéticos; pdfinfo: 9/9 A4 de uma página; pdffonts: PDF padrão Helvetica, prova local DejaVuSans com emb=yes; inspeção de texto e imagens renderizadas. Sem emissão de nota, alteração de XML, histórico ou uso de dados/certificados reais.

    Resultado: auditoria e classificação concluídas; a divergência de fonte permanece rastreada no épico #118. Este fechamento NÃO certifica conformidade integral nem encerra o épico.

  6. vitormattos
    closed this as completedon Oct 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:fiscalarea:qualitykind:research

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions