AdaFlow - Chi tiết một lần chạy Flow

I. Tổng quan

Tài liệu này mô tả màn hình chi tiết của một lần chạy flow. Mục tiêu là cho phép người dùng truy vết từ trigger khởi phát cho tới từng node đã thực thi trong run đó.

1. Vấn đề

  • Khi flow thất bại, màn báo cáo tổng quan chỉ cho biết run nào lỗi nhưng không cho biết lỗi ở node nào, input gì dẫn đến lỗi và output nào đã được tạo trước đó.
  • Dev, QA và người vận hành cần một nơi để xem đầy đủ hành trình của một lần chạy mà không phải suy luận ngược từ log thô.

2. Giải pháp

  • Cung cấp màn Flow Run Detail cho từng execution cụ thể.
  • Hiển thị thông tin tổng quan của run, trigger khởi phát và danh sách node đã thực thi.
  • Cho phép xem input, output, trạng thái và lỗi ở từng node.

3. Đối tượng

  • Người vận hành cần kiểm tra flow lỗi.
  • QA kiểm tra kết quả test flow.
  • Dev phân tích lỗi hoặc đối chiếu logic node.

4. Tầm nhìn/insight

  • Có thể mở rộng thêm replay, retry, export log hoặc so sánh hai lần chạy trong tương lai.

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

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

  • Xem metadata chung của một run.
  • Xem trigger khởi phát.
  • Xem timeline thực thi từng node.
  • Xem input và output của từng node.
  • Xem lỗi và trạng thái kết thúc của từng bước.

2. Đặc tả chi tiết

User story 1: Là một [Người vận hành], tôi muốn [xem chi tiết một lần chạy flow] để [biết chính xác node nào đã thành công và node nào đã thất bại].

  • Use case 1.1 (Mở chi tiết run): User từ report click vào một run -> Hệ thống mở chi tiết run -> Phần đầu màn hình hiển thị tên flow, ID run, trigger, trạng thái tổng và thời gian bắt đầu/kết thúc.

  • Use case 1.2 (Xem trạng thái từng node): User cuộn xuống phần timeline thực thi -> Hệ thống hiển thị danh sách node theo đúng thứ tự đã chạy -> Mỗi node có trạng thái riêng như success, failed, skipped.

User story 2: Là một [Dev hoặc QA], tôi muốn [xem input/output của từng node] để [đối chiếu dữ liệu thực thi với logic đã cấu hình trên builder].

  • Use case 2.1 (Xem input của node): User mở chi tiết một node trong run -> Hệ thống hiển thị dữ liệu đầu vào mà node nhận được tại thời điểm thực thi.

  • Use case 2.2 (Xem lỗi của node): Node thực thi thất bại -> User mở chi tiết node -> Hệ thống hiển thị thông điệp lỗi, thời điểm lỗi và thông tin cần thiết để truy vết.

3. Danh sách nghiệp vụ

  • Mỗi run detail phải gắn với đúng một run duy nhất.
  • Trigger khởi phát phải được hiển thị như điểm bắt đầu của timeline.
  • Các node trong run detail phải được sắp theo thứ tự thực thi thực tế, không chỉ theo vị trí trên builder.
  • Một node có thể có các trạng thái thực thi như:
    • success
    • failed
    • skipped
  • Nếu node lỗi, run tổng có thể failed hoặc stopped tùy cơ chế thực thi của flow.
  • Với node chưa chạy do bước trước lỗi hoặc do điều kiện không thỏa, hệ thống phải thể hiện rõ đây là node skipped thay vì coi là thành công.
  • Input/output của node chỉ là dữ liệu phục vụ truy vết và không được phép chỉnh sửa từ màn detail.

4. Giao diện

  • Trong phạm vi hiện tại, màn chi tiết cần có tối thiểu:
    • Khối thông tin chung của run.
    • Khối trigger khởi phát.
    • Timeline hoặc danh sách từng node đã thực thi.
    • Khu vực xem input, output và lỗi của node được chọn.
  • Layout cụ thể sẽ được chốt thêm khi có Figma chi tiết cho report/detail.

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

  • Khả năng truy vết: Dữ liệu input/output/error phải đủ để đối chiếu với logic đã cấu hình trong builder.
  • Tính nhất quán: Thông tin ở run detail phải khớp với trạng thái và metadata đã hiển thị ở run report.
  • Bảo mật: Chỉ người có quyền xem flow hoặc quyền xem log vận hành mới được truy cập run detail.

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

V. API Contract (dev viết)

  • Chưa định nghĩa API chi tiết.
  • Khi triển khai cần tối thiểu có API:
    • Lấy metadata chung của một run.
    • Lấy timeline node execution.
    • Lấy input/output/error theo từng node trong run.

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

  • TC1 (Happy Path): Từ run report mở một run thành công -> Xem được trigger và danh sách node đều có trạng thái phù hợp.
  • TC2 (Happy Path): Mở một node trong run -> Hiển thị được input và output của node đó.
  • TC3 (Exception): Mở một run lỗi -> Hiển thị rõ node lỗi, thời điểm lỗi và thông điệp lỗi.
  • TC4 (Business Rule): Có node chưa chạy do bước trước thất bại -> Node hiển thị trạng thái skipped.