Tích hợp
1. Sister Services
| Sister | Hướng | Bề mặt | Auth | Chế độ thất bại | Idempotency |
|---|---|---|---|---|---|
Tất cả VerifierApplication (sale, inventory, commerce, finance, payment, signal, v.v.) | → (sister pulls) | HTTP GET /jw-certs | không (JWKS công khai) | retry; cache JWKS trước đó cho đến khi có thể truy cập | nhận biết xoay JWKS qua kid |
| Tất cả sisters | → (sister calls) | HTTP — endpoint lookup PolicyDefinitionService | JWT | sister cache trong Redis | theo (role, action, subject) |
@nx/sale (truy vấn Customer) | → (sale reads) | HTTP — CustomerController CRUD qua repository xuyên-package | JWT hoặc BASIC | retry | giới hạn theo merchant |
@nx/signal | → | Phát WebSocket qua ApplicationWebSocketComponent | — | best-effort | broadcast |
Identity không gọi trực tiếp tới sister service. Mô hình JWKS pull-based là nền tảng tin cậy.
2. Hệ thống ngoài
| Hệ thống | Hướng | Bề mặt | Auth | Chế độ thất bại |
|---|---|---|---|---|
| SMTP (Gmail / SMTP của merchant) | → | NodemailerComponent | SMTP credential từ env | retry qua queue executor nội bộ |
| VN Pay SMS | → | MQSMSComponent | cấu hình provider từ bảng Configuration | cấu hình theo merchant; queue retry |
| Redis | ↔ | Trạng thái OTP, BullMQ (queue mail/SMS), auth cache | mật khẩu từ env | service vẫn khởi động khi không có (auth cache tắt); OTP yêu cầu Redis |
3. Flow xuyên-service quan trọng
3.1 Boot sister — bootstrap JWKS
Sister cache vô thời hạn; chỉ refresh khi JWT mang
kidchưa biết.
3.2 Flow request đã xác thực (phía sister)
3.3 Permission check (xuyên-service)
Trong setup BANA hiện tại, bảng
PolicyDefinitionđược dùng chung (một DB), nên các sister thường đọc trực tiếp quaPolicyDefinitionRepositorythay vì gọi HTTP đến identity. Identity sở hữu đường ghi cho thay đổi policy.
3.4 Đăng ký → gán role mặc định
4. Tính ổn định của Hợp đồng
| Bề mặt | Ổn định | Versioning |
|---|---|---|
GET /jw-certs | ổn định | định dạng JWKS RFC 7517 |
Payload JWT { userId, roles, organizers, merchants } | ổn định | chỉ thêm trường |
HTTP /v1/api/identity/* | ổn định | tiền tố URL /v1/ |
Bảng Configuration (mail/SMS/OTP) | ổn định | thêm mới (code mới) |
Bảng PolicyDefinition | ổn định | thêm mới |
5. Vấn đề xuyên suốt
| Vấn đề | Cách xử lý |
|---|---|
| Trust | Mọi sister service tin issuer /jw-certs; xoay key xử lý qua kid |
| Single key vs per-merchant | Hiện một signing key duy nhất; multi-tenant key isolation ngoài scope (xem purpose & scope) |
| Service-to-service | Hỗ trợ chiến lược auth BASIC cho gọi xuyên-package |
| Snapshot fields | Roles/orgs/merchants trong payload JWT là snapshot tại thời điểm phát — client nên refresh khi thay đổi quyền |