Learning Management - Metrics (Shared)

Purpose

• Quy định chung cho tính chỉ số. Áp dụng mọi exam.

Impact to goal (Shared)

• Ý nghĩa: Chỉ ra nhóm nên luyện trước.
• Cách tính: so sánh hiện tại với ngưỡng cần đạt của mục tiêu.
  • gapPct = max(0, requiredPct - currentPct) (chỉ áp dụng khi score profile tương thích).
  • Ngưỡng: High 15–20%+; Medium 3–14%; Low <3% (ẩn nhãn).
  • Nhãn: Cần luyện gấp (đỏ), Nên luyện thêm (vàng).
• Hiển thị:
  • nếu so sánh hợp lệ: icon màu + tooltip “Hiện tại X • Mục tiêu Y • Thiếu Z”,
  • nếu không hợp lệ: ẩn nhãn thiếu điểm và hiển thị hint ngắn “Dạng bài này chưa so sánh trực tiếp với mục tiêu”.
  • nếu chưa đủ độ tin cậy dữ liệu so sánh (comparable attempts < 3 trong 30 ngày hoạt động): ẩn numeric gap và chỉ hiển thị trend/progress.

Goal scale compatibility (Shared)

• Goal và score phải đi theo program + assessment form + skill, không dùng một thang chung cho mọi dạng bài.
• Contract cốt lõi:
  • assessment_form_id,
  • goal_scale_profile_id,
  • attempt_score_profile_id,
  • goal_comparison_mode = direct | normalized | not_comparable.
• Rule:
  • direct: cùng profile, so sánh trực tiếp.
  • normalized: chỉ dùng khi có mapping chuẩn giữa 2 profile trong whitelist đã duyệt.
  • not_comparable: không show numeric gap, chỉ show trend/progress.

Goal priority and versioning (Shared)

• Goal model:
  • 1 primary + tối đa 1 secondary.
  • LM mặc định ưu tiên đọc theo primary goal.
• Versioning:
  • mỗi lần user đổi goal tạo goal_version_id mới,
  • mỗi attempt lưu goal_version_id_at_submission,
  • đánh giá lịch sử dùng version tại thời điểm nộp để tránh méo dữ liệu.

Numeric gap confidence gate (Shared)

• Điều kiện hiển thị numeric distance-to-goal:
  • goal_comparison_mode = direct | normalized, và
  • comparable_attempts_30_active_days >= 3.
• Nếu không đạt gate:
  • ẩn numeric gap,
  • chỉ hiển thị trend/progress + confidence hint.

Time window for Impact (Shared)

• 30 ngày hoạt động: lấy “30 ngày có bài hoàn thành” gần nhất, neo theo lastSubmittedAt (không tính ngày không nộp bài).
• Nếu <30 ngày hoạt động (trong 365 ngày), dùng tất cả ngày hoạt động hiện có.
• Ở chế độ 1 năm/Lifetime: ẩn nhãn, hiển thị hint “Impact chỉ khả dụng ở 30 ngày hoạt động”.

Confidence (Shared)

• Mục tiêu: Giải thích độ tin cậy theo cỡ mẫu.
• Tiers: Low <10, Medium 10–49, High ≥50. Không tham gia tính Impact.

Average progress & Required threshold (Shared)

• Average progress: trung bình kết quả các dạng của skill.
• Required threshold: ngưỡng nên đạt theo mục tiêu. Nếu skill dùng %, hệ thống tự quy đổi và hiển thị gợi ý.

Submission Counting Rule (Shared)

• Mọi bài tập user đã nộp hợp lệ đều được tính vào chỉ số học tập.
• Rule này không phụ thuộc account tier (Free, Pro, Pro Max).
• Tier chỉ ảnh hưởng phạm vi nội dung user xem/được mở khoá, không ảnh hưởng việc ghi nhận nỗ lực đã nộp bài.

Engagement Ranking Baseline (DOL English V2)

• Cross-area/community/global ranking đọc từ LearningPointsWeek.
• Module-level surfaces có thể show PracticePointsWeek hoặc VocabCarePointsWeek như breakdown theo ngữ cảnh.
• Current rollout không dùng user/account level.
• badge, streak, certificate, và achievement surfaces là lớp recognition riêng; mặc định không làm đổi công thức rank.

AI Tutor Progress Insight Contract (V2)

• Trigger policy:
  • chỉ render progress insight khi user hỏi trực tiếp (on_user_request_only).
  • không tự đẩy insight như auto-popup bắt buộc.
• Metric window policy:
  • ưu tiên thứ tự today -> 7_day -> 30_day khi dữ liệu tồn tại.
  • nếu thiếu dữ liệu cho window user hỏi, fallback về window gần nhất có dữ liệu và gắn note minh bạch.
