Tham chiếu API — Async Task Manager

Tổng quan Resource

Resource	Mô tả	Quyền
asyncTasks	Quản lý tác vụ nền	Người dùng đã đăng nhập (loggedIn)

User chỉ thấy và điều khiển tasks do chính mình tạo.

Lấy danh sách tasks

const response = await agent.resource('asyncTasks').list({
  sort: ['-createdAt'],
  filter: { status: 'running' },  // tuỳ chọn: lọc theo trạng thái
});
// response.body.data = [{ id, taskType, status, progress, createdAt, ... }]

Lấy chi tiết task

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

Dừng task đang chạy

await agent.resource('asyncTasks').stop({
  filterByTargetKey: taskId,
});
// Task chuyển sang status: 'cancelled'

Tải file kết quả

// Chỉ khả dụng khi status = 'completed' và task có resultFile
const file = await agent.resource('asyncTasks').fetchFile({
  filterByTargetKey: taskId,
});
// Response: stream file download

Task Object

Trường	Kiểu	Mô tả
id	bigint	ID tác vụ
taskType	string	Loại task: export-xlsx, import-csv, bulk-update, custom...
status	string	pending, running, completed, failed, cancelled
progress	float	Tiến trình 0–100 (%)
params	json	Tham số đầu vào của task
resultFile	string	Đường dẫn file kết quả (nếu có)
errorMessage	text	Thông báo lỗi (nếu failed)
userId	bigint	User đã tạo task
createdAt	timestamp	Thời gian tạo
updatedAt	timestamp	Thời gian cập nhật gần nhất

Dành cho Plugin Developer

Đăng ký Task Type

Plugin khác đăng ký task type thông qua AsyncTaskManager:

import { Plugin } from '@digiforce-nc/server';

class MyExportPlugin extends Plugin {
  async load() {
    const taskManager = this.app.pm.get('async-task-manager');
    
    taskManager.registerTaskType('my-custom-export', {
      handler: async (task, params) => {
        const { collectionName, filter } = params;
        const records = await this.db.getRepository(collectionName).find({ filter });
        
        for (let i = 0; i < records.length; i++) {
          // Xử lý từng record
          await processRecord(records[i]);
          
          // Cập nhật tiến trình
          const progress = Math.round((i / records.length) * 100);
          await task.updateProgress(progress);
        }
        
        return { resultFile: '/path/to/result.xlsx' };
      },
    });
  }
}

Tạo task từ code

const taskManager = this.app.pm.get('async-task-manager');
const task = await taskManager.createTask({
  type: 'my-custom-export',
  params: {
    collectionName: 'orders',
    filter: { status: 'completed' },
  },
  userId: ctx.state.currentUser.id,
});
// task.id = ID của task vừa tạo

Task Type Registry

Lifecycle của một task

Thành phần Client

Thành phần	Mô tả	Sử dụng
AsyncTaskManagerProvider	Context provider quản lý task states	Wrap toàn bộ app
TaskProgressBar	Component hiển thị thanh tiến trình	Trong task list
TaskList	Danh sách tasks đang chạy/hoàn thành	Panel popup
TaskOriginRegistry	Registry để plugin client đăng ký UI cho task type	Plugin developer

Giới hạn kỹ thuật

Tham số	Giá trị	Ghi chú
Tối đa tasks đồng thời	5 (cấu hình được)	Tăng nếu server đủ tài nguyên
File kết quả tồn tại	24h (cấu hình được)	Tự động xoá sau đó
Task timeout mặc định	10 phút	Tăng cho tác vụ lớn
Retry khi lỗi	3 lần	Chỉ cho transient errors