Smart Search Platform - Master Product Specification

Purpose

• Hợp nhất toàn bộ đặc tả Smart Search thành một tài liệu thực thi end-to-end cho toàn nền tảng.
• Đảm bảo triển khai nhất quán, tối ưu trải nghiệm tìm kiếm và hành động cho user ở mọi module.
• Đây là tài liệu chuẩn dùng chung đa hoàn cảnh; không phải tài liệu phân bổ đầu việc theo team/sprint.

1) Product Goal and Success Definition

• Search phải giúp user “làm được việc tiếp theo” trong vài giây, không buộc user duyệt nhiều trang.
• Search phải giữ một hành vi nhất quán khi user di chuyển giữa Home, Course, Learning, Practice, Vocabulary.
• Search phải hỗ trợ cả giai đoạn khám phá chương trình/khoá (guest/pre-login) và giai đoạn học thực thi (post-login) trong cùng một chuẩn logic.
• Search phải hỗ trợ cả hành vi ngắn hạn (làm ngay) và hành vi dài hạn (duy trì nhịp học, đạt mục tiêu).

North-star outcomes

• time_to_first_action_from_search giảm rõ rệt ở mọi module.
• search_success_rate tăng theo phase rollout.
• cross_module_handoff_success_rate ổn định cao cho các flow Home -> PRA, PRA -> VOC.

2) Core Operating Model

• Model chuẩn: Intent × Context × Depth.
  • Intent: người dùng muốn làm gì.
  • Context: user đang ở đâu, entitlement gì, urgency/momentum ra sao.
  • Depth:
    • PAGE: mở trang tổng quát.
    • STEP: nhảy vào tác vụ cụ thể.
    • AI: trả insight/widget.
    • EXEC: chạy hành động ngay.

3) End-to-End Search Lifecycle

1. Open:

• User mở search (Cmd/Ctrl + K hoặc click icon).

2. Context hydrate:

• UI gửi Context Pack (pageContext, signals, entitlement, return path).

3. Query understanding:

• Umbrella bundle detect (AI, làm bài…) -> facet detect (báo cáo, widget, checklist…) -> prefix match -> phrase match -> verb-object match -> semantic fallback.

4. Intent dispatch:

• Orchestrator gọi adapter phù hợp (single hoặc multi-adapter nếu cần).

5. Rank and compose:

• Score theo priority + urgency + momentum + context bias + confidence.

6. Render:

• Hero Action + grouped results + AI (nếu được gọi).

7. Handoff:

• Click result -> deeplink/exec/inline AI/AI tutor portal.

8. Track:

• Log events để tối ưu vòng sau.

4) Search Surface States (Global)

State	Mục tiêu UX	Thành phần bắt buộc	Quy tắc
Closed	Giữ entry gọn	Search bar	placeholder theo module
Focus zero-state	Gợi ý hành động nhanh	3 lanes: Urgency, Momentum, Insight	lane cap + item cap
Typing prefix	Giảm gõ	Prefix completions	max 3
Typing umbrella	Liệt kê nhóm tính năng theo chủ đề tổng quát	Feature catalog theo bundle	không cắt còn 3 kết quả
Typing facet	Liệt kê tính năng theo loại nội dung	Facet list (report/widget/checklist/popup/task)	ưu tiên facet tags trước title match
Typing semantic	Trả kết quả thật	Hero + grouped results	group cap 3
Inline AI	Trả insight ngay	summary + widget + CTA	có back về list
No result	Tránh dead-end	fallback suggestions + ask AI	luôn có CTA
Error/timeout	Giữ flow	partial results/fallback	hiển thị retry nhẹ

5) Module-specific Behavior Contracts

• Chi tiết mapping theo area và page được chốt tại ux-patterns/SSP_Area_Positioning_Page_Behavior.md và là nguồn chuẩn cho placeholder/chips/ranking bias từng ngữ cảnh.

5.1 Home Pre-login Discovery

• Priority order:
  • Program discovery -> Course discovery -> Compare/fit -> Auth/consultation.
