Skip to content

Alertas do Estudo — Plano de Implementação

Alertas do Estudo — Plano de Implementação

Goal: Materializar GET /api/v1/platform/study/{enrolment_id}/alerts para retornar alertas reais derivados do estado do Plano do Aluno, substituindo o stub { "alerts": [] }. Notificações do Aluno (/platform/notifications) ficam fora desta entrega — controller volta a retornar shape vazio do contrato firme até F7-PR3 ter exam_correction_landed e o domínio campaign começar a emitir eventos. Justificativa: hoje só existe um signal-source real para notificações (revision_resolved), o que produziria bell icon vazio em ~99% dos casos. Alertas, ao contrário, são derivados de estado já presente (slots, sessões, plano), gerando valor imediato.

Architecture: Novo subdomain extensions/engine/alerts/ (projection-only, sem persistência). Generator orquestra N regras puras (alert_rule_interface) sobre um alert_context VO carregado uma única vez. Cada regra recebe o contexto e retorna Alert | null. Façade em extensions/platform/service/alerts_view_service.php resolve student_plan e delega ao generator (mantém ADR-90 — controllers chamam orchestration services em platform).

Notificações: controller notification_api_controller::list_notifications retorna { "items": [], "unread_count": 0 } (shape do contrato firme). Sem mock hardcoded. Plano separado para F7-PR3 cobre a implementação real quando ≥2 fontes existirem.

Tech Stack: PHP 8.3 (Moodle 4.x), framework local_middag (Symfony-like), enum nativo PHP, readonly classes para VO/DTO. Sem novas tabelas, sem LinkML, sem listeners. Reusa student_plan_service, study_flow_service, study_block_service, slot_service já em produção.

Reference docs:

  • .vigim/ddd/terms/terms-platform.yaml — Notificação do Aluno (não materializada nesta entrega)
  • docs/plataforma/api-integracoes/contratos/study.md — contrato firme do /alerts
  • docs/plataforma/api-integracoes/contratos/notification.md — contrato firme do /notifications (permanece marcado como Mock)
  • docs/plataforma/adrs/adr-90_dominio-platform-gateway-e-contratos-de-tela.md
  • docs/plataforma/adrs/ref-90-a_premissas-contratos-api-aluno.md — §12 (actions), §15 (Notif vs Alert)
  • classes/extensions/engine/algorithm/vo/slot_action.php — VO existente (referência para action_type enum)
  • classes/extensions/platform/service/student_area_service.php — pattern de view_service stateless

Premissas vinculantes (decisões fechadas durante review)

ID Decisão Origem
P-1 Notificações adiadas para F7-PR3. Esta entrega cobre apenas alertas. Controller notification_api_controller::list_notifications retorna { items: [], unread_count: 0 } — shape vazio do contrato firme. CT1 review 2026-05-04
P-2 Alertas não persistem. São projeção determinística sobre estado do Plano do Aluno (slots, sessões, blocos). Cada GET /alerts recomputa. REF-90-A §15, CLAUDE.md
P-3 Subdomain extensions/engine/alerts/. Engine já tem 5 subdomains (algorithm, plan, enrolment, onboarding, session); alerts entra como sexto. Justificativa: alerts lê de estado do engine, escopo coerente. A4 review 2026-05-04
P-4 Generator carrega o alert_context VO uma única vez (student_plan, current_flow, current_block, slots) e injeta em cada regra. Regras são funções puras, sem I/O lateral. C3 review 2026-05-04, REF-90-A §10/12
P-5 Enum action_type é compartilhado entre slots, alerts e (futuro) notifications. Local: extensions/platform/enums/action_type.php. Valores: navigate, navigate_with_context, modal, external, dismiss. Refactor de slot_action::$type para usar o enum vira TODO. C1 review 2026-05-04, REF-90-A §12
P-6 Cada regra de alerta gera no máximo 1 instância (id próprio) por alert_context. Generator deduplica por alert.id antes de emitir. Limite total: 10 alertas (alinhado ao mock do contrato). Boa prática, evita inundação visual
P-9 Generator isola exceções: cada rule->evaluate() é envolto em try/catch. Exception → log via debugging(...) + regra ignorada; demais regras continuam. Bug em 1 regra não quebra /alerts. F1 review 2026-05-04
P-7 Idioma: identifiers, classes, métodos, comments e exception messages em inglês; PHPDocs descritivos podem mencionar termos canônicos pt-BR; mensagens user-facing seguem pt-BR. CLAUDE.md
P-8 study_api_controller::alerts continua sendo o handler do endpoint. Substitui-se apenas o corpo do método para delegar ao alerts_view_service. Path, OpenAPI annotation e shape de resposta inalterados. CLAUDE.md “convenções”, contrato firme

