Search

@nx/search là một package dạng thư viện, không phải ứng dụng IGNIS độc lập. Nó cung cấp bốn IGNIS component để một host service (hiện là commerce) đăng ký, cùng với một SearchableControllerMixin mà consumer gắn vào các REST controller của riêng mình. Nó giữ ~8 Typesense collection đồng bộ với PostgreSQL qua một pipeline CDC Debezium → Kafka và phục vụ tìm kiếm theo từ khoá + ngữ nghĩa tuỳ chọn.

1. Tham chiếu nhanh

Thuộc tính	Giá trị
Package	@nx/search
Code	LIB-SEARCH
Loại	Thư viện / component package (dùng bởi commerce)
Runtime	Bun (>=1.3.8) - chạy bên trong process host
Base Class	N/A - không có lớp Application; export các lớp con BaseComponent
Vị trí	packages/search
Base Path	/search (mount dưới base path của host service)
Dev Port	N/A - package thư viện, không có port riêng
Container Port	N/A - chạy trong container host (commerce)
Snowflake ID	N/A - host service sở hữu cấp phát ID
Search Engine	Typesense ^3.0.3 (nodes dạng protocol:host:port)
Nguồn đồng bộ	Debezium → Kafka CDC (schema public, pricing, inventory)
Được dùng bởi	commerce
Binding Namespace	@nx/search

Bản chất thư viện: không có application.ts, index.ts → bootstrapApplication(), port riêng, hay DB schema riêng. Ứng dụng host đăng ký bốn component theo thứ tự phụ thuộc; tất cả collection, service, CDC consumer, và SearchController chung được gắn vào IGNIS container của host. Xem ADR-0001.

2. Mục đích & Phạm vi

Bao gồm	Không bao gồm
Tìm kiếm full-text theo từ khoá trên 8 Typesense collection	Sở hữu các bảng nguồn (commerce/pricing/inventory sở hữu chúng)
Tìm kiếm ngữ nghĩa / hybrid tuỳ chọn qua auto-embedding	Vận hành model embedding (cấu hình Typesense/Google bên ngoài)
CDC consumer: đồng bộ Debezium → Kafka → Typesense	Bản thân Debezium connector (do infra sở hữu)
Lan toả cascade từ bảng join/liên quan tới document chính	Write API để thay đổi document trực tiếp từ client
Dịch where/order/fields/include kiểu Ignis → Typesense	Toán tử khớp mẫu (like/ilike/regexp) - dùng text search
SearchableControllerMixin cho /search + /search/count theo từng entity	Policy về scope theo tenant (host ghi đè resolveSearchScope)
Phát hiện schema drift (migration thủ công khi sai lệch)	Tự dựng lại collection đã sai lệch (làm thủ công, tránh mất dữ liệu)

3. Tech Stack

Bên ngoài:

Thư viện	Mục đích
@venizia/ignis	IoC container, BaseComponent, BaseRestController, DI
@venizia/ignis-helpers	Logger, applicationEnvironment, HTTP helpers
typesense	Typesense client - CRUD collection, search, import
@platformatic/kafka	CDC Kafka consumer + DLQ producer
avsc	Giải mã Avro cho payload CDC Debezium
@hono/zod-openapi	Schema Zod request/response cho route search
zod	Kiểm tra schema
lodash	Tiện ích

Nội bộ:

Package	Mục đích
@nx/core	CdcTables, ConfigurationRepository, EnvironmentKeys, SystemConfigurations, base class, DI

4. Cấu trúc Project

packages/search/
├── src/
│   ├── index.ts                    # Barrel - re-export components, services, helpers
│   ├── component.ts                # ApplicationSearchComponent
│   ├── components/
│   │   ├── embedding-configuration.component.ts
│   │   ├── typesense-search-engine.component.ts
│   │   └── cdc.component.ts
│   ├── common/                     # keys, environments, constants, kafka-topics,
│   │                               # search.types, relations, pipeline-config types
│   ├── configurations/             # 8 collection configs + schema-fragments.ts
│   ├── controllers/                # SearchController + searchable.mixin + definitions
│   ├── datasources/                # (re-export)
│   ├── helpers/                    # typesense, converter, registry, include, migration
│   ├── mappers/                    # DB row → Typesense doc (theo từng entity + *-info)
│   ├── services/
│   │   ├── search/                 # SearchService, SearchIndexingService
│   │   ├── cdc/                    # kafka, cdc, cascade, enrichment, circuit-breaker
│   │   └── search-configuration.service.ts
│   ├── migrations/processes/       # backfill processes
│   └── utilities/                  # error-classifier, with-retry, errors
├── scripts/                        # migrate, rebuild-collection, backfill-search
└── package.json

Không có application.ts / migrate.ts / models/ / repositories riêng - đây là thư viện, không phải service.

5. Architecture

@nx/search chạy bên trong host service (commerce). Sơ đồ thể hiện nó được nhúng.

Chi tiết: xem Architecture.

6. Snapshot Domain

