Storage
1. Tổng quan
| Thuộc tính | Giá trị |
|---|---|
| Status | Stable |
| Owner | platform |
| Phụ thuộc | BunS3Helper (@venizia/ignis-helpers/bun-s3), APP_ENV_S3_* |
| Controllers | AssetController (/assets), BanksVNController (/assets/banks-vn) |
Object storage chỉ dùng S3/Minio qua một
BunS3Helperduy nhất bind khi component init. Không có backend local-disk (ADR-0001).
2. Model Entity
Các thao tác storage tạo một bản ghi MetaLink cho mỗi object được upload (xem Domain Model). Bản thân các object nằm trong S3, key bằng bucketName + objectName.
3. Vòng đời
| Từ | Sự kiện | Đến | Guards |
|---|---|---|---|
* | upload | Stored | folderPath ≤2 segment, mỗi segment isValidName |
Stored | get/download | streamed | isValidPath(name, maxDepth:2) |
Stored | delete | Removed | isValidPath; bản ghi MetaLink được deleteAll (async) |
Tên object là một
crypto.randomUUID().slice(0,8)mới cho mỗi lần upload —i18n.jsonliteral là tên duy nhất được giữ. Upload không idempotent.
4. Thao tác
| Handler | Mục đích | Inputs | Output |
|---|---|---|---|
AssetController UPLOAD | Lưu file vào S3 + tạo MetaLink | multipart body, query principalType/principalId/variant/folderPath | [{ objectName, link, metaLink }] |
AssetController GET_OBJECT_BY_NAME | Stream object inline | path objectName | binary stream |
AssetController DOWNLOAD_OBJECT_BY_NAME | Stream dạng attachment | path objectName | binary + Content-Disposition |
AssetController GET_I18N / DOWNLOAD_I18N | Stream i18n.json từ APP_ENV_S3_BUCKET | — | binary stream |
AssetController DELETE_OBJECT | Xóa object S3 + MetaLink | path objectName | { success: true } |
AssetController LIST_OBJECTS | List object trong bucket | query prefix/recursive/maxKeys | [{ name, size, lastModified, etag, prefix }] |
BanksVNController GET_BANKS_VN_REGISTRY | JSON registry ngân hàng VN (URL logo được tuyệt-đối-hóa) | — | JSON map (cache 1h) |
BanksVNController GET_BANK_VN_LOGO | Stream một PNG ngân hàng từ đĩa | path filename (^[A-Za-z0-9]+\.png$) | image/png (cache 7d immutable) |
5. REST Endpoints
Schema đầy đủ render trực tiếp từ
/doc/openapi.jsoncủa host. Nguồn:controllers/asset/definition.ts,controllers/banks-vn/definition.ts.
| Verb | Path | Auth | Handler |
|---|---|---|---|
POST | /assets/upload | BASIC / JWT | AssetController UPLOAD |
GET | /assets/objects | BASIC / JWT | LIST_OBJECTS |
GET | /assets/objects/i18n | public | GET_I18N |
GET | /assets/download/i18n | public | DOWNLOAD_I18N |
GET | /assets/objects/{objectName} | public | GET_OBJECT_BY_NAME |
GET | /assets/download/{objectName} | public | DOWNLOAD_OBJECT_BY_NAME |
DELETE | /assets/objects/{objectName} | BASIC / JWT | DELETE_OBJECT |
GET | /assets/banks-vn | public | GET_BANKS_VN_REGISTRY |
GET | /assets/banks-vn/{filename} | public | GET_BANK_VN_LOGO |
Path hiển thị tương đối với asset controller; prefix thực tế là base path của host (vd
/v1/api/commerce/assets/upload).
6. Events
Inbound / Outbound: không có. Storage là REST + S3 đồng bộ (xem API Events).