# Stats Response Schema Platform Fix Plan

## Status do documento

Este arquivo virou registro histórico de uma correção de plataforma já
implementada e validada. Ele é útil para auditoria técnica e para reconstruir a
causa raiz original do problema de `stats/*`.

Não use este texto como fonte primária do contrato atual de stats; o contrato
vivo está no código, nos testes e nos guias/specs sincronizados do starter.

## Status em 2026-03-21

- Fase 1 concluída: `AbstractCrudController` publica `response schema` explícito para `group-by`, `timeseries` e `distribution`.
- Fase 2 concluída: `ApiDocsController` foi endurecido para seleção consistente de `content` e resolução de wrappers de stats.
- Fase 3 concluída: `ApiDocsController` e `DomainCatalogController` passaram a compartilhar a política de resolução via `OpenApiDocsSupport`.
- Fase 5 concluída: o starter ganhou cobertura cruzada entre `catalog` e `/schemas/filtered`.
- Fase 6 concluída: o `quickstart` foi validado com `StatsSchemaSmokeHttpTest`, confirmando `BUILD SUCCESS` para request/response schema e coerência de `schemaLinks`.
- Fase 7 auditada: não foi encontrado consumidor ativo no monorepo degradando `response schema` estrutural de `/schemas/filtered` para `responseSchema` de `/schemas/catalog`; o fluxo correto segue sendo `catalog` para discovery e `filtered` para estrutura.
- Endurecimento adicional no consumidor backend de AI: `SchemaRetrievalService` permanece acoplado apenas a `/schemas/filtered`, e a documentação do `praxis-config-starter` agora explicita que `/schemas/catalog` não substitui resolução estrutural.

## Objetivo

Corrigir em nível de plataforma a inconsistência entre:

- o contrato OpenAPI publicado para `POST /stats/group-by`
- o contrato OpenAPI publicado para `POST /stats/timeseries`
- o contrato OpenAPI publicado para `POST /stats/distribution`
- o comportamento de `/schemas/filtered`
- o comportamento de `/schemas/catalog`

A meta não é apenas fazer o frontend funcionar. A meta é restaurar um contrato
canônico, verificável e consistente entre a documentação OpenAPI, os schemas
derivados e os consumidores metadata-driven.

## Diagnóstico Consolidado

### Fato 1: os DTOs canônicos já existem

O starter já possui DTOs explícitos e padronizados para stats:

- `GroupByStatsResponse`
- `TimeSeriesStatsResponse`
- `DistributionStatsResponse`

Também já existe o wrapper canônico `RestApiResponse<T>`.

Ou seja, o problema não é falta de modelagem de domínio.

### Fato 2: o vínculo da operação com o schema de resposta está incompleto

Os endpoints de stats em `AbstractCrudController` publicam exemplos no `200`,
mas não publicam explicitamente o `schema` da resposta no conteúdo OpenAPI.

Na prática, isso permite que o OpenAPI final preserve:

- `components.schemas.RestApiResponseGroupByStatsResponse`
- `components.schemas.GroupByStatsResponse`
- exemplos operacionais de resposta

mas perca o elo canônico:

- `paths -> ... -> responses -> 200 -> content -> application/json -> schema`

Quando esse elo some, `/schemas/filtered` deixa de conseguir resolver
`schemaType=response`.

### Fato 3: a falha é sistêmica na família `stats/*`

A investigação mostrou que isso não afeta só `vw-perfil-heroi/group-by`.
O padrão é repetido em toda a família `stats/*`.

Na superfície pública verificada, os casos sem `schema` de resposta estavam
concentrados exclusivamente em `stats/*`.

### Fato 4: `/schemas/catalog` e `/schemas/filtered` não estão operando com a mesma garantia contratual

Hoje o catálogo:

- pode enxergar `responseSchema`
- sempre publica `schemaLinks.response`

mas o filtered:

- exige que o schema seja resolvível no documento OpenAPI selecionado
- falha com `400` quando esse vínculo não existe

Isso significa que o catálogo pode expor um link contratual que o endpoint
estrutural não consegue honrar.

### Fato 5: há divergência na estratégia de resolução do documento OpenAPI

Os dois controladores não resolvem grupo/documento da mesma forma:

- `ApiDocsController` resolve grupo a partir do path real solicitado
- `DomainCatalogController` resolve grupo com uma estratégia mais ampla

