*.workflow.ts
Workflow là một chuỗi bước viết bằng code, chạy bền trên cùng engine với quy trình BPMN: mỗi step.run chạy đúng một lần và được nhớ kết quả, nên app khởi động lại hay bước sau lỗi thì lượt chạy vẫn đi tiếp từ chỗ dừng. Hợp với việc kỹ thuật nhiều bước — nhập dữ liệu theo lô, đồng bộ với hệ thống khác — khi chuỗi bước là code chứ không phải sơ đồ cho người đọc.
Chưa mở cho app. Hiện check chưa nhận file *.workflow.ts (rule process.code-later) — đây là bề mặt nâng cao, còn ở dạng xem trước. Việc nghiệp vụ nhiều bước (duyệt, chờ thanh toán, nhắc hạn) hãy làm bằng quy trình BPMN: cùng engine, cùng trang Vận hành › Quy trình, cùng bộ công cụ, và vẽ được cho người nghiệp vụ đọc.
Export
*.workflow.ts:defaultlà hàmasync (input, step). Bắt đầu một lượt bằngstart("app/…/x.workflow.ts", input, { key })từ handler không phải GET — cùng engine, cùng công cụ với quy trình BPMN.step.run(name, fn): chạyfnđúng một lần, nhớ kết quả; lần thức dậy sau trả lại kết quả cũ, không chạy lại. ĐặtDate.now(),Math.random(), đọc DB vào trongstep.run.step.sleep(name, seconds | Date): ngủ tới một thời điểm (giây hoặcDate, tối đa 365 ngày); đang ngủ thì không tốn tài nguyên.step.waitFor(name, event, { timeoutSeconds }): chờ một sự kiện dosend()gửi tới; trả dữ liệu của sự kiện, hoặcnullkhi hết giờ.
Ví dụ
export default async function (input: { batchId: number }, step) {
const rows = await step.run("fetch", () => fetchBatch(input.batchId)); // chạy một lần, nhớ kết quả
await step.sleep("cool-down", 600); // giây hoặc một Date, ≤ 365 ngày
const ok = await step.waitFor("confirm", "confirmed", { timeoutSeconds: 86400 }); // dữ liệu của send(), hoặc null khi hết giờ
if (!ok) return { skipped: true };
await step.run("apply", () => applyRows(rows), { attempts: 5 });
}Workflow trực quan (*.workflow.json)
Workflow trực quan là một đồ thị node + cạnh trong một file JSON, dựng để vẽ trên canvas (mở file trong tab Code là thấy sơ đồ: thanh thêm bước, ô thuộc tính bên phải, nối node bằng cách kéo; tab JSON sửa cùng nội dung). Nó chạy trên cùng engine bền với quy trình: có lượt chạy, từng bước, hẹn giờ, thử lại, và bắt đầu bằng start("app/…/x.workflow.json", { … }) từ handler không phải GET. Đầu vào phải là một object, trở thành biến của lượt chạy (vars trong file là giá trị mặc định).
{
"nodes": [
{ "id": "start", "type": "start" },
{ "id": "reserve", "type": "run-code", "config": { "task": "orders/reserve", "inputs": { "id": "=orderId" } } },
{ "id": "big", "type": "condition" },
{ "id": "wait", "type": "sleep", "config": { "duration": "PT30M" } },
{ "id": "done", "type": "output" }
],
"edges": [
{ "from": "start", "to": "reserve" }, { "from": "reserve", "to": "big" },
{ "id": "yes", "from": "big", "to": "wait", "when": "=total >= 1000" },
{ "id": "no", "from": "big", "to": "done" },
{ "from": "wait", "to": "done" }
]
}- Node cơ bản:
start,run-code(gọiapp/<task>.task.ts),condition(cạnh ra mangwhenlà FEEL, đúng một cạnh không cówhenlà nhánh else),sleep,set-var,output. - Node nâng cao: giá trị trong
configbắt đầu bằng=là biểu thức FEEL; trong các ô chữ (prompt,subject,text,html,url){{tên}}chèn giá trị của một biến.loop: lặp qua một danh sách (items: danh sách hoặc=biểu thức), tối đa 1000 phần tử (mặc định 100), lần lượt từng phần tử. Có hai cạnh ra:"branch": "body"(các bước chạy cho từng phần tử, bước cuối nối ngược vềloop) và"branch": "done"(đi tiếp sau phần tử cuối).collect+resultVariablegom một giá trị sau mỗi vòng thành danh sách.wait-for: dừng tới khi cósend(<lượt>, "<sự kiện>", dữ liệu), không tốn tài nguyên khi chờ. Đặttimeoutthì có thêm cạnh"branch": "timeout"cho trường hợp hết giờ.call-process: chạy một file.bpmnhoặc.workflow.jsonkhác thành lượt con và chờ nó xong; huỷ lượt cha thì lượt con cũng bị huỷ.checkbáo nếu file được gọi không có.http: gọi một địa chỉ công khai (method,url,headers,body), kết quả{ ok, status, body }vào một biến. Lỗi 5xx / 429 được thử lại, 4xx thì dừng. Bước có thể chạy lại sau sự cố, nên một POST không idempotent có thể tới nơi hai lần: gửi kèm khoá idempotency khi việc đó quan trọng.llm: gọi dịch vụ AI của app (cùng dịch vụ và cùng hạn mức vớimanh/openai), câu trả lời (hoặc JSON đã phân tích) vào một biến. Lỗi 429 / 503 / 504 được thử lại; bậtcontinueOnErrorđể workflow vẫn chạy tiếp khi AI bận.email: gửi thư qua dịch vụ thư của app (manh/email, cùng giới hạn người nhận).
- Chưa mở:
db(đọc bảng bằng mộtrun-codegọi*.task.ts), nhánh song song,merge,map,triggervà vòng lặp ngoàiloop.checkbáo rõ tên node chưa có. checkbắt file JSON hỏng, cạnh trỏ sai, biểu thức FEEL sai cú pháp,run-codethiếu file*.task.tsvàcall-processtrỏ tới file không có.
Quy trình hay workflow
- Việc nghiệp vụ — duyệt nhiều cấp, chờ thanh toán, SLA, nhắc hạn, việc giao cho người — là một quy trình BPMN: vẽ được, có user task / bảng quyết định DMN / boundary timer, và là bề mặt đang mở cho app.
- Việc kỹ thuật — chuỗi bước là code, không cần sơ đồ — hợp với
*.workflow.ts. Nhưng vìcheckchưa nhận file này, hiện vẫn nên mô hình hoá các bước đó bằng một quy trình BPMN (service task gọi*.task.ts), hoặc một *.job.ts nếu chỉ là một việc nền sau request.
Cần biết
- Replay: mỗi lần thức dậy, hàm chạy lại từ đầu; bước đã xong trả lại kết quả đã nhớ. Giữ code giữa các bước không có
Date.now(),Math.random(), đọc DB (đặt chúng trongstep.run); đặt tên riêng cho từng bước ("send-" + itrong vòng lặp). - Một bước có thể chạy hai lần nếu hỏng giữa chừng — làm cho phần ghi của nó idempotent (upsert, kiểm trạng thái trước khi ghi).
- Lượt chạy, sự cố, thử lại, huỷ: cùng trang Vận hành › Workflow với quy trình BPMN.
Bước tiếp theo
- Quy trình (*.bpmn) — việc nghiệp vụ nhiều bước, duyệt, hẹn giờ, chờ người (bề mặt đang mở cho app).
- *.job.ts — một việc chậm chạy nền sau request.