Skip to content

REF-90-A: Premissas e Padrões dos Contratos API do Aluno

REF-90-A: Premissas e Padrões dos Contratos API do Aluno

ADR vinculado: ADR-90 — Domínio Platform — Gateway e Contratos de Tela Status: Aceito Data: 2026-04-29 Autor: Michael Meneses (Arquiteto)

Objetivo

Registrar as premissas arquiteturais e padrões de design aplicados na definição dos contratos da API REST HÉLICO para o fluxo do Aluno (UC-001 a UC-005). Este documento orienta futuras interpretações e novas implementações de endpoints no domínio platform.


1. Separação de responsabilidades — Auth vs Domínio

Camada Responsável Escopo
Autenticação (login, wstoken, JWT) local_middag Retorna wstoken + user info
Dados de domínio HÉLICO local_helico Inscrições, onboarding, plano, estudo

Premissa: MIDDAG não retorna dados específicos da HÉLICO. A API HÉLICO começa onde a autenticação termina.


2. Três namespaces de endpoints

/platform/*                              Cross-product, sem contexto de matrícula
/platform/dashboard                      Resumo geral
/platform/notifications                  Notificações do sistema (bell icon)
/platform/me                             User info
/platform/enrolments                     Inscrições com estado do ciclo
/platform/onboarding/{enrolment_id}/*    Onboarding (per-enrollment)

/platform/study/{enrolment_id}/*         Per-enrollment, exige contexto ativo

Premissa: Endpoints que dependem do produto/matrícula ativa ficam sob /study/{enrolment_id}. Endpoints que valem para qualquer contexto ficam diretamente sob /platform/.


3. Onboarding per-enrollment

Cada inscrição (Matrícula) tem seu próprio estado de Onboarding. O Onboarding não é per-user.

Fases:

  • Onboarding Geral — sempre existe, compartilhado
  • Complemento do Curso-Produto — quando a Trilha exigir

O Frontend NÃO hardcoda os steps. A API entrega a configuração (steps, tipos de input, opções) e o Frontend renderiza genericamente com base em input.type.

Premissa: Backend é dono da estrutura do questionário. Frontend é renderizador genérico. Novas perguntas = mudança de configuração no Backend, sem deploy de Frontend.


4. Contratos seguem terms, não código atual

Quando há divergência entre terms (fonte de verdade) e código existente, o contrato da API segue os terms. Backend adapta internamente até a implementação completa.

Premissa: Spec first — terms definem a estrutura; código é consequência.


5. Plano do Aluno é autônomo

Após criação (evento Primeiro Acesso), o Plano do Aluno é entidade independente. Não consulta nem depende do Plano de Estudo para operações de leitura.

Premissa: Endpoints de estudo resolvem dados a partir do Plano do Aluno, não do Plano de Estudo.


6. Slots pré-gerados e idempotência

O Motor de Execução pré-gera slots quando processa o Fluxo Atual. Cada slot é uma posição pré-alocada para uma atividade, identificada por UUID.

Benefícios:

  • Idempotência — slot existe antes da submissão; submissão duplicada retorna 409
  • Rastreabilidade — cada atividade tem UUID estável
  • Previsibilidade — Frontend sabe quantos slots existem antes de executar

Premissa: Atividades não são criadas ad-hoc. O Motor gera os slots; o Aluno preenche.


7. Slot agnóstico — estrutura padronizada

Todos os slots seguem a mesma estrutura independente do tipo de atividade:

Campo Papel
id (UUID) Identificação e idempotência
order Sequência no bloco
type Tipo de atividade (agnóstico — string)
status Estado: not_started, in_progress, completed, locked, skipped, dispensed
label Nome visível para o Aluno
scope[] Referências flexíveis
context{} Dados específicos do tipo — aninhamento livre
result Resultado individual (quando completed)
locked Motivo de bloqueio (quando locked)
action Ação disponível (quando acionável)

Premissa: Novos tipos de atividade plugam na mesma estrutura. Dados específicos ficam em context{}. Nunca adicionar campos top-level por tipo.


8. scope[] — Referências flexíveis

scope: [{ type: "discipline"|"unit", id: int, name: string }]

Resolve a variabilidade de referências sem campos fixos:

  • 1 discipline (DI)
  • discipline + unit (Resumo/Leitura)
  • múltiplas disciplines (Simulado Objetivo)
  • múltiplas units (Revisão Geral)

Premissa: Slots referenciam entities via scope[], não via campos discipline_id / unit_id fixos.


9. context{} — Aninhamento livre

Objeto livre que aninha conforme necessidade do tipo de atividade. Sem schema fixo — cada tipo define sua estrutura. Arrays e objetos encadeados são permitidos.

context: { format: "summary" }
context: { phase: "post_di_activities", di: { completed: true, score: 72 } }
context: { submission: { deadline: "...", max_pages: 5, formats_accepted: ["pdf"] } }

Premissa: context é o campo de extensão. Dados que não cabem nos campos fixos do slot vão aqui.


10. result em dois níveis

Nível Localização Conteúdo
Raiz response.result Agregado do bloco atual (slots_total, completion_%, time_spent)
Slot slot.result Resultado individual (score, level, completed_at — varia por type)

Premissa: Frontend usa result da raiz para progresso visual. Usa slot.result para detalhes.


11. locked com granularidade

{
  "reason": "prerequisite|progression|availability|dispensed",
  "message": "Texto legível",
  "depends_on": ["uuid-1", "uuid-2"],
  "unlock_rule": "all_completed|any_completed|scheduled",
  "unlock_at": "2026-05-01T00:00:00Z"
}

Premissa: locked explica o bloqueio em termos acionáveis. O Frontend pode mostrar dependências e estimativa de desbloqueio.


12. Actions dinâmicas

Todos os componentes que permitem ação (alerts, notifications, slots) usam o mesmo padrão:

{ "type": "navigate|navigate_with_context|modal|external|dismiss", "label": "..." }
type Campos adicionais
navigate route
navigate_with_context route, params{}
modal modal_key
external url
dismiss —

Premissa: Padrão de action unificado. Novos tipos de ação = novo valor de type, não nova estrutura.


13. effects[] na submissão

POST de submissão retorna effects[] com consequências:

{ "type": "slot_unlocked", "slot_id": "uuid" }
{ "type": "block_progress", "completion_percentage": 50 }
{ "type": "block_completed" }
{ "type": "flow_completed" }

Premissa: Frontend não precisa re-fetch completo após submissão. effects informa o que mudou incrementalmente.


14. Módulos futuros invisíveis

Módulos podem ser dinâmicos — gerados quando o current fecha. A API não lista módulos futuros.

Premissa: Não assumir que a sequência completa é conhecida antecipadamente. Mostrar apenas current flow/block/stage.


15. Notificações vs Alertas

Conceito Endpoint Escopo UI
Notificação do Aluno /platform/notifications Cross-product Bell icon (Header)
Alerta do estudo /platform/study/{id}/alerts Per-enrollment Componente na Área do Aluno

Premissa: Notificações são avisos do sistema. Alertas são tarefas acionáveis vinculadas ao estudo ativo.


16. Agrupamento no Backend

Operações de agrupamento (ex: unidades por disciplina) são feitas no Backend, não no Frontend.

Razões:

  • Cache compartilhado (N alunos, mesmo plano = 1 cálculo)
  • Frontend puro renderizador — sem lógica de domínio
  • Estrutura de agrupamento pode evoluir sem deploy de Frontend

Premissa: Backend entrega dados prontos para renderização. Frontend não reorganiza dados de domínio.


17. Convenções de nomeação

Aspecto Convenção
Controllers PHP {recurso}_api_controller.php, sem prefixo helico_
Endpoints helico/api/v1/platform/{recurso}
Status enum snake_case: not_started, in_progress, completed, locked
IDs de slot UUID v4
Datas ISO 8601 UTC (2026-04-29T15:00:00Z)
Objetos vazios (object) [] em PHP → {} em JSON (nunca null para contextos vazios)

UCs vinculados

UC Título Endpoints
UC-001 Login (auth MIDDAG)
UC-002 Inscrições do Aluno GET /platform/enrolments
UC-003 Onboarding do Aluno GET/POST /platform/onboarding/{id}
UC-004 Área do Aluno GET /dashboard, /notifications, /study/{id}/progress,disciplines,alerts
UC-005 Roteiro de Estudos GET/POST /study/{id}, /study/{id}/results, /study/{id}/slots/{uuid}
UC-006 Detalhe do Slot GET /study/{id}/slots/{uuid}, GET/POST /study/{id}/slots/{uuid}/session
UC-007 Desempenho (Visão) GET /study/{id}/performance
UC-008 Simulados (Visão) GET /study/{id}/exams, GET /study/{id}/exams/{slot_id}
UC-009 Caderno Online GET /study/{id}/notebook, GET /study/{id}/notebook/{artifact_id}
UC-010 Flashcards (Browse) GET /study/{id}/flashcards

Histórico

Data Evento
2026-04-29 Criado — consolida premissas das sessões 18-19 (UC-001 a UC-005)
2026-04-29 UC-006 adicionado — slot detail + session como sub-recurso
2026-04-29 UC-007 a UC-010 adicionados — visões agregadas do Aluno
Navigation

Type to search…

↑↓ navigate↵ selectEsc close