Contexto
A iniciativa do front-end para upload sem seleção manual está rastreada em:
O estudo com layouts reais MQSeries e IDoc mostrou que identificação universal com 100% de acerto e 100% de cobertura não é demonstrável quando dois layouts aceitam o mesmo conjunto observável de registros. A garantia correta é: zero falsa auto-seleção. A API só seleciona quando há prova única; caso contrário retorna ambiguidade ou ausência de candidato.
Objetivo
Implementar na LayoutParserApi um fingerprint/probe determinístico, versionado e sem efeitos colaterais que receba somente o documento e resolva o layout internamente.
Contrato esperado
POST /api/parse/auto (ou contrato equivalente aceito pelo front), multipart com o documento e override manual opcional.
Resposta:
- unique: um único layout provado; inclui layout selecionado, evidências, versões/hash, correlationId e resultado do parse;
- ambiguous: dois ou mais candidatos ainda compatíveis; não deve selecionar por score;
- not_found: nenhum candidato compatível; inclui conflitos sanitizados.
Regras duras
- formato físico MQSeries/IDoc;
- largura explícita quando disponível;
- conjunto de marcadores/segmentos;
- ordem e hierarquia;
- cardinalidade validada;
- discriminadores cadastrados e versionados.
Nome do arquivo, extensão, nome do layout, quantidade isolada de campos ou score de ML podem ordenar candidatos, mas não autorizam seleção automática.
Requisitos técnicos
Evidência inicial
- O catálogo atual possui 57 layouts.
- No recorte NF-e 4.00 foram avaliados 5 MQSeries e 4 IDoc.
- Um fixture MQSeries real teve todos os 59 registros reconhecidos por todos os 5 layouts MQSeries avaliados: o matcher estrutural atual não distingue esse caso.
- Um fixture IDoc real foi distinguido por cobertura de segmentos no recorte avaliado, mas isso não prova unicidade universal.
Critérios de aceite
Dependências e handoff
O consumo no front está planejado em LayoutParser/LayoutParserReact#180, #181 e #182; o gate de aceitação é LayoutParser/LayoutParserReact#183.
Refinamento de contrato — Top 5 equivalente
Quando não houver prova única, a API deve retornar uma lista rankedCandidates com até cinco layouts mais equivalentes para escolha explícita do usuário.
Semântica
- unique: exatamente um layout provado; pode seguir para parse automático.
- ambiguous: de 2 a 5 candidatos ainda compatíveis, ordenados por equivalência.
- not_found: de 0 a 5 sugestões mais próximas, separadas semanticamente de candidatos compatíveis; zero somente quando não houver layout comparável.
- Se o universo aplicável exceder cinco, a resposta informa total e truncamento, sem impedir busca manual no catálogo.
Explicabilidade e segurança
Cada candidato deve trazer identificador estável, rank, score/componentes, evidências favoráveis, conflitos, limitações e indicação de empate. O ranking deve ser determinístico para o mesmo documento, versão do catálogo e algoritmo. Nome, extensão ou score podem ordenar alternativas, mas continuam incapazes de produzir unique.
Resultados não únicos não podem preencher layout selecionado, executar parse, editar ou transformar sem confirmação explícita.
Override auditável
A escolha deve preservar, sem payload documental:
- status original da detecção;
- layoutGuid escolhido;
- origem ranked_candidate ou manual_override (auto_unique para a seleção autoritativa);
- rank/score apresentado no momento da escolha, quando aplicável;
- versões/hash do algoritmo e catálogo;
- correlationId, data/hora e identificador de auditoria;
- identificador técnico do ator conforme política de retenção/acesso, sem e-mail em log comum.
A API deve rejeitar escolha adulterada, expirada ou incompatível com o snapshot/versionamento da detecção, exigindo nova detecção quando necessário.
Contexto
A iniciativa do front-end para upload sem seleção manual está rastreada em:
O estudo com layouts reais MQSeries e IDoc mostrou que identificação universal com 100% de acerto e 100% de cobertura não é demonstrável quando dois layouts aceitam o mesmo conjunto observável de registros. A garantia correta é: zero falsa auto-seleção. A API só seleciona quando há prova única; caso contrário retorna ambiguidade ou ausência de candidato.
Objetivo
Implementar na LayoutParserApi um fingerprint/probe determinístico, versionado e sem efeitos colaterais que receba somente o documento e resolva o layout internamente.
Contrato esperado
POST /api/parse/auto (ou contrato equivalente aceito pelo front), multipart com o documento e override manual opcional.
Resposta:
Regras duras
Nome do arquivo, extensão, nome do layout, quantidade isolada de campos ou score de ML podem ordenar candidatos, mas não autorizam seleção automática.
Requisitos técnicos
Evidência inicial
Critérios de aceite
Dependências e handoff
O consumo no front está planejado em LayoutParser/LayoutParserReact#180, #181 e #182; o gate de aceitação é LayoutParser/LayoutParserReact#183.
Refinamento de contrato — Top 5 equivalente
Quando não houver prova única, a API deve retornar uma lista rankedCandidates com até cinco layouts mais equivalentes para escolha explícita do usuário.
Semântica
Explicabilidade e segurança
Cada candidato deve trazer identificador estável, rank, score/componentes, evidências favoráveis, conflitos, limitações e indicação de empate. O ranking deve ser determinístico para o mesmo documento, versão do catálogo e algoritmo. Nome, extensão ou score podem ordenar alternativas, mas continuam incapazes de produzir unique.
Resultados não únicos não podem preencher layout selecionado, executar parse, editar ou transformar sem confirmação explícita.
Override auditável
A escolha deve preservar, sem payload documental:
A API deve rejeitar escolha adulterada, expirada ou incompatível com o snapshot/versionamento da detecção, exigindo nova detecção quando necessário.