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.popupaqui (valor: timestamp). Matrículas marcadas antes continuam valendo pelo itemmetaretrospective_popup_shown_at, lido como fallback.