Practice Flow - Result Flow

Shell Fit

• Result là owner flow sau submit của Luyện tập; nó không thay thế Hôm nay, Tiến độ, hoặc Khóa học.
• Các summary card hoặc recommendation surfaces chỉ surfacing result signal; deeplink xem sâu phải quay về result context thật của PRA.

Purpose

• Chuẩn hoá flow sau khi nộp bài để mọi tier dùng cùng một result surface.
• Làm rõ phần lock/unlock theo Free / Pro / Pro Max.
• Chốt luồng nâng cấp ngay trong context đang học để giảm rơi rụng.
• Chuẩn hóa recommendation sau result theo hướng habit-first, động và dễ hiểu.

Core Flow

1. User nộp bài thành công (normal submit hoặc timeout-submit từ timed mode).
2. Hệ thống luôn đưa user tới trang kết quả.
3. Nếu bài thuộc nhóm có AI scoring (đặc biệt Writing/Speaking):
   • hiển thị trạng thái loading AI đang chấm.
4. Khi AI chấm xong:
   • hiển thị nội dung kết quả theo entitlement của tài khoản.
   • luôn tạo notification-center entry cho trạng thái score-ready.
   • có thể gửi thêm toast/web-push 1 lần nếu user bật kênh.
   • không nhắc lặp lại cho cùng sự kiện score-ready.
5. Recommendation list được refresh sau submit, đồng thời user có quyền manual refresh.
6. Nếu nguồn nộp là timeout-submit:
   • result hiển thị nhãn ngắn Hết giờ - đã nộp tự động,
   • pipeline chấm điểm/metrics giữ như submit thường.

Submit Failure Handoff

• Nếu submit chưa thành công (kể cả sau auto-retry):
  • user vẫn ở attempt context để manual retry,
  • chưa chuyển sang result cho đến khi có submission thành công,
  • support CTA được hiển thị khi auto-retry đã hết ngưỡng.

Unified Result Surface (Same UI, Different Access)

• Cùng một bố cục trang kết quả cho tất cả user.
• Khác biệt nằm ở trạng thái section:
  • mở khoá,
  • hoặc khoá theo gói.

AI Analysis Surface Contract

• Result không được dừng ở score-only; baseline phải có AI Analysis Panel ngay dưới phần kết quả chính.
• Result dùng analysis_panel làm archetype mặc định:
  • trình tự đọc nên là signal -> meaning -> priority fix -> next action,
  • evidence chỉ hiện khi gắn trực tiếp với lỗi/nhận xét đang nói tới,
  • không ép dùng layout action-first kiểu Home hay queue-guide kiểu Course/Vocab.
• Với Reading/Listening/objective result, AI Analysis Panel tối thiểu phải có:
  • main mistakes hoặc error clusters,
  • evidence / vì sao sai,
  • priority fixes,
  • review pack hoặc CTA review lỗi ngay,
  • vocab extraction khi payload hợp lệ,
  • next-step action.
• Với Writing/Speaking sau submit, AI surface nên render như Feedback Workspace thay vì panel ngắn:
  • đây là biến thể analysis_panel.expanded, không phải một card summary chung,
  • rubric / score bands,
  • priority fixes,
  • rewrite / re-record plan,
  • compare-to-stronger-version khi đủ evidence và entitlement.
• Nếu user mở AI Tutor từ result:
  • drawer/tab mặc định là Phân tích,
  • conversation phải giữ continuity với result context hiện tại,
  • AI có thể deep-link sang review pack, similar exercise, progress, hoặc vocabulary tùy output.
• Nếu AI scoring/analysis chưa sẵn sàng:
  • chỉ hiển thị loading/skeleton + deterministic status,
  • không fabricate explanation khi evidence chưa có.

Tier Access Baseline

• Free:
  • làm được bài tập,
  • xem được điểm Reading/Listening,
  • Writing/Speaking chỉ xem basic total score,
  • phần AI của Writing/Speaking bị khoá.
