UC-003: Onboarding do Aluno
Status: EM REVISÃO Data: 2026-04-29 Domínio: platform / engine.onboarding Ator: Aluno Terms: Onboarding, Onboarding Geral, Complemento de Onboarding do Curso-Produto, Questionário de Perfil, Disponibilidade Semanal de Estudo, Primeiro Acesso, Plano do Aluno
Contexto
Após UC-002 (Inscrições do Aluno) identificar que o Aluno tem onboarding pendente para uma inscrição, o Frontend redireciona para o fluxo de Onboarding. O Onboarding é um questionário configurável definido pelo Backend, com duas fases possíveis: Onboarding Geral (compartilhado) e Complemento do Curso-Produto (específico).
IMPORTANTE: O Frontend NÃO deve hardcodar os steps do Onboarding. Toda a estrutura (steps, perguntas, tipos de input, opções) vem da API via GET. O Frontend é um renderizador genérico de formulário com base no input.type de cada step. Isso permite que diferentes Produtos/Trilhas tenham onboardings diferentes sem deploy de Frontend.
Endpoints
GET — Configuração do Onboarding
GET /platform/onboarding/{enrolment_id}
Authorization: Bearer {wstoken}Retorna a configuração dos steps e perguntas para a fase pendente do Onboarding.
POST — Envio das Respostas
POST /platform/onboarding/{enrolment_id}/submit
Authorization: Bearer {wstoken}
Content-Type: application/jsonRecebe as respostas do Aluno e marca a fase como concluída.
Estrutura: Fases do Onboarding
Conforme terms, o Onboarding tem duas camadas:
Onboarding
├── Onboarding Geral (phase: "general")
│ ├── Boas-vindas (type: info)
│ ├── Questionário de Perfil (type: question, vários steps)
│ ├── Disponibilidade Semanal de Estudo (type: question, slider)
│ └── Finalização (type: info, action: submit)
│
└── Complemento do Curso-Produto (phase: "complement")
└── Steps específicos definidos pela Trilha PedagógicaRegras de fase:
- Onboarding Geral sempre existe
- Complemento só existe se a Trilha exigir (
complement_required: trueem UC-002) - Primeiro Acesso só ocorre quando AMBAS as fases (geral + complemento se exigido) estiverem concluídas
- Primeiro Acesso dispara criação do Plano do Aluno
Resposta GET — Exemplo Onboarding Geral
{
"enrolment_id": 101,
"phase": "general",
"completed": false,
"steps": [
{
"key": "welcome",
"type": "info",
"title": "Bem-vindo",
"description": "Responda algumas perguntas para nós te conhecermos melhor!"
},
{
"key": "careers",
"type": "question",
"title": "Quais carreiras você pretende seguir?",
"subtitle": "Vamos criar um plano de estudo personalizado para você",
"input": {
"type": "multi_select",
"max_selections": 2,
"options": [
{ "value": "promotor", "label": "Promotor(a) de Justiça", "icon": "briefcase" },
{ "value": "analista_mp", "label": "Analista do MP", "icon": "search" },
{ "value": "juiz", "label": "Juiz(a)", "icon": "library" },
{ "value": "delegado", "label": "Delegado(a)", "icon": "shield" },
{ "value": "defensor", "label": "Defensor(a) Pública", "icon": "scale" },
{ "value": "outro", "label": "Outro", "icon": "refresh" }
]
}
},
{
"key": "exam_history",
"type": "question",
"title": "Já prestou esse concurso antes?",
"subtitle": "Vamos criar um plano de estudo personalizado para você",
"input": {
"type": "single_select_with_quantity",
"options": [
{ "value": "never", "label": "Nunca prestei" },
{ "value": "yes", "label": "Já prestei", "quantity_field": true }
]
}
},
{
"key": "second_phase",
"type": "question",
"title": "Já passou para alguma segunda fase?",
"subtitle": "Vamos criar um plano de estudo personalizado para você",
"input": {
"type": "single_select",
"options": [
{ "value": "yes", "label": "Sim" },
{ "value": "no", "label": "Não" }
]
}
},
{
"key": "difficulty_phase",
"type": "question",
"title": "Em qual fase você possui mais dificuldade?",
"subtitle": "Vamos criar um plano de estudo personalizado para você",
"input": {
"type": "single_select",
"options": [
{ "value": "primeira_fase", "label": "Primeira fase" },
{ "value": "segunda_fase", "label": "Segunda fase" },
{ "value": "ambas", "label": "Ambas" }
]
}
},
{
"key": "prep_time",
"type": "question",
"title": "Há quanto tempo já está em preparação?",
"subtitle": "Vamos criar um plano de estudo personalizado para você",
"input": {
"type": "single_select",
"options": [
{ "value": "menos_6m", "label": "Menos de 6 meses" },
{ "value": "6m_1a", "label": "6 meses a 1 ano" },
{ "value": "1a_2a", "label": "1 a 2 anos" },
{ "value": "2a_5a", "label": "2 a 5 anos" },
{ "value": "mais_5a", "label": "Mais de 5 anos" }
]
}
},
{
"key": "weekly_hours",
"type": "question",
"title": "Quantas horas você pretende estudar por semana?",
"subtitle": "Vamos criar um roteiro de estudo personalizado para você",
"input": {
"type": "slider",
"min": 5,
"max": 60,
"step": 5,
"unit": "horas"
},
"hint": "Não se preocupe, você pode ajustar as horas semanais quando precisar."
},
{
"key": "finish",
"type": "info",
"title": "Vamos começar!",
"action": "submit"
}
]
}Request POST — Envio das respostas
{
"answers": [
{ "key": "careers", "value": ["promotor", "juiz"] },
{ "key": "exam_history", "value": { "option": "yes", "quantity": 3 } },
{ "key": "second_phase", "value": "no" },
{ "key": "difficulty_phase", "value": "primeira_fase" },
{ "key": "prep_time", "value": "1a_2a" },
{ "key": "weekly_hours", "value": 25 }
]
}Resposta POST — Sucesso
{
"success": true,
"phase_completed": "general",
"next_phase": null,
"onboarding_completed": true,
"first_access": true,
"student_plan": {
"id": 500,
"status": "not_started"
},
"redirect": "student_area"
}Cenários de resposta:
next_phase: "complement"→ Frontend redireciona para fase de complemento (novo GET)next_phase: null+onboarding_completed: true→ Onboarding concluídofirst_access: true→ Plano do Aluno foi criado neste momentoredirect: "student_area"→ Frontend vai para Área do Aluno
Tipos de Input
O Backend define o tipo de input. O Frontend renderiza com base no input.type:
input.type |
Descrição | Valor retornado |
|---|---|---|
multi_select |
Múltipla escolha com limite | string[] |
single_select |
Escolha única | string |
single_select_with_quantity |
Escolha única com campo numérico opcional | { option: string, quantity?: number } |
slider |
Valor numérico em faixa | number |
Tipos futuros possíveis: text, date, checkbox, rating.
Fluxo completo
UC-002 identifica onboarding pendente
│
▼
GET /platform/onboarding/{enrolment_id}
│ → Retorna phase: "general" + steps
│
▼
Frontend renderiza steps sequencialmente
│ → Aluno responde pergunta por pergunta
│
▼
POST /platform/onboarding/{enrolment_id}/submit
│ → Backend salva respostas (Questionário de Perfil + Disponibilidade Semanal)
│
├── next_phase: "complement"
│ └── GET /platform/onboarding/{enrolment_id}
│ → Retorna phase: "complement" + steps específicos
│ → POST /platform/onboarding/{enrolment_id}/submit
│
└── next_phase: null (concluído)
│
├── Backend marca Onboarding como concluído
├── Backend dispara Primeiro Acesso
├── Backend cria Plano do Aluno (vincula Matrícula ao Plano de Estudo vigente)
│
└── Frontend redireciona para Área do AlunoMapeamento term → persistência
| Dado | Term | Persistência atual | Persistência alvo |
|---|---|---|---|
| Respostas do perfil | Questionário de Perfil | helico_onboarding (flat, per-user) |
Per-enrolment, JSON em metadata |
| Carga horária | Disponibilidade Semanal de Estudo | studytime em metadata |
weekly_hours em metadata |
| Onboarding concluído | Primeiro Acesso | user_has_onboarding() (bool per-user) |
Flag per-enrolment + evento |
| Plano do Aluno | Plano do Aluno | Não implementado | Criação automática no Primeiro Acesso |
Erros esperados
| HTTP | Código | Situação |
|---|---|---|
| 401 | unauthorized |
Token inválido ou expirado |
| 404 | enrolment_not_found |
Inscrição não existe ou não pertence ao usuário |
| 409 | onboarding_already_completed |
Onboarding já foi concluído para esta inscrição |
| 422 | validation_error |
Respostas incompletas ou fora do formato esperado |
Decisões
- D-01: Onboarding é per-enrolment, não per-user (cada inscrição tem seu Onboarding)
- D-02: Backend define os steps e tipos de input — Frontend renderiza genericamente
- D-03: Duas fases: Onboarding Geral (sempre) + Complemento (quando exigido pela Trilha)
- D-04: Keys semânticas nos steps (
careers,weekly_hours) mas transporte genérico (answers[]) - D-05: Primeiro Acesso e criação do Plano do Aluno acontecem no submit da última fase
- D-06: Steps info (welcome, finish) não geram resposta — são navegação pura
- D-07:
single_select_with_quantitycomo tipo para perguntas do tipo “já prestei X vezes”