Integration

1. Service anh em

Direction: → gọi / ← được gọi / ↔ hai chiều.

Anh em	Hướng	Bề mặt	Hợp đồng	Auth	Failure Mode
@nx/identity	→	HTTP JWKS (/jw-certs)	JWKSVerifierTokenService	—	token bị từ chối nếu fetch JWKS thất bại
@nx/sale / @nx/payment	←	Kafka signal.activity-notification	TActivityNotificationMessage	—	at-least-once; không retry khi handler lỗi
@nx/sale / @nx/payment	←	Redis pub/sub (WebSocketEmitter)	{ topic, data, destination }	—	best-effort; bỏ nếu không instance nào subscribe
@nx/core	→	repository in-process	ActivityNotificationRepository, PolicyDefinitionRepository	—	lỗi DB lan truyền, message không commit

Producer (@nx/sale, @nx/payment) không host một WebSocket server. Họ publish qua một WebSocketEmitter nhẹ; Signal là service duy nhất sở hữu một WebSocketServerHelper và subscribe bus.

2. Hệ thống ngoài

Hệ thống	Hướng	Bề mặt	Auth	Failure Mode
WebSocket client (POS / Admin / Tauri)	↔	WSS /stream (ECDH + AES-256-GCM)	JWT trong handshake	từ chối nếu thiếu JWT hợp lệ + clientPublicKey
Redis	↔	pub/sub (single hoặc cluster)	password (tuỳ chọn)	offline queue (cluster) / retry (single)
Kafka	←	consumer (SASL tuỳ chọn)	SCRAM/PLAIN	broker reconnect; thiếu brokers → fail-fast lúc boot

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

3.1 Thanh toán thành công → notification cho user

Bước	Chi tiết
1	Producer chọn recipientScope; org/merchant giải phía server qua PolicyDefinitionRepository, users dùng recipientIds
4	Cùng hàng cũng lấy được qua GET /notifications; WS push là gợi ý live, không phải nguồn sự thật

3.2 Push trực tiếp xuyên instance / xuyên service

4. Độ ổn định hợp đồng

Bề mặt	Độ ổn định	Versioning
WS /stream handshake (type, token, clientPublicKey)	ổn định	không — một protocol
Payload Kafka signal.activity-notification	beta	hình dạng TActivityNotificationMessage; chưa trường version
WS topic observation/signal/notification/created	beta	theo path
REST /notifications, /socket/websocket/clients	ổn định	URL /v1/

5. Trang liên quan

• API Events
• Architecture
• Decisions