VHRMS — Vietnam HRMS

Ứng dụng mở rộng cho Frappe HRMS, bổ sung các tính năng tuân thủ quy định lao động, thuế, bảo hiểm và kế toán Việt Nam.

Phiên bản: 0.1.0 Yêu cầu: Frappe v16, ERPNext v16, HRMS v16, Python 3.10+

---

Lương & Thuế (Payroll & Tax)

• Hệ thống tài khoản kế toán theo Thông tư 200/2014/TT-BTC — 243 tài khoản, 3 cấp; override API get_charts_for_country / get_chart của ERPNext để chart "Vietnam - TT200" xuất hiện trực tiếp khi tạo Company.

• Bảo hiểm bắt buộc: BHXH, BHYT, BHTN, BHTNLĐ-BNN và phí Công đoàn, tính trần tự động theo mức lương cơ sở / lương tối thiểu vùng, cap động theo số tháng.

• Thuế TNCN: biểu thuế lũy tiến 7 bậc (cập nhật 2026), giảm trừ bản thân + NPT, phí Công đoàn 1%, hỗ trợ biến thể thử việc, PIT formula tự động re-generate khi cập nhật tỷ lệ.

• 3 cấu trúc lương mẫu Việt Nam tự động khởi tạo khi tạo Company (on_company_created): Official / Probation / Manager.

• Phụ cấp Việt Nam — 6 Salary Component dựng sẵn, tự gán account TT200 (TK 6421):

  • PC_AT Phụ cấp ăn trưa — miễn thuế TNCN ≤ 1.200.000đ/tháng (dự thảo NĐ hướng dẫn Luật Thuế TNCN 2025), tự trừ khỏi thu nhập chịu thuế trong công thức PIT.
  • PC_TP Phụ cấp trang phục — miễn thuế ≤ 5.000.000đ/năm (TT 111/2013/TT-BTC); cảnh báo khi tổng năm vượt mức, có xét cả entry recurring.
  • PC_XX Phụ cấp xăng xe — đi lại / công tác.
  • PC_DT Phụ cấp điện thoại — liên lạc, theo định mức công ty.
  • PC_NO Phụ cấp nhà ở — dành cho cấp quản lý, cấu hình theo % base (mặc định 15%).
  • Phụ cấp tăng ca — Earning component theo Điều 98 BLLĐ 2019.

  Ràng buộc giới hạn qua hook Additional Salary (soft warning, không block).

• Pro-rata giữa tháng (TETRA-790): tự động tính lương theo ngày khi thay đổi Salary Structure Assignment giữa kỳ (override Salary Slip).

• KPI Bonus: Vietnam KPI Bonus Rule + Monthly KPI Evaluation, tính thưởng theo tầng (tier) gắn với Appraisal.

• Grade / Band lương (Vietnam Salary Band, Vietnam Reference Level) — Salary Structure Assignment tự động điền Base từ grade × band.

• Gross-up / Net ↔ Gross theo biểu thuế + BHXH hiện hành, đối chiếu hợp đồng Gross vs Net.

• BHXH Claim (BHXH Claim) — quản lý hồ sơ hưởng chế độ BHXH ngắn hạn (ốm đau, thai sản, dưỡng sức…), tính mức hưởng, liên kết sổ BHXH và tài khoản thanh toán.

Tăng ca (Overtime)

• Theo Bộ luật Lao động 2019, Điều 98 & 107.
• Tự phát hiện loại ngày (thường / cuối tuần / lễ) và ca đêm (+30%).
• Giới hạn giờ tăng ca theo tháng/năm (Vietnam OT Limit).
• Hệ số OT cấu hình qua Vietnam OT Rate.

Hồ sơ nhân viên (Employee Profile)

• 80+ custom fields theo Thông tư 06/2023/TT-BNV (dân tộc, tôn giáo, quê quán, hộ khẩu, lý lịch Đảng/Đoàn, quân ngũ…).
• Bảng con: Employee Family Member, Employee Language Proficiency, Employee Work History Item, Employee Award, Employee Disciplinary.
• NPT (Người phụ thuộc): NPT Dependent, Employee NPT Item, NPT Submission Batch — quản lý & đăng ký NPT theo lô.
• Validation theo chuẩn VN: số CCCD, mã số thuế cá nhân (PIT code), số sổ BHXH, ngày vào Đảng/Đoàn, thời gian nhập ngũ.
• Print format "VN Employee Profile" in hồ sơ theo chuẩn hành chính.
• Master data Việt hoá: Nationality (200+), Ethnicity (54 dân tộc), Religion (16 tôn giáo).