• Pro:
  • luyện không giới hạn Reading/Listening,
  • Writing/Speaking chấm điểm cơ bản không giới hạn,
  • AI detail của Writing/Speaking vẫn lock nếu thuộc nhóm advanced AI,
  • mở tính năng đặc biệt nền tảng (quản lý luyện tập, thống kê, sổ từ vựng).
• Pro Max:
  • luyện không giới hạn cả 4 kỹ năng,
  • dùng AI Credit cho các tính năng nâng cao,
  • advanced AI là credit-based (không phải unlimited advanced AI usage).

Locked-AI Upgrade Entry

• Khi user bấm vào feature AI bị khoá:
  • mở quick-upgrade popup trước checkout.
• Offer set theo yêu cầu feature:
  • feature mở được bằng Pro -> hiển thị Pro + Pro Max,
  • feature chỉ mở bằng Pro Max -> chỉ hiển thị Pro Max.
• Default preselect:
  • nếu có cả Pro và Pro Max, preselect gói tối thiểu đủ mở feature,
  • user vẫn có thể đổi gói trước khi xác nhận.
• Upgrade entry trong result context là in-context quick popup mặc định.
• Trang pricing chỉ là đường xem chi tiết tùy chọn từ popup, không redirect mặc định.
• Nếu popup hiển thị Pro + Pro Max:
  • bắt buộc user chọn rõ gói trước khi sang bước checkout kế tiếp.
• Popup có link Xem chi tiết gói.
• Sau khi chọn gói hợp lệ -> đi nhanh vào bước checkout tiếp theo.
• Repeat policy:
  • mỗi lần user tap vào AI feature đang lock trong result context đều mở popup nâng cấp.
  • anti-spam cooldown giữa 2 lần mở popup liên tiếp: 1-2 giây.

Post-payment Behavior

• Nếu checkout được gọi từ context attempt/result:
  • quay lại đúng result context hiện tại,
  • reload lại trang hiện tại,
  • mở ngay section vừa unlock theo entitlement mới.
• Nếu checkout được gọi từ landing/exploration:
  • return về trang trước đó,
  • hiển thị popup chào mừng nâng cấp thành công.

Mid-attempt Entitlement Safety

• Nếu entitlement/credit AI đổi trạng thái giữa lúc user đang làm bài:
  • vẫn cho submit bài bình thường,
  • ở trang result, các section AI không còn quyền sẽ hiển thị lock-state,
  • lock-state có entry nâng cấp/top-up để mở lại quyền phù hợp.

Recommendation Contract (Result Surface)

• Priority:
  • recommendation_priority = habit_first.
  • default ordering sau khi nộp bài:
    1. gợi ý khớp kết quả vừa làm,
    2. gợi ý cùng chủ đề,
    3. gợi ý skill khác để đa dạng.
• Set size:
  • recommendation_set_size = dynamic(3..7).
  • recommendation_default_size = 5.
  • recommendation_low_inventory_min = 3.
  • recommendation_default_mix = 2_habit + 2_target + 1_explore.
• Explainability:
  • mỗi item có recommendation_reason_label (1 dòng).
  • mỗi item chỉ có đúng 1 primary_reason_code.
  • reason priority order:
    1. recovery_critical,
    2. goal_aligned,
    3. habit_continuity,
    4. freshness,
    5. trending_fallback.
  • mỗi item có recommendation_confidence_level = high | medium | low.
  • khi inventory đủ:
    • tối đa 1 item low trong một set,
    • item low được đặt gần cuối set.
• Refresh triggers:
  • recommendation_refresh_trigger = on_submit | manual_refresh.
