Bỏ qua để đến nội dung
DOL Wiki

Practice Flow - Entry Routing Contracts

DomainsDOL EnglishUX3.245 words16 min read
activebyDOL Product Design

Practice Flow - Entry Routing Contracts (Home and Course)

Phần tiêu đề “Practice Flow - Entry Routing Contracts (Home and Course)”

Purpose

Phần tiêu đề “Purpose”
  • Vấn đề: Entry vào flow làm bài đến từ nhiều nguồn nên dễ đứt context nếu không có contract route chung.
  • Đối tượng chính: Team thiết kế/triển khai deeplink và điều hướng vào attempt/result.
  • Tín hiệu thành công: Mọi điểm vào PRA đều xác định được nguồn, chương trình, đường quay lại, và trạng thái recommendation liên quan.

Alignment note

Phần tiêu đề “Alignment note”
  • File này chỉ giữ contract deeplink/handoff vào owner flow Luyện tập.
  • Nó không redefine shell rule của resume last program -> Program Workspace và không tạo entry surface độc lập ngoài PRA.

Elements / Scope

Phần tiêu đề “Elements / Scope”
  • Entry sources:
    • Home & Discovery -> Exercise Bank.
    • Course Management -> Course Detail.
    • Practice Management -> Recommendation actions.
  • Required routing params:
    • source_context
    • program
    • exercise_id
    • returnTo
  • Optional params:
    • bank_id
    • challenge_id
    • attempt_mode (untimed | timed)
    • ai_action_source (home_ai | search_ai_inline | ai_tutor)
    • ai_target_key
    • ai_highlight_mode (ring | pulse | spotlight)
    • ai_prefill_controls
    • ai_reveal_panel
    • attempt_resume_key
    • attempt_submit_idempotency_key
    • attempt_draft_retention_ttl_days
    • timed_pause_policy
    • timed_background_timer_policy
    • submit_auto_retry_max
    • submit_support_cta_after_auto_retry_exhausted
    • submit_review_summary_mode
    • recommendation_strategy
    • recommendation_reason_label
    • recommended_skill
    • recommended_difficulty
    • recommended_duration
    • decline_state
    • rescue_pack_version
    • rescue_prompt_cooldown_until
    • auth_gate_reopen_cooldown_seconds
    • reactivation_intent_stage
    • reactivation_seed_program_id
    • reactivation_seed_skill_id
    • reactivation_entry_session_id
    • activation_entry (true | false)
    • activation_step (step1_first_attempt | step2_second_attempt_48h)
    • activation_program_resolution_source (goal_program | last_program_intent_14d | trending_easy_available_program)
    • activation_step1_submission_id
    • activation_continuity_target_assessment_form_id

Logic

Phần tiêu đề “Logic”
  • Thiếu required params thì không được vào attempt.
  • returnTo phải trỏ về màn nguồn tương ứng với source_context.
  • Nếu returnTo không còn hợp lệ/hết hạn, fallback theo thứ tự:
    • route hợp lệ gần nhất trong cùng skill/program,
    • route hợp lệ cấp program,
    • onboarding / program choice / discovery (chỉ khi không có route contextual hợp lệ).
  • Entry từ Home phải giữ được context program + bank.
  • Entry từ Course phải giữ được context khóa học để result map đúng nguồn.
  • Entry từ recommendation phải giữ đủ metadata để đo lường và tái tạo state.
  • Entry từ activation card phải giữ metadata step/source để đo continuity và hiệu quả week-1 activation.
  • Attempt execution contracts:
    • default attempt_mode = untimed nếu source không truyền mode rõ ràng,
    • attempt_resume_key dùng để gắn draft state khi user quay lại attempt chưa nộp,
    • attempt_submit_idempotency_key dùng để đảm bảo submit chỉ finalize một lần.
    • attempt_draft_retention_ttl_days = 7 cho untimed draft.
    • timed_pause_policy = no_manual_pause.
    • timed_background_timer_policy = timer_continues.
    • submit_auto_retry_max = 3 cho lỗi transient.
    • submit_support_cta_after_auto_retry_exhausted = true.
    • submit_review_summary_mode = total_first_expandable_by_section.

Recommendation routing contracts

