AdaFlow - Data Mapping (Cấu hình tương thích dữ liệu)

I. Tổng quan

Tài liệu này quy định các nguyên tắc tương thích khi “map” (gán/binding) dữ liệu từ biến (variable) hoặc output của một node (Source) vào ô input của một node tiếp theo (Target).

1. Vấn đề

  • Trong quá trình cấu hình thiết lập Flow, người dùng thường xuyên có thao tác lấy kết quả của Action A đẩy vào đầu vào của Action B.
  • Nếu không thiết lập một bảng quy tắc ranh giới về kiểu dữ liệu (kiểu nào có thể nhận, kiểu nào không thể map), hệ thống có nguy cơ lỗi runtime, hoặc người dùng đẩy dữ liệu rác/mảng sai lệch vào Database của hệ thống, dẫn đến crash ứng dụng.

2. Giải pháp

  • Xây dựng Ma trận tương thích Data Mapping giữa các kiểu dữ liệu Đầu ra (Source) so với Ô đích (Target).
  • Thiết lập quy tắc chuyển đổi (Type Casting), tự nhận diện và trích xuất thông tin thông minh (như nhận Email text để tìm ID User tương ứng, tách tài khoản từ mảng lấy phần tử đầu).

3. Đối tượng

  • BA thiết kế logic và thiết kế giao diện lúc người dùng gán tham số.
  • Dev thiết lập validation ở bước execution engine (khi Flow chạy).
  • QA sử dụng làm căn cứ viết Test Case.

4. Tầm nhìn/insight

  • Thiết kế một cấu hình Data Binding tự nhiên nhất có thể: hạn chế phải tạo các node trung gian trung chuyển (Format data node), ưu tiên để hệ thống tự parse và ép kiểu, chỉ báo lỗi rành mạch lịch sử khi dữ liệu thực sự lệch.

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

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

  • Hiển thị UI gợi ý biến: UI chọn biến chỉ highlight sáng các biến tương thích với ô Input đang chọn, làm mờ các biến cấm.
  • Runtime Validator: Kiểm tra xem biến truyền trong lúc chạy có đúng định dạng đích nếu nó có rủi ro (VD: Gõ Text báo lỗi Email).
  • Object & Array Smart Extract: Cơ chế mặc định xử lý Mảng nhiều phần tử nhét vào ô Một phần tử.

2. Đặc tả chi tiết (Ma trận Data Mapping)

Ghi chú bảng: Cột Nguồn (hàng ngang ngoài cùng) thể hiện dữ liệu cung cấp. Cột Đích (tiêu đề dọc) thể hiện cấu hình field tiếp nhận. x là tương thích. Ô trống là bị cấm map.

Loại dữ liệu nguồn \ Đích Nhập chữ Đoạn văn Văn bản định dạng Email Số điện thoại Địa chỉ URL Số nguyên Số thập phân Phần trăm Ngày Ngày & Giờ Thời lượng Chọn một Chọn nhiều Một tài khoản Nhiều tài khoản Đối tượng
Nhập chữ x x x x (báo lỗi khi sai) x x (báo lỗi khi sai) x (báo lỗi khi sai) x (báo lỗi khi sai)         x x x (ID user) x (ID user) x (ID object)
Đoạn văn x x x x (báo lỗi khi sai) x x (báo lỗi khi sai) x (báo lỗi khi sai) x (báo lỗi khi sai)         x x x (ID user) x (ID user) x (ID object)
Văn bản định dạng x x x                   x x      
Email x x x x                     x (Email user) x (Email user)  
Số điện thoại x x x   x                        
Địa chỉ URL x x x     x                      
Số nguyên x x x   x (báo lỗi)   x x x x x x          
Số thập phân x x x   x (báo lỗi)   x x x x x x          
Phần trăm x x x       x x x                
Ngày x x x       x x   x x (mặc định 00:00)            
Ngày & Giờ x x x       x x   x (bỏ giờ) x            
Thời lượng x x x       x x x     x          
Chọn một x x x                   x x      
Chọn nhiều x x x                   x (lấy first) x      
Một tài khoản x x x                       x x  
Nhiều tài khoản x x x                       x (lấy first) x  
Đối tượng x (ID object) x (ID object) x (ID object)                           x

3. Danh sách nghiệp vụ (Quy tắc mapping)

3.1. Ép kiểu Validation (Chuỗi String)

  • Nhập chữ, Đoạn văn -> Map vào Email, Số điện thoại, URL, Số nguyên, Số thập phân: Hệ thống đồng ý lưu bước cài đặt, nhưng ở Runtime khi thực hiện (Execute), hệ thống sẽ check định dạng. Rule: Báo lỗi flow fail ở cụm node đó nếu chuỗi truyền vào không thể parser/cast được thành dữ liệu mong muốn.
  • Văn bản có định dạng (Rich text) chỉ được phép truyền nội dung vào field của nhóm Văn bản hoặc Chọn một/Chọn nhiều. Cấm gài vào các thông số hẹp như Email/SĐT tránh làm sập logic backend và sai dữ liệu hiển thị.