• Response shape tối thiểu:
  • window: khung thời gian đang diễn giải,
  • signal: chỉ số chính (ví dụ completion, streak, trend score),
  • meaning: diễn giải ngắn dễ hành động,
  • next_action: tối thiểu 1 bước học tiếp theo.
• Provenance policy:
  • insight phải có source class (history, practice, course, hoặc general_fallback khi thiếu dữ liệu platform).
  • nếu rơi vào general_fallback, bắt buộc có disclaimer giới hạn dữ liệu.
  • provenance depth hỗ trợ compact|standard|detailed:
    • default theo segment (new learner = compact, active/high-attention = standard),
    • detailed mở theo on-demand action.
• Guardrail:
  • không dùng insight để gắn nhãn tiêu cực learner.
  • wording phải theo nguyên tắc khích lệ của verdict model.

AI-assisted UI action for progress insight

• Khi user chấp nhận guidance từ AI Tutor trên bề mặt Learning Management, hệ thống được phép:
  • mở đúng metric window/tab liên quan (today, 7_day, 30_day),
  • reveal/focus card hoặc block metric tương ứng,
  • highlight signal chính đang được AI diễn giải,
  • focus CTA tiếp theo nếu CTA đó là action an toàn đã đăng ký.
• Không auto-run các action có impact nhạy cảm:
  • thay đổi dữ liệu học tập,
  • submit/request ra ngoài,
  • payment/upgrade,
  • delete/reset.
• Nếu metric window hoặc target block không tồn tại:
  • vẫn mở surface Learning Management hợp lệ,
  • fallback về block metric gần nhất có dữ liệu,
  • hiển thị notice ngắn thay vì hard fail.

DOL English Web V2 - Scoring & KPI Baseline

• Score bands (chuẩn mới):
  • 0-19: Chưa đạt
  • 20-59: Cần cải thiện
  • 60-79: Khá
  • 80-99: Giỏi
  • 100: Xuất sắc
• Với bài dùng thang điểm khác (vd IELTS band):
  • normalize theo điểm tối đa về % trước khi map band.
• Objective unanswered:
  • câu bỏ trống tính sai.
• KPI pack tối thiểu:
  • Primary: habit_retention (>=4 ngày học/tuần trong 4 tuần liên tiếp).
  • Secondary growth: locked_feature_upgrade_conversion.
  • Secondary quality: recommendation_to_attempt_rate.
• KPI mapping contract (measurement layer):
  • habit_retention lấy từ streak + completed_days_weekly windows.
  • locked_feature_upgrade_conversion lấy từ locked_ai_entry_click -> checkout_success_from_locked_entry.
  • recommendation_to_attempt_rate lấy từ recommendation_render_event -> recommendation_attempt_start_event.

KPI Operational Contract (V2)

• Review cadence:
  • daily D-1 monitor,
  • weekly KPI review,
  • monthly policy review.
• Denominator normalization:
  • habit_retention: rolling 4-week cohort trên valid completed-day signals,
  • recommendation_to_attempt_rate: chỉ tính item recommendation thực sự được render và visible,
  • locked_feature_upgrade_conversion: đo từ locked-entry exposure đến checkout success trong attribution window.
• Guardrail thresholds (default):
  • habit_retention giảm >5pp WoW -> mở investigation,
  • recommendation_to_attempt_rate giảm >8pp WoW -> mở recommendation quality audit,
  • locked_feature_upgrade_conversion giảm >10pp WoW -> mở paywall/offer audit.
• Escalation path:
  • 1 tuần breach: ghi diagnosis note,
  • 2 tuần breach liên tiếp: mở experiment ticket,
  • 3 tuần breach liên tiếp: bắt buộc policy review.
• Mandatory KPI cuts:
  • theo program,
  • theo tier,
  • theo cold_start vs returning.

First-week Activation Indicators (V2)

• Mục tiêu:
  • đo chất lượng kích hoạt hành vi ở 7 ngày đầu sau signup.
• Chỉ số dẫn dắt (leading indicators):
  • activation_first_attempt_24h: tỷ lệ user mới có bài nộp đầu tiên trong 24h đầu.
  • activation_second_attempt_48h: tỷ lệ user mới có bài nộp thứ hai trong 48h kể từ bài đầu.
  • activation_week1_active_days_ge3: tỷ lệ user mới đạt >=3 ngày active trong tuần đầu.
  • activation_card_cta_click_rate: tỷ lệ click CTA từ activation card trên Home.
  • activation_week1_completion_rate: tỷ lệ hoàn thành đủ ladder tuần đầu.
• Chỉ số chẩn đoán chất lượng activation theo program:
  • activation_program_resolution_source_distribution: phân bổ nguồn resolve program (goal | intent | fallback).
  • activation_week1_completion_by_program_source: tỷ lệ hoàn thành week-1 theo nguồn resolve program.
  • activation_step2_same_program_continuity_rate: tỷ lệ step-2 giữ được continuity cùng program.