Phần tiêu đề “Recommendation routing contracts”
  • recommendation_priority = habit_first.
  • recommendation_set_size = dynamic(3..7).
  • recommendation_default_size = 5.
  • recommendation_low_inventory_min = 3.
  • recommendation_default_mix = 2_habit + 2_target + 1_explore.
  • recommendation_reason_label_policy = exactly_one_primary_reason_per_item.
  • recommendation_primary_reason_priority_order = recovery_critical -> goal_aligned -> habit_continuity -> freshness -> trending_fallback.
  • recommendation_confidence_levels = high | medium | low.
  • recommendation_low_confidence_cap_per_set = 1_when_inventory_allows.
  • recommendation_low_confidence_position = near_end.
  • recommendation_refresh_trigger = on_submit | manual_refresh.
  • recommendation_ignore_streak_threshold = 3.
  • recommendation_ignore_definition = no_click | click_no_submit.
  • recommendation_ignore_eval_timing = end_of_session(30m_idle_or_exit).
  • recommendation_strategy_adaptation_order = difficulty -> format -> skill.
  • recommendation_feedback_scope = cluster_like_dislike.
  • recommendation_dislike_persistence = next_clusters.
  • recommendation_feedback_does_not_reset_ignore = true.
  • recommendation_repetition_cap_per_skill = 3.
  • recommendation_topic_repetition_cap_per_set = 2.
  • recommendation_freshness_min_per_set = 1_when_inventory_allows.
  • recommendation_freshness_window_days = 14.
  • recommendation_freshness_definition = not_attempted_14d_or_same_skill_new_format.
  • recommendation_manual_controls = skill | difficulty | duration.
  • recommendation_manual_preference_ttl = session.
  • recommendation_manual_controls_mode = soft_priority.
  • recommendation_manual_controls_scope = session_cross_surface.
  • recommendation_no_match_policy = nearest_ladder_with_notice.
  • recommendation_refresh_without_action_threshold = 2.
  • recommendation_refresh_without_action_next_set_alt_skill_min = 1.
  • cold_start_source = trending_14d + easy_start_bias.
  • inventory_fallback_policy = nearest_ladder.
  • recommendation_available_now_priority = true.
  • recommendation_locked_teaser_cap_per_set = 1_when_inventory_sufficient.
  • recommendation_locked_teaser_position = end_of_set.
  • recommendation_locked_teaser_label = lock_reason_plus_minimum_eligible_plan.
  • recommendation_available_now_shortage_relax_order = same_program_assessment_form_skill_nearest_ladder_then_locked_with_notice.
  • reactivation_seed_mode = one_time_first_set_in_session.
  • reactivation_seed_quick_win_min = 1_when_inventory_allows.
  • reactivation_seed_confidence_preference = high_or_medium_preferred.
  • reactivation_seed_expire_on = first_attempt_start_or_session_end.
  • reactivation_seed_stage_profile = lost_streak_or_1w__quick_win_last_skill | 1m_1y_q3__quick_win_plus_trending_new.
  • activation_program_resolution_order = goal_program -> last_explicit_program_intent_14d -> trending_easy_available_program.
  • activation_primary_duration_target = 5_10_minutes.
  • activation_swap_options_cap = 2_when_inventory_allows.
  • activation_step2_continuity_policy = same_program_plus_nearest_assessment_form.
  • activation_program_fallback_policy = in_program_nearest_ladder_then_cross_program_easy_start_with_notice.

Rescue-pack routing contracts (decline support)

