App Builder - Quy trình khởi tạo ứng dụng và quản lý trang trên App Studio

Hướng dẫn 3 phương án khởi tạo ứng dụng trên App Builder, kết nối nguồn dữ liệu API và quản lý trang trong App Studio.

Mở khu vực Danh sách App và Trình xem App Studio

Để bắt đầu khởi tạo ứng dụng thu nhỏ (MiniApp / Dashboard), ghép trang từ kho mẫu và quản lý cấu trúc trang trên App Builder, bạn truy cập vào một trong các đường dẫn sau trên thanh điều hướng bên trái của hệ thống RedAI:

Danh sách App (/app-builder): Hiển thị toàn bộ các ứng dụng trong không gian làm việc (Workspace) hiện tại. Trên thanh công cụ phía trên cùng bao gồm:
- Ô tìm kiếm (Tìm kiếm App theo tên hoặc ID…).
- Nút (Tạo App) để mở hộp thoại khởi tạo ứng dụng mới.
- Nút (Làm mới) và nút (Lọc theo Thẻ).
- Các nút điều hướng và tiện ích mở rộng: (Mẫu Template App Builder), (App của hệ thống), (Quản lý Môi trường Workspace (Environments)), (Quản lý tên miền Workspace), (Import App từ file ZIP) và (Quản lý Thẻ App).
Trình xem App / App Studio (/app-builder/:appId): Nhấp trực tiếp vào một thẻ ứng dụng bất kỳ trên danh sách để mở không gian làm việc của ứng dụng đó. Thanh tiêu đề phía trên cùng của trình xem được bố trí như sau:
- Cụm điều khiển bên trái:
  - Nút (Quản Lý Trang): Mở hộp thoại quản lý danh sách trang của ứng dụng.
  - Tên App: Bạn có thể nhấp đúp chuột (double-click) trực tiếp vào tên ứng dụng trên thanh tiêu đề để đổi tên nhanh tại chỗ (nhấn phím Enter để lưu hoặc Escape để hủy).
- Cụm 11 nút công cụ bên phải:
  - (Nguồn dữ liệu & APIs): Mở ngăn chọn và gắn công cụ API (Custom Tools / Dynamic Tables) vào ứng dụng.
  - (Thư viện App): Mở hộp thoại Thư viện App & Trang Mẫu để áp dụng nguyên gói mẫu hoặc ghép từng trang lẻ vào ứng dụng đang mở.
  - (Tải Lại): Làm mới lại khung hiển thị ứng dụng.
  - (Thống kê): Xem nhanh số liệu thống kê của ứng dụng.
  - (Lịch sử phiên bản): Xem và quản lý các bản phát hành của ứng dụng.
  - (Cấu hình Theme): Mở trình chỉnh sửa bảng màu và giao diện.
  - (Cấu hình AI Agent đọc dữ liệu App): Mở cấu hình Agent Semantic View.
  - (Liên kết chia sẻ): Mở hộp thoại quản lý đường dẫn chia sẻ và mã QR.
  - (Toàn màn hình) / (Thoát toàn màn hình): Mở rộng khung xem ứng dụng ngay trong tab hiện tại.
  - (Mở tab xem toàn màn hình (Live Realtime)): Mở trang /app-builder/:appId/preview ở một tab trình duyệt mới kèm nút bong bóng điều khiển nổi RedAI.
  - (Cài đặt): Chuyển sang trang cài đặt toàn diện của ứng dụng (/app-builder/:appId/settings).
- Nút tự động hỗ trợ khi gặp lỗi hiển thị: Nếu mã nguồn trang gặp sự cố trong lúc chạy (Runtime Error), góc dưới bên phải khung xem sẽ tự động xuất hiện nút nổi màu đỏ (Sửa lỗi với AI) để bạn gửi toàn bộ ngữ cảnh lỗi cho trợ lý AI khắc phục ngay lập tức.

Các bước thực hiện

Chọn phương án khởi tạo ứng dụng phù hợp

Trước khi bắt đầu ở Giai đoạn 1, hãy chọn phương án khởi tạo phù hợp với nhu cầu của bạn:

Phương án khởi tạo	Khi nào nên sử dụng	Kết quả nhận được
Phương án 1 — Tạo App mới từ đầu	Khi bạn muốn tạo một không gian ứng dụng trống để tự thiết kế hoặc nhờ trợ lý ảo AI Agent lập trình giao diện theo yêu cầu riêng.	Một ứng dụng mới được khởi tạo ngay lập tức với tên và mô tả bạn đã nhập.
Phương án 2 — Sử dụng mẫu từ Kho Template	Khi bạn muốn nhân bản nhanh một ứng dụng mẫu hoàn chỉnh có sẵn trên hệ thống hoặc chỉ lấy một vài trang lẻ từ mẫu ghép vào ứng dụng đang có.	Tạo ra một ứng dụng độc lập có đầy đủ trang và giao diện mẫu, hoặc thêm các trang đã chọn vào ứng dụng đích.
Phương án 3 — Import App từ file ZIP	Khi bạn có sẵn gói mã nguồn VFS định dạng `.zip` (tối đa 50MB) được xuất ra từ một ứng dụng hoặc môi trường RedAI khác.	Hệ thống tự động kiểm tra cấu trúc VFS, giải nén toàn bộ các trang, thành phần giao diện và tạo thành ứng dụng mới.

Giai đoạn 1 — Khởi tạo ứng dụng mới

Phương án 1 — Tạo App mới từ đầu

Bước	Cách thực hiện
1. Mở hộp thoại Tạo App mới	Tại màn hình Danh sách App (`/app-builder`), bấm vào nút (Tạo App) trên thanh công cụ phía trên.
2. Nhập thông tin cơ bản	Trong hộp thoại Tạo App mới, điền 2 trường thông tin: • Tên App : Nhập tên ứng dụng của bạn (ví dụ: `RedAI E-Commerce App...`). • Mô tả ngắn*: Nhập mô tả mục đích và chức năng của ứng dụng.
3. Xác nhận khởi tạo	Bấm nút (Tạo) ở góc dưới bên phải hộp thoại (hoặc bấm (Hủy) nếu muốn đóng lại).

Phương án 2 — Sử dụng mẫu từ Kho Template hoặc ghép trang lẻ

Bước	Cách thực hiện
1. Mở Kho Mẫu Template	Tại màn hình Danh sách App (`/app-builder`), bấm nút (Mẫu Template App Builder) trên thanh công cụ để chuyển sang trang `/app-builder/templates`.
2. Xem trước mẫu đa thiết bị (Tùy chọn)	Trên thẻ của mẫu muốn kiểm tra, bấm nút (Xem trước). Trong hộp thoại xem trước: • Chuyển đổi kích thước khung nhìn bằng 3 nút: (Máy tính), (Máy tính bảng) (`768 × 1024`), (Điện thoại) (`390 × 844`). • Chuyển đổi các trang trong mẫu tại mục Trang: hoặc bấm (Tải lại). • Bấm nút (Chọn) ở góc dưới bên phải để chuyển sang hộp thoại tải mẫu.
3. Chọn chế độ tải mẫu	Khi bấm (Tải mẫu) trên thẻ Template (hoặc bấm Chọn từ cửa sổ xem trước), hộp thoại hiển thị 2 tab: • Nếu muốn tạo thành một ứng dụng mới hoàn chỉnh: Giữ nguyên ở tab (Tải về (Tạo App mới)) rồi bấm nút (Tải về tạo App mới) ở góc dưới bên phải. • Nếu chỉ muốn lấy một số trang ghép vào ứng dụng đang có: Chuyển sang tab (Tải lẻ các trang vào 1 App), chọn ứng dụng đích tại mục 1. Chọn MiniApp đích muốn ghép trang:, tích chọn các trang muốn lấy tại mục 2. Chọn các trang mẫu cần thêm (X/Y): (có thể dùng nút (Chọn tất cả các trang)), sau đó bấm nút (Thêm {số lượng} trang vào App).

Phương án 3 — Import App từ file ZIP (Dành cho Không gian Hệ thống)