Mesmo que isso não fosse a causa raiz principal, isso já é um problema
arquitetural porque permite inconsistência entre duas superfícies derivadas do
mesmo contrato.

## Objetivos da Correção

### Objetivo Primário

Garantir que todo endpoint `stats/*` publique um `response schema` OpenAPI
explícito, estável e resolvível por `/schemas/filtered`.

### Objetivo Secundário

Garantir que `/schemas/catalog` e `/schemas/filtered` derivem suas respostas a
partir de premissas compatíveis e testadas.

### Objetivo de Plataforma

Garantir a seguinte propriedade:

- se `/schemas/catalog` expõe `schemaLinks.response` para uma operação
- então `/schemas/filtered` deve conseguir resolver esse `response schema`

Essa propriedade precisa virar contrato de plataforma, não convenção informal.

## Princípios de Solução

### 1. Corrigir na origem do contrato

A solução correta começa na publicação OpenAPI dos endpoints de stats, não no
frontend e não em fallbacks oportunistas do catálogo.

### 2. Evitar inferência onde o contrato pode ser explícito

`findResponseSchema(...)` pode ter heurísticas defensivas, mas stats não deve
depender de inferência por nome ou estrutura parcial. O contrato deve ser
explícito.

### 3. Tornar as superfícies derivadas coerentes entre si

`/schemas/catalog` e `/schemas/filtered` podem ter finalidades diferentes, mas
não podem divergir sobre a existência do schema estrutural da mesma operação.

### 4. Proteger a correção com testes de consistência cruzada

Não basta testar cada endpoint isoladamente. É necessário testar a coerência
entre:

- OpenAPI da operação
- `/schemas/catalog`
- `/schemas/filtered`

## Escopo da Correção

### Incluído

- endpoints `stats/group-by`, `stats/timeseries` e `stats/distribution`
- publicação OpenAPI desses endpoints no starter
- resolução de `response schema` em `/schemas/filtered`
- coerência contratual em `/schemas/catalog`
- testes unitários/integrados do starter
- validação downstream no quickstart

### Excluído do primeiro lote

- redesign dos payloads de stats
- mudança semântica dos DTOs de stats
- novos endpoints analíticos
- features de frontend além da remoção de workarounds temporários

## Plano de Implementação

### Fase 0: Congelar o contrato desejado

Definir explicitamente o contrato-alvo para cada operação de stats:

- `group-by` retorna `RestApiResponse<GroupByStatsResponse>`
- `timeseries` retorna `RestApiResponse<TimeSeriesStatsResponse>`
- `distribution` retorna `RestApiResponse<DistributionStatsResponse>`

Também registrar a expectativa de documentação:

- `requestBody.content.application/json.schema` presente
- `responses.200.content.application/json.schema` presente
- `examples` preservados
- wrappers e DTOs presentes em `components.schemas`

Saída esperada da fase:

- lista de asserts canônicos a serem codificados nos testes

### Fase 1: Corrigir a publicação OpenAPI na origem

Ajustar `AbstractCrudController` para que cada `@ApiResponse(responseCode = "200")`
de stats publique explicitamente o schema do wrapper correto.

Direção recomendada:

- declarar `mediaType = "application/json"`
- declarar `schema = @Schema(implementation = ...)`
- preservar os `examples` já existentes no mesmo `@Content`

Ponto crítico:

- a anotação não deve degradar os exemplos operacionais já publicados
- a anotação não deve colapsar o tipo em `Object.class`
- a anotação deve continuar gerando wrappers específicos e navegáveis em
  `components.schemas`

Arquivos-alvo:

- `src/main/java/org/praxisplatform/uischema/controller/base/AbstractCrudController.java`

### Fase 2: Endurecer a resolução de `response schema` em `/schemas/filtered`

Mesmo com a publicação corrigida, o `ApiDocsController` deve ficar mais robusto.

Trabalho recomendado:

- revisar `findResponseSchema(...)`
- preferir seleção de content type via helper equivalente ao usado no catálogo
- suportar de forma consistente `application/json`, `*/*` e primeiro content
  disponível quando seguro
- manter prioridade para `x-ui.responseSchema` quando explicitamente publicado

Objetivo:

- reduzir fragilidade do endpoint derivado sem transformá-lo em resolvedor
  heurístico excessivo

Arquivos-alvo:

- `src/main/java/org/praxisplatform/uischema/controller/docs/ApiDocsController.java`

