Fechamento da Fase 6 - Capabilities Unificadas

Status

A Fase 6 de capabilities unificadas esta concluida no praxis-metadata-starter.

O eixo de capabilities ja esta implementado como camada agregadora sobre contratos canonicos ja publicados, sem redefinir payload, sem schema inline e sem reabrir o problema de shadow API.

O que a fase entregou

• CapabilitySnapshot como snapshot unificado de:
  • canonicalOperations
  • surfaces
  • actions
• CanonicalCapabilityResolver para resolver o mapa canonico de operacoes publicadas a partir do OpenAPI agrupado
• CapabilityService / DefaultCapabilityService separando:
  • capabilities de colecao
  • capabilities de item
• discovery contextual no core HTTP em:
  • GET /{resource}/capabilities
  • GET /{resource}/{id}/capabilities
• agregacao canonicamente disciplinada:
  • colecao -> apenas surfaces de COLLECTION e actions de COLLECTION
  • item -> apenas surfaces de ITEM e actions de ITEM
• integracao do mesmo resolvedor canonico em ApiDocsController para manter x-ui.resource.capabilities alinhado ao agregado unificado
• comportamento defensivo para catalogos ausentes:
  • recurso valido sem surfaces publicadas -> lista vazia
  • recurso valido sem actions publicadas -> lista vazia
  • sem inventar semantica paralela
• hardening final do calculo de update:
  • workflow-like PATCH em /{id}/actions/...
  • aliases /{id}:action
  • nao contaminam mais a capability resource-oriented de update

Regras canonicamente fixadas

• capabilities nao define schema, fields ou payload inline
• capabilities apenas agrega:
  • operacoes canonicas presentes
  • surfaces disponiveis
  • actions disponiveis
• CapabilitySnapshot.group representa o grupo OpenAPI canonico resolvido por resourcePath
• CapabilitySnapshot.group nao representa o agrupamento documental agregado de @ApiGroup
• update no eixo de capabilities continua sendo semantica resource-oriented
• workflow actions nao podem contaminar update so por usarem PATCH

Validacao que fecha a fase

Cobertura focal principal validada no starter:

• OpenApiCanonicalCapabilityResolverTest
• CapabilityServiceTest
• CapabilityE2ETest
• AbstractResourceControllerJpaWriteIntegrationTest
• SurfaceCatalogE2ETest
• ActionCatalogE2ETest
• ApiDocsControllerTest

Primeiro corte da Fase 6:

• BUILD SUCCESS
• 61 testes
• validou:
  • resolver canonico
  • agregador de capabilities
  • fixture E2E real
  • piloto JPA interno
  • regressao lateral em surfaces, actions e ApiDocsController

Hardening curto da reabertura da fase:

• BUILD SUCCESS
• 22 testes
• endureceu explicitamente:
  • exclusao de workflow-like PATCH do calculo de update
  • semantica publica de CapabilitySnapshot.group
  • regressao em ApiDocsController para x-ui.resource.capabilities

QA independente:

• rodada principal sem blockers
• rodada de hardening sem blockers

O que ficou fora por escopo

• campo separado para distinguir grupo individual do recurso e agrupamento documental agregado
• suite integral do modulo
• perfil e2e-pg com PostgreSQL/Testcontainers
• migracao do primeiro consumidor externo

Esses pontos nao bloqueiam o encerramento da Fase 6. Eles pertencem a governanca futura, hardening transversal ou ao proximo ciclo de migracao.

Saida formal da fase

Com a Fase 6 encerrada:

• o starter ja possui snapshot unificado de capabilities sobre operacoes canonicas, surfaces e actions
• o calculo canonicamente publicado em /capabilities e em x-ui.resource.capabilities ficou alinhado
• a base 1-6 do plano arquitetural esta completa dentro do praxis-metadata-starter
• o proximo passo canonicamente correto deixa de ser evolucao interna do starter e passa a ser a migracao do primeiro consumidor externo