[EPIC] Upload inteligente com detecção automática de layout

[elson-vinicius-lopes]

Objetivo

Permitir que o analista anexe somente o documento e que o sistema identifique automaticamente o layout correto antes do parse.

Resultado de negócio

Reduzir erro humano e tempo de operação sem transformar semelhança em certeza falsa.

Escopo inicial

• MQSeries e SAP IDoc para NFe 4.00;
• detecção determinística com estados unique, ambiguous e not_found;
• seleção manual preservada como fallback;
• contrato API, UX acessível, segurança, observabilidade, MCP e gates E2E.

Não escopo

• Escolher o primeiro layout por nome/extensão;
• permitir que score de IA autorize seleção automática;
• prometer identificação universal quando o arquivo é compatível com mais de um layout.

Métrica principal

100% de precisão no subconjunto auto-selecionado e zero falsas auto-seleções no corpus aprovado. Cobertura pode ser menor que 100%; ambiguidade é resultado correto.

Evidência de discovery

Estudo versionável em docs/proposals/automatic-layout-detection-mqseries-idoc.md: catálogo com 57 layouts; amostra MQSeries ambígua entre cinco variantes; amostra IDoc com assinatura única no recorte.

Refinamento de produto — Top 5 equivalente

Quando a prova de unicidade não existir, a experiência passa a oferecer até cinco layouts mais equivalentes para escolha explícita, com foco inicial nos layouts Fiat e demais variantes próximas.

• o ranking é consultivo e nunca transforma similaridade em unique;
• cada alternativa explica por que está bem posicionada, com evidências, conflitos e limitações sanitizados;
• nenhuma alternativa vem pré-selecionada;
• empates são apresentados como empate, sem fabricar um vencedor;
• a escolha registra origem, layout escolhido, posição/score apresentados, versão do algoritmo e catálogo, correlationId e identificador de auditoria;
• se houver mais de cinco equivalentes, a resposta informa total e truncamento e preserva a busca manual no catálogo.

[elson-vinicius-lopes]

Hierarquia registrada no Project #3:

• PBI [PBI] Identificar automaticamente layouts MQSeries e IDoc #178 — detecção automática MQSeries/IDoc;
• Task [TASK] Documentar arquitetura e handoff da detecção automática #185 — documentação, memória e handoff.

O PBI #178 concentra contrato, API, UX/front, MCP e gate de qualidade como sub-issues nativas.

[elson-vinicius-lopes]

Handoff de produto — 29/08/2026

Rastreabilidade reconciliada entre os Projects oficiais:

• Front Project Integrate logging and multi-candidate transformation for analysis tab #3: [EPIC] Upload inteligente com detecção automática de layout #177 → [PBI] Identificar automaticamente layouts MQSeries e IDoc #178; bloqueios [TASK] Contrato: validar fingerprint e probe autoritativo da API #179/[STORY] Anexar somente o documento e receber o layout identificado #180/[GATE] Garantir zero falsa auto-seleção em MQSeries e IDoc #183/[TASK] Expor detect_layout no MCP após estabilizar contrato da API #184; [STORY] Anexar somente o documento e receber o layout identificado #180 → [TASK] Front: consumir parse automático e remover layout obrigatório #181/[TASK] UX: tratar unique, ambiguous e not_found com fallback manual #182; documentação [TASK] Documentar arquitetura e handoff da detecção automática #185.
• API Project Develop #2: feature: detecção autoritativa de layout por documento MQSeries/IDoc LayoutParserApi#213 → feat: governança de releases fiscais (Slice 7) no Mapping Studio (#213) #214 (fingerprint/colisões), chore(deps): bump fast-uri in /server #215 (gate independente) e chore(deps): bump fastify from 5.11.3 to 5.12.1 in /server #216 (MCP).
• Marco comum nos dois repositórios: Detecção automática de layout — MQSeries e IDoc.

Decisão de produto preservada: 100% de precisão no subconjunto auto-selecionado, sem exigir 100% de cobertura. Sem prova única, o resultado correto é ambiguous ou not_found; nunca o primeiro candidato por nome, extensão ou score.

Sequência recomendada: API #214 → API #213 → API #215 → aceite contratual front #179 → front #181/#182 → gate front #183 → MCP API #216/front #184. #185 permanece em andamento até revisão, PR e promoção da documentação.

[elson-vinicius-lopes]

Refinamento sincronizado — Top 5 equivalente

O escopo foi refinado sem criar nova Epic/PBI:

• quando não houver prova única, a API fornece até cinco layouts mais equivalentes;
• ambiguous lista candidatos compatíveis; not_found pode trazer sugestões aproximadas claramente separadas;
• ranking é determinístico, explicável e consultivo, com empates, total e truncamento;
• nenhuma alternativa vem pré-selecionada ou libera parse sozinha;
• seleção pelo ranking e override pelo catálogo completo exigem confirmação explícita e proveniência auditável;
• a contraparte contratual foi sincronizada em feature: detecção autoritativa de layout por documento MQSeries/IDoc LayoutParserApi#213–chore(deps): bump fastify from 5.11.3 to 5.12.1 in /server #216.

Itens impactados: #178–#185. A métrica de zero falsa auto-seleção permanece inalterada.

[elson-vinicius-lopes]

Implementação iniciada nas branches locais codex/feat-layout-auto-detection do front e da API. Em execução: front #180/#181/#182 e API #213/#214. Gates #183/#215 e MCP #184/#216 permanecem dependentes dos contratos e testes.

[elson-vinicius-lopes]

Entrega principal em revisão no PR #186, dependente da API #222. O fluxo arquivo-primeiro, top 5, proveniência e gates reais estão implementados; a evolução MCP #184 continua separada.

[elson-vinicius-lopes]

Fechamento técnico do incremento automático em 30/08/2026: API #222 e front #186 foram mergeados em develop; CI/deploy development, CodeQL, quality gates e E2E real MQSeries aprovados. As issues #179–#183 e #185 estão Done. Este Epic permanece aberto exclusivamente para a extensão MCP tipada #184, dependente de LayoutParserApi#216; isso não bloqueia o fluxo web entregue.

[elson-vinicius-lopes]

Auditoria integral de 30/08/2026: toda implementação React/BFF deste Epic está concluída em develop e validada por 250 testes front, 69 BFF, 18 E2E, contrato 13/13, zero vulnerabilidades e deployment development. A antiga #184 foi encerrada porque pertence ao MCP da API (#216). O único bloqueio restante é o gate de release #188: a API precisa promover /api/parse/auto para produção antes do front.