Skip to content

Contrato — Onboarding (questionário)

Contrato — Onboarding (questionário)

Status: EM REVISÃO (qualidade lake) Termos: Onboarding, Onboarding Geral, Complemento de Onboarding do Curso-Produto, Questionário de Perfil, Disponibilidade Semanal de Estudo, Primeiro Acesso, Plano do Aluno Controller: classes/extensions/platform/controller/onboarding_api_controller.php Service: classes/extensions/engine/onboarding/contract/onboarding_service_interface.php UC: UC-003 — Onboarding do Aluno

Visão geral

O Onboarding é um questionário configurável. O Backend define os steps (perguntas, tipos de input, opções, validações). O Frontend renderiza genericamente — não hardcoda steps.

Existem duas fases:

Fase Quando
general Primeira fase, comum a todos os Curso-Produto
complement Complemento específico do Curso-Produto, após o general

O Aluno completa as fases em sequência. Ao concluir a última fase aplicável, o Backend dispara a criação assíncrona do Plano do Aluno.

Endpoints

Método Path Função
GET /api/v1/platform/onboarding/{enrolment_id} Configuração dos steps da fase atual
POST /api/v1/platform/onboarding/{enrolment_id}/submit Envia respostas e conclui a fase
PUT /api/v1/platform/onboarding/{enrolment_id}/weekly-hours Altera só a Disponibilidade Semanal de Estudo
PUT /api/v1/platform/onboarding/{enrolment_id}/profile Edita o Questionário de Perfil inteiro
GET /api/v1/platform/onboarding/{enrolment_id}/weekly-hours/history Histórico de alterações da carga (de → para)

Todos exigem Authorization: Bearer {wstoken} (ou ?wstoken=).

Disponibilidade Semanal no meio do curso. Em Trilha de Tipo de Módulo Dinâmico, alterar a carga (via weekly-hours ou profile) afeta apenas os Módulos futuros — cada Módulo é dimensionado quando é gerado (ao concluir o anterior), lendo o valor vigente. O Módulo atual e os concluídos não mudam. Ver termo Disponibilidade Semanal de Estudo.

GET /onboarding/{enrolment_id}

Retorna a configuração da fase pendente para a matrícula. Se já estiver concluído, retorna 409.

Path params

Param Tipo Descrição
enrolment_id integer ID da Matrícula do Aluno

Response 200

{
  "enrolment_id": 42,
  "phase": "general",
  "completed": false,
  "steps": [
    {
      "key": "weekly_hours",
      "type": "question",
      "title": "Quantas horas por semana você consegue estudar?",
      "subtitle": null,
      "description": null,
      "hint": "Você pode ajustar depois.",
      "input": {
        "type": "slider",
        "min": 5,
        "max": 60,
        "step": 5,
        "unit": "horas/semana"
      }
    },
    {
      "key": "areas_of_interest",
      "type": "question",
      "title": "Áreas de interesse",
      "input": {
        "type": "multi_select",
        "max_selections": 3,
        "options": [
          { "value": "constitucional", "label": "Direito Constitucional" },
          { "value": "penal", "label": "Direito Penal" },
          { "value": "civil", "label": "Direito Civil" }
        ]
      }
    },
    {
      "key": "experience",
      "type": "question",
      "title": "Você já estudou para concursos antes?",
      "input": {
        "type": "single_select",
        "options": [
          { "value": "no", "label": "Não" },
          {
            "value": "yes",
            "label_template": "Sim, há {years} {years_unit}",
            "inputs": [
              {
                "key": "years",
                "type": "integer",
                "min": 0,
                "max": 30,
                "placeholder": "0",
                "required": true
              },
              {
                "key": "years_unit",
                "type": "text",
                "placeholder": "anos",
                "required": false
              }
            ]
          }
        ]
      }
    }
  ]
}

Schema do step

Campo Tipo Obrigatório Descrição
key string Sim Identificador semântico do step (estável entre versões)
type info | question Sim info é só descritivo (sem input). question exige resposta
title string Sim Título principal
subtitle string|null Não Subtítulo
description string|null Não Texto descritivo (Markdown permitido)
hint string|null Não Dica curta abaixo do input
action string|null Não Para steps info, label de botão (ex: “Avançar”)
input objeto Sim em question Configuração do input (ver abaixo)

Tipos de input

slider

