Giao diện

Hướng dẫn cài đặt và sử dụng — Departments ​

Yêu cầu ​

Thành phầnYêu cầu
Server DigiforcePhiên bản >= 1.0
Plugin phụ thuộcplugin-users, plugin-acl, plugin-error-handler

Bước 1: Kích hoạt plugin ​

  1. Truy cập Settings → Plugin Manager
  2. Tìm plugin-departments
  3. Bật công tắc Enable
  4. Khởi động lại server nếu hệ thống yêu cầu

Khi cài đặt lần đầu, plugin tự động:

  • Tạo bảng departments, departmentsUsers, departmentsRoles
  • Thêm trường departments và mainDepartment vào collection users
  • Bảo vệ các collection hệ thống (không cho phép xóa)

Bước 2: Tạo cấu trúc phòng ban ​

Vào Settings → Departments để bắt đầu xây dựng cơ cấu tổ chức.

Tạo phòng ban gốc ​

  1. Nhấn Add department
  2. Nhập tên phòng ban (ví dụ: "Ban Giám đốc")
  3. Lưu lại

Tạo phòng ban con ​

  1. Chọn phòng ban cha trong cây phòng ban
  2. Nhấn Add sub-department
  3. Nhập tên phòng ban con (ví dụ: "Phòng Kinh doanh")

Plugin sử dụng cấu trúc adjacency-list tree — mỗi phòng ban có parentId trỏ đến phòng ban cha. Không có giới hạn số cấp.

Sắp xếp phòng ban ​

Kéo thả phòng ban trong cây để thay đổi thứ tự hiển thị. Plugin hỗ trợ sortable — mỗi phòng ban có trường sort để duy trì thứ tự.

Bước 3: Gán nhân viên vào phòng ban ​

  1. Chọn phòng ban trong cây phòng ban
  2. Nhấn Add members
  3. Chọn users từ danh sách (hỗ trợ tìm kiếm theo tên, email, số điện thoại)
  4. Xác nhận thêm

Quy tắc gán ​

Quy tắcMô tả
Nhiều phòng banMột user có thể thuộc nhiều phòng ban (quan hệ M2M)
Phòng ban chínhMỗi user có một mainDepartment — phòng ban chính
ValidationPhòng ban chính phải nằm trong danh sách phòng ban của user

Lưu ý

Khi đặt mainDepartmentId cho user, phòng ban đó phải nằm trong danh sách phòng ban của user. Nếu không, hệ thống sẽ báo lỗi "Invalid main department, it must be one of the user's departments".

Bước 4: Chỉ định trưởng phòng (Owner) ​

  1. Chọn phòng ban
  2. Trong danh sách thành viên, nhấn Set as owner cho user cần chỉ định
  3. Một phòng ban có thể có nhiều owner

Owners có thuộc tính isOwner: true trong bảng liên kết departmentsUsers. Trưởng phòng có thể được sử dụng trong phân quyền ACL để cấp quyền quản lý đặc biệt.

Bước 5: Gán Role cho phòng ban ​

Mỗi phòng ban có thể được liên kết với một hoặc nhiều Role (vai trò). Khi user được gán vào phòng ban, họ tự động nhận các role của phòng ban đó.

TrườngMô tả
departments.rolesQuan hệ M2M qua bảng departmentsRoles
departmentIdID phòng ban
roleNameTên role

Plugin cung cấp action aggregateSearch cho phép tìm kiếm đồng thời cả user và phòng ban:

  • Tìm user theo: username, displayname, phone, email
  • Tìm phòng ban theo: title
  • Hỗ trợ phân trang qua last (cursor) và limit

Kết hợp với ACL ​

Phòng ban có thể được sử dụng làm điều kiện phân quyền:

  • Data scope: Giới hạn user chỉ xem dữ liệu thuộc phòng ban của mình
  • Role assignment: Gán role tự động theo phòng ban
  • Plugin đăng ký middleware setDepartmentsInfo chạy sau auth và trước setCurrentRole — đưa thông tin phòng ban vào context cho ACL sử dụng

Cache ​

Plugin sử dụng cache để tối ưu hiệu năng truy vấn phòng ban:

  • Cache key: departments:{userId}
  • Cache tự động bị xóa khi:
    • Thay đổi danh sách phòng ban của user (departmentsUsers.afterSave, afterDestroy)
    • User đăng xuất (beforeSignOut)

Lưu ý triển khai ​

  • Xóa phòng ban sẽ cascade xóa tất cả phòng ban con (do onDelete: CASCADE)
  • Xóa phòng ban không xóa users, chỉ xóa liên kết trong departmentsUsers
  • Plugin kiểm tra trước khi xóa: nếu phòng ban có phòng ban con, cần xóa phòng ban con trước
  • Trường isLeaf tự động cập nhật khi thêm/xóa phòng ban con — phục vụ hiển thị cây
  • Plugin hỗ trợ Data Sync qua DepartmentDataSyncResource (nếu plugin user-data-sync được bật)