DOL English Navigation Shell Contracts

DOL English - Navigation Shell Contracts

Purpose

• Chốt shell model mới cho logged-in DOL English ở mức cross-surface.
• Tách rõ cross-program orchestration, one-program execution, và deep object ownership.
• Giảm việc dùng nav như sitemap phẳng thay vì workflow controller.

Doc Role

• Đây là feature-rule chi tiết cho navigation shell.
• Nếu cần đọc navigation như 1 feature hoàn chỉnh, mở ./ENG_Navigation_00_Overview.md trước.
• File này là supporting rule doc; chỉ mở khi cần matrices, boundary, hoặc behavior detail sâu hơn file master.

Objective

• Tối ưu task completion, clarity, retention, và khả năng scale của hệ thống khi số program, tool, và object tiếp tục tăng.
• Giữ logged-in shell ưu tiên execution hằng ngày hơn discovery/catalog.
• Dùng một contract đủ ngắn để UX, content, PM, và implementation cùng đọc ra một logic giống nhau.

Current Truth

• Logged-in shell của DOL English không còn nên đọc như một portal trộn discovery + portfolio + execution.
• Baseline active là:
  • Program Workspace
  • Selective Cross-program Aggregate Views
  • Deep Object

Problem Framing

• Đây là shell cho logged-in learning product, không phải lớp menu của site khám phá.
• User quay lại để:
  • học tiếp thứ đang dở,
  • làm bài được giao,
  • luyện kỹ năng theo program,
  • ôn vocab,
  • xem mình đang tiến bộ hay tụt ở đâu.
• Vì object của DOL English chồng nhau (program, course, assignment, attempt, vocab, analytics), shell phải hoạt động như workflow controller, không phải flattened sitemap.

Key Assumptions and Constraints

• Baseline này đang tối ưu cho desktop web logged-in experience.
• Learner là role chính cần tối ưu trong shell hiện tại.
• Phần lớn hành vi học trong một giai đoạn vẫn là 1 program chính, kể cả khi account có hơn một program.
• Shell mới phải giữ tương thích với returnTo, protected entry, và các entry contract đã khóa ở Stage A/A2.
• Chưa có đủ dữ liệu để hard-lock mọi quyết định về:
  • danh sách đầy đủ các aggregate view đủ điều kiện ngoài schedule / calendar,
  • độ thường xuyên thật của hành vi Từ vựng,
  • mức ưu tiên của ecosystem switcher trên mobile/compressed layouts.

Locked Principles

• Program = context.
• Task = primary navigation.
• Cross-program view chỉ là scoped exception, không được giả làm default shell hay deep execution view.
• Mỗi deep object phải có 1 canonical home.
• Một lớp nav = một chiều thông tin; không để một row vừa là destination, vừa là context, vừa là subview.

Shell Layer Model

1. Public Discovery

• Trả lời: Tôi học gì / mua gì / vào app bằng đường nào?
• Dùng program hoặc buying intent làm trục chính.
• Không thay thế shell logged-in.

2. Program Workspace

• Trả lời: Trong chương trình này, tôi làm gì tiếp và đi vào section nào?
• Một lần chỉ ở 1 program thật.
• Desktop baseline dùng task-first primary destinations:
  • Hôm nay
  • Khóa học
  • Luyện tập
  • Từ vựng
  • Tiến độ
• Local tabs chỉ xuất hiện bên trong từng destination, ví dụ:
  • Luyện tập -> Reading / Listening / Writing / Speaking
  • Tiến độ -> Overview / History / Weak areas
  • Khóa học -> Active / Schedule / Assignments / Materials

3. Selective Cross-program Aggregate Views

• Không phải là Home, không phải Global Today, và không phải All Programs workspace.
• Chỉ được tồn tại trong các view thật sự cần gom dữ liệu chéo chương trình.
• Confirmed initial use case:
  • schedule / calendar style operational surfaces.
• Contract của aggregate view:
  • mặc định vẫn đọc theo program hiện tại,
  • chỉ mở All Programs như scope toggle tường minh khi cần,
  • không dùng cho deep execution như timed attempt, course detail, vocab queue, hoặc analytics deep dive.

