Quick start

Điều kiện

• App Digiforce đã cài plugin auth (middleware auth phải chạy trước setCurrentRole).
• Plugin users đã cài (plugin-acl phụ thuộc bảng users, rolesUsers).
• Database đã migrate (bảng roles, dataSourcesRolesResources, ... đã tồn tại).

Sau khi cài mới

Khi plugin users được cài lần đầu, plugin-acl tự động:

1. Tạo role mặc định

Role	Mô tả	Strategy	Snippet
root	Superuser, ẩn khỏi UI	- (bypass tất cả)	ui.*, pm, pm.*
admin	Quản trị viên	create, view, update, destroy	ui.*, pm, pm.*
member	Thành viên (mặc định cho user mới)	view:own	!ui.*, !pm, !pm.*

2. Tạo scope mặc định

Scope key	Tên	Filter
all	Tất cả bản ghi	(không filter)
own	Bản ghi của mình	{ createdById: '{{ ctx.state.currentUser.id }}' }

3. Gán role cho user đầu tiên

User đầu tiên nhận cả 3 role (root, admin, member), với root là role mặc định.

User tạo sau đó tự động nhận role có default: true (thường là member).

Cấu hình quyền đầu tiên

Bước chi tiết

1. Đăng nhập bằng user có snippet pm.acl.roles (thường admin hoặc root).
2. Mở Settings → Roles & Permissions.
3. Chọn role cần cấu hình (ví dụ member).
4. Tab System - cấu hình snippet (quyền truy cập UI, plugin settings).
5. Tab Permissions - danh sách collection hiện ra:
   • Chọn collection → bật/tắt từng action (view, create, update, destroy, export...).
   • Với mỗi action, chọn scope (all = tất cả, own = chỉ bản ghi của mình, custom).
   • Tùy chọn fields - giới hạn field được xem/sửa.
6. Lưu - thay đổi được persist vào DB và đồng bộ vào ACL engine ngay lập tức.
7. Kiểm tra - đăng nhập bằng user thuộc role đó, gọi API và xác nhận 200 / 403.

Developer: đồng bộ thủ công

Trong code server, có thể gọi trực tiếp:

const aclPlugin = app.pm.get('acl');

// Đồng bộ một role
await aclPlugin.writeRoleToACL(roleModel, { transaction });

// Đồng bộ toàn bộ roles (sau migrate dữ liệu)
await aclPlugin.writeRolesToACL({});

WARNING

Chỉ dùng khi hiểu rõ transaction context và vòng hook DB. Trong hầu hết trường hợp, hooks tự động đồng bộ khi lưu qua UI/API.

Kiểm tra nhanh quyền

// Trong action handler
const can = ctx.app.acl.can({
  role: ctx.state.currentRole,
  resource: 'orders',
  action: 'update',
});

if (!can) {
  ctx.throw(403, 'No permission');
}

Hoặc dùng API roles:check - trả về toàn bộ quyền hiệu lực của user hiện tại (xem API reference).