Trang /hr/setup chỉ bọc <SetupWizardRoot module-key="hr" /> — toàn bộ logic nằm trong schema (hr-schema.ts) và 2 step tuỳ biến đăng ký qua extendSchema (hr-setup.ts):
Schema — tạo 28 collection + field + relation từ hr-schema.ts (không tạo được nếu instance chưa có Contacts — hr_people.contact_id FK vào c_contacts).
Seed — chèn dữ liệu bắt buộc: hr_employment_types (full_time/part_time/contractor/intern), hr_leave_types (annual/sick/unpaid/maternity/paternity kèm default_days), hr_settings (1 row mặc định), hr_document_triggers (6 sự kiện: talent_created/offer_sent/offer_accepted/hired/probation_confirmed/resigned).
Register Permissions — bước này không gọi API tạo gì cả (khác các module khác dùng createPermissionStep). Module quyền hr đã được backend tự đăng ký từ package.json (odp-extension.permissions) của extension — step này chỉ GET /app-permissions/modules để xác nhận hr có mặt, báo lỗi nếu không thấy.
Seed HR Role Policies — tạo (nếu chưa có) 5 policy: HR Admin, HR Manager, HR Recruiter, HR Department Manager, HR Viewer, cùng toàn bộ app-permission grant tương ứng cho từng policy. Idempotent — chạy lại (Repair) không tạo trùng, chỉ bổ sung grant còn thiếu.
/hr/settings (yêu cầu quyền hr:admin, tự redirect về /hr nếu thiếu) có 8 tab chọn qua query ?tab=:
General
company_name, default_currency, fiscal_year_start_month (1-12). Bên dưới là bảng nhãn tuỳ biến theo stage — đổi label hiển thị cho từng giá trị hr_people.stage (talent/interviewing/offer/probation/active/resigned) mà không đổi giá trị lưu trong DB.
Taxonomies
Quản lý 2 lookup: Leave type (label, số ngày mặc định/năm, có trả lương hay không — key tự sinh bằng slugify) và Employment type (label — key tự sinh). Có thể archive, không xoá cứng.
Policies
Bật/tắt + cấu hình tham số cho 4 nhóm chính sách: Leave base (số ngày annual/sick/personal theo employment type), Tenure bonus (cộng thêm ngày phép theo bậc thâm niên), Insurance eligibility (employment type nào đủ điều kiện BHXH/BHYT), Probation period (số tháng thử việc theo employment type). Đổi tham số kích hoạt tính lại leave balance (policy-engine.ts).
Holidays
Danh sách ngày lễ theo năm (điều hướng năm trước/sau), thêm mới (form dùng FormRoot + field-registry cho 3 field name/date/recurring), xoá, và Copy from [năm trước] để nhân bản nhanh sang năm mới.
Recruitment
Không có UI tự xây pipeline riêng trong HR — trang này liệt kê các ODP workflow definition khả dụng (collection hr_applications) và link thẳng sang trình soạn workflow chung của nền tảng (/workflow/definitions/:id) để tạo/sửa pipeline. Đây chính là pipeline được chọn ở tab Recruitment của một talent (xem Tuyển dụng).
Documents
Quản lý Document template — tạo/sửa nội dung markdown với placeholder dạng {{full_name}}, phân theo category (Onboarding/Probation/Resignation/Asset/Misc/Other), có thể archive.
Automation
Không phải rule builder tự do — đây là màn hình gắn template vào 6 sự kiện vòng đời cố định: Offer Sent, Hire, Probation End, Resign, Asset Issued, Asset Returned. Mỗi sự kiện chọn 0..n template + bật/tắt Auto-generate (tự sinh tài liệu ngay khi sự kiện xảy ra, không cần bấm tay).
Integrations
CRUD Provider 3rd-party (Authentik, webhook tuỳ biến) — cấu hình action nào được kích hoạt (on_hire/on_resign/on_reactivate), nút Test connection kiểm tra kết nối, xem log ở tab Provisioning của từng employee.
Bảng đầy đủ role → action nằm ở PERMISSIONS.md của module; tóm tắt:
| Vai trò | Làm được |
|---|---|
| HR Admin | Toàn quyền — cả hr:admin (Settings/Policies/Providers/Templates) |
| HR Manager | Toàn bộ vòng đời nhân viên + tuyển dụng + duyệt nghỉ phép + xem/sửa lương/bảo hiểm/tài liệu, không có hr:admin |
| HR Recruiter | Chỉ read + recruitment.read/recruitment.write — không tạo/sửa/xoá employee, không thấy dữ liệu sensitive, không duyệt nghỉ phép |
| HR Department Manager | Chỉ read + leave.approve.dept — thấy và duyệt nghỉ phép cho nhân viên thuộc phòng ban mình đứng đầu |
| HR Viewer | Chỉ read — không thấy compensation/insurance/documents |
Gán quyền: Settings → Permissions/Roles (ngoài phạm vi module HR, thuộc ODP core), mở role hoặc user, gắn policy HR * tương ứng. Chạy lại setup (Repair) không đụng tới role đã gán — chỉ re-sync policy/grant còn thiếu.
Quyền leave.approve.dept chỉ hoạt động nếu hệ thống resolve được “user hiện tại là head của phòng ban nào” — qua chuỗi hr_people.user_id → hr_departments.head_person_id. Gán bằng cách:
POST /api/hr/people/:id/link-user { user_id } (cũng tự match theo email trùng duy nhất lúc tạo person).Chưa gán link này, user có policy Department Manager sẽ thấy danh sách rỗng ở GET /people và GET /leave/requests — không phải lỗi quyền, chỉ vì không resolve được phạm vi phòng ban. Chi tiết ở Phòng ban.