AdaFlow - Flow (Luồng Tự Động)

I. Tổng quan

Tài liệu này mô tả tổng quan về Flow và màn hình cấu hình Flow Builder trong AdaFlow. Trong phạm vi hiện tại, Flow và Flow Builder được mô tả trong cùng một file vì đây là một trải nghiệm thống nhất của người dùng.

1. Vấn đề

  • Nhiều tác vụ tự động như cập nhật CRM, gửi email, xử lý hội thoại hoặc gọi tích hợp ngoài thường phát sinh theo chuỗi nhiều bước, nhưng nếu chỉ cấu hình bằng các form rời rạc thì người dùng khó hình dung luồng tổng thể.
  • Khi một flow có điều kiện kích hoạt, bước chờ, bước xử lý và bước gửi thông báo, người dùng cần một màn hình đủ trực quan để thấy thứ tự thực thi và dữ liệu đi qua từng node.
  • Nếu không có tài liệu gốc cho Flow, các file node riêng lẻ sẽ không đủ để giải thích cách chúng được ghép lại thành một luồng hoàn chỉnh, khi nào được publish và khi nào được ghi nhận vào báo cáo chạy.

2. Giải pháp

  • Xây dựng mô hình Flow gồm:
    • Một trigger node làm điểm khởi phát.
    • Một hoặc nhiều action node xử lý tiếp theo.
    • Quan hệ nối giữa các node theo đúng thứ tự thực thi.
  • Cung cấp Flow Builder dạng trực quan:
    • Canvas hiển thị card node.
    • Header hiển thị tên flow và trạng thái lưu/xuất bản.
    • Panel cấu hình node ở bên phải với các tab Hành động, Cài đặt, Kiểm thử, Đầu ra.
  • Cho phép người dùng lưu nháp, chỉnh sửa, kiểm thử và xuất bản flow trước khi đưa vào vận hành thật.

3. Đối tượng

  • Admin hoặc người có quyền cấu hình automation trong workspace.
  • Quản lý vận hành CRM, marketing automation, CSKH hoặc nhóm tích hợp cần chuẩn hóa rule tự động.
  • BA, Dev, QA và Designer cần hiểu builder để đặc tả hoặc phát triển node mới.

4. Tầm nhìn/insight

  • Tương lai có thể bổ sung flow template, sao chép flow, versioning, rollback hoặc thư viện flow mẫu theo từng nghiệp vụ.
  • Tương lai có thể hỗ trợ nhiều loại trigger phức tạp hơn, nhiều nhánh điều kiện và báo cáo vận hành chi tiết hơn cho từng flow.

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

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

  • Tạo mới flow.
  • Chỉnh sửa thông tin flow.
  • Thiết kế flow trên canvas builder.
  • Chọn trigger node khởi đầu cho flow.
  • Thêm, xóa và cấu hình action node.
  • Kiểm thử node hoặc kiểm thử flow trước khi xuất bản.
  • Lưu nháp và cập nhật flow.
  • Xuất bản hoặc tạm dừng flow.
  • Điều hướng sang báo cáo và chi tiết các lần chạy.

2. Đặc tả chi tiết

User story 1: Là một [Quản trị viên hoặc người cấu hình automation], tôi muốn [tạo và thiết kế flow trên một màn hình trực quan] để [nhìn được toàn bộ các bước xử lý trong cùng một luồng].

  • Use case 1.1 (Tạo flow mới): User vào module AdaFlow -> Bấm tạo flow -> Hệ thống mở màn builder với flow mới ở trạng thái nháp -> User nhập tên flow và chọn trigger node đầu tiên -> Canvas hiển thị flow với một trigger card.

  • Use case 1.2 (Thêm action node): User chọn điểm nối tiếp sau trigger hoặc sau một action node -> Bấm thêm node -> Hệ thống mở danh sách node phù hợp -> User chọn action node -> Hệ thống thêm card node lên canvas và nối node theo đúng vị trí vừa chọn.

User story 2: Là một [Người cấu hình flow], tôi muốn [cấu hình node ở panel bên phải] để [không phải rời khỏi canvas khi sửa từng bước của flow].

  • Use case 2.1 (Chọn node và mở panel cấu hình): User click vào một node trên canvas -> Hệ thống mở panel cấu hình ở bên phải -> Panel hiển thị các tab Hành động, Cài đặt, Kiểm thử, Đầu ra tùy node -> User chỉnh dữ liệu cấu hình tại đây.

  • Use case 2.2 (Kiểm tra đầu ra của node): User mở tab Đầu ra của node -> Hệ thống hiển thị tập dữ liệu mà node hiện tại tạo ra hoặc truyền sang bước sau -> User dùng thông tin này để map dữ liệu cho action tiếp theo.

