Tham chiếu kỹ thuật

Snapshot JSON Field

Thuộc tính	Giá trị
Field type	`snapshot`
DB column type	`JSON`
targetField	Field relation để chụp giá trị
appends	Mảng association names cần eager load
Trigger	`afterCreateWithAssociations`

Cột JSON lưu toàn bộ dữ liệu target record đã serialize, bao gồm cả appends.

SnapshotField — afterCreateWithAssociations

Hook chụp snapshot chạy sau khi bản ghi và tất cả association đã được tạo:

Bản ghi mới INSERT + associations
  → afterCreateWithAssociations trigger
  → Tìm tất cả snapshot fields trong collection
  → Với mỗi snapshot field:
    → Đọc targetField (relation) → lấy target record ID
    → Query target record + eager load appends
    → Serialize toàn bộ thành JSON object
    → UPDATE bản ghi SET snapshotField = JSON

Chi tiết quá trình chụp

targetField = 'product', appends = ['category', 'images']

→ record.productId = 5
→ SELECT * FROM products WHERE id = 5
   INCLUDE category, images
→ result = {
    id: 5,
    name: "iPhone 15",
    price: 25000000,
    category: { id: 1, name: "Điện thoại" },
    images: [{ url: "img1.jpg" }, { url: "img2.jpg" }]
  }
→ Lưu JSON vào cột snapshot

collectionsHistory / fieldsHistory — Schema Evolution

Hai collection phụ trợ theo dõi lịch sử thay đổi schema:

collectionsHistory

Cột	Kiểu	Mô tả
`name`	STRING	Tên collection
`schema`	JSON	Schema tại thời điểm ghi
`createdAt`	DATE	Thời điểm ghi lịch sử

fieldsHistory

Cột	Kiểu	Mô tả
`collectionName`	STRING	Tên collection chứa field
`name`	STRING	Tên field
`schema`	JSON	Schema field tại thời điểm ghi
`createdAt`	DATE	Thời điểm ghi lịch sử

Tại sao cần schema history?

Khi xem snapshot cũ, collection gốc có thể đã thay đổi (thêm/xóa field, đổi tên). Schema history giúp client render snapshot đúng cấu trúc tại thời điểm chụp — không bị ảnh hưởng bởi schema hiện tại.

Server Hooks

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

ACL

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

Client — SnapshotFieldProvider

Provider cung cấp context cho snapshot rendering:

SnapshotFieldProvider
  → Đọc snapshot JSON value từ record
  → Fetch schema history (collectionsHistory, fieldsHistory)
  → Dựng schema component tree từ historical schema
  → Render snapshot data dạng read-only fields

Snapshot Block Initializers

Plugin cung cấp block initializers cho phép kéo thả snapshot block vào detail/form page:

Block hiển thị snapshot data giống một "mini detail" của target record.
Sử dụng schema từ fieldsHistory để render đúng field types.

Sơ đồ tổng quan

┌────────────┐  targetField  ┌──────────────┐   serialize   ┌──────────┐
│ New Record │ ────────────→ │ Target Record│ ────────────→ │ Snapshot │
│ (order)    │               │ + appends    │               │ (JSON)   │
└────────────┘               └──────────────┘               └──────────┘
                                                                  │
                             ┌──────────────┐                     │
                             │ collections/ │ ◄────────── schema history
                             │ fieldsHistory│    (cho rendering)
                             └──────────────┘