@digiforce-nc/plugin-action-export

Plugin cung cấp xuất dữ liệu ra file Excel (XLSX) - đăng ký action export trên data source, tạo file XLSX từ dữ liệu collection với mutex đảm bảo không xuất đồng thời.

Plugin này làm gì?

Hãy hình dung bạn cần xuất danh sách khách hàng để gửi cho đối tác. Plugin đăng ký action export trên server - khi nhận request, nó query dữ liệu theo filter hiện tại, dùng XlsxExporter tạo file Excel rồi trả binary stream về client. Mutex đảm bảo chỉ một request export chạy tại một thời điểm, tránh quá tải server.

Ba nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Đăng ký export action	Gắn handler `export` lên mỗi data source khi plugin load
2	Tạo file XLSX	`XlsxExporter` query dữ liệu, format theo cấu hình columns, tạo binary XLSX
3	Mutex & ACL	Mutex toàn cục ngăn export đồng thời; quyền `export` riêng biệt có cấu hình field-level

Kiến trúc

Tổng quan

Plugin có cả server (export handler, XlsxExporter) và client (nút export, designer cấu hình). Khi install, plugin tự động thêm quyền export vào admin role strategy.

Tầng	Vai trò	Thành phần
Client UI	Nút Export + cấu hình field xuất	`ExportActionWidget`, `ExportDesigner`
Server Handler	Nhận request, điều phối export	Export action handler
XlsxExporter	Query dữ liệu, tạo file XLSX	`XlsxExporter` class
Mutex	Ngăn nhiều export chạy cùng lúc	Global `async-mutex`

API endpoints

Endpoint	Method	Mô tả
`{collection}:export`	POST	Xuất dữ liệu collection ra file XLSX (binary response)

Request parameters

Tham số	Kiểu	Mô tả
`columns`	array	Danh sách cột cần xuất (tên field + tiêu đề)
`filter`	object	Bộ lọc dữ liệu (giống list filter)
`sort`	array	Thứ tự sắp xếp
`fields`	string[]	Danh sách field kèm theo
`appends`	string[]	Relation fields cần kèm theo

ACL - Phân quyền

Quyền	Mô tả
`export`	Quyền riêng biệt, `allowConfigureFields: true` cho phép cấu hình field-level
On install	Tự động thêm `export` vào admin role strategy

Luồng hoạt động

XlsxExporter - Chi tiết xử lý

Bước	Mô tả
1. Query	Đọc dữ liệu từ DB theo filter, sort, appends
2. Format	Map dữ liệu theo cấu hình columns (tên cột, format number/date)
3. Relations	Resolve relation fields (belongsTo, hasMany) thành giá trị hiển thị
4. Build XLSX	Sử dụng `xlsx` / `node-xlsx` để tạo file Excel binary
5. Stream	Trả binary stream về client qua HTTP response

Thành phần client

Thành phần	Mô tả
`ExportPluginProvider`	Provider đăng ký toàn bộ component vào plugin system
`ExportActionInitializer`	Đăng ký nút Export vào toolbar bảng
`ExportDesigner`	Cấu hình field xuất trong designer mode
`ExportActionWidget`	Widget nút action kèm loading state và confirm dialog

Dependencies

Package	Vai trò
`@digiforce-nc/actions`	Action context types (peer)
`@digiforce-nc/database`	Database ORM (peer)
`@digiforce-nc/server`	Server framework (peer)
`@digiforce-nc/client`	Client framework (peer)
`xlsx`	Thư viện tạo file Excel (dev)
`node-xlsx`	Parser/builder XLSX (dev)
`async-mutex`	Mutex để serialize export requests (dev)
`file-saver`	Lưu file tại client (dev)