User story 3: Là một [Người cấu hình flow], tôi muốn [lưu nháp và xuất bản flow theo từng giai đoạn] để [chỉ đưa flow hợp lệ vào chạy thực tế].

  • Use case 3.1 (Lưu nháp thành công): User chỉnh sửa tên flow hoặc cấu hình node -> Bấm Lưu -> Hệ thống lưu bản nháp hiện tại -> Header hiển thị trạng thái Đã lưu.

  • Use case 3.2 (Có thay đổi chưa xuất bản): Flow đang có phiên bản đã xuất bản -> User chỉnh sửa node hoặc thêm node mới -> Hệ thống hiển thị cảnh báo Có thay đổi chưa được xuất bản -> Flow cũ vẫn tiếp tục vận hành cho tới khi user xuất bản phiên bản mới.

  • Use case 3.3 (Xuất bản flow hợp lệ): User bấm Xuất bản -> Hệ thống validate toàn bộ flow -> Nếu flow hợp lệ thì hệ thống lưu phiên bản xuất bản mới và chuyển flow sang trạng thái active.

  • Use case 3.4 (Exception - Flow chưa hợp lệ): User bấm Xuất bản khi còn node thiếu cấu hình bắt buộc -> Hệ thống chặn xuất bản -> Node lỗi được highlight và hiện thông tin lỗi tại panel cấu hình hoặc ngay trên canvas.

3. Danh sách nghiệp vụ

  • Mỗi flow phải có đúng một trigger node gốc làm điểm bắt đầu ở phiên bản hiện tại của builder.
  • Một flow có thể có nhiều action node xử lý nối tiếp; khả năng rẽ nhánh được hỗ trợ tùy theo node logic hoặc node điều kiện được cấu hình.
  • Flow có tối thiểu các trạng thái:
    • draft: đang cấu hình, chưa xuất bản.
    • saved: bản nháp đã được lưu.
    • active: phiên bản hiện tại đang được xuất bản và tham gia vận hành.
    • paused: flow tạm dừng, không khởi tạo run mới.
  • Khi flow đã có phiên bản active, mọi thay đổi mới phải được xem là thay đổi nháp cho tới khi user xuất bản lại.
  • Node thiếu cấu hình bắt buộc hoặc có mapping dữ liệu không hợp lệ phải làm flow không đủ điều kiện xuất bản.
  • Việc Kiểm thử không thay thế cho Xuất bản; test dùng để kiểm tra logic hoặc dữ liệu cấu hình trước khi đưa flow vào vận hành thật.
  • Việc xóa node phải giữ tính toàn vẹn của canvas; nếu xóa một node ở giữa chuỗi xử lý, hệ thống phải yêu cầu user xác nhận hoặc cấu hình lại nhánh bị ảnh hưởng.

4. Giao diện

  • Figma tham chiếu:
    • https://www.figma.com/design/tBBrdtHlG1LAYJUfJsvyS3/UCALL-2026–Ant-Design-5.10.1-?node-id=4-154796&m=dev
  • Lưu ý: Hình dưới đây chỉ mang tính minh họa để diễn giải bố cục, 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 bố cục Flow Builder

  • Màn hình builder gồm ba vùng chính:
    • Header: tên flow, breadcrumb, trạng thái lưu, hành động lưu/xuất bản/lịch sử.
    • Canvas: hiển thị trigger node, action node và các mối nối giữa chúng.
    • Panel phải: hiển thị chi tiết node đang chọn theo tab.
  • Trên canvas, mỗi node hiển thị tối thiểu:
    • Icon nhóm node.
    • Tên node.
    • Mô tả ngắn hoặc tham số chính.
  • Panel phải cần giữ thống nhất cấu trúc tab giữa các node để người dùng dễ học và dễ chuyển đổi.

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

  • Tính nhất quán: Builder phải dùng cách gọi, bố cục tab và quy tắc trạng thái đồng nhất giữa các loại node.
  • Hiệu năng: Thao tác chọn node, mở panel cấu hình và lưu nháp cần phản hồi nhanh để không làm gián đoạn quá trình thiết kế flow.
  • Khả năng truy vết: Mọi thay đổi quan trọng như lưu, xuất bản, tạm dừng flow cần có cơ chế audit hoặc activity log ở mức phù hợp.
  • An toàn vận hành: Flow chưa hợp lệ không được phép tham gia chạy thực tế. Việc cập nhật flow đang active phải tách bạch giữa bản nháp và bản đã xuất bản.

IV. Dependency (liên quan & phụ thuộc)

V. API Contract (dev viết)

  • File này chưa chốt API contract chi tiết.
  • Khi triển khai kỹ thuật, cần bổ sung tối thiểu:
    • API tạo/sửa/lưu flow.
    • API publish / pause flow.
    • API lấy catalog node.
    • API test node hoặc test flow.

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

  • TC1 (Happy Path): Tạo flow mới -> Chọn trigger -> Thêm action node -> Lưu -> Header hiển thị Đã lưu.
  • TC2 (Happy Path): Chọn một node bất kỳ trên canvas -> Panel phải mở đúng cấu hình của node đó.
  • TC3 (Happy Path): Cấu hình đầy đủ flow hợp lệ -> Bấm Xuất bản -> Flow chuyển trạng thái active.
  • TC4 (Exception): Bỏ trống field bắt buộc của node -> Bấm Xuất bản -> Hệ thống chặn và highlight node lỗi.
  • TC5 (Business Rule): Flow đang active -> User sửa một node -> Hệ thống hiển thị cảnh báo Có thay đổi chưa được xuất bản.
  • TC6 (UI): Chọn nhiều node khác nhau liên tiếp -> Panel phải đổi đúng tab và nội dung tương ứng.