Housekeeping Workflow (Hotels)

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €29/mo; room-status dashboard, inspector sign-off, maintenance alerts

Generated from docs/plan/paid/housekeeping-workflow/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Hotel staff need real-time tracking of room status (clean/dirty/occupied/maintenance) and check-in/out workflows. This feature provides a room dashboard, inspector sign-off, maintenance alerts, and audit trail for housekeeping operations.

The problem

My housekeeping staff doesn’t know which rooms are dirty or ready to let. Checkout delays happen because status changes aren’t visible, and there’s no way to track maintenance issues or no-shows.

What it does

• Room status entity: occupied → checkout-expected → inspecting → clean-ready / needs-maintenance
• Status transitions: each transition logged with timestamp, who made the change, and optional notes
• No-show detection: checkout time passes without status change to checkout-expected; flag the room
• Maintenance alert: any room can be flagged ‘needs-maintenance’ with description (broken toilet, AC, etc.); maintenance staff see queue
• Inspector sign-off: after cleaning, inspector visits room, confirms it’s guest-ready (photo optional), status → clean-ready
• Housekeeping dashboard: card per room showing current status, time in current state, next action, alerts
• Mobile-first UI: staff taps room to check in, marks dirty, marks clean, calls maintenance
• Audit trail: every status change, who changed it, when, notes; searchable by room/date/staff member
• Reporting: occupancy timeline, average checkout-to-clean time, maintenance request volume, staff productivity (tasks completed per shift)
• API endpoints: GET room status, POST status change, GET maintenance queue, POST maintenance request

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• PMS integration (property management system) — we do not sync with Opera, Amadeus, or Opera; room status is canonical in AstroBaaS only
• Housekeeping mobile app — this is a web UI in responsive design; native iOS/Android app is separate
• Linen/supply inventory tracking — what sheets are where is a separate operational system
• Guest messaging (SMS/push to room phone) — alerting housekeeping happens via the web UI only; no outbound SMS
• Automatic checkout via PMS — AstroBaaS does not read PMS calendars; checkout time is manual input or webhook from PMS

Data model

New entity: Room {id, room_number, floor, status, current_guest_checkout_time (nullable), last_status_changed_at, created_at, updated_at}. New entity: RoomStatusChange {id, room_id, from_status, to_status, changed_by_staff_id, changed_at, notes (nullable)}. New entity: MaintenanceRequest {id, room_id, description, priority, status, reported_by_staff_id, assigned_to_staff_id (nullable), resolved_at, created_at}. Schema migration across all three drivers. Assume existing staff/user entity.

API

• GET /api/rooms — list all rooms with current status (staff only)
• GET /api/rooms/:id — fetch room detail with status history
• PATCH /api/rooms/:id/status — update room status (staff only; validates state machine)
• POST /api/rooms/:id/maintenance — create maintenance request
• GET /api/maintenance — list open maintenance requests (priority order)
• PATCH /api/maintenance/:id — update maintenance (mark resolved)
• GET /api/housekeeping/dashboard — summary: occupied, dirty, clean, inspecting, maintenance counts
• GET /api/housekeeping/audit — status changes for date range, filterable by room/staff

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Housekeeping dashboard: large grid or cards, one per room, color-coded by status (green=clean-ready, yellow=inspecting, red=dirty, blue=occupied). Click room card to see history and change status. Maintenance queue sidebar: list of open requests, filter by priority, assign to staff, mark resolved. Audit log page: searchable by date/room/staff, export to CSV. Reports tab: occupancy chart, average clean time, staff productivity (completion count per shift).

The seam — why this is paid

Core owns the room entity, status state machine, audit trail, and REST API. Paid layer owns PMS integrations (polling for checkout times, syncing occupancy), mobile app development (native iOS/Android for staff with offline support), and support for complex workflows (multiple inspectors, linen tracking, housekeeping scheduling).

Support commitment: mobile app for staff, real-time status sync, incident audit trail

Dependencies

• Staff/user entity (already shipped in core)
• Audit log system (already shipped in core)
• Real-time notifications or WebSocket support for status updates (assume available or a separate dependency)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• A room can be created with room number and floor; status defaults to ‘clean-ready’
• Status can be changed: clean-ready → occupied → checkout-expected → inspecting → clean-ready; each step is validated
• Each status change is logged with timestamp, staff member ID, and optional notes
• A room that reaches checkout-expected but is not cleaned within 2 hours is flagged as ‘at-risk’ (visual warning only, no auto-action)
• A maintenance request can be created for a room; it appears in the maintenance queue with priority
• Inspector must confirm clean status; status cannot → clean-ready without inspection sign-off
• Audit log returns all status changes for a room, sorted by date, with staff member name and notes
• Dashboard shows count of rooms in each status and average time in ‘inspecting’ state

Risks

Status changes must be sequenced — if two staff members tap ‘mark clean’ at the same time, only one should succeed (row lock during update). No-show detection requires knowing expected checkout time; if checkout time is wrong in the system, no-show flag fires incorrectly. Audit trail can grow large for busy hotels; queries must be indexed by date and room. Inspector sign-off without photo means no verification of actual cleanliness; photo storage (optional) is a separate feature but valuable for disputes.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.