Integration
Ledger không có lệnh gọi HTTP đồng bộ tới service anh em. Mọi dữ liệu xuyên service được đọc trực tiếp qua repository
@nx/core(schema dùng chung, cùng database). Nó phụ thuộc@nx/assetđể lưu file và identity chỉ để xác minh JWT.
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 | Idempotency |
|---|---|---|---|---|---|---|
@nx/identity | → | Xác minh JWKS mỗi request | VerifierApplication | JWKS (ES256) | 401 khi JWT không hợp lệ/hết hạn | — |
@nx/asset | → | MetaLinkService + upload/download S3 | in-process (repo @nx/core + BunS3Helper) | — | lỗi upload → job REJECTED | dọn link mồ côi trước/sau run |
@nx/finance | ← | Đọc DB: FinanceTransactionRepository | schema dùng chung | — | kết quả rỗng → sổ rỗng | chỉ đọc |
@nx/sale | ← | Đọc DB: SaleOrderRepository | schema dùng chung | — | — | chỉ đọc |
@nx/commerce | ← | Đọc DB: MerchantRepository, TaxInfoRepository, VnProvince/VnWard | schema dùng chung | — | thiếu merchant → lỗi validate | chỉ đọc |
Đọc xuyên package chỉ S1a-HKD (dữ liệu thật). S2a–S2e hiện dùng JSON fixture qua
LedgerDataFixtureService(placeholder chờ tích hợp thật).
2. Hệ thống ngoài
| Hệ thống | Hướng | Bề mặt | Auth | Failure Mode |
|---|---|---|---|---|
| Kafka | ↔ | produce + consume ledger.generate | SASL SCRAM-SHA-512 (bật/tắt APP_ENV_KAFKA_SASL_ENABLE) | broker down → enqueue throw → job REJECTED (ENQUEUE_FAILED) |
| S3 / Minio | → | put/get PDF/XLSX mã hoá (BunS3Helper) | access/secret key | lỗi upload → job REJECTED |
| Redis | → | cache auth + WS pubsub | password | WS emit best-effort |
| Typst | in-proc | render PDF NodeCompiler | — | lỗi compile → compiler mới, rồi rethrow |
3. Luồng xuyên service quan trọng
3.1 Lấy dữ liệu S1a-HKD (dữ liệu thật)
| Bước | Chi tiết |
|---|---|
| 1 | Facade LedgerDataFetcherService định tuyến theo loại tới S1aHkdDataFetcherService |
| 5 | Worker validate bằng SCHEMA_MAP['S1a-HKD'].safeParse; parse thất bại → REJECTED |
3.2 Upload file qua @nx/asset
| Bước | Chi tiết |
|---|---|
| 2 | originalName phải là filename phẳng — BunS3Helper.isValidName() từ chối /; path dựng trong normalizeNameFn |
| 4 | Download đảo ngược: getLedgerFromS3Decrypted → decrypt → stream tới client |
4. Độ ổn định hợp đồng
| Bề mặt | Độ ổn định | Versioning |
|---|---|---|
HTTP /v1/api/ledger/* | ổn định | URL /v1/ |
Kafka ledger.generate | ổn định (self-loop nội bộ) | trường payload chỉ thêm |
Bố cục key S3 ledgers/{period}/{merchantId}/{version}/ | ổn định | — |
| Nguồn dữ liệu S2a–S2e | beta — placeholder fixture, fetch thật còn chờ | — |