Practice Flow Screen Inventory

Practice Flow - Screen Inventory

Purpose

• Chuẩn hóa danh sách màn hình cần triển khai cho area Practice Flow theo hướng flow-complete skeleton.
• Chốt contract route/state trước, tránh mỗi entry source tự định nghĩa flow riêng.
• Đảm bảo flow Attempt -> Result -> Impact Sync luôn nhất quán và không mất context quay lại.

Source Review Scope (đã rà soát)

• Core docs:
  • PRA_00_Overview.md
  • PRA_Information_Architecture.md
  • PRA_Entry_Routing_Contracts.md
  • PRA_Attempt_Flow.md
  • PRA_Result_Flow.md
  • PRA_Result_Impact_Contracts.md

Assumptions for this inventory

• Canonical routes:
  • /domains/dol-english/practice/attempt/:id
  • /domains/dol-english/practice/result/:id
• Mọi route PRA đều là protected flow; guest chỉ thấy auth-required state rồi quay lại đúng route.
• Required params tuân theo contract:
  • attempt: source_context, program, exercise_id, returnTo
  • result: source_context, program, exercise_id, returnTo + attempt_id trên path
• returnTo không hợp lệ phải fallback deterministic về route hợp lệ gần nhất.

Screen Inventory (Recommended)

ID	Layer	Screen	Canonical route	Required state	Priority	Notes
PRA-S01	Entry	Entry from Exercise Bank	/domains/dol-english/practice/bank/:programId/:skillId -> /domains/dol-english/practice/attempt/:id	Post	P0	Giữ source_context=self_study + returnTo bank
PRA-S02	Entry	Entry from Course Detail	/domains/dol-english/courses/:courseId -> /domains/dol-english/practice/attempt/:id	Post	P0	Giữ source_context=course + returnTo course
PRA-S03	Entry	Auth-required state at attempt route	/domains/dol-english/practice/attempt/:id	Pre	P0	Login tại chỗ, retry cùng contract params
PRA-S04	Entry	Attempt contract validation gate	Same attempt route	Post	P0	Check required params trước khi render attempt
PRA-S05	Entry	Attempt invalid contract fallback	Same attempt route (invalid)	Pre + Post	P0	Fallback về route hợp lệ + copy hướng dẫn
PRA-S06	Entry	Attempt loading/init state	Same attempt route	Post	P1	Chuẩn bị metadata + session context
PRA-S07	Attempt	Attempt active state	Same attempt route	Post	P0	Màn chính làm bài
PRA-S08	Attempt	Timed mode state	Same attempt route (mode=timed)	Post	P0	Countdown + time-expired behavior
PRA-S09	Attempt	Untimed mode state	Same attempt route (mode=untimed)	Post	P1	Không countdown, giữ contract như nhau
PRA-S10	Attempt	Pause/exit confirm modal	Same attempt route (modal)	Post	P1	Giữ dữ liệu item đã trả lời
PRA-S11	Attempt	Submit confirm state	Same attempt route	Post	P1	Tránh submit nhầm
PRA-S12	Attempt	Submit in-flight state	Same attempt route	Post	P0	Lock thao tác trong lúc submit
PRA-S13	Attempt	Submit failed retry state	Same attempt route	Post	P0	Retry submit, không mất state phiên
PRA-S14	Attempt	Submission success redirect	/domains/dol-english/practice/attempt/:id -> /domains/dol-english/practice/result/:id	Post	P0	Bắt buộc có attempt_id
PRA-S15	Result	Auth-required state at result route	/domains/dol-english/practice/result/:id	Pre	P0	Login tại chỗ, giữ params
PRA-S16	Result	Result contract validation gate	Same result route	Post	P0	Check required params + attempt_id
PRA-S17	Result	Result invalid contract fallback	Same result route (invalid)	Pre + Post	P0	Fallback deterministic theo contract
PRA-S18	Result	Result summary baseline	Same result route	Post	P0	Completion + score summary
PRA-S19	Result	LM sync status panel	Same result route	Post	P0	Always-on sync: queued/done/failed_retrying
PRA-S20	Result	Vocabulary sync available	Same result route	Post	P0	Chỉ khi có vocab_suggestion_payload hợp lệ
PRA-S21	Result	Vocabulary sync skipped	Same result route	Post	P0	Không payload thì skip nhưng không fail result
PRA-S22	Result	Sync pending/retry feedback	Same result route	Post	P1	Hiển thị trạng thái retry nền
PRA-S23	Result CTA	Return to previous context	Same result route	Post	P0	Dùng returnTo đã sanitize
PRA-S24	Result CTA	Do next exercise CTA	Same result route	Post	P1	Điều hướng vào attempt tiếp theo
PRA-S25	Result CTA	Open LM detail CTA	Same result route	Post	P1	Xem thống kê sâu ở LM
PRA-S26	Result CTA	Open Vocabulary suggestions CTA	Same result route	Post	P1	Khi sync VOC có ý nghĩa cho user
PRA-S27	Guardrail	Invalid exercise fallback policy	Attempt invalid exercise_id	Pre + Post	P0	Về bank/course gần nhất theo source context
PRA-S28	Guardrail	Program mismatch recovery	Attempt/result route	Pre + Post	P0	Ưu tiên context từ source screen
PRA-S29	Guardrail	Expired/unsafe returnTo fallback	Attempt/result route	Pre + Post	P0	Fallback về landing/home hợp lệ
PRA-S30	Guardrail	Logout retains route context	Current PRA route	Transition	P0	Không đổi route, chuyển sang auth-required state
PRA-S31	Guardrail	Deep-link direct access state	Attempt/result direct URL	Pre + Post	P0	Vẫn phải pass contract checks
PRA-S32	Analytics	PRA flow event instrumentation state	Attempt/result lifecycle	Post	P1	Track entry_source, source_context, sync states