4. Deep Object

• Assignment, attempt, result, vocab item, AI feedback, hay object tương tự luôn thuộc một owner section thật.
• Mọi surface khác chỉ được surfacing object như shortcut, queue item, hoặc summary entry.

Hierarchy Semantics

• Ecosystem switcher
  • đổi giữa DOL English / DOL Kid / DOL Academy.
  • Đây là brand/domain context, không phải logged-in task nav.
• Program switcher
  • đổi program workspace context.
  • Đây là global state của workspace, không phải filter local.
• Primary navigation
  • đổi task destination trong shell hiện tại.
  • Ví dụ: Hôm nay / Khóa học / Luyện tập / Từ vựng / Tiến độ.
• Local navigation
  • đổi subview trong cùng destination.
  • Ví dụ: Reading / Listening / Writing / Speaking trong Luyện tập.
• Utility navigation
  • giữ search / notification / help / account / quick access.
  • Không chen vào primary nav.
• Filter / search / sort
  • chỉ thay đổi cách nhìn dữ liệu trong cùng view.
  • Không được dùng để giả làm context switch.

Program Context Contract

• Program switcher chỉ liệt kê program thật.
• Tất cả chương trình không được sống như peer context trong switcher hoặc workspace shell.
• Nếu một aggregate view đủ điều kiện có All Programs, đó chỉ là view scope toggle, không phải switcher context.
• Nếu user mở object thuộc program khác từ notification/search/deep-link:
  • app được phép đổi context sang program đúng,
  • nhưng phải đổi một cách tường minh trong URL/state,
  • và phải cho user tín hiệu rõ rằng context đã đổi.
• Nếu user đang ở critical flow như timed attempt hoặc unsaved high-cost action:
  • switch program không được silent,
  • hoặc phải chặn,
  • hoặc phải yêu cầu confirm rõ hậu quả.

Default Entry Contract

• Nếu có returnTo hợp lệ -> quay lại exact context trước.
• Nếu không có returnTo hợp lệ:
  • last meaningful program workspace -> resume vào đó,
  • nếu deep target cũ không còn hợp lệ -> fallback về same program root,
  • nếu không có restore context nhưng chỉ có 1 valid active program -> vào thẳng workspace của program đó,
  • nếu chưa resolve được program hợp lệ -> onboarding / program choice / discovery.
• Single-program không nên bị ép học theo mental model portfolio nếu không có nhu cầu thật.
• Multi-program vẫn đọc theo program-first; aggregate chỉ bật trong eligible views thay vì trở thành default shell destination.

Active Program Resolution Contract

• Last meaningful program workspace không được đọc từ raw URL cuối cùng một cách mù quáng.
• Resolution inputs tối thiểu gồm:
  • current in-progress program,
  • recent meaningful activity,
  • last explicit program intent,
  • goal_program,
  • program lifecycle state (not_started | active | completed | archived),
  • entitlement / registration / purchase state nếu ảnh hưởng quyền vào workspace.
• Restore source phải loại trừ các route không đáng resume:
  • auth,
  • account,
  • checkout,
  • transient success/error pages,
  • expired deep routes.
• Khi cần resolve safe fallback hoặc sort ưu tiên cho restore, thứ tự baseline là:
  • current in-progress program,
  • recent meaningful activity,
  • last explicit program intent,
  • goal_program,
  • direct single-program fallback,
  • onboarding / program choice / discovery.
• Owned but not started, completed, hoặc archived không được đẩy lên thành default execution context chỉ vì tồn tại trong account state.

Hôm Nay vs Tiến Độ Contract

• Hôm nay
  • trả lời: Bây giờ tôi nên làm gì?
  • owner của:
    • continue,
    • due queue,
    • next class/deadline,
    • recommended next action,
    • shortcut vào owner section.
• Tiến độ
  • trả lời: Tôi đang tiến triển thế nào theo thời gian, yếu ở đâu, và pattern nào đáng chú ý?
  • owner của:
    • analytics,
    • history,
    • weak areas,
    • trend,
    • goal comparison.