• Adaptive rule:
  • nếu recommendation_ignore_streak >= 3, engine đổi chiến lược gợi ý.
  • ignore được tính khi:
    • không click gợi ý, hoặc
    • click rồi thoát mà không nộp bài.
  • ignore streak chốt ở cuối session (30m idle hoặc user thoát session).
  • thứ tự đổi chiến lược: difficulty -> format -> skill.
  • feedback model:
    • like/dislike ở mức cluster,
    • dislike cluster có hiệu lực cho các cluster sau,
    • feedback interaction không reset ignore streak.
  • dislike + thoát không làm bài vẫn cộng ignore +1.
• Diversity guardrail:
  • tối đa 3 item cùng skill trong một set.
  • tối đa 2 item cùng topic trong một set.
  • mỗi set cần có ít nhất 1 freshness item khi inventory cho phép.
  • freshness item:
    • bài chưa làm trong 14 ngày gần nhất, hoặc
    • cùng skill nhưng khác format so với lượt làm gần đây.
• User control:
  • user chỉnh nhanh skill | difficulty | duration.
  • preference chỉ giữ trong phiên hiện tại (session).
  • controls là soft-priority ranking (không hard filter mặc định).
  • nếu thiếu item khớp: nearest-ladder + notice ngắn.
  • controls áp dụng xuyên các bề mặt trong cùng session (Result/Home/Practice Management).
  • nếu user manual refresh 2 lần liên tiếp mà không click/attempt:
    • set kế tiếp bắt buộc có ít nhất 1 item khác skill.
• Entitlement-aware composition:
  • recommendation composer ưu tiên item available-now (user làm được ngay theo entitlement hiện tại).
  • khi inventory đủ, locked teaser tối đa 1 item/set và đặt cuối set.
  • locked teaser phải hiển thị rõ lý do khoá + gói tối thiểu cần để mở (Pro hoặc Pro Max).
  • nếu inventory available-now thiếu:
    • nới nearest-ladder trong cùng program/assessment-form/skill trước,
    • chỉ khi vẫn thiếu mới cho thêm locked items + notice ngắn.
• Cold-start fallback:
  • nếu user không goal và chưa có lịch sử, dùng trending_14d + easy_start_bias.
• Reactivation reminder handoff:
  • nếu user vào session từ reminder click, set recommendation đầu tiên áp dụng one-time seed boost.
  • seed boost:
    • có ít nhất 1 quick-win item theo intent stage khi inventory cho phép.
    • quick-win seeded item phải là available-now.
    • quick-win seeded item ưu tiên confidence high | medium.
    • lost_streak | inactive_1w: ưu tiên skill gần nhất + quick-win.
    • inactive_1m | inactive_1y | inactive_q3_repeat: thêm 1 item trending-new trong program khi có thể.
  • seed boost hết hiệu lực sau attempt đầu tiên hoặc khi session kết thúc.
  • nếu seed inventory không đủ, fallback về baseline trending_14d + easy_start_bias.
• Goal-confidence fallback:
  • nếu goal comparison not_comparable hoặc chưa đạt confidence gate (<3 comparable attempts/30 active days),
  • recommendation ưu tiên cùng canonical assessment_form_id,
  • nếu inventory đủ thì ưu tiên cùng skill trước.
• Inventory fallback:
  • ưu tiên nearest-match ladder, giảm dần độ chặt thay vì random sớm.
• Repeat suppression:
  • không gợi ý lại đúng bài đã làm trong 7 ngày gần nhất (trừ khi user chủ động tìm và mở lại).

Recommendation and Sync Contracts

• Recommendation khi AI score chưa sẵn sàng:
  • không dùng score để recommend,
  • ưu tiên level + topic + recent skill intent.