• Search phải ưu tiên:
  • program landing deep-links,
  • program compare actions,
  • course guest preview/detail gate actions.
• Conversion contracts:
  • mọi action cần quyền đi auth-first + returnTo,
  • fallback an toàn về discovery context gần nhất khi return target invalid.

5.2 Home Post-login

• Priority order:
  • Continue Learning -> Unified Quick Access -> Program Quick Access -> Recommendation.
• Activation week-1:
  • inline activation card (non-blocking), ladder 3 bước.
• Reactivation handoff:
  • first-set seed boost one-time theo stage.
• High-attention:
  • nhắc AI Tutor adaptive recovery plan theo policy, không chặn luồng học.
• AI policy:
  • AI Tutor on-demand only, không auto-open.

5.3 Course Management

• Priority order:
  • Due Today/Overdue -> In Progress -> Next Class -> Admin Ops -> Explore.
• Cần hỗ trợ mạnh EXEC:
  • báo nghỉ, booking, download, actions modal.
• Guest discovery contexts:
  • hỗ trợ course.guest_overview, course.guest_courses_preview, course.guest_course_detail_gate,
  • ưu tiên preview/conversion actions thay vì task-action của học viên đã enroll.
• AI widgets:
  • stats, schedule prep, recap, error bank, concept explain, catch-up.

5.4 Learning Management

• Priority order:
  • recovery_critical -> goal_aligned -> habit_continuity -> freshness.
• Goal compatibility:
  • numeric gap chỉ hiển thị khi profile so sánh hợp lệ + đủ confidence gate.
• Search cần ưu tiên:
  • weakest analysis unit,
  • impact cao ở 30 ngày hoạt động,
  • next best exercise.

5.5 Practice Flow

• Bắt buộc route contract đầy đủ với source_context, program, exercise_id, returnTo.
• Recommendation engine sau result:
  • habit-first, dynamic 3..7, explainability 1 primary reason/item.
• Entitlement-aware:
  • available-now priority,
  • lock teaser capped,
  • upgrade popup in-context.

5.6 Vocabulary Management

• Priority order:
  • due_words_today -> mistake_queue -> start_session -> list exploration.
• Handoff từ PRA:
  • nếu vocab_suggestion_payload hợp lệ thì đẩy vào smart mistake lane.
• Quick-start:
  • ưu tiên Ôn ngay (5 phút) khi có dữ liệu due.

6) Feature Completion Scope (Smart Search internal)

6.1 Intent Engine

• Hỗ trợ multi-intent query blending có ưu tiên.
• Synonym governance VI/EN theo kỳ.
• Conflict resolution khi query khớp nhiều intent.
• Hỗ trợ intent bundles cho query tổng quát:
  • BUNDLE_AI_FEATURES khi user gõ AI.
  • BUNDLE_PRACTICE_ACTIONS khi user gõ làm bài, làm bài tập.
• Hỗ trợ content facets để query theo loại nội dung:
  • featureFamily (ai/practice/schedule/…),
  • contentType (insight/task/plan/…),
  • contentFormat (widget/list/popup/report/…).

6.2 Ranking Engine

• Công thức baseline:
  • final = intentPriority + urgency + momentum + contextBias + recency + confidence.
• Guardrails:
  • cap low-confidence items,
  • avoid same-topic over-repeat,
  • stale-data badge khi cần.

6.3 Result Composer

• Hero Action luôn hiển thị nếu có intent match rõ.
• Grouped results theo category; mỗi group tối đa 3.
• Distinguish rõ PAGE/STEP/AI/EXEC bằng badge + CTA.

6.4 AI Layer

• Kiến trúc 2 lớp bắt buộc:
  • Layer 1 = AI Inline (xem nhanh insight + action ngắn trong Search),
  • Layer 2 = AI Tutor (đào sâu bằng chat tự do).
• Boundary rules:
  • AI Inline không phải chat,
  • AI Tutor không auto-open khi AI Inline render,
  • query task rõ (làm bài, nộp bài, đặt lịch) vẫn ưu tiên hero task trước AI lane.