Nhà thầu / Correspondent (Supplier)

Theo Luật Đấu thầu 2023 và Nghị định 214/2025/NĐ-CP:

• Supplier Legal Representative — người đại diện pháp luật.
• Supplier Financial Record — báo cáo tài chính theo năm.
• Supplier Contract History — lịch sử hợp đồng.
• Supplier Equipment, Supplier Production Facility, Supplier Key Personnel.
• Supplier Certification Item, Supplier Reputation Record.

Tuyển dụng (Recruitment)

• Custom fields & property setters bổ sung cho Job Applicant / Job Opening (TETRA-1218).

Báo cáo (Reports)

• D02-TS — Danh sách lao động tham gia BHXH, BHYT.
• D03-TS — Báo tăng / báo giảm BHXH.
• C70a-HD — Đề nghị thanh toán chế độ BHXH ngắn hạn.
• PIT Monthly — Bảng kê thuế TNCN theo tháng.
• All Employee NPT — Tổng hợp NPT toàn công ty (Mẫu 20).

Nghỉ phép (Leave Management)

• Bộ Leave Type theo BLLĐ 2019 (Phép năm, Nghỉ ốm, Nghỉ bù, Nghỉ không lương, Thai sản…), tự thay thế các Leave Type tiếng Anh mặc định của HRMS khi an toàn.
• Vietnam Leave Period, Vietnam Leave Policy, tự động gán policy cho Employee mới.

Cấu hình mặc định (Auto-setup)

Chạy trong after_install, after_migrate và on_company_created:

• Ngày lễ Việt Nam (Dương + Âm lịch: Tết Nguyên đán tính theo năm, Giỗ tổ Hùng Vương), T7/CN weekly off.
• Employee Grade mẫu, Shift Type mặc định, Overtime Type.
• Payroll Settings, Payroll Period theo chuẩn VN.
• Custom fields + Property Setters (áp dụng cả cho Recruitment).
• Salary Component + tự động gán account theo TT200.
• Employee Self Service permissions cho các doctype VHRMS (NPT, Correspondent…).
• Bản dịch tiếng Việt cho Employment Type, Salary Mode, Marital Status, Travel Request, Designation.
• Workspace "VHRMS" trên Desk + dashboard charts tuỳ biến.
• Global search cho Correspondent và các bảng nhà thầu.

Tác vụ định kỳ (Scheduled Tasks)

• Hàng ngày: phát hiện NPT đủ 18 tuổi (hết điều kiện giảm trừ), cảnh báo giấy tờ sắp hết hạn (CCCD, giấy phép lao động…).
• Hàng tháng (ngày 1): nhắc HR nộp báo cáo D02-TS, kiểm tra NPT sắp hết kỳ đăng ký.
• Hàng năm (tháng 12): tự sinh Holiday List cho năm tiếp theo, nhắc cập nhật tỷ lệ BH / biểu thuế / lương tối thiểu vùng.

Di trú dữ liệu (Patches)

Patch chạy theo version trong patches.txt — ví dụ v0_3_0 dọn custom fields cũ, v0_4_0 migrate NPT Dependent sang child table.

REST API

Whitelisted endpoints tại vhrms.api:

Endpoint	Mô tả
get_insurance_rates(date)	Tỷ lệ BHXH, BHYT, BHTN, BHTNLĐ-BNN, CĐ
get_tax_brackets(date)	Biểu thuế TNCN 7 bậc
get_tax_deductions(date)	Mức giảm trừ bản thân / NPT
get_minimum_wages(date)	Lương tối thiểu vùng I–IV
get_reference_level(date)	Mức lương cơ sở
get_ot_rates()	Hệ số OT
calculate_deductions(gross, npt, date, region)	Tính BHXH + PIT
gross_up(net, npt, date, region)	Quy đổi Net → Gross
calculate_ot(hourly_rate, hours, day_type, is_night)	Tính lương OT
get_employee_npt_info(employee, date)	Số NPT hợp lệ của nhân viên

---

Installation

cd $PATH_TO_YOUR_BENCH
bench get-app https://wedev.carp.vn/tant/vhrms.git --branch develop
bench --site [site-name] install-app vhrms
bench --site [site-name] migrate

Xem HUONG_DAN_SU_DUNG.md để biết chi tiết cài đặt, cấu hình và sử dụng.

Contributing

Repo dùng pre-commit để format & lint:

cd apps/vhrms
pre-commit install

Tools: ruff, eslint, prettier, pyupgrade.

License

MIT