epic(danfse): concluir apresentação NT008 v1.02 com divergência tipográfica documentada #118

Objetivo

Auditar, corrigir e comprovar a conformidade integral do DANFSe v2 produzido por nfse-php com a Nota Técnica SE/CGNFS-e nº 008/2026, versão 1.02, especialmente os itens 2.1 a 2.5 e o Anexo I.

O resultado deve ser verificável em todo o documento, não apenas nos campos previamente identificados com problemas (Código IBGE/CEP, alinhamentos e divisórias).

Fundamentação e evidências técnicas

A NT 008 estabelece que:

• O conteúdo impresso deve representar o XML autorizado; não se devem inventar valores fiscais ausentes (2.1).
• O posicionamento relativo dos campos deve respeitar o modelo do Anexo I; as dimensões e quantidades de caracteres sugeridas no item 2.4.5 não são obrigatórias, mas os tamanhos mínimos de fonte e as regras de apresentação são (2.1 e 2.2.4).
• O DANFSe deve ser impresso em uma única página, no mínimo A4 em orientação retrato (2.2).
• As divisórias entre blocos têm 0,5 pt, a borda da página 1 pt, e o sombreamento deve obedecer às regras específicas (2.2.3).
• Blocos e campos condicionais têm regras próprias de supressão (2.3); cancelamento e substituição requerem apresentação específica (2.5).

O código atual merece revisão integrada:

• src/Danfse/HTMLTemplate.php dispõe nome/e-mail na mesma linha, mas município/UF e Código IBGE/CEP junto do endereço, divergindo da distribuição apresentada no Anexo I.
• O mesmo template utiliza, entre outros, border-bottom: 0.7pt nas seções e border: 0.7pt na borda externa.
• O bloco do intermediário apresenta apenas CEP onde a norma também prevê identificação municipal, conforme os dados aplicáveis.
• Ainda é preciso confrontar os campos condicionais de destinatário, ISSQN, IBS/CBS, informações complementares e marcas de estado com seus respectivos contratos.
• docs/danfse-v2-rendering.md afirma que descrições extensas podem continuar em páginas adicionais; isso contradiz a exigência normativa de impressão em uma única página.
• Os testes em tests/Unit/Danfse/DanfseTemplateTest.php e tests/Unit/Danfse/DanfseGoldenReferenceTest.php verificam diversos rótulos e conteúdos, mas não constituem uma prova de conformidade da distribuição de todas as células, da paginação e dos estilos.

As evidências acima não demonstram que cada campo esteja errado; o objetivo é mapear e corrigir somente divergências verificadas, preservando o que já funciona.

Escopo da verificação

Abranger todos os blocos previstos na NT 008:

1. Cabeçalho, logomarca, município/UF, ambiente e advertência de produção restrita.
2. Identificação da NFS-e e DPS: chave, QR Code, número, série, competência, emissão, situação e finalidade.
3. Prestador/fornecedor.
4. Tomador/adquirente.
5. Destinatário da operação, inclusive quando coincidir com o tomador.
6. Intermediário da operação.
7. Serviço prestado: classificações, NBS, localidade e descrição.
8. Tributação municipal (ISSQN), benefícios e campos condicionais.
9. Tributação federal, retenções e regras aplicáveis à competência.
10. IBS/CBS: classificação, localização de incidência, bases, reduções, alíquotas nominais/efetivas e valores apurados conforme o XML.
11. Valores totais da NFS-e e IBS/CBS.
12. Informações complementares, inclusive os totais aproximados e a ordem/separação exigida.
13. Canhoto opcional.
14. Estados de cancelamento, substituição e produção restrita.

Validar, por bloco, conteúdo, origem no XML, obrigatoriedade, condições de exibição, estrutura das linhas/colunas, tipografia, sombreamento, bordas e tratamento de textos extensos.

Estratégia de execução

1. Auditoria completa e rastreável. Elaborar uma matriz dos requisitos da NT 008 com: seção normativa, obrigação ou sugestão, fonte XML, comportamento observado, estado de conformidade, teste existente/ausente e correção proposta. Manter a matriz no acompanhamento da issue e/ou na discussão do PR, como evidência de revisão; não criar arquivo Markdown no repositório para relatar etapas, achados transitórios ou evolução das issues.

2. Correções independentes. Depois de validar a matriz, decompor somente os resultados que tenham entregas técnicas próprias e testáveis. Corrigir DanfseTemplate.php, HTMLTemplate.php e componentes relacionados sem refazer correções já integradas. Evitar um único PR excessivamente amplo ou uma lista especulativa de tarefas.

3. Verificação integrada. Gerar HTML e PDFs a partir de XMLs inteiramente sintéticos; comparar a distribuição com o Anexo I, confirmar uma única página e inspecionar visualmente os casos extremos de comprimento/condicionalidade. Não exigir PDFs byte a byte idênticos.

4. Revisão de consumidores. Comunicar alterações efetivas de contratos de renderização e necessidades de atualização das aplicações consumidoras, sem introduzir dependência com ERP específico.

Critérios de aceitação

