Plano — Frontend Completo: Atividades + Métricas
Data: 2026-05-01
Branch base: feature/new-contracts
Goal: experiência fim-a-fim no NextJS — Aluno realiza qualquer tipo de atividade → backend processa → métricas reais aparecem.
Princípios
- EAV-only. Toda entity persistida via
helico_items+helico_itemmeta. Zero tabela dedicada nova. Tabelas mortas (helico_responses,helico_classifications,helico_slots,helico_sessions) removidas em Fase 0. - VOs tipados sobre JSONs soltos. Shape estável + queryable → VO flat com
to_metadata()/from_metadata()decompostas em meta_keys. Collection → VO child items. Cache opaque derivado pode ficar como JSON emdescription(exceção justificada). - Bottom-up. Cada fase desbloqueia métrica visível. Fase N+1 só inicia após N verde.
- ADR conformity. Cada fase cita ADR aplicável. Refactor moves alinham domínio com terms canônico.
- Teste antes de avanço. Cada fase tem Definition of Done com tests passing.
Storage convention
LinkML entity → EAV item TYPE='<linkml_slug>'
shape estável VO → flat meta_keys em parent item (via VO::to_metadata())
VO collection → child items TYPE='vo_<name>' parent=<ar_id>
cache opaco derivado → JSON em item.description (exceção, justificar caso a caso)
process_domain → service stateless (sem persistência)
view-model → composição runtime (sem storage)VO convention (sem interface forçada)
final readonly class my_vo {
public function __construct(public ?float $field_a, public int $field_b, ...) {}
public function to_metadata(): array { return ['field_a' => $this->field_a, ...]; }
public static function from_metadata(array $meta): self { return new self(...); }
}Sem interface formal. Convenção idiomatic: par to_metadata() + from_metadata(). Tipo concreto via PHP property types + readonly. Tooling encontra por nome.
Catálogo VOs
| VO | Fase | Pattern | Fields |
|---|---|---|---|
score_breakdown |
F1 ✅ | flat | nota_real, nota_bruta, nota_ajustada, bonus_relevancia, total_questions, correct_count, incorrect_count, unanswered_count, time_total_ms |
slot_scope_ref |
F1.5 | collection child | type, ref_id, name |
slot_lock |
F1.5 | flat | reason, message, unlock_rule, unlock_at |
lock_dependency |
F1.5 | collection child | depends_on_slot_id, kind |
slot_action |
F1.5 | flat | type, label, route, params_json (delimited shape) |
slot_context_diagnostic |
F1.5 | flat sealed | unit_ids[], question_pool_size, segment |
slot_context_flashcard |
F1.5 | flat sealed | deck_id, card_count, source_module_ids |
slot_context_guided_study |
F1.5 | flat sealed | unit_id, source_type, scenario_di_level |
slot_context_exam_objective |
F1.5 | flat sealed | window_rg_number, question_count |
slot_context_exam_written |
F1.5 | flat sealed | exam_template_id, max_score |
slot_context_general_review |
F1.5 | flat sealed | window_rg_number, source_unit_count |
session_data_* |
F1.5 | flat sealed | type-specific runtime state |
question_response |
F2 | collection child parent=session | question_id, answer, correct, notsure, time_ms, sort_order |
flashcard_response |
F2 | collection child parent=session | card_id, knew, confidence, time_ms |
notebook_interaction (highlight/note) |
F3 | collection child parent=artifact | kind, range_start, range_end, text, color |
criterion_score |
F7 | collection child parent=correction | criterion_name, score, max, weight, comment |
review_window_module |
F6 | collection child parent=window | module_id, sort_order, source_phase |
dimension_snapshot |
F5 | JSON cache em report.description (exceção) | hierarquica overall→discipline→module→unit — derivada, invalidável |
Sealed VOs (slot_context_, session_data_): um VO concreto por slot_type discriminado. Factory from_slot() resolve qual VO instanciar pelo TYPE. Evita context blob amorfo.
Fases
| # | Goal | Duração | Depends |
|---|---|---|---|
| 0 | Cleanup tabelas legadas (zero contract de VO formal) | 0.5d | — |
| 1 | 7 slot handlers + result EAV + score_breakdown VO | 8-10d | 0 |
| 1.5 | Slot/Session JSON soltos → VOs tipados sealed | 4-6d | 1 |
| 2 | response/result AR move para activity domain | 3-4d | 1.5 |
| 3 | notebook_artifact (EAV) + notebook_interaction VO + reforço | 4-5d | 2 |
| 4 | metrics fundação — classification + report (EAV) | 3-4d | 1+2 |
| 5 | consolidação real → performance_api sem mock | 5-7d | 4 |
| 6 | review_window EAV + review_window_module VO + objective_priority | 5-6d | 5 |
| 7 | tutor correction loop + criterion_score VO | 4-5d | 2+5 |
| 8 | platform orchestration services (10) | 4-5d | 1-7 |
| 9 | activity FLAT_LEGACY → DDD per-entity | 2-3d | 1-7 |
Caminho crítico frontend completo: F0→F1→F2→F4→F5. ~3 semanas.
FASE 0 — Cleanup + base contracts
0.1 Remover tabelas mortas
Modificar: db/install.xml — remover blocos:
<TABLE NAME="helico_responses"><TABLE NAME="helico_classifications"><TABLE NAME="helico_slots"><TABLE NAME="helico_sessions">
Modificar: db/upgrade.php — adicionar step bump version + drop tables se existirem.
Modificar: version.php — bump.
0.2 Base contracts EAV-aware
Arquivo novo: classes/extensions/base/eav_value_object_interface.php
namespace local_helico\extensions\base;
interface eav_value_object_interface {
public function to_metadata(): array; // flat meta_keys
public static function from_metadata(array $meta): static;
}Arquivo novo: classes/extensions/base/eav_collection_item_interface.php
interface eav_collection_item_interface {
public static function child_type(): string;
public function to_metadata(): array;
}0.3 DoD
-
install.xmlsem 4 tabelas mortas -
upgrade.phpdrop idempotente - DB fresh install + DB existente upgrade ambos limpos
- VO/collection contracts existem
FASE 1 — Slot handlers + result EAV
Goal: dispatcher completo. 7 slot types submetem corretamente.
1.1 Result entity (EAV)
Arquivo novo: classes/extensions/activity/result/entity/result.php
namespace local_helico\extensions\activity\result\entity;
use local_middag\base\domain\item;
class result extends item {
public const TYPE = 'activity_result';
public const METADATA_FIELDS = [
'slot_id',
'session_id',
'student_plan_id',
'enrolment_id',
'unit_id',
'slot_type',
'completion_status', // completed|pending_correction|exempted
// VO score_breakdown flat:
'nota_real',
'nota_bruta',
'nota_ajustada',
'bonus_relevancia',
'total_questions',
'correct_count',
'incorrect_count',
'unanswered_count',
'time_total_ms',
'completed_at',
];
}1.2 score_breakdown VO
Arquivo novo: classes/extensions/activity/result/vo/score_breakdown.php
namespace local_helico\extensions\activity\result\vo;
use local_helico\extensions\base\eav_value_object_interface;
final readonly class score_breakdown implements eav_value_object_interface {
public function __construct(
public ?float $nota_real,
public ?float $nota_bruta,
public ?float $nota_ajustada,
public float $bonus_relevancia,
public int $total_questions,
public int $correct_count,
public int $incorrect_count,
public int $unanswered_count,
public int $time_total_ms,
) {}
public function to_metadata(): array {
return [
'nota_real' => $this->nota_real,
'nota_bruta' => $this->nota_bruta,
'nota_ajustada' => $this->nota_ajustada,
'bonus_relevancia' => $this->bonus_relevancia,
'total_questions' => $this->total_questions,
'correct_count' => $this->correct_count,
'incorrect_count' => $this->incorrect_count,
'unanswered_count' => $this->unanswered_count,
'time_total_ms' => $this->time_total_ms,
];
}
public static function from_metadata(array $meta): self {
return new self(
nota_real: isset($meta['nota_real']) ? (float) $meta['nota_real'] : null,
nota_bruta: isset($meta['nota_bruta']) ? (float) $meta['nota_bruta'] : null,
nota_ajustada: isset($meta['nota_ajustada']) ? (float) $meta['nota_ajustada'] : null,
bonus_relevancia: (float) ($meta['bonus_relevancia'] ?? 0),
total_questions: (int) ($meta['total_questions'] ?? 0),
correct_count: (int) ($meta['correct_count'] ?? 0),
incorrect_count: (int) ($meta['incorrect_count'] ?? 0),
unanswered_count: (int) ($meta['unanswered_count'] ?? 0),
time_total_ms: (int) ($meta['time_total_ms'] ?? 0),
);
}
}1.3 result service + dto + contract
Arquivos novos em classes/extensions/activity/result/:
dto/result_dto.phpdto/activity_submit_result_dto.php— payload retornado por handlerscontract/result_service_interface.phpservice/result_service.php
result_service::create_from_breakdown(int $slot_id, int $user_id, score_breakdown $vo, array $context): result
1.4 activity_handler contract + registry
Arquivos novos:
classes/extensions/engine/algorithm/contract/activity_handler_service_interface.phpclasses/extensions/engine/algorithm/service/activity_handler_registry.php
1.5 7 handlers
Em classes/extensions/engine/algorithm/service/:
| Handler | Status | Lógica |
|---|---|---|
diagnostic_initial_handler_service |
refactor existente | retornar activity_submit_result_dto; persistir result via result_service |
diagnostic_verify_handler_service |
NOVO | espelha DI + is_di=false no pool; emit signal segment=SVD |
exam_objective_handler_service |
NOVO | itera responses, computa NR=correctas/total, persiste result |
exam_truefalse_handler_service |
NOVO | similar exam_objective (avulso, sem CDA) |
exam_written_handler_service |
NOVO | persiste exam_submission EAV (Fase 2 dep), status=pending_correction; sem result até correção |
flashcard_practice_handler_service |
NOVO | itera cards, persiste flashcard_response children; sem nota |
guided_study_handler_service |
NOVO | recebe content_html; delega notebook_artifact_service (Fase 3 stub) |
general_review_handler_service |
NOVO | semelhante exam_objective sob escopo Janela Revisão |
1.6 Signals
Arquivos novos em classes/extensions/engine/algorithm/signal/:
activity_completed_signal.phpcda_classification_done_signal.phpexam_submission_pending_signal.php
1.7 Modificar slot_api dispatcher
Modificar: classes/extensions/platform/controller/slot_api_controller.php linhas 230-258.
Substituir if/elseif por dispatcher via registry.
1.8 Tests
tests/activity/result/
├── result_service_test.php
└── score_breakdown_test.php (VO roundtrip)
tests/engine/algorithm/
├── diagnostic_verify_handler_service_test.php
├── exam_objective_handler_service_test.php
├── exam_truefalse_handler_service_test.php
├── exam_written_handler_service_test.php
├── flashcard_practice_handler_service_test.php
├── guided_study_handler_service_test.php
└── activity_handler_registry_test.php
tests/integration/
└── slot_api_dispatcher_e2e_test.php (7 types)1.9 DoD
- Postman flow passa com qualquer slot type
-
score_breakdownVO roundtrip preserva dados - result EAV persiste com 9 meta_keys flat
- Cada handler test ≥85% coverage
- Zero
slot_type_not_supported_yetretornado
FASE 2 — response/result AR move
Goal: ADR-80 compliance. response + result moram em activity/.
2.1 Move response
De: classes/extensions/engine/session/{entity,service,contract}/response*
Para: classes/extensions/activity/response/{entity,service,contract}/
PHPStorm refactor preserva uso. response continua EAV type='response' ou desambiguar question_response vs flashcard_response.
Decisão: dois TYPEs separados — question_response e flashcard_response. Refactor response_service::bulk_create() muda TYPE conforme payload.
2.2 exam_submission (EAV)
Arquivo novo: classes/extensions/activity/assessment/exam_submission/entity/exam_submission.php
class exam_submission extends item {
public const TYPE = 'exam_submission';
public const METADATA_FIELDS = [
'slot_id',
'session_id',
'user_id',
'submitted_text',
'submitted_at',
'correction_status', // pending|in_review|corrected
'corrected_by',
'corrected_at',
];
}2.3 activity_extension hook
Arquivo novo: classes/extensions/activity/activity_extension.php — registra services no DI.
2.4 DoD
- grep
engine\session\responseretorna 0 - result EAV instanciado por todos handlers
- exam_submission EAV preenchido em exam_written submit
- Tests passing
FASE 3 — notebook_artifact + reforço
Goal: Caderno Online persistido. Reforço com 3 cenários.
3.1 EAV entities
Arquivo novo: classes/extensions/activity/productive/notebook_artifact/entity/notebook_artifact.php
class notebook_artifact extends item {
public const TYPE = 'notebook_artifact';
public const METADATA_FIELDS = [
'enrolment_id',
'unit_id',
'discipline_id',
'source_type', // resumo|leitura|reforco|hibrido
'source_origin', // student|helico|merged
'last_interaction_at',
'visibility_scope', // current_block|notebook (regra A-09)
];
// content_html → item.description (texto longo opaque)
}Arquivo novo: classes/extensions/activity/productive/artifact_versioning/entity/artifact_version.php
class artifact_version extends item {
public const TYPE = 'artifact_version';
public const METADATA_FIELDS = [
'artifact_id', // parent = notebook_artifact
'version_number',
'change_reason',
'created_by',
];
// version content → description
}parent = notebook_artifact id. ADR-11 imutável (status=‘archived’ ao invés de delete).
3.2 service
Arquivo novo: classes/extensions/activity/productive/notebook_artifact/service/notebook_artifact_service.php
Métodos:
persist_resumo(user_id, enrolment_id, unit_id, content_html, origin)persist_leitura_interaction(artifact_id, highlights, notes)— interactions append em description (versioned)persist_reforco_substitution(artifact_id, new_content, origin)— cenário 1 ADR-60: arquiva versão atual + cria novafind_by_enrolment(enrolment_id, include_current_block)find_by_unit(user_id, unit_id)
3.3 Reforço lógica
guided_study_handler_service::submit() — switch baseado em context:
- consulta classification.di_level for unit
- se reforço:
- cenário 1 (DI Básico): substitution (se Aluno escolheu) ou keep
- cenário 2 (DI Inter): no-op no artifact (releitura mesmo content)
- cenário 3 (DI Avançado): primeira exibição → cria artifact source=
leitura
3.4 Atualizar notebook_api
Modificar: classes/extensions/platform/controller/notebook_api_controller.php
- Substituir mock por chamada
notebook_artifact_service - Aplicar regra A-09 (excluir bloco atual)
3.5 DoD
- notebook_api retorna dados reais
- 3 cenários reforço funcionam (3 testes integration)
- artifact_version preserva histórico imutável
- Regra A-09 testada
FASE 4 — metrics fundação
Goal: ADR-70 compliance. classification em metrics/. report AR existe.
4.1 Move classification
De: classes/extensions/engine/algorithm/{entity,service,contract}/classification*
Para: classes/extensions/metrics/classification/{entity,service,contract}/classification*
Entity já é EAV. Só rename namespace + path.
4.2 report (EAV)
Arquivo novo: classes/extensions/metrics/report/entity/report.php
class report extends item {
public const TYPE = 'metrics_report';
public const METADATA_FIELDS = [
'enrolment_id',
'student_plan_id',
'scope', // unit|discipline|module|overall
'scope_target_id',
'generated_at',
'invalidated_at', // null = válido
];
// dimension_data (cache opaque) → item.description (JSON serializado)
}idnumber = report:{enrolment_id}:{scope}:{target_id} para idempotência.
4.3 Process services
Arquivos novos:
classes/extensions/metrics/level_classification/service/level_classification_service.phpclasses/extensions/metrics/level_reclassification/service/level_reclassification_service.phpclasses/extensions/metrics/relevance_bonus/service/relevance_bonus_calculator.phpclasses/extensions/metrics/progress_rebalancing/service/progress_rebalancing_service.php
Sem persistência — process services stateless.
4.4 listener SVD reclass
Arquivo novo: classes/extensions/metrics/level_reclassification/listener/cda_classification_listener.php
- on signal
cda_classification_donesegment=SVD → busca DI da unit → calcula média → cria nova classification source=unit_combined
4.5 metrics_extension
Arquivo novo: classes/extensions/metrics/metrics_extension.php — DI registration.
4.6 DoD
-
engine.algorithm.classification_servicezero referências internas - DI handler chama
metrics::level_classification_service.classify() - SVD signal → reclassification listener cria classification combined
- report EAV persiste + invalida via
set_invalidated_at()
FASE 5 — consolidação real
Goal: performance_api sem mock.
5.1 Estrutura
classes/extensions/metrics/consolidation/
├── contract/
│ ├── consolidation_engine_service_interface.php
│ └── dimension_calculator_interface.php
├── service/
│ ├── consolidation_engine_service.php
│ ├── unit_performance_calculator.php
│ ├── discipline_performance_calculator.php
│ ├── module_performance_calculator.php
│ └── overall_performance_calculator.php
├── dto/
│ ├── consolidated_dashboard_dto.php
│ └── trend_dto.php
└── listener/
└── activity_completed_listener.php5.2 Cache strategy
Lazy + invalidation:
- listener
activity_completed→ marca affected reportsinvalidated_at = now() get_dashboard()busca reports; se invalidated → recompute + persist; senão return description JSON- TTL hard 24h fallback
5.3 MVP scope
4 dimensões: overall, by_discipline, by_module, by_exam_type. Resto (13 charts) → fase futura.
5.4 Update performance_api
Modificar: classes/extensions/platform/controller/performance_api_controller.php
- Substituir mock por
consolidation_engine_service::get_dashboard($enrolment_id)
5.5 DoD
- performance_api zero TODO, zero mock
- Submit DI → /performance reflete
- Cache hit/miss verificável
- 4 dimensões MVP
FASE 6 — review_window + objective_priority
6.1 review_window EAV
classes/extensions/engine/plan/review_window/
├── entity/review_window.php (TYPE='review_window')
├── entity/review_window_module.php (TYPE='review_window_module' parent=window)
├── service/review_window_service.php
└── enums/review_window_phase.phpreview_window:
public const METADATA_FIELDS = [
'student_plan_id',
'rg_number',
'phase', // crescimento|deslizamento|cumulativo
'computed_at',
];review_window_module (VO collection):
public const TYPE = 'review_window_module';
public const METADATA_FIELDS = [
'module_id',
'sort_order',
'source_phase', // sliding|cumulative
];parent = review_window id.
6.2 objective_priority service
Arquivo novo: classes/extensions/engine/algorithm/objective_priority/service/objective_priority_service.php
select_questions(review_window, student_plan_id, count): question_id[]
Aplica 6 regras (Critério Priorização ADR-60/70).
6.3 Compilation usa priority
compilation_engine_service — quando gera slot general_review ou exam_objective no contexto RG: chama priority service.
6.4 DoD
- DI Avançado → SVD Básico rebaixa para Básico
- RG1 produz window M1-M4; RG6 produz cumulativo + deslizante
- objective_priority distribui 1q/unit antes de repetir
FASE 7 — tutor correction loop
7.1 EAV entities
classes/extensions/activity/assessment/
├── exam_correction/
│ ├── entity/exam_correction.php (TYPE='exam_correction')
│ ├── entity/criterion_score.php (TYPE='criterion_score' parent=correction)
│ └── service/exam_correction_service.php
└── exam_feedback/
└── service/exam_feedback_service.php (compõe submission + correction, sem AR próprio)exam_correction:
public const METADATA_FIELDS = [
'submission_id',
'tutor_id',
'total_score',
'max_score',
'corrected_at',
];
// feedback_html → item.descriptioncriterion_score (VO collection child):
public const TYPE = 'criterion_score';
public const METADATA_FIELDS = [
'correction_id',
'criterion_name',
'score',
'max',
'weight',
'comment',
];7.2 Admin endpoint
Arquivo novo: classes/extensions/admin/controller/exam_correction_admin_controller.php
POST /admin/corrections/{submission_id}— body inclui criteria array. Cria correction + N criterion_score children.
7.3 listener
Arquivo novo: classes/extensions/activity/assessment/exam_correction/listener/exam_corrected_to_result_listener.php
Cria result retroativo + emit activity_completed (atrasado).
7.4 Update exam_api
Modificar: classes/extensions/platform/controller/exam_api_controller.php
exam_detailinclui correction + feedback quando submission corrigida.
7.5 DoD
- Aluno submita exam_written → submission pending
- Admin corrige → correction + N criterion_score children EAV
- /performance reflete nota tardia
- /exam/{slot} retorna feedback completo
FASE 8 — platform orchestration services
8.1 10 services
classes/extensions/platform/service/
├── student_area_service.php
├── study_roadmap_service.php
├── flashcard_view_service.php
├── review_view_service.php
├── diagnostic_view_service.php
├── performance_view_service.php
├── exam_view_service.php
├── library_view_service.php
├── notebook_view_service.php
└── profile_view_service.phpCada um stateless, agrega N domains, retorna *_dto.
8.2 Refactor controllers
Cada method virou:
public function X(int $enrolment_id): JsonResponse {
$this->validate_token();
$this->validate_enrolment_belongs_to_user($enrolment_id);
$dto = middag::get(X_view_service_interface::class)->get(...);
return $this->json_response($dto->to_array());
}8.3 DoD
- 10 services existem
- Controllers ≤10 lines per method
- Frontend funciona idêntico (zero breaking)
- ADR-90 conformity
FASE 9 — activity FLAT_LEGACY → DDD
9.1 Migrações
| De | Para |
|---|---|
activity/objective_questionnaire/objective_questionnaire.php |
activity/assessment/exam_objective/entity/exam_objective.php |
activity/vf_questionnaire/vf_questionnaire.php |
activity/assessment/exam_truefalse/entity/exam_truefalse.php |
activity/written_questionnaire/written_questionnaire.php |
activity/assessment/exam_written/entity/exam_written.php |
activity/mock_assessment/mock_assessment_config.php |
activity/assessment/exam_template/entity/exam_template.php |
Cada destino: EAV item + dto + service + contract.
9.2 Update ddd-config.yaml
Remover prefixo _ em activity.assessment, activity.formative, activity.productive. Adicionar activity.practice.
9.3 LinkML materialize
12 entities activity.assessment + 1 activity.formative + 2 activity.productive + 1 activity — auto-generate stubs com storage_type: eav_meta.
9.4 DoD
- grep
simulado_retorna 0 - build_extensions regenera sem warnings
- extensions-audit P0-1 = ✅