Suggested Build Sequence (Practice Flow)

1. P0 flow kernel: PRA-S01/S02 → S03/S04/S05 → S07/S08/S12/S13/S14 → S15/S16/S17/S18/S19/S20/S21/S23 → S27/S28/S29/S30/S31.
2. P1 reliability + UX depth: PRA-S06/S09/S10/S11/S22/S24/S25/S26/S32.

Coverage Check Against UX Contract

• Attempt/Result contract: đã map validation gate riêng cho cả hai routes.
• Auth-first + returnTo: có state bắt buộc cho guest ở cả attempt/result.
• Impact sync: LM always-on, Vocabulary conditional được tách riêng rõ ràng.
• No dead-end: mọi route invalid đều có fallback policy.
• Logout context retention: giữ route và chuyển về auth-required state.

Open Gaps (from current docs)

• PRA_Attempt_Flow.md đã có baseline active; vẫn cần ma trận variant sâu theo từng loại bài cụ thể ở phase implementation.
• Chưa có mapping chuẩn giữa score_summary UI và công thức scoring engine theo từng dạng bài.
• Chưa có acceptance matrix chính thức cho retry/offline/sync-failure behavior.
• Chưa có concept docs riêng cho pre-login messaging tại attempt/result.

Next Area Queue

1. docs/Shared/Shared Capabilities/Smart Search Platform/** (nếu tiếp tục mở rộng outside-in flow)

Change log

• 2026-03-15: Chuẩn hóa route examples PRA sang canonical /domains/dol-english/* và route shape hiện hành :id.
• 2026-02-21: Đồng bộ inventory với attempt baseline mới: bỏ ghi chú placeholder cho Attempt/Result, giữ open gaps ở mức variant matrix và acceptance matrix triển khai.
• 2026-02-15: Khởi tạo inventory màn hình cho Practice Flow theo contract docs + runtime contract hiện tại, ưu tiên flow-complete skeleton.