Skip to content

UC-003: Onboarding do Aluno

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/json

Recebe 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ógica

Regras de fase:

  • Onboarding Geral sempre existe
  • Complemento só existe se a Trilha exigir (complement_required: true em 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ído
  • first_access: true → Plano do Aluno foi criado neste momento
  • redirect: "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 Aluno

Mapeamento 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_quantity como tipo para perguntas do tipo “já prestei X vezes”
Navigation

Type to search…

↑↓ navigate↵ selectEsc close