Skip to main content

J-22 — Cleaning Reveals Maintenance Issue

One-liner: During cleaning, housekeeper finds a broken fixture; raises a maintenance ticket; room moves out of inventory until fixed.

1. Purpose​

During cleaning, housekeeper finds a broken fixture (e.g., shower drips, AC fault). Housekeeper raises a maintenance ticket inline; the room moves to "Out of order" until fixed; if there's an arriving guest, front desk is notified to reaccommodate. Outcome: rapid issue triage; no faulty room sold; clean coordination across HK, maintenance, front desk.

2. Persona Context​

  • Personas: Housekeeper (reporter); Maintenance (executor); Front Desk (reaccommodation).
  • Surface: Electron Desktop.
  • Primary BFF: bff-backoffice-service.
  • Backing services: maintenance-service, housekeeping-service, front-desk-service, booking-service, audit-service.
  • Preconditions: Maintenance team configured; reaccommodation policy set.
  • Trigger: Housekeeper clicks "Report issue" inline on a task.

3. Entry Points​

#EntryNotes
1"Report issue" inline on cleaning taskDefault
2Front desk-initiated "Mark out of order"Adhoc

4. Screen-by-Screen Flow​

4.1 ReportIssueModal (Housekeeper)​

  • Layout: Issue type (plumbing / HVAC / electrical / furniture / other), severity (low / medium / high / critical), description, photo upload, "Mark room out of order" toggle (auto-true for high/critical).
  • Components: Form, IssueTypeSelect, SeveritySelect, PhotoUpload.
  • Offline: Editable; queued.
  • AI: Phase 2 — issue classification from photo.
  • Errors: Validation per field.
  • Loading: Submit <= 500 ms.
  • A11y: Field labels; severity announced.
  • RTL: Mirror.
  • Perf: <= 500 ms.
  • Telemetry: frontend.maintenance.issue_reported { type, severity }.

4.2 RoomStatusOutOfOrderBanner​

  • Layout: Room tile shows "Out of order" pill; details panel shows ticket id, ETA, technician.
  • Components: RoomStatusPill, OooDetailsPanel.
  • Offline: Local state.
  • AI: None.
  • Errors: n/a.
  • Loading: Sub-second.
  • A11y: Pill announced; details labelled.
  • RTL: Mirror.
  • Perf: SSE update <= 1 s.
  • Telemetry: frontend.room.ooo_set { roomId }.

4.3 ReaccommodationPanel (Front Desk; if guest arriving)​

  • Layout: Affected reservation summary; alternative room suggestions (AI in P2); upgrade / downgrade pill; "Re-assign" CTA.
  • Components: ReservationCard, RoomAlternativesList, Button.
  • Offline: Reaccommodation deferred until online; banner with reason.
  • AI: P2 — alternative room suggestion.
  • Errors: No alternatives -> escalation modal.
  • Loading: <= 500 ms.
  • A11y: Alternatives are tab stops; rate impact announced.
  • RTL: Mirror.
  • Perf: <= 500 ms.
  • Telemetry: frontend.front_desk.reaccommodate { reservationId, newRoomId }.

4.4 MaintenanceWorkOrderScreen (Maintenance)​

  • Layout: Ticket detail; status pipeline (New / Scheduled / In Progress / Resolved); parts ordering placeholder; resolution notes; "Resolve & return to inventory" CTA.
  • Components: WorkOrderCard, StatusPipeline, Button.
  • Offline: Editable; queued.
  • AI: None.
  • Errors: Resolution requires confirmation.
  • Loading: Submit <= 500 ms.
  • A11y: Pipeline states announced.
  • RTL: Mirror.
  • Perf: <= 500 ms.
  • Telemetry: frontend.maintenance.work_order_resolved { ticketId }.

5. State Machine​

6. Data Requirements​

6.1 Server state​

  • POST /api/v1/maintenance/tickets (idempotent)
  • PATCH /api/v1/rooms/:id/status (idempotent; status=out_of_order)
  • POST /api/v1/front-desk/reaccommodate (idempotent)
  • PATCH /api/v1/maintenance/tickets/:id/status (idempotent)

6.2 Local persistence​

  • SQLite maintenance_tickets_local, room_status_local, outbox.

6.3 Idempotency​

  • All mutations carry X-Idempotency-Key.

7. AI Behavior​

n/a in P1; P2 — issue classification from photo + alternative room suggestion.

8. Offline Behavior​

  • Issue + OOO status local; reaccommodation deferred until online (with banner).
  • Maintenance work-order updates queued.

9. Error States​

ErrorTriggerUX shownRecoveryTelemetry
NO_ALTERNATIVE_ROOMSAll comparable rooms occupiedEscalation modalFront desk decidesfrontend.front_desk.no_alternatives
REACCOMMODATION_DEFERRED_OFFLINEOfflineBanner with reasonResolve on reconnectfrontend.front_desk.reaccom_deferred
RESOLUTION_REQUIRES_CONFIRMATIONValidationConfirm modalConfirmfrontend.maintenance.resolution_confirm

10. E2E Test Gates​

  • Composite gate G-OPS-1: report -> OOO -> ticket -> work order -> resolve -> back to inventory.
  • Reaccommodation arrival path.
  • Offline reaccommodation deferral.

11. Performance Requirements​

MetricTarget
Each action<= 500 ms p95
SSE update<= 1 s

12. Accessibility Requirements​

  • All keyboard-completable.
  • Status pipeline accessible.
  • Photo upload progress accessible.

13. Telemetry​

Frontend events​

  • frontend.maintenance.issue_reported { type, severity }
  • frontend.room.ooo_set { roomId }
  • frontend.front_desk.reaccommodate { reservationId, newRoomId }
  • frontend.maintenance.work_order_resolved { ticketId }

Domain events emitted​

  • melmastoon.maintenance.ticket.created.v1
  • melmastoon.room.status.changed.v1 (with out_of_order)
  • melmastoon.front_desk.reaccommodate.v1
  • melmastoon.maintenance.ticket.resolved.v1
  • melmastoon.audit.recorded.v1

14. Success Criteria​

  • No room sold while OOO.
  • Reaccommodation handled gracefully online; deferred clearly offline.
  • Maintenance pipeline complete; audit log records lifecycle.

References​