Giao diện
@digiforce-nc/plugin-users
Plugin quản lý người dùng — định nghĩa collection users, cung cấp API quản lý tài khoản, profile, và tích hợp sâu với ACL và auth.
Plugin này làm gì?
plugin-users là sổ danh bạ của hệ thống. Nó quản lý thông tin user (tên, email, phone, mật khẩu), cho phép admin tạo/sửa/xóa user, user tự cập nhật profile, và tự động gắn createdBy/updatedBy vào mọi bản ghi trong hệ thống.
Ba nhiệm vụ chính
| # | Nhiệm vụ | Chi tiết |
|---|---|---|
| 1 | Collection users | Định nghĩa bảng users với UserModel, hỗ trợ desensitize (ẩn field nhạy cảm) |
| 2 | API quản lý | CRUD users (admin), updateProfile, updateLang, listExcludeRole, system settings |
| 3 | Tự động hóa | Gắn createdBy/updatedBy vào collection khác, invalidate cache khi role thay đổi |
Kiến trúc
Tổng quan
| Thành phần | Vai trò |
|---|---|
| UserModel | Model class cho users, có desensitize() để ẩn field nhạy cảm (password...) khi trả về client |
| Custom actions | 5 action đặc biệt ngoài CRUD chuẩn |
| Auto-inject fields | Tự thêm createdBy/updatedBy vào collection có interface tương ứng |
Luồng updateProfile
Bảo mật
updateProfile chỉ cho phép sửa field được định nghĩa trong UI schema profile form. User không thể tự sửa roles, password (dùng changePassword), hay field hệ thống.
API endpoints
CRUD chuẩn
| Endpoint | Mô tả |
|---|---|
users:list | Danh sách user (admin) |
users:get | Chi tiết user |
users:create | Tạo user mới |
users:update | Cập nhật user |
users:destroy | Xóa user (không xóa được user id=1) |
Custom actions
| Endpoint | Ai dùng | Mô tả |
|---|---|---|
users:updateProfile | User đăng nhập | Cập nhật profile cá nhân (chỉ field được phép) |
users:updateLang | User đăng nhập | Đổi ngôn ngữ giao diện |
users:listExcludeRole | Admin | Danh sách user chưa có role cụ thể (dùng khi gán role) |
users:getSystemSettings | Admin | Lấy cấu hình profile/password |
users:updateSystemSettings | Admin | Cập nhật cấu hình profile/password |
Database
Bảng users
| Field | Type | Mô tả |
|---|---|---|
id | bigInt (PK) | ID user |
displayname | string | Tên hiển thị |
username | string (unique) | Tên đăng nhập |
email | string (unique) | |
phone | string (unique) | Số điện thoại |
password | password (hidden) | Mật khẩu (bcrypt hash, ẩn khỏi API) |
appLang | string | Ngôn ngữ giao diện |
passwordChangeTz | string | Thời điểm đổi password gần nhất |
resetToken | string | Token reset password |
systemSettings | json | Cài đặt cá nhân |
System settings (extended)
Plugin mở rộng bảng systemSettings thêm 2 flag:
| Field | Mô tả |
|---|---|
enableEditProfile | Cho phép user tự sửa profile |
enableChangePassword | Cho phép user tự đổi mật khẩu |
Tự động gắn createdBy / updatedBy
Khi collection nào có createdBy: true hoặc updatedBy: true (hoặc dùng interface tương ứng), plugin tự động thêm field liên kết đến users:
typescript
// Ví dụ collection orders có createdBy
{
name: 'orders',
createdBy: true,
updatedBy: true,
fields: [
{ name: 'title', type: 'string' },
// createdBy, updatedBy được tự động thêm bởi plugin-users
]
}Khi tạo/sửa record, hệ thống tự gán createdById / updatedById = user hiện tại.
DB operators
Plugin đăng ký các operator đặc biệt cho filter:
| Operator | Mô tả | Ví dụ |
|---|---|---|
$isCurrentUser | Record thuộc user hiện tại | { createdById: { $isCurrentUser: true } } |
$isNotCurrentUser | Record không thuộc user hiện tại | { createdById: { $isNotCurrentUser: true } } |
$isVar | So sánh với biến hệ thống | Filter động |
Thành phần client
| Thành phần | Mô tả |
|---|---|
| UsersManagement | Trang quản lý users (Settings → Users & Permissions → Users) |
| RoleUsersManager | Tab gán user vào role (trong trang Roles & Permissions) |
| PreferencesUserCenter | Menu user: đổi ngôn ngữ, đổi role, sửa profile |
| UpdateProfilePreference | Form sửa profile cá nhân |
| PasswordPreference | Form đổi mật khẩu |
| LanguagePreference | Đổi ngôn ngữ |
| RolePreference | Đổi role mặc định |
| SignOut | Nút đăng xuất |
Dependencies
| Package | Vai trò |
|---|---|
@digiforce-nc/plugin-acl | Snippets, role cache, fixed params bảo vệ user root |
@digiforce-nc/plugin-auth | Xác thực user, cache auth |
@digiforce-nc/plugin-system-settings | Lưu cấu hình profile/password |
@digiforce-nc/plugin-ui-schema-storage | UI schema cho profile form |
@digiforce-nc/plugin-user-data-sync | Tùy chọn: đồng bộ user từ nguồn bên ngoài |
@digiforce-nc/server | Server framework |
@digiforce-nc/database | Database ORM |
@digiforce-nc/client | Client framework |
Mục lục chi tiết
- Kiến trúc — UserModel, operators, auto fields, extension
- API Reference — CRUD, custom actions, filter operators, system settings
- Database Schema — ER diagram, bảng users, systemSettings
- FAQ — Câu hỏi thường gặp về quản lý người dùng