Skip to content

Contrato — Estado de Interface do Aluno

Contrato — Estado de Interface do Aluno

Status: Em implementação Controller: user_state_api_controller Tabela: helico_user_state

Guarda, por Aluno, o estado de interface que deve valer em qualquer navegador: marcas de “já visto” (modais, popups, toasts) e, no futuro, filtros e preferências lembrados. É estado de interface, não dado pedagógico: progresso, respostas e conclusão continuam nas tabelas de domínio.

Escopo

enrolment_id Vale para
omitido ou null o Aluno em qualquer Matrícula (escopo global)
id da Matrícula só aquela Matrícula (o id do item enrolment)

O userid vem sempre do usuário autenticado; o cliente nunca o envia. Uma Matrícula de outro Aluno responde 404 enrolment_not_found.

Chaves

Formato: prefixo aceito seguido de segmentos separados por ponto, ^(seen|filter|pref)(\.[A-Za-z0-9_-]+)+$, até 191 caracteres. Um segmento m{flowId} (id numérico do fluxo/módulo) marca a chave como presa a um módulo.

Prefixo Uso
seen. marca de “já visto” (valor 1)
filter. filtro lembrado
pref. preferência do Aluno

Valores: string, inteiro ou booleano (true/false viram "1"/"0"), até 1000 caracteres. null, listas e objetos são rejeitados. Até 200 itens por chamada.

GET /platform/user-state

Query Tipo Descrição
enrolment_id inteiro > 0, opcional Matrícula. Sem ele, só o escopo global
prefix seen. | filter. | pref., opcional Filtra as duas listas
{
  "global": { "seen.faq_video.12": "1" },
  "enrolment": { "seen.roteiro.welcome": "1" }
}

enrolment é null quando enrolment_id não foi enviado. Como nas demais rotas da plataforma, toda resposta 200 também traz "success": true (omitido nos exemplos).

POST /platform/user-state

Idempotente. Regravar uma chave atualiza a mesma linha; um valor igual ao atual não conta em written.

{
  "enrolment_id": 53394,
  "items": { "seen.roteiro.new_activities.m76137": "1" },
  "remove": ["filter.desempenho.discipline"],
  "current_module": "76137"
}
Campo Tipo Descrição
enrolment_id inteiro > 0 ou null null grava no escopo global
items objeto chave → valor chaves a gravar
remove lista de chaves, opcional chaves a apagar; não pode repetir uma chave de items
current_module string de dígitos, opcional exige enrolment_id; apaga as chaves seen.* com m{flowId} diferente deste. Chaves sem módulo e o escopo global não são tocados

Resposta 200:

{ "written": 1, "removed": 0, "pruned": 3 }

Erros

HTTP error Quando
401 unauthorized sem usuário autenticado
404 enrolment_not_found Matrícula inexistente ou de outro Aluno
422 invalid_user_state corpo malformado, prefixo/chave/valor inválido, itens demais, current_module sem matrícula

Ciclo de vida

  • Reset de Matrícula apaga as chaves daquela Matrícula (enrolment_reset_listener_service). As do escopo global ficam.
  • A retrospectiva grava seen.retrospective.popup aqui (valor: timestamp). Matrículas marcadas antes continuam valendo pelo itemmeta retrospective_popup_shown_at, lido como fallback.
Navigation

Type to search…

↑↓ navigate↵ selectEsc close