feat(search): add Search Intelligence module

2026-07-10 13:25:31 +04:00
parent 494451bb96
commit 7ecb19cb1a
29 changed files with 1030 additions and 251 deletions
--- a/docs/Search.md
+++ b/docs/Search.md
@@ -0,0 +1,188 @@
+# Search Intelligence Engine - Sprint 12
+
+## Scope
+
+Sprint 12 introduces a standalone Search Feature architecture reusable across marketplaces.
+
+Constraints respected:
+- No authentication changes
+- No payment changes
+- No runtime bootstrap changes
+- No Widget Manifest changes
+- No Section Engine changes
+- No Product/Catalog business rule changes
+
+## Architecture
+
+```text
+src/app/features/search/
+  components/
+    search-bar/
+    trending-searches/
+    empty-results/
+  services/
+    search-autocomplete.service.ts
+    search-history.service.ts
+    search-history.repository.ts
+    search-trending.service.ts
+    search-cache.service.ts
+    search-analytics.service.ts
+  facade/
+    search.facade.ts
+  models/
+    search.model.ts
+    search-state.model.ts
+  store/
+    search.store.ts
+  utils/
+    search-query-key.util.ts
+```
+
+Legacy compatibility kept:
+- `src/app/facades/platform/search.facade.ts` now re-exports feature facade
+- `src/app/core/search/models/*` re-export feature models
+- `src/app/core/search/services/search-history.service.ts` re-exports feature history service
+
+## Facade API
+
+Search UI communicates through `SearchFacade`:
+- `search(query)`
+- `loadCatalog(query)`
+- `suggestions(query, products, categories, limit)`
+- `autocomplete(query, products, categories, limit)`
+- `getSearchHistory()`
+- `pushSearchHistory(term, maxHistory)`
+- `clearSearchHistory()`
+- `trending()`
+- existing helpers reused by catalog: filters, sorting, pagination, query params
+
+## State Model
+
+Managed in `SearchStore`:
+- current query
+- loading
+- results
+- suggestions
+- recent searches
+- popular searches
+- selected filters
+- current sort
+- current page
+- total results
+
+Compatibility aliases preserved for existing catalog integration.
+
+## Suggestion Model
+
+Each suggestion includes:
+- `type`
+- `title`
+- `subtitle`
+- `icon`
+- `target`
+
+Supported suggestion types:
+- product
+- category
+- brand
+- collection
+- seller
+- static-page
+- ai
+
+## Autocomplete
+
+Behavior:
+- Debounced typing (`debounceTime`)
+- Previous request cancellation (`switchMap`)
+- Distinct query suppression (`distinctUntilChanged`)
+- Suggestion state controlled by facade/store
+
+Current source:
+- In-memory products/categories/tags
+
+Future-ready for backend endpoint:
+- autocomplete service can switch to API provider without UI changes
+
+## Search History
+
+Abstraction:
+- `SearchHistoryRepository`
+  - `LocalSearchHistoryRepository` for guest users
+  - `BackendSearchHistoryRepository` placeholder for logged users
+
+Behavior:
+- Newest first
+- Configurable max length
+- Clear history support
+
+## Trending Searches
+
+`SearchTrendingService` contract introduced.
+
+Current behavior:
+- Returns `null` when endpoint unavailable
+- UI hides trending block gracefully
+
+## Empty Results UX
+
+Reusable empty state supports:
+- no results messaging
+- popular categories
+- popular searches
+- recommended products
+- reset filters action
+
+## Filters and Sorting Reuse
+
+No duplicated filter/sort engines.
+
+Search facade reuses existing catalog filter metadata generation,
+filter application, and sort application pathways.
+
+## Search Bar UX
+
+Reusable `SearchBarComponent` supports:
+- ESC closes suggestions/overlay
+- arrow navigation
+- Enter opens highlighted suggestion
+- mouse selection
+- loading indicator
+- clear button
+- mobile fullscreen overlay with large touch targets
+
+## Performance
+
+Implemented:
+- debounce
+- switch-map cancellation
+- duplicate suppression
+- query-result cache for repeated searches
+
+## Analytics Architecture
+
+`SearchAnalyticsService` provides event factory only.
+
+Event shape:
+- query
+- tenant
+- language
+- timestamp
+- result count
+
+No analytics transport implementation in Sprint 12.
+
+## Configuration and Extension Points
+
+Extension points:
+- replace history repository with backend endpoint
+- replace trending provider with backend endpoint
+- replace autocomplete provider with API or AI provider
+- enrich suggestion mapper with static pages/sellers/collections sources
+
+## Responsiveness and Accessibility
+
+- Desktop suggestion dropdown behavior
+- Mobile fullscreen overlay behavior
+- ARIA labels and keyboard navigation
+- touch target sizing in mobile mode