• Escalation contract:
  • CTA chuẩn: Hỏi sâu hơn với AI Tutor,
  • packet tối thiểu bắt buộc: inlineFeatureKey + intentId + query + inlineSummary + sourceModule + returnTo,
  • packet khuyến nghị: evidence[] + recommendedActions[] + pageContextId + freshnessAt + confidence.
• Fallback bắt buộc:
  • nếu packet thiếu/lỗi, vẫn mở AI Tutor,
  • dùng seed tối thiểu (intentId + query + sourceModule),
  • hiển thị notice nhẹ, không chặn conversation.

6.5 Reliability and Fallback

• Adapter timeout trả partial + fallback.
• Missing context fallback an toàn về PAGE.
• No-result fallback vào AI ask với disambiguation chips.

7) AI Keyword and Widget Behavior (Concrete)

Intent	Trigger keywords (ví dụ)	Widget	Hiển thị cốt lõi	CTA chính
ACT_AI_STATS	thống kê, báo cáo, tiến độ	Unified Stats HUD	radar + trend + KPI cards + summary	Xem phân tích
ACT_AI_PRACTICE_PROCESS	quá trình, nỗ lực, streak	Practice Journey	heatmap + effort/performance/habit	Xem hành vi học
ACT_AI_SCHEDULE_PREP	chuẩn bị, ngày mai, lịch tới	Schedule Prep	timeline tương lai + debt cảnh báo	Chuẩn bị ngay
ACT_AI_SESSION_SUMMARY	tóm tắt, recap, ghi chú	Session Recap	teacher quote + key takeaways + linked homework	Đọc recap
ACT_AI_ERROR_BANK	lỗi sai, fix, mistake	Mistake Clinic	ranked error clusters + severity + fix-it	Ôn lỗi ngay
ACT_AI_PLAN	gỡ bài, bắt kịp, cứu nhịp	Catch-up Plan	absent timeline + must-watch + MVP checklist	Bắt đầu kế hoạch
ACT_AI_EXPLAIN	giải thích, tại sao sai	Concept Clarifier	definition + bad-vs-good + related concepts	Hiểu nhanh
ACT_AI_VOCAB_CONNECT	vocab context, từ này dùng ở đâu	Vocab Bridge	word hero + future lesson context + prime cards	Ôn từ ngay
ACT_AI_TUTOR	hỏi AI, chat AI	Floating Tutor	contextual handoff message	Mở portal

AI inline feature key contract (để đồng nhất UX + telemetry)

• Mỗi widget AI phải có inlineFeatureKey ổn định để dùng cho ranking, handoff và đo lường:
  • AIF_MOCK_FULL_TEST (AI Thi thử Full Test),
  • AIF_LEARNING_PERFORMANCE_RADAR (Phân tích hiệu suất học tập),
  • AIF_PRACTICE_BEHAVIOR_VIEW (Xem hành vi luyện tập),
  • các key khác map tại ux-patterns/SSP_AI_Keyword_Widget_Map.md.
• Mỗi card AI inline phải có:
  • 1 CTA hành động tại module,
  • 1 CTA escalation sang AI Tutor (Hỏi sâu hơn với AI Tutor).
• Khi user bấm CTA escalation, Smart Search bắt buộc gửi inlineFeatureKey theo packet để AI Tutor biết chính xác card nguồn.

Umbrella keyword behavior (bắt buộc)

• Query AI:
  • render AI Feature Catalog và liệt kê đầy đủ AI actions khả dụng trong context hiện tại.
  • không cắt còn 3 như prefix completion.
• Query làm bài / làm bài tập:
  • render Practice Action Catalog và liệt kê đầy đủ nhóm tác vụ làm bài/luyện tập.
  • ưu tiên actions available-now, sau đó mới tới group AI hỗ trợ.

Facet keyword behavior (bắt buộc)

• Query theo loại nội dung (báo cáo, widget, checklist, popup, task):
  • không bắt user nhớ tên tính năng.
  • trả danh sách feature có cùng facet tags trong context hiện tại.