Bước	Cách thực hiện
1. Mở hộp thoại Import ZIP	Tại màn hình Danh sách App (`/app-builder`), bấm nút (Import App từ file ZIP) trên thanh công cụ.
2. Tải lên và kiểm tra cấu trúc gói	Kéo thả tệp `.zip` (tối đa 50MB) vào vùng (Kéo thả file .zip vào đây hoặc click để chọn). Hệ thống sẽ tự động phân tích và hiển thị bảng thông tin gồm: Tên App phát hiện, Số trang (Pages), Components và Các đường dẫn (Routes).
3. Đặt tên ghi đè và bắt đầu Import	Bạn có thể nhập tên mới vào ô Tên App ghi đè (Tùy chọn) (nếu để trống, hệ thống sẽ lấy theo tên gốc trong tệp `app.json` của gói ZIP). Sau đó bấm nút (Bắt đầu Import) và bấm (Mở App ngay) sau khi hoàn tất.

Giai đoạn 2 — Kết nối Nguồn dữ liệu & APIs cho ứng dụng

Để ứng dụng hiển thị và thao tác với dữ liệu thực tế từ Bảng dữ liệu động (Dynamic Tables) hoặc các dịch vụ bên ngoài, bạn cần gắn các công cụ API (Custom Tools) vào ứng dụng:

Bước	Cách thực hiện
1. Mở ngăn Nguồn dữ liệu & APIs	Tại màn hình Trình xem App (`/app-builder/:appId`), bấm nút (Nguồn dữ liệu & APIs) trên thanh tiêu đề phía trên (hoặc vào Cài đặt → mục (Nguồn dữ liệu & APIs) → bấm (Gắn thêm API)).
2. Tìm và lọc công cụ API	Trong cửa sổ Nguồn dữ liệu & APIs: • Chọn tab nguồn công cụ: (Cá nhân) hoặc (Hệ thống). • Sử dụng ô tìm kiếm (Tìm kiếm công cụ…) hoặc bấm các nút lọc nhanh theo phương thức HTTP: (GET), (POST), (PUT), (PATCH), (DELETE).
3. Chọn nhóm Project Schema và từng API	Nhấp vào từng nhóm dự án công cụ ( Project Schema) để mở rộng danh sách các hàm API bên trong. Tích chọn từng công cụ () cần cấp quyền cho ứng dụng hoặc bấm (Chọn cả nhóm) để chọn toàn bộ API của bảng dữ liệu đó.
4. Lưu danh sách API liên kết	Kiểm tra số lượng tại dòng Đã chọn: {số lượng} API, sau đó bấm nút (Lưu) ở góc dưới bên phải cửa sổ.

Giai đoạn 3 — Quản lý trang, ghép trang từ Thư viện App và kiểm thử giao diện

Bước	Cách thực hiện
1. Quản lý danh sách trang hiện có	Trên thanh tiêu đề bên trái của Trình xem App, bấm nút (Quản Lý Trang). Tại đây bạn có thể: • Nhấp trực tiếp vào một dòng trang bất kỳ để chuyển khung nhìn sang trang đó. • Bấm vào biểu tượng (Thao tác) ở cuối dòng trang để thực hiện 1 trong 3 hành động: 1. (Cập nhật thông tin trang): Sửa Tên trang và Mô tả trang, sau đó bấm (Lưu). 2. (Nhân bản sang APP khác): Chọn một ứng dụng đích trong Workspace để sao chép trang này sang. 3. (Xóa trang): Xóa trang khỏi ứng dụng hiện tại.
2. Ghép thêm trang mẫu hoặc áp dụng gói mẫu ngay trong App	Bấm nút (Thư viện App) trên thanh tiêu đề để mở hộp thoại Thư viện App & Trang Mẫu: • Tab (Gói App Mẫu): Bấm (Xem trước) hoặc bấm (Áp dụng gói) để ghi đè toàn bộ ứng dụng hiện tại bằng gói mẫu. • Tab (Từng Trang Lẻ): Tìm trang lẻ cần dùng, bấm (Xem trước trang) hoặc bấm (Ghép vào App) để chèn trang đó vào ứng dụng đang mở.
3. Xem trước độc lập và điều khiển bằng Nút bong bóng nổi RedAI	Bấm nút (Mở tab xem toàn màn hình (Live Realtime)) trên thanh tiêu đề để mở trang `/app-builder/:appId/preview`. Trên màn hình này có Nút bong bóng nổi RedAI (có thể kéo thả tự do). Khi nhấp vào nút bong bóng, bạn có 4 công cụ điều khiển nhanh: • (AI Agent): Mở ngăn trò chuyện `ChatPanel` ngay bên phải màn hình để ra lệnh cho AI chỉnh sửa giao diện trực tiếp. • (Tải Lại): Tải lại hệ thống tệp ảo VFS của ứng dụng. • / (Đổi giao diện (Sáng/Tối)): Kiểm tra giao diện ứng dụng ở cả hai chế độ Light Mode và Dark Mode. • (App Studio): Quay trở về màn hình quản lý `/app-builder/:appId`.

