Smart Search Platform - Implementation Logic Contract

SharedShared Capabilities2.393 words12 min read

activebyDOL Product Design

Mục tiêu

Chuyển logic Smart Search từ mức spec sang mức có thể triển khai runtime.
Đảm bảo placeholder và thứ tự ưu tiên kết quả thay đổi đúng theo page context.
Giữ cách làm nhất quán, dễ kiểm thử, dễ mở rộng.
Đây là runtime reference contract dùng chung, không phải tài liệu phân việc theo sprint/team.

Định nghĩa Done (cho logic runtime)

Placeholder không còn giống nhau trên mọi page.
Hero action thay đổi theo area/page và tín hiệu ngữ cảnh.
Ranking có context bias rõ ràng, không chỉ keyword match.
Có fallback an toàn khi thiếu dữ liệu hoặc timeout.
Có telemetry tối thiểu cho tất cả nhánh chính.

1) Thành phần bắt buộc cần có trong runtime

1.1 AreaProfileRegistry

Mỗi area khai báo một profile chuẩn:

intentPriorityMap
placeholderPool
quickChipPool
lanePolicy
aiIntentPolicy
handoffPolicy

Ví dụ tối thiểu cho vocabulary:

lane: Due words today -> Mistake-based list -> Start session
hero rule: nếu due_words_today > 0 thì Ôn ngay (5 phút)
AI policy: ACT_AI_VOCAB_CONNECT ưu tiên cao, ACT_AI_TUTOR on-demand

1.2 PageContextResolver

Resolver phải map route hiện tại về pageContextId, ví dụ:

/dol-english -> home.prelogin_main
/dol-english/program/:programSlug -> home.program_landing_prelogin
/dol-english/course-management -> course.guest_overview
/dol-english/courses -> course.guest_courses_preview
/dol-english/course/:courseId -> course.guest_course_detail_gate
/home -> home.main
/course/:id -> course.dashboard
/course/:id/schedule -> course.schedule_tab
/course/:id/assignments -> course.assignment_tab
/course/:id/tests -> course.test_tab
/learning -> learning.dashboard
/learning/history -> learning.history_tab
/practice/result/:attemptId -> practice.result
/vocabulary -> vocabulary.dashboard

Resolver cũng phải đính kèm local signals:

due counts
in-progress item
streak
urgency flags
entitlement flags
discovery signals (preferredProgram, preferredLane, timePreference)
conversion signals (returnTo, entrySource, consultationEligible)

1.3 PlaceholderComposer

Logic chọn placeholder theo thứ tự:

pageContext-specific placeholder.
fallback placeholder trong cùng area.
fallback global safe placeholder.

Rule:

chỉ rotate trong pool của page context hiện tại.
tối đa 2 placeholder luân phiên cho 1 context.
quick chips tối đa 3 và có ít nhất 1 chip từ local signals.

1.4 RankingComposer

Công thức chuẩn:

finalScore = intentPriority + urgencyBoost + momentumBoost + pageContextBoost + recencyBoost + confidenceBoost + entitlementBoost

Rule:

+3 nếu kết quả đúng page hiện tại.
+2 nếu cùng area nhưng khác page.
+1 nếu cross-area nhưng có continuity signal.
ưu tiên available-now, giảm điểm item bị khóa.

1.5 ResultComposer

Khuôn hiển thị bắt buộc:

1 Hero Action
Grouped results (mỗi group tối đa 3)
AI lane chỉ bật khi phù hợp policy hoặc user gọi AI rõ ràng

Caps:

prefix completions <= 3
low-confidence item <= 1 (khi inventory đủ)

1.6 UmbrellaQueryExpander (Msearch)

Phải có dictionary trigger cho query tổng quát:
- AI umbrella: ai, tính năng ai, ai có gì, trợ lý ai.
- Practice umbrella: làm bài, làm bài tập, luyện tập, practice, làm đề.
Khi match trigger:
- chuyển sang bundle mode,
- expand từ query -> intent bundle (BUNDLE_AI_FEATURES hoặc BUNDLE_PRACTICE_ACTIONS),
- trả danh sách đầy đủ theo group thay vì top-3 prefix completions.
Bundle mode vẫn phải tôn trọng:
- area policy (intent nào đang off thì không đưa vào primary group),
- entitlement constraints,
- continuity/handoff contracts.

1.7 ContentFacetIndexer (Msearch)

Phải có index metadata cho từng feature/result:
- featureFamily, contentType, contentFormat, keywordAliases[].
Query parser phải detect facet tokens:
- ví dụ báo cáo, thống kê, widget, popup, checklist, task, danh sách.
Khi detect facet:
- chuyển sang facet mode,
- ưu tiên filter theo facet tags trước title match,
- render danh sách đầy đủ kết quả thuộc facet trong context hiện tại.
Ưu tiên xử lý:
- umbrella mode > facet mode > semantic mode.

1.8 AIInlineSurfaceArchetypeRegistry