• Decline-state rescue recommendation (light-touch):
  • khi learner ở trạng thái dang_tut_phong_do, hệ thống thêm gói 3 bài cứu nhịp.
  • composition chuẩn:
    1. 1 bài warm-up cố định,
    2. 2 bài personalized theo vùng yếu/trend.
  • touchpoints:
    • hiển thị ngay khi vừa phát hiện decline (immediate prompt),
    • luôn có điểm vào bền vững tại Practice Management.
  • rescue pack là gợi ý tự nguyện, không tạo hard gate, không ép theo thứ tự cố định.
  • prompt style mặc định là inline non-blocking card/panel (không dùng blocking modal).
  • cooldown:
    • sau khi đã hiển thị immediate prompt, chặn prompt immediate mới trong 7 ngày,
    • trong cooldown vẫn giữ entry ở Practice Management.
  • re-prompt policy:
    • không nhắc lại theo timer,
    • chỉ nhắc lại khi có new decline signal.
  • new decline signal:
    • chỉ hợp lệ sau khi learner đã qua ít nhất 1 recovery period.
  • recovery period condition:
    • learner hoàn thành ít nhất 1 bài tương tự (không bắt buộc đúng bài trong rescue pack).
  • similarity ladder để xác định “bài tương tự”:
    • Tier A (strict): cùng program + cùng skill + cùng dạng bài + chênh lệch độ khó <=1,
    • Tier B (medium): cùng program + cùng skill,
    • Tier C (broad): cùng skill trong cùng program.
  • fallback guardrail:
    • chỉ dùng Tier C khi inventory Tier A+B <3,
    • không fallback cross-program.
  • quality gate để tính recovery hợp lệ:
    • đạt ngưỡng thời lượng luyện theo skill,
    • đạt ngưỡng completion ratio theo loại bài (objective/subjective).
  • default threshold baseline:
    • Reading >=8m, Listening >=8m, Writing >=12m, Speaking >=12m,
    • Objective completion >=70%, Subjective completion >=60%.
  • reset strictness:
    • chỉ cần 1 bài tương tự hợp lệ là đủ reset cooldown.
  • cooldown reset:
    • reset cooldown khi learner hoàn thành ít nhất 1 bài tương tự.
  • async scoring rule:
    • với Writing/Speaking, chỉ reset sau khi có kết quả chấm xong.
  • reset scope:
    • reset theo skill within program, không reset lan sang vùng khác.
  • transparency:
    • hiển thị checklist ngắn cho user: match tương tự + đủ thời lượng + đủ completion.
  • nếu phát hiện decline mới trong lúc cooldown còn hiệu lực:
    • vẫn tôn trọng cooldown,
    • không bật immediate prompt mới.
• Sync dữ liệu:
  • kết quả hợp lệ luôn sync sang Learning Management,
  • vocabulary sync theo điều kiện payload vocab hợp lệ.

AI Tutor Plan Escalation (High-attention)

• Recovery status:
  • sau result hợp lệ, có thể hiển thị trạng thái phục hồi tạm (provisional).
  • trạng thái phục hồi chính thức chốt theo weekly pulse.
• Escalation trigger:
  • nếu learner không recovery trong 2 chu kỳ liên tiếp, system gợi ý AI Tutor adaptive recovery plan.
  • escalation là non-blocking, user có thể tiếp tục luồng học bình thường.
• Plan structure:
  • mỗi ngày gồm 1 required + 1 optional.
  • optional là bonus, không thay required.
• Plan lifecycle:
  • chỉ regenerate sau khi kết thúc chu kỳ 7 ngày và learner vẫn high-attention.
  • nếu learner đổi program giữa chu kỳ, plan hiện tại giữ đến hết chu kỳ.
• Completion semantics:
  • required chỉ được tính hoàn thành khi bài required được submit.
  • nếu bỏ lỡ ngày required, không carry-forward; chuyển sang ngày kế tiếp.
  • completion theo local-day, day boundary tại 00:00.
  • completion-day attribution dùng submit timestamp.
• Plan nudge sync semantics:
  • khi priority step đã hoàn thành, dừng plan nudge ngay lập tức.
  • nếu đến trước thời điểm nudge mà priority step đã hoàn thành, skip nudge đó.
  • rule này áp dụng account-level cho mọi thiết bị/kênh của account.
