Skip to Content

*.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: default là hàm async (input, step). Bắt đầu một lượt bằng start("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ạy fn đú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. Đặt Date.now(), Math.random(), đọc DB vào trong step.run.
  • step.sleep(name, seconds | Date): ngủ tới một thời điểm (giây hoặc Date, 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 do send() gửi tới; trả dữ liệu của sự kiện, hoặc null khi hết giờ.

Ví dụ

app/sync/import.workflow.ts
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).

app/orders/welcome.workflow.json
{ "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ọi app/<task>.task.ts), condition (cạnh ra mang when là FEEL, đúng một cạnh không có when là nhánh else), sleep, set-var, output.
  • Node nâng cao: giá trị trong config bắ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 + resultVariable gom 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ờ. Đặt timeout thì có thêm cạnh "branch": "timeout" cho trường hợp hết giờ.
    • call-process: chạy một file .bpmn hoặc .workflow.json khác thành lượt con và chờ nó xong; huỷ lượt cha thì lượt con cũng bị huỷ. check bá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ới manh/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ật continueOnError để 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ột run-code gọi *.task.ts), nhánh song song, merge, map, trigger và vòng lặp ngoài loop. check báo rõ tên node chưa có.
  • check bắt file JSON hỏng, cạnh trỏ sai, biểu thức FEEL sai cú pháp, run-code thiếu file *.task.ts và call-process trỏ 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ì check chư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 trong step.run); đặt tên riêng cho từng bước ("send-" + i trong 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.
Cập nhật