EP-006: Housekeeping Management
Business Objective
Housekeeping is the backbone of guest satisfaction in any hotel. A dirty room or missed turndown service directly impacts online reviews and repeat bookings. Indian hotels face unique challenges: high staff-to-room ratios, multiple daily cleaning cycles (checkout clean, stayover tidy, turndown), linen tracking across laundry vendors, and minibar reconciliation with GST compliance. Real-time room status synchronization between front desk and housekeeping eliminates the #1 operational bottleneck in Indian hotels -- the "room ready" phone call loop. Digital task management replaces paper checklists, enables photo-based proof of work, and provides management with KPIs to optimize staffing levels and cleaning times.
Audience
- Primary: Housekeeping Staff, Housekeeping Supervisors, Executive Housekeeper (Manager role)
- Secondary: Front Desk Agents (room status consumers), General Manager (KPI dashboards), Maintenance Team
- Tertiary: Accounts team (linen inventory valuation, minibar revenue tracking)
Scope
In Scope
- Real-time room status board (CLEAN, DIRTY, INSPECTED, OUT_OF_ORDER, OUT_OF_SERVICE, DO_NOT_DISTURB, PICKUP)
- Task management with 6 types: CLEANING, DEEP_CLEAN, TURNDOWN, INSPECTION, MAINTENANCE, CUSTOM
- 4 priority levels: URGENT, HIGH, NORMAL, LOW
- 5 task statuses: PENDING, ASSIGNED, IN_PROGRESS, COMPLETED, VERIFIED
- Staff assignment (manual + auto-assign by floor/section)
- Mobile task queue for housekeeping staff (React Native)
- Task completion with before/after photo upload
- Supervisor inspection workflow with checklist scoring
- Maintenance request creation and tracking
- Linen inventory management with movement types: ISSUED, RETURNED, DAMAGED, DISCARDED, WASHED, IN_LAUNDRY
- Minibar par level management and consumption tracking
- Lost & found item logging and guest notification
- Auto-reorder alerts when linen/amenity stock falls below threshold
- Housekeeping KPIs: rooms cleaned per hour, inspection pass rate, average turnaround time
- Discrepancy reports: Front Desk vs. Housekeeping status mismatch detection
- Kafka events for room status changes (consumed by front desk, reservation services)
- Multi-tenant isolation (all queries scoped by tenantId)
Out of Scope
- Laundry vendor management and billing (separate operations module)
- Guest-facing housekeeping request via mobile app (deferred to guest experience epic)
- IoT integration (smart locks, occupancy sensors) for auto-status updates
- Outsourced housekeeping agency contract management
Current Implementation Status
- Backend (housekeeping-service): Fully built NestJS microservice with controllers for room status, tasks, assignments, linen inventory, linen movements, minibar, lost & found, maintenance requests, and KPI endpoints. Prisma models for HousekeepingTask, LinenInventory, LinenMovement, MinibarItem, LostFoundItem, MaintenanceRequest. Kafka producer emits
housekeeping.room.status.changedevents. Redis caching for room status board. RBAC guards restrict endpoints to HOUSEKEEPING, MANAGER, ADMIN roles. - Dashboard (02-hmp-web-dashboard): Housekeeping module with room status board (color-coded grid), task list with filters, task creation/assignment dialogs, linen inventory table with movement log, minibar par management, lost & found register, maintenance request list, and KPI dashboard with charts.
- Mobile App: React Native housekeeping app with task queue, swipe-to-update status, photo capture (camera integration), offline queue for poor connectivity areas.
- API Gateway: Proxy routes configured for
/api/v1/housekeeping/*endpoints.
Gap Analysis
- Photo Upload to Cloud Storage: Camera capture works on mobile but photos are stored as base64 in the database. No integration with S3/MinIO cloud storage for proper file management, thumbnail generation, or CDN delivery. Impact: database bloat, slow task detail loading.
- Supervisor Inspection Checklist Scoring: Inspection tasks exist but lack a structured checklist (e.g., bathroom: 5 items, bedroom: 8 items, balcony: 3 items) with per-item pass/fail scoring and weighted overall score. Currently just a pass/fail toggle.
- Auto-Reorder Alerts: Linen and amenity inventory tracks quantities but threshold-based alerts are not connected to the notification service. No Kafka event emitted when stock falls below par. Procurement team has no automated visibility.
- Discrepancy Report Enhancement: Basic report exists comparing FD and HK status but lacks visual highlighting (color-coded mismatches), time-based analysis (how long a room stayed in mismatch), and auto-resolution suggestions.
- Predictive Task Generation: No auto-creation of cleaning tasks on checkout events. Currently tasks are manually created or bulk-generated at shift start. Integration with reservation service checkout events would automate this.
- Deep Clean Scheduling: No recurring schedule for deep cleans (e.g., every 7th stayover day, post-long-stay). Must be manually tracked.
User Stories
| Story ID | Title | Priority | Points | Status | Sprint |
|---|---|---|---|---|---|
| US-006-001 | Real-Time Room Status Board | P0 | 5 | Built | 5 |
| US-006-002 | Create Housekeeping Task | P0 | 3 | Built | 5 |
| US-006-003 | Assign Task to Staff | P0 | 3 | Built | 5 |
| US-006-004 | Mobile Task Queue | P0 | 5 | Built | 5 |
| US-006-005 | Update Task Status (In-Progress / Complete) | P0 | 3 | Built | 5 |
| US-006-006 | Photo Upload for Task Completion | P1 | 5 | Partial | 6 |
| US-006-007 | Supervisor Inspection with Checklist Scoring | P1 | 8 | Partial | 6 |
| US-006-008 | Maintenance Request Creation | P0 | 3 | Built | 5 |
| US-006-009 | Linen Inventory Management | P0 | 5 | Built | 6 |
| US-006-010 | Linen Movement Tracking | P0 | 3 | Built | 6 |
| US-006-011 | Minibar Par Level Management | P1 | 5 | Built | 6 |
| US-006-012 | Lost & Found Register | P1 | 3 | Built | 6 |
| US-006-013 | Auto-Reorder Alerts (Linen/Amenities) | P2 | 5 | Not Started | 10 |
| US-006-014 | Discrepancy Report (FD vs HK) | P1 | 5 | Partial | 7 |
| US-006-015 | Housekeeping KPI Dashboard | P1 | 5 | Built | 7 |
| US-006-016 | Auto-Task Generation on Checkout | P2 | 5 | Not Started | 10 |
Dependencies
- EP-001 (Auth & Access): RBAC roles HOUSEKEEPING, MANAGER, ADMIN gate all endpoints
- EP-002 (Property): Room master data (room number, floor, type) sourced from property service
- EP-003 (Reservation): Checkout events trigger task auto-generation; stayover schedule drives daily task lists
- EP-005 (Front Desk): Room status synchronization; discrepancy report compares FD vs HK status
- Notification Service: Auto-reorder alerts, task assignment push notifications
- File Storage (S3/MinIO): Required for photo upload cloud storage integration
Acceptance Criteria (Epic Level)
- Room status board updates in real-time (< 2 second latency) when HK staff changes status on mobile
- Tasks can be created, assigned, started, completed, and verified through full lifecycle
- Before/after photos are captured on mobile and stored in cloud storage (not database)
- Supervisor can inspect rooms using a scored checklist with per-item pass/fail
- Linen inventory reflects accurate counts with full movement audit trail
- Minibar par levels are tracked and consumption is posted to guest folio
- Lost & found items are logged with photos and linked to guest profiles when identified
- Auto-reorder alerts fire when inventory drops below configured threshold
- KPI dashboard shows rooms/hour, inspection pass rate, avg turnaround time per shift
- Discrepancy report highlights FD/HK mismatches with timestamps and duration
- All data is tenant-scoped; Property A housekeeping staff cannot see Property B data
KPIs / Success Metrics
- Room turnaround time (checkout to clean): target < 30 minutes
- Rooms cleaned per housekeeper per hour: target > 3.0
- Inspection pass rate (first attempt): target > 90%
- Discrepancy resolution time: target < 15 minutes
- Linen loss rate: target < 2% per month
- Lost & found item return rate: target > 60%
- Mobile app adoption by HK staff: target > 95%
- Task completion rate within shift: target > 98%
Detailed User Stories
US-006-001: Real-Time Room Status Board
As a housekeeping supervisor, I want to see the real-time status of every room on a color-coded board, So that I can quickly identify dirty rooms, assign cleaning tasks, and coordinate with front desk for early check-ins.
Priority: P0 | Points: 5 | Sprint: 5 | Status: Built
Implementation Status
Backend exposes GET /api/v1/housekeeping/room-status returning all rooms with current HK status, last cleaned timestamp, assigned staff, and DND flag. Redis caches the board and invalidates on status change. Dashboard renders a grid grouped by floor with color-coded cells (green=clean, red=dirty, blue=inspected, grey=OOO, yellow=in-progress). WebSocket subscription pushes status changes. Mobile app shows simplified floor view.
Acceptance Criteria
Scenario: View room status board grouped by floor
Given I am logged in as a Housekeeping Supervisor for "Taj Palace Delhi"
And the property has 120 rooms across 8 floors
When I navigate to Housekeeping > Room Status
Then I see a grid with 8 floor rows
And each room cell is color-coded by its housekeeping status
And I can see the assigned housekeeper name on each cell
Scenario: Real-time status update on the board
Given I am viewing the room status board
And Room 305 is currently showing as DIRTY (red)
When a housekeeper marks Room 305 as CLEAN via mobile app
Then Room 305 changes to CLEAN (green) within 2 seconds
And a toast notification shows "Room 305 marked Clean by Sunita"
Scenario: Filter board by status
Given I am viewing the room status board
When I click the "Dirty" filter chip
Then only rooms with DIRTY status are highlighted
And all other rooms are dimmed
And the count badge shows "23 Dirty Rooms"
US-006-002: Create Housekeeping Task
As a housekeeping supervisor, I want to create cleaning tasks for specific rooms with type, priority, and instructions, So that housekeeping staff receive clear work orders with all necessary details.
Priority: P0 | Points: 3 | Sprint: 5 | Status: Built
Implementation Status
POST /api/v1/housekeeping/tasks accepts roomId, type (6 enum values), priority (4 levels), assigneeId (optional), notes, and scheduledFor. Dashboard has a "Create Task" dialog accessible from the room status board (right-click on room cell) or from the Tasks page. Bulk task creation supported for multiple rooms.
Acceptance Criteria
Scenario: Create a checkout cleaning task
Given I am a Housekeeping Supervisor
And Room 412 has just been checked out
When I create a task with type "CLEANING", priority "HIGH", and note "Guest reported spill near minibar"
Then a task is created with status PENDING
And the task appears in the unassigned task queue
And a Kafka event "housekeeping.task.created" is published
Scenario: Bulk create tasks for a floor
Given 12 rooms on Floor 3 are in DIRTY status
When I select all Floor 3 dirty rooms and click "Bulk Create Tasks"
And I set type "CLEANING" and priority "NORMAL"
Then 12 individual tasks are created, one per room
And each task inherits the floor's default housekeeper assignment if configured
Scenario: Prevent duplicate active task for same room
Given Room 201 already has an active CLEANING task in IN_PROGRESS status
When I attempt to create another CLEANING task for Room 201
Then the system shows a warning "Room 201 already has an active cleaning task assigned to Priya"
And I can choose to proceed (creating a second task) or cancel
US-006-003: Assign Task to Staff
As a housekeeping supervisor, I want to assign tasks to specific housekeeping staff members or use auto-assignment, So that workload is distributed fairly and every task has clear ownership.
Priority: P0 | Points: 3 | Sprint: 5 | Status: Built
Implementation Status
PATCH /api/v1/housekeeping/tasks/:id/assign accepts staffId. Auto-assign endpoint POST /api/v1/housekeeping/tasks/auto-assign distributes pending tasks by floor/section assignment and current workload (tasks in progress count). Dashboard shows drag-and-drop from task pool to staff cards. Push notification sent to assigned staff via mobile app.
Acceptance Criteria
Scenario: Manual assignment of task to staff
Given there is a pending CLEANING task for Room 508
And housekeeper "Meena" is on shift and assigned to Floor 5
When I assign the task to Meena
Then the task status changes to ASSIGNED
And Meena receives a push notification on her mobile app
And the room status board shows Meena's initials on Room 508
Scenario: Auto-assign tasks at shift start
Given 40 rooms are in DIRTY status for the morning shift
And 8 housekeepers have clocked in for the morning shift
When I click "Auto-Assign All Pending Tasks"
Then tasks are distributed based on each housekeeper's floor assignment
And each housekeeper gets approximately equal task count (within +/- 2)
And tasks are ordered by priority (URGENT first, then HIGH, NORMAL, LOW)
Scenario: Reassign task from one staff to another
Given Room 312 task is assigned to "Ravi" who has reported sick mid-shift
When I reassign the task to "Sunita"
Then Ravi's task count decreases by 1 and Sunita's increases by 1
And Sunita receives a push notification with the task details
And the reassignment is logged in the task audit trail
US-006-004: Mobile Task Queue
As a housekeeper, I want to see my assigned tasks in priority order on my mobile phone, So that I can work through my rooms efficiently without returning to the desk for instructions.
Priority: P0 | Points: 5 | Sprint: 5 | Status: Built
Implementation Status
React Native housekeeping app shows a scrollable task queue sorted by priority then floor proximity. Each task card shows room number, type, priority badge, special instructions, and guest name (for stayover). Swipe right to start (IN_PROGRESS), swipe left to skip (moves to bottom). Offline queue caches tasks and syncs when connectivity returns. App uses GET /api/v1/housekeeping/tasks?assigneeId={me}&status=ASSIGNED,IN_PROGRESS.
Acceptance Criteria
Scenario: View assigned tasks for the shift
Given I am housekeeper "Priya" logged into the mobile app
And I have 14 tasks assigned for today's shift
When the app loads my task queue
Then I see 14 task cards sorted by priority (URGENT first)
And each card shows room number, task type icon, priority color band, and any special instructions
And an URGENT task for Room 801 (VIP guest checkout) appears at the top
Scenario: Start and complete a task
Given I am viewing my task queue
And the first task is CLEANING for Room 305
When I swipe right on Room 305 to start
Then the task status changes to IN_PROGRESS
And a timer starts showing elapsed cleaning time
And the room status board in the dashboard updates to show Room 305 as "Being Cleaned"
Scenario: Work offline in basement floors
Given I am cleaning rooms in Basement Level 1 with no WiFi signal
When I complete 3 tasks and mark them as done
Then the app queues the status updates locally
And shows an "Offline - 3 updates pending" indicator
And when I reach a floor with WiFi, all 3 updates sync automatically
US-006-005: Update Task Status (In-Progress / Complete)
As a housekeeper, I want to update my task status as I start and finish cleaning a room, So that supervisors see real-time progress and front desk knows when rooms are ready.
Priority: P0 | Points: 3 | Sprint: 5 | Status: Built
Implementation Status
PATCH /api/v1/housekeeping/tasks/:id/status accepts new status with validation for allowed transitions (ASSIGNED -> IN_PROGRESS -> COMPLETED). On COMPLETED, a Kafka event housekeeping.task.completed is emitted. Room status auto-updates to CLEAN when cleaning task completes. Timestamp recorded for startedAt and completedAt to calculate turnaround metrics.
Acceptance Criteria
Scenario: Mark task as in-progress
Given I have an ASSIGNED cleaning task for Room 410
When I update the status to IN_PROGRESS
Then the task shows a running timer
And the room status changes from DIRTY to "Being Cleaned" on the supervisor's board
And the startedAt timestamp is recorded
Scenario: Mark task as completed
Given I have an IN_PROGRESS cleaning task for Room 410 (started 22 minutes ago)
When I mark the task as COMPLETED
Then the room status changes to CLEAN
And completedAt timestamp is recorded
And the turnaround time (22 minutes) is logged for KPI calculation
And a Kafka event notifies front desk service that Room 410 is clean
Scenario: Prevent invalid status transition
Given I have a PENDING task (not yet assigned)
When I attempt to mark it as COMPLETED directly
Then the system rejects with error "Invalid status transition: PENDING -> COMPLETED"
And the task remains in PENDING status
US-006-006: Photo Upload for Task Completion
As a housekeeper, I want to take before and after photos when completing a task, So that supervisors can verify cleaning quality remotely and resolve guest complaints with photographic evidence.
Priority: P1 | Points: 5 | Sprint: 6 | Status: Partial
Implementation Status
Mobile app integrates device camera for photo capture. Before photos are taken when starting a task (IN_PROGRESS), after photos when completing (COMPLETED). Currently photos are stored as base64 strings in the task record in PostgreSQL. The dashboard task detail view renders these images. Gap: No S3/MinIO integration. No thumbnail generation. Database stores raw base64 causing performance issues on rooms with 4-6 photos. No image compression before upload.
Acceptance Criteria
Scenario: Capture before photo when starting task
Given I start a cleaning task for Room 602
When the app prompts "Take before photo" and I capture an image of the room
Then the photo is compressed to max 1MB
And uploaded to cloud storage (S3/MinIO) under path /{tenantId}/housekeeping/{taskId}/before/
And a thumbnail (200x200) is generated for the task list view
And the photo URL is stored in the task record (not base64)
Scenario: Capture after photo when completing task
Given I am completing the cleaning task for Room 602
When I take 2 after photos (bathroom and bedroom)
Then both photos are uploaded to cloud storage under /{tenantId}/housekeeping/{taskId}/after/
And the task record stores an array of photo URLs
And the supervisor can view before/after comparison in the dashboard
Scenario: Handle photo upload failure gracefully
Given I am in an area with weak network connectivity
When I complete a task and photo upload fails
Then the task completion is saved immediately (not blocked by photo upload)
And the photo is queued for retry upload in background
And an indicator shows "1 photo pending upload"
And the photo uploads when connectivity is restored
US-006-007: Supervisor Inspection with Checklist Scoring
As a housekeeping supervisor, I want to inspect cleaned rooms using a structured checklist with per-item scoring, So that quality standards are consistently enforced and I can identify specific training needs for staff.
Priority: P1 | Points: 8 | Sprint: 6 | Status: Partial
Implementation Status
Inspection task type exists and supervisors can mark rooms as INSPECTED (pass) or revert to DIRTY (fail). Gap: No structured checklist template. No per-item scoring (e.g., bathroom cleanliness: 8/10, bed making: 9/10). No checklist template management (different templates for standard vs suite rooms). No weighted scoring or minimum passing score configuration. Currently a binary pass/fail only.
Acceptance Criteria
Scenario: Inspect room using structured checklist
Given I am a Housekeeping Supervisor inspecting Room 305
And Room 305 is a "Deluxe Room" which uses the "Deluxe Inspection Checklist"
And the checklist has 5 sections: Bedroom (8 items), Bathroom (6 items), Balcony (3 items), Minibar (4 items), General (5 items)
When I score each item as Pass, Fail, or N/A
Then the system calculates a weighted overall score (e.g., 87%)
And if score >= 85% (configurable threshold), the room passes inspection
And room status changes to INSPECTED
And the housekeeper "Priya" gets a notification "Room 305 passed inspection (87%)"
Scenario: Failed inspection triggers re-clean task
Given I am inspecting Room 412
And I mark "Bathroom floor" and "Toilet" as Fail
And the overall score is 72% (below 85% threshold)
When I submit the inspection as Failed
Then a new CLEANING task is auto-created for Room 412 with priority HIGH
And the task notes include "Re-clean required: Bathroom floor, Toilet failed inspection"
And the original housekeeper receives a notification with specific failed items
And room status reverts to DIRTY
Scenario: View inspection history and trends
Given I want to review housekeeper "Meena's" performance for the last 30 days
When I navigate to KPIs > Staff Performance > Meena
Then I see her inspection pass rate (93%), average score (89%)
And a breakdown of most commonly failed checklist items
And a trend chart showing improvement or decline over time
US-006-008: Maintenance Request Creation
As a housekeeper, I want to report maintenance issues I discover while cleaning a room, So that the engineering team can fix problems before the next guest checks in.
Priority: P0 | Points: 3 | Sprint: 5 | Status: Built
Implementation Status
POST /api/v1/housekeeping/maintenance-requests accepts roomId, category (PLUMBING, ELECTRICAL, HVAC, FURNITURE, APPLIANCE, OTHER), description, priority, and optional photo. Dashboard shows maintenance request list with status tracking (OPEN, ASSIGNED, IN_PROGRESS, RESOLVED, CLOSED). Integration with property service to update room status to OUT_OF_ORDER for critical issues.
Acceptance Criteria
Scenario: Report a maintenance issue during cleaning
Given I am cleaning Room 208 and discover a leaking bathroom faucet
When I create a maintenance request with category "PLUMBING", priority "HIGH"
And I attach a photo of the leaking faucet
And I add description "Bathroom sink faucet leaking continuously, guest complained"
Then a maintenance request is created with status OPEN
And the engineering team receives a notification
And the request appears in the Maintenance dashboard with the photo
Scenario: Critical maintenance puts room out of order
Given a maintenance request for Room 515 is category "ELECTRICAL" with priority "URGENT"
And the description indicates "Exposed wiring near bathroom - safety hazard"
When the supervisor marks the room as OUT_OF_ORDER
Then Room 515 status changes to OOO on both HK and FD status boards
And the reservation service is notified to prevent new bookings for Room 515
And existing reservations for Room 515 are flagged for room reassignment
Scenario: Track maintenance resolution
Given a maintenance request for Room 208 was created 3 hours ago
When the maintenance engineer marks it as RESOLVED with note "Faucet washer replaced"
Then the supervisor receives a notification to verify the fix
And upon verification, the request status changes to CLOSED
And Room 208 can be cleaned and made available again
US-006-009: Linen Inventory Management
As an Executive Housekeeper, I want to track linen inventory (bed sheets, towels, pillow covers, duvet covers) with par levels, So that I can ensure adequate stock for daily operations and plan procurement before shortages occur.
Priority: P0 | Points: 5 | Sprint: 6 | Status: Built
Implementation Status
GET/POST/PATCH /api/v1/housekeeping/linen-inventory manages linen types with current stock, par level (ideal stock), and reorder point. Dashboard shows inventory table with stock vs. par comparison, color-coded rows (red below reorder point, yellow below par, green at/above par). Supports multiple linen categories: BED_SHEET, PILLOW_COVER, DUVET_COVER, BATH_TOWEL, HAND_TOWEL, FACE_TOWEL, BATH_MAT, BATHROBE.
Acceptance Criteria
Scenario: View linen inventory with par comparison
Given I am the Executive Housekeeper for "Hotel Oberoi Mumbai"
And the property has 200 rooms
When I navigate to Housekeeping > Linen Inventory
Then I see a table with all linen types, current stock, par level, and reorder point
And "Bath Towels" shows 380 current / 600 par / 400 reorder (highlighted yellow)
And "Bed Sheets" shows 250 current / 400 par / 300 reorder (highlighted red - below reorder)
And a summary card shows "3 items below reorder point"
Scenario: Add new linen stock after procurement
Given "Bed Sheets (King)" current stock is 250
When I record a new stock receipt of 200 bed sheets from vendor "Mumbai Linen Suppliers"
Then the current stock updates to 450
And a linen movement record is created with type "RECEIVED", quantity 200
And the movement includes vendor name, purchase order reference, and receipt date
Scenario: Configure par levels for a property
Given I am setting up linen par levels for a newly onboarded 100-room property
When I set Bath Towel par level to 300 (3 per room) and reorder point to 200
Then the system saves the configuration
And future inventory checks will use these thresholds for alerts
And the par level accounts for laundry turnaround time (typically 24 hours in India)
US-006-010: Linen Movement Tracking
As an Executive Housekeeper, I want to track every linen movement (issued to floors, returned from rooms, sent to laundry, damaged, discarded), So that I have a complete audit trail and can calculate linen loss rate accurately.
Priority: P0 | Points: 3 | Sprint: 6 | Status: Built
Implementation Status
POST /api/v1/housekeeping/linen-movements records movements with type (ISSUED, RETURNED, DAMAGED, DISCARDED, WASHED, IN_LAUNDRY), linenTypeId, quantity, staffId, and notes. Dashboard shows movement log with date filters and type filters. Running balance calculated from movements. Movement types map to Indian hotel operations: ISSUED (morning floor distribution), IN_LAUNDRY (sent to dhobi/laundry vendor), WASHED (returned from laundry), DAMAGED (stained/torn, needs write-off).
Acceptance Criteria
Scenario: Record morning linen issuance to floor
Given it is 7:00 AM shift start at "ITC Grand Chola Chennai"
And Floor 4 housekeeper "Lakshmi" needs linen for 15 rooms
When the linen room attendant issues 30 bath towels, 15 bed sheets, 30 hand towels
Then 3 linen movement records are created with type ISSUED
And each record references staffId (Lakshmi) and floor (4)
And the available stock decreases by the issued quantities
Scenario: Track laundry send-out and return
Given 200 bath towels and 150 bed sheets are collected for laundry
When I record movements with type IN_LAUNDRY for both items
Then the stock shows 200 towels and 150 sheets "In Laundry"
And when the laundry vendor returns them next day, I record type WASHED
And if only 195 towels return, I record 195 as WASHED and 5 as DAMAGED
And the linen loss is tracked as 5 units (2.5% loss rate)
Scenario: Generate linen movement report for audit
Given the month-end linen audit is due
When I generate the Linen Movement Report for February 2026
Then the report shows opening stock, total issued, returned, damaged, discarded, closing stock
And calculates monthly loss rate per linen type
And highlights any linen type with loss rate > 3% in red
And the report can be exported to Excel for the accounts team
US-006-011: Minibar Par Level Management
As a housekeeping supervisor, I want to manage minibar par levels (standard stocking per room type) and track consumption, So that minibars are restocked efficiently and consumption is accurately posted to guest folios with GST.
Priority: P1 | Points: 5 | Sprint: 6 | Status: Built
Implementation Status
Minibar items configured per room type with par level, selling price (inclusive of GST), and cost price. GET /api/v1/housekeeping/minibar/rooms/:roomId returns current minibar state vs. par. Consumption recorded on housekeeping rounds and posted to guest folio via integration with billing service. Dashboard shows minibar management with room-wise consumption log.
Acceptance Criteria
Scenario: Configure minibar par level for room type
Given I am setting up minibar for "Deluxe Room" type
When I configure the par as: 2x Water Bottles (Rs 100 each + 18% GST), 2x Cola (Rs 150 + 18% GST), 1x Chips (Rs 200 + 12% GST), 2x Beer (Rs 350 + 28% GST)
Then all Deluxe Rooms default to this minibar configuration
And selling prices include GST with correct slab (5%/12%/18%/28%)
And the total minibar par value is displayed per room
Scenario: Record minibar consumption during room cleaning
Given housekeeper "Anita" is cleaning Room 706 (occupied, stayover)
And Room 706 minibar par is 2 Water, 2 Cola, 1 Chips, 2 Beer
When Anita records consumption: 1 Water, 2 Beer consumed
Then the consumption is logged with timestamp, room, guest, and staff
And charges of Rs 100 + Rs 700 = Rs 800 (plus applicable GST) are posted to Room 706 folio
And the minibar restock list shows Room 706 needs: 1 Water, 2 Beer
Scenario: Generate minibar restock list for floor
Given it is evening turndown service time
When the supervisor generates the minibar restock list for Floor 7
Then a consolidated list shows total items needed across all occupied rooms on Floor 7
And the list is grouped by item for efficient picking from store
And items are sorted by quantity needed (highest first)
US-006-012: Lost & Found Register
As a housekeeper, I want to log items found in rooms after guest checkout, So that the hotel maintains a proper lost & found register and can return items to guests.
Priority: P1 | Points: 3 | Sprint: 6 | Status: Built
Implementation Status
POST /api/v1/housekeeping/lost-found records item with description, roomId, foundByStaffId, photo, category (CLOTHING, ELECTRONICS, JEWELRY, DOCUMENTS, TOILETRIES, OTHER), and storage location. Auto-links to last guest who checked out of the room. Dashboard shows lost & found register with search, status tracking (FOUND, NOTIFIED, CLAIMED, UNCLAIMED, DISPOSED), and guest contact actions.
Acceptance Criteria
Scenario: Log a found item after checkout
Given housekeeper "Ravi" finds a laptop charger in Room 310 after guest checkout
When he logs the item with category "ELECTRONICS", description "Dell laptop charger, black"
And takes a photo of the item
Then the item is registered with status FOUND
And auto-linked to the last guest "Mr. Sharma" who checked out of Room 310 at 11:00 AM
And stored location is recorded as "Housekeeping Office, Shelf B3"
Scenario: Notify guest about found item
Given a gold earring was found in Room 502 and linked to guest "Mrs. Patel"
When the front office contacts Mrs. Patel via the registered email/phone
And records the contact attempt in the system
Then the item status changes to NOTIFIED
And a timeline shows all contact attempts with dates
And if guest confirms, the item status moves to CLAIMED with shipping/pickup details
Scenario: Dispose unclaimed items per hotel policy
Given 15 items have been in NOTIFIED status for more than 90 days
When the system flags them for review based on the hotel's 90-day retention policy
Then the supervisor can bulk-update status to DISPOSED
And a disposal log is generated with item details, original guest, and disposal date
And high-value items (JEWELRY, ELECTRONICS) require Manager approval before disposal
US-006-013: Auto-Reorder Alerts (Linen/Amenities)
As an Executive Housekeeper, I want to receive automatic alerts when linen or amenity stock falls below the reorder threshold, So that I can initiate procurement before stock runs out and avoid operational disruption.
Priority: P2 | Points: 5 | Sprint: 10 | Status: Not Started
Implementation Status
Linen inventory tracks current stock and reorder point, but no automated alerting mechanism exists. The notification service has push notification and email capabilities, but no integration with housekeeping inventory thresholds. No Kafka event emitted on stock threshold breach. Procurement team must manually check the inventory dashboard.
Acceptance Criteria
Scenario: Trigger alert when stock falls below reorder point
Given "Bath Towels" has a reorder point of 200
And current stock is 210
When a linen movement records 15 towels as DAMAGED
And updated stock becomes 195 (below reorder point of 200)
Then a Kafka event "housekeeping.inventory.below_reorder" is published
And the notification service sends a push notification to the Executive Housekeeper
And an email is sent with subject "Low Stock Alert: Bath Towels (195/200 reorder point)"
And the inventory dashboard shows a red alert badge on the Linen section
Scenario: Suppress duplicate alerts for same item
Given an alert was already sent for "Bath Towels" being below reorder point
And the stock has not been replenished
When another movement further reduces the stock
Then no duplicate alert is sent within 24 hours
But if stock drops below 50% of reorder point (critical), an escalation alert is sent to the General Manager
Scenario: Clear alert when stock is replenished
Given "Bath Towels" stock was at 195 (below 200 reorder point)
When a new stock receipt brings the total to 450
Then the active alert is automatically cleared
And the dashboard alert badge is removed
And a resolution notification is sent: "Bath Towels restocked (450 units)"
US-006-014: Discrepancy Report (FD vs HK)
As a Front Office Manager, I want to see a report highlighting rooms where Front Desk status and Housekeeping status do not match, So that I can resolve mismatches quickly and prevent guest check-in into unclean rooms.
Priority: P1 | Points: 5 | Sprint: 7 | Status: Partial
Implementation Status
Basic report exists comparing FD occupancy status (Occupied, Vacant) with HK cleaning status (Clean, Dirty). Displays as a table. Gap: No visual highlighting or color-coding for mismatches. No time-based analysis showing how long a mismatch has persisted. No auto-resolution suggestions (e.g., "Room 305: FD says Vacant, HK says Occupied -- likely late checkout not updated"). No real-time mismatch alert when discrepancy is detected. Report is static (manual refresh).
Acceptance Criteria
Scenario: View discrepancy report with visual highlighting
Given there are 5 rooms with FD/HK status mismatch at 2:00 PM
When I open the Discrepancy Report
Then mismatched rooms are highlighted in red rows
And each row shows: Room Number, FD Status, HK Status, Mismatch Type, Duration, Suggested Action
And Room 305 shows: FD=Vacant, HK=Occupied, Duration=45 min, Suggestion="Verify checkout completed"
And the report auto-refreshes every 60 seconds
Scenario: Resolve a discrepancy
Given Room 412 shows FD=Occupied but HK=Vacant (guest checked out but FD not updated)
When I click "Resolve" on Room 412
And select resolution "Update FD Status to Vacant"
Then FD status is corrected to Vacant
And the discrepancy is removed from the active list
And logged in the discrepancy history with resolver name and resolution action
Scenario: Generate daily discrepancy summary
Given it is end of day (11:00 PM night audit)
When the system generates the daily discrepancy summary
Then the report shows: total discrepancies detected (18), resolved (16), unresolved (2)
And average resolution time (12 minutes)
And most frequent mismatch type ("Late checkout not updated" - 7 occurrences)
And the report is emailed to the Front Office Manager and General Manager
US-006-015: Housekeeping KPI Dashboard
As a General Manager, I want to see housekeeping performance KPIs on a dashboard with trends, So that I can evaluate operational efficiency, identify bottlenecks, and optimize staffing.
Priority: P1 | Points: 5 | Sprint: 7 | Status: Built
Implementation Status
GET /api/v1/housekeeping/kpis returns calculated metrics: rooms cleaned per hour per staff, average turnaround time, inspection pass rate, task completion rate, overdue task count. Dashboard renders KPI cards with sparkline trends and detailed charts (bar chart by staff, line chart by date, pie chart by task type). Date range filter and shift filter supported.
Acceptance Criteria
Scenario: View daily KPI summary
Given it is 6:00 PM and the day shift is ending
When I open the Housekeeping KPI Dashboard
Then I see summary cards: Rooms Cleaned (87), Avg Turnaround (26 min), Inspection Pass Rate (91%), Overdue Tasks (3)
And each card shows a comparison arrow (up/down) vs. last week same day
And "Avg Turnaround 26 min" shows a green up arrow (was 31 min last week)
Scenario: Drill down to staff-level performance
Given I want to review individual performance for the morning shift
When I click on the "Rooms Cleaned" KPI card
Then I see a bar chart showing rooms cleaned per housekeeper
And "Priya" leads with 16 rooms, "Lakshmi" has 14, "Ravi" has 11
And I can click on "Ravi" to see his task timeline and identify delays
Scenario: View monthly trend report
Given I select date range "February 2026"
When the KPI dashboard loads the monthly view
Then a line chart shows daily rooms-cleaned trend across the month
And weekends (high checkout days) show peaks of 95+ rooms
And weekdays show baseline of 60-70 rooms
And a secondary axis shows staffing level per day for correlation
US-006-016: Auto-Task Generation on Checkout
As a housekeeping supervisor, I want cleaning tasks to be automatically created when a guest checks out, So that room turnaround starts immediately without waiting for manual task creation.
Priority: P2 | Points: 5 | Sprint: 10 | Status: Not Started
Implementation Status
Currently, housekeeping tasks are created manually by the supervisor or in bulk at shift start. The front desk service emits a Kafka event frontdesk.checkout.completed with roomId and guestId, but the housekeeping service does not consume this event to auto-create tasks. The infrastructure (Kafka consumer in housekeeping-service) exists but the specific handler for auto-task-creation is not implemented.
Acceptance Criteria
Scenario: Auto-create cleaning task on guest checkout
Given guest "Mr. Kumar" checks out of Room 405 at 11:30 AM
When the front desk processes the checkout
And a Kafka event "frontdesk.checkout.completed" is emitted with roomId=405
Then the housekeeping service consumes the event
And auto-creates a CLEANING task for Room 405 with priority NORMAL
And assigns it to the housekeeper responsible for Floor 4 (if configured)
And Room 405 status changes to DIRTY on the room status board
Scenario: VIP arrival triggers high-priority cleaning task
Given Room 405 has a VIP check-in scheduled at 2:00 PM (in 2.5 hours)
And the current guest checks out at 11:30 AM
When the auto-task is generated
Then the task priority is auto-elevated to HIGH (because next guest is VIP arriving same day)
And the task notes include "VIP arrival at 2:00 PM - Mr. Reddy (Platinum member)"
And the supervisor receives a highlighted notification about the VIP turnaround
Scenario: Extended stay does not trigger checkout task
Given Room 312 guest was expected to checkout today but has extended by 2 nights
When the reservation is modified to extend the departure date
Then no CLEANING task is auto-created for Room 312
But a TURNDOWN task may be auto-created if the property has turndown service enabled
And the stayover cleaning schedule remains intact for Room 312