• Priority-step unavailable fallback:
  • nếu priority step hiện tại bị unavailable trước khi complete,
  • hệ thống tự thay bằng ladder A -> B -> C trong cùng program,
  • hiển thị notice ngắn để user biết step đã được thay.

AI Tutor Post-submit Transition Contract

• Khi attempt đã submitted/finalized và user mở AI Tutor từ Result:
  • chuyển sang reference_explanation behavior (không còn active-attempt coaching guardrail).
  • AI được phép đưa lời giải đầy đủ phục vụ học lại.
  • output đầy đủ phải gắn nhãn rõ reference explanation để tránh hiểu nhầm là hỗ trợ nộp bài đang diễn ra.
• Action continuity sau lời giải:
  • tối thiểu 1 action kế tiếp:
    • continue_chat, hoặc
    • open_exercise/open_resource cho bài tương tự để luyện thêm.
• Boundary:
  • nếu user quay lại một attempt khác còn active, runtime phải quay lại exercise_coaching mode theo PRA_Attempt_Flow.

Metrics Contract

• Tất cả bài đã nộp thành công đều được tính vào chỉ số học tập, không phụ thuộc tier.
• submitted_at từ submission thành công là mốc nguồn cho streak/progress attribution.

Decision Trace

• Supporting discovery trail có tồn tại cho các cụm rule như entitlement/upgrade, recommendation composition, goal comparability, AI Tutor post-submit boundary, và action continuity.
• Current truth của Result vẫn đọc trong file này và PRA_Result_Impact_Contracts.md; chỉ sang Product Discovery khi thật sự cần replay lịch sử quyết định.

References

• ./PRA_Result_Impact_Contracts.md
• ./PRA_Entry_Routing_Contracts.md
• ../Payment/PAY_Checkout_Flows.md
• ../Payment/PAY_Recommendations.md
• ../Learning Management/LM_Metrics.md

Change log

