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/alertsdocs/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.mddocs/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 paraaction_typeenum)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_startedmas com slot já emin_progress) —diagnostic_pending_ruledeve verificar AND, não OR. - Sessão paused há > 7 dias vs < 1h — decisão de variant (warning vs info)? Default v1:
infopararesume_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 emitirnext_block_unlocked(não há próximo).
OpenAPI + study.md sync
Após etapas 9-10:
study.md: remover linha “Status atual: subdomainengine.alertsainda não implementado”. Adicionar tabela de regras ativas, ids estáveis, variant default por regra.openapi.yaml: garantir queaction.typereferencia oaction_typeenum (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(/notificationsreal, persistência, listeners, mark-as-read, admin dispatch). Plano separado pós-F7-PR3. - Refactor de
slot_actionpara usar o novo enumaction_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
GET /api/v1/platform/study/{enrolment_id}/alertsretorna alertas reais derivados de estado (sem[]hardcoded).- Cada uma das 4 regras tem teste positivo + negativo + edge case verde no PHPUnit.
- Generator deduplica, ordena e respeita o cap de 10.
GET /api/v1/platform/notificationsretorna{ items: [], unread_count: 0 }(shape vazio do contrato; sem mock hardcoded).action_typeenum criado e referenciado peloalert_dto.study.mdatualizado: linha “engine.alerts não implementado” removida; tabela de regras ativas adicionada.- OpenAPI + Postman sincronizados.
- 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.