UC-002: Resolução de Estado do Aluno (Pós-Auth)
Status: EM REVISÃO Data: 2026-04-29 Domínio: platform Ator: Aluno Terms: Matrícula, Inscrição no Curso-Produto, Ciclo do Aluno, Onboarding, Primeiro Acesso, Plano do Aluno, Status do Plano do Aluno, Área do Aluno, Produto Comercial, Trilha Pedagógica, Vigência de Acesso
Contexto
Após login (UC-001), o Frontend precisa saber: quem é o usuário, quais produtos ele tem acesso, e qual o estado de cada um. Este endpoint é a porta de entrada da plataforma HÉLICO.
Endpoint
GET /platform/enrolments?status=active
Authorization: Bearer {wstoken}Parâmetros query:
status(opcional, default:active) — filtra por Status da Matrícula:active,suspended,inactive,all
Resposta
{
"user": {
"id": 42,
"fullname": "Maria Silva",
"email": "aluno@email.com",
"avatar_url": "https://plataforma.helico.com.br/avatar/42.jpg"
},
"enrolments": [
{
"id": 101,
"course_id": 5,
"status": "active",
"product": {
"id": 10,
"fullname": "Curso Regular Extensivo — MP",
"shortname": "cre-mp"
},
"trail": {
"id": 20,
"fullname": "Trilha CRE MP 2026"
},
"study_plan_id": 30,
"onboarding": {
"completed": false,
"general_completed": false,
"complement_required": false,
"complement_completed": false
},
"student_plan": {
"id": null,
"status": null
},
"validity": {
"start": "2026-03-01",
"end": "2027-03-01"
}
}
]
}Campos e mapeamento para terms
user (embutido)
Dados básicos do usuário. Evita chamada separada a /platform/me no boot do app.
| Campo | Descrição |
|---|---|
id |
ID do usuário no Moodle |
fullname |
Nome completo |
email |
|
avatar_url |
URL do avatar |
enrolments[]
Cada elemento representa uma Matrícula (entity_root, engine.access).
| Campo | Term | Tipo no term | Notas |
|---|---|---|---|
id |
Matrícula | entity_root | ID da helico_enrolment |
course_id |
Curso-Produto (Moodle) | entity | ID do course Moodle |
status |
Status da Matrícula | state_group | active, suspended, inactive |
product |
Produto Comercial | entity_root | Objeto aninhado com id/fullname/shortname |
trail |
Trilha Pedagógica | entity_root | Objeto aninhado com id/fullname |
study_plan_id |
Plano de Estudo | entity_root | null se trilha não publicada |
onboarding |
Onboarding | process | Estado do onboarding desta inscrição |
student_plan |
Plano do Aluno | process | null se não criado ainda |
validity |
Vigência de Acesso | — | Datas de início e fim |
onboarding (per-enrolment)
Estado do Onboarding para esta inscrição específica. Conforme terms, o Onboarding tem duas camadas: Geral (compartilhada) e Complemento (per-Curso-Produto).
| Campo | Term | Descrição |
|---|---|---|
completed |
Primeiro Acesso | true se Onboarding completo (geral + complemento se exigido) |
general_completed |
Onboarding Geral | true se camada geral concluída |
complement_required |
Complemento de Onboarding do Curso-Produto | true se este curso exige complemento |
complement_completed |
Complemento de Onboarding do Curso-Produto | true se complemento concluído |
student_plan
| Campo | Term | Valores |
|---|---|---|
id |
Plano do Aluno | null (não criado) ou ID |
status |
Status do Plano do Aluno | null, not_started, active, blocked, interrupted, completed, closed |
Mapeamento dos estados canônicos:
null→ Plano do Aluno ainda não criado (pré-Primeiro Acesso)not_started→ Plano do Aluno Não Iniciadoactive→ Plano do Aluno Em Execuçãoblocked→ Plano do Aluno Bloqueadointerrupted→ Plano do Aluno Interrompidocompleted→ Plano do Aluno Concluídoclosed→ Plano do Aluno Encerrado
Lógica de roteamento no Frontend
Frontend recebe { user, enrolments[] }
│
├── enrolments.length === 0
│ └── Tela: "Nenhum produto ativo" / catálogo
│
├── enrolments.length === 1
│ └── Auto-seleciona como CONTEXT ativo
│
├── enrolments.length > 1
│ └── Menu de seleção de produto (CONTEXT)
│ O Aluno escolhe qual produto quer acessar
│
└── Para o enrolment selecionado (CONTEXT):
│
├── onboarding.completed === false
│ └── Redireciona para Onboarding (UC-003)
│
├── student_plan.status === null
│ └── Processando... (Primeiro Acesso em andamento)
│
├── student_plan.status === "not_started"
│ └── Área do Aluno (estado inicial)
│
├── student_plan.status === "active"
│ └── Área do Aluno
│
├── student_plan.status === "blocked"
│ └── Área do Aluno com aviso de bloqueio
│ Causa: ver Causa de Bloqueio do Plano do Aluno
│
├── student_plan.status === "interrupted"
│ └── Tela de interrupção (ex: matrícula suspensa)
│
├── student_plan.status === "completed"
│ └── Tela de conclusão (certificado se disponível)
│
└── student_plan.status === "closed"
└── Tela de encerramentoContexto de Produto no Frontend
O Frontend mantém um CONTEXT com o produto ativo. Regras:
- Apenas 1 produto ativo por vez no CONTEXT
- Aluno pode trocar de produto via menu de contexto
- Ao trocar, Frontend recarrega dados do novo enrolment
- O CONTEXT determina qual Trilha/Plano/Roteiro é exibido
Erros esperados
| HTTP | Código | Situação |
|---|---|---|
| 401 | unauthorized |
Token inválido ou expirado |
| 403 | forbidden |
Usuário não tem permissão |
Decisões
- D-01:
userembutido na resposta de enrolments para evitar /me separado no boot - D-02: Onboarding é per-enrolment (cada inscrição tem seu estado de onboarding)
- D-03:
productetrailcomo objetos aninhados (não só IDs) — Frontend não precisa resolver - D-04:
student_plan.statussegue os 6 estados canônicos do term “Status do Plano do Aluno” - D-05:
status=activecomo default — Frontend normalmente quer só inscrições ativas - D-06: Certificado é opcional (não modelado ainda) —
completedpode levar a tela genérica de conclusão