AI inline là một surface system, không phải một widget/card cố định cho mọi page.
Mỗi pageContextId phải map vào đúng 1 primary archetype theo main question và page purpose.
Runtime chỉ nên dùng một trong các archetype chuẩn sau:
- action_hub:
  - dùng cho page cần trả lời nhanh làm gì tiếp theo ngay bây giờ,
  - output mặc định: 1 primary next step + 1..2 alternate step + short why-now tags,
  - không ép render evidence block nặng.
- strategy_panel:
  - dùng cho page cần ưu tiên chiến lược hoặc sắp thứ tự hành động,
  - output mặc định: strategic summary + ordered next steps + 1 primary CTA,
  - evidence là optional, chỉ hiện khi giúp quyết định tốt hơn.
- coaching_rail:
  - dùng cho active work contexts như attempt,
  - output mặc định: micro hint + scaffolded step + self-check,
  - không render report, không biến thành planning panel.
- analysis_panel:
  - dùng cho page mà câu hỏi chính là điều gì đang sai / nên sửa gì trước,
  - output mặc định: signal -> meaning -> priority fix -> next action,
  - evidence có thể hiển thị, nhưng phải ngắn và bám đúng source data.
- queue_guide:
  - dùng cho page có hàng đợi hoặc resource queue rõ,
  - output mặc định: do-now item + short clarifier + learn-more/deeper CTA,
  - không ép render strategy summary dài nếu page chỉ cần điều hướng.
Rules:
- archetype được quyết định bởi page purpose, không chỉ bởi intent keyword.
- chỉ cho phép secondary variant khi vẫn giữ cùng main question của page.
- page action-first không được bị kéo sang evidence-heavy layout chỉ vì dùng chung AI lane.
- page diagnosis-first không được rút xuống thành card quá ngắn nếu làm mất why this matters.

1.9 AIInlineHandoffGuard

Bắt buộc phân tách runtime theo 2 lớp:
- Layer 1: AI Inline surfaces theo archetype của page hiện tại,
- Layer 2: AI Tutor chat (đào sâu).
Rules:
- AI Tutor chỉ được mở qua CTA chủ động (Hỏi sâu hơn với AI Tutor) hoặc query chat trực tiếp.
- render AI Inline không được tự mở AI Tutor.
- query task rõ không để AI lane vượt hero task.
Packet validation trước khi open Tutor:
- Required:
  - inlineFeatureKey,
  - intentId,
  - query,
  - inlineSummary,
  - sourceModule,
  - returnTo.
- Recommended:
  - evidence[],
  - recommendedActions[],
  - pageContextId,
  - freshnessAt,
  - confidence.
Compression tier policy:
- chọn payloadTier = full|balanced|lite theo device/network profile.
- áp caps runtime:
  - evidence[] = 3/2/0-1,
  - recommendedActions[] = 3/2/1,
  - inlineSummary cắt theo tier.
- không được drop packet required minimum fields.
Full-test query mapping:
- cluster thi thu/full test/mock test map canonical intent ACT_TEST,
- dùng variant AIF_MOCK_FULL_TEST thay vì tạo intent mới.
Fallback:
- nếu packet thiếu/lỗi, vẫn mở AI Tutor với seed tối thiểu (intentId + query + sourceModule),
- hiển thị notice nhẹ, không chặn hội thoại.

1.10 Pragmatic Complexity Caps

Multi-intent:
- chỉ resolve tối đa 2 intent chính cho 1 query trong runtime mặc định.
- intent thứ 3 trở lên chỉ hiển thị dưới dạng disambiguation options.
Disambiguation:
- tối đa 3 lựa chọn mỗi lần.
- chỉ cho phép 1 vòng hỏi lại, sau đó phải fallback an toàn.
Hero policy:
- luôn chỉ có 1 hero action.
- hero phải là action khả thi ngay (available-now) nếu tồn tại.
AI lane:
- không quá 2 cards trong cùng state render.
- AI cards không vượt lên hero task khi query là task/operation rõ.
Fallback:
- timeout không được trả màn rỗng; bắt buộc có safe actionable fallback.

1.11 Runtime Optimization Order (No-sprawl)

Khi cần cải thiện chất lượng search, phải đi theo thứ tự:
1. cập nhật normalization dictionary + synonym/alias,
2. cập nhật facet metadata cho kết quả,
3. điều chỉnh ranking weights,
4. điều chỉnh result composition,
5. chỉ đề xuất cơ chế runtime mới nếu 1-4 không đạt quality gate.
Không được triển khai đồng thời nhiều lớp logic mới trong một lần release.
Mọi thay đổi runtime phải map được về một mục đo lường cụ thể trong telemetry.

2) State machine triển khai

closed
focus_zero_state
typing_prefix
typing_umbrella
typing_facet
typing_semantic
inline_ai
no_result
error

Chuyển trạng thái:

focus + query rỗng -> focus_zero_state
query 1-2 ký tự -> typing_prefix
query match umbrella trigger -> typing_umbrella (ưu tiên cao hơn prefix/semantic)
query match content facet token -> typing_facet
query >=3 ký tự -> typing_semantic
chọn AI intent -> inline_ai
không có kết quả -> no_result
timeout/error -> error

3) Điều kiện dữ liệu tối thiểu theo area

