@digiforce-nc/plugin-action-import

Plugin cung cấp nhập dữ liệu từ file Excel (XLSX) - upload file Excel, validate, parse dữ liệu và tạo/cập nhật bản ghi trong collection, kèm template mẫu tải về.

Plugin này làm gì?

Hãy hình dung bạn nhận file Excel danh sách 500 khách hàng từ đối tác và cần nhập vào hệ thống. Plugin cung cấp quy trình hoàn chỉnh: tải template mẫu → điền dữ liệu → upload → validate → insert/update. Server xử lý file qua multer middleware, parse bằng exceljs rồi tạo/cập nhật bản ghi. Client cung cấp modal import nhiều bước.

Ba nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Template mẫu	Handler `downloadXlsxTemplate` tạo file Excel mẫu theo cấu hình field của collection
2	Import dữ liệu	Handler `importXlsx` nhận file upload (multipart), parse, validate rồi insert/update
3	Error handling	Custom error classes `ImportValidationError`, `ImportError` báo cáo chi tiết dòng lỗi

Kiến trúc

Tổng quan

Plugin có cả server (handlers, multer middleware) và client (modal import, designer). Khi install, tự động thêm quyền importXlsx vào admin role strategy.

Tầng	Vai trò	Thành phần
Client UI	Modal import + designer cấu hình	`ImportModal`, `ImportDesigner`
Upload Middleware	Xử lý multipart file upload	`@koa/multer`
Import Handler	Parse Excel, validate, insert/update	`importXlsx` handler
Template Handler	Tạo file template mẫu	`downloadXlsxTemplate` handler
Error Handler	Báo cáo lỗi chi tiết	`ImportValidationError`, `ImportError`

API endpoints

Endpoint	Method	Mô tả
`{collection}:importXlsx`	POST	Nhập dữ liệu từ file Excel (multipart/form-data)
`{collection}:downloadXlsxTemplate`	POST	Tải file Excel mẫu theo cấu hình field

importXlsx - Request parameters

Tham số	Kiểu	Mô tả
`file`	File	File Excel (.xlsx) upload qua multipart
`columns`	JSON	Mapping cột Excel sang field collection
`explain`	boolean	Chế độ dry-run: chỉ validate, không insert

ACL - Phân quyền

Quyền	Mô tả
`importXlsx`	Quyền riêng biệt cho import, thêm vào admin role khi install
`downloadXlsxTemplate`	Cho phép tất cả user đã đăng nhập tải template

Luồng hoạt động

Error handling

Plugin định nghĩa hai custom error class:

Error class	Khi nào	Nội dung
`ImportValidationError`	Dữ liệu không hợp lệ (type, required, unique)	Danh sách dòng + lý do lỗi
`ImportError`	Lỗi hệ thống (DB, parse)	Mô tả lỗi kỹ thuật

Chế độ dry-run

Khi gửi explain: true, handler chỉ validate mà không insert/update - hữu ích để kiểm tra dữ liệu trước khi import thật.

Thành phần client

Thành phần	Mô tả
`ImportPluginProvider`	Provider đăng ký toàn bộ component vào plugin system
`ImportModal`	Modal nhiều bước: tải template → upload → mapping → kết quả
`ImportDesigner`	Cấu hình import action trong designer mode
`ImportActionInitializer`	Đăng ký nút Import vào toolbar bảng
`ImportActionWidget`	Widget nút action trong uiCore

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)
`exceljs`	Parse và tạo file Excel (dev)
`xlsx`	Parser XLSX bổ trợ (dev)
`@koa/multer`	Middleware xử lý file upload (dev)
`async-mutex`	Serialize import requests (dev)