Không có schema PostgreSQL riêng - "domain" là tập các Typesense collection, mỗi collection là một projection phi chuẩn hoá của các bảng nguồn.

Schema collection đầy đủ + nguồn cascade: xem Domain Model.

7. Tổng quan bề mặt

REST controller - @nx/search mở ra hai endpoint; phần lớn consumer dùng mixin thay vì controller chung. Schema đầy đủ được render trực tiếp từ /doc/openapi.json của host service (commerce), không phải từ thư viện này.

Nguồn	Base path	Endpoints
SearchController (chung)	/search/{collectionName}	2 (GET, GET …/count)
SearchableControllerMixin (theo từng entity, trên controller của consumer)	<entity>/search	2 mỗi controller

Permission	Action
search:search	Tìm kiếm document
search:search-count	Đếm số document khớp

Async topics (tham chiếu đầy đủ trong API Events):

Hướng	Số lượng
Inbound (Kafka CDC)	18 topic trên 3 schema
Outbound (Kafka)	1 - DLQ (nx.seller.cdc.dlq)
WebSocket out	0
BullMQ jobs in/out	0

8. Components

Đăng ký bởi host theo thứ tự này:

Thứ tự	Component	File	Mục đích
1	ApplicationSearchComponent	src/component.ts	Đọc Typesense nodes + 8 collection config từ env, bind SEARCH_COMPONENT_OPTIONS, đăng ký ConfigurationRepository + SearchConfigurationService
2	ApplicationEmbeddingConfigurationComponent	src/components/embedding-configuration.component.ts	Nạp config model embedding tuỳ chọn + config pipeline từ DB; bind EMBEDDING_MODEL_CONFIG + SEARCH_PIPELINE_CONFIG
3	TypesenseSearchEngineComponent	src/components/typesense-search-engine.component.ts	Tạo TypesenseHelper, đăng ký collection vào CollectionRegistry (gắn embed.from), đăng ký service + SearchController, chạy kiểm tra schema-drift
4	ApplicationCdcComponent	src/components/cdc.component.ts	Khởi động CDCKafkaService trên ALL_CDC_TOPICS, kèm DLQ + circuit breaker tuỳ chọn

9. Services

Service	File	Mô tả ngắn
SearchService	src/services/search/search.service.ts	Phía truy vấn: filter Ignis → Typesense, phân giải include, trả về { count, data }
SearchIndexingService	src/services/search/search-indexing.service.ts	Phía ghi: upsert/xoá đơn lẻ + theo batch, chỉ số throughput, getHealth()
CDCService	src/services/cdc/cdc.service.ts	handleBatch() - định tuyến các dòng CDC tới mapper, upsert/xoá
CDCCascadeService	src/services/cdc/cdc-cascade.service.ts	Lan toả thay đổi của bảng join/liên quan để tính lại document chính
CDCEnrichmentService	src/services/cdc/cdc-enrichment.service.ts	Bổ sung dữ liệu xuyên collection vào document
CDCCircuitBreakerService	src/services/cdc/cdc-circuit-breaker.service.ts	Thăm dò sức khoẻ Typesense, tạm dừng tiêu thụ khi sự cố (tuỳ chọn bật)
CDCKafkaService	src/services/cdc/cdc-kafka.service.ts	Kafka consumer, gom batch, định tuyến DLQ
SearchConfigurationService	src/services/search-configuration.service.ts	Đọc config embedding + pipeline từ bảng Configuration

10. Repositories

Repository	Bảng	Nguồn	Method tuỳ chỉnh
ConfigurationRepository	core.Configuration	@nx/core	- (đăng ký, không sở hữu; đọc config embedding/pipeline)

Search không sở hữu bảng nào; nó không có repository riêng.

11. Entry Points

File	Mục đích
src/index.ts	Barrel export - host import component từ đây
src/component.ts	ApplicationSearchComponent (component đầu vào)
scripts/migrate.ts	Migration schema chỉ-thêm - diff config với Typesense đang chạy, PATCH trường (migrate[:apply])
scripts/rebuild-collection.ts	Dựng lại collection kiểu blue-green với đổi alias nguyên tử (migrate:rebuild[:apply])
scripts/backfill-search.ts	Backfill các dòng DB sẵn có bằng incremental snapshot của Debezium (backfill[:apply])

Không có bootstrapApplication() / bootstrapMigration() - những cái đó thuộc về host service.

12. Configuration

Typesense nodes/API key, env CDC + circuit breaker, config embedding + pipeline lưu trong DB: xem Configuration.

13. Operations

Chạy bên trong commerce - không triển khai độc lập. Migration schema, độ trễ CDC, chẩn đoán đồng bộ: xem Operations.

14. Trang liên quan

• Architecture
• Domain Model
• API Events
• Integration
• Configuration
• Operations
• Semantic Search Selection - đánh giá vector DB + model embedding
• Decisions
• REST endpoints - OpenAPI trực tiếp tại host service /v1/api/commerce/doc/openapi.json
• Commerce - host / nơi dùng chính