Fontes de alerta (mapeamento estado → regra)

┌────────────────────────────────────────────────────────────────────────────┐
│  ESTADO OBSERVADO                              REGRA QUE GERA O ALERTA     │
├────────────────────────────────────────────────────────────────────────────┤
│  Plano do Aluno status = "not_started"      ──► diagnostic_pending_rule    │
│  AND nenhum diagnostic_initial completed                                   │
│                                                                            │
│  Slot do bloco atual com status "in_progress" ──► resume_session_rule      │
│  AND sessão associada paused/idle                                          │
│                                                                            │
│  exam_written com status "pending_correction" ──► correction_pending_rule  │
│  AND tutor já emitiu correção                                              │
│                                                                            │
│  Bloco atual concluído AND próximo bloco      ──► next_block_unlocked_rule │
│  status = "atual"                                                          │
└────────────────────────────────────────────────────────────────────────────┘

Verificação prévia obrigatória (D-1): antes de implementar correction_pending_rule e next_block_unlocked_rule, validar que existem getters/queries baratas para o estado observado. Se exigir join cross-domain custoso, a regra é refatorada para checar via alert_context enriquecido pelo generator (não pela regra). Caso contrário, regra deixa de ser pura.


Estrutura de diretórios

classes/extensions/engine/alerts/                         (NOVO subdomain)
├── CLAUDE.md                                              (escopo do subdomain)
├── contract/
│   ├── alerts_generator_service_interface.php            (orquestrador)
│   └── alert_rule_interface.php                          (contrato individual)
├── dto/
│   ├── alert_context.php                                  (VO carregado 1x)
│   └── alert_dto.php                                      (id, title, variant, action)
├── enum/
│   └── alert_variant.php                                  (info|success|warning|error)
└── service/
    ├── alerts_generator_service.php                       (executa rules registradas + dedup + cap 10)
    └── rule/
        ├── diagnostic_pending_rule.php
        ├── resume_session_rule.php
        ├── correction_pending_rule.php
        └── next_block_unlocked_rule.php

classes/extensions/platform/contract/
└── alerts_view_service_interface.php                      (consumido por study_api_controller)

classes/extensions/platform/dto/
└── alerts_view_dto.php                                    (shape final do endpoint)

classes/extensions/platform/enums/
└── action_type.php                                        (NOVO — enum compartilhado)

classes/extensions/platform/service/
└── alerts_view_service.php                                (resolve student_plan + delega ao generator)

Total novo: ~12 arquivos PHP + 1 CLAUDE.md.

Contrato alert_rule_interface:

namespace local_helico\extensions\engine\alerts\contract;

use local_helico\extensions\engine\alerts\dto\alert_context;
use local_helico\extensions\engine\alerts\dto\alert_dto;

interface alert_rule_interface
{
    public function evaluate(alert_context $context): ?alert_dto;
    public function get_id(): string;        // diagnostic_pending, resume_session, etc.
    public function get_priority(): int;     // ordem de exibição (asc)
}

alert_context shape mínimo (carregado em batch pelo generator):

final readonly class alert_context
{
    public function __construct(
        public student_plan $student_plan,
        public ?study_flow $current_flow,
        public ?study_block $current_block,
        /** @var slot[] */
        public array $current_block_slots,
        /** @var session[] indexado por slot_uuid */
        public array $sessions_by_slot,
        /** @var int[] enrolment_ids com correções landed pendentes — cache enriquecido */
        public array $landed_correction_slot_ids,
    ) {}
}

Endpoint — comportamento alvo

GET /api/v1/platform/study/{enrolment_id}/alerts

1. Auth + lookup student_plan_service::find_by_enrolment_id
   → 401 sem token
   → 404 student_plan_not_found
2. alerts_view_service::generate($enrolment_id):
   2.1 Carrega alert_context completo via batch: 1 query por relação
       (current_flow, current_block, slots_do_bloco, sessions_dos_slots,
       landed_correction_slot_ids)
   2.2 Para cada alert_rule_interface registrada (4 v1):
       rule->evaluate($context) → Alert | null
   2.3 Filtra nulls; deduplica por alert.id; ordena por rule->get_priority() asc; corta em 10
3. Controller serializa { "alerts": Alert[] }

Códigos: 200, 401, 404 (student_plan_not_found) — exatos do contrato firme em study.md.

Response (cada alerta):