• Boundary:
  • nhóm chỉ số này là leading indicator để phát hiện friction sớm,
  • không thay thế KPI priority chính (habit_retention vẫn là north priority).

Improvement Evidence Model (V2)

• Bằng chứng tiến bộ có thể đến từ nhiều track song song:
  • 2 lần mock test liên tiếp có xu hướng tăng,
  • điểm trung bình tuần này so với tuần trước,
  • điểm trung bình tháng này so với tháng trước,
  • điểm trung bình chu kỳ 3 tháng so với 3 tháng trước,
  • xu hướng 5 lần làm bài gần nhất tăng dần và không giảm mạnh.
• Sharp-drop detection:
  • dùng ngưỡng hybrid (% drop + program-scale drop),
  • hệ thống lấy điều kiện nghiêm ngặt hơn làm cảnh báo.
• Baseline giai đoạn đầu:
  • dùng shared threshold cho toàn bộ chương trình,
  • review lại sau 4 tuần dữ liệu thực tế.

Decline Detection & Light Intervention (V2)

• Decline detection dùng OR logic:
  • Signal A: 2 lần mock test liên tiếp bị giảm điểm.
  • Signal B: điểm trung bình 7 ngày gần nhất giảm >=10% so với 7 ngày trước đó.
• Nếu một trong hai signal kích hoạt:
  • gắn trạng thái dang_tut_phong_do.
• Intervention policy:
  • chỉ can thiệp nhẹ (light-touch),
  • hệ thống gợi ý phục hồi, không chặn luồng học bình thường.
  • skip rescue-pack được phép, không có penalty.
  • re-prompt rescue-pack chỉ khi có new decline signal, không nhắc lại theo lịch thời gian.
  • new decline signal chỉ hợp lệ sau khi learner đi qua ít nhất 1 recovery period.
  • recovery period tối thiểu: hoàn thành 1 bài tương tự (không cần đúng bài trong rescue-pack).
  • nếu decline mới xuất hiện trong lúc cooldown prompt còn hiệu lực:
    • không bật prompt immediate mới,
    • vẫn giữ rescue-pack ở Practice Management.

Recovery Quality Thresholds (V2 default)

• Similarity ladder:
  • Tier A: cùng program + cùng skill + cùng dạng bài + chênh lệch độ khó <=1.
  • Tier B: cùng program + cùng skill.
  • Tier C: cùng skill trong cùng program.
• Tier C guardrail:
  • chỉ cho phép khi inventory Tier A+B <3.
• Practice-time thresholds:
  • Reading >=8m, Listening >=8m, Writing >=12m, Speaking >=12m.
• Completion-ratio thresholds:
  • Objective >=70%,
  • Subjective >=60%.
• Recovery reset:
  • chỉ cần 1 bài tương tự hợp lệ để reset cooldown.
  • reset theo skill within program.
  • với Writing/Speaking chỉ reset sau khi async scoring hoàn tất.

Threshold Governance Cadence (V2)

• Freeze threshold mặc định trong 3 tháng đầu rollout.
• Sau giai đoạn freeze:
  • review threshold theo chu kỳ tháng.
• Mục tiêu:
  • tránh thay đổi rule quá dồn dập trong giai đoạn đầu,
  • vẫn giữ khả năng tối ưu dần theo dữ liệu thực.

Progress Verdict Cadence (V2)

• Cadence:
  • theo dõi weekly pulse,
  • chốt official monthly verdict.
• Learner verdict levels:
  • Can co gang,
  • Dang on,
  • Dang tien bo tot.
• Với learner có goal:
  • xét trend + khoảng cách tới goal.
  • không chốt verdict dựa vào 1 lần làm bài đơn lẻ.
• Với learner chưa có goal:
  • xét trend + diligence.
  • số lượng bài làm không đủ để kết luận nếu thiếu tín hiệu chất lượng.
• Language guardrail:
  • dùng wording khích lệ, tránh pass/fail cứng.

Recovery Status & High-attention (V2)

• Recovery visibility:
  • hiển thị provisional recovery ngay sau kết quả hợp lệ.
  • chỉ xác nhận official recovery trong weekly pulse.
• High-attention threshold:
  • learner vào trạng thái high_attention khi không recovery trong 2 chu kỳ liên tiếp.
• Escalation:
  • khi vào high_attention, kích hoạt AI Tutor adaptive recovery plan (guidance-only, non-blocking).

AI Tutor Adaptive Recovery Plan Policy (V2)

• Step structure:
  • 1 bước now,
  • 1-2 bước next,
  • tối đa 1 bước optional (bonus).
• Plan regeneration:
  • chỉ regenerate khi learner vẫn high_attention và plan hiện tại không còn phù hợp với context mới.
