AdaFlow - Template Node

I. Tổng quan

File này là template meta để viết tài liệu cho từng node trong AdaFlow. Mục tiêu là giúp các file node vẫn giữ đúng khung chung của thư mục dev, nhưng đủ chỗ để mô tả đặc thù như input, output, tab cấu hình và validation.

1. Vấn đề

  • Nếu viết node theo cùng template của một tính năng lớn mà không điều chỉnh, tài liệu node dễ thiếu các phần quan trọng như dữ liệu đầu ra, cấu hình theo tab hoặc rule test node.
  • Nếu mỗi người tự chọn một format khác nhau cho node, các file node sẽ khó so sánh, khó review và khó mở rộng thành catalog lớn.

2. Giải pháp

  • Giữ khung section chuẩn của thư mục dev:
    • I. Tổng quan
    • II. Yêu cầu chức năng
    • III. Yêu cầu phi chức năng
    • IV. Dependency
    • V. API Contract
    • VI. Test case
  • Trong phần II. Yêu cầu chức năng, chuẩn hóa thêm các trường đặc thù cho node:
    • Loại node / nhóm node.
    • Input.
    • Output.
    • Các tab cấu hình.
    • Validation và lỗi thường gặp.

3. Đối tượng

  • BA, PO, Dev, QA khi tạo mới tài liệu cho một node.
  • Người review tài liệu node cần một chuẩn để đối chiếu tính đầy đủ.

4. Tầm nhìn/insight

  • Khi số lượng node tăng lớn, template này sẽ giúp node docs đồng nhất và có thể được dùng như checklist chất lượng tài liệu.

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

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

  • Chuẩn hóa cấu trúc tài liệu node.
  • Giảm lặp lại và thiếu sót khi viết node mới.
  • Giữ liên kết với node_overview.md để không phải lặp lại phần định nghĩa chung.

2. Đặc tả chi tiết

  • Một file node nên dùng template dưới đây:

Ví dụ hình dưới đây chỉ mang tính minh họa cho panel cấu hình node, 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

Ví dụ panel cấu hình node

# [Tên node]

## I. Tổng quan
*Mô tả ngắn gọn node này dùng để làm gì.*

**1. Vấn đề**
- Nêu pain point hoặc nhu cầu nghiệp vụ mà node này giải quyết.

**2. Giải pháp**
- Mô tả node xử lý vấn đề như thế nào.

**3. Đối tượng**
- Ai là người cấu hình node này.

**4. Tầm nhìn/insight**
- Hướng mở rộng sau này nếu có.

---

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

**1. Danh sách tính năng**
- Loại node: `Trigger` hoặc `Action`.
- Nhóm node: `CRM`, `Omnichannel`, `Logic`, `Integration`...
- Danh sách operation hoặc mode hoạt động nếu node có nhiều lựa chọn.

**2. Đặc tả chi tiết**
- Input node nhận từ đâu.
- Tab `Hành động` hiển thị gì.
- Tab `Cài đặt` có field nào.
- Tab `Kiểm thử` dùng để làm gì.
- Tab `Đầu ra` trả ra dữ liệu nào.
- Use case happy path và exception path khi cấu hình node.

**3. Danh sách nghiệp vụ**
- Rule validate.
- Rule dữ liệu bắt buộc.
- Rule khi node lỗi.
- Rule output cho node tiếp theo.

**4. Giao diện**
- Link Figma hoặc mô tả card node và panel cấu hình.

---

## III. Yêu cầu phi chức năng
- Hiệu năng, khả năng kiểm thử, giới hạn dữ liệu, logging nếu có.

---

## IV. Dependency
- Flow builder.
- Module nghiệp vụ liên quan.
- Tích hợp ngoài nếu có.

---

## V. API Contract (Dev viết)
- Chỉ mô tả API khi đã có thiết kế kỹ thuật.

---

## VI. Test case (BA hoặc tester viết)
- Happy path.
- Validation path.
- Edge cases.

3. Danh sách nghiệp vụ

  • Không lặp lại định nghĩa chung của trigger node, action node, input, output; các phần đó kế thừa từ node_overview.md.
  • Node nào có nhiều operation trong cùng một file thì phải mô tả rõ operation nào dùng chung cấu hình, operation nào có field riêng.
  • Node ví dụ viết đầy đủ phải có ít nhất một luồng thành công và một luồng ngoại lệ.

4. Giao diện

  • Nếu node có Figma rõ ràng, phải tham chiếu link Figma trong file node.
  • Nếu node không có frame riêng trong Figma page hiện tại, cần mô tả theo pattern panel chung của builder.

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

  • Tính nhất quán: Mọi file node dùng cùng template này để giảm chênh lệch chất lượng tài liệu.
  • Khả năng mở rộng: Template phải áp dụng được cho node đơn giản và node nhiều operation.
  • Khả năng review: Reviewer có thể dùng template như checklist để xác định file node có thiếu phần nào hay không.

IV. Dependency

V. API Contract (Dev viết)

  • File này không có API contract riêng.
  • Phần API chỉ xuất hiện trong tài liệu node cụ thể khi cần.

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

  • TC1: Dùng template này để viết node mới -> Có đủ chỗ cho input, output, tab cấu hình và validation.
  • TC2: So sánh hai file node khác nhau -> Có cùng cấu trúc section để dễ review.