{
  "id": "diagnostic_pending",
  "title": "Faça o Diagnóstico Inicial",
  "variant": "info",
  "action": {
    "type": "navigate",
    "label": "Iniciar",
    "route": "/slot/550e8400-e29b-41d4-a716-446655440000"
  }
}

action.type segue action_type enum (P-5). Campos extras (params, modal_key, url) presentes apenas quando type correspondente — REF-90-A §12.

GET /api/v1/platform/notifications

Volta a retornar shape vazio do contrato firme:

{ "items": [], "unread_count": 0 }

Sem mock hardcoded. Annotation OpenAPI permanece. notification.md continua marcando status Mock (pendente service de domínio).


Migração mock → real (ordem de etapas)

# Etapa Resultado
1 Criar extensions/platform/enums/action_type.php enum + testes mínimos do enum Tipo compartilhado pronto
2 Criar extensions/engine/alerts/contract/ interfaces + dto/ VOs Contratos prontos
3 Implementar alerts_generator_service (carregamento de alert_context, dedup, cap, ordenação, try/catch per-rule) Orquestrador isolado
4 Implementar 4 regras (diagnostic_pending, resume_session, correction_pending, next_block_unlocked) Geradores
5 Implementar alerts_view_service em extensions/platform/service/ Façade ADR-90
6 Wire DI: registrar interfaces no container do middag (mesmo pattern de student_area_service) Container resolve
7 Substituir corpo de study_api_controller::alerts para delegar ao alerts_view_service Endpoint /alerts real
8 Reverter mock de notification_api_controller::list_notifications para { items: [], unread_count: 0 } Stub limpo
9 Atualizar study.md (remover “subdomain engine.alerts ainda não implementado”, listar 4 regras ativas) Doc alinhada
10 Atualizar OpenAPI (docs/plataforma/api-integracoes/openapi.yaml) com action_type enum referenciado Schema sync
11 Atualizar Postman collection com request /alerts produzindo cenários Sample requests prontos

Cada etapa fecha com commit atômico mais sua bateria de testes (etapas 1-7).


Testes — matriz de cobertura

Camada Arquivo de teste Cenários
Enum tests/extensions/platform/enums/action_type_test.php Valores válidos batem REF-90-A §12; from() rejeita inválido
Context VO tests/extensions/engine/alerts/dto/alert_context_test.php Imutabilidade (readonly); construção com nullable optional
Rule (cada uma) tests/extensions/engine/alerts/rule/{nome}_rule_test.php Cenário positivo (alerta gerado), negativo (não gera), edge case (estado parcial)
Generator tests/extensions/engine/alerts/alerts_generator_service_test.php Compõe rules; dedup por id; ordena por priority; corta em 10; rule throws → log + skip + outras rules processam
View service tests/extensions/platform/service/alerts_view_service_test.php Resolve student_plan; 404 quando ausente; chama generator; retorna DTO
Endpoint tests/contract/platform/study_alerts_contract_test.php Shape contratual; 401 sem token; 404 plan ausente; lista vazia válida; lista com 1+ alertas
Endpoint notifications tests/contract/platform/notifications_contract_test.php Shape vazio do contrato (items: [], unread_count: 0); 401 sem token
Regression tests/regression/alerts_no_mock_regression_test.php Garante que study_api_controller::alerts não retorna {alerts: []} hardcoded; busca string match

Edge cases obrigatórios em rule tests (não pular):

  • Plano do Aluno em estado intermediário (status not_started mas com slot já em in_progress) — diagnostic_pending_rule deve verificar AND, não OR.
  • Sessão paused há > 7 dias vs < 1h — decisão de variant (warning vs info)? Default v1: info para resume_session, sem distinção de tempo.
  • Correção landed para slot que o aluno ainda não consultou vs já visualizou — v1 emite alerta enquanto não houver flag de “visto”; flag fica em backlog.
  • Bloco atual concluído mas plano em status interrupted — não emitir next_block_unlocked (não há próximo).

OpenAPI + study.md sync

Após etapas 9-10:

  • study.md: remover linha “Status atual: subdomain engine.alerts ainda não implementado”. Adicionar tabela de regras ativas, ids estáveis, variant default por regra.
  • openapi.yaml: garantir que action.type referencia o action_type enum (não duplicar valores inline).
  • Postman: adicionar request com 4 cenários (vazio, diagnostic_pending, correction_pending, múltiplos).

Decisões abertas (intencionais — para decisão durante implementação)