Kiểm tra kết quả

Sau khi hoàn tất các giai đoạn trên, bạn kiểm tra lại ứng dụng theo các tiêu chí sau:

Tại màn hình Danh sách App (/app-builder): Thẻ ứng dụng mới xuất hiện trên lưới danh sách với đúng Tên App, Mô tả ngắn và hiển thị tổng số lượng trang ở góc dưới bên trái ( {N} Trang).
Tại hộp thoại Quản Lý Trang: Tất cả các trang trong ứng dụng hiển thị đầy đủ đường dẫn (routePath), số lượng API liên kết ({N} APIs) và số lượng thành phần ({N} components).
Tại màn hình Xem trước (/app-builder/:appId/preview): Các trang chuyển hướng mượt mà, dữ liệu từ API hiển thị chính xác trên bảng/biểu đồ, giao diện tương thích tốt khi bấm nút đổi chế độ Sáng / Tối và không xuất hiện nút báo lỗi đỏ (Sửa lỗi với AI).

Hướng dẫn thao tác qua trợ lý ảo AI Agent

Toàn bộ quy trình từ khởi tạo ứng dụng, gắn bảng dữ liệu/API cho đến lập trình giao diện đa trang trên hệ thống tệp ảo (VFS) và kiểm thử tự động đều có thể giao cho trợ lý ảo AI Agent thực hiện hoàn toàn.

Chuẩn bị kỹ năng (Skill) cho trợ lý ảo AI Agent

Trước khi ra lệnh, hãy đảm bảo trợ lý ảo AI Agent của bạn đã được gắn kỹ năng sau:

Kỹ năng (Skill) cần trang bị: RedAI - Module - App Builder (ID: 58f36f44-2e1c-4aaf-8ca7-d73008169e95)
Bộ công cụ (Tool) đi kèm trong kỹ năng: RedAI - Module - App Builder (ID: d16e4656-c070-43b6-b234-abcff883fd61)
Quyền hạn tài khoản: Tài khoản người dùng trong Workspace có quyền tạo và chỉnh sửa MiniApp.

Bảng liên kết thao tác giao diện và công cụ của trợ lý ảo AI Agent

Thao tác trên giao diện	Công cụ trợ lý ảo AI Agent sử dụng	Nhiệm vụ của công cụ
Bấm (Tạo App) và điền Tên App, Mô tả ngắn	`app_createApp`	Khởi tạo một ứng dụng MiniApp mới trong Workspace và trả về `appId`.
Mở (Mẫu Template App Builder) và bấm (Tải mẫu)	`app_useTemplate`	Nhân bản ứng dụng mới hoặc ghép trang từ một mẫu Template có sẵn.
Tra cứu thư viện được phép sử dụng trong mã nguồn VFS	`appCatalog_getLibraries`	Lấy danh sách các thư viện chuẩn (React, Lucide, ECharts, Shadcn UI…) được hỗ trợ trên trình xem.
Mở (Nguồn dữ liệu & APIs) để tìm và gắn API vào ứng dụng	`listProjectSchemas`, `listCustomTools`, `getCustomToolDetail`, `executeResource_execute`	Tìm kiếm nhóm Project Schema, liệt kê Custom Tools, đọc cấu trúc đầu vào/đầu ra và chạy thử API lấy dữ liệu mẫu thật.
Kiểm tra cấu trúc tệp và các trang trong (Quản Lý Trang)	`agentAppVfs_tree`, `agentAppVfs_summary`, `agentAppVfs_search`, `agentAppVfs_read`	Duyệt cây thư mục ảo VFS (`/app.json`, `/apis.json`, `/pages/...`, `/components/...`) và đọc nội dung từng tệp.
Tạo mới, chỉnh sửa hoặc xóa trang và thành phần giao diện	`agentAppVfs_create`, `agentAppVfs_write`, `agentAppVfs_edit`, `agentAppVfs_delete`	Tạo tệp mới, ghi đè nội dung, chỉnh sửa từng đoạn mã nguồn hoặc xóa tệp trong hệ thống VFS của ứng dụng.
Bấm (Sửa lỗi với AI) hoặc kiểm tra lỗi biên dịch & hiển thị	`pageValidation_validateJsx`, `pageValidation_diagnose`, `pageValidation_getConsoleLogs`, `pageValidation_traceNetwork`	Kiểm tra cú pháp JSX/TSX, chẩn đoán lỗi runtime, đọc nhật ký Console và kiểm tra các lệnh gọi mạng trên trang.

