# Fechamento da Fase 5 - Catalogo de Workflow Actions

## Status

A Fase 5 de `WorkflowAction` esta concluida no `praxis-metadata-starter`.

O eixo `action-oriented` ja esta implementado como camada semantica derivada sobre operacoes HTTP
reais, sem payload inline, sem dispatcher generico e sem redefinir o contrato estrutural canonico.

## O que a fase entregou

- `@WorkflowAction` como anotacao canonica para comandos de negocio explicitos
- catalogo global em:
  - `GET /schemas/actions?resource={resourceKey}`
  - `GET /schemas/actions?group={openApiGroup}`
- discovery contextual em:
  - `GET /{resource}/{id}/actions`
  - `GET /{resource}/actions`
- `ActionScope.ITEM` e `ActionScope.COLLECTION` publicados no mesmo modelo canonico
- catalogo retornando apenas referencias canonicas:
  - `operationId`
  - `path`
  - `method`
  - `requestSchemaId`
  - `requestSchemaUrl`
  - `responseSchemaId`
  - `responseSchemaUrl`
- availability contextual por composicao, com:
  - `ActionAvailabilityRule`
  - `ActionAvailabilityContextResolver`
  - `DefaultActionAvailabilityEvaluator`
  - short-circuit no primeiro deny sensivel
  - compartilhamento de contexto/snapshot por catalogo para evitar custo N+1 por action
  - `ResourceStateSnapshot` e `ResourceStateSnapshotProvider` promovidos para o pacote neutro `capability`
- conflito semantico `@UiSurface` + `@WorkflowAction` governado por
  `praxis.metadata.validation.surface-workflow-conflict=FAIL|WARN|IGNORE`
- shape canonico de `@WorkflowAction` governado por
  `praxis.metadata.validation.workflow-action-shape=FAIL|WARN|IGNORE`
- fixture E2E real para os dois escopos:
  - `POST /employees/{id}/actions/approve`
  - `POST /employees/actions/bulk-approve`

## Regras canonicamente fixadas

- `action` nao define fields, schema ou payload inline
- `action` sempre aponta para endpoint real tipado e documentado
- a identidade canonica da action e `(resourceKey, actionId)`
- `delete`, `filter`, `stats`, `options` e `PATCH` resource-oriented por intencao nao entram no catalogo de actions
- `@WorkflowAction` nao entra no catalogo de `surfaces`
- `@WorkflowAction` deve apontar para mapping canonico de comando, com verbo `POST` ou `PATCH` e path workflow-like (`/actions/...` ou alias `:action`)
- `ITEM` actions em catalogo global sao discovery semantico e nao affordance executavel sem `resourceId`
- `COLLECTION` actions podem ser avaliadas contextual e canonicamente sem `resourceId`

## Validacao que fecha a fase

Cobertura focal validada no starter:

- `ActionCatalogE2ETest`
- `ActionCatalogServiceTest`
- `AnnotationDrivenActionDefinitionRegistryTest`
- `DefaultActionAvailabilityEvaluatorTest`
- `DefaultActionAvailabilityContextResolverTest`
- `OpenApiUiSchemaAutoConfigurationActionAvailabilityTest`
- `SurfaceCatalogE2ETest`
- `AnnotationDrivenSurfaceDefinitionRegistryTest`
- `AbstractResourceControllerJpaWriteIntegrationTest`

Rodada de hardening da availability:

- `BUILD SUCCESS`
- `50 testes`
- ampliou a blindagem de:
  - `resource-context-required`
  - `missing-authority`
  - `resource-state-blocked`
  - `resource-state-unavailable`
  - short-circuit sem vazamento de metadata apos deny por RBAC
  - wiring plugavel da auto-configuracao com prova real de ordering/override do container

Rodada de fechamento de `ActionScope.COLLECTION`:

- `BUILD SUCCESS`
- `54 testes`
- ampliou a blindagem de:
  - discovery contextual `GET /{resource}/actions`
  - `404` explicito para recurso sem actions de colecao
  - fixture real com `POST /employees/actions/bulk-approve`
  - cobertura E2E dos escopos `ITEM` e `COLLECTION` sem regressao em `surfaces`
- QA independente sem findings bloqueantes

## O que ficou fora por escopo

- capabilities unificadas agregando operacoes canonicas + surfaces + actions
- anuncio HATEOAS do novo endpoint `GET /actions` nas colecoes
- cobertura negativa do comando de colecao para payload invalido e IDs ausentes
- snapshot agregado de estado para futuras actions de colecao dependentes do estado do conjunto
- perfil `e2e-pg` com PostgreSQL/Testcontainers

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

## Saida formal da fase

Com a Fase 5 encerrada:

- o starter ja possui discovery semantico de workflow actions sobre operacoes reais
- o catalogo de actions ja esta endurecido para uso corporativo basico nos escopos `ITEM` e `COLLECTION`
- a proxima fase canonicamente correta e a Fase 6 de capabilities unificadas