@digiforce-nc/plugin-audit-logs

Plugin ghi lại nhật ký thao tác (audit trail) cho mọi hoạt động CRUD trong hệ thống — ai đã làm gì, khi nào, trên dữ liệu nào, giá trị cũ/mới.

Plugin này làm gì?

Mỗi khi người dùng tạo, sửa hoặc xóa bản ghi, plugin tự động ghi lại một audit log entry bao gồm: người thực hiện, thời gian, collection, action, và diff dữ liệu (before/after).

Ba nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Ghi nhận tự động	Gắn DB hooks (afterCreate/afterUpdate/afterDestroy) lên tất cả collection
2	Lưu trữ diff	Tính toán giá trị cũ/mới cho từng field thay đổi, lưu vào `auditChanges`
3	Giao diện tra cứu	Block audit logs trên page/popup, bộ lọc theo user/collection/action/thời gian

Kiến trúc

Luồng ghi audit log

API endpoints

Endpoint	Phương thức	Mô tả
`auditLogs:list`	GET	Danh sách audit log, hỗ trợ filter/sort/paginate
`auditLogs:get`	GET	Chi tiết một audit log entry
`auditChanges:list`	GET	Danh sách thay đổi field trong một audit log

Database - 2 bảng chính

Bảng	Chứa gì	Ví dụ
`auditLogs`	Entry chính: ai, làm gì, trên collection nào	`{ userId: 1, collectionName: 'posts', action: 'update' }`
`auditChanges`	Chi tiết thay đổi từng field	`{ field: 'title', before: 'Draft', after: 'Published' }`

Vòng đời plugin

DB Hooks - cơ chế ghi nhận

Hook	Khi nào	Ghi nhận gì
`afterCreate`	Sau khi tạo bản ghi	action = `create`, before = null, after = giá trị mới
`afterUpdate`	Sau khi cập nhật	action = `update`, before = giá trị cũ, after = giá trị mới
`afterDestroy`	Sau khi xóa	action = `destroy`, before = giá trị cũ, after = null

Ví dụ sử dụng API

Truy vấn audit logs

typescript

const response = await agent.resource('auditLogs').list({
  filter: { collectionName: 'posts' },
  sort: ['-createdAt'],
  pageSize: 20,
});
const { data } = response.body;

Xem chi tiết thay đổi

typescript

const response = await agent.resource('auditChanges').list({
  filter: { auditLogId: 100 },
});
// [{ field: 'title', before: 'Draft', after: 'Published' }]

Lọc theo user và khoảng thời gian

typescript

const response = await agent.resource('auditLogs').list({
  filter: {
    userId: 5,
    createdAt: { $gte: '2024-01-01', $lte: '2024-12-31' },
  },
});

Thành phần client

Thành phần	Mô tả
`AuditLogsProvider`	Context provider cung cấp dữ liệu audit cho UI
`AuditLogsBlockInitializer`	Block initializer thêm audit logs block vào page/popup
`AuditLogsTable`	Bảng hiển thị danh sách audit log với filter, sort, paginate
`AuditLogDetail`	Chi tiết entry: diff before/after dạng visual

Dependencies

Package	Vai trò
`@digiforce-nc/server`	Server framework — gắn hooks vào DB
`@digiforce-nc/database`	Database ORM — collection definitions, hooks API
`@digiforce-nc/client`	Client framework — đăng ký UI components
`@digiforce-nc/actions`	Action context — lấy thông tin user, collection từ request