Area	Signals tối thiểu	Nếu thiếu dữ liệu
Home	continue item/due72h/streak (post-login) hoặc discovery + conversion signals (pre-login)	fallback sang quick actions/lane discovery mặc định
Course	due tasks, next class, in-progress, debt tasks, ops eligibility	fallback sang page-level actions + safe ops links
Learning	weak unit, impact tier, confidence, high_attention, goal comparison mode	ẩn numeric gap, giữ trend summary + mở quick actions
Practice	route params, available-now items	fallback nearest ladder + notice
Vocabulary	due_words_today, mistake queue	fallback start session + list exploration

4) Handoff contract tối thiểu

mọi STEP sang Practice phải có source_context/program/exercise_id/returnTo.
PRA -> Vocabulary phải hỗ trợ vocab_suggestion_payload.
AI inline -> AI Tutor phải giữ packet tối thiểu:
- inlineFeatureKey + intentId + query + inlineSummary + sourceModule + returnTo.
Packet phải được nén theo payloadTier nhưng vẫn giữ required minimum + fallback invariant.
AI Thi thu Full Test phải đi qua intent-variant mapping (ACT_TEST + AIF_MOCK_FULL_TEST).
nếu packet lỗi/thiếu:
- mở AI Tutor với seed fallback (intentId + query + sourceModule) + notice nhẹ.
discovery pre-login -> auth phải có returnTo + entrySource + targetEntity.

5) Pseudocode tham chiếu

function composeSearchSurface(query: string, contextPack: SmartSearchContextPack) {
  const pageContext = resolvePageContext(contextPack);
  const areaProfile = getAreaProfile(pageContext.area);
  const placeholders = composePlaceholders(pageContext, areaProfile);

  if (!query) return buildZeroState(pageContext, areaProfile, placeholders);

  const umbrellaBundle = detectUmbrellaBundle(query);
  if (umbrellaBundle) {
    const bundleResults = expandBundleIntents(umbrellaBundle, areaProfile, contextPack);
    return composeBundleResults(bundleResults, pageContext, umbrellaBundle);
  }

  const facetFilter = detectFacetFilter(query);
  if (facetFilter) {
    const facetResults = filterByFacet(facetFilter, contextPack, areaProfile);
    return composeFacetResults(facetResults, pageContext, facetFilter);
  }

  const intents = detectIntents(query, areaProfile);
  const rawResults = dispatchToAdapters(intents, contextPack);
  const ranked = rankResults(rawResults, pageContext, areaProfile);

  return composeResults(ranked, pageContext, areaProfile, query);
}

6) QA checklist bắt buộc

Cùng 1 query nhưng ở 2 page khác nhau phải cho thứ tự kết quả khác nếu context khác.
Không còn placeholder “y chang” trên mọi page sau khi có pageContext.
Query AI phải trả danh sách toàn bộ AI features khả dụng theo context (không bị cắt ở 3 kết quả).
Query làm bài hoặc làm bài tập phải trả danh sách đầy đủ nhóm tác vụ làm bài/luyện tập.
Cùng một intent AI nhưng ở home/program/result/course/vocabulary phải có thể render theo archetype khác nhau nếu main question khác.
Query theo facet (báo cáo, widget, checklist, popup, task) phải trả đầy đủ feature cùng loại, kể cả khi không match title.
Multi-intent query dài không được làm UI quá tải; phải giữ cap và disambiguation đúng contract.
Hero action đúng với rule urgency/momentum của area hiện tại.
No-result luôn có CTA phục hồi (không dead-end).
Khi adapter timeout vẫn có fallback action usable.
Handoff PRA và VOC không mất context quan trọng.
AI Tutor không auto-open từ render inline AI.
CTA Hỏi sâu hơn với AI Tutor luôn mở được ngay cả khi packet degraded.
Mobile packet balanced/lite vẫn giữ được open-chat continuity.
Query thi thu/full test/mock test resolve đúng variant AIF_MOCK_FULL_TEST dưới canonical ACT_TEST.

7) Telemetry tối thiểu

search_opened
search_page_context_resolved
search_placeholder_rendered
search_chip_clicked
search_result_clicked
search_umbrella_detected
search_umbrella_result_rendered
search_facet_detected
search_facet_result_rendered
search_hero_clicked
search_handoff_started
search_handoff_completed
search_zero_result
search_error_fallback_rendered
search_ai_inline_rendered
search_ai_tutor_handoff_start
search_ai_tutor_handoff_success
search_ai_tutor_handoff_fallback_open

8) Reference maturity waves (non-prescriptive)

Wave A: giữ ổn định các thành phần nền (resolver, composer, fallback).
Wave B: tăng chất lượng xếp hạng (urgency + context + personalization).
Wave C: tăng độ chính xác query (umbrella + facet + disambiguation).
Wave D: tăng độ tin cậy hệ thống (freshness/confidence gates + handoff safety + telemetry depth).

References

Change log

2026-02-28: title: “Smart Search Platform - Implementation Logic Contract”
2026-03-01: Add AI Inline vs AI Tutor runtime boundary, packet validation, and fallback handoff telemetry.
2026-03-01: Add mobile payload compression tiers and AI Thi thu Full Test intent-variant resolver policy.