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 anh em

Sister	Direction	Surface	Contract	Auth	Failure Mode
commerce (host)	←	In-process — đăng ký 4 component, gọi SearchService, áp dụng SearchableControllerMixin	Library API	Kế thừa (host JWT/Basic)	Exception in-process
@nx/core	→	ConfigurationRepository, CdcTables, EnvironmentKeys, SystemConfigurations	Library	—	Dependency compile-time

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

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

System	Direction	Surface	Auth	Failure Mode
Typesense	→	HTTP (typesense client) — search, import, collection CRUD, health	API key (APP_ENV_TYPESENSE_API_KEY)	Health probe → circuit breaker pause CDC; lỗi search được phân loại + retry
Kafka + Debezium	←	Consume CDC topics (@platformatic/kafka, Avro qua avsc)	SASL tùy chọn (APP_ENV_KAFKA_SASL_*)	DLQ cho message độc; offset không commit khi fail

3. Luồng cross-service quan trọng

3.1 Consumer nối search theo từng entity (build-time)

Bước	Chi tiết
2	Nodes parse từ CSV protocol:host:port; mặc định http:localhost:8108
6	embed.from chỉ nối khi có config embedding DB + collection có embeddingField/embeddingFields
7	Collection thiếu được tạo; cái đã phân kỳ được log (migration thủ công)

3.2 Search scope theo tenant lúc request

Bước	Chi tiết
2	Override của host trả về một object where; mixin and-merge nó với filter của caller
3	Scope rỗng (null) nghĩa là search mở (không giới hạn tenant)

4. Tính ổn định Contract

Surface	Stability	Versioning
Thứ tự đăng ký component	stable	Library semver (@nx/search)
SearchableControllerMixin(Base, options)	stable	Library semver
ISearchParams / ISearchResponse	stable	Library types
GET /search/{collectionName} (controller generic)	stable	Host URL /v1/
Tên CDC topic (nx.seller.{schema}.{table})	ghép với config Debezium connector	Do connector sở hữu
Schema Typesense collection	tiến hóa (additive qua script backfill)	Migration thủ công khi phân kỳ

5. Trang liên quan

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