• High-attention exit:
  • thoát high_attention khi có 1 lần official recovery (weekly pulse).
• Required sourcing:
  • ưu tiên skill yếu nhất trong program hiện tại.
• Low-inventory fallback:
  • dùng ladder A -> B -> C trong cùng program.
• Program switch rule:
  • nếu đổi program giữa plan, kế hoạch hiện tại giữ nguyên cho đến khi user refresh hoặc AI regenerate theo context mới.
• Missed-step handling:
  • bước bỏ lỡ không carry-forward.
  • tiếp tục theo bước ưu tiên hiện tại của plan.
• Completion semantics:
  • bước now hoàn thành khi có submission hoặc tín hiệu completion hợp lệ của step liên kết.
  • bước optional chỉ là bonus; không thay thế bước now, không ảnh hưởng rule thoát high-attention.

Diligence Score & Active-time Rules (V2)

• Diligence hybrid score:
  • 40% số ngày có nộp bài trong tuần,
  • 40% số bài hoàn thành trong tuần,
  • 20% thời gian học chủ động trong tuần.
• Active-time counting:
  • chỉ tính tương tác thực (click/type/scroll/audio),
  • tự tạm dừng khi không có tương tác,
  • timeout mặc định: 90s,
  • có tương tác mới thì tự resume.

Exam specifics

• IELTS: xem IELTS/IELTS_Metrics.md.
• SAT: xem SAT/SAT_Metrics.md.
• TOEIC: xem TOEIC/TOEIC_Metrics.md.
• DGNL: xem DGNL/DGNL_Metrics.md.
• K12: xem K12/K12_Metrics.md.

Change log

• 2026-03-11: Bổ sung AI-assisted UI action cho progress insight trong Learning Management: open window/tab, reveal/focus card, highlight signal, và protected-action boundary.
• 2026-03-09: Bổ sung baseline engagement ranking cho DOL English V2: cross-area rank dùng LearningPointsWeek, giữ breakdown theo module, chưa dùng user/account level, và tách recognition layers khỏi rank formula.
• 2026-03-01: Bổ sung provenance depth policy cho progress insight (compact|standard|detailed on-demand) theo DEC-0091.
• 2026-03-01: Bổ sung AI Tutor progress-insight contract: trigger on-demand, metric window fallback (today/7-day/30-day), response shape window->signal->meaning->next_action, và provenance/disclaimer policy.
• 2026-02-22: Bổ sung metrics chẩn đoán cho program-adaptive activation: distribution theo nguồn resolve program, completion theo source, và continuity rate ở step-2.
• 2026-02-22: Bổ sung nhóm chỉ số dẫn dắt first-week activation (24h bài đầu, 48h bài thứ hai, >=3 ngày active tuần đầu, activation card CTR, activation week-1 completion) và boundary “leading indicator only”.
• 2026-02-21: Bổ sung goal engine V1 refinement: depth theo program + assessment form + skill, mapping whitelist-only cho normalized mode, primary/secondary + goal-versioning, và confidence gate >=3 comparable attempts/30 active days trước khi hiển thị numeric gap.
• 2026-02-21: Chốt baseline so sánh mục tiêu theo program + assessment form; thêm compatibility modes direct | normalized | not_comparable và fallback UX khi không so sánh trực tiếp được.
• 2026-02-20: Bổ sung KPI operational contract: cadence monitor/review, denominator normalization, guardrail thresholds, escalation path, và segmentation baseline.
• 2026-02-18: Bổ sung policy recovery-status/provisional-vs-official, high-attention escalation, và AI Tutor adaptive recovery plan rules (structure, regeneration, sourcing, missed-day, completion semantics).
• 2026-02-18: Bổ sung recovery quality thresholds mặc định (similarity ladder A/B/C, thời lượng theo skill, completion ratio objective/subjective) và threshold review cadence (freeze 3 tháng rồi review theo tháng).
• 2026-02-18: Bổ sung decline detection OR logic (2 mock giảm liên tiếp hoặc giảm >=10% giữa 2 cửa sổ 7 ngày), light-touch intervention, và verdict cadence tuần/tháng 3 mức.
• 2026-02-18: Bổ sung improvement evidence model đa khung thời gian và diligence/active-time rules (40/40/20, inactivity timeout 90s).
• 2026-02-18: Bổ sung chuẩn score bands mới, normalization contract, và KPI mapping contract (habit retention, locked-feature conversion, recommendation-to-attempt).
• 2026-02-17: Bổ sung rule tính chỉ số học tập cho mọi bài đã nộp bất kể tier.
• 2025-11-13: Chuẩn hoá Impact chỉ hiển thị ở 30 ngày hoạt động (30d/1y/Lifetime).
• 2025-11-13: Đồng bộ đơn vị hiển thị (% vs điểm) và Confidence tiers/tooltip Impact trên mọi program.