Skip to content

Plano — Frontend Completo: Atividades + Métricas

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

  1. 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.
  2. 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 em description (exceção justificada).
  3. Bottom-up. Cada fase desbloqueia métrica visível. Fase N+1 só inicia após N verde.
  4. ADR conformity. Cada fase cita ADR aplicável. Refactor moves alinham domínio com terms canônico.
  5. 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.xml sem 4 tabelas mortas
  • upgrade.php drop 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.php
  • dto/activity_submit_result_dto.php — payload retornado por handlers
  • contract/result_service_interface.php
  • service/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.php
  • classes/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.php
  • cda_classification_done_signal.php
  • exam_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_breakdown VO roundtrip preserva dados
  • result EAV persiste com 9 meta_keys flat
  • Cada handler test ≥85% coverage
  • Zero slot_type_not_supported_yet retornado

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\response retorna 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 nova
  • find_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.php
  • classes/extensions/metrics/level_reclassification/service/level_reclassification_service.php
  • classes/extensions/metrics/relevance_bonus/service/relevance_bonus_calculator.php
  • classes/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_done segment=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_service zero 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.php

5.2 Cache strategy

Lazy + invalidation:

  • listener activity_completed → marca affected reports invalidated_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.php

review_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.description

criterion_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_detail inclui 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.php

Cada 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 = ✅
Navigation

Type to search…

↑↓ navigate↵ selectEsc close