Giao diện
@digiforce-nc/plugin-action-import-pro
Plugin nhập Excel nâng cao (async import) - mở rộng plugin-action-import bằng async job cho file lớn, theo dõi tiến trình real-time và báo cáo lỗi chi tiết.
Plugin này làm gì?
Hãy hình dung bạn import file Excel 100.000 dòng - import đồng bộ sẽ timeout hoặc block cả server. plugin-action-import-pro giải quyết bằng cách chuyển import sang background job. Khi file vượt ngưỡng cấu hình, hệ thống tự động dùng async mode - user theo dõi tiến trình real-time qua task manager UI, nhận thông báo khi hoàn tất kèm báo cáo chi tiết.
Ba nhiệm vụ chính
| # | Nhiệm vụ | Chi tiết |
|---|---|---|
| 1 | Async import | Override handler importXlsx bằng ProImportXlsx - tự chọn sync/async theo ngưỡng |
| 2 | Progress tracking | Cập nhật tiến trình real-time (số dòng đã xử lý / tổng số) qua task manager |
| 3 | Error report | Báo cáo chi tiết: dòng nào thành công, dòng nào lỗi và lý do |
Kiến trúc
Tổng quan
Plugin extends plugin-action-import - override handler import và thêm chế độ async. Yêu cầu plugin-async-task-manager để quản lý background job.
| Tầng | Vai trò | Thành phần |
|---|---|---|
| Client UI | Override import modal + hiển thị kết quả | ImportProPluginProvider, ImportTaskResultRenderer |
| Server Handler | Override importXlsx với sync/async mode | ProImportXlsx |
| Job Worker | Xử lý import trong background | Worker topic importXlsxPro |
| Task Manager | Quản lý job, progress, notification | plugin-async-task-manager |
Yêu cầu plugin
| Plugin bắt buộc | Vai trò |
|---|---|
plugin-action-import | Plugin import cơ bản (được override) |
plugin-async-task-manager | Quản lý async job, notification |
Biến môi trường
| Biến | Mặc định | Mô tả |
|---|---|---|
IMPORT_AUTO_MODE_THRESHOLD | (hệ thống) | Ngưỡng số dòng để tự chuyển sang async mode |
API endpoints
| Endpoint | Method | Mô tả |
|---|---|---|
{collection}:importXlsx | POST | Import Excel (override - tự chọn sync/async) |
asyncTasks:fetchFile/{taskId} | GET | Tải báo cáo kết quả từ async task |
Job topics
| Topic | Mô tả |
|---|---|
importXlsxPro | Job import dữ liệu từ Excel (async mode) |
CLI commands
| Command | Mô tả |
|---|---|
import-xlsx | Chạy import Excel từ command line |
Cờ đặc biệt
| Cờ | Mô tả |
|---|---|
skipWorkflow | Bỏ qua workflow hooks trong sync path (tăng tốc import) |
Luồng hoạt động
Import async mode
Báo cáo kết quả
Sau khi import hoàn tất (cả sync và async), hệ thống trả về báo cáo chi tiết:
| Thông tin | Mô tả |
|---|---|
| Tổng số dòng | Tổng dòng dữ liệu trong file Excel |
| Thành công | Số dòng insert/update thành công |
| Lỗi | Số dòng lỗi kèm danh sách chi tiết |
| Chi tiết lỗi | Dòng số mấy, field nào, lý do gì |
So sánh Import vs Import Pro
| Tiêu chí | Import (cơ bản) | Import Pro |
|---|---|---|
| Xử lý | Đồng bộ | Sync/async tự động |
| File lớn | Timeout risk | Background job |
| Progress | Không | Real-time tracking |
| Error report | Cơ bản | Chi tiết từng dòng |
| skipWorkflow | Không | Có (sync path) |
Thành phần client
| Thành phần | Mô tả |
|---|---|
ImportProPluginProvider | Provider override import UI bằng phiên bản async |
ImportTaskResultRenderer | Hiển thị kết quả import trong async task manager UI |
ImportValidationErrors | Component hiển thị chi tiết lỗi validation từng dòng |
ImportProModal | Modal import với progress bar và error report |
Dependencies
| Package | Vai trò |
|---|---|
@digiforce-nc/plugin-action-import | Plugin import cơ bản (peer) |
@digiforce-nc/plugin-async-task-manager | Async task manager (peer) |
@digiforce-nc/client | Client framework (peer) |
@digiforce-nc/server | Server framework (peer) |