Skip to main content

Integration Guide (WMS, HR & Accounting)

Hệ thống Boxme Levelling không hoạt động độc lập mà cần đồng bộ dữ liệu hai chiều với các hệ thống lõi khác: HRMS (Nhân sự), WMS (Vận hành kho), và Accounting/Payroll (Kế toán & Tính lương).

Tài liệu này hướng dẫn Developer cấu trúc các luồng đồng bộ, cách kiểm tra dữ liệu, và phương án tích hợp hệ thống.

1. Inbound: HRMS → Levelling (Master Data)​

Dữ liệu nhân sự (nhân viên, phòng ban, phân quyền) luôn lấy HRMS làm gốc (Source of Truth).

1.1 Đồng bộ lần đầu (Initial Sync)​

Khi mới triển khai hệ thống, cần đồng bộ theo thứ tự sau để tránh lỗi khóa ngoại (Foreign Key):

  1. Countries & Warehouses: Đồng bộ danh sách kho từ hệ thống quản lý kho/vùng.
  2. Staff Groups: Đồng bộ các nhóm nhân sự (Inbound, Outbound, Sorting, etc.).
  3. Employees: Fetch toàn bộ nhân sự hiện có từ HRMS.
  4. Users (Login): Khởi tạo tài khoản đăng nhập dựa trên role của nhân viên.

Phương pháp: Chạy script lấy dữ liệu qua API của HRMS, sau đó insert trực tiếp vào database Supabase của Levelling (Upsert strategy).

1.2 Đồng bộ khi có thay đổi (Event-driven Sync)​

Mỗi khi có biến động nhân sự, HRMS cần bắn Webhook hoặc Message Queue (Kafka/RabbitMQ) sang hệ thống Levelling.

  • Onboarding (Nhân viên mới): Tạo mới employee và cấp tài khoản user.
  • Offboarding (Nghỉ việc): Cập nhật status = 'inactive' trên bảng employees và vô hiệu hóa tài khoản user.
  • Role/Warehouse Change (Chuyển kho/Thăng chức): Cập nhật warehouse_id, role, và main_staff_group_id.

2. Inbound: WMS → Levelling (Operational Data)​

Hệ thống WMS cung cấp dữ liệu hiệu suất (PPH) và lỗi tự động.

2.1 Đồng bộ định kỳ (Periodic Sync)​

  • Daily PPH (Năng suất ngày):
    • Tần suất: Chạy Cron Job vào 01:00 AM mỗi ngày.
    • Dữ liệu: Tổng hợp lượng đơn xử lý, số giờ làm việc, và PPH của ngày hôm trước cho toàn bộ nhân viên kho.
    • Lưu trữ: Insert hàng loạt vào bảng pph_daily_raw trong Levelling. Hệ thống Levelling sẽ tự group data để tính điểm vinh danh tháng/tuần.

2.2 Đồng bộ tức thời (Real-time Events)​

  • Lỗi tự động từ WMS: (VD: Quét sai mã vạch, đóng gói thiếu hàng được camera AI phát hiện).
    • WMS gọi POST /api/violations để ghi nhận lỗi trực tiếp vào hệ thống Levelling.
    • Hệ thống sẽ thông báo tới Trưởng ca để vào xác nhận (Confirm/Waive).

3. Auditing & Monitoring (Kiểm tra dữ liệu)​

Làm sao để biết dữ liệu đã đồng bộ đúng và đủ sau mỗi lần chạy script?

3.1 Sau Initial Sync​

  1. Count Check: So sánh tổng số employees đang active trên HRMS với database Levelling (SELECT COUNT(*) FROM employees WHERE status = 'active').
  2. Orphaned Records: Kiểm tra xem có employee nào không có warehouse_id hợp lệ hay không.
  3. Role Validation: Chạy script select các user có role là warehouse_manager nhưng không mapping quản lý bất kỳ kho nào.

3.2 Monitoring Daily Sync​

  1. Log Webhook/Cronjob: Ghi log số lượng bản ghi PPH được push thành công vào pph_daily_raw mỗi đêm.
  2. Missing PPH Alerts: Tạo alert (Slack/Telegram) nếu Job Daily PPH chạy xong mà số lượng bản ghi insert = 0.
  3. Data Quality Queries: 
    -- Tìm nhân viên đi làm trên HRMS nhưng không có data PPH từ WMS
    SELECT e.employee_code, e.full_name 
    FROM employees e
    LEFT JOIN pph_daily_raw p ON e.id = p.employee_id AND p.date = CURRENT_DATE - 1
    WHERE p.id IS NULL AND e.status = 'active';

4. Outbound: Levelling → HR & Accounting​

Hệ thống Levelling là nơi xử lý chấm điểm, tuy nhiên để ra quyết định trả lương hoặc thưởng, dữ liệu cần được export ngược về HRMS và Kế toán.

4.1 Payroll & Accounting (Hàng tháng)​

Vào kỳ chốt lương (e.g. ngày 5 hàng tháng), Kế toán sử dụng các API Export:

  • Net Penalty / Khấu trừ: Lấy tổng số điểm trừ còn lại (sau recovery) qua API GET /api/scores/period?period=2026-02. Mỗi điểm trừ tương ứng với số tiền phạt cấu hình trong hệ thống nhân sự.
  • Bonus Payout / Thưởng: Export các điểm thưởng (total_bonus_points) cho sáng kiến, chứng chỉ để quy đổi ra tiền thưởng.
  • Lương tháng 13: Sử dụng API POST /api/benefits/thirteenth-month/calculate và export kết quả để kế toán chi trả vào dịp cuối năm.

4.2 HRMS (Phúc lợi & Quyền lợi)​

  • Phía HRMS gọi API GET /api/benefits/eligibility để lấy kết quả tính toán phúc lợi từ Levelling (Ví dụ: Ai đủ điều kiện nhận thẻ BHYT VIP, ai được đi du lịch Company Trip).
  • HR dựa vào dữ liệu này để ra quyết định mua bảo hiểm hoặc lập danh sách phúc lợi tự động thay vì phải tổng hợp Excel thủ công.

4.3 WMS (Điều phối vận hành)​

  • WMS gọi API Levelling để lấy pph_level của nhân sự.
  • Ứng dụng (Use case): WMS tự động điều phối các nhân viên có năng suất cao (Level: excellent) vào các zone gom hàng có độ ưu tiên cao hoặc xử lý đơn hỏa tốc (SLA ngắn). Ngược lại, nhân viên needs_improvement sẽ được assign các task ít áp lực thời gian hơn để làm quen.