Skip to content

Plano: helicouserstate — estado de UI do Aluno entre navegadores

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

  1. currentModule no app é o id do fluxo (ex.: 46974), não a ordem do módulo. As chaves usam m{flowId}. Poda por “diferente do atual”, nunca “menor que”.
  2. A chave do toast leva o módulo do item (modulo.id), e o efeito só avalia itens do módulo atual (hoje percorre data com o escopo do módulo atual: risco de rajada ao avançar). Confirmar o que useModules devolve antes de migrar.
  3. Id do toast = slot.id (UUID).
  4. O reset de matrícula já tem cascata (enrolment_reset_listener_service).
  5. API REST em api/v1/platform/... (controller Symfony, deny_if_not_owned), proxy Next por arquivo (app/api/helico/platform/<área>/route.ts).
  6. 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 };
  • useUserState usa useSyncExternalStore(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 localStorage nem fetch para as telas; ESLint no-restricted-properties proíbe localStorage/sessionStorage nos arquivos migrados e o teste guarda de keys.ts cobre 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_module do cliente: valor errado apaga flags válidos (modais reaparecem). Mitigação: o valor vem do /study e 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

  1. Dica do flashcard: “uma vez por aluno” ou “toda prática”? (sem resposta: não mexer)
  2. Marcar como vistos os toasts já concluídos no deploy? (sem resposta: só semear pelo localStorage do navegador)
  3. Write-through em 2 releases (recomendado) ou corte direto para o backend?
  4. seen.retrospective.popup guarda timestamp (string) ou 1? (recomendo timestamp, igual ao itemmeta atual)
  5. 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?
  6. remove no POST (lista de chaves a apagar, resposta com removed): incluir agora (recomendado, serve a “limpar filtro”) ou só quando o primeiro filtro for migrado?
Navigation

Type to search…

↑↓ navigate↵ selectEsc close