Cài đặt và sử dụng — Record History

Tổng quan

@digiforce-nc/plugin-record-history tự động ghi lại lịch sử thay đổi bản ghi thông qua DB hooks (afterCreate, afterUpdate, afterDestroy). Plugin sử dụng Event Queue để xử lý bất đồng bộ, không ảnh hưởng đến response time của API.

Bước 1: Kích hoạt Plugin

Vào Settings → Plugin Manager, tìm plugin-record-history và bật.

Khi cài đặt, plugin tự động tạo các bảng lịch sử và đăng ký chúng vào Collection Manager.

Bước 2: Cấu hình Collection cần tracking

Vào trang cấu hình Record History và chọn Collection và Field cần theo dõi:

Cấu hình	Mô tả
`recordHistoryCollections`	Chọn Collection cần tracking (dataSourceKey + collectionName)
`recordHistoryFields`	Chọn Field cần theo dõi trong mỗi Collection

Lưu ý: Plugin chỉ ghi lịch sử cho các Collection và Field đã cấu hình. Mặc định không tracking Collection nào — bạn phải bật thủ công.

Bước 3: Xem lịch sử

Mở trang chi tiết bản ghi → tab History để xem timeline thay đổi:

Thông tin	Mô tả
Thời gian	Khi nào thay đổi (createdAt)
Người thay đổi	User thực hiện (userId → users)
Hành động	create / update / destroy
Chi tiết field	Tên field, giá trị trước (before), giá trị sau (after)

Cách hoạt động chi tiết

Luồng xử lý

Snapshot-based diff

Plugin không so sánh trực tiếp old/new value trong hook. Thay vào đó:

Tạo snapshot: Khi có thay đổi, chụp giá trị hiện tại của mỗi field được tracking
Lưu snapshot: Upsert vào recordFieldSnapshots (1 snapshot per field per record)
Diff: Khi snapshot được lưu (afterSave), so sánh model.get('value') với model.previous('value')
Ghi history: Nếu giá trị khác nhau, tạo bản ghi trong recordFieldHistories và recordHistories

Transaction-aware

Plugin chờ transaction commit trước khi tạo snapshot (transaction.afterCommit). Điều này đảm bảo:

Snapshot chỉ tạo khi dữ liệu thực sự được lưu
Nếu transaction rollback, không có snapshot rác

Relation fields

Với relation fields (belongsTo, hasMany, belongsToMany...), plugin:

Lấy giá trị target key (VD: ID) thay vì toàn bộ object
Ghi nhận titleFieldOptions từ target Collection để hiển thị đẹp
Hỗ trợ cả single relation và array relation

Các action được tracking

Action	DB Hook	Mô tả
`create`	`afterCreate`, `afterBulkCreate`	Tạo bản ghi mới
`update`	`afterUpdate`, `afterBulkUpdate`	Cập nhật bản ghi
`destroy`	`afterDestroy`, `afterBulkDestroy`	Xóa bản ghi

History DB riêng biệt

Plugin tạo Database connection riêng (historyDB) dùng cùng database config nhưng có logging và context riêng. Điều này:

Tách biệt transaction giữa data chính và history
Tránh deadlock khi ghi history trong hook
Cho phép history tables có migration riêng

Lưu ý quan trọng

Bảng recordFieldSnapshots chứa snapshot mới nhất của mỗi field — không phải lịch sử đầy đủ
Bảng recordFieldHistories chứa diff log — giá trị trước và sau mỗi thay đổi
Lịch sử chỉ ghi từ khi bật tracking — không retroactive cho dữ liệu cũ
Bảng history có thể lớn nhanh — cân nhắc retention policy hoặc cleanup định kỳ
Nên chỉ tracking Collection và field quan trọng, không bật cho tất cả
Bulk operations tạo nhiều history entries — mỗi record trong batch là một entry riêng