Phần tiêu đề “Rescue-pack routing contracts (decline support)”
  • decline_state = dang_tut_phong_do kích hoạt entry rescue-pack.
  • rescue_pack_touchpoints = immediate_prompt | practice_management_persistent.
  • rescue_pack_composition = fixed_warmup_1 + personalized_2.
  • rescue_pack_prompt_style = inline_non_blocking.
  • rescue_pack_mandatory = false.
  • rescue_pack_sequence_forced = false.
  • rescue_pack_immediate_prompt_cooldown_days = 7.
  • rescue_pack_reprompt_policy = only_on_new_decline_signal.
  • new_decline_signal_requires_recovery_period = true.
  • recovery_period_min_condition = complete_1_similar_exercise.
  • cooldown_reset_trigger = complete_1_similar_exercise.
  • similarity_ladder = tier_a | tier_b | tier_c.
  • similarity_tier_a = same_program + same_skill + same_type + difficulty_delta_lte_1.
  • similarity_tier_b = same_program + same_skill.
  • similarity_tier_c = same_skill_within_program.
  • tier_c_eligibility_cutoff = inventory_tier_a_plus_b_lt_3.
  • fallback_cross_program_allowed = false.
  • recovery_quality_gate = practice_time + completion_ratio.
  • practice_time_default = reading_8m | listening_8m | writing_12m | speaking_12m.
  • completion_ratio_default = objective_gte_70 | subjective_gte_60.
  • reset_scope = skill_within_program.
  • reset_chain_required = false (1 bài hợp lệ là đủ).
  • reset_eval_timing = result_ready_only.
  • reset_eval_timing_async = wait_scoring_complete.
  • threshold_review_cadence = freeze_3_months_then_monthly_review.
  • reset_checklist_visibility = concise_user_facing.
  • Nếu decline mới xuất hiện trong khi cooldown còn hiệu lực:
    • không hiển thị immediate prompt mới,
    • vẫn giữ rescue-pack ở Practice Management.

High-attention & AI Tutor adaptive recovery plan contracts

Phần tiêu đề “High-attention & AI Tutor adaptive recovery plan contracts”
  • high_attention_trigger = non_recovery_2_consecutive_cycles.
  • recovery_status_visibility = provisional_after_result | official_weekly_pulse.
  • ai_tutor_plan_mode = guidance_only_non_blocking.
  • ai_tutor_plan_singleton = one_active_plan_per_account.
  • ai_tutor_plan_step_structure = now_1 + next_1_to_2 + optional_0_to_1.
  • ai_tutor_plan_refresh = when_context_or_progress_changes_meaningfully.
  • high_attention_exit = one_official_recovery_confirmation.
  • plan_sourcing_priority = weakest_skill_in_current_program.
  • ai_tutor_plan_program_switch_policy = keep_current_plan_until_refresh.
  • priority_step_completion_definition = submit_or_complete_linked_step.
  • ai_tutor_plan_completion_attribution = completion_timestamp.
  • missed_priority_step_policy = no_step_debt.
  • optional_role = bonus_only_no_required_replacement.
  • ai_tutor_plan_nudge_scope = active_plan_priority_step_only.
  • ai_tutor_plan_nudge_channels = in_app + web_push.
  • ai_tutor_plan_nudge_cap = contextually_throttled.
  • ai_tutor_plan_nudge_slot = adaptive_local_window.
  • ai_tutor_plan_nudge_pre_check = skip_if_priority_step_completed.
  • ai_tutor_plan_nudge_stop = immediate_after_priority_step_completion.
  • ai_tutor_plan_nudge_permission_fallback = in_app_only_if_web_push_unavailable.
  • ai_tutor_plan_nudge_not_logged_in = no_forced_catchup.
  • ai_tutor_plan_state_on_next_login = show_current_priority_step_only.
  • ai_tutor_plan_nudge_timezone_change_effective = next_local_window.
  • ai_tutor_plan_nudge_consistency_scope = account_cross_device.
  • ai_tutor_plan_nudge_deeplink = practice_management_highlight_priority_step.
  • ai_tutor_plan_step_unavailable_fallback = tier_a_to_b_to_c_with_notice.

AI-assisted UI action routing contracts

Phần tiêu đề “AI-assisted UI action routing contracts”
  • ai_ui_action_execution_model = ai_decides_client_executes_registered_action.
  • ai_ui_target_binding = semantic_target_key_only.
  • ai_ui_allowed_action_families = navigate | reveal_focus | highlight | lightweight_set_state.
  • ai_ui_reversible_set_state_scope = recommendation_controls | practice_filters | tab_switch.
  • ai_ui_protected_actions = submit_attempt | finalize_answer | payment | delete | external_send.
  • ai_ui_protected_actions_mode = confirm_or_block.
  • ai_ui_missing_target_policy = open_route_then_fallback_with_notice.
  • ai_ui_attempt_guardrail = no_answer_or_input_mutation_inside_active_attempt.
  • ai_ui_result_assist_scope = highlight_feedback | open_next_exercise | open_progress | open_vocab.

UI / Behavior

