74 lines
4.0 KiB
Markdown
74 lines
4.0 KiB
Markdown
---
|
|
title: Lesson Evaluation
|
|
order: 4
|
|
category: evaluation
|
|
---
|
|
# 04. Lesson Evaluation
|
|
|
|
The LMS determines the type of lesson and how to evaluate it based on specific markers found in the Markdown content.
|
|
|
|
## Markdown Markers
|
|
|
|
| Mode | Marker | Evaluation Logic |
|
|
|------|--------|------------------|
|
|
| **C / Python** | `---INITIAL_CODE---` / `---INITIAL_PYTHON---` | Standard stdout matching against `---EXPECTED_OUTPUT---` and presence of `---KEY_TEXT---`. |
|
|
| **Circuit** | `---INITIAL_CIRCUIT---` | Node voltage matching against `---EXPECTED_CIRCUIT_OUTPUT---` and `---KEY_TEXT_CIRCUIT---`. |
|
|
| **Arduino (Velxio)** | `---INITIAL_CODE_ARDUINO---` | Serial output sequence matching, lenient graph wiring comparison, and `---KEY_TEXT---`. |
|
|
| **Quiz** | `---QUIZ_MCQ---` / `---QUIZ_WEIGHTED---` / `---FLASHCARD---` | Skor resmi = rata-rata persentase per jenis quiz (weighted pakai poin bobot); lulus bila ≥ 75. |
|
|
| **Slide** | `---slide-start---` | Tidak ada (hanya presentasi konten). |
|
|
|
|
## Evaluators (`lib/services/`)
|
|
|
|
The evaluation logic is isolated into specific service files:
|
|
|
|
### General & C/Python (`evaluators.ts`, `exercise.ts`)
|
|
- `export function checkKeyText(code: string, keyText: string): boolean`
|
|
Checks if all lines in the `keyText` are present in the provided `code`.
|
|
- `export function processLanguageEvaluation(...)`
|
|
Coordinates the compilation request and output verification for C and Python.
|
|
|
|
### Circuit Evaluation (`evaluators.ts`, `exercise.ts`)
|
|
- `export function evaluateCircuitSubmission(...)`
|
|
Handles the flow of extracting the circuit state.
|
|
- `export function validateNodes(actualVoltages: Record<string, number>, expectedNodes: Record<string, NodeResult>): boolean`
|
|
Validates if the actual node voltages match the expected voltages within a specified tolerance.
|
|
|
|
### Arduino/Velxio Evaluation (`velxio-evaluator.ts`, `velxio-bridge.ts`)
|
|
- `class VelxioBridge` (`velxio-bridge.ts`)
|
|
Manages the `window.postMessage` protocol between the LMS and the Velxio iframe.
|
|
- Commands: `elemes:load_code`, `elemes:load_circuit`, `elemes:get_source_code`, `elemes:get_serial_log`, `elemes:get_wires`.
|
|
- Events: `velxio:ready`, `velxio:compile_result`.
|
|
- `export function evaluateVelxioSubmission(...)`
|
|
Orchestrates the 3-part Arduino evaluation:
|
|
1. **Key Text**: Checks the retrieved source code.
|
|
2. **Serial Output**: Uses `matchSerialSubsequence(actual, expected)` to ensure expected log lines appear in the correct order.
|
|
3. **Wiring**: Performs a lenient graph comparison (expected edges must exist; extra edges are allowed; ground pins are normalized).
|
|
|
|
### Flowchart Evaluation (`flowchart-evaluator.ts`)
|
|
- `export function evaluateFlowchartSubmission(...)`
|
|
Parses flowchart JSON data and verifies structural correctness against the expected model.
|
|
|
|
## Sinkronisasi Evaluasi → Progress (tanpa restart)
|
|
|
|
Jenis evaluasi lesson ditentukan oleh marker di file `.md` (lihat tabel di atas).
|
|
Saat guru mem-publish perubahan di `/teacher/content`:
|
|
|
|
1. `POST /content/drafts/<id>/publish` membandingkan **signature evaluasi**
|
|
sebelum vs sesudah (`has_exercise`, `has_quiz`, jenis kuis, jumlah soal).
|
|
2. **Registry lesson** (`lessons`) langsung disinkronkan dari `home.md` +
|
|
`sub-home.md` — lesson baru/hapus/rename tidak perlu restart.
|
|
3. Bila signature berubah, `repositories.recompute_lesson_progress()`
|
|
menghitung ulang `composite_percent` + `state` **semua siswa** untuk lesson
|
|
itu memakai komponen baru ("recompute jujur"):
|
|
- Menambah quiz ke lesson exercise-only → siswa `done` turun ke
|
|
`in_progress` sampai quiz dikerjakan.
|
|
- Skor historis (`quiz_score_earned/total`, attempt kuis) **tidak dihapus**;
|
|
guru tetap bisa reset per siswa lewat halaman progress.
|
|
4. Respons publish memuat `evaluation_changed` + `progress_recomputed`, yang
|
|
ditampilkan sebagai notifikasi di editor.
|
|
|
|
Perubahan konten di luar webapp (git pull/edit manual) ditangani oleh tombol
|
|
**Sinkronisasi** di `/teacher/progress` (`POST /content/sync-registry`) dan
|
|
safety-net saat startup (`recompute_all_lessons`). Tidak ada lagi kebutuhan
|
|
restart server agar progress guru konsisten.
|