Giao diện
@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) |