Asset

@nx/asset là một package dạng thư viện/component, không phải service độc lập. Các ứng dụng host (commerce, finance, ledger) mount các IGNIS component của nó để có được các endpoint file dựa trên S3/Minio, theo dõi metadata MetaLink, và dữ liệu tham chiếu ngân hàng Việt Nam. Nó không có application class, port, migration, hay DB schema riêng.

1. Tham chiếu nhanh

Thuộc tính	Giá trị
Package	@nx/asset
Loại	Thư viện / IGNIS component package
Runtime	Bun (chạy bên trong một ứng dụng host)
Base Class	N/A — export các lớp con BaseComponent, không phải Application
Vị trí	packages/asset
Base Path	N/A — controller mount dưới base path của host
Dev Port	N/A — không có entry point độc lập
Container Port	N/A — thư viện
Snowflake ID	N/A — không phát sinh ID riêng (dùng IdGenerator của host)
DB Schema	N/A — đọc/ghi public.MetaLink được định nghĩa trong @nx/core
Binding Namespace	@nx/commerce (giá trị của BindingKeys.BASE; xem Configuration)
Owner	platform

2. Mục đích & Phạm vi

Bao gồm	Không bao gồm
Upload / download / stream / delete / list object S3/Minio	Ứng dụng độc lập, port, healthcheck
Bản ghi metadata MetaLink cho object đã lưu	Sở hữu schema MetaLink (nằm trong @nx/core)
Stream bundle bản dịch i18n (i18n.json)	Biến đổi ảnh / tạo thumbnail
Registry ngân hàng Việt Nam + logo PNG	Đường dẫn StaticAssetComponent presigned-URL (đã comment — không hoạt động)

3. Tech Stack

Bên ngoài:

Thư viện	Mục đích
@venizia/ignis	DI, BaseComponent, BaseRestController, ControllerFactory, DefaultCRUDRepository
@venizia/ignis-helpers	BunS3Helper (S3/Minio client đang hoạt động), BaseStorageHelper, helper multipart + content-disposition
hono	HTTP route context (qua IGNIS)
drizzle-orm	Truy cập MetaLink qua PostgresCoreDataSource
@hono/zod-openapi	Schema request/response cho route

Nội bộ:

Package	Mục đích
@nx/core	Model/schema MetaLink, PostgresCoreDataSource, EnvironmentKeys, BindingKeys, crudPermissions

4. Cấu trúc Project

packages/asset/
├── src/
│   ├── index.ts                       # Re-export components + resources (không bootstrap)
│   ├── common/
│   │   ├── keys.ts                    # BindingKeys (binding S3 helper)
│   │   └── rest-paths.ts              # /assets, /meta-links
│   ├── components/
│   │   ├── application-asset.component.ts  # ApplicationAssetComponent
│   │   └── banks-vn.component.ts            # ApplicationAssetBanksVNComponent
│   ├── controllers/
│   │   ├── asset/                     # AssetController (/assets objects + i18n)
│   │   ├── banks-vn/                   # BanksVNController (/assets/banks-vn)
│   │   ├── meta-link/                  # MetaLinkController (/meta-links CRUD)
│   │   └── permissions.ts             # AssetPermissions (= MetaLink CRUD perms)
│   ├── datasources/                   # Re-export PostgresCoreDataSource từ @nx/core
│   ├── repositories/                  # MetaLinkRepository (CRUD mỏng trên core model)
│   ├── resources/                     # banks-vn.json + banks-vn/*.png logos
│   └── utilities/                     # toAbsoluteUrl
├── package.json
└── tsconfig.json

5. Architecture

Chi tiết: xem Architecture.

6. Snapshot Domain

ERD đầy đủ + bảng entity: xem Domain Model.

7. Tổng quan bề mặt

REST controllers (tham chiếu đầy đủ render trực tiếp từ /doc/openapi.json của host; asset không có port riêng):

Controller	Base path	Endpoints	Auth
AssetController	/assets	7	hỗn hợp (đọc public, ghi JWT/Basic)
BanksVNController	/assets/banks-vn	2	public
MetaLinkController	/meta-links	7 (CRUD)	JWT/Basic (hiện bỏ qua authorize)

Async topics (tham chiếu đầy đủ trong API Events):

Hướng	Số lượng
Inbound (Kafka)	0
Outbound (Kafka)	0
WebSocket out	0
BullMQ jobs in	0
BullMQ jobs out	0

N/A — asset không có bề mặt async. Nó là thư viện REST + S3 đồng bộ.

8. Components

Component	File	Mục đích
ApplicationAssetComponent	src/components/application-asset.component.ts	Khởi tạo BunS3Helper, bind nó dưới APPLICATION_S3_STORAGE_HELPER, đăng ký AssetController + MetaLinkController
ApplicationAssetBanksVNComponent	src/components/banks-vn.component.ts	Đăng ký BanksVNController (registry ngân hàng VN + logo)

9. Services

Service	File	Mô tả ngắn
—	—	N/A — không có service layer; logic nằm trực tiếp trong controller + BunS3Helper

10. Repositories

Repository	Bảng	Nguồn	Method tùy chỉnh
MetaLinkRepository	public.MetaLink	model từ @nx/core; DefaultCRUDRepository mỏng	—

11. Entry Points

File	Mục đích
src/index.ts	Re-export components + resources cho host app; không có bootstrapApplication()
src/components/*.component.ts	Hai IGNIS component có thể mount

N/A — không có application.ts, migrate.ts, hay service entry. Mount qua host.component(ApplicationAssetComponent).

12. Configuration

Env vars (APP_ENV_S3_*, APP_ENV_S3_BUCKET, APP_ENV_APPLICATION_EXPLORER_URL) + bindings: xem Configuration.

13. Operations

Deployment (lib — không có pod), observability, security, runbook: xem Operations.

14. Trang liên quan

• Architecture
• Domain Model
• API Events
• Integration
• Configuration
• Operations
• Storage — vòng đời object S3/Minio (feature)
• MetaLinks — model metadata + CRUD (feature)
• Decisions
• REST endpoints — OpenAPI trực tiếp trên service host (vd /v1/api/commerce/doc/openapi.json)