Câu lệnh mẫu (Prompt mẫu)

Bạn có thể sao chép mẫu câu lệnh dưới đây, thay đổi tên ứng dụng và yêu cầu nghiệp vụ của mình rồi gửi cho trợ lý ảo AI Agent:

Hãy giúp tôi khởi tạo và xây dựng một ứng dụng MiniApp mới trên App Builder theo quy trình sau: 1. Bối cảnh và Mục tiêu: - Tôi cần xây dựng ứng dụng quản lý và theo dõi số liệu vận hành theo chuẩn giao diện phẳng (Flat & Borderless), hỗ trợ cả 2 chế độ Sáng (Light Mode) và Tối (Dark Mode). 2. Dữ liệu cung cấp: - Tên App: "Bảng Điều Khiển Vận Hành Kinh Doanh" - Mô tả ngắn: "Ứng dụng theo dõi KPI doanh thu, danh sách đơn hàng và biểu đồ tăng trưởng thời gian thực." - Nguồn dữ liệu: Hãy tìm trong danh sách Project Schemas và Custom Tools của tôi các API liên quan đến đơn hàng và sản phẩm để gắn vào /apis.json của ứng dụng. 3. Các bước yêu cầu thực hiện: - Bước 1: Dùng công cụ app_createApp để tạo ứng dụng mới với tên và mô tả trên. - Bước 2: Dùng listProjectSchemas, listCustomTools và executeResource_execute để kiểm tra dữ liệu thực tế từ API, sau đó đăng ký các API cần thiết vào tệp /apis.json. - Bước 3: Thiết kế thanh điều hướng dùng chung (/components/SharedNavbar.tsx) và các trang chính trong /pages/ sử dụng dữ liệu thật 100% từ API. - Bước 4: Dùng pageValidation_validateJsx và pageValidation_diagnose để kiểm tra toàn bộ các trang, đảm bảo không có lỗi cú pháp hay lỗi runtime. 4. Yêu cầu phản hồi: - Báo cáo lại ID ứng dụng (appId), danh sách các đường dẫn trang (routePath) đã tạo, danh sách API đã kết nối và kết quả kiểm tra cú pháp/hiển thị của từng trang.

Kiểm tra kết quả sau khi ra lệnh cho trợ lý ảo AI Agent

Sau khi trợ lý ảo AI Agent thông báo đã hoàn thành, bạn có thể kiểm tra lại theo 2 cách:

Cách kiểm tra	Thao tác thực hiện
Cách 1 — Kiểm tra trực tiếp trên giao diện	Truy cập `/app-builder`, nhấp vào thẻ ứng dụng Bảng Điều Khiển Vận Hành Kinh Doanh vừa được tạo, bấm (Quản Lý Trang) để xem danh sách các trang và bấm (Mở tab xem toàn màn hình (Live Realtime)) để trải nghiệm trực tiếp.
Cách 2 — Yêu cầu trợ lý ảo AI Agent chụp ảnh và kiểm chứng	Gửi câu lệnh: “Hãy dùng công cụ `pageValidation_captureScreenshot` và `pageValidation_diagnose` kiểm tra tất cả các trang của ứng dụng vừa tạo và gửi báo cáo cho tôi.”