Skip to content

Contrato — Action Semântica (Frontend Actions)

Contrato — Action Semântica (Frontend Actions)

Status: Aceito (substitui REF-90-A §12 quando refactor route→intent for concluído) Termos: Plataforma HÉLICO, API REST HÉLICO

Por que existe este contrato

Endpoints da API HÉLICO retornam objetos action para descrever o que acontece quando o Aluno clica num CTA. Antes, o backend mandava route literal (path do Frontend NextJS). O acoplamento ficou frágil: mudar a rota no Next exigia mudar PHP. Agora o backend descreve a intenção semântica; o Frontend resolve a rota.

Antes (REF-90-A §12 v1): { "type": "navigate", "route": "/slot/550e..." } — backend conhece path do Next.

Agora: { "kind": "open_slot", "label": "Iniciar", "params": { "slot_uuid": "550e..." } } — backend descreve intenção; Next mapeia.

Onde aparece

Endpoint Campo Quem produz
GET /study/{enrolment_id} slots[].action study_roadmap_view_service (slot lifecycle)
GET /study/{enrolment_id}/progress action study_api_controller::progress
GET /study/{enrolment_id}/alerts alerts[].action alerts_generator_service + cada alert_rule_interface
GET /study/{enrolment_id}/alerts alerts[].action (retrospective_available) alerts_generator_service + retrospective_available_rule
GET /study/{enrolment_id}/flashcards disciplines[].action flashcard_view_service
GET /platform/notifications (futuro) items[].action notification_view_service (pós-F7-PR3)

Shape

{
  "kind": "open_slot",
  "label": "Iniciar",
  "params": { "slot_uuid": "550e8400-e29b-41d4-a716-446655440000" }
}
Campo Tipo Obrigatório Descrição
kind string (enum) sim Identificador semântico da intenção. Ver tabela abaixo.
label string sim Texto pt-BR exibido no CTA. Backend é dono do texto.
params object | null depende Parâmetros da intenção. Shape definido por kind. Vazio = null.

kind é a fonte de verdade. label é apenas display. Frontend mapeia kind → rota/comportamento via tabela estática.

Vocabulário (kind)

kind Descrição params esperado Mapeamento Frontend (referencial)
open_slot Abre detalhe de um slot do Roteiro de Estudos { slot_uuid: string } /slot/{slot_uuid}
open_study_roadmap Volta para visão geral do Roteiro de Estudos null /roteiro-de-estudos
open_block Abre detalhe de um bloco específico { block_id: integer } /roteiro-de-estudos?block={block_id}
open_discipline Abre detalhe da disciplina (browse de unidades) { discipline_id: string } /disciplinas/{discipline_id}
open_flashcards Abre prática com flashcards filtrada por disciplina ou unidade { discipline_id: string } | { unit_id: string } /flashcards?discipline_id={id} ou /flashcards?unit_id={id}
open_exam Abre simulado por slot { slot_uuid: string } /simulados/{slot_uuid}
open_exams Abre a lista de simulados (sem slot específico) null /simulados
open_notebook Abre Caderno Online (artefato específico ou índice) { artifact_id?: integer } /caderno-online[?artifact={id}]
open_modal Abre modal interno do Frontend { modal_key: string } trigger de modal — sem rota
open_external Link externo (abre em nova aba) { url: string } (URL absoluta validada) window.open(url)
open_retrospective Abre a retrospectiva de conclusão do plano de estudos null trigger de modal — sem rota (ver open_modal, mas dedicado por ter fluxo próprio de popup-uma-vez)
open_profile Abre a tela de Perfil do Usuário, destacando os campos faltando { missing_fields: string[] } /perfil (destaca os campos faltando)
dismiss Apenas dispensa o CTA, sem destino null nenhuma navegação

Regra: params segue o schema do kind. Se uma chave esperada estiver ausente, Frontend trata como dado inválido (não navega; loga). Backend nunca emite kind sem os params obrigatórios.

Por que kind semântico vs type + route

Aspecto type+route (anterior) kind+params (atual)
Acoplamento backend ↔ Next Backend conhecia paths do Frontend Backend conhece intenções, não paths
Mudar rota no Frontend Editar PHP + Next Apenas Next
Adicionar destino novo Adicionar string em N lugares Adicionar kind + mapeamento Next
Validação de payload URL como string opaca Schema por kind (params tipados)
Versionamento Difícil — mudança silenciosa de rota quebra contrato Explícito — adicionar kind é breaking apenas no Next

Adicionar novo kind

  1. Definir o kind semântico (snake_case): exemplo open_devolutiva.
  2. Definir o schema dos params: chaves obrigatórias, tipos, validação.
  3. Adicionar à tabela acima.
  4. Adicionar entry no enum local_helico\extensions\platform\enums\action_kind.
  5. Atualizar producers (controllers / services / regras) para emitir o novo kind.
  6. Frontend NextJS atualiza o mapa interno kind → handler antes do deploy.
  7. Atualizar OpenAPI (composer build:openapi).

Regras

  • Backend nunca emite route/url literal. A única exceção é open_external, em que a URL absoluta é o conteúdo da intenção.
  • Backend é dono do label (idioma do produto: pt-BR). Frontend não traduz nem reformata.
  • Frontend é dono do mapeamento kind → rota. Mudar rota = mudar Next, não PHP.
  • Cada kind tem schema fixo de params. Se o produtor PHP não tem dado pra preencher um param obrigatório, não emite a action — emite null em slot.action/alert.action ou omite o objeto.
  • kind desconhecido pelo Frontend = render padrão (botão desabilitado + log). Não derruba a tela.

Migração

Migração executada em fase única (alerts + slots + progress + flashcards + future notifications). Antes da migração, o campo route aparece no payload; depois, o campo kind+params. Período de transição com ambos os campos não está previsto — backend e Frontend são versionados juntos no deploy.

Referências

  • ADR-90 — Domínio Platform — Gateway e Contratos de Tela
  • REF-90-A §12 — Actions dinâmicas (versão antes do refactor)
  • classes/extensions/platform/enums/action_kind.php — enum canônico
  • Producers: slot_action VO, alert_dto, study_api_controller::progress, flashcard_view_service
Navigation

Type to search…

↑↓ navigate↵ selectEsc close