Fechamento da Fase 4 - Catalogo de Surfaces

Status

A Fase 4 do catalogo de surfaces esta concluida no praxis-metadata-starter.

O eixo surface-oriented ja esta implementado como camada semantica derivada sobre o contrato canonico resource-oriented, sem redefinir payload, validacao ou schema inline.

O que a fase entregou

• resourceKey obrigatorio em @ApiResource como identidade semantica estavel do recurso
• @UiSurface para surfaces explicitas sobre operacoes HTTP reais
• surfaces automaticas create, list, detail e edit
• discovery global em:
  • GET /schemas/surfaces?resource={resourceKey}
  • GET /schemas/surfaces?group={openApiGroup}
• discovery contextual item-level em:
  • GET /{resource}/{id}/surfaces
• catalogo retornando apenas referencias canonicas:
  • operationId
  • path
  • method
  • schemaId
  • schemaUrl
• availability contextual por composicao, com:
  • SurfaceAvailabilityRule
  • SurfaceAvailabilityContextResolver
  • ResourceStateSnapshotProvider
  • short-circuit no primeiro deny sensivel
  • compartilhamento de contexto/snapshot por catalogo para evitar custo N+1 por surface
• hardening final do catalogo:
  • 404 para resourceKey ou group desconhecidos
  • cache lazy no registry annotation-driven
  • exclusao de mappings workflow-like (/actions/ e :approve)

Regras canonicamente fixadas

• surface nao define campos, schema ou validacao inline
• surface sempre referencia operacao real descoberta no OpenAPI
• FORM e PARTIAL_FORM apontam para schema request
• VIEW e READ_PROJECTION apontam para schema response
• ITEM surfaces em catalogo global sao discovery semantico e nao affordance executavel sem resourceId
• workflow actions continuam fora do catalogo de surfaces

Validacao que fecha a fase

Cobertura focal validada no starter:

• SurfaceCatalogE2ETest
• AnnotationDrivenSurfaceDefinitionRegistryTest
• DefaultSurfaceAvailabilityContextResolverTest
• DefaultSurfaceAvailabilityEvaluatorTest
• SurfaceCatalogServiceTest
• OpenApiUiSchemaAutoConfigurationSurfaceAvailabilityTest
• AbstractResourceControllerJpaWriteIntegrationTest

Rodada de fechamento formal:

• BUILD SUCCESS
• 32 testes
• QA independente sem findings bloqueantes

Rodada de hardening de testes em src/test:

• BUILD SUCCESS
• 39 testes
• ampliou a blindagem de:
  • short-circuit sem vazamento de metadata apos deny por RBAC
  • resource-state-unavailable
  • ordenacao e conflitos canônicos em SurfaceCatalogService
  • not found de resourceKey e group
  • cache do registry e publicacao automatica mutavel vs. read-only
• QA independente sem blockers

O que ficou fora por escopo

• catalogo de workflow actions (@WorkflowAction) e endpoints /schemas/actions
• capabilities unificadas agregando surfaces + actions
• perfil e2e-pg com PostgreSQL/Testcontainers
• teste de bootstrap completo de ApplicationContext para ordering/override de SurfaceAvailabilityRule beans

Esses pontos nao bloqueiam o encerramento da Fase 4. Eles pertencem a fases posteriores ou a hardening adicional.

Saida formal da fase

Com a Fase 4 encerrada:

• o starter ja possui discovery semantico de surfaces sobre operacoes reais
• o catalogo de surfaces ja esta endurecido para uso corporativo basico
• a proxima fase canonicamente correta e a Fase 5 de WorkflowAction