Tham chiếu API: Module HRM

Tài liệu này chi tiết về các điểm cuối API RESTful cho module HRM.

---

1. Xác thực

Tất cả các yêu cầu PHẢI bao gồm một Platform JWT trong tiêu đề Authorization.

Authorization: Bearer <JWT>

JWT được cấp bởi Shell và chứa danh tính, tổ chức và vai trò của người dùng.

---

2. API Nhân viên

GET /employees

Liệt kê tất cả nhân viên trong tổ chức hiện tại.

Tham số Truy vấn:

• q: Tìm kiếm theo tên hoặc email.
• departmentId: Lọc theo ID bộ phận.
• status: Lọc theo employee_status.

Phản hồi (200 OK):

{
  "data": [
    {
      "id": "uuid",
      "jobTitle": "Engineer",
      "status": "active",
      ...
    }
  ]
}

GET /employees/:id

Truy xuất hồ sơ chi tiết của một nhân viên cụ thể.

POST /employees

Tạo một bản ghi nhân viên mới. Yêu cầu vai trò HR_ADMIN hoặc ADMIN.

PUT /employees/:id

Cập nhật chi tiết nhân viên. Nhân viên có thể cập nhật số điện thoại và liên hệ khẩn cấp của chính họ. Quản lý/Quản trị viên HR có thể cập nhật chức danh và bộ phận.

GET /org-chart

Truy xuất cấu trúc báo cáo phân cấp cho tổ chức.

---

3. API Quản lý Nghỉ phép

GET /leave-requests

Liệt kê các yêu cầu nghỉ phép. Mặc định là các yêu cầu của người dùng hiện tại trừ khi người dùng là Quản lý hoặc Quản trị viên HR.

POST /leave-requests

Gửi một yêu cầu nghỉ phép mới.

Thân yêu cầu (Body):

{
  "leaveType": "annual",
  "startDate": "2024-12-01",
  "endDate": "2024-12-05",
  "note": "Nghỉ phép gia đình"
}

POST /leave-requests/:id/approve

Phê duyệt một yêu cầu đang chờ xử lý. Yêu cầu người thực hiện phải là quản lý của nhân viên đó.

POST /leave-requests/:id/reject

Từ chối một yêu cầu đang chờ xử lý với lý do bắt buộc.

DELETE /leave-requests/:id

Hủy một yêu cầu đang chờ xử lý. Chỉ được phép bởi chủ sở hữu yêu cầu.

---

4. API Onboarding

GET /onboarding/checklists/:employeeId

Truy xuất danh sách kiểm tra đang hoạt động của một nhân viên cụ thể.

POST /onboarding/checklists/:employeeId/items/:itemId/complete

Đánh dấu một nhiệm vụ trong danh sách kiểm tra là hoàn thành.

GET /onboarding/templates

Liệt kê tất cả các mẫu onboarding có sẵn cho tổ chức.

POST /onboarding/templates

Tạo một mẫu onboarding mới với một tập hợp các nhiệm vụ.

---

5. Mã Lỗi Tiêu chuẩn

Mã Trạng thái	Mô tả
400 Bad Request	Đầu vào không hợp lệ hoặc vi phạm logic nghiệp vụ (ví dụ: không đủ số dư nghỉ phép).
401 Unauthorized	Thiếu hoặc JWT không hợp lệ.
403 Forbidden	Không đủ quyền hạn RBAC để thực hiện hành động.
404 Not Found	Tài nguyên (Nhân viên, Yêu cầu, v.v.) không tồn tại.
500 Server Error	Lỗi nội bộ không mong muốn.