3.2. Ép kiểu Ngày tháng / Thời gian

  • Ngày -> Map Ngày & Giờ: Bổ sung thành 00:00:00 phút mặc định.
  • Ngày & Giờ -> Map Ngày: Cắt bỏ toàn bộ dữ liệu giờ, để lại YYYY-MM-DD.
  • Cấu trúc Thời gian sang Hệ số (Số nguyên / Số thập phân): Implicit cast sang [Unix Time] (Ví dụ: 1702930239).

3.3. Xử lý tập hợp (Arrays) xuống phần tử lẻ (Scalar)

  • Mapping biến chứa mảng Chọn nhiều (nhiều Label) nhét vào field Chọn một: Hệ thống tự động trích lọc, chỉ lấy phần tử đầu tiên (first element) ở index số [0].
  • Mảng Nhiều tài khoản vào field đích Một tài khoản: Tương tự, bắt luôn User ID ở vị trí [0].

3.4. Ánh xạ Đối tượng (Smart Search)

  • Móc thuộc tính [Email lưu text] vào ô field của [Một/Nhiều Tài khoản]: Flow engine lấy đoạn email text đó lôi ra từ hệ thống ID của User có email tương ứng.
  • Đưa [Nhập chữ] hay Text vào ô Tài khoản / Đối tượng: Hệ thống sẽ tự hiểu nội dung text đó là ID của Tài khoản / ID của Đối tượng.
  • Chuyển Một tài khoản / Đối tượng ra thành Cột Nhập chữ / Đoạn văn: Map ra chuỗi String ghi nhận “ID User” / “ID Object” để log lịch sử ghi nhận.

4. Giao diện

  • Giao diện Binding Biến ở Popup / Panel Configuration ở Flow Builder:
    • Tại một ô Target (ví dụ Ô nhập Email), khi mở sổ sách Dropdown (List Variable / Data pill), các biến từ node phía trước có kiểu định dạng bị cấm truyền (blank trong ma trận) sẽ không show ra, hoặc hiện ở trạng thái Disabled mờ nhạt ghi chú (Forbidden format).

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

  • Bắt lỗi nhẹ nhàng (Graceful Failure): Thay vì ứng dụng bị văng Error 500, khi mapping lỗi Runtime do dữ liệu sai thì ghi nhận vào Log Node fail (tham chiếu Flow Report) chi tiết field nào mapping sai.
  • Tốc độ Validation (Performance): Thao tác engine check Regex đối với map từ TEXT sang INT/EMAIL trên hệ lượng message khủng khiếp phải không chiếm dụng Memory lớn. Tham khảo cơ chế tối ưu cho engine script chạy nền.

IV. Dependency

  • node_overview.md
  • Phụ thuộc Flow runtime Execution Module & Giao diện Flow Builder Frontend kéo thả.

V. API Contract (Dev viết)

  • Không có module Backend API riêng lẻ trong file này. Chức năng ép kiểu được nhúng chung vào Flow Engine Core Controller hoặc thư viện DataValidation của node runner.

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

ID Kịch bản Test Dữ liệu khởi tạo Kết quả mong đợi (Expected)
TC-MAP-01 Kiểm thử String hợp lệ sang Email Map “Nhập chữ” -> Ô “Email”. Chạy thực tế biến chứa “[email protected]” Flow chạy thành công với node email.
TC-MAP-02 Kiểm thử String cấm vào Email Map “Nhập chữ” -> Ô “Email”. Chạy thực tế biến chứa “hello nha” Log lỗi báo Failed “Sai định dạng email”. Node đó dừng thực thi.
TC-MAP-03 Kiểm thử Array to Single Element Nhét “Nhiều tài khoản” (list ["US_1", "US_2"]) vào list “Một tài khoản” Cập nhật được dữ liệu thành công chỉ áp dụng cho người dùng US_1.
TC-MAP-04 Map Ngày giờ về Ngày Lấy Date Time: “2026-12-10 15:30:00” gán vào ô “Ngày” form Excel/DB Trích xuất thành công format ngày 2026-12-10.
TC-MAP-05 Disable Caching thả biến Kéo viên thuốc (data pill) là biến “Văn bản định dạng” tính thả vào cấu hình “Ví URL Webhook” Giao diện xuất hiện “chặn đỏ” cấm thả (No-drop mode on).