{
  "type": "slider",
  "min": 5,
  "max": 60,
  "step": 5,
  "unit": "horas/semana"
}

Valor coletado é number.

single_select / multi_select

{
  "type": "single_select",
  "max_selections": 1,
  "options": [
    { "value": "<key>", "label": "<texto plano>" }
  ]
}

multi_select aceita max_selections > 1.

Inputs embarcados em opções (label_template + inputs)

Uma option pode declarar label_template com placeholders {key} e um array inputs[]. O Frontend renderiza inputs inline na posição do placeholder, em qualquer ponto da frase.

{
  "value": "yes",
  "label_template": "Sim, há {years} {years_unit}",
  "inputs": [
    { "key": "years", "type": "integer", "min": 0, "max": 30, "required": true },
    { "key": "years_unit", "type": "text", "placeholder": "anos", "required": false }
  ]
}

Renderização do exemplo:

[ ] Sim, há [____] [____]

Onde os colchetes [____] são inputs reais. Frontend coleta valores e envia em value.inputs ao submeter.

type em inputs[] Descrição
text Texto livre (string)
integer Inteiro com min/max opcionais

Erros

HTTP error Causa
401 unauthorized wstoken inválido/ausente
404 enrolment_not_found Matrícula não existe ou não pertence ao usuário
409 onboarding_already_completed Onboarding já completo para esta matrícula

POST /onboarding/{enrolment_id}/submit

Recebe respostas e conclui a fase atual. Pode resultar em:

  • avanço para a próxima fase (general → complement),
  • conclusão total (último submit), iniciando criação assíncrona do Plano do Aluno.

Request body

{
  "answers": [
    { "key": "weekly_hours",       "value": 25 },
    { "key": "areas_of_interest",  "value": ["constitucional", "penal"] },
    { "key": "experience",         "value": { "option": "yes", "inputs": { "years": 3, "years_unit": "anos" } } }
  ]
}

Forma do value em answers[]

A forma é heterogênea conforme input.type do step:

input.type Forma do value
slider number — ex: 25
single_select (sem inputs embarcados) string (a value da option) — ex: "no"
single_select (com inputs embarcados) { option: string, inputs: { <inputkey>: <value> } }
multi_select (sem inputs embarcados) string[] — ex: ["constitucional", "penal"]
multi_select (com inputs embarcados) Array<{ option, inputs }>

A ordem dos itens em answers[] não importa — o Backend resolve pelo key.

Response 200 (não-final)

Submetendo a fase general quando ainda existe complement:

{
  "success": true,
  "phase_completed": "general",
  "next_phase": "complement",
  "onboarding_completed": false,
  "first_access": false,
  "student_plan": null,
  "redirect": null
}

Response 200 (final — conclusão de onboarding)

Submetendo a última fase aplicável:

{
  "success": true,
  "phase_completed": "complement",
  "next_phase": null,
  "onboarding_completed": true,
  "first_access": false,
  "student_plan": {
    "id": null,
    "status": "creating"
  },
  "redirect": null
}
Campo Tipo Descrição
success boolean Sempre true (erros usam HTTP 4xx)
phase_completed general|complement Fase recém-concluída
next_phase complement|null Fase seguinte (null se acabou)
onboarding_completed boolean true se foi a última fase
first_access boolean Sempre false no response. O first_access conceitual ocorre quando o handler async cria o Plano do Aluno
student_plan objeto|null Estado provisório do Plano. Ver tabela abaixo
student_plan.id integer|null null enquanto o handler async não cria
student_plan.status creating|active|failed Estado do plano
redirect string|null Rota sugerida para Frontend (raramente usada)

Fluxo assíncrono pós-conclusão

Frontend                Backend                  Engine/Plan handler
   |                       |                              |
   |--- POST submit ------>|                              |
   |                       |  emite                       |
   |                       |  onboarding_completed_signal-|
   |<-- 200 {creating} ----|                              |
   |                       |                              |
   |  (poll /enrolments)   |                              |
   |                       |                              |
   |                       |             #[async_on]      |
   |                       |<--- create_for_enrolment ----|
   |                       |  cria student_plan           |
   |                       |                              |
   |--- GET /enrolments -->|                              |
   |<-- {active}, id:42 ---|                              |

Polling (P1)

Ver autenticacao.md#polling.

Erros

