Plano: helico_user_state — estado de UI do Aluno entre navegadores
Status: IMPLEMENTADO (backend + app), sem commit. Data: 2026-10-07.
Branch: feat/user-state-modais-popups (plugin e app), a partir de origin/main.
Estado da implementação
Feito: tabela + upgrade (step 2026100703; versão estampada pelo CI), domínio engine/user_state, camada platform
(DTOs, view service, controller GET/POST com remove), cascata do reset, retrospectiva em
seen.retrospective.popup com fallback ao itemmeta, contrato contratos/user-state.md; no
app: proxy Next, cliente, keys.ts, legacy-storage.ts, UserStateService, provider e
hooks, migração dos 8 itens, regra de ESLint e teste-guarda.
Não feito (decisões suas pendentes): privacy provider (decisão 5); dica do flashcard
(decisão 1); marcar como vistos os toasts já concluídos no deploy (decisão 2). openapi.yaml
não regenerado: o script build:openapi do composer.json aponta para um
../middag/cli/build.php que não existe mais. Release 2 (remover legacy-storage.ts) fica
para depois de estável.
Correção ao desenho original (achado na implementação)
modulo.id em useModules é o id da disciplina, não do fluxo, e data só traz os slots
do /study atual. Logo o toast já avalia só o módulo atual e a chave usa o fluxo atual
(activeCourse.currentModule), como a chave antiga.
0. Problema e escopo
Modais, popups e toasts de “mostrar uma vez” guardam o “já visto” só no
localStorage/sessionStorage do navegador. Em outro navegador, aba anônima ou storage
limpo eles reaparecem. Só a retrospectiva tem “visto” no backend.
Dentro do escopo: marcas seen.* dos modais/toasts migráveis (seção 6). A tabela já aceita
filter.* e pref.* (filtros e preferências do Aluno), mas nenhum consumidor deles entra
nesta entrega.
Fora do escopo: estado de domínio (progresso, respostas), caches, rascunhos, handoffs de uma navegação, modais de confirmação, tooltips.
Achados que condicionam o desenho
currentModuleno app é o id do fluxo (ex.: 46974), não a ordem do módulo. As chaves usamm{flowId}. Poda por “diferente do atual”, nunca “menor que”.- A chave do toast leva o módulo do item (
modulo.id), e o efeito só avalia itens do módulo atual (hoje percorredatacom o escopo do módulo atual: risco de rajada ao avançar). Confirmar o queuseModulesdevolve antes de migrar. - Id do toast =
slot.id(UUID). - O reset de matrícula já tem cascata (
enrolment_reset_listener_service). - API REST em
api/v1/platform/...(controller Symfony,deny_if_not_owned), proxy Next por arquivo (app/api/helico/platform/<área>/route.ts). - O plugin não tem privacy provider nem handler de exclusão de usuário hoje.
1. Tabela helico_user_state
Padrão helico_response: descritor #[Table] em classes/base/persistence/schema/,
registro em dedicated_schema, bloco em db/install.xml, teste de drift em schema_test.
| Coluna | XMLDB | Postgres | Nulo | Default | Descrição |
|---|---|---|---|---|---|
id |
int(10) sequence |
integer (identity) |
não | — | PK |
userid |
int(10) |
integer |
não | — | Aluno. Sem FK (decisão); integridade no código |
helicoenrolmentid |
int(10) |
integer |
não | 0 |
id do helico_items type enrolment; 0 = vale para o Aluno em qualquer matrícula |
statekey |
char(191) |
varchar(191) |
não | — | chave pontuada com prefixo (seção 6) |
statevalue |
text |
text |
sim | NULL |
valor escalar (string). Marcas “visto” gravam "1". Limite de 1000 caracteres aplicado no service |
timecreated |
int(10) |
integer |
não | 0 |
convenção Moodle |
timemodified |
int(10) |
integer |
não | 0 |
convenção Moodle |
Chaves e índices:
| Nome | Tipo | Campos | Uso |
|---|---|---|---|
primary |
PK | id |
|
userenrolmentkey |
UNIQUE | userid, helicoenrolmentid, statekey |
upsert idempotente; leitura por escopo |
helicoenrolmentid |
INDEX | helicoenrolmentid |
apagar por matrícula (reset) |
Regras: helicoenrolmentid é NOT NULL DEFAULT 0 (no Postgres NULL não colide em índice
único, o que duplicaria a linha global). Sem JSON: um valor escalar por linha.
Descritor (esboço):
#[Table('helico_user_state', comment: 'HELICO - Per-student UI state remembered across browsers (seen flags, filters); one scalar value per key')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('userid', 'int', length: 10, notnull: true, comment: 'The student (no foreign key on purpose)')]
#[Column('helicoenrolmentid', 'int', length: 10, notnull: true, default: 0, comment: 'helico_items id of the enrolment; 0 = student-wide')]
#[Column('statekey', 'char', length: 191, notnull: true, comment: 'Dotted key, e.g. seen.toast.m46974.<slot uuid>')]
#[Column('statevalue', 'text', notnull: false, comment: 'Scalar value; seen flags store 1')]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('userenrolmentkey', ['userid', 'helicoenrolmentid', 'statekey'], unique: true)]
#[Index('helicoenrolmentid', ['helicoenrolmentid'])]
final class user_state_table {}Upgrade: step < 2026100703 cria a tabela de install.xml
(install_one_table_from_xmldb_file), mesmo padrão dos steps anteriores. O version.php
não é tocado no PR: o job stamp-version do release.yml estampa $plugin->version na
Release PR (data do dia, sempre acima da atual). O step usa 2026100703 porque a main já
está em 2026100702; a versão estampada no próximo release será maior que isso.
2. Classes (backend)
Namespace local_helico\extensions\engine\user_state\{kind} (ADR-23). Idioma: código e
docblocks em inglês (CLAUDE.md do plugin).
2.1 Domínio engine/user_state/
| Arquivo | Classe | Responsabilidade |
|---|---|---|
entity/user_state.php |
user_state extends AbstractEntity |
Uma linha. Construtor com uma propriedade por coluna (padrão response). Constante GLOBAL_SCOPE = 0 |
mapper/user_state_mapper.php |
final user_state_mapper extends entity_mapper |
Linha ↔ entidade |
repository/user_state_repository.php |
final user_state_repository extends dedicated_table_repository<user_state> |
Acesso à tabela |
contract/user_state_service_interface.php |
interface | Contrato do domínio |
service/user_state_service.php |
user_state_service |
Validação, upsert, poda |
support/user_state_key.php |
final user_state_key |
Constantes/builders de chave usados pelo backend (ex.: RETROSPECTIVE_POPUP) e whitelist de prefixos |
exception/invalid_user_state_exception.php |
final … implements http_aware_exception |
422 invalid_user_state |
user_state (getters): getId(): ?int, get_user_id(): int, get_helico_enrolment_id(): int,
get_state_key(): string, get_state_value(): ?string, getTimecreated(): int,
getTimemodified(): int, toArray(): array.
user_state_repository:
/** @return array<string, user_state> keyed by statekey */
public function find_by_scope(int $user_id, int $helico_enrolment_id): array;
/** @param array<string, string> $items statekey => value; @return int rows written */
public function upsert_many(int $user_id, int $helico_enrolment_id, array $items): int;
/** @param int[] $ids */
public function delete_by_ids(array $ids): void;
public function delete_by_enrolment(int $helico_enrolment_id): void;
public function delete_by_user(int $user_id): void;upsert_many: lê o escopo, insere só as chaves novas (insert_many), atualiza as que mudaram
e ignora as iguais. Em corrida (violação do índice único) cai para insert/update linha a linha.
user_state_service_interface / user_state_service:
/** @return array<string, string> */
public function get_scope(int $user_id, int $helico_enrolment_id, ?string $prefix = null): array;
/** @param array<string, string> $items; @return int rows written; @throws invalid_user_state_exception */
public function set_many(int $user_id, int $helico_enrolment_id, array $items): int;
/** Removes `seen.*` keys tied to a module (`.m{digits}` segment) other than $keep_module. @return int rows deleted */
public function prune_module_scoped(int $user_id, int $helico_enrolment_id, string $keep_module): int;
public function delete_by_enrolment(int $helico_enrolment_id): void;
public function delete_by_user(int $user_id): void;Validação em set_many (tudo ou nada: qualquer item inválido rejeita a chamada inteira):
| Regra | Valor |
|---|---|
| Formato da chave | ^(seen|filter|pref)(\.[A-Za-z0-9_\-]+)+$ |
| Tamanho da chave | ≤ 191 |
| Tipo do valor | string, inteiro ou booleano (bool vira "1"/"0"); null, array e objeto rejeitados |
| Tamanho do valor | ≤ 1000 |
| Itens por chamada | ≤ 200 |
| Poda | só chaves seen. com segmento .m(\d+) (regex \.m(\d+)(?:\.|$)) diferente de $keep_module |
2.2 Camada platform/ (gateway)
| Arquivo | Classe | Responsabilidade |
|---|---|---|
platform/dto/user_state_view_dto.php |
final readonly user_state_view_dto |
Resposta do GET |
platform/dto/user_state_save_request_dto.php |
final readonly user_state_save_request_dto |
Corpo do POST, já validado em forma |
platform/dto/user_state_save_result_dto.php |
final readonly user_state_save_result_dto |
Resposta do POST |
platform/contract/user_state_view_service_interface.php |
interface | Orquestra leitura/gravação para a API |
platform/service/user_state_view_service.php |
user_state_view_service |
Chama user_state_service; aplica poda; monta DTO |
platform/controller/user_state_api_controller.php |
user_state_api_controller extends platform_api_controller |
Rotas HTTP |
DTOs (padrão retrospective_view_dto: final readonly, to_array()):
final readonly class user_state_view_dto
{
/** @param array<string,string> $global; @param null|array<string,string> $enrolment */
public function __construct(public array $global, public ?array $enrolment) {}
public function to_array(): array { return ['global' => $this->global, 'enrolment' => $this->enrolment]; }
}
final readonly class user_state_save_request_dto
{
/** @param array<string,string|int|bool> $items */
public function __construct(
public ?int $enrolment_id,
public array $items,
public ?string $current_module,
) {}
/** @throws invalid_user_state_exception when the payload shape is wrong */
public static function from_payload(mixed $payload): self;
}
final readonly class user_state_save_result_dto
{
public function __construct(public int $written, public int $pruned) {}
public function to_array(): array { return ['written' => $this->written, 'pruned' => $this->pruned]; }
}from_payload valida: corpo é objeto; items é objeto de pares; enrolment_id é inteiro > 0
ou null; current_module é string de dígitos e só vale com enrolment_id informado.
user_state_view_service_interface:
public function get_view(int $user_id, ?int $enrolment_id, ?string $prefix): user_state_view_dto;
public function save(int $user_id, user_state_save_request_dto $request): user_state_save_result_dto;save: set_many(user, enrolment_id ?? 0, items); se current_module veio, prune_module_scoped
depois da gravação.
2.3 Alterações em código existente
| Arquivo | Mudança |
|---|---|
engine/retrospective/service/retrospective_ack_service.php |
Construtor ganha user_state_service_interface. mark_popup_shown grava seen.retrospective.popup (escopo da matrícula, userid = dono da matrícula). was_popup_shown consulta a tabela e, se não achar, cai no itemmeta retrospective_popup_shown_at. O alerta open_retrospective e o clique manual não mudam |
admin/listener/enrolment_reset_listener_service.php |
Novo passo: user_state_repository::delete_by_enrolment($enrolment_id) na cascata, dentro da transação |
classes/base/persistence/dedicated_schema.php |
user_state_table::class na lista |
db/install.xml, db/upgrade.php |
Tabela e step de upgrade (a versão é estampada pelo CI) |
tests/base/persistence/schema_test.php |
Lista de tabelas declaradas |
tests/.../retrospective_ack_service_test.php |
Construtor novo |
2.4 Privacidade e exclusão de usuário
O plugin hoje não tem privacy provider. Proposta: classes/privacy/provider.php cobrindo
apenas helico_user_state (metadata, contexto, exportar e apagar por usuário), usando
delete_by_user. Exclusão de usuário pelo evento do Moodle fica como item posterior (não há
handler no plugin). Ver decisão pendente 5.
3. API
Rotas em classes/extensions/platform/controller/user_state_api_controller.php,
BASE_PATH = 'api/v1/platform/user-state', autenticação por wstoken como as demais. O
userid vem sempre do usuário autenticado ($USER->id); o cliente nunca o envia.
3.1 GET /api/v1/platform/user-state
Nome da rota: helico_platform_user_state_get.
| Query | Tipo | Obrigatório | Descrição |
|---|---|---|---|
enrolment_id |
inteiro > 0 | não | Matrícula. Sem ele, só o escopo global |
prefix |
string | não | Um dos prefixos aceitos (seen., filter., pref.). Filtra as duas listas |
Resposta 200:
{
"global": { "seen.faq_video.12": "1" },
"enrolment": { "seen.roteiro.welcome": "1", "seen.toast.m76137.61857d52-…": "1" }
}enrolment é null quando não veio enrolment_id. Valores sempre string.
3.2 POST /api/v1/platform/user-state
Nome da rota: helico_platform_user_state_save. Idempotente.
Corpo:
{
"enrolment_id": 53394,
"items": { "seen.roteiro.new_activities.m76137": "1" },
"current_module": "76137"
}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
enrolment_id |
inteiro > 0 ou null |
sim | null grava no escopo global |
items |
objeto chave → valor |
sim | até 200 itens; regras da seção 2.1 |
current_module |
string de dígitos | não | só com enrolment_id. Apaga as chaves seen.* de módulo diferente deste |
Resposta 200: { "written": 1, "pruned": 0 }. written não conta chaves já iguais.
3.3 Erros (mesmo formato das demais rotas: { "error": "<code>" })
| HTTP | error |
Quando |
|---|---|---|
| 401 | unauthorized |
Sem usuário autenticado |
| 404 | enrolment_not_found |
enrolment_id inexistente ou de outro aluno (deny_if_not_owned) |
| 422 | invalid_user_state |
Prefixo/chave/valor inválidos, itens demais, corpo malformado, current_module sem matrícula |
3.4 Proxy Next (app-helico)
app/api/helico/platform/user-state/route.ts (GET e POST), padrão das rotas existentes
(getServerSession, callHelicoPlatformApi, resolvePlatformEnrolmentId,
mapPlatformError). O front fala ?enrolmentId= (camelCase, como o resto) e o proxy converte
para enrolment_id.
Documentação: atributos OpenAPI no controller (gera o openapi.yaml) e página de contrato em
docs/plataforma/api-integracoes/contratos/user-state.md.
4. Catálogo de chaves
Gramática: prefixo(.segmento)+, segmento [A-Za-z0-9_-]. m{flowId} = segmento de módulo
(flowId numérico, o currentModule do app).
| Chave | Escopo | Valor | Produtor (front) |
|---|---|---|---|
seen.roteiro.welcome |
matrícula | 1 |
roteiro-de-estudos/page.tsx |
seen.roteiro.new_activities.m{flowId} |
matrícula | 1 |
page.tsx |
seen.module_completion.m{flowId}.{exam_written|module_review} |
matrícula | 1 |
page.tsx |
seen.toast.m{flowId}.{slotUuid} |
matrícula | 1 |
RoteiroDeEstudosSections.tsx |
seen.flashcard.intro.m{flowId} |
matrícula | 1 |
modulo/flashcard/page.tsx |
seen.flashcard.all_done.m{flowId} |
matrícula | 1 |
modulo/flashcard/page.tsx |
seen.review_general.welcome.{rgNumber} |
matrícula | 1 |
modulo/revisao/page.tsx |
seen.faq_video.{videoId} |
global | 1 |
hooks/useWatchedVideos.ts |
seen.retrospective.popup |
matrícula | timestamp (string) | backend (retrospective_ack_service) |
Poda: só as chaves com segmento .m{digits} (as quatro primeiras linhas com módulo e as duas
de flashcard). Chaves sem módulo e as do escopo global nunca são podadas.
5. Front (app-helico): serviço estruturado de estado de UI
Hoje cada tela lê e grava localStorage por conta própria, com a chave montada na hora. O
plano substitui isso por uma camada única; nenhuma tela chama localStorage, fetch ou
monta chave de estado.
5.1 Camadas e arquivos
| Camada | Arquivo | Responsabilidade | Conhece React? |
|---|---|---|---|
| Transporte | lib/helico/api/platform-user-state.ts |
fetchUserState, saveUserState (padrão platform-*.ts, usa _shared.ts) e tipos do contrato |
não |
| Chaves | lib/helico/user-state/keys.ts |
Única fonte das chaves (catálogo da seção 4) e do escopo de cada uma | não |
| Armazenamento legado | lib/helico/user-state/legacy-storage.ts |
Lê/grava o localStorage antigo: write-through (Release 1), fallback (degraded) e semeadura |
não |
| Serviço | lib/helico/user-state/user-state-service.ts |
Núcleo: cache em memória, isSeen, markSeen, fila de gravação, retry, estado status |
não |
| Provider | providers/user-state-provider.tsx |
Cria o serviço por (usuário, matrícula), expõe o contexto, ligado ao layout |
sim |
| Hooks | hooks/useUserState.ts |
useUserState() e useSeen(key) para as telas |
sim |
| Guarda | lib/helico/user-state/keys.test.ts |
Falha se uma chave migrada aparecer como literal fora de keys.ts |
não |
O núcleo (serviço, chaves, legado, transporte) é TypeScript puro com dependências injetadas, então tem teste Vitest sem montar componente.
5.2 keys.ts: catálogo tipado
export type UserStateScope = 'enrolment' | 'global';
export interface UserStateKeyDef { key: string; scope: UserStateScope; moduleScoped: boolean }
export const userStateKeys = {
roteiroWelcome: (): UserStateKeyDef => ({ key: 'seen.roteiro.welcome', scope: 'enrolment', moduleScoped: false }),
newActivities: (flowId: number | string): UserStateKeyDef => ({ key: `seen.roteiro.new_activities.m${flowId}`, scope: 'enrolment', moduleScoped: true }),
moduleCompletion: (flowId: number | string, block: 'exam_written' | 'module_review'): UserStateKeyDef => ({ /* … */ }),
toast: (flowId: number | string, slotId: string): UserStateKeyDef => ({ /* … */ }),
flashcardIntro: (flowId: number | string): UserStateKeyDef => ({ /* … */ }),
flashcardAllDone: (flowId: number | string): UserStateKeyDef => ({ /* … */ }),
reviewGeneralWelcome: (rg: number): UserStateKeyDef => ({ /* … */ }),
faqVideo: (videoId: string): UserStateKeyDef => ({ key: `seen.faq_video.${videoId}`, scope: 'global', moduleScoped: false }),
} as const;Cada função valida o segmento ([A-Za-z0-9_-]) e lança em desenvolvimento se vier algo
inválido, para o erro aparecer no front e não como 422 em produção. O escopo vem da
definição da chave: a tela não escolhe entre global e matrícula.
5.3 UserStateService: API pública
type UserStateStatus = 'loading' | 'ready' | 'degraded';
interface UserStateServiceDeps {
transport: { fetch(enrolmentId: number | null): Promise<UserStateResponse>; save(req: SaveUserStateRequest): Promise<SaveUserStateResponse> };
legacy: LegacyStorage; // localStorage antigo (write-through / fallback / seed)
scheduler?: { setTimeout; clearTimeout }; // injetável para teste
}
class UserStateService {
constructor(deps: UserStateServiceDeps, ctx: { userId: string; enrolmentId: number | null });
readonly status: UserStateStatus;
load(): Promise<void>; // carrega global + matrícula; seed na 1ª vez
isSeen(def: UserStateKeyDef): boolean; // lê o cache; em 'degraded' lê o legado
markSeen(defs: UserStateKeyDef | UserStateKeyDef[], opts?: { currentModule?: string }): void;
remove(defs: UserStateKeyDef | UserStateKeyDef[]): void; // só se a decisão 6 for aprovada
get(def: UserStateKeyDef): string | undefined; // valor bruto (filtros/preferências)
set(def: UserStateKeyDef, value: string): void; // idem
flush(): Promise<void>; // envia a fila agora (troca de matrícula, saída da página)
subscribe(listener: () => void): () => void; // para useSyncExternalStore
}Comportamento:
| Aspecto | Regra |
|---|---|
| Leitura | Só do cache em memória (síncrona). Antes de ready devolve false/undefined e o chamador espera status !== 'loading' |
| Gravação otimista | markSeen/set atualizam o cache na hora e notificam os assinantes; a tela reage sem esperar a rede |
| Coalescência | Gravações dentro de uma janela curta (ex.: 300 ms) viram um POST por escopo (20 toasts = 1 chamada) |
| Retry | Falha de rede/5xx reenfileira com backoff exponencial e teto de tentativas; 4xx (422/404) não repete, loga e descarta o item |
| Idempotência | Reenviar a mesma chave é seguro (upsert no backend) |
| Poda | markSeen(..., { currentModule }) anexa current_module ao POST; só vale para escopo de matrícula |
| Saída da página | flush() em pagehide/visibilitychange com fetch(..., { keepalive: true }) para não perder a marca |
| Troca de matrícula | O provider descarta o serviço antigo (flush() antes) e cria outro; cache nunca mistura matrículas |
| Falha de carga | status = 'degraded': isSeen lê o localStorage legado, markSeen grava nele e tenta o POST depois. Nunca suprime modal por erro |
| Release 1 | markSeen também grava o legado (write-through). Release 2 remove legacy-storage.ts |
| Semeadura | No 1º ready, legacy lista as chaves antigas do navegador e o serviço as envia por matrícula (chave com matrícula vai para essa matrícula; chave de escopo fraco só para a matrícula ativa); registra “semeado” para não repetir |
| Concorrência entre abas | Last-write-wins no servidor; como marcas só passam de não-visto a visto, é inofensivo. storage/BroadcastChannel fica fora desta entrega |
5.4 Provider e hooks
// providers/user-state-provider.tsx — monta o serviço para (session.user.id, enrolmentId ativo)
// hooks/useUserState.ts
export function useUserState(): Pick<UserStateService, 'status' | 'isSeen' | 'markSeen' | 'get' | 'set'>;
export function useSeen(def: UserStateKeyDef): { ready: boolean; seen: boolean; markSeen(opts?: { currentModule?: string }): void };useUserStateusauseSyncExternalStore(service.subscribe, …)para re-renderizar quando o cache muda.- A matrícula ativa vem de
useActivePlatformParams(já existe); o provider não duplica essa lógica. - Tela típica:
const { ready, seen, markSeen } = useSeen(userStateKeys.flashcardIntro(flowId)); useEffect(() => { if (ready && !seen) setShowIntro(true); }, [ready, seen]); const onClose = () => { setShowIntro(false); markSeen(); };
5.5 Limites do serviço
- Não cacheia nem decide o quê mostrar: só diz se uma chave está marcada. A regra de quando abrir cada modal continua na tela.
- Não guarda dado de domínio, rascunho nem cache de UI (seção 6, “ficam como estão”).
- Não expõe
localStoragenemfetchpara as telas; ESLintno-restricted-propertiesproíbelocalStorage/sessionStoragenos arquivos migrados e o teste guarda dekeys.tscobre chave literal.
6. Migração dos modais (Fase 3)
| Item | Hoje | Passa a usar |
|---|---|---|
| Welcome do roteiro | localStorage helico_roteiro_welcome_seen_* (page.tsx:246,386) |
seen.roteiro.welcome |
| Novas atividades | localStorage …new_activities_seen_* (page.tsx:247,392) |
seen.roteiro.new_activities.m{flowId} |
ModuleCompletion |
sessionStorage …_session_dismissed (page.tsx:284-347) |
seen.module_completion.m{flowId}.{bloco}; force_completion segue em sessão |
| Toast de item concluído | localStorage toast_seen_* (RoteiroDeEstudosSections.tsx:125-163) |
seen.toast.m{flowId}.{slotUuid}; só itens do módulo atual |
| Intro do flashcard | localStorage helico_flashcard_intro_seen_${moduleScope} (flashcard/page.tsx:227,288) |
seen.flashcard.intro.m{flowId} |
| Toast “tudo feito” | localStorage helico_all_done_seen_* (flashcard/page.tsx:254,260) |
seen.flashcard.all_done.m{flowId} |
| Boas-vindas da Revisão Geral | localStorage helico_review_general_welcome_seen_* (revisao/page.tsx:101,162) |
seen.review_general.welcome.{rg} |
| Vídeos do FAQ | localStorage helico_faq_videos_watched_{userId} (useWatchedVideos.ts) |
seen.faq_video.{videoId} (global) |
| Retrospectiva | popup_pending + ack (já no backend) |
seen.retrospective.popup (backend, com fallback) |
Corrige de passagem o escopo fraco (sem aluno/matrícula) do intro/all_done do flashcard e da Revisão Geral.
Ficam como estão: handoffs (helico_roteiro_force_completion_modal,
helico_last_unit_completed_*, helico_post_onboarding, cookie helico-signed-out), caches e
rascunhos (skeleton, last_block_type, optimistic_done, tabsCache, sketch, cronômetro,
app_settings_*), modais de confirmação e tooltips. Dica (hint) do flashcard: depende de
decisão de produto.
7. Testes
| Alvo | Casos |
|---|---|
user_state_repository |
find_by_scope isola usuário e escopo; upsert_many insere/atualiza/ignora igual; idempotente; corrida cai no fallback; delete_by_* |
user_state_service |
prefixo fora da whitelist; chave malformada/longa; valor null/array/longo; mais de 200 itens; bool normalizado; prune_module_scoped mantém o módulo atual e as chaves sem módulo |
user_state_save_request_dto |
corpo malformado; enrolment_id inválido; current_module sem matrícula |
user_state_view_service |
GET sem matrícula (enrolment: null); com matrícula; filtro por prefix; save com e sem poda |
user_state_api_controller |
401; 404 de matrícula alheia; 422; 200; idempotência; usuário sem matrícula grava global |
retrospective_ack_service |
grava em user_state; lê o itemmeta antigo quando a tabela não tem; idempotente |
enrolment_reset_listener_service |
reset apaga as linhas da matrícula e preserva as de outras matrículas e as globais |
schema_test |
tabela declarada e igual ao install.xml |
| Front (Vitest) | UserStateService (leitura/gravação otimista, coalescência, retry com backoff, descarte em 4xx, degraded, semeadura, troca de matrícula, flush), keys.ts (segmentos válidos, escopo, guarda de literais), legacy-storage, hooks useUserState/useSeen |
PHPUnit do plugin roda pelo Makefile:
make moodle CMD="../../vendor/bin/phpunit --no-coverage --bootstrap=/var/www/html/moodle/lib/phpunit/bootstrap.php --configuration=/var/www/html/moodle/local/helico/phpunit.xml <arquivo>"
(mudou o install.xml → refazer o init do ambiente PHPUnit). Gate de estilo do CI:
php-cs-fixer + rector (o check:cs/phpcs e o phpstan ficam fora do gate hoje).
8. Fases e ordem
| Fase | Entrega |
|---|---|
| 1 Backend | 1.1 tabela (descritor, dedicated_schema, install.xml, schema_test) → 1.2 upgrade + versão → 1.3 domínio (seção 2.1) → 1.4 camada platform e controller (2.2) + testes → 1.5 cascata do reset (2.3) → 1.6 retrospectiva (2.3) → 1.7 privacy provider (2.4, se aprovado) → 1.8 docs (contrato, OpenAPI) |
| 2 App | proxy Next → platform-user-state.ts (transporte) → keys.ts → legacy-storage.ts → UserStateService (+ testes Vitest) → provider e hooks → regra ESLint e teste guarda |
| 3 Migração | itens da seção 6, um por vez, testando cada um |
| 4 Verificação | phpunit, php-cs-fixer, rector; manual em https://helico.app.localhost: modal visto não reaparece em outro navegador/aba anônima; reset limpa os flags; módulo novo mostra o do novo módulo e a poda apaga os do anterior |
Deploy: backend primeiro, depois o app (o app degrada se a rota não existir). Release 1 faz write-through no localStorage; Release 2 remove. Sem commit sem pedido explícito (CLAUDE.md do plugin).
9. Tamanho esperado
Com poda: ~25 linhas por matrícula (cerca de 5 fixas + 5 por módulo + 1 por item concluído do módulo atual). Sem poda: ~200. Estimativa, não medida.
10. Riscos
- Poda usa
current_moduledo cliente: valor errado apaga flags válidos (modais reaparecem). Mitigação: o valor vem do/studye a poda só roda no POST. - Chave de toast sem o módulo do item re-dispara rajada ao avançar; por isso a chave leva o módulo do item e o efeito só avalia o módulo atual.
- Retrospectiva é o único ponto que altera comportamento existente; o fallback do itemmeta evita repetir o popup para quem já viu.
- A tabela é criada em produção (RDS) no deploy do plugin.
11. Decisões pendentes
- Dica do flashcard: “uma vez por aluno” ou “toda prática”? (sem resposta: não mexer)
- Marcar como vistos os toasts já concluídos no deploy? (sem resposta: só semear pelo localStorage do navegador)
- Write-through em 2 releases (recomendado) ou corte direto para o backend?
seen.retrospective.popupguarda timestamp (string) ou1? (recomendo timestamp, igual ao itemmeta atual)- Privacy provider: criar agora só para
helico_user_state(o plugin não tem nenhum) ou tratar privacidade do plugin inteiro em um trabalho à parte? removenoPOST(lista de chaves a apagar, resposta comremoved): incluir agora (recomendado, serve a “limpar filtro”) ou só quando o primeiro filtro for migrado?