epic: autenticação machine-to-machine + validação do layout FIAT para desbloquear e2e Cypress

[elson-vinicius-lopes]

Contexto

O gate e2e do repo LayoutParserCypress (validação ponta-a-ponta TXT → transformação → aceito pelo e-forms/Pollux) rodou contra a API real de desenvolvimento e encontrou dois bloqueadores que impedem a suíte inteira de rodar:

• Relacionado a gate: sem mecanismo de autenticação machine-to-machine — bloqueia suíte E2E Cypress inteira #218 — sem mecanismo de autenticação machine-to-machine, a API exige login OAuth interativo e o Cypress não consegue autenticar programaticamente.
• Relacionado a gate: generate-for-layout recusa layout FIAT com 'Tipo de layout não suportado: 2' #219 — generate-for-layout recusa o layout FIAT (LAY_TXT_MQSERIES_ENVNFE_4.00_NFe, GUID ad4fb6f4-9ff5-44fd-988b-3da5ed56b22c) com "Tipo de layout não suportado: 2".

Este EPIC amarra as duas frentes porque bloqueiam o mesmo gate, mas são tecnicamente independentes uma da outra — cada uma tem seu próprio critério de aceite abaixo.

Fecha parcialmente #218
Fecha parcialmente #219

Prompt para o time

Prompt autocontido — pode ser colado direto num agente (@lp-architect, @lp-backend-dev, @lp-parser-llm) ou usado por um dev humano para começar o trabalho. Também salvo como arquivo em docs/architecture/prompt-auth-m2m-e-layout-fiat-2026-08-29.md.

Contexto

O repo LayoutParserCypress mantém uma suíte E2E que valida, ponta-a-ponta, que documentos TXT transformados pela LayoutParserApi (via TCL/XSL gerados para um layout SysMiddle) são aceitos pelo e-forms/Pollux (SEFAZ fake de desenvolvimento da NDD). Esse gate roda cy.request() diretamente contra os endpoints da API — sem navegador, sem sessão interativa.

Ao rodar esse gate contra a API real, dois problemas bloquearam a suíte inteira:

1. A API passou a exigir login OAuth (Google/Microsoft) — não existe hoje nenhum mecanismo de autenticação de serviço para um cliente automatizado (como o Cypress) bater direto nos endpoints sem essa interação.
2. O endpoint generate-for-layout, quando chamado para o layout FIAT (LAY_TXT_MQSERIES_ENVNFE_4.00_NFe, GUID ad4fb6f4-9ff5-44fd-988b-3da5ed56b22c), recusa a chamada com o erro "Tipo de layout não suportado: 2". Não está confirmado se é uma lacuna real no código (o layoutType=2 deveria ser suportado e não é) ou um cadastro incorreto desse layout específico no banco.

Essas duas frentes são independentes uma da outra, mas ambas bloqueiam o mesmo gate — por isso viraram um EPIC único, com uma issue-filha para cada achado (#218 e #219).

Frente A — Autenticação machine-to-machine (dono sugerido: @lp-architect decide o mecanismo, @lp-backend-dev implementa)

Não decida a solução técnica sozinho de forma unilateral fora de uma avaliação explícita — isto é decisão de arquitetura. Avalie as opções plausíveis e registre a decisão (ADR ou doc em docs/architecture/) antes de implementar:

• OAuth2 client credentials grant (service principal, sem usuário humano no fluxo);
• API key de serviço com escopo restrito (só os endpoints do fluxo de transformação, não o CRUD administrativo);
• mTLS (certificado cliente);
• service account interno (usuário técnico "de sistema" com flag especial no banco).

Requisito não-negociável: o mecanismo escolhido não pode, em nenhuma etapa, exigir interação de navegador (redirect para tela de login, popup, MFA interativo). Tem que ser algo que um cy.request() do Cypress consiga completar programaticamente.

Critério de aceite: com a credencial de serviço, uma chamada legítima aos seguintes endpoints retorna 200:

• POST /api/AutoTransformation/generate-for-layout
• POST /api/transformation-execution/execute
• POST /api/TransformationExecution/execute-lowcode

Frente B — generate-for-layout recusa layoutType=2 para o layout FIAT (dono sugerido: @lp-parser-llm investiga)

Investigar por que o layout FIAT LAY_TXT_MQSERIES_ENVNFE_4.00_NFe (ad4fb6f4-9ff5-44fd-988b-3da5ed56b22c) é recusado por generate-for-layout com "Tipo de layout não suportado: 2".

Critério de aceite — uma das duas conclusões, documentada:

• (i) layoutType=2 deveria ser suportado pelo endpoint e há uma lacuna real de código — corrigir a lacuna; ou
• (ii) o layout está cadastrado com o tipo errado no banco — corrigir o cadastro.

Documentar explicitamente qual dos dois casos era, com evidência (trecho de código ou registro do cadastro).

Ao concluir

Quando as duas frentes estiverem resolvidas (ou parcialmente, avise qual), sinalize o repo LayoutParserCypress (@cy-devops ou @qa-cypress) para reexecutar o gate e2e (npm run test:mappers) e fechar as issues correspondentes lá (#9 e #10 nesse repo).

Rastreamento

• Issue-filha Frente A: gate: sem mecanismo de autenticação machine-to-machine — bloqueia suíte E2E Cypress inteira #218
• Issue-filha Frente B: gate: generate-for-layout recusa layout FIAT com 'Tipo de layout não suportado: 2' #219
• Prompt também salvo em: docs/architecture/prompt-auth-m2m-e-layout-fiat-2026-08-29.md