story: endpoint de histórico de análises fiscais com AnalysisId durável

[elson-vinicius-lopes]

Origem

Bloqueio P0 do LayoutParserReact #197 ([PBI] Histórico seguro de análises fiscais por workspace). Drift do `@lp-contract-qa` (2026-09-07) confirmou: não existe endpoint de histórico/persistência de análise fiscal com identificador durável recuperável.

Gap

• `tbAiUserSession`/`tbAiUserSessionHistoryEntry` (story: tabela SQL AiUserSession/AiUserSessionHistoryEntry para histórico de longo prazo do pathway de IA #102) cobrem o histórico do pathway de IA por sessão — não "análise fiscal com ID durável".
• Base de identidade/workspace (feature: identidade imutável, workspaces e histórico fiscal por usuário #225) existe, mas não expõe recuperação de análise por ID.

Escopo a desenhar (@lp-architect antes de implementação)

• Contrato de persistência de uma "análise fiscal" (o que é uma análise: parse + candidatos + transformação exibida?) com `AnalysisId` durável (GUID determinístico ou gerado).
• Endpoint(s): `GET /api/analyses/{analysisId}`, listagem por workspace (`GET /api/workspaces/{id}/analyses` ou `/api/analyses?workspaceId=`), com paginação.
• Isolamento por workspace/usuário (reusar `ICurrentUser`/membership fiscal já existente).
• Banco: `IdentityDatabase:` — nunca `Database:`/172.31.249.51 (security.md).
• Retenção/TTL (fora de escopo desta issue ou dentro? decidir).

Critério de aceite

• Desenho de contrato (request/response + modelo de dados) aprovado.
• Endpoint de recuperação por `AnalysisId` e de listagem por workspace, com isolamento.
• `dotnet build`/`dotnet test` verdes.

Relacionado

• LayoutParserReact story: contrato aditivo PositionalAlignmentFailed por linha para sinalizar degradação posicional #197 (P0), feat: diagnostico estruturado de pathwayDiagnostics em execute-candidates (fecha LayoutParserReact#86) #200 (gate de contratos).
• story: tabela SQL AiUserSession/AiUserSessionHistoryEntry para histórico de longo prazo do pathway de IA #102, feature: identidade imutável, workspaces e histórico fiscal por usuário #225 (adjacentes, não cobrem).

[elson-vinicius-lopes]

Escopo confirmado pelo dono (2026-09-18)

Resposta à pergunta em aberto ("o que é uma análise: parse + candidatos + transformação exibida?"):

Uma "análise fiscal" = os arquivos que o usuário anexou junto com o layout. O histórico é o usuário conseguir ver, depois, o que ele analisou — recuperar os arquivos/layout submetidos numa análise anterior, não necessariamente um snapshot de todo o pipeline (parse+candidatos+transformação) em si.

Isso reduz o escopo do "o que persistir": o núcleo é o vínculo AnalysisId → arquivos anexados + layout usado, recuperável por workspace/usuário. Ainda cabe a @lp-architect decidir o contrato exato (onde os arquivos ficam armazenados — mesmo padrão de artefato já usado em outros pontos do projeto? referência a blob existente ou cópia própria?), mas a pergunta central de "o que é uma análise" está respondida.