• 2026-03-16: Chốt Result AI theo archetype analysis_panel; Result/Feedback Workspace đọc theo signal -> meaning -> fix -> action, không dùng action-hub hay queue-guide layout.
• 2026-03-13: Bổ sung AI Analysis Panel / Feedback Workspace như baseline surface của Result; khi mở AI Tutor từ result, drawer mặc định tab Phân tích và phải giữ continuity với score/evidence/review-next-step.
• 2026-03-01: Bổ sung post-submit AI Tutor transition contract: cho phép full reference explanation sau finalized result, yêu cầu label rõ và action continuity.
• 2026-02-22: Bổ sung lớp explainability deterministic cho recommendation: mỗi item chỉ có 1 primary reason theo priority cố định và confidence high|medium|low; cap tối đa 1 low-confidence item/set (khi inventory đủ) và đặt gần cuối set.
• 2026-02-22: Bổ sung entitlement-aware recommendation composition: ưu tiên available-now items, cap lock teaser tối đa 1 item/set (khi inventory đủ), lock teaser luôn có reason + minimum-eligible-plan label.
• 2026-02-22: Bổ sung reactivation-intent handoff: khi vào từ reminder click, set đầu tiên có one-time seed quick-win theo stage, hết hiệu lực sau attempt đầu tiên hoặc hết session.
• 2026-02-22: Bổ sung freshness guardrails cho recommendation: mỗi set có ít nhất 1 item mới khi inventory cho phép, cap tối đa 2 item cùng topic, và thêm rule diversify theo khác skill sau 2 lần manual refresh liên tiếp không có action.
• 2026-02-21: Bổ sung goal-confidence fallback cho recommendation: khi goal-gap không đủ điều kiện so sánh, ưu tiên gợi ý cùng assessment form và cùng skill (nếu inventory đủ) để tích lũy tín hiệu comparable.
• 2026-02-21: Bổ sung deep handoff cho timeout-submit và submit-failure boundary (chỉ vào result khi submission thành công; support CTA sau auto-retry exhausted).
• 2026-02-21: Đồng bộ handoff từ Attempt baseline: nhận cả timeout-submit path của timed mode và chuẩn hóa submitted_at làm source-of-truth cho attribution.
• 2026-02-21: Chốt baseline entitlement/upgrade UX: Pro Max advanced AI theo credit-based policy, lock-popup default preselect minimum-eligible tier, và return-to-current-result + auto-open unlocked section sau thanh toán.
• 2026-02-20: Chốt Stage A execution: result lock-state giữ upgrade entry tại chỗ (quick popup mặc định), pricing page là đường detail tùy chọn.
• 2026-02-20: Tinh chỉnh vận hành lock-state: cooldown anti-spam 1-2s cho popup lock và làm rõ retained-credit lock visibility ở Result + Billing/Subscription.
• 2026-02-20: Chốt lock-popup repeat policy (mỗi tap đều mở popup) và chuẩn hóa rule giữ credit khi downgrade Pro Max -> Pro (usage lock ngoài entitlement).
• 2026-02-19: Bổ sung baseline entitlement/fairness: Free/Pro Writing-Speaking chỉ basic score, reopen result không trừ thêm credit, auto-refund khi AI chấm lỗi hệ thống, và mid-attempt hết quyền AI vẫn cho submit + lock ở result.
• 2026-02-18: Bổ sung AI Tutor daily required semantics: stop reminder same-day sau submit, pre-slot skip nếu đã hoàn thành, local 00:00 day boundary + submit timestamp attribution, và unavailable-required fallback A->B->C.
• 2026-02-18: Bổ sung recommendation baseline mới (habit-first, dynamic 3..7, reason label, adaptive ignore, session control, refresh triggers).
• 2026-02-17: Nâng từ placeholder lên flow đầy đủ: unified result UI, tier lock policy, locked-AI upgrade popup, post-payment reload/return, metrics counting rule.

Tier/Credit Refinements

• Free với Writing/Speaking:
  • xem được basic total score,
  • AI detail sections vẫn lock.
• Pro:
  • không có advanced AI credit mặc định,
  • AI detail vẫn lock nếu feature thuộc advanced AI scope.
• Reopen fairness:
  • mở lại result đã chấm xong không trừ thêm AI credit.
  • credit chỉ trừ 1 lần cho mỗi scoring job/result.
• AI system failure fairness:
  • nếu chấm AI lỗi do hệ thống sau khi đã trừ credit, hệ thống auto-refund credit.
• top-up:
  • số dư được giữ lại,
  • usage bị lock khi user ở ngoài entitlement context hợp lệ.
  • khi downgrade Pro Max -> Pro, credit còn lại vẫn giữ và tiếp tục bị usage lock cho feature vượt entitlement.
  • trạng thái credit retained but usage-locked hiển thị ở Result và Billing/Subscription.

Course-vs-Subscription Boundary (Result Context)

• Entitlement mặc định theo context:
  • course context dùng quyền khóa học,
  • self-study context dùng quyền tier.
• Same-item exception:
  • bài đã chạm trong course có thể mở khi nhìn từ self-study.
• Course learner AI:
  • dùng được AI trong phạm vi khóa học qua course credit (không bắt buộc Pro Max).
  • course credit refill theo tháng trong thời gian khóa active.
  • hết credit có thể top-up trực tiếp (không bắt buộc Pro Max).
  • nếu không có entitlement subscription phù hợp, top-up chỉ dùng trong scope khóa học.

Score & Streak Attribution Signals

• Với bài objective:
  • câu bỏ trống tính sai.
• Với bài scaled score:
  • quy đổi % theo điểm tối đa trước khi map band.
• Streak attribution:
  • ngày theo local timezone,
  • tính theo submit timestamp,
  • freeze auto-consume ở ngày bỏ đầu tiên.