@digiforce-nc/plugin-snapshot-field

Plugin cung cấp kiểu field snapshot — chụp lại giá trị record tại thời điểm tạo, lưu dạng JSON bất biến, kết hợp theo dõi lịch sử schema qua collectionsHistory và fieldsHistory.

Plugin này làm gì?

Hãy hình dung: khi tạo đơn hàng, bạn muốn "chụp" thông tin sản phẩm (giá, tên, mô tả) tại thời điểm đặt hàng — dù sau đó sản phẩm thay đổi, đơn hàng vẫn giữ dữ liệu cũ. Plugin này tự động snapshot giá trị từ bản ghi liên kết (qua targetField) cùng các field bổ sung (appends), lưu thành JSON bất biến.

Bốn nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Snapshot on create	Tự động chụp giá trị record liên kết khi tạo bản ghi mới
2	Schema history	Lưu lịch sử collection/field schema để hiển thị snapshot đúng cấu trúc
3	Immutable data	Giá trị snapshot lưu dạng JSON, không thay đổi theo dữ liệu gốc
4	Block initializers	Cung cấp block để hiển thị snapshot data trong giao diện

Kiến trúc

Tổng quan

Plugin có cả server (field type, hooks, history collections) và client (provider, block initializers, interface). Server chụp giá trị và quản lý lịch sử schema; client hiển thị dữ liệu snapshot.

Luồng snapshot khi tạo bản ghi

Field type `snapshot`

Thuộc tính	Giá trị
DB column type	JSON
targetField	Field liên kết (relation) để chụp giá trị từ đó
appends	Danh sách association cần eager load khi chụp
Trigger	`afterCreateWithAssociations` — chụp sau khi tạo bản ghi + association

Database collections phụ trợ

Collection	Mô tả
`collectionsHistory`	Lưu snapshot schema của collection tại thời điểm tạo/sửa
`fieldsHistory`	Lưu snapshot schema của field tại thời điểm tạo/sửa

Hai collection này giúp hệ thống biết cấu trúc data tại thời điểm snapshot được chụp — cần thiết khi collection gốc đã thay đổi schema (thêm/xóa field) nhưng snapshot vẫn cần hiển thị đúng.

Hooks

Hook	Sự kiện	Hành động
`afterCreateWithAssociations`	Tạo bản ghi mới	Chụp snapshot từ targetField + appends
`collections.afterCreate`	Tạo/sửa collection	Ghi vào collectionsHistory
`fields.afterCreate`	Tạo/sửa field	Ghi vào fieldsHistory

ACL

Permission	Mô tả
`collectionsHistory:list`	Cho phép đọc lịch sử schema (cần cho client render snapshot)

Ví dụ sử dụng

Cấu hình field snapshot

typescript

const productSnapshotField = {
  name: 'productSnapshot',
  type: 'snapshot',
  interface: 'snapshot',
  targetField: 'product',
  appends: ['category', 'images'],
};

Đọc snapshot data

typescript

const order = await repository.findOne({
  filterByTk: 1,
  fields: ['productSnapshot'],
});
// order.productSnapshot.price = 15000000 (giá tại thời điểm đặt)
// Dù product hiện tại đã đổi giá → snapshot không thay đổi

Thành phần client

Thành phần	Mô tả
`SnapshotFieldProvider`	Provider cung cấp context cho snapshot rendering
`SnapshotFieldInterface`	Định nghĩa interface cho field snapshot
`Snapshot Block Initializers`	Block để hiển thị dữ liệu snapshot trong detail/form

Dependencies

Package	Vai trò
`@digiforce-nc/server`	Server framework — hooks, collections
`@digiforce-nc/database`	Database ORM — field type + history collections
`@digiforce-nc/client`	Client framework — đăng ký component