Tham chiếu API

Endpoints

Endpoint	Method	Mô tả
{collection}:importXlsx	POST	Import Excel (override — tự chọn sync/async theo ngưỡng)
asyncTasks:fetchFile/{taskId}	GET	Tải báo cáo kết quả từ async task

{collection}:importXlsx (override)

Plugin override handler importXlsx bằng ProImportXlsx. Luồng xử lý:

1. Server nhận file upload qua multer middleware.
2. Đếm số dòng dữ liệu trong file.
3. So sánh với ngưỡng IMPORT_AUTO_MODE_THRESHOLD.
4. Nếu dưới ngưỡng → import đồng bộ (giống plugin cơ bản).
5. Nếu vượt ngưỡng → tạo async job topic importXlsxPro, trả job ID về client.

Request params: giống endpoint import cơ bản (file, columns, explain).

Cờ đặc biệt

Cờ	Mô tả
skipWorkflow	Bỏ qua workflow hooks trong sync path — tăng tốc import khi không cần trigger workflow

Job topic

Topic	Mô tả
importXlsxPro	Job import dữ liệu từ Excel (async mode)

Luồng async job

1. Worker nhận job từ queue.
2. Parse file Excel thành từng batch dòng.
3. Validate + insert/update từng batch.
4. Cập nhật progress sau mỗi batch (x/total).
5. Khi hoàn tất, lưu báo cáo kết quả + đánh dấu done.
6. Gửi notification cho user.

CLI commands

Command	Mô tả
import-xlsx	Chạy import Excel từ command line (hữu ích cho batch processing hoặc migration)

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

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)