OLOW Hotel ERP

Appearance

Staff Module Documentation ​

Overview ​

The Staff Module acts as the central directory for human resources. It manages the identity, access, and daily lifecycle of every employee. It serves as the single source of truth for the HR/Payroll module (compensation data) and Housekeeping module (assignment data).

Key Features ​

  • Centralized Profiles: Manages "Party" data (PII) separately from "Staff" data (Employment).
  • Attendance Tracking: Supports Dual-Mode clocking (Web Dashboard for back-office, PIN Kiosk for operations).
  • Leave Management: Automated balance checking, approval workflows, and cancellation logic.
  • Role Management: Links staff to Departments (Front Office, Kitchen) and Positions.
  • Document Management: Stores contracts, IDs, and certifications.

Architecture ​

Domain Layer (app/Domain/Staff) ​

Models (6 Models) ​

Staff (Staff.php) ​
  • Table: staff
  • Description: The employment record.
  • Key Fields:
    • party_id: Link to PII (Name, Email, Phone).
    • property_id: Tenant scope.
    • employee_code: Unique ID (e.g., STF-1234).
    • employee_pin: 4-digit PIN for Kiosk access.
    • department_id, position_id: Organization links.
    • base_salary: Monthly compensation amount.
    • available_leave_days: Current balance.
    • is_active: Employment status.
  • Relationships:
    • party(): BelongsTo Party.
    • user(): HasOne User (optional login).
StaffAttendance (StaffAttendance.php) ​
  • Table: staff_attendance
  • Description: Daily work log.
  • Key Fields:
    • staff_id: Link to Staff.
    • work_date: Date of shift.
    • clock_in_time: Timestamp.
    • clock_out_time: Timestamp.
    • hours_worked: Calculated duration.
StaffLeaveRecord (StaffLeaveRecord.php) ​
  • Table: staff_leave_records
  • Description: A request for time off.
  • Key Fields:
    • leave_type: ANNUAL | SICK | UNPAID | MATERNITY.
    • start_date, end_date: Duration.
    • status: PENDING | APPROVED | REJECTED | CANCELLED.
    • days_taken: Calculated count.

Services ​

StaffManagementService (StaffManagementService.php) ​

Purpose: Handles the daily operations of staff management.

Key Methods:

createStaff(partyData, staffData) ​

Onboards a new hire.

  • Logic:
    1. Creates Party record (PII).
    2. Generates unique employee_code (e.g., STF-9988).
    3. Creates Staff record linked to Party.
    4. Returns unified entity.
requestLeave(staff, type, dates) ​

Submits a time-off request.

  • Logic:
    1. Calculates daysTaken.
    2. Validation: If type=ANNUAL, checks staff.available_leave_days >= daysTaken.
    3. Overlap Check: Prevents double-booking dates.
    4. Creates record (Status: PENDING).
approveLeave(record) ​

Manager authorizes the time off.

  • Logic:
    1. Status -> APPROVED.
    2. Side Effect: If type=ANNUAL, decrements staff.leave_days_used.
cancelLeave(record) ​

Restores balance if plans change.

  • Logic:
    1. Status -> CANCELLED.
    2. Side Effect: If previously APPROVED ANNUAL leave, restores staff.leave_days_used.
clockWithPin(pin) ​

Kiosk logic for shared terminals.

  • Logic:
    1. Finds active staff by PIN.
    2. Smart Toggle:
      • If no record for today -> Call clockIn().
      • If record exists & open -> Call clockOut().
      • If record exists & closed -> Error "Already completed today".

Workflows ​

1. Hiring & Onboarding ​

  1. HR Entry: Admin enters "John Doe", "Chef", Salary $1000.
  2. System: Creates Party record + Staff record STF-1001.
  3. User Account: Admin toggles "Create Login". System sends invitation email to John.
  4. Kiosk Setup: Admin assigns PIN 1001. John can now use the kitchen tablet.

2. Time & Attendance (Kitchen API_ ​

  1. Start Shift: John types 1001 on Kitchen Tablet.
    • System: "Welcome John! Clocked in at 08:00 AM".
  2. End Shift: John types 1001 on Kitchen Tablet.
    • System: "Goodbye John! Worked 9.0 hours".

3. Leave Request Cycle ​

  1. Request: John logs into Portal, requests 3 days for "Family Event".
  2. Validation: System checks balance (15 days avail). Allows request.
  3. Approval: Chef Manager gets notification. Clicks "Approve".
  4. Effect:
    • Request -> APPROVED.
    • Balance -> 12 days avail.
    • Roster -> marked as "On Leave" for those dates.
  5. Cancellation (Optional): John cancels request.
    • Balance -> 15 days avail.

Audit Findings & Improvements ​

Strengths ​

  • Transactional Integrity: Leave workflows (Request/Approve/Cancel) are wrapped in DB transactions to ensure available_leave_days never drifts.
  • PII Separation: Using the Party model is excellent for GDPR/Privacy compliance, keeping strict separation between "The Person" and "The Job".

Issues Identified ​

Major ​

Major ​

  • Hardcoded Context: [FIXED] createStaff now requires explicit property_id parameter, removing reliance on unsafe fallbacks.

Minor ​

  • Time Logic: calculateHours is a simple subtraction. Needs logic for "Unpaid Breaks" (e.g., auto-deduct 30 mins if shift > 6h).
  • Shift Enforcement: Currently, staff can clock in at 3 AM for a 9 AM shift. Needs "Tolerance" settings (e.g., max 15 mins early).

Configuration ​

Config: config/staff.php

php
return [
    'default_leave_days' => 21,
    'currency' => 'USD',
];

Module Version: 1.0 Status: Production Ready