• Nếu một page không giữ được ranh giới này, ưu tiên:
  • merge,
  • hoặc đổi label,
  • không giữ hai destination mờ nghĩa cùng tồn tại.

Canonical Object Ownership Contract

• Mỗi deep object phải có tối thiểu:
  • program
  • object_type
  • source
  • canonical_section
• Ví dụ:
  • bài Writing được giao trong course:
    • có thể xuất hiện ở Program Workspace root / Hôm nay hoặc aggregate view đủ điều kiện,
    • nhưng owner thật vẫn là Khóa học.
  • kết quả một bài luyện:
    • có thể được nhắc lại ở Tiến độ,
    • nhưng owner detail vẫn nằm ở flow result / section chuẩn của Luyện tập.
• Không được có hai object state khác nhau chỉ vì object đó được surfacing ở hai surface khác nhau.

Canonical Home Matrix

• Course schedule / lesson / assignment / material / teacher feedback
  • canonical home: Khóa học
• Drill / mock test / AI room / attempt / result
  • canonical home: Luyện tập
• Saved word / review queue / source-tagged vocab item
  • canonical home: Từ vựng
• Analytics / history / weak areas / trend / goal-gap reasoning
  • canonical home: Tiến độ
• Continue card / due card / next action card
  • canonical home: Hôm nay chỉ ở mức shortcut orchestration trong program workspace; detail vẫn thuộc owner section bên dưới

Naming Contract

• Primary nav logged-in phải ưu tiên wording learner-centric và action-centric.
• Không dùng label system-centric làm destination chính nếu có label learner-centric rõ hơn.
• Baseline direction:
  • Khám phá -> ra khỏi primary nav logged-in,
  • Quản lý khóa học -> Khóa học,
  • Quản lý luyện tập -> Luyện tập,
  • Tổng quan -> Hôm nay nếu page thực chất là next-action surface.
• Từ vựng chỉ nên giữ slot top-level khi hành vi review thực sự đủ thường xuyên trong cohort chính; nếu không, phải cân nhắc hạ prominence thay vì giữ vì structure nội bộ.

Behavior Matrix

• Single-program learner
  • default: resume last meaningful workspace hoặc program root.
  • shell phải giảm tối đa cảm giác đang ở chế độ portfolio.
• Multi-program learner
  • default vẫn là resume last meaningful workspace nếu không có returnTo.
  • aggregate chỉ bật ở eligible views khi learner thật sự cần xem chéo chương trình.
• Deep-link entry
  • đi thẳng tới object/owner section nếu target hợp lệ.
  • nếu phải đổi program, UI phải báo rõ là context đã đổi.
• No valid restore context
  • không fabricate Global Today dashboard làm fallback.
  • đi tới single valid program workspace hoặc program choice / discovery.
• Empty / no-course / no-practice state
  • dùng CTA khởi động và add-program entry,
  • không fabricate fake data để lấp shell.
• Archived / unavailable program
  • không giữ như active peer context trong switcher.
  • chỉ xuất hiện ở grouped history/archive surface nếu thật sự cần.

UX Guardrails

• Không stack nhiều row ngang mà mỗi row lại là một logic khác (destination, program, subview) cùng tranh attention.
• Không biến All Programs thành workaround cho vấn đề cross-program orchestration.
• Không để dashboard cards trở thành second home của object.
• Không để discovery chiếm ưu tiên hơn daily execution trong logged-in primary shell.
• Không dựng standalone Global Today / All Programs overview chỉ để phục vụ rare cohort multi-program nếu cùng bài toán đã được giải tốt hơn bằng resume last program + scoped aggregate views.
• Offline / live online / self-paced là course modality; chúng chỉ sống ở filter / chip / grouping bên trong Khóa học, không sống như primary destination.
• Luyện tập không được biến thành top nav itemization của toàn bộ tool (AI Speaking, Mock Test, Mini Quiz, …); tool inventory phải được gom theo skill / use case và đi bằng local nav hoặc content grouping.

