API reference

Database schema

Quan hệ giữa các bảng

Bảng roles - chi tiết

Field	Type	Mô tả
name	uid (PK)	ID duy nhất, prefix r_
title	string (unique)	Tên hiển thị, hỗ trợ i18n
description	string	Mô tả role
strategy	json	Strategy mặc định, ví dụ { actions: ['view', 'create'] }
default	boolean	Nếu true, user mới tự động nhận role này
hidden	boolean	Ẩn khỏi danh sách role trên UI
allowConfigure	boolean	Cho phép truy cập trang cấu hình
allowNewMenu	boolean	Cho phép tạo menu page mới
snippets	set<string>	Danh sách snippet (ví dụ ['ui.*', 'pm', 'pm.*'])
menuUiSchemas	belongsToMany	UI schema menu mà role được phép truy cập
resources	hasMany	→ dataSourcesRolesResources
users	belongsToMany	→ users qua rolesUsers

Strategy field

{
  "actions": ["create", "view", "update", "destroy"]
}

Hoặc với scope:

{
  "actions": ["view:own", "update:own", "create", "destroy:own"]
}

view:own = chỉ xem bản ghi do mình tạo.

usingActionsConfig - hai chế độ permission

Giá trị	Ý nghĩa
false	Collection dùng strategy mặc định của role
true	Collection có cấu hình action riêng (rows trong dataSourcesRolesResourcesActions)

Custom API endpoints

availableActions:list

Trả về danh sách action mà hệ thống hỗ trợ phân quyền.

GET /api/availableActions:list

Response:

[
  { "name": "create", "displayName": "Create", "allowConfigureFields": true },
  { "name": "view", "displayName": "View", "allowConfigureFields": true },
  { "name": "update", "displayName": "Update", "allowConfigureFields": true },
  { "name": "destroy", "displayName": "Delete", "allowConfigureFields": false },
  { "name": "export", "displayName": "Export", "allowConfigureFields": true }
]

roles.collections:list

Danh sách collection cho một role, kèm trạng thái cấu hình.

GET /api/roles/{roleName}/collections:list?page=1&pageSize=20

Response mỗi item:

{
  "name": "orders",
  "title": "Đơn hàng",
  "usingConfig": "strategy",
  "exists": false
}

Field	Ý nghĩa
usingConfig	"strategy" = dùng strategy mặc định, "resourceAction" = có cấu hình riêng
exists	true nếu đã có row trong dataSourcesRolesResources cho role này

roles:check

Kiểm tra quyền hiệu lực của user hiện tại. Dùng cho client để quyết định hiển thị UI.

GET /api/roles:check

Response:

{
  "role": "member",
  "roles": ["member"],
  "roleMode": "default",
  "availableActions": ["create", "view", "update", "destroy", "export"],
  "actionAlias": { "get": "view", "list": "view" },
  "allowAll": false,
  "allowConfigure": false,
  "allowMenuItemIds": ["uid1", "uid2"],
  "anonymous": false,
  "resources": {
    "orders": {
      "view": { "fields": ["id", "title", "status"], "filter": {} },
      "create": { "fields": ["title", "status"] }
    }
  },
  "uiButtonSchemasBlacklist": ["uid3"]
}

roles:setSystemRoleMode

Đặt chế độ role hệ thống.

POST /api/roles:setSystemRoleMode
Body: { "roleMode": "default" | "allow-use-union" | "only-use-union" }

Mode	Ý nghĩa
default	User sử dụng một role tại một thời điểm
allow-use-union	User có thể chọn "tất cả role" (union)
only-use-union	Luôn dùng union tất cả role

users:setDefaultRole

Đổi role mặc định cho user hiện tại.

POST /api/users:setDefaultRole
Body: { "roleName": "admin" }

roleName có thể là __union__ (khi roleMode cho phép) để dùng union role.

Không thể set anonymous.

Ví dụ sử dụng API

Tạo role mới

const response = await agent.resource('roles').create({
  values: {
    name: 'editor',
    title: 'Biên tập viên',
    strategy: {
      actions: ['view', 'create'],
    },
  },
});
// response.statusCode === 200

Cấu hình permission riêng cho collection

// Gán permissions cho collection "posts" trên role "editor"
await agent.resource('roles.resources', 'editor').create({
  values: {
    name: 'posts',
    usingActionsConfig: true,
    actions: [
      { name: 'create' },
      { name: 'view', fields: ['title', 'content'] },
      { name: 'update', fields: ['title', 'content'] },
    ],
  },
});

// Kiểm tra lại - danh sách collections của role
const listResp = await agent.resource('roles.collections', 'editor').list({
  filter: { name: 'posts' },
});
// listResp.body.data[0].usingConfig === 'resourceAction'

Tạo scope và gán vào action

// Tạo scope "published posts"
const { body: { data: scope } } = await agent
  .resource('dataSourcesRolesResourcesScopes')
  .create({
    values: {
      resourceName: 'posts',
      name: 'published posts',
      scope: { published: true },
    },
  });

// Gán scope vào action view
await agent.resource('roles.resources', 'editor').create({
  values: {
    name: 'posts',
    usingActionsConfig: true,
    actions: [
      { name: 'view', fields: ['title'], scope: scope.id },
      { name: 'create' },
    ],
  },
});

Kiểm tra quyền hiệu lực

const checkResp = await agent.resource('roles').check();
const { actions } = checkResp.body.data;

// actions là map dạng { 'posts:create': {...}, 'posts:view': {...} }
console.log(actions['posts:create']); // defined → có quyền
console.log(actions['posts:destroy']); // undefined → không có quyền

Lấy ACL meta cho danh sách (client dùng ẩn/hiện nút)

const response = await agent
  .set('X-With-ACL-Meta', true)
  .resource('posts')
  .list({});

const { data, meta } = response.body;
// meta.allowedActions.view = [1, 2, 3]    → row IDs được phép xem
// meta.allowedActions.update = [1, 2]      → row IDs được phép sửa
// meta.allowedActions.destroy = [1]        → row IDs được phép xóa

Luồng dữ liệu: UI → DB → ACL

Standard CRUD endpoints

Ngoài custom endpoints ở trên, plugin sử dụng framework CRUD tiêu chuẩn:

Resource	Actions	Mô tả
roles	list, get, create, update, destroy	Quản lý role
roles.resources	list, get, create, update	Permission per collection per role
roles.snippets	list, add, remove	Snippet assignment
roles.menuUiSchemas	list, set, toggle	Menu access per role
roles.users	list, add, remove	User-role assignment

Fixed params - bảo vệ hệ thống

Plugin đăng ký fixed params ngăn xóa/sửa dữ liệu hệ thống:

Resource	Action	Filter	Ý nghĩa
roles	destroy	name != root, admin, member	Không xóa role hệ thống
rolesResourcesScopes	destroy, update	key != all, own	Không sửa/xóa scope mặc định
collections	destroy	name != roles, rolesUsers	Không xóa collection ACL

Exports

Module server/index.ts export thêm middleware và model để plugin khác tái sử dụng:

Export	Mô tả
setCurrentRole	Middleware gắn role vào request
withACLMeta	Middleware bổ sung ACL meta vào response
applyQueryPermission	Áp dụng query filter theo quyền
RoleModel	Model class cho roles
RoleResourceModel	Model class cho resources
RoleResourceActionModel	Model class cho actions
UNION_ROLE_KEY	Constant '__union__'
SystemRoleMode	Enum default, allow-use-union, only-use-union