Tham chiếu API — Departments

Resources

Lấy cây phòng ban

await agent.resource('departments').list({
  tree: true,
  appends: ['members', 'owners', 'roles', 'parent'],
});

Tạo phòng ban

await agent.resource('departments').create({
  values: {
    title: 'Phòng Kỹ thuật',
    parentId: parentDeptId,  // null cho phòng ban gốc
  },
});

Cập nhật phòng ban

await agent.resource('departments').update({
  filterByTk: deptId,
  values: {
    title: 'Phòng Công nghệ',
  },
});

Xóa phòng ban

await agent.resource('departments').destroy({
  filterByTk: deptId,
});

WARNING

Xóa phòng ban sẽ cascade xóa tất cả phòng ban con. Middleware destroyDepartmentCheck kiểm tra trước khi xóa.

Quản lý thành viên

Thêm thành viên

await agent.resource('departments.members', deptId).add({
  values: [userId1, userId2],
});

Xóa thành viên

await agent.resource('departments.members', deptId).remove({
  values: [userId1],
});

Danh sách user không thuộc phòng ban

await agent.resource('users').listExcludeDept({
  values: { departmentId: deptId },
});

Quản lý Owner (Trưởng phòng)

Đặt làm trưởng phòng

await agent.resource('departments').setOwner({
  values: {
    userId: userId,
    departmentId: deptId,
  },
});

Thao tác này cập nhật isOwner: true trong bảng departmentsUsers.

Gỡ quyền trưởng phòng

await agent.resource('departments').removeOwner({
  values: {
    userId: userId,
    departmentId: deptId,
  },
});

Tìm kiếm tổng hợp

await agent.resource('departments').aggregateSearch({
  values: {
    keyword: 'Nguyễn',
    type: 'user',    // 'user', 'department', hoặc bỏ trống để tìm cả hai
    last: 0,         // cursor cho phân trang
    limit: 10,       // số kết quả tối đa
  },
});

Kết quả trả về:

{
  "users": [
    { "id": 1, "username": "nguyenvana", "displayname": "Nguyễn Văn A", ... }
  ],
  "departments": [
    { "id": 10, "title": "Phòng Nguyễn Trãi", "parent": { ... } }
  ]
}

Department Object

Trường	Kiểu	Mô tả
id	snowflakeId	ID duy nhất (tạo tự động)
title	string	Tên phòng ban
parentId	bigint	ID phòng ban cha (null nếu là gốc)
isLeaf	boolean	true nếu không có phòng ban con
sort	integer	Thứ tự sắp xếp
children	hasMany	Danh sách phòng ban con
parent	belongsTo	Phòng ban cha
members	belongsToMany	Thành viên (qua departmentsUsers)
owners	belongsToMany	Trưởng phòng (qua departmentsUsers với isOwner: true)
roles	belongsToMany	Vai trò (qua departmentsRoles)
createdBy	belongsTo	Người tạo
updatedBy	belongsTo	Người cập nhật lần cuối

DepartmentsUsers Object (Bảng liên kết)

Trường	Kiểu	Mô tả
departmentId	bigint	ID phòng ban
userId	bigint	ID user
isOwner	boolean	true nếu là trưởng phòng (mặc định: false)
isMain	boolean	(Deprecated) Dùng user.mainDepartmentId thay thế

Middleware Pipeline

Plugin đăng ký các middleware sau theo thứ tự:

Middleware	Thời điểm	Mô tả
setDepartmentsInfo	Sau auth, trước setCurrentRole	Đưa thông tin phòng ban vào context
setDepartmentOwners	Resource middleware	Xử lý owners khi lấy dữ liệu phòng ban
destroyDepartmentCheck	Resource middleware	Kiểm tra trước khi xóa phòng ban
updateDepartmentIsLeaf	Resource middleware	Cập nhật isLeaf khi thêm/xóa phòng ban con
resetUserDepartmentsCache	Resource middleware	Xóa cache phòng ban khi có thay đổi
setMainDepartment	Resource middleware	Xử lý logic phòng ban chính

ACL Snippets

Plugin đăng ký snippet pm.departments cho phép admin truy cập:

departments:*
roles:list
users:list
users:listExcludeDept
users.departments:*
roles.departments:*
departments.members:*

User đã đăng nhập (loggedIn) được phép gọi users:listExcludeDept.