Phần tiêu đề “UI / Behavior”
  • Trước khi start attempt, hệ thống xác thực route context.
  • Route lỗi thì điều hướng về màn nguồn gần nhất và báo hướng dẫn ngắn.
  • Kết thúc result, CTA quay lại dùng returnTo đã lưu.
  • Recommendation panel cho phép user chỉnh nhanh skill | difficulty | duration không rời màn hình.
  • Nếu entry/handoff đến từ AI:
    • route mở đúng màn PRA tương ứng trước,
    • sau đó mới reveal/focus/highlight target đã đăng ký,
    • nếu có ai_prefill_controls, chỉ apply với controls cục bộ có thể đảo ngược,
    • không được auto mutate câu trả lời trong active attempt.
  • Nếu entry đến từ AI Tutor plan nudge:
    • mở Practice Management,
    • highlight priority step hiện tại.
  • Recovery trạng thái hiển thị checklist 3 dòng:
    • Bài tương tự,
    • Thời lượng đủ,
    • Hoàn thành đủ.

State model / Edge cases

Phần tiêu đề “State model / Edge cases”
  • Invalid exercise_id: fallback về bank hoặc course tab chứa bài.
  • Expired returnTo: fallback route hợp lệ gần nhất trong cùng program/skill; nếu không có thì fallback Home.
  • Program mismatch: ưu tiên context từ source screen và sửa route trước khi start.
  • Attempt mode missing: fallback về untimed.
  • Draft TTL expired: không resume draft cũ; điều hướng vào phiên attempt mới sạch.
  • Auth gate dismissed at attempt-start: giữ nguyên trang hiện tại, không start attempt, không ghi nhận attempt event.
  • Auth gate retrigger during cooldown: trong 3s sau dismiss, giữ nguyên trang hiện tại, không start attempt, không ghi nhận attempt event.
  • No-history/no-goal: recommendation mặc định từ trending gần đây + easy-start bias.
  • Recommendation ignored >= 3: đổi chiến lược gợi ý ở lần render kế tiếp.
  • Freshness guardrail unavailable due to low inventory: relax theo nearest-ladder và hiển thị notice ngắn.
  • Manual refresh >=2 without action: set kế tiếp phải có ít nhất 1 item khác skill.
  • Entry via reactivation reminder click: set đầu tiên nhận seed boost 1 lần theo intent stage.
  • Reactivation seed inventory missing: fallback trending_14d + easy_start_bias.
  • Reactivation seed expired: sau attempt đầu tiên hoặc hết session thì quay lại baseline recommendation engine.
  • Entry via activation card step-1: ưu tiên quick-start item và lưu activation_step1_submission_id sau submit thành công.
  • Entry via activation card step-2: ưu tiên cùng program + assessment-form continuity theo activation_step1_submission_id (khi có dữ liệu).
  • Activation source missing: fallback resolve theo goal_program -> last_program_intent_14d -> trending_easy_available_program.
  • Activation selected program no starter available: nới in-program nearest-ladder trước, rồi mới cross-program fallback + notice.
  • Entitlement-aware composer: ưu tiên available-now; locked teaser (nếu có) ở cuối set.
  • Low-confidence overflow: khi inventory đủ mà số item low > 1, composer phải thay/bỏ bớt để giữ max 1 item low-confidence/set.
  • Available-now inventory low: nới nearest-ladder trước khi tăng locked items; luôn kèm notice ngắn.
  • Session-end contract: kết thúc session khi 30m idle hoặc user thoát session.
  • Rescue skipped: không chặn luồng học; chỉ lưu signal và giữ entry ở Practice Management.
  • Rescue cooldown active: không phát lại immediate prompt trước khi cooldown hết.
  • New decline during cooldown: không phá cooldown; chờ đủ điều kiện re-prompt.
  • Recovery by similar exercise: hoàn thành 1 bài tương tự là đủ để reset cooldown.
  • Async-scored recovery: Writing/Speaking chỉ xét reset khi score đã sẵn sàng.
  • High-attention active: hiển thị plan entry nhưng không khóa các entry học khác.
  • Program switched mid-cycle: giữ plan cũ đến hết cycle, đánh dấu regenerate ở cycle kế.
  • Missed priority step: không tạo debt, không tạo catch-up queue.
  • Not logged in at nudge slot: không gửi bù; login sau chỉ thấy priority-step state hiện tại.
  • Required completed before slot: skip gửi reminder của ngày đó.
  • Required completed on another device: dừng reminder cùng ngày cho toàn bộ thiết bị/kênh của account.
  • Timezone changed in-day: chỉ áp dụng timezone mới từ ngày kế tiếp.
  • Priority step unavailable: auto thay step bằng ladder A -> B -> C và hiển thị notice ngắn.
  • Invalid ai_target_key: vẫn mở route PRA hợp lệ; fallback về block tổng quan/recommendation gần nhất và hiển thị notice ngắn.
  • Protected AI action requested: không auto-run; chuyển sang CTA confirm hoặc bỏ qua action đó.

