Cài đặt và sử dụng — Public Forms

Tổng quan

@digiforce-nc/plugin-public-forms cho phép tạo form thu thập dữ liệu mà người điền không cần đăng nhập. Plugin sinh JWT token tạm thời (hết hạn 1 giờ) để xác thực submission, chuyển đổi action publicSubmit thành create để tương thích với workflow trigger.

Bước 1: Kích hoạt Plugin

Vào Settings → Plugin Manager, tìm plugin-public-forms và bật.

Sau khi kích hoạt:

• Route /public-forms/:name được đăng ký (skipAuthCheck)
• Mục Public forms xuất hiện trong Plugin Settings
• Bảng publicForms được tạo trong Database

Bước 2: Tạo Public Form

1. Vào Settings → Public forms
2. Nhấn Create để tạo form mới

Trường	Kiểu	Mô tả
key	uid (tự sinh)	Khóa duy nhất, dùng trong URL
title	string	Tiêu đề form hiển thị
type	string	Loại form (mặc định: form)
collection	string	Collection đích (định dạng: dataSource:collectionName)
description	string	Mô tả form
enabled	boolean	Bật/tắt form
password	string	Mật khẩu bảo vệ (tùy chọn, để trống = không cần)

3. Cấu hình UI Schema cho form — chọn các field cần hiển thị

Bước 3: Chia sẻ link

Sau khi tạo, link form có dạng:

https://your-domain.com/public-forms/<key>

Gửi link này cho người cần điền form. Họ có thể truy cập trực tiếp mà không cần tài khoản.

Luồng hoạt động chi tiết

1. Truy cập form (getMeta)

Khi người dùng mở link, client gọi publicForms:getMeta:

2. JWT Token

Token chứa:

• collectionName: Collection đích
• formKey: Khóa form
• targetCollections: Danh sách Collection liên quan (association appends)

Token hết hạn sau 1 giờ. Sau đó, người dùng cần tải lại trang để lấy token mới.

3. Submit dữ liệu

Client gửi request với header X-Form-Token:

POST /api/<collection>:publicSubmit
X-Form-Token: <jwt-token>
Content-Type: application/json

{
  "name": "Nguyễn Văn A",
  "email": "user@example.com",
  "message": "Nội dung liên hệ"
}

Plugin middleware:

1. Verify JWT token từ header X-Form-Token
2. Kiểm tra form còn enabled
3. Chuyển publicSubmit → create (kích hoạt workflow)
4. Bỏ qua auth check (ctx.skipAuthCheck = true)
5. Bỏ qua ACL check cho Collection đích và target Collections

4. ACL và quyền truy cập

Plugin tự động skip ACL check cho các trường hợp:

• create trên Collection đích của form
• list, get trên target Collections (association)
• create trên Collection file (upload)
• getBasicInfo, createPresignedUrl trên storages
• check trên vditor
• get trên map-configuration

Bảo vệ form bằng mật khẩu

Nếu đặt password cho form:

1. Lần đầu truy cập, API trả về { passwordRequired: true }
2. Client hiển thị form nhập mật khẩu
3. Người dùng nhập mật khẩu → gọi lại getMeta với password
4. Nếu đúng → trả về schema + token
5. Nếu sai → 401 "Please enter your password"

Lưu ý: Password được lưu dưới dạng template string — hỗ trợ biến môi trường qua renderJsonTemplate().

Form type mở rộng

Plugin hỗ trợ đăng ký nhiều loại form qua API client:

const publicForms = app.pm.get('public-forms') as PluginPublicFormsClient;

publicForms.registerFormType('survey', {
  label: 'Khảo sát',
  uiSchema: (options) => {
    return {
      // Custom UI Schema cho form khảo sát
    };
  },
});

Lưu ý quan trọng

• Dữ liệu gửi từ public form lưu trực tiếp vào Collection — cẩn thận với field nào hiển thị ra ngoài
• publicSubmit được chuyển thành create → kích hoạt workflow như bản ghi tạo thông thường
• Token hết hạn sau 1 giờ — form mở lâu cần tải lại trang
• Nên giới hạn các field hiển thị, không expose field nội bộ
• Nên kết hợp với CAPTCHA hoặc rate limiting nếu form public trên internet