• Existe uma matriz de conformidade revisada para todos os blocos da NT 008, registrada na issue ou revisão do PR, não em documentação versionada de andamento.
• Todos os desvios normativos conhecidos foram corrigidos ou receberam decisão fundamentada e testável.
• As células, linhas, campos condicionais e supressões obedecem ao Anexo I e às regras aplicáveis.
• Bordas, divisórias, sombreamentos, fontes e dimensões mínimas são validados.
• O DANFSe é gerado em uma única página na configuração suportada, sem ocultar silenciosamente informações obrigatórias.
• O Código IBGE/CEP e demais identificações são obtidos e apresentados a partir de dados autorizados, sem perda de zeros nem preenchimento fictício.
• Campos de ISSQN, tributos federais, IBS/CBS e totais são fiéis ao XML, sem recálculo no renderizador.
• Estados de cancelamento/substituição e avisos de produção restrita são testados com uma fonte de estado explícita e confiável.
• Testes de estrutura HTML, unidade, geração de PDF e inspeção visual sintética cobrem os casos obrigatórios, opcionais, estrangeiros, incompletos e extensos.
• composer test, composer cs:check, composer psalm e verificações CI pertinentes passam.
• Documentação do produto não contém garantias incorretas nem narra o processo de implementação; o resultado integrado foi revisado.

Política de documentação — importante

Não transformar docs/, README.md ou outros arquivos Markdown em relatórios de auditoria, diários de implementação, listas de issues em andamento, tabelas de pendências ou descrições de estados transitórios.

Achados, matriz de análise, propostas, screenshots sintéticos e histórico de execução pertencem às issues e aos PRs.

Alterar documentação versionada somente quando necessário para corrigir ou explicar um contrato estável e relevante ao consumidor: por exemplo, corrigir uma garantia de paginação incompatível com a norma. Manter essa alteração mínima, voltada ao comportamento final e sem referências a etapas, commits ou PRs. Não alterar README apenas para registrar trabalho interno.

Limites e coordenação

• Não transmitir NFS-e nem alterar XML autorizado, DPS, cálculos tributários ou sequências fiscais.
• Não usar dados de contribuintes reais nas issues, commits, fixtures, logs, screenshots ou PDFs de evidência.
• Não reabrir trabalhos concluídos apenas por serem relacionados: Validate DANFSe v2 rendering against official NT 008 reference cases #57 fornece base de testes; o PR fix(danfse): alinhar a grade NT 008 e corrigir os campos de localidade #113 já introduziu melhorias que devem ser preservadas.
• A issue fix(danfse): adequar identificação do município e UF no cabeçalho à NT 008 #117 cobre especificamente a identificação municipal/UF no cabeçalho e pode avançar sem aguardar toda a auditoria.
• O PR fix(nfse): restore NT 007 consolidated social retentions in XML and DANFSe #116 contém alterações ainda em revisão relacionadas a outros campos; coordenar para não sobrepor correções.

Referência normativa: https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/rtc/nt-008-se-cgnfse-danfse-20260714-v1-02.pdf

O épico termina somente com a conformidade integrada demonstrada, não com o simples fechamento das issues individuais.

Complemento de aceitação — conformidade jurídica e origem do XML (2026-10)

• Separar claramente renderização da NFS-e autorizada da seleção/validação das obrigações tributárias feita pelo emissor. O DANFSe não deve recalcular IBS/CBS, ISS, retenções ou tributos estimados, nem inferir que a SEFIN autorizou o conteúdo por aceitá-lo.
• Incluir fixtures sintéticas por contrato legado e NT009 somente quando o XML correspondente estiver oficialmente suportado; NT009 preview (docs/nt009.md) não é contrato de emissão. Se ainda não houver XML autorizado de formato novo, classificar caso como futuro e não inventar saída conforme.
• Testar fidelidade XML autorizado → modelo de exibição → HTML/PDF campo a campo (presente, ausente, 0, condicional, arredondamentos já fixados no XML), e inspecionar PDF uma página segundo NT008 v1.02, com casos extensos sem ocultar campo legal obrigatório.
• Validar separadamente conteúdo (semântica fiscal) e forma (NT008); aprovar HTML não prova layout final. Não aplicar snapshot de bytes do PDF.
• O módulo akaunting-nfse#425 é responsável pela origem dos percentuais aproximados enviados; este épico verifica apenas representação fiel do XML autorizado. nfse-php#120 verifica regEspTrib como célula condicional de DANFSe; akaunting-nfse#424 verifica elegibilidade de configuração/preenchimento antes da DPS. PR fix(nfse): restore NT 007 consolidated social retentions in XML and DANFSe #116 trata semântica NT007, não deduzir o significado de vRetCSLL pelo nome.
• Nenhuma mudança em regras de negócio de cálculo ou XSD neste épico. Não exigir chamadas a SEFIN nem dados reais, e não chamar documentação de andamento de contrato estável.
  Referências: NT008 (https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/rtc), documentação XSD por ambiente (https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual), publicação NT009 (https://www.gov.br/nfse/pt-br/noticias/publicado-o-ato-tecnico-conjunto-rfb-cgibs-no-7-aprovando-a-versao-1-01-da-nota-tecnica-009-nfs-e-e-a-nota-tecnica-010-da-nfs-e-via).