Accessibility and State Feedback

• Context switch phải có state feedback rõ:
  • visual cue,
  • selected state,
  • và announcement path phù hợp cho screen reader nếu context đổi đáng kể.
• Không dùng color-only để phân biệt program hoặc selected state.
• Header actions quan trọng không được chỉ là icon nếu thiếu accessible name rõ.
• Mega menu hoặc switcher không được phụ thuộc hoàn toàn vào hover.
• Focus order phải phản ánh hierarchy thật:
  • ecosystem/domain,
  • program context,
  • task destination,
  • local nav,
  • content.

Success Measures

• first_click_success
• time_to_resume_study
• wrong_context_entry_rate
• backtracking_after_entry
• assigned_task_completion_rate

Validation Methods

• Ưu tiên:
  • card sorting để kiểm tra user nhóm nội dung đúng theo mental model,
  • tree testing để kiểm tra user có vào đúng section/context hay không.
• Task baseline:
  • tìm lớp IELTS 6.5,
  • vào mock test SAT,
  • xem bài Writing cần sửa,
  • ôn lại từ TOEIC đã quên.

Validation-dependent Calls

• Từ vựng có giữ slot top-level ở mọi cohort hay chỉ ở cohort có review frequency cao.
• Exact list của aggregate-eligible views sau schedule / calendar.
• Mobile/compressed shell nên ưu tiên collapse theo trục nào để không phá hierarchy semantics.
• Một số family như IELTS / SAT / TOEIC có cần local-nav template riêng hay vẫn đủ dùng một baseline thống nhất.
• Storage/read model cho last meaningful program workspace có đủ an toàn với expired deep route hay không.

Open Validation

• Từ vựng có xứng đáng top-level across cohorts hay không.
• Mobile shell nên nén thế nào mà không phá hierarchy semantics.
• Data model đã đủ sạch để mọi surfaced object luôn mang program + source + canonical_section hay chưa.
• Aggregate views nào ngoài schedule / calendar thật sự đáng unlock.
• Restore/fallback ladder của last meaningful program workspace đã đủ an toàn với route lỗi thời hay chưa.

References

• ./ENG_Page_Role_Contracts.md
• ./ENG_Lifecycle_Motivation_Contracts.md
• ../Product Discovery/30_STATE/STATE_Navigation_Shell_and_Object_Ownership.md
• ./Home & Discovery/HOME_ENG_Detailed_Baseline.md
• ../Product Discovery/20_DECISIONS/DEC-0096_resume-last-program-and-selective-cross-program-aggregation-shell-model.md

Change log

• 2026-03-27: Retire Global Today Hub như default logged-in shell, chuyển baseline sang resume last meaningful program workspace, và giới hạn cross-program aggregation vào selective scoped views với use case ban đầu là schedule / calendar.
• 2026-03-26: Bổ sung utility navigation, khóa course modality về lớp filter/grouping trong Khóa học, chốt practice tool inventory phải đi theo skill / use case, và thêm validation methods.
• 2026-03-26: Bổ sung Active Program Resolution Contract để chốt input resolve orchestration state sau login (in-progress, recent activity, goal, explicit intent, lifecycle, entitlement) và tránh đọc active program như entitlement thô.
• 2026-03-25: Gắn doc_role: feature-rule và giữ ENG_Navigation_00_Overview.md làm file master để giảm phân mảnh đường đọc.
• 2026-03-25: Bổ sung Objective, Key Assumptions and Constraints, và Validation-dependent Calls để phân biệt phần đã khóa với phần còn cần validate trước khi detailed IA/pixel design.
• 2026-03-25: Mở rộng shell contract theo hướng build-ready hơn: thêm Problem Framing, Locked Principles, Hierarchy Semantics, Hôm nay vs Tiến độ, Canonical Home Matrix, Behavior Matrix, Accessibility and State Feedback, và Success Measures.
• 2026-03-25: Khởi tạo shell contract mới cho mô hình Global Today Hub + Program Workspace + Deep Object, chốt rule no pseudo-program, default entry theo số program active, và canonical object ownership.