Tích hợp

1. Sister Services

Sister	Hướng	Bề mặt	Auth	Failure Mode	Idempotency
@nx/sale	←	Kafka PAYMENT_SUCCESS	—	delivery at-least-once; consumer skip những lần đã xử lý qua tracking lookup	(SALE_ORDER, saleOrderId, stockId)
@nx/sale	←	Kafka KITCHEN_TICKET_ITEM_STATUS_CHANGED	—	at-least-once	theo (saleOrderId, kitchenTicketItemId, materialId)
@nx/sale	→	Kafka MATERIAL_STOCK_CHANGED	—	post-commit fire-and-forget	theo id sự kiện stock
@nx/finance	→	Kafka PURCHASE_ORDER_RECEIVED	—	post-commit fire-and-forget; chỉ khi payments[] không rỗng	(POREC, purchaseOrderId) phía consumer
@nx/commerce	←	HTTP — gọi trực tiếp InventoryService.createInventoryForProductVariant / updateInventoryForProductVariant (trong TX dùng chung)	JWT (service-to-service)	rollback TX khi lỗi	ensureInventoryItem
@nx/commerce (CDC)	←	Kafka CDC nx.seller.public.product_variant (Debezium)	—	at-least-once	ensureInventoryItem là idempotent
@nx/identity (CDC)	←	Kafka CDC nx.seller.public.merchant (Debezium)	—	at-least-once	ensureDefaultLocation idempotent
@nx/identity	→	HTTP — JWT verify qua JWKS (/jw-certs)	JWT	retry / circuit-break (gateway)	request-id propagate
@nx/identity	→	HTTP — lookup permission PolicyDefinitionService	JWT	fallback Redis cache	theo (role, action)
@nx/signal	→	WebSocket emission qua ApplicationWebSocketComponent	—	best-effort delivery	none (broadcast)

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

N/A — inventory không gọi trực tiếp bất kỳ API ngoài (third-party) nào. Tất cả tích hợp third-party (vd e-invoice, payment) thuộc các package khác.

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

3.1 Sale Payment → Trừ Stock (quan trọng nhất)

Hợp đồng:

• Sale đảm bảo PAYMENT_SUCCESS được phát đúng một lần cho mỗi chuyển trạng thái (post-commit).
• Inventory đảm bảo xử lý idempotent theo (saleOrderId, stockId).
• Reservation của material chạy sau khi trừ product trong cùng một handler call (tuần tự, không song song).

3.2 PO Receive → Ghi nhận Expense bên Finance

Hợp đồng:

• Stock + tracking + snapshot vendor là atomic (một TX duy nhất).
• Kafka emit xảy ra SAU commit — nếu emit lỗi, finance được thông báo qua reconciliation job (TBD), không rollback in-band.
• Finance coi PURCHASE_ORDER_RECEIVED là quyền lực: idempotent trên (POREC, purchaseOrderId).

3.3 Onboarding Merchant → Seed Default Location

Hợp đồng: idempotent. Re-delivery là no-op.

3.4 ProductVariant Create → Seed Inventory

Hai đường song song:

Đường A — HTTP trực tiếp (đồng bộ, trong TX của commerce):

Đường B — CDC (bất đồng bộ, hồi tố):

Cả hai đường hội tụ về cùng upsert idempotent ensureInventoryItem.

4. Tính ổn định Hợp đồng

Bề mặt	Tính ổn định	Versioning
HTTP /v1/api/inventory/*	stable	tiền tố URL /v1/
Kafka topic payment.success	stable	payload chỉ thêm field
Kafka topic purchase-order.received	stable	payload chỉ thêm field
Kafka topic material.stock-changed	beta	có thể thêm field
Kafka topic material.transferred	beta	—
CDC topic (nx.seller.public.*)	stable	điều khiển bởi config Debezium
WebSocket topic observation/inventory/inventory-stock	stable	đường room có version

5. Trang liên quan

• API Sự kiện
• Chi tiết luồng Sale ↔ Inventory
• Quyết định