@digiforce-nc/plugin-workflow

Plugin tự động hoá quy trình nghiệp vụ — định nghĩa workflow dạng đồ thị node, kích hoạt bằng sự kiện hoặc lịch hẹn, thực thi jobs theo thứ tự.

Plugin này làm gì?

Hãy hình dung một dây chuyền sản xuất: mỗi workflow là một dây chuyền với các trạm (node) — trạm tính toán, trạm kiểm tra điều kiện, trạm ghi dữ liệu. Khi có sản phẩm (trigger event) đi vào, dây chuyền tự động chạy qua từng trạm cho đến khi hoàn thành.

Ba nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Kích hoạt	Lắng nghe sự kiện collection (afterCreate, afterUpdate...) hoặc chạy theo lịch (cron)
2	Xử lý luồng	Duyệt đồ thị node: tính toán, rẽ nhánh điều kiện, CRUD dữ liệu, chờ duyệt
3	Quản lý thực thi	Ghi log execution, theo dõi trạng thái job, hỗ trợ resume/cancel

Kiến trúc

Triggers (built-in)

Trigger	Khi nào chạy	Ví dụ
CollectionTrigger	Sự kiện trên collection	Khi tạo đơn hàng mới → gửi email
ScheduleTrigger	Theo lịch cron	Mỗi ngày 8h sáng → tổng hợp báo cáo

Triggers — cải thiện validation

Từ phiên bản mới, tất cả trigger types (Action, Custom Action, Request Interceptor) đều hỗ trợ config validation qua Joi schema:

typescript

configSchema = Joi.object({
  collection: Joi.string().required(),
});

validateConfig(config) {
  const errors = super.validateConfig(config);
  if (errors) return errors;
  return validateCollectionField(config.collection, this.workflow.app.dataSourceManager);
}

validateCollectionField() kiểm tra:

Format dataSourceName:collectionName hợp lệ
Data source tồn tại
Collection tồn tại trong data source

Instructions (built-in node types)

Instruction	Chức năng
`calculation`	Tính toán giá trị, gán biến
`condition`	Rẽ nhánh theo điều kiện đơn (if/else)
`multi-conditions`	Rẽ nhánh theo nhiều điều kiện
`create`	Tạo bản ghi mới
`update`	Cập nhật bản ghi
`destroy`	Xóa bản ghi
`query`	Truy vấn dữ liệu
`output`	Xuất kết quả
`end`	Kết thúc workflow

Database — 7 bảng chính

Bảng	Chứa gì
`workflows`	Định nghĩa workflow (title, type, config, enabled)
`flow_nodes`	Node trong workflow (type, config, upstreamId, branchIndex)
`executions`	Lịch sử chạy workflow (status, context)
`jobs`	Từng bước thực thi (nodeId, status, result)
`workflowTasks`	Task chờ duyệt
`userWorkflowTasks`	Gán task cho user cụ thể (stats: pending, all)
`workflowCategories`	Phân loại workflow

ACL — Phân quyền

Resource	Quyền	Mô tả
`workflows:`, `workflows.nodes:`	Admin (snippet)	Quản lý workflow và nodes
`executions:list/get/cancel/destroy`	Admin (snippet)	Xem và quản lý execution
`flow_nodes:update/destroy/...`	Admin (snippet)	Chỉnh sửa nodes
`workflowCategories:*`	Admin (snippet)	Phân loại workflow
`workflows:list`	`ui.workflows`	UI hiển thị danh sách
`userWorkflowTasks:listMine`	`loggedIn`	User xem task của mình
`*:trigger`	`loggedIn`	Kích hoạt workflow

Workflow utilities (mới)

Plugin export thêm các utility functions:

Function	Mô tả
`validateCollectionField(collection, dsManager)`	Kiểm tra collection path hợp lệ (format, data source, collection tồn tại)
`getExecutionStatusName(status)`	Chuyển status number thành tên readable (`RESOLVED`, `REJECTED`, `CANCELED`...)
`getWorkflowExecutionLogMeta(workflow, processor?)`	Trích metadata cho structured logging (workflowId, executionId, lastNode, status...)
`toJSON(data)`	Serialize Model instances thành plain objects (xử lý associations đệ quy)

RequestInstruction — hỗ trợ multipart/form-data

plugin-workflow-request giờ hỗ trợ gửi HTTP request với body dạng multipart/form-data, cho phép upload file từ workflow:

Content-Type	Mô tả
`application/json`	JSON body (mặc định)
`text/plain`	Plain text
`application/x-www-form-urlencoded`	URL-encoded form
`multipart/form-data`	Mới — Form data với hỗ trợ file upload từ attachment

typescript

// Ví dụ config node request với file upload
{
  url: 'https://api.example.com/upload',
  method: 'POST',
  contentType: 'multipart/form-data',
  data: [
    { valueType: 'text', name: 'title', text: 'Report 2026' },
    { valueType: 'file', name: 'document', file: attachmentRecord },
  ],
}

Dependencies

Package	Vai trò
`@digiforce-nc/database`	Database ORM
`@digiforce-nc/server`	Server framework
`@digiforce-nc/evaluators`	Đánh giá biểu thức trong node
`@digiforce-nc/logger`	Ghi log execution riêng biệt
`nodejs-snowflake`	Sinh ID duy nhất cho execution
`lru-cache`	Cache logger instances