# Decisão Recomendação
D-1 Verificar existência de getter barato para “correção landed” antes de implementar correction_pending_rule Investigar activity/assessment/exam_correction/ antes de comprometer. Se exige join custoso, pré-resolve no alert_context.
D-2 Variant de resume_session_rule deve mudar com tempo desde last activity? v1: sempre info. Telemetria pode justificar warning >7 dias em F7+.
D-3 Refactor de slot_action::$type para usar action_type enum (P-5) entra neste plano? Não. Vira TODO (slot_action é estável; ROI baixo). Plano não toca slot_action.
D-4 Authorization no /alerts: validar que enrolment_id pertence ao $USER->id? Sim (defesa em profundidade). Helper centralizado vira spike subseguinte; v1 valida no controller via student_plan_service::find_by_enrolment_id (já filtra implicitamente via Plano do Aluno do user).

NÃO em escopo

  • Toda materialização de Notificação do Aluno (/notifications real, persistência, listeners, mark-as-read, admin dispatch). Plano separado pós-F7-PR3.
  • Refactor de slot_action para usar o novo enum action_type (D-3).
  • Cache MUC para alerts (alerts é lightweight; cache premature).
  • Listener revision_resolved → notificação (faz parte do plano de notificações futuro).
  • performance_warning_rule (regra de alerta dependente de baseline; backlog).
  • Integração com Moodle native messaging (core_message).
  • Distinção de variant por idade do estado (resume_session warning >7 dias) — D-2.

Riscos

Risco Mitigação
Carga de correction_pending_rule exige join cross-domain custoso D-1 verifica antes de comprometer; se exigir, pré-resolve no alert_context
Generator chamado por polling do Frontend sem rate limit Stateless + queries simples; aceita carga sem cache na v1; adicionar cache se métricas justificarem
Frontend assume ordem específica de alertas Plano define priority asc explícito; documentar em study.md
Regra emite duplicata em estados borderline (slot completou 2x, evento racing) P-6 deduplica por alert.id no generator antes de emitir
Notificação volta retornando vazia quebra Frontend que esperava mock Shape do contrato firme já é {items, unread_count}; vazio é estado válido. Bell icon mostra “0”.

Critérios de aceite

  1. GET /api/v1/platform/study/{enrolment_id}/alerts retorna alertas reais derivados de estado (sem [] hardcoded).
  2. Cada uma das 4 regras tem teste positivo + negativo + edge case verde no PHPUnit.
  3. Generator deduplica, ordena e respeita o cap de 10.
  4. GET /api/v1/platform/notifications retorna { items: [], unread_count: 0 } (shape vazio do contrato; sem mock hardcoded).
  5. action_type enum criado e referenciado pelo alert_dto.
  6. study.md atualizado: linha “engine.alerts não implementado” removida; tabela de regras ativas adicionada.
  7. OpenAPI + Postman sincronizados.
  8. Regression test garante que nenhum dos dois endpoints (/alerts, /notifications) retorna mock hardcoded.

Worktree parallelization

Sequencial por dependência: enum (etapa 1) → contracts/DTOs (2) → generator+rules (3-4) → view_service (5) → DI (6) → controller swap (7) → notifications cleanup (8) → docs (9-11). Lanes paralelas pouco viáveis (a maioria das etapas depende da anterior). Etapas 4 (4 regras) podem ser paralelas entre si — cada regra independente do contrato. Lane único.


Histórico

Data Evento
2026-05-04 v0 — versão inicial cobria notifications + alerts (~40 arquivos).
2026-05-04 v1 — review escolheu CT1=B (cortar notifications). Plano reescrito focado em alerts (~12 arquivos). Notifications adiadas para pós-F7-PR3.

GSTACK REVIEW REPORT

Review Trigger Why Runs Status Findings
CEO Review /plan-ceo-review Scope & strategy 0 — —
Codex Review /codex review Independent 2nd opinion 0 — Codex CLI indisponível; outside voice via Claude subagent
Eng Review /plan-eng-review Architecture & tests (req.) 1 CLEAR (PLAN) 17 issues; 14 decisões + 3 testes adicionais; CT1 cortou notifications (40→12 arquivos)
Design Review /plan-design-review UI/UX gaps 0 — N/A — backend-only
DX Review /plan-devex-review Developer experience gaps 0 — N/A — não é produto developer-facing

OUTSIDE VOICE (Claude subagent): 14 achados. Maioria invalidada pelo cut CT1 de notifications. Achados sobreviventes incorporados como F1 (try/catch per-rule) e D-4 (auth granular já no plano).

UNRESOLVED: 0

VERDICT: ENG CLEARED — pronto para implementar.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close