HTTP error Causa
401 unauthorized wstoken inválido/ausente
404 enrolment_not_found Matrícula não existe ou não pertence ao usuário
409 onboarding_already_completed Submit em fase já concluída
422 validation_error Respostas incompletas/fora de schema/fora dos limites. Inclui errors[]

Detalhe do 422

{
  "error": "validation_error",
  "message": "Respostas inválidas.",
  "errors": [
    { "step_key": "weekly_hours", "field": null, "message": "Valor 100 fora do range [5, 60]." },
    { "step_key": "areas_of_interest", "field": null, "message": "Selecione no máximo 3 opções." },
    { "step_key": "experience", "field": "years", "message": "Campo obrigatório." }
  ]
}

PUT /onboarding/{enrolment_id}/weekly-hours

Altera somente a Disponibilidade Semanal de Estudo, sem reenviar o Questionário. Valida contra a faixa do step slider (min/max do Produto). Grava no Questionário de Perfil e denormaliza no Plano do Aluno (síncrono): o próximo Módulo materializado já usa o valor novo.

Request body

{ "weekly_hours": 35 }

Response 200

{
  "success": true,
  "weekly_hours": 35,
  "student_plan_updated": true
}

student_plan_updated é false quando ainda não há Plano do Aluno (Onboarding não concluído) — o valor fica gravado no Questionário.

Erros

Código error Quando
404 enrolment_not_found Matrícula/Questionário inexistente ou de outro usuário
422 validation_error weekly_hours fora da faixa do slider do Produto

PUT /onboarding/{enrolment_id}/profile

Edita o Questionário de Perfil inteiro (reabertura do Onboarding). Envia o answers[] completo da fase geral — mesmo formato e validação do submit. Grava o perfil e denormaliza weekly_hours no Plano do Aluno. Não altera as flags de conclusão do Onboarding.

Request body

{
  "answers": [
    { "key": "step1",        "value": ["promotor", "juiz"] },
    { "key": "step3",        "value": "PasseiMasNaoAvancei" },
    { "key": "weekly_hours", "value": 35 }
  ]
}

Response 200

{ "success": true, "weekly_hours": 35, "student_plan_updated": true }

Erros idênticos ao weekly-hours (404 / 422).

GET /onboarding/{enrolment_id}/weekly-hours/history

Histórico das alterações de carga (de → para), derivado das revisões imutáveis do Plano do Aluno. Da mais recente para a mais antiga. A primeira transição tem from: null (valor do Primeiro Acesso).

Response 200

{
  "enrolment_id": 42,
  "current": 35,
  "changes": [
    { "from": 15,   "to": 35, "changed_at": 1717340400, "changed_by": 71, "revision": 3 },
    { "from": null, "to": 15, "changed_at": 1717000000, "changed_by": 71, "revision": 1 }
  ]
}

Erros

Código error Quando
404 student_plan_not_found Não há Plano do Aluno para a Matrícula

Estados do Onboarding

                    POST /onboarding/{id}/submit (general)
                    │
                    v
   [pending_general] ──────────► [pending_complement] ──────────► [completed]
        │                              │                              │
        │ GET 200                      │ GET 200                      │ GET 409
        │ steps general                │ steps complement             │ already_completed
        v                              v                              v
       ...                            ...                            ...

Idempotência (T2 — pendente implementação engine)

Submit duplicado da mesma fase (duplo-clique, retry de rede) deve ser idempotente: backend retorna mesmo payload, signal emitido uma única vez.

Estado atual: idempotência não garantida. Frontend deve evitar duplo-submit client-side enquanto a implementação backend não sobe.

Async failure (T3 — pendente implementação engine)

Quando o handler async falha em criar o student_plan:

{
  "id": null,
  "status": "failed",
  "error_message": "Falha ao montar a Trilha. Por favor, tente novamente."
}

Frontend mostra erro + botão “Tentar de novo” (re-emit signal sem reapresentar questionário).

Estado atual: T3 não implementado. Frontend pode entrar em loop de polling se handler falhar — usar timeout client-side de 60 tentativas como fallback.

Pendências

ID Descrição Bloqueia
T2 Idempotência de submit (lock por enrolment_id no engine onboarding) Não — workaround client-side
T3 student_plan.status='failed' + retry button Não — fallback timeout client
B-pend-2 Async student_plan creation: dead letter / retry / alerta operacional Não — observabilidade ops

Referências

Navigation

Type to search…

↑↓ navigate↵ selectEsc close