@digiforce-nc/plugin-async-task-manager

Plugin quản lý tác vụ nền (background jobs) — theo dõi tiến trình, hỗ trợ dừng giữa chừng, và tải file kết quả.

Plugin này làm gì?

Một số thao tác tốn thời gian (xuất Excel, import CSV, xử lý batch...) không thể chạy đồng bộ. Plugin cung cấp AsyncTaskManager — container quản lý tác vụ nền: khởi tạo, theo dõi tiến trình, dừng, và tải kết quả.

Ba nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Quản lý lifecycle	Tạo task, chạy background, cập nhật progress, hoàn thành/thất bại
2	Task type registry	Plugin khác đăng ký task type (CommandTaskType) vào container
3	API điều khiển	List tasks, get progress, stop task, download file kết quả

Kiến trúc

Luồng thực thi tác vụ nền

Task Type Registry

Task Type	Plugin nguồn	Mô tả
`export-xlsx`	plugin-export	Xuất collection ra Excel
`import-csv`	plugin-import	Nhập dữ liệu từ CSV
`bulk-update`	plugin-bulk-edit	Cập nhật hàng loạt

Database - collection asyncTasks

Field	Mô tả
`taskType`	Loại task (export-xlsx, import-csv...)
`status`	`pending`, `running`, `completed`, `failed`, `cancelled`
`progress`	Tiến trình 0-100 (%)
`resultFile`	Đường dẫn file kết quả (nếu có)
`errorMessage`	Thông báo lỗi (nếu failed)

API endpoints

Endpoint	Mô tả
`asyncTasks:list`	Danh sách tasks của user hiện tại
`asyncTasks:get`	Chi tiết task (status, progress)
`asyncTasks:stop`	Dừng task đang chạy
`asyncTasks:fetchFile`	Tải file kết quả (stream)

Vòng đời plugin

ACL - Phân quyền

Quyền	Đối tượng	Mô tả
`asyncTasks:*`	loggedIn	User đã đăng nhập có thể tạo và xem tasks của mình

Ví dụ sử dụng API

Theo dõi tiến trình

typescript

const response = await agent.resource('asyncTasks').get({
  filterByTargetKey: taskId,
});
const { status, progress } = response.body.data;

Dừng task

typescript

await agent.resource('asyncTasks').stop({ filterByTargetKey: taskId });

Đăng ký task type (plugin developer)

typescript

class MyPlugin extends Plugin {
  async load() {
    const tm = this.app.pm.get('async-task-manager');
    tm.registerTaskType('my-task', {
      handler: async (task, params) => {
        for (let i = 0; i <= 100; i += 10) await task.updateProgress(i);
        return { resultFile: '/path/to/result.xlsx' };
      },
    });
  }
}

Thành phần client

Thành phần	Mô tả
`AsyncTaskManagerProvider`	Context provider quản lý task states
`TaskProgressBar`	Component hiển thị tiến trình
`TaskList`	Danh sách tasks đang chạy/hoàn thành
`TaskOriginRegistry`	Registry để plugin client đăng ký UI cho task type

Dependencies

Package	Vai trò
`@digiforce-nc/server`	Server framework — resource, streaming
`@digiforce-nc/database`	Database ORM — collection definitions
`@digiforce-nc/client`	Client framework — UI components