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-hoursouprofile) 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)
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
- autenticacao.md
- openapi.yaml
- Postman — pasta 2. Onboarding
- UC-003
- ref-30-e — contract specifications
- Source:
classes/extensions/platform/controller/onboarding_api_controller.php - Plano: 2026-05-04-platform-api-docs-improvement