AdaFlow - Tổng quan Node

I. Tổng quan

Tài liệu này mô tả khái niệm dùng chung cho toàn bộ node trong AdaFlow. Đây là file gốc để định nghĩa node, phân biệt trigger/action và chốt những nguyên tắc áp dụng trước khi đi vào từng file node cụ thể.

1. Vấn đề

  • Nếu mỗi file node tự định nghĩa lại khái niệm theo cách riêng, người đọc sẽ khó phân biệt đâu là trigger, đâu là action và đâu là rule chung cho toàn hệ thống.
  • Builder của AdaFlow dùng chung một cấu trúc tương tác cho node như chọn card trên canvas, mở panel phải, xem output và test node; nếu không có tài liệu gốc thì các node dễ đặc tả thiếu thống nhất.
  • Một số node đến từ CRM, chat, logic hoặc integration có khác nhau về nghiệp vụ, nhưng vẫn cần cùng cách hiểu về input, output, validation và trạng thái lỗi.

2. Giải pháp

  • Định nghĩa một mô hình node chung cho AdaFlow.
  • Tách bạch hai loại node:
    • Trigger node: node khởi phát flow.
    • Action node: node xử lý sau khi flow đã khởi phát.
  • Quy định một số thành phần chung của mọi node:
    • Tên node.
    • Nhóm node.
    • Cấu hình input.
    • Dữ liệu output.
    • Rule validate.
    • Trạng thái lỗi.

3. Đối tượng

  • BA, PO, Dev, QA cần hiểu logic chung của node trước khi viết hoặc đọc tài liệu node cụ thể.
  • Người thiết kế flow hoặc xây node mới cần dùng file này làm nguồn tham chiếu chung.

4. Tầm nhìn/insight

  • Khi số lượng node tăng lớn, việc có một node overview chuẩn sẽ giúp node mới được thêm vào hệ thống mà không làm lệch ngôn ngữ tài liệu.
  • Tương lai có thể mở rộng thêm node template library, nhóm node nâng cao hoặc chính sách version riêng cho node.

II. Yêu cầu chức năng

1. Danh sách tính năng

  • Định nghĩa khái niệm chung của node.
  • Phân biệt trigger node và action node.
  • Mô tả cách node xuất hiện trên builder.
  • Mô tả luồng dữ liệu giữa các node.
  • Chỉ ra cách phân nhóm node trong hệ thống.

2. Đặc tả chi tiết

  • Một node trong AdaFlow được hiểu là đơn vị cấu hình nhỏ nhất của flow.
  • Mỗi node đại diện cho một hành vi có thể được thêm lên canvas và thực thi trong lúc flow chạy.
  • Trigger node là điểm bắt đầu của flow; action node là bước xử lý tiếp theo.
  • Mọi node nên được mô tả theo cùng một cấu trúc tài liệu:
    • Mục đích sử dụng.
    • Input mà node nhận.
    • Cấu hình người dùng nhập.
    • Output mà node tạo ra.
    • Rule validation.
    • Trường hợp lỗi.

3. Nhóm node

Loại Nhóm Thư mục Ý nghĩa
Trigger Action trigger_nodes/action Trigger theo lịch hoặc hành động hệ thống.
Trigger CRM trigger_nodes/CRM Trigger theo biến động của record CRM.
Trigger Omnichannel trigger_nodes/omnichannel Trigger theo hội thoại, tin nhắn hoặc metadata chat.
Trigger Integration trigger_nodes/integration Trigger theo event từ hệ thống ngoài.
Action CRM action_nodes/CRM Action thao tác lên record CRM.
Action Omnichannel action_nodes/omnichannel Action thao tác lên hội thoại hoặc metadata chat.
Action Logic action_nodes/logic Action chờ, điều kiện, rẽ nhánh, xử lý trung gian.
Action Integration action_nodes/integration Action gọi email, webhook hoặc dịch vụ ngoài.

4. Danh sách nghiệp vụ

  • Trong phiên bản hiện tại của builder, mỗi flow có một trigger node gốc.
  • Trigger node tạo ra ngữ cảnh đầu vào đầu tiên cho flow run.
  • Action node nhận dữ liệu từ trigger hoặc action đứng trước.
  • Output của một node phải có thể được tham chiếu ở node sau nếu flow cho phép mapping dữ liệu.
  • Node chưa cấu hình đủ field bắt buộc phải bị xem là invalid.
  • Node lỗi validate không được làm flow đủ điều kiện xuất bản.
  • Node có thể có trạng thái chưa cấu hình, hợp lệ, lỗi cấu hình hoặc lỗi thực thi tùy theo ngữ cảnh builder và run.
  • Tài liệu từng node không nên lặp lại toàn bộ định nghĩa trong file này; chỉ mô tả rule riêng của node đó.

5. Giao diện

  • Lưu ý: Hình dưới đây chỉ mang tính minh họa cho cách node xuất hiện trên builder, không phải ảnh thiết kế giao diện chính thức trích xuất trực tiếp từ Figma.
  • Thiết kế giao diện chính thức xem tại:
    • https://www.figma.com/design/tBBrdtHlG1LAYJUfJsvyS3/UCALL-2026–Ant-Design-5.10.1-?node-id=4-154796&m=dev

Minh họa node card và panel cấu hình

  • Trên builder, node hiển thị dưới dạng card trên canvas.
  • Khi chọn node, panel cấu hình bên phải mở ra với một số tab chính theo Figma:
    • Hành động: mô tả hoặc chọn mode hoạt động của node.
    • Cài đặt: nhập field cấu hình chính.
    • Kiểm thử: kiểm tra node bằng dữ liệu mẫu hoặc trạng thái hợp lệ.
    • Đầu ra: xem tập dữ liệu node sinh ra cho bước sau.
  • Node card nên thể hiện được ít nhất tên node, icon nhóm node và một số tham số chính để người dùng nhìn nhanh flow.

III. Yêu cầu phi chức năng

  • Tính nhất quán: Tất cả node cần dùng cùng cách gọi, cùng logic input/output và cùng cách phân biệt trigger/action.
  • Khả năng mở rộng: Hệ thống phải cho phép bổ sung node mới theo nhóm mà không cần viết lại tài liệu gốc.
  • Khả năng học nhanh: Người đọc chỉ cần hiểu node_overview một lần là có thể đọc các node khác theo cùng pattern.
  • Khả năng truy vết: Khi flow chạy lỗi, tài liệu node phải đủ rõ để đối chiếu với flow_run_detail.

IV. Dependency

V. API Contract (Dev viết)

  • File này không định nghĩa API contract cụ thể.
  • API ở mức kỹ thuật cần bổ sung tại tài liệu chi tiết của flow, run hoặc từng node khi triển khai.

VI. Test case (BA hoặc tester viết)

  • TC1: Đọc file này -> Phân biệt được trigger node và action node.
  • TC2: Đọc file này -> Xác định được node thuộc nhóm nào và nên tìm tài liệu ở folder nào.
  • TC3: Đọc file này trước khi đọc tài liệu node cụ thể -> Không cần hỏi lại khái niệm input, output, validation, run.