Dependencies / Integration

Phần tiêu đề “Dependencies / Integration”
  • Home & Discovery và Course Management là nguồn route.
  • Practice Management là nguồn entry cho recommendation action.
  • Practice Flow nhận route và xử lý attempt/result.
  • Register/Auth giữ session hợp lệ trước khi start attempt.

References

Phần tiêu đề “References”

Change log

Phần tiêu đề “Change log”
  • 2026-03-11: Bổ sung AI-assisted UI action routing contracts cho PRA: semantic target keys, reveal/focus/highlight, lightweight set-state, và protected-action boundary.
  • 2026-02-22: Bổ sung activation-entry routing contracts cho tuần đầu: metadata step/source (activation_step, activation_program_resolution_source), continuity target cho step-2, và fallback policy in-program trước cross-program.
  • 2026-02-22: Bổ sung recommendation routing contracts cho explainability/confidence: 1 primary reason theo priority cố định, confidence high|medium|low, cap low-confidence tối đa 1/set (khi inventory đủ) và ưu tiên seed quick-win ở mức high/medium.
  • 2026-02-22: Bổ sung contracts cho entitlement-aware recommendation composition: available-now priority, lock teaser cap/position/label và shortage-relax order.
  • 2026-02-22: Bổ sung entry contracts cho reactivation-intent handoff: payload stage/seed, one-time first-set quick-win boost và expiry theo attempt/session.
  • 2026-02-22: Bổ sung routing contracts cho recommendation freshness: quota item mới tối thiểu, cap topic, và diversify theo khác skill sau 2 lần manual refresh liên tiếp không có action.
  • 2026-02-21: Thêm deep contracts cho attempt execution: draft TTL 7 ngày (untimed), timed no-pause + background timer continuity, submit auto-retry max=3, support CTA sau retry exhaust, và submit review summary mode.
  • 2026-02-21: Bổ sung attempt execution contract fields: attempt_mode, attempt_resume_key, attempt_submit_idempotency_key; và fallback default untimed khi thiếu mode.
  • 2026-02-20: Precision round 3: mở rộng fallback ladder (same skill/program -> program route -> Home) và thêm edge-case cooldown 3s khi user đóng rồi bấm lại auth gate attempt-start.
  • 2026-02-20: Precision round 2: chuẩn hóa returnTo fallback hierarchy (nearest contextual route trước Home) và bổ sung edge-case khi user đóng auth gate ở attempt-start.
  • 2026-02-18: Bổ sung contract AI Tutor plan nudge (context throttle, no forced catch-up, stop ngay khi priority step hoàn thành, consistency account-level, deeplink highlight, timezone next-window, fallback khi step unavailable).
  • 2026-02-18: Bổ sung contracts cho high-attention và AI Tutor adaptive recovery plan (trigger, step structure, refresh, program-switch, completion semantics).
  • 2026-02-18: Bổ sung similarity ladder A/B/C, quality thresholds mặc định, reset timing result-ready, và cadence review threshold (freeze 3 tháng -> review theo tháng).
  • 2026-02-18: Bổ sung rescue-pack routing contracts (touchpoints, inline prompt, cooldown 7 ngày, new-decline + recovery reset rules).
  • 2026-02-18: Bổ sung recommendation routing contracts (dynamic 3..7, reason label, adaptive ignore, manual controls, refresh triggers, cold-start source).
  • 2026-02-11: Liên kết Entry Routing Contracts với Smart Search Platform để chuẩn hóa deeplink params từ kết quả search.
  • 2026-02-07: Khởi tạo contract route vào Practice Flow từ Home Exercise Bank và Course Detail.