Kiến trúc

1. Bối cảnh hệ thống (C4 L1)

Commerce không push trực tiếp tới các dịch vụ chị em. Seam tích hợp là CDC (Debezium đọc Postgres WAL). Xem ADR-0002.

2. Góc nhìn Container (C4 L2)

3. Góc nhìn Component (C4 L3) — Phân lớp nội bộ

Lớp	Trách nhiệm
Routes	Base path trong RestPaths
Controllers	Cổng auth (jwt/basic), lọc theo vai trò, ánh xạ DTO
Services	Transaction aggregate, phát EventBus, mã hóa
Repositories	Truy vấn Drizzle, soft-delete
Components	Kafka producer, hàng đợi/worker BullMQ, EventBus, WebSocket, search/asset, hai Redis

4. Chỉ mục Máy trạng thái

Thực thể	Trạng thái	Sơ đồ
Product	DRAFT, ACTIVATED, DEACTIVATED, ARCHIVED	→
ProductVariant	DRAFT, ACTIVATED, DEACTIVATED, ARCHIVED	→
Merchant onboarding	cờ boolean theo từng bước	→

Trạng thái Product / ProductVariant

ARCHIVED là trạng thái cuối. Statuses được tái sử dụng từ @venizia/ignis (ProductStatuses / ProductVariantStatuses). Giá trị DRAFT cũng tồn tại trong enum.

ProductVariant.type (bộ phân biệt cấu trúc)

Không phải vòng đời — đây là type điều khiển hành vi tồn kho & gói. Nguồn: core/.../product-variant/constants.ts.

Type	Lưu kho	BOM	Ghi chú
STORABLE	✓	—	vật lý, có tồn kho (mặc định)
CONSUMABLE	—	—	vật lý, không lưu kho
SERVICE	—	—	không có hàng hóa vật lý
KIT	—	✓	nổ tung khi bán qua Material
COMBO	—	✓	ảo; nổ tung khi bán qua ProductVariant thành phần
MANUFACTURED	✓	✓	sản xuất để lưu kho

Xem ADR-0003.

Các bước onboarding Merchant

Cờ MerchantOnboardingSteps nằm trong Merchant.metadata.onboarding. ProductAggregateCreatedListener.handleMarkOnboardingStepComplete đánh dấu bước PRODUCT khi tạo product đầu tiên.

5. Kịch bản Runtime

5.1 Tạo Product Aggregate + Đồng bộ đa Merchant

Transaction aggregate commit trước khi phát EventBus — đồng bộ là best-effort/async. Xem ADR-0001.

5.2 Onboarding Organizer (đồng bộ)

Không có hàng đợi fan-out COMMERCE_INITIALIZED_* — thiết lập downstream được điều khiển bởi CDC.

5.3 Thông tin thuế Merchant → TaxInfo (CDC)

MST/hóa đơn điện tử được lưu trong Merchant.metadata.tax (không phải cột). TaxInfo là nguồn đọc downstream có thẩm quyền. Xem luồng thông tin thuế merchant.

5.4 Tích hợp Provider được mã hóa

6. Mối quan tâm xuyên suốt

Mối quan tâm	Dịch vụ này xử lý như thế nào
AuthN	JWT (ES256, JWKS từ identity); BASIC cho service-to-service. VerifierApplication.
AuthZ	Lọc theo vai trò qua useRequestContext() + AppFixedRoles; quy tắc Casbin GROUP của PolicyDefinition được cache trong authorization Redis
i18n	jsonb { en, vi } qua cột i18n()
Logging	IGNIS có cấu trúc (key: %s)
Mã hóa	EncryptService AES-256-GCM với APP_ENV_APPLICATION_SECRET; getDecryptedCredential chỉ nội bộ
Seam tích hợp	CDC (Debezium WAL) — Kafka chỉ producer, không produce cấp ứng dụng
Sao chép async	EventBus in-process → BullMQ SYNC_PRODUCT_QUEUE → worker
Soft-delete	SoftDeletableRepository (deletedAt) trên tất cả thực thể
IDs	Snowflake qua IdGenerator, worker 2; slug tự sinh nếu vắng
Chế độ kép	ApplicationRoles.API / WORKER; CDC consumer + workers chỉ ở vai trò WORKER

7. Trang liên quan

• Domain Model
• API Events
• Tích hợp
• Quyết định