Architecture
@nx/assetkhông ship runtime riêng. Mọi sơ đồ dưới đây mô tả các asset component khi được mount bên trong một ứng dụng host (commerce, finance, hoặc ledger).
1. System Context (C4 L1)
2. Container View (C4 L2)
3. Component View (C4 L3) — Phân lớp nội bộ
| Layer | Trách nhiệm |
|---|---|
| Routes | Bề mặt HTTP, khai báo trong StaticAssetRoutes / BanksVNRoutes / CRUD factory |
| Controllers | Validate path, cổng auth, định hình header, response stream/JSON |
BunS3Helper | Object put/get/stat/remove/list trên S3/Minio (bind dưới APPLICATION_S3_STORAGE_HELPER) |
MetaLinkRepository | CRUD Drizzle trên public.MetaLink |
| Components | Nối helper + controller vào host khi binding() |
4. Chỉ mục State Machine
| Entity | Trạng thái | Sơ đồ |
|---|---|---|
| — | N/A — MetaLink không có trường status / vòng đời | — |
N/A — các entity của asset là bản ghi phẳng. Bản ghi
MetaLinkđược tạo khi upload và hard-delete khi xóa object; không có state machine.
5. Kịch bản Runtime
5.1 Upload object + ghi MetaLink
| Bước | Chi tiết |
|---|---|
| 2 | folderPath được chuẩn hóa + mỗi segment kiểm tra bằng helper.isValidName; độ sâu tối đa 2 |
| 3 | Tên object = crypto.randomUUID().slice(0,8); i18n.json giữ nguyên tên literal |
| 6 | Lỗi MetaLink không làm fail upload — lỗi được bắt vào metaLinkError cho từng file |
5.2 Stream / download object
| Bước | Chi tiết |
|---|---|
| 1 | /objects/... stream inline; /download/... thêm Content-Disposition: attachment |
| 2 | Path không hợp lệ → 400; object thiếu hiện ra dưới dạng lỗi helper |
| — | GET /objects/i18n + GET /download/i18n stream bundle i18n.json từ APP_ENV_S3_BUCKET |
5.3 Phục vụ registry ngân hàng VN + logo
6. Mối quan tâm xuyên suốt
| Mối quan tâm | Cách asset xử lý |
|---|---|
| AuthN | Kế thừa từ host (JWT/Basic). Các route asset ghi + /meta-links yêu cầu BASIC hoặc JWT; route đọc/download + banks-vn là public |
| AuthZ | AssetPermissions = quyền CRUD MetaLink có tồn tại, nhưng MetaLinkController hiện đặt authorize: { skip: true } trên mọi route |
| i18n | Phục vụ bundle bản dịch i18n.json từ S3; nhãn ngân hàng VN là JSON tĩnh |
| Logging | Key-value có cấu trúc qua this.logger.for(...); lỗi MetaLink khi upload/delete được log, không throw |
| An toàn path | isValidPath/isValidName (độ sâu ≤2); regex logo ngân hàng ^[A-Za-z0-9]+\.png$; x-content-type-options: nosniff trên stream |
| Idempotency | Không — upload sinh tên UUID mới mỗi lần gọi |
| Soft-delete | N/A — xóa object hard-remove object S3 và deleteAll các bản ghi MetaLink khớp |
| IDs | IdGenerator của host (asset không phát sinh) |