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
- Definir o
kindsemântico (snake_case): exemploopen_devolutiva. - Definir o schema dos
params: chaves obrigatórias, tipos, validação. - Adicionar à tabela acima.
- Adicionar entry no enum
local_helico\extensions\platform\enums\action_kind. - Atualizar producers (controllers / services / regras) para emitir o novo
kind. - Frontend NextJS atualiza o mapa interno
kind → handlerantes do deploy. - Atualizar OpenAPI (
composer build:openapi).
Regras
- Backend nunca emite
route/urlliteral. 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
kindtem schema fixo deparams. Se o produtor PHP não tem dado pra preencher um param obrigatório, não emite a action — emitenullemslot.action/alert.actionou omite o objeto. kinddesconhecido 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_actionVO,alert_dto,study_api_controller::progress,flashcard_view_service