Giao diện
@digiforce-nc/plugin-action-custom-request
Plugin cho phép gửi HTTP request tùy chỉnh từ giao diện - admin cấu hình URL/method/headers/body với template variables, user kích hoạt từ nút action trên bảng hoặc form.
Plugin này làm gì?
Hãy hình dung bạn cần tích hợp với hệ thống bên ngoài: gửi webhook khi duyệt đơn, đồng bộ dữ liệu sang CRM, hay gọi API thanh toán. Thay vì viết code, admin chỉ cần cấu hình request template (URL, method, headers, body) với biến động như currentRecord, currentUser. Khi user nhấn nút, server resolve template rồi gửi HTTP request đến hệ thống đích.
Ba nhiệm vụ chính
| # | Nhiệm vụ | Chi tiết |
|---|---|---|
| 1 | Lưu trữ cấu hình | Collection customRequests lưu URL, method, headers, body trong DB |
| 2 | Resolve & gửi request | Server thay thế biến template bằng giá trị thực (record, user, form) rồi gửi HTTP request qua axios |
| 3 | Phân quyền theo role | Mỗi request gán cho role cụ thể qua bảng junction customRequestsRoles |
Kiến trúc
Tổng quan
Plugin có cả server (resource, actions, DB) và client (UI cấu hình, nút action). Server xử lý logic resolve template và gửi request thực tế.
| Tầng | Vai trò | Thành phần |
|---|---|---|
| Client UI | Cấu hình request + nút action | CustomRequestConfigForm, CustomRequestAction |
| Server Resource | CRUD cấu hình, resolve & send | customRequests resource + actions |
| Database | Lưu trữ bền vững | customRequests, customRequestsRoles |
| Logger | Ghi log request đã gửi | File logger trên server |
API endpoints
| Endpoint | Method | Mô tả |
|---|---|---|
customRequests:send | POST | Resolve template và gửi HTTP request đến URL đích |
customRequests:listByCurrentRole | GET | Lấy danh sách request mà role hiện tại được phép dùng |
customRequests:create | POST | Tạo cấu hình request mới (admin) |
customRequests:update | PUT | Sửa cấu hình request (admin) |
customRequests:destroy | DELETE | Xóa cấu hình request (admin) |
customRequests:list | GET | Liệt kê tất cả cấu hình (admin) |
ACL - Phân quyền
| Quyền | Loại | Mô tả |
|---|---|---|
ui.* | Snippet | ACL snippet cho phép truy cập UI customRequests:* |
customRequests:send | Action | Cho phép user đã đăng nhập gửi request |
customRequests:listByCurrentRole | Action | Cho phép user đã đăng nhập lấy danh sách |
customRequests CRUD | Resource | Chỉ admin quản trị cấu hình |
Database
Bảng customRequests
| Cột | Kiểu | Mô tả |
|---|---|---|
key | string | Khóa định danh duy nhất cho request |
options | JSON | Cấu hình request: url, method, headers, body, params |
roles | belongsToMany | Danh sách role được phép sử dụng (qua customRequestsRoles) |
Bảng customRequestsRoles (junction)
| Cột | Kiểu | Mô tả |
|---|---|---|
customRequestKey | string | FK → customRequests.key |
roleName | string | FK → roles.name |
Template variables
Trong options (url, headers, body), admin sử dụng cú pháp mustache để chèn biến động. Server resolve các biến này trước khi gửi request:
| Biến | Mô tả |
|---|---|
currentRecord.* | Dữ liệu bản ghi hiện tại (VD: currentRecord.id) |
currentUser.* | Thông tin user đang thao tác (VD: currentUser.email) |
$nForm.* | Dữ liệu từ form hiện tại (nếu action trên form) |
Luồng hoạt động
Bảo mật
- Proto path guard: Server kiểm tra URL đích không trỏ về internal service
- File logger: Mọi request gửi đi đều được ghi log
- Role-based: Chỉ role được gán mới thấy và dùng được request
Thành phần client
| Thành phần | Mô tả |
|---|---|
CustomRequestAction | Component nút action gửi request trên row/form |
CustomRequestInitializer | Đăng ký action vào schema initializer |
CustomRequestConfigForm | Form cấu hình request trong designer (url, method, headers, body) |
CustomRequestActionWidget | Widget nút action trong uiCore |
CustomRequestPluginProvider | Provider đăng ký toàn bộ component vào plugin system |
Dependencies
| Package | Vai trò |
|---|---|
@digiforce-nc/client | Client framework (peer) |
@digiforce-nc/server | Server framework (peer) |
@digiforce-nc/database | Database ORM (peer) |