• Facet match có priority cao hơn title contains, thấp hơn umbrella bundles.

AI widget rendering states (bắt buộc)

• loading: skeleton + context label.
• success: summary + evidence + CTA.
• stale: stale badge + refresh CTA.
• empty-data: onboarding insight + next-step CTA.
• error: brief error + retry + module-deeplink fallback.

8) UI Placeholder Copy Rules

• Mỗi placeholder phải bắt đầu bằng ngôn ngữ hành động, không mô tả chung chung.
• Mỗi module có placeholder riêng nhưng giữ cùng voice.
• Zero-state chips phải bám context hiện tại (không random).

Placeholder examples

• Home: Hôm nay bạn muốn học tiếp gì?
• Course: Làm bài tập, xem lịch, báo nghỉ, hỏi AI...
• Learning: Tìm kỹ năng yếu và bài nên luyện tiếp...
• Practice: Tìm bài theo dạng, kỹ năng hoặc mục tiêu...
• Vocabulary: Ôn từ cần học hôm nay hoặc từ hay sai...

9) Telemetry and Quality Gates

• Baseline events:
  • search_opened,
  • search_query_submitted,
  • search_result_clicked,
  • search_result_depth,
  • search_handoff_started,
  • search_handoff_completed,
  • search_zero_result,
  • search_ai_inline_rendered,
  • search_ai_tutor_handoff_start,
  • search_ai_tutor_handoff_success,
  • search_ai_tutor_handoff_fallback_open.
• Quality gates trước khi mở rộng phase:
  • handoff success,
  • zero-result,
  • recommendation-to-attempt,
  • latency p95.

10) Reference Maturity Map (Non-prescriptive)

1. Stabilize core contracts (intent/context/result/ranking) as shared standard.
2. Lock UI states + placeholders + umbrella/facet behavior across surfaces.
3. Maintain cross-module route contract safety and fallback safety.
4. Enforce AI freshness/confidence/evidence gates as default quality rule.
5. Maintain optimization loop using benchmark queries + telemetry + controlled experiments.
6. Keep governance stable while allowing additive evolution of intents/facets.

11) Anti-fragmentation Rules (Long-term)

• Mọi thay đổi Search phải cập nhật vào Smart Search Platform folder trước.
• Không tạo riêng “search logic local” trong module nếu có thể dùng contract chung.
• Intent mới chỉ thêm khi governance board duyệt.
• Mọi module phải giữ cùng chuẩn depth/badge/CTA semantics.
• Không mở rộng logic vượt quá pain thực tế đã được xác nhận bằng dữ liệu/feedback.
• Ưu tiên “ít cơ chế, rõ hành vi” hơn “nhiều cơ chế nhưng khó dự đoán”.

References

• SSP_INDEX.md
• SSP_Smart_Search_Logic_Explainer.md
• SSP_00_Overview.md
• contracts/SSP_Intent_Taxonomy_Result_Contract.md
• contracts/SSP_Context_Pack_Adapter_Contracts.md
• contracts/SSP_Implementation_Logic_Contract.md
• governance/SSP_Deep_Dive_and_Completion_Plan.md
• ux-patterns/SSP_Area_Positioning_Page_Behavior.md
• ux-patterns/SSP_UI_Placeholder_By_Flow.md
• ux-patterns/SSP_AI_Keyword_Widget_Map.md
• ux-patterns/SSP_AI_Innovation_By_Area.md
• governance/SSP_Optimization_Framework.md
• area-bundles/SSP_Program_Course_Discovery_Search_Bundles.md
• governance/SSP_Rollout_Governance.md
• ../Home & Discovery/HOME_ENG_Home_Post_Login.md (archived, DEC-0096)
• ../Practice Flow/PRA_Entry_Routing_Contracts.md
• ../Practice Flow/PRA_Result_Flow.md
• ../Learning Management/LM_Metrics.md
• ../Course Management/CM_FEATURE_Smart_Search.md