### Fase 3: Unificar a política de resolução entre catálogo e filtered

Hoje os dois controladores podem consultar documentos/grupos diferentes para a
mesma operação.

Direção recomendada:

- extrair uma política compartilhada de resolução de grupo/documento OpenAPI
- fazer `DomainCatalogController` usar a mesma lógica de path real quando
  `pathFilter` estiver presente
- reduzir o espaço para divergência entre grupo específico e fallback global

Opção preferida:

- criar um componente compartilhado para:
  - resolver grupo a partir do path
  - buscar documento OpenAPI com fallback
  - selecionar content node preferido

Arquivos-alvo:

- `src/main/java/org/praxisplatform/uischema/controller/docs/ApiDocsController.java`
- `src/main/java/org/praxisplatform/uischema/controller/docs/DomainCatalogController.java`
- possivelmente um novo helper compartilhado em `controller/docs` ou `util`

### Fase 4: Endurecer o contrato de `/schemas/catalog`

O catálogo não deve publicar `schemaLinks.response` cegamente.

Duas opções:

- opção preferida: só publicar o link quando o response schema for
  resolvível/consistente
- opção aceitável: publicar sempre, mas adicionar teste obrigatório de
  resolubilidade e falhar a build quando isso quebrar

Recomendação:

- manter os links, mas fazer a suíte de testes garantir a consistência
- se durante a implementação isso ainda deixar janelas de falso positivo,
  condicionar a emissão do link à resolubilidade real

Arquivos-alvo:

- `src/main/java/org/praxisplatform/uischema/controller/docs/DomainCatalogController.java`

### Fase 5: Cobertura de testes

#### 5.1 Testes de `ApiDocsController`

Adicionar cenários para:

- `schemaType=response` com `group-by`
- `schemaType=response` com `timeseries`
- `schemaType=response` com `distribution`
- response com `examples` e `schema` explícito
- content type alternativo quando aplicável
- fallback controlado para wrapper `RestApiResponse<...>`

Também adicionar um teste negativo:

- operação com examples, mas sem response schema explícito
- comportamento esperado documentado de forma clara

#### 5.2 Testes de `DomainCatalogController`

Adicionar cenários para:

- stats response schema publicado corretamente
- `schemaLinks.response` consistente com a operação
- comportamento quando o documento não permite resolver response schema

#### 5.3 Teste de consistência cruzada

Adicionar um teste de integração do starter com esta propriedade:

- para uma operação de stats no catálogo
- o `schemaLinks.response` emitido deve ser resolvido com sucesso por
  `/schemas/filtered`

Esse é o teste mais importante do lote porque fecha a regressão estrutural.

Arquivos-alvo:

- `src/test/java/org/praxisplatform/uischema/controller/docs/ApiDocsControllerTest.java`
- `src/test/java/org/praxisplatform/uischema/controller/docs/DomainCatalogControllerTest.java`
- novo teste integrado, se necessário

### Fase 6: Validação downstream no quickstart

Depois da correção no starter:

- atualizar a dependência consumida pelo quickstart
- validar que os endpoints reais `stats/*` continuam operando
- validar que os docs OpenAPI reais agora publicam `response schema`
- validar que `/schemas/catalog` e `/schemas/filtered` convergem nos casos
  `funcionarios`, `vw_perfil_heroi` e `vw_indicadores_incidentes`

Validações mínimas:

- `GET /schemas/filtered?...schemaType=request` continua `200`
- `GET /schemas/filtered?...schemaType=response` passa a `200`
- `GET /schemas/catalog?...stats...` continua trazendo request/response/examples
- os links de schema do catálogo passam a ser efetivamente navegáveis

Arquivos/superfícies-alvo:

- `praxis-api-quickstart` consumindo a versão corrigida do starter
- OpenAPI público do quickstart

### Fase 7: Remoção de contingências em consumidores

Se houver fallback temporário no frontend para usar `responseSchema` do catálogo
quando `/schemas/filtered` falhar, esse fallback deve ser tratado como
contingência transitória.

Após a correção de plataforma:

- remover ou reduzir esse fallback
- voltar a tratar `/schemas/filtered` como fonte estrutural canônica
- manter `/schemas/catalog` como fonte documental/discovery

Resultado da auditoria de 2026-03-21:

- `praxis-ui-angular` na feature `stats-examples` já usa `/schemas/filtered` para `request/response` e `/schemas/catalog` apenas para discovery/exibição.
- `praxis-config-starter` usa `SchemaRetrievalService` apontando somente para `/schemas/filtered`.
- Não foi identificado fallback estrutural ativo a remover neste lote; a ação correta foi endurecer o contrato e documentar explicitamente a separação de responsabilidades.

## Backlog Técnico por Arquivo

### Starter

- `src/main/java/org/praxisplatform/uischema/controller/base/AbstractCrudController.java`
  - explicitar `schema` do `200` em `group-by`, `timeseries`, `distribution`
  - preservar `examples`

- `src/main/java/org/praxisplatform/uischema/controller/docs/ApiDocsController.java`
  - endurecer `findResponseSchema(...)`
  - alinhar seleção de content type
  - reduzir dependência de heurísticas frágeis

- `src/main/java/org/praxisplatform/uischema/controller/docs/DomainCatalogController.java`
  - alinhar resolução de grupo/path
  - revisar emissão de `schemaLinks.response`
  - manter coerência com resolubilidade real

- `src/test/java/org/praxisplatform/uischema/controller/docs/ApiDocsControllerTest.java`
  - cobrir stats response reais

- `src/test/java/org/praxisplatform/uischema/controller/docs/DomainCatalogControllerTest.java`
  - cobrir consistência de links e response schema para stats

- `src/test/java/...`
  - incluir teste de consistência cruzada entre catálogo e filtered

### Quickstart

- atualizar a versão do starter
- rerodar smoke de stats
- validar docs reais e endpoints derivados

## Ordem Recomendada de Execução

1. adicionar testes que reproduzem a falha atual
2. corrigir a anotação OpenAPI em `AbstractCrudController`
3. corrigir/fortalecer `ApiDocsController`
4. alinhar `DomainCatalogController`
5. adicionar teste de consistência cruzada
6. validar no quickstart
7. só então ajustar consumidores se necessário

Essa ordem é importante porque força a correção a nascer no contrato e não no
consumidor.

## Critérios de Aceite

### Contrato OpenAPI

- cada endpoint `stats/*` publica `responses.200.content.application/json.schema`
- os `examples` continuam presentes
- os wrappers específicos continuam em `components.schemas`

### `/schemas/filtered`

- `schemaType=request` continua resolvendo
- `schemaType=response` passa a resolver `group-by`, `timeseries` e
  `distribution`

### `/schemas/catalog`

- continua expondo request schema, response schema e operation examples
- `schemaLinks.response` não aponta mais para um endpoint estrutural quebrado

### Consistência

- existe teste garantindo que links de schema publicados pelo catálogo são
  resolvíveis

### Downstream

- quickstart validado com recursos reais
- consumidores de frontend deixam de depender de workaround para stats response

## Riscos

### Risco 1: SpringDoc gerar wrappers inesperados

Ao explicitar `schema` no `@ApiResponse`, o SpringDoc pode gerar nomes de
wrapper diferentes dos atuais.

Mitigação:

- proteger por testes de snapshot/asserts estruturais
- validar nomes reais publicados em `components.schemas`

### Risco 2: perda involuntária de examples

Ao mexer em `@Content`, os exemplos podem desaparecer ou ser sobrescritos.

Mitigação:

- asserts específicos para `operationExamples`
- validação de catálogo e filtered após a mudança

### Risco 3: resolver divergência entre docs públicos e internos

Se `app.openapi.internal-base-url` estiver apontando para uma superfície
OpenAPI diferente da pública, a inconsistência pode continuar mascarada.

Mitigação:

- validar explicitamente a origem usada server-side
- documentar essa dependência operacional
- garantir que os testes do starter não dependam de diferenças ambientais

## Definition of Done

- a família `stats/*` publica response schema OpenAPI explícito
- `/schemas/filtered` resolve request e response para stats
- `/schemas/catalog` e `/schemas/filtered` ficam coerentes para stats
- existe teste de consistência cruzada cobrindo `schemaLinks.response`
- quickstart validado com recursos reais
- workarounds temporários em consumidores ficam desnecessários ou claramente
  marcados para remoção

## Próxima PR Recomendada

Escopo da primeira PR:

- testes reprodutores no starter
- correção de `AbstractCrudController`
- ajuste mínimo de `ApiDocsController`
- teste de consistência cruzada básico

Escopo da segunda PR:

- refatoração compartilhada da resolução de documento/grupo
- endurecimento adicional do catálogo
- validação downstream no quickstart