Giao diện

API Reference ​

Tổng quan ​

Plugin-users cung cấp resource users với CRUD chuẩn và 5 custom action. Tất cả endpoint tuân theo convention của framework: resourceName:actionName.

CRUD chuẩn — resource users ​

users:list ​

Lấy danh sách user. Yêu cầu quyền admin (ACL snippet pm.users).

Request:

http
GET /api/users:list?page=1&pageSize=20

Response: Danh sách user đã qua desensitize() — không chứa password và resetToken.

users:get ​

Lấy chi tiết một user.

http
GET /api/users:get?filterByTargetKey=1

users:create ​

Tạo user mới. Admin only.

http
POST /api/users:create
Content-Type: application/json

{
  "displayname": "Nguyen Van A",
  "username": "nguyenvana",
  "email": "a@example.com",
  "phone": "0901234567",
  "password": "SecureP@ss1"
}

Các field unique: username, email, phone — nếu trùng sẽ báo lỗi validation.

users:update ​

Cập nhật thông tin user. Admin only.

http
POST /api/users:update?filterByTargetKey=2
Content-Type: application/json

{
  "displayname": "Nguyen Van B",
  "email": "b@example.com"
}

Lưu ý password

Khi cập nhật password, server tự động:

  • Ghi passwordChangeTz = timestamp hiện tại
  • Xóa cache roles và auth → buộc user đăng nhập lại

users:destroy ​

Xóa user. Admin only.

http
POST /api/users:destroy?filterByTargetKey=5

Ràng buộc ACL: User có id = 1 (root) không thể bị xóa. Server tự động inject filter id.$ne: 1 vào mọi request destroy.

Custom actions ​

users:updateProfile ​

Cho phép user đã đăng nhập tự cập nhật profile cá nhân. Đây là action quan trọng nhất cho end-user.

Quyền: loggedIn (bất kỳ user đã đăng nhập)

http
POST /api/users:updateProfile
Content-Type: application/json

{
  "displayname": "Tên mới",
  "username": "newusername",
  "email": "new@example.com",
  "phone": "0909876543"
}

Luồng xử lý chi tiết:

Bảo mật:

  • Field được phép sửa được derive từ UI schema, không phải từ request. User không thể tự thêm field ngoài schema
  • Các field x-read-pretty hoặc x-disabled trong schema bị loại ra
  • Field roles không nằm trong user profile edit schema → user không thể tự gán role
  • Server remap updateProfile thành update trong middleware để kích hoạt workflow

Error:

HTTP StatusĐiều kiện
401Chưa đăng nhập
403enableEditProfile = false
Validation ErrorRequired field bị thiếu giá trị

users:updateLang ​

Đổi ngôn ngữ giao diện cho user hiện tại.

Quyền: loggedIn

http
POST /api/users:updateLang
Content-Type: application/json

{
  "appLang": "vi-VN"
}

Chỉ cập nhật field appLang của user hiện tại. Trả về 401 nếu chưa đăng nhập.

users:listExcludeRole ​

Lấy danh sách user chưa được gán một role cụ thể. Dùng trong giao diện gán user vào role.

Quyền: Admin (ACL snippet pm.users)

http
GET /api/users:listExcludeRole?roleName=editor&page=1&pageSize=20

Response:

json
{
  "count": 15,
  "rows": [...],
  "page": 1,
  "pageSize": 20,
  "totalPage": 1
}

Logic: Trước tiên tìm tất cả user đã có role đó, sau đó query lại users với filter id.$notIn để loại ra.

users:getSystemSettings ​

Lấy cấu hình hệ thống liên quan đến user.

Quyền: Admin

http
GET /api/users:getSystemSettings

Response:

json
{
  "enableEditProfile": true,
  "enableChangePassword": true
}

users:updateSystemSettings ​

Cập nhật cấu hình hệ thống.

Quyền: Admin

http
POST /api/users:updateSystemSettings
Content-Type: application/json

{
  "enableEditProfile": false,
  "enableChangePassword": true
}

Có thể gửi một hoặc cả hai field. Nếu không gửi field nào → 400 Bad Request.

Filter operators ​

Plugin đăng ký 3 operator đặc biệt dùng được trong mọi filter query:

$isCurrentUser ​

Lọc record theo user hiện tại đang đăng nhập.

json
{
  "filter": {
    "createdById": { "$isCurrentUser": true }
  }
}

Chuyển thành: createdById = ctx.state.currentUser.id. Nếu chưa đăng nhập, so sánh với -1 (không match bất kỳ user nào).

$isNotCurrentUser ​

Ngược lại của $isCurrentUser — lọc record không thuộc user hiện tại.

json
{
  "filter": {
    "assigneeId": { "$isNotCurrentUser": true }
  }
}

$isVar ​

So sánh field với biến động từ ctx.state. Giá trị được parse dưới dạng template.

json
{
  "filter": {
    "departmentId": { "$isVar": "currentUser.departmentId" }
  }
}

Middleware ​

Xóa cache khi role thay đổi ​

Khi thực hiện roles.users:add, roles.users:remove, hoặc roles.users:set, server phát event cache:del:roles cho từng userId bị ảnh hưởng. Đảm bảo permission được cập nhật ngay lập tức.

Remap updateProfile cho workflow ​

Middleware chuyển actionName từ updateProfile thành update trước khi xử lý. Điều này cho phép workflow (plugin-workflow) lắng nghe event users:update và bắt được cả hành động updateProfile.

Audit logging ​

Action users:updateProfile được đăng ký với auditManager:

  • MetaData: Toàn bộ request body, nhưng password được thay bằng ******
  • Target: targetCollection: 'users', targetRecordUK: currentUser.id