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 ativoPremissa: 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 |