Integration

@nx/search tích hợp bằng cách được nhúng, không gọi qua mạng. Host đăng ký các component của nó và dùng SearchService + SearchableControllerMixin in-process.

1. Service liên quan

Service	Hướng	Bề mặt	Contract	Auth	Chế độ lỗi
commerce (host)	←	Trong tiến trình - đăng ký 4 component, gọi SearchService, áp dụng SearchableControllerMixin	Library API	Kế thừa (host JWT/Basic)	Exception trong tiến trình
@nx/core	→	ConfigurationRepository, CdcTables, EnvironmentKeys, SystemConfigurations	Library	-	Phụ thuộc lúc biên dịch

Commerce áp dụng mixin lên các controller organizer / merchant / category / device / sale-channel / product / product-variant của nó; mỗi controller ghi đè resolveSearchScope() để chèn một scope where theo merchant/tenant.

2. Hệ thống bên ngoài

Hệ thống	Hướng	Bề mặt	Auth	Chế độ lỗi
Typesense	→	HTTP (typesense client) - search, import, CRUD collection, kiểm tra sức khoẻ	API key (APP_ENV_TYPESENSE_API_KEY)	Thăm dò sức khoẻ → circuit breaker tạm dừng CDC; lỗi search được phân loại + thử lại
Kafka + Debezium	←	Tiêu thụ CDC topics (@platformatic/kafka, Avro qua avsc)	SASL tuỳ chọn (APP_ENV_KAFKA_SASL_*)	DLQ cho message lỗi; offset không commit khi thất bại

3. Luồng xuyên service quan trọng

3.1 Consumer gắn search theo từng entity (lúc build)

Bước	Chi tiết
2	Nodes được phân tích từ CSV protocol:host:port; mặc định http:localhost:8108
6	embed.from chỉ được gắn khi có config embedding trong DB + collection có embeddingField/embeddingFields
7	Collection còn thiếu sẽ được tạo; collection đã sai lệch được ghi log (migration thủ công)

3.2 Tìm kiếm theo scope tenant lúc request

Bước	Chi tiết
2	Bản ghi đè của host trả về một object where; mixin gộp nó với filter của caller bằng and
3	Scope rỗng (null) nghĩa là tìm kiếm mở (không giới hạn tenant)

4. Độ ổn định của Contract

Bề mặt	Độ ổn định	Đánh phiên bản
Thứ tự đăng ký component	ổn định	Library semver (@nx/search)
SearchableControllerMixin(Base, options)	ổn định	Library semver
ISearchParams / ISearchResponse	ổn định	Library types
GET /search/{collectionName} (controller chung)	ổn định	Host URL /v1/
Tên CDC topic (nx.seller.{schema}.{table})	gắn chặt với config Debezium connector	Do connector sở hữu
Schema Typesense collection	tiến hoá dần (chỉ thêm, qua script backfill)	Migration thủ công khi sai lệch

5. Trang liên quan

• API Events
• Configuration
• Decisions
• Commerce - host service