EP-005D: Ancillary Front Desk Services
Parent Epic: EP-005 Front Desk Operations Split Note: EP-005 has been split into sub-epics EP-005A, EP-005B, EP-005C, EP-005D. This file covers concierge, wake-up calls, PBX/phone charges, guest messages, safe deposit, in-room dining relay, service recovery, forex, UPI QR, and cash management.
| Field | Value |
|---|---|
| Epic ID | EP-005D |
| Epic Name | Ancillary Front Desk Services |
| Parent Epic | EP-005 Front Desk Operations |
| Owner | Front Desk Module Lead |
| Created | 2026-03-27 |
| Last Updated | 2026-03-27 |
| Status | In Progress / Partial |
| Priority | P2-P3 |
1. Business Objective
Front desk is more than check-in and billing — it is the guest's 24/7 service hub. The ancillary services in this sub-epic directly affect guest satisfaction scores and ancillary revenue capture. Missed wake-up calls, un-logged concierge requests, and unrecorded phone charges are the most common complaint categories in Indian hotel reviews. This sub-epic captures the long tail of front desk operations that, collectively, account for ~15% of guest touchpoints.
2. Audience
| Role | Interaction |
|---|---|
| Front Desk Agent | Log concierge requests, schedule wake-up calls, record PBX charges |
| Night Auditor | Reconcile phone charge logs, close cash drawer, record petty cash |
| Guest | Request services via phone, kiosk, or in-room tablet |
| Manager | Service recovery escalation, forex rate management, cash drawer approval |
3. Scope
3.1 In Scope
- Concierge request log: taxi booking, restaurant reservation, sightseeing, parcel delivery
- Wake-up call scheduling: single, recurring, and batch (group wake-up calls)
- Wake-up call execution: automated PBX dial or manual reminder (fallback)
- PBX / telephone integration: log incoming/outgoing call duration and charge per hotel tariff
- Phone charge posting to guest folio
- Guest messages and notices: receive (from reception), view (by agent), deliver to room
- In-room messaging via WhatsApp/SMS (through EP-014 notification service)
- Safe deposit box: assign, release, log access
- In-room dining relay: receive order at front desk, relay to POS/kitchen (pending full POS integration)
- Service recovery: log guest complaint, assign resolution action, track SLA, escalate
- Forex / currency exchange: manual rate entry, exchange transaction log, conversion receipt
- UPI QR code generation for service charges (ancillary payments outside folio)
- Cash drawer management: open/close shift, cash-in, cash-out, petty cash log, discrepancy report
- Lost-and-found log: item description, date, room, status (held/claimed/donated)
3.2 Out of Scope
- Full POS order management (EP-007)
- Housekeeping task dispatch (EP-006)
- Spa / wellness bookings (EP-016)
- Banquet event services (EP-008)
- Loyalty / CRM-driven concierge automation (EP-010)
4. Current Implementation Status
4.1 Backend — frontdesk-service
| Controller / Endpoint | Status | Notes |
|---|---|---|
POST /wakeup-calls | Partial | Scheduling works; PBX execution is mock-only |
GET /wakeup-calls | Built | List pending and completed wake-up calls |
PATCH /wakeup-calls/:id/complete | Built | Mark executed |
POST /guest-messages | Partial | Create works; delivery confirmation not tracked |
GET /guest-messages | Built | List by room / guest |
POST /concierge | Not Started | No controller yet |
GET /concierge | Not Started | - |
PATCH /concierge/:id/status | Not Started | - |
POST /pbx/charges | Partial | Tariff table exists; auto-capture from PBX not wired |
POST /safe-deposit | Not Started | - |
POST /service-recovery | Not Started | - |
POST /forex/exchange | Not Started | - |
GET /forex/rates | Not Started | - |
POST /cash-drawer/shift | Partial | Open/close; balance reconciliation incomplete |
POST /cash-drawer/petty-cash | Not Started | - |
POST /lost-found | Not Started | - |
| In-room dining relay to POS | Not Started | Schema defined; POS integration pending |
4.2 Dashboard — 02-hmp-web-dashboard
| Component | Status | Notes |
|---|---|---|
| Guest Messages UI | Partial | Display works; send/schedule needs work |
| Wake-Up Calls UI | Partial | List view only; scheduling form not built |
| Concierge UI | Not Started | - |
| Service Recovery UI | Not Started | - |
| Cash Drawer UI | Not Started | - |
| Forex Exchange UI | Not Started | - |
| Lost & Found UI | Not Started | - |
5. Gap Analysis
| # | Gap | Impact | Effort | Priority |
|---|---|---|---|---|
| 1 | Concierge request log controller completely missing | Medium | M | P2 |
| 2 | PBX auto-charge capture not wired (manual entry only) | Medium | L | P3 |
| 3 | In-room dining relay to POS not built | Medium | L | P2 |
| 4 | Service recovery (complaint log + SLA) has no controller | Medium | M | P2 |
| 5 | Forex management entirely missing | Medium | M | P2 |
| 6 | Cash drawer petty cash log missing | Low | S | P2 |
| 7 | Safe deposit box log missing | Low | S | P3 |
| 8 | Lost & found log missing | Low | S | P3 |
6. User Stories
| Story ID | Title | Priority | Points | Sprint | Status |
|---|---|---|---|---|---|
| US-005-18 | PBX / Wake-Up Calls | P3 | 8 | 6 | Partial |
| US-005-19 | Guest Messages & Notices | P2 | 5 | 5 | Partial |
| US-005-20 | In-Room Dining Order Relay | P2 | 8 | 5 | Not Started |
| US-005D-01 | Concierge Request Log | P2 | 5 | 5 | Not Started |
| US-005D-02 | Service Recovery & Complaint Tracking | P2 | 8 | 5 | Not Started |
| US-005D-03 | Forex / Currency Exchange | P2 | 5 | 5 | Not Started |
| US-005D-04 | Cash Drawer & Petty Cash Management | P2 | 5 | 5 | Partial |
| US-005D-05 | Safe Deposit Box Log | P3 | 3 | 6 | Not Started |
| US-005D-06 | Lost & Found Log | P3 | 3 | 6 | Not Started |
| US-005D-07 | UPI QR for Ancillary Payments | P2 | 3 | 5 | Partial |
7. Detailed User Stories
US-005-18: PBX / Wake-Up Calls
As a Front Desk Agent, I want to schedule wake-up calls for guests and have the system either automatically dial via PBX or remind the night agent to call manually, So that guests are reliably woken up and telephone charges are automatically posted to their folio.
Priority: P3 | Points: 8 | Sprint: 6 | Status: Partial
Implementation Status
Wake-up call scheduling (POST /wakeup-calls) is implemented. Automated PBX execution is mock-only; real PBX driver not tested. Phone charge tariff table exists but auto-capture from PBX CDR is not implemented — charges must be entered manually.
Acceptance Criteria
Scenario: Schedule and execute wake-up call
Given guest "Suresh Mehta" in room "312" requests wake-up at 06:30
When the agent creates a wake-up call for room 312 at 06:30
Then at 06:30 the system dials room 312 via PBX (or alerts the night agent)
And the wake-up call is marked "COMPLETED" with actual time
And a log entry is created: "Wake-up call, room 312, 06:30, completed 06:31"
Scenario: Failed wake-up call retry
Given a wake-up call at 06:30 received no answer
Then the system automatically retries at 06:35
And if the second attempt fails, an alert is sent to the front desk agent
US-005-19: Guest Messages & Notices
As a Front Desk Agent, I want to log, view, and relay messages for guests (e.g., "Your car has arrived"), So that guests receive timely communications during their stay.
Priority: P2 | Points: 5 | Sprint: 5 | Status: Partial
Implementation Status
POST /guest-messages creates a message record. Display in dashboard works. Delivery to guest via WhatsApp/SMS through notification service not yet wired. Scheduled future-delivery not implemented.
Acceptance Criteria
Scenario: Leave a message for a guest
Given guest "Priya Kapoor" is in room "205"
When the agent logs message: "Package received at reception for Ms. Kapoor"
Then the message appears on the in-house board for room 205
And an optional SMS is sent to the guest's registered mobile
Scenario: Scheduled message (pre-departure)
Given guest checks out tomorrow at 10:00
When the agent schedules: "Reminder: checkout is at 11:00 — enjoy your breakfast!" for 09:00 tomorrow
Then the message is dispatched at 09:00 via SMS/WhatsApp
US-005D-01: Concierge Request Log
As a Front Desk Agent, I want to log concierge requests (taxi, restaurant booking, sightseeing, courier), track their status, and note the outcome, So that no guest request falls through the cracks and the hotel can measure concierge service performance.
Priority: P2 | Points: 5 | Sprint: 5 | Status: Not Started
Implementation Notes
- New
ConciergeModulein frontdesk-service POST /concierge—{ guestId, roomId, type, description, requestedAt, dueBy }- Types: TAXI, RESTAURANT_RESERVATION, SIGHTSEEING, COURIER, LAUNDRY_PICKUP, OTHER
- Statuses: OPEN → IN_PROGRESS → COMPLETED / CANCELLED
PATCH /concierge/:id/status— update with resolution notes- Optional: charge posting to guest folio if a billable service is rendered
Acceptance Criteria
Scenario: Log taxi request
Given guest "Amit Sharma" in room "401" needs a taxi to airport at 14:00
When the agent creates: type=TAXI, due=14:00, description="Taxi to IGI Airport T3"
Then the request appears on the concierge board with status "OPEN"
And the agent can mark it "IN_PROGRESS" and then "COMPLETED" with cab number
Scenario: View outstanding concierge requests at shift handover
When the outgoing agent opens the concierge board
Then all OPEN and IN_PROGRESS requests are listed with guest name, room, and deadline
And overdue requests are highlighted in red
US-005D-02: Service Recovery & Complaint Tracking
As a Front Desk Manager, I want to log guest complaints, assign a resolution action, set an SLA, and track whether the complaint was resolved before checkout, So that service failures are documented, acted upon, and used for training.
Priority: P2 | Points: 8 | Sprint: 5 | Status: Not Started
Implementation Notes
- New
ServiceRecoveryModulein frontdesk-service POST /service-recovery—{ guestId, reservationId, category, description, severity, assignedTo }- Categories: HOUSEKEEPING, MAINTENANCE, F&B, NOISE, AC_TEMPERATURE, BILLING, OTHER
- SLA by severity: CRITICAL=1h, HIGH=2h, MEDIUM=4h, LOW=24h
- On SLA breach: escalate to Front Desk Manager (Kafka event → notification)
- Resolution posts a "service recovery" comp (e.g., free breakfast) to the folio with manager approval
Acceptance Criteria
Scenario: Log and resolve AC complaint
Given guest "Riya Desai" in room "506" reports "AC not cooling"
When agent logs complaint: category=AC_TEMPERATURE, severity=HIGH
Then SLA of 2 hours is set
And maintenance is notified via Kafka event
When maintenance resolves the issue within 1 hour
And agent marks complaint RESOLVED with note "AC filter replaced"
Then complaint is closed and no SLA breach is recorded
Scenario: SLA breach escalation
Given a HIGH severity complaint with 2-hour SLA
When 2 hours pass without resolution
Then an escalation alert is sent to the Front Desk Manager
And the complaint is flagged "SLA BREACHED" in red
US-005D-03: Forex / Currency Exchange
As a Front Desk Agent, I want to process currency exchange transactions for guests (e.g., USD to INR), generate a forex receipt, and log the transaction for audit compliance, So that the hotel provides a value-added service while maintaining regulatory compliance (RBI FFMC guidelines).
Priority: P2 | Points: 5 | Sprint: 5 | Status: Not Started
Implementation Notes
- New
ForexModulein frontdesk-service GET /forex/rates— manual rates set by manager (not live feed; hotels typically use fixed daily rates)POST /forex/exchange—{ guestId, fromCurrency, toCurrency, fromAmount, rateApplied }→ calculatestoAmount- Generates forex receipt (ESC/POS print or PDF)
- Logs transaction for RBI compliance (date, guest passport, amount, rate, INR equivalent)
- Optional: post service fee to guest folio
Acceptance Criteria
Scenario: Exchange USD to INR
Given today's hotel forex rate is USD 1 = INR 83.50
And guest "John Smith" presents USD 200
When the agent enters: fromCurrency=USD, fromAmount=200
Then system calculates INR 16,700
And deducts hotel margin (e.g., 1%): INR 167
And disburses INR 16,533 to guest
And prints a forex receipt with guest passport number and transaction ID
US-005D-04: Cash Drawer & Petty Cash Management
As a Night Auditor, I want to open and close a cash drawer shift with an opening and closing balance, log petty cash disbursements, and generate a discrepancy report, So that the front desk cash is fully reconciled at end of shift.
Priority: P2 | Points: 5 | Sprint: 5 | Status: Partial
Implementation Status
POST /cash-drawer/shift open/close exists. Petty cash entries and closing balance reconciliation are not yet implemented.
Acceptance Criteria
Scenario: Open and close cash drawer shift
Given the night auditor starts their shift at 23:00 with opening cash of INR 10,000
When they open a shift with opening balance INR 10,000
Then all cash transactions during the shift are recorded
When the shift closes at 07:00
Then the system calculates: opening + cash receipts - refunds - petty cash = expected closing balance
And the auditor enters actual physical count
And any discrepancy is highlighted for manager review
Scenario: Petty cash disbursement
Given the shift is open and INR 450 is paid for printer paper
When the agent logs: type=PETTY_CASH, amount=INR 450, description="Printer paper", approvedBy="Manager"
Then the petty cash log shows the entry
And the expected closing balance decreases by INR 450
8. Dependencies
| Dependency | Type | Epic / Service | Status |
|---|---|---|---|
| Reservation / guest data | Upstream | EP-003, EP-004 | Available |
| Auth (manager role for approvals) | Upstream | EP-001 / auth | Available |
| Notification service (WhatsApp/SMS) | Downstream | EP-014 / notification | Available |
| Folio / charges (EP-005B) | Sibling | EP-005B / frontdesk | Available |
| POS service (in-room dining relay) | Peer | EP-007 / pos | Not Ready |
| PBX hardware (wake-up calls) | Infra | External PBX vendor | Mock only |
| ESC/POS printer | Infra | libs/common | Built |
| Kafka event bus | Infra | Docker / Kafka | Available |
9. Acceptance Criteria (Sub-Epic Level)
- AC-EP-005D-01: Wake-up calls scheduled by agents are executed (via PBX or manual alert) with a logged completion status; missed calls trigger an automatic retry and agent alert.
- AC-EP-005D-02: Guest messages and concierge requests have an auditable status trail from creation to resolution.
- AC-EP-005D-03: Service recovery complaints with SLA >= HIGH severity trigger escalation notifications on breach.
- AC-EP-005D-04: Cash drawer shift close produces a reconciliation report with opening balance, transactions, petty cash, and discrepancy.
- AC-EP-005D-05: Forex exchange transactions generate a printed receipt and a regulatory-compliant log entry.
- AC-EP-005D-06: In-room dining orders logged at the front desk are relayed to the POS/kitchen within 60 seconds.
10. Technical Notes
- Service files location:
01-hmp-backend/apps/frontdesk-service/src/— new modules:concierge/,service-recovery/,forex/,lost-found/,safe-deposit/ - Wake-up call controller:
01-hmp-backend/apps/frontdesk-service/src/wakeup/wakeup.controller.ts - Guest messages:
01-hmp-backend/apps/frontdesk-service/src/messages/messages.controller.ts - PBX integration:
01-hmp-backend/libs/integrations/— PBX adapter stub; real integration requires vendor-specific CDR feed - Cash drawer:
01-hmp-backend/apps/frontdesk-service/src/cash-drawer/— partial implementation - ESC/POS printer:
01-hmp-backend/libs/common/src/lib/printer/— folio receipt template reusable for forex receipts - In-room dining relay will publish Kafka event
order.inRoomDiningReceivedconsumed by pos-serviceKitchenGateway(Phase 2 WebSocket deliverable) - Service recovery Kafka event:
SERVICE_RECOVERY_ESCALATED(new event type, add to Phase 6.3 event constants)