[PBI] Ingestão versionada do pacote de especificação fiscal

[elson-vinicius-lopes]

Epic pai

#195

User story

Como especialista fiscal, quero montar um pacote com amostra de entrada, layout, planilha de especificação, XSD e gabarito opcional para que a IA trabalhe sobre evidências versionadas.

Aceite

• wizard identifica documento fiscal, versão, operação e jurisdição;
• upload separado por tipo de artefato, com progresso, erro e reenvio;
• revisão do pacote mostra hash, versão, qualidade, conflito e ausência;
• planilha permite confirmar aba/cabeçalho/colunas antes de interpretar; (PR feat(fiscal-package-wizard): confirma aba/cabeçalho/colunas do inventário antes da IA (#201) #269, merged develop→main, deploy produção 6482977582 em 2026-09-16)
• alteração de artefato cria revisão; não muda um Draft silenciosamente;
• conteúdo fiscal não vai para localStorage, log ou analytics;
• UI não habilita geração sem origem, estrutura e XSD identificados.

Dependência API

Contrato de FiscalMappingPackage e inventário normalizado.

[elson-vinicius-lopes]

Atualização cross-repo: a API #236 entregou criação multipart da revisão 1 e consulta de metadados. O PR front #208 já tipa/valida esse contrato e prepara upload idempotente com progresso e retry seguro. O PBI permanece Blocked para o wizard completo porque ainda faltam inventário normalizado de Excel/XSD, navegação/seleção de projetos e criação de nova revisão; a UI não inventará esses resultados nem projectId.

[elson-vinicius-lopes]

Implementação parcial — @lp-front-dev (commit local a65bf62 em develop, ainda não pushado)

Entregue e pronto para revisão:

• Novo componente FiscalPackageWizard (src/components/mapping-studio/FiscalPackageWizard/), rota workspace/fiscal-package e link na WorkspacePage.
• Consome o service/tipos já existentes do PR feat: integrar workspaces fiscais e contrato de pacotes #208 (mergeados em 2026-08-31, sem UI ligada até agora).
• Fluxo coberto: contexto fiscal (documento/versão/operação/jurisdição) gera automaticamente o artefato fiscalContext (JSON); upload por artefato (sample/layout/spec/xsd/expectedXml opcional) com barra de progresso; erros tratados via MappingPackageRequestError; resultado exibe hash/tamanho/status de inspeção por artefato da revisão criada.
• Quality gates locais limpos: npm run lint, npx tsc --noEmit, npx vitest run (346 testes, incluindo 4 novos do FiscalPackageWizard).

Ainda pendente — bloqueado por falta de contrato na API, não por escopo de implementação:

Confirmado contra LayoutParserApi (branch develop, Controllers/FiscalMappingPackagesController.cs): só existem POST .../projects/{projectId}/mapping-packages (cria pacote + primeira revisão) e GET .../mapping-packages/{packageId}. Models/Entities/Fiscal/FiscalProject.cs documenta explicitamente que CRUD completo de projeto está fora do escopo atual da API.

Por isso, os itens abaixo ficaram fora desta entrega (com aside explicativo na própria tela para o usuário):

1. Navegação/seleção de projetos — projectId continua sendo colado manualmente como GUID; não existe endpoint de listagem de projetos fiscais.
2. Inventário normalizado de Excel/XSD — a API só devolve hash/tamanho/status de antivírus por artefato, não estrutura de abas/cabeçalho/colunas.
3. Criação de nova revisão — o endpoint de revisão incremental (revisão 2+) ainda não existe na API.

Dos critérios de aceite originais do PBI, "upload multipart idempotente da revisão 1 com progresso e contexto fiscal" está entregue; "navegação de projetos", "inventário normalizado" e "nova revisão" seguem pendentes de contrato futuro em LayoutParserApi.

Status no board: movido para In Review (parte pronta para revisão), refletindo entrega parcial — o board não tem estado nativo de "parcial". O PBI permanece aberto; não fechar até a lacuna de contrato acima ser resolvida ou seu escopo remanescente ser desmembrado explicitamente.

(Registrado por @lp-product-manager a partir de handoff técnico do @lp-front-dev.)

[elson-vinicius-lopes]

Aviso do lado da API (LayoutParserApi): os 3 gaps reportados aqui já estão em produção desde 2026-09-05, via LayoutParserApi#309 (commit 8864f8b, mergeado em master):

1. Listagem de projetos fiscais — GET /api/workspaces/{workspaceId}/projects
2. Inventário normalizado de Excel/XSD — GET /api/workspaces/{workspaceId}/mapping-packages/{packageId}/artifacts/{artifactId}/excel-inventory
3. Criação de nova revisão incremental — POST /api/workspaces/{workspaceId}/mapping-packages/{packageId}/revisions

Os comentários no código da API (Controllers/FiscalMappingPackagesController.cs) já citam explicitamente 'Gap 1/2/3 — issue #201'. Pode sair de In Review/Blocked e retomar: navegação/seleção de projetos, exibição do inventário normalizado e fluxo de nova revisão.

[elson-vinicius-lopes]

Atualização de status — dependências de API resolvidas

A LayoutParserApi confirmou que os 3 gaps do pacote fiscal (listagem de projetos, inventário Excel/XSD e revisão incremental) estão em produção desde 05/09/2026 (LayoutParserApi#309).

O front já tem a implementação correspondente commitada (a65bf62 feat: wizard de ingestão do pacote de especificação fiscal (#201)), e o item já está em In Review no Project. Com a dependência de API agora confirmada em produção, não há mais bloqueio externo para concluir a validação deste PBI — falta apenas a evidência de QA/validação sobre os critérios de aceite (hash/versão/qualidade/conflito, confirmação de aba/cabeçalho, ausência de persistência em localStorage/log/analytics).

Deixando o status como In Review (movendo para In Validation quando @lp-qa confirmar o veredito) — ainda não há evidência suficiente registrada aqui para Done.

[elson-vinicius-lopes]

Reavaliação 2026-09-16

Revisão de src/components/mapping-studio/FiscalPackageWizard/FiscalPackageWizard.tsx (621
linhas, desde LayoutParserApi#309).

Entregue:

• Wizard identifica documento fiscal, versão de schema, operação e jurisdição.
• Upload separado por tipo de artefato (sample/layout/spec/xsd/expectedXml), com progresso,
  erro e possibilidade de reenvio.
• Revisão incremental: alterar artefato cria nova revisão (createRevision), não sobrescreve
  o pacote silenciosamente.
• Inventário normalizado de planilha (abas, colunas, contagem de regras) via
  getExcelInventory.
• Conteúdo fiscal não é persistido em localStorage/log/analytics (grep confirma ausência
  de qualquer localStorage.setItem no componente).
• UI não habilita envio sem projeto, contexto fiscal e os 4 artefatos obrigatórios
  (canSubmit).

Gap real remanescente:

1. "Revisão do pacote mostra hash, versão, qualidade, conflito e ausência" — hoje só
   temos hash, tamanho e status de inspeção de antivírus (inspectionStatus). A própria UI
   documenta essa limitação (aside.mapping-limitations, "O que esta tela não mostra
   ainda"). Depende da API expor sinais semânticos de qualidade/conflito/ausência —
   não encontrei contrato aberto para isso; precisa virar issue na API se o produto ainda
   quiser esse dado.
2. "Planilha permite confirmar aba/cabeçalho/colunas antes de interpretar" — hoje o
   inventário é só exibido (botão "Ver inventário da planilha"), não há um passo de
   confirmação explícita antes de a IA interpretar a planilha. Este é implementável só no
   front (o contrato ExcelInventoryResult com decisionSheets/columns já existe e é
   consumido) — falta adicionar uma etapa de confirmação/seleção de aba antes de prosseguir.

Mantendo em In Review — a ingestão em si funciona e está em produção, mas os dois pontos
acima seguem em aberto: um por dependência de API, outro puramente de front.

[elson-vinicius-lopes]

Dependência criada na API: LayoutParser/LayoutParserApi#424 — contrato aditivo de sinais de qualidade/conflito/ausência na ingestão da planilha de especificação fiscal. Status aqui não muda; aguardando avaliação/priorização do lado da API.