Housekeeping Module Documentation

Overview

The Housekeeping Module handles one of the most operationally intensive parts of the hotel—room cleanliness and readiness. It automates daily task assignment based on guest movements (Arrivals, Departures, Stay-overs), enforces quality control through inspection workflows, and tracks inventory consumption per room.

Key Features

• Automated Scheduling: Daily logic generates tasks (Routine vs Checkout) based on real-time Front Desk data.
• Digital Checklists: Standardized steps for different clean types (e.g., "Deep Clean" has 40 steps, "Turndown" has 5).
• Inspection Workflow: Logic to require Supervisor approval before release.
• Inventory Integration: Tracks soap, shampoo, and towel usage per room for accurate cost accounting.
• Maintenance Reporting: Maids can log broken lamps or plumbing issues directly from the room view.
• Status Sync: Bi-directional status updates with Front Desk (Dirty <-> Clean <-> Occupied).

---

Architecture

Domain Layer (app/Domain/Housekeeping)

Models (6 Models)

HousekeepingTask (HousekeepingTask.php)

• Table: housekeeping_tasks
• Description: A unit of work assigned to a staff member.
• Key Fields:
  • room_id: The room to clean.
  • assigned_staff_id: Who does the work.
  • task_type: ROUTINE | CHECKOUT | DEEP_CLEAN | TURNDOWN.
  • status: PENDING | IN_PROGRESS | COMPLETED | PENDING_INSPECTION | APPROVED | SKIPPED | CANCELLED.
  • priority: HIGH (Check-in waiting) | NORMAL | LOW.
  • started_at, completed_at, inspected_at: Timestamps.

HousekeepingChecklistItem (HousekeepingChecklistItem.php)

• Table: housekeeping_checklist_items
• Description: Template for a step (e.g., "Change Sheets").
• Key Fields:
  • task_type: Link to task type.
  • description: Instruction text.
  • sort_order: Display order.

HousekeepingTaskChecklist (HousekeepingTaskChecklist.php)

• Table: housekeeping_task_checklists
• Description: Instance of a step for a specific task.
• Key Fields:
  • is_completed: Boolean toggle.

HousekeepingSupplyUsage (HousekeepingSupplyUsage.php)

• Table: housekeeping_supply_usages
• Description: Log of inventory consumed during a task.
• Key Fields:
  • inventory_item_id: Product (e.g., Shampoo).
  • quantity: Amount used.
  • inventory_transaction_id: Link to financial record.

MaintenanceIssue (MaintenanceIssue.php)

• Table: maintenance_issues
• Description: Defect reported found during cleaning.
• Key Fields:
  • issue_type: PLUMBING | ELECTRICAL | HVAC | FURNITURE.
  • status: OPEN | RESOLVED.

Services

HousekeepingService (HousekeepingService.php)

Purpose: Manages the lifecycle of tasks and room status updates.

Key Methods:

createTask(...)

Generates a new assignment.

• Logic:
  1. Creates Task record.
  2. Auto-Populate: Copies all active HousekeepingChecklistItems for this task_type into HousekeepingTaskChecklist.
  3. Returns task (Status: PENDING).

startCleaning(task)

Mark work as begun.

• Logic:
  1. Status -> IN_PROGRESS.
  2. Side Effect: Room Status -> DIRTY (if not already).

completeCleaning(task, requiresInspection)

Mark work as done.

• Logic:
  1. If requiresInspection=true (Configurable), Status -> PENDING_INSPECTION.
  2. If requiresInspection=false:
     • Status -> COMPLETED.
     • Side Effect: Check for active booking.
       • If Guest Checked In -> Room Status: OCCUPIED.
       • If Vacant -> Room Status: CLEAN.

approveInspection(task)

Supervisor passes the room.

• Logic:
  1. Status -> APPROVED.
  2. Side Effect: Check for active booking.
     • If Guest Checked In -> Room Status: OCCUPIED.
     • If Vacant -> Room Status: CLEAN.

supplyRoom(task, item, qty)

Record inventory usage.

• Logic:
  1. Calls InventoryService::issueOut (Dr Expense, Cr Inventory).
  2. Records HousekeepingSupplyUsage.

skipCleaning(task, reason)

Guest refused service (DND).

• Logic:
  1. Status -> SKIPPED.
  2. Room Status remains OCCUPIED.

---

Workflows

1. The Daily Cleaning Cycle

1. 7:00 AM: NightlyHousekeepingReset job runs.
   • Finds all Occupied Rooms -> Creates ROUTINE tasks.
   • Finds all Due-Out Rooms -> Creates CHECKOUT tasks.
2. 8:00 AM: Supervisor reviews dashboard and drags-and-drops tasks to balance workloads if needed.
3. 9:00 AM: Maid opens Tablet/Mobile view.
   • Sees "Room 101 - Routine".
   • Clicks Start.
4. Cleaning:
   • Maid checks off "Replace Towels".
   • Maid checks off "Vaccuum".
   • Maid notices burnt bulb -> Clicks "Report Issue" -> "Electrical" -> "Bulb".
   • Maid clicks "Add Supply" -> "Shampoo (x2)".
5. Completion:
   • Maid clicks Complete.
   • Task moves to Inspection Queue.
6. Inspection:
   • Supervisor receives alert. Walks to Room 101.
   • Verifies quality.
   • Clicks Approve.
   • Front Desk sees Room 101 turn Green (Clean/Ready).

2. Guest Check-Out Workflow

1. Guest checks out at Front Desk.
2. BookingService::checkOut() fires.
3. Event Listener calls HousekeepingService::markRoomDirty().
4. Room Status -> DIRTY (Red).
5. System generates High Priority CHECKOUT task.
6. Maid gets pinged for "Priority Clean".

---

Audit Findings & Improvements

Strengths

• Inventory Link: The integration with InventoryService::issueOut within the supplyRoom method ensures that "free" guest amenities are actually accounted for financially as COGS/Room Expense.
• Occupancy Logic: The service is smart enough (hasActiveBooking) to never accidentally mark an occupied room as VACANT/CLEAN, ensuring guest security.

Issues Identified

Major

• Automation Logic Gap: The scheduled job (NightlyHousekeepingReset) currently creates tasks essentially manually. It needs to be refactored to use HousekeepingService::createTask to ensure checklists are populated.
  • Risk: Auto-generated tasks currently have empty checklists.

Minor

• Mobile View: The current UI is table-based. Housekeepers need a Card-based view for standard mobile phones.
• Bulk Assign: No easy way to assign "All 3rd Floor" to "Staff A".

---

Configuration

Config: config/housekeeping.php

return [
    'inspection_required' => true, // Enforce Supervisor step?
    'default_priority' => 'NORMAL',
];

Module Version: 1.0 Status: Production Ready