MetaLinks

1. Tổng quan

Thuộc tính	Giá trị
Status	Stable
Owner	platform
Phụ thuộc	model MetaLink từ @nx/core, PostgresCoreDataSource
Controller	MetaLinkController (/meta-links)
Repository	MetaLinkRepository (DefaultCRUDRepository mỏng)

Một MetaLink là bản ghi DB mô tả một object S3 đã lưu và (tùy chọn) entity nghiệp vụ mà nó thuộc về. Model nằm trong @nx/core để commerce/ledger có thể tham chiếu mà không gây dependency vòng (ADR-0002).

2. Model Entity

Xem Domain Model cho bảng trường đầy đủ và index.

Trường	Kiểu	Bắt buộc	Mô tả
bucketName / objectName	text	✓	Định danh object S3 đã lưu
link	text	✓	Path truy cập tương đối /assets/objects/{name}
mimetype / size / etag	—	hỗn hợp	Từ S3 stat
variant	text		Tag vai trò do caller cung cấp
storageType	text	✓	Hiện luôn là s3
isSynced	boolean	✓	true khi đang phản chiếu object
principalType / principalId	text		Owner đa hình (không có DB FK)

Principal types (MetaLinkPrincipalTypes): Product, ProductVariant, Organizer, Ledger, Category.

3. Vòng đời

Từ	Sự kiện	Đến	Guards
*	upload	Created	tạo trong cùng handler với S3 put; lỗi bắt vào metaLinkError, không throw
Created	updateById	Updated	body MetaLinkUpdateSchema
Created	xóa object	Deleted	deleteAll({ bucketName, objectName }) (hard delete, không có cột soft-delete)

4. Thao tác

Handler	Mục đích	Inputs	Output
MetaLinkRepository.create	Insert một MetaLink (dùng bởi upload)	data MetaLinkInsertSchema	{ data: MetaLink }
MetaLinkRepository.deleteAll	Xóa bản ghi theo { bucketName, objectName }	filter	count
MetaLinkController (CRUD factory)	find/findById/findOne/count/create/updateById/deleteById/deleteBy tiêu chuẩn	schema theo route	theo route

MetaLinkRepository không thêm method tùy chỉnh nào — nó là DefaultCRUDRepository<TMetaLinkSchema, TMetaLink>.

5. REST Endpoints

MetaLinkController là ControllerFactory.defineCrudController(). Schema đầy đủ render trực tiếp từ /doc/openapi.json của host. Nguồn: controllers/meta-link/meta-link.controller.ts.

Verb	Path	Auth	Authorize
GET	/meta-links	JWT / BASIC	skipped
GET	/meta-links/{id}	JWT / BASIC	skipped
GET	/meta-links/count	JWT / BASIC	skipped
GET	/meta-links/find-one	JWT / BASIC	skipped
POST	/meta-links	JWT / BASIC	skipped (MetaLinkInsertSchema)
PATCH	/meta-links/{id}	JWT / BASIC	skipped (MetaLinkUpdateSchema)
DELETE	/meta-links/{id}	JWT / BASIC	skipped
DELETE	/meta-links (theo filter)	JWT / BASIC	skipped

AssetPermissions (= quyền CRUD MetaLink từ crudPermissions) được khai báo nhưng không được thực thi — mọi route đặt authorize: { skip: true } hiện tại.

6. Events

Inbound / Outbound: không có (xem API Events).

7. Trang liên quan

• Domain Model
• Storage
• API Events
• ADR-0002 — MetaLink polymorphic principal