EP-005: Front Desk Operations
This epic has been split into sub-epics:
- EP-005A: Check-In / Check-Out Operations
- EP-005B: Folios & Billing
- EP-005C: Night Audit
- EP-005D: Ancillary Front Desk Services
This file is retained as the parent reference. New work should be tracked in the sub-epics above.
| Field | Value |
|---|---|
| Epic ID | EP-005 |
| Epic Name | Front Desk Operations |
| Owner | Front Desk Module Lead |
| Created | 2026-03-05 |
| Last Updated | 2026-03-05 |
| Status | In Progress |
| Priority | P0 - Critical |
1. Business Objective
Transform the front desk check-in experience from the current industry average of 8-12 minutes down to under 3 minutes through digital registration, automated folio management, and integrated night audit. This directly impacts guest satisfaction (first and last touchpoint), operational efficiency, and revenue capture accuracy. For a 100-room Indian hotel processing ~80 check-ins/day, this saves approximately 9-12 staff-hours daily and reduces billing errors that typically account for 2-4% revenue leakage.
2. Audience
| Role | Interaction |
|---|---|
| Front Desk Agent | Primary user: check-in/out, folio charges, room assignment, guest messages |
| Front Desk Manager | Night audit oversight, room moves, rate overrides, walk-in approvals |
| Guest | Express check-in (pre-arrival), registration card signature, e-invoice receipt |
3. Scope
3.1 In Scope
- Standard check-in with Aadhaar/passport ID scanning and digital registration card
- Express / pre-arrival check-in (guest completes details before arrival)
- Check-out with automated folio settlement and GST e-invoice generation
- Room assignment (manual, auto-suggest, upgrade)
- Folio management: create, charge, payment (cash/card/UPI), transfer between folios, split, settle
- Night audit: automated end-of-day reconciliation, rate posting, no-show processing
- Registration card: digital capture, PDF generation, C-Form for foreign nationals
- Keycard management: encode, re-encode, deactivate
- Smart lock integration (BLE/RFID)
- PBX/phone system integration (wake-up calls, DND, room status)
- ID scanner integration (Aadhaar QR, passport MRZ)
- GST e-invoice generation (B2B and B2C)
- Early check-in / late check-out with automated charges
- Room move / upgrade with folio adjustment
- Walk-in guest handling (rapid booking + check-in)
- Guest messages and wake-up call scheduling
- In-room dining order relay to POS/kitchen
3.2 Out of Scope
- Housekeeping workflows (covered in EP-006)
- Revenue management / rate strategy (covered in EP-007)
- Guest loyalty program (covered in EP-010)
- Channel manager / OTA sync (covered in EP-009)
- Full POS / restaurant billing (covered in EP-007)
4. Current Implementation Status
4.1 Backend (01-hmp-backend - Frontdesk Service)
| Component | Status | Notes |
|---|---|---|
| Check-in API | Built | Full workflow with ID validation, room assignment |
| Check-out API | Built | Folio settlement, balance verification |
| Folio CRUD | Built | Create, charge, payment, transfer, split, settle |
| Night Audit Engine | Built | Automated rate posting, no-show, EOD reconciliation |
| Keycard API | Built | Encode/re-encode/deactivate endpoints |
| Smart Lock Integration | Partial | Mock adapter only, no real hardware driver |
| PBX Integration | Partial | API built, not tested with physical PBX hardware |
| ID Scanner | Built | Aadhaar QR decode, passport MRZ parsing |
| GST E-Invoice | Built | IRN generation, B2B/B2C, credit note support |
| Registration Card PDF | Partial | Generation works, formatting needs polish |
| Express Check-in | Partial | Backend endpoints exist, not connected to guest app |
| Walk-in Flow | Partial | Works but requires too many steps |
| In-Room Dining Relay | Not Started | Schema defined, POS integration pending |
4.2 Dashboard (02-hmp-web-dashboard)
| Component | Status | Notes |
|---|---|---|
| Room Grid View | Built | Real-time status with color coding |
| Arrivals List | Built | Filterable, sortable, with check-in action |
| Departures List | Built | Balance alerts, check-out action |
| In-House Guest List | Built | Search, filter by floor/room type |
| Check-in Form | Built | Multi-step wizard with ID capture |
| Check-out Form | Built | Folio review, payment, invoice generation |
| Folio Page | Built | Charges, payments, transfers, PDF export |
| Night Audit Dashboard | Built | Status, logs, manual trigger |
| Express Check-in UI | Not Started | Guest-facing pre-arrival form not connected |
| Walk-in Quick Form | Partial | Exists but needs streamlining |
| Guest Messages UI | Partial | Display works, send/schedule needs work |
5. Gap Analysis
| # | Gap | Impact | Effort | Priority |
|---|---|---|---|---|
| 1 | Express check-in not connected to guest booking engine | High - missed 3-min target for pre-booked guests | M | P2 |
| 2 | Smart lock integration is mock-only | Medium - keycards work as fallback | L | P3 |
| 3 | PBX not tested with real hardware | Low - wake-up calls can be manual | M | P3 |
| 4 | Registration card PDF formatting | Medium - legal compliance risk | S | P1 |
| 5 | Walk-in flow too many steps | High - losing walk-in revenue | S | P1 |
| 6 | In-room dining to POS not built | Medium - manual order relay works | L | P2 |
| 7 | Guest message scheduling | Low - manual messages work | S | P2 |
6. User Stories Summary
| Story ID | Title | Priority | Points | Sprint | Status |
|---|---|---|---|---|---|
| US-005-01 | Standard Check-In | P0 | 8 | 1 | Built |
| US-005-02 | Standard Check-Out | P0 | 8 | 1 | Built |
| US-005-03 | Folio Creation & Charges | P0 | 5 | 1 | Built |
| US-005-04 | Folio Payment Recording | P0 | 5 | 1 | Built |
| US-005-05 | Folio Transfer & Split | P0 | 5 | 2 | Built |
| US-005-06 | Folio Settlement | P0 | 5 | 2 | Built |
| US-005-07 | Night Audit Automation | P0 | 13 | 2 | Built |
| US-005-08 | Room Assignment (Auto) | P1 | 5 | 2 | Built |
| US-005-09 | Registration Card & C-Form | P1 | 5 | 3 | Partial |
| US-005-10 | Aadhaar/Passport ID Scan | P1 | 8 | 3 | Built |
| US-005-11 | GST E-Invoice Generation | P0 | 8 | 3 | Built |
| US-005-12 | Keycard Encode/Manage | P1 | 5 | 3 | Built |
| US-005-13 | Early Check-In / Late Check-Out | P1 | 5 | 4 | Built |
| US-005-14 | Room Move / Upgrade | P1 | 5 | 4 | Built |
| US-005-15 | Walk-In Quick Booking | P1 | 5 | 4 | Partial |
| US-005-16 | Express Check-In (Pre-Arrival) | P2 | 8 | 5 | Partial |
| US-005-17 | Smart Lock Integration | P3 | 13 | 6 | Partial |
| 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-005-21 | Room Grid Real-Time View | P0 | 5 | 1 | Built |
| US-005-22 | Night Audit Report & Logs | P0 | 5 | 2 | Built |
7. Dependencies
| Dependency | Type | Epic/Service | Status |
|---|---|---|---|
| Reservation service (booking data) | Upstream | EP-003 / reservation | Available |
| Guest profile service (guest data) | Upstream | EP-004 / guest | Available |
| Property service (room inventory) | Upstream | EP-002 / property | Available |
| Auth service (RBAC roles) | Upstream | EP-001 / auth | Available |
| Housekeeping status | Peer | EP-006 / housekeeping | Available |
| POS / Kitchen service | Downstream | EP-007 / pos | Not Ready |
| Booking engine (express check-in) | Peer | EP-011 / booking-engine | Partial |
| Kafka event bus | Infra | Docker / Kafka | Available |
| Redis (room status cache) | Infra | Docker / Redis | Available |
8. Epic-Level Acceptance Criteria
- AC-EP-005-01: A front desk agent can complete a standard check-in (ID scan, room assign, keycard, registration card) in under 3 minutes for a pre-booked guest.
- AC-EP-005-02: All folio operations (charge, payment, transfer, split, settle) produce accurate GST-compliant invoices in INR.
- AC-EP-005-03: Night audit runs automatically at configured time (typically 00:00-02:00 IST), posts room charges, processes no-shows, and generates reconciliation report without manual intervention.
- AC-EP-005-04: Walk-in guests can be booked and checked in within 5 minutes through the quick walk-in flow.
- AC-EP-005-05: All check-in/out events publish Kafka events consumed by notification service (EP-014) for guest communication.
- AC-EP-005-06: The room grid view updates in real-time (within 2 seconds) when room status changes.
- AC-EP-005-07: Registration cards comply with Indian hotel registration requirements including Form C for foreign nationals.
9. KPIs
| KPI | Target | Measurement Method |
|---|---|---|
| Average check-in time | < 3 minutes | Timestamp: start to keycard issue |
| Average check-out time | < 2 minutes | Timestamp: initiate to invoice |
| Folio accuracy rate | > 99.5% | Audit discrepancies / total folios |
| Night audit completion rate | 100% automated | Manual interventions / total runs |
| Walk-in conversion time | < 5 minutes | Inquiry to checked-in timestamp |
| Guest satisfaction (check-in) | > 4.5/5 | Post-stay survey scores |
| GST invoice compliance | 100% | Failed IRN generations / total |
10. Detailed User Stories
US-005-01: Standard Check-In
As a Front Desk Agent, I want to check in a guest with a confirmed reservation by scanning their ID, assigning a room, and issuing a keycard, So that the guest can access their room quickly and the hotel has compliant registration records.
Priority: P0 | Points: 8 | Sprint: 1 | Status: Built
Implementation Status
Fully implemented in the frontdesk service with check-in API endpoint. Dashboard check-in wizard supports multi-step flow: select reservation, scan ID (Aadhaar QR or passport), confirm room, encode keycard, print/email registration card. Kafka event guest.checked_in published on completion.
Acceptance Criteria
Scenario: Successful check-in for confirmed reservation
Given a reservation with status "CONFIRMED" for guest "Rajesh Sharma"
And the room "301" is in "CLEAN" status
When the front desk agent scans the guest's Aadhaar card
And assigns room "301"
And encodes the keycard
Then the reservation status changes to "CHECKED_IN"
And the room status changes to "OCCUPIED"
And a registration card PDF is generated with guest details and Aadhaar number
And a Kafka event "guest.checked_in" is published
And the check-in completes in under 3 minutes
Scenario: Check-in blocked for unclean room
Given a reservation with status "CONFIRMED" for guest "Priya Patel"
And the assigned room "405" is in "DIRTY" status
When the front desk agent attempts to check in the guest
Then the system displays a warning "Room 405 is not ready"
And suggests alternative clean rooms of the same type
And allows the agent to select a different room
Scenario: Check-in with advance payment verification
Given a reservation with a pending balance of INR 5,000
When the front desk agent initiates check-in
Then the system displays the outstanding balance
And allows the agent to collect payment via cash, card, or UPI
And creates a folio with the advance payment recorded
US-005-02: Standard Check-Out
As a Front Desk Agent, I want to check out a guest by settling their folio balance and generating a GST-compliant invoice, So that the room is released for the next guest and the hotel has accurate financial records.
Priority: P0 | Points: 8 | Sprint: 1 | Status: Built
Implementation Status
Check-out API settles all open folios, generates GST e-invoice, updates room status to DIRTY, publishes guest.checked_out Kafka event. Dashboard check-out form shows folio summary, accepts final payment, and triggers invoice email.
Acceptance Criteria
Scenario: Successful check-out with zero balance
Given guest "Anita Desai" is checked in to room "201"
And her folio balance is INR 0 (fully paid)
When the front desk agent initiates check-out
Then the system generates a GST e-invoice with valid GSTIN and SAC codes
And the room status changes to "DIRTY"
And the reservation status changes to "CHECKED_OUT"
And a Kafka event "guest.checked_out" is published
Scenario: Check-out with outstanding balance
Given guest "Vikram Singh" is checked in to room "502"
And his folio has an outstanding balance of INR 12,450
When the front desk agent initiates check-out
Then the system displays the itemized folio with GST breakup
And requires payment collection before completing check-out
And accepts payment via UPI (QR code displayed) or card swipe
And generates the final invoice after payment confirmation
Scenario: Express check-out with email invoice
Given guest "Meera Joshi" has requested express check-out
When the scheduled check-out time (12:00 PM IST) is reached
And the folio is pre-authorized on the guest's credit card
Then the system auto-settles the folio
And emails the GST invoice to the guest's registered email
And updates the room status to "DIRTY"
US-005-03: Folio Creation & Charges
As a Front Desk Agent, I want to create folios and post charges for room rent, minibar, laundry, and other services, So that all guest expenses are accurately tracked for billing.
Priority: P0 | Points: 5 | Sprint: 1 | Status: Built
Implementation Status
Folio service supports multiple folios per reservation. Charges categorized by department (room, F&B, laundry, telephone, minibar, miscellaneous). Each charge records GST components (CGST + SGST for intra-state, IGST for inter-state) based on hotel and guest GSTIN.
Acceptance Criteria
Scenario: Post room charge with GST breakup
Given guest "Suresh Kumar" is checked in with a room rate of INR 5,000/night
When the night audit posts the daily room charge
Then a folio line item is created for INR 5,000
And CGST at 9% (INR 450) and SGST at 9% (INR 450) are calculated
And the total charge of INR 5,900 is added to the folio balance
And the charge is tagged with SAC code "996311"
Scenario: Post minibar charge
Given guest "Rekha Nair" is checked in to room "303"
When the front desk agent posts a minibar charge of INR 350 for "2x Mineral Water, 1x Chips"
Then the charge appears on the guest's primary folio
And GST is calculated at the applicable rate (18% for packaged items)
And the charge includes item-level description for the invoice
US-005-04: Folio Payment Recording
As a Front Desk Agent, I want to record payments against a guest's folio via cash, credit card, UPI, or bank transfer, So that the folio balance is accurately updated and payment is traceable.
Priority: P0 | Points: 5 | Sprint: 1 | Status: Built
Implementation Status
Payment recording supports multiple payment methods: CASH, CREDIT_CARD, DEBIT_CARD, UPI, BANK_TRANSFER, COMPANY_CREDIT. Each payment generates a receipt number and updates folio balance. UPI integration supports QR code generation for guest scanning.
Acceptance Criteria
Scenario: Record UPI payment
Given guest "Amit Bhatt" has a folio balance of INR 8,500
When the front desk agent selects "UPI" payment method
And enters the UPI transaction reference "UPIREF20260305143022"
And records a payment of INR 8,500
Then the folio balance updates to INR 0
And a payment receipt is generated with the UPI reference
And the payment is logged in the financial audit trail
Scenario: Record partial cash payment
Given guest "Deepa Menon" has a folio balance of INR 15,000
When the front desk agent records a cash payment of INR 10,000
Then the folio balance updates to INR 5,000
And the system displays the remaining balance
And the cash receipt is printed with the hotel's GSTIN
US-005-05: Folio Transfer & Split
As a Front Desk Agent, I want to transfer charges between folios or split a folio into multiple folios, So that corporate vs personal expenses can be separated or group billing can be managed.
Priority: P0 | Points: 5 | Sprint: 2 | Status: Built
Implementation Status
Transfer API moves individual line items or bulk charges between folios. Split creates a new folio and moves selected charges. Commonly used for separating room charges (company folio) from incidentals (personal folio).
Acceptance Criteria
Scenario: Transfer room charges to company folio
Given guest "Kiran Rao" has two folios: personal (F-001) and company (F-002)
And folio F-001 has room charges of INR 20,000 and minibar charges of INR 800
When the front desk agent selects the room charges
And transfers them to company folio F-002
Then folio F-001 balance becomes INR 800 (minibar only)
And folio F-002 balance becomes INR 20,000 (room charges with GST)
And both folios maintain accurate GST breakup
Scenario: Split folio for group checkout
Given a group reservation with 3 rooms sharing a master folio of INR 75,000
When the front desk agent splits the folio by room
Then three individual folios are created
And each folio contains charges attributable to that room
And the total across all folios equals INR 75,000
US-005-06: Folio Settlement
As a Front Desk Agent, I want to settle a folio by applying all payments and generating a final invoice, So that the guest's account is closed and the hotel has a complete financial record.
Priority: P0 | Points: 5 | Sprint: 2 | Status: Built
Implementation Status
Settlement API verifies zero balance, marks folio as SETTLED, generates final GST invoice with IRN (Invoice Reference Number) via e-invoice API. Settled folios are immutable; adjustments require credit notes.
Acceptance Criteria
Scenario: Settle folio with zero balance
Given guest "Sanjay Gupta" has a folio with total charges INR 25,000 and total payments INR 25,000
When the front desk agent settles the folio
Then the folio status changes to "SETTLED"
And a GST e-invoice is generated with a valid IRN
And the invoice PDF includes hotel GSTIN, guest details, SAC codes, and HSN codes
And the folio becomes read-only (no further charges or payments allowed)
Scenario: Prevent settlement with outstanding balance
Given guest "Pooja Shah" has a folio with balance INR 3,200
When the front desk agent attempts to settle the folio
Then the system rejects the settlement
And displays "Outstanding balance of INR 3,200 must be cleared before settlement"
And offers payment collection options
US-005-07: Night Audit Automation
As a Front Desk Manager, I want to run an automated night audit that posts room charges, processes no-shows, and reconciles the day's transactions, So that the hotel's daily books are closed accurately without manual effort.
Priority: P0 | Points: 13 | Sprint: 2 | Status: Built
Implementation Status
Night audit engine runs as a scheduled job (configurable, default 00:00 IST). Steps: (1) post room and tax charges to all in-house folios, (2) process no-shows and apply cancellation charges per policy, (3) advance business date, (4) generate audit report with revenue summary, occupancy stats, and discrepancy alerts. Manual trigger available via dashboard.
Acceptance Criteria
Scenario: Automated night audit posts room charges
Given 45 rooms are occupied on business date 2026-03-05
And the night audit is scheduled for 00:00 IST
When the audit runs automatically
Then room and tax charges are posted to all 45 in-house folios
And each charge includes correct GST (CGST + SGST or IGST based on guest state)
And the business date advances to 2026-03-06
And an audit report is generated with total revenue of the day
Scenario: Night audit processes no-show reservations
Given 3 reservations for 2026-03-05 have not checked in by audit time
And the no-show policy charges 1 night's room rent
When the night audit runs
Then the 3 reservations are marked as "NO_SHOW"
And cancellation charges are posted to each reservation's folio
And rooms are released back to available inventory
And a Kafka event "reservation.no_show" is published for each
Scenario: Night audit generates discrepancy report
Given the night audit has completed
When the front desk manager views the audit report
Then the report shows total room revenue, F&B revenue, and other revenue
And highlights any rate discrepancies (actual vs expected)
And shows occupancy percentage and ADR (Average Daily Rate) in INR
And lists any manual adjustments made during the day
US-005-08: Room Assignment (Auto-Suggest)
As a Front Desk Agent, I want to receive intelligent room assignment suggestions based on guest preferences, room status, and optimization rules, So that I can assign the best available room quickly.
Priority: P1 | Points: 5 | Sprint: 2 | Status: Built
Implementation Status
Auto-assignment considers: room type match, floor preference, connecting rooms for families, accessibility needs, VIP upgrades, and housekeeping completion time. Returns ranked list of suggestions. Agent can override with manual selection.
Acceptance Criteria
Scenario: Auto-suggest room based on guest preferences
Given guest "Ramesh Iyer" has a reservation for a "Deluxe King" room
And the guest profile indicates preference for high floor and non-smoking
And rooms 601, 603, 605 are available "Deluxe King" rooms on floor 6
When the front desk agent clicks "Auto-Assign"
Then the system suggests room 601 as the top recommendation
And displays reasons: "High floor preference, non-smoking, closest to elevator"
And allows the agent to accept or choose an alternative
Scenario: Suggest upgrade for VIP guest
Given guest "Dr. Lakshmi Narayan" is a VIP (loyalty tier: Platinum)
And the reserved "Superior" room type has availability
And "Deluxe Suite" rooms are also available
When auto-assignment runs
Then the system suggests a complimentary upgrade to "Deluxe Suite"
And notes the upgrade policy and rate difference (INR 0 for Platinum)
US-005-09: Registration Card & C-Form
As a Front Desk Agent, I want to generate a digital registration card for Indian nationals and a C-Form for foreign nationals, So that the hotel complies with Indian registration laws and police reporting requirements.
Priority: P1 | Points: 5 | Sprint: 3 | Status: Partial
Implementation Status
Registration card generation works with basic guest data, room details, and terms. C-Form for foreign nationals captures visa details, passport info, and intended travel. PDF generation functional but formatting needs improvement for print quality. Digital signature capture not yet implemented.
Acceptance Criteria
Scenario: Generate registration card for Indian guest
Given guest "Arjun Reddy" is being checked in
And Aadhaar verification is complete (masked number: XXXX-XXXX-4523)
When the registration card is generated
Then the PDF includes guest name, Aadhaar (masked), address, room number, rate in INR
And includes hotel terms and conditions in English and Hindi
And provides a digital signature pad for guest acknowledgment
And the signed card is stored in the guest's digital folio
Scenario: Generate C-Form for foreign national
Given guest "John Miller" from USA is being checked in
And passport number "US12345678" and visa number "V987654" are captured
When the C-Form is generated
Then it includes passport details, visa type, duration of stay, and arrival details
And is formatted per FRRO (Foreigners Regional Registration Office) requirements
And is queued for submission to the local police station within 24 hours
US-005-10: Aadhaar/Passport ID Scan
As a Front Desk Agent, I want to scan a guest's Aadhaar card QR code or passport MRZ zone to auto-populate registration details, So that data entry is eliminated and check-in is faster.
Priority: P1 | Points: 8 | Sprint: 3 | Status: Built
Implementation Status
Aadhaar QR scanner decodes the secure QR code and extracts name, DOB, gender, and masked Aadhaar number. Passport MRZ scanner reads the machine-readable zone and extracts name, nationality, passport number, expiry. Both integrate with the check-in wizard to auto-fill guest profile fields.
Acceptance Criteria
Scenario: Scan Aadhaar QR code
Given the front desk agent is on the check-in ID verification step
When the agent scans the guest's Aadhaar card QR code using the connected scanner
Then the system extracts guest name, date of birth, gender, and address
And auto-populates the registration form with extracted data
And displays the masked Aadhaar number (XXXX-XXXX-3456) for verification
And the agent confirms the details match the guest
Scenario: Scan passport MRZ for foreign national
Given a foreign guest presents their passport
When the agent scans the passport MRZ zone
Then the system extracts full name, nationality, passport number, and expiry date
And flags if the passport expires within 6 months
And triggers the C-Form workflow for foreign national registration
US-005-11: GST E-Invoice Generation
As a Front Desk Agent, I want to generate GST-compliant e-invoices at check-out with proper HSN/SAC codes and tax breakup, So that the hotel meets Indian GST compliance requirements and guests can claim input tax credit.
Priority: P0 | Points: 8 | Sprint: 3 | Status: Built
Implementation Status
E-invoice generation integrates with the GST e-invoice portal for IRN (Invoice Reference Number) generation. Supports B2B (with buyer GSTIN) and B2C invoices. Tax calculation handles CGST+SGST (intra-state) and IGST (inter-state) based on hotel and guest state. Credit notes supported for post-checkout adjustments.
Acceptance Criteria
Scenario: Generate B2B e-invoice with GSTIN
Given guest "TCS Corporate" has GSTIN "27AADCT1234F1Z5"
And the hotel is in Maharashtra (state code 27)
And the folio total is INR 50,000 (room charges SAC 996311)
When the e-invoice is generated at check-out
Then the invoice includes supplier GSTIN, buyer GSTIN, and SAC codes
And calculates CGST at 9% (INR 4,500) and SGST at 9% (INR 4,500)
And obtains a valid IRN from the e-invoice portal
And generates a QR code on the invoice for verification
Scenario: Generate B2C invoice for individual guest
Given guest "Neha Kapoor" from Karnataka is checking out of a Mumbai hotel
And the folio total is INR 12,000
When the invoice is generated
Then IGST at 18% (INR 2,160) is calculated (inter-state supply)
And the invoice is generated without IRN (B2C below threshold)
And the invoice includes the hotel's FSSAI number for F&B charges
US-005-12: Keycard Encode & Manage
As a Front Desk Agent, I want to encode room keycards at check-in and manage re-encoding for lost cards or room changes, So that guests have secure room access and the hotel can track card usage.
Priority: P1 | Points: 5 | Sprint: 3 | Status: Built
Implementation Status
Keycard API supports ENCODE, RE_ENCODE, and DEACTIVATE operations. Integrates with keycard encoder hardware via serial/USB protocol adapter. Each encode creates an audit log entry. Lost card deactivation is immediate. Room move triggers automatic re-encode for new room.
Acceptance Criteria
Scenario: Encode keycard at check-in
Given guest "Ravi Verma" is being checked in to room "408"
And the keycard encoder is connected and ready
When the front desk agent places a blank card on the encoder
And clicks "Encode Keycard"
Then the card is programmed with room 408 access
And the card validity is set from check-in date to check-out date (12:00 PM)
And the encode event is logged in the security audit trail
Scenario: Deactivate lost keycard and issue replacement
Given guest "Sunita Devi" reports her keycard for room "210" as lost
When the front desk agent clicks "Report Lost" for the active keycard
Then the lost card is immediately deactivated (will not open room 210)
And a new card is encoded with room 210 access
And the security log records the lost card incident with timestamp
US-005-13: Early Check-In / Late Check-Out
As a Front Desk Agent, I want to process early check-ins and late check-outs with automated charge calculation, So that guests get flexibility and the hotel captures additional revenue.
Priority: P1 | Points: 5 | Sprint: 4 | Status: Built
Implementation Status
Early check-in charges calculated based on configurable rules: before 8 AM = full night charge, 8 AM-12 PM = 50% charge, 12 PM-2 PM (standard) = no charge. Late check-out: 2 PM-6 PM = 50% charge, after 6 PM = full night charge. Charges auto-posted to folio with GST.
Acceptance Criteria
Scenario: Early check-in with half-day charge
Given guest "Manish Tiwari" arrives at 9:30 AM (standard check-in is 2:00 PM)
And the room rate is INR 6,000/night
And the early check-in policy charges 50% before noon
When the front desk agent processes early check-in
Then an early check-in charge of INR 3,000 + GST is posted to the folio
And the system displays the charge for agent confirmation before posting
And the guest's check-in time is recorded as 9:30 AM
Scenario: Late check-out approved by manager
Given guest "Fatima Khan" requests late check-out until 6:00 PM
And the standard check-out is 12:00 PM
And the late check-out would incur a 50% charge of INR 4,000
When the front desk agent requests manager approval
And the manager approves with a waiver (complimentary for loyalty member)
Then the check-out time is extended to 6:00 PM
And no charge is posted (waiver applied with manager authorization code)
And the waiver reason is logged in the audit trail
US-005-14: Room Move / Upgrade
As a Front Desk Agent, I want to move a guest to a different room or upgrade their room type, So that guest complaints are resolved or VIP guests receive better accommodation.
Priority: P1 | Points: 5 | Sprint: 4 | Status: Built
Implementation Status
Room move API handles: deactivate old keycard, update reservation room assignment, encode new keycard, adjust rate if room type changes, notify housekeeping of vacated room. Folio automatically adjusted for rate differences. Upgrade can be complimentary (with authorization) or charged.
Acceptance Criteria
Scenario: Move guest to different room same type
Given guest "Arun Jaitley" is in room "305" (Deluxe King)
And the guest complains about noise from adjacent room
And room "312" (Deluxe King) is available and clean
When the front desk agent initiates a room move to "312"
Then the keycard for room "305" is deactivated
And a new keycard for room "312" is encoded
And housekeeping is notified to clean room "305"
And the reservation record is updated with the room change and reason
And no rate adjustment is needed (same room type)
Scenario: Complimentary upgrade for VIP
Given guest "Priya Chopra" is a VIP in room "401" (Superior, INR 8,000/night)
And room "501" (Premium Suite, INR 15,000/night) is available
When the manager authorizes a complimentary upgrade
Then the guest is moved to room "501" with new keycard
And the folio rate remains INR 8,000/night (complimentary upgrade)
And the rate difference is logged as a management allowance
US-005-15: Walk-In Quick Booking
As a Front Desk Agent, I want to create a booking and check in a walk-in guest in a single streamlined flow, So that walk-in revenue is captured quickly without making the guest wait.
Priority: P1 | Points: 5 | Sprint: 4 | Status: Partial
Implementation Status
Walk-in flow exists but requires navigating through full reservation creation before check-in. Needs consolidation into a single-page form that combines: guest details capture, room selection, rate confirmation, ID scan, payment, and keycard encode.
Acceptance Criteria
Scenario: Walk-in guest checked in within 5 minutes
Given a guest walks in without a reservation
And "Deluxe Twin" rooms are available at rack rate INR 7,500/night
When the front desk agent opens the "Walk-In" quick form
And captures the guest's name, phone, and Aadhaar via QR scan
And selects room type and confirms the rate
And collects advance payment of INR 7,500 via UPI
Then a reservation is created with status "CHECKED_IN"
And a folio is created with the advance payment recorded
And a keycard is encoded for the assigned room
And the entire process completes in under 5 minutes
Scenario: Walk-in with negotiated rate
Given the front desk agent is handling a walk-in during low occupancy (< 40%)
When the agent applies a 20% discount on the rack rate
And the discounted rate of INR 6,000 is within the agent's authority limit
Then the booking is created at INR 6,000/night
And the discount reason is recorded ("Walk-in low occupancy discount")
And no manager approval is needed (within agent authority)
US-005-16: Express Check-In (Pre-Arrival)
As a Guest, I want to complete my check-in formalities online before arriving at the hotel, So that I can go directly to my room upon arrival with minimal wait time.
Priority: P2 | Points: 8 | Sprint: 5 | Status: Partial
Implementation Status
Backend endpoints exist for pre-arrival data submission (guest details, ID upload, preferences). Not yet connected to the booking engine guest portal. Needs: guest-facing UI in booking engine, Aadhaar upload and verification, digital signature for registration card, room selection from available inventory.
Acceptance Criteria
Scenario: Guest completes pre-arrival check-in
Given guest "Sneha Reddy" has a confirmed reservation for 2026-03-10
And she receives a pre-arrival email link 48 hours before arrival
When she opens the link and uploads her Aadhaar card photo
And confirms her contact details and preferences (high floor, extra pillows)
And digitally signs the registration card
Then her check-in status changes to "PRE_REGISTERED"
And upon arrival, the front desk agent only needs to issue a keycard
And the total at-desk time is under 1 minute
Scenario: Express check-in with room selection
Given guest "Nitin Kumar" is completing pre-arrival check-in
And 3 rooms of his booked type are available
When he views the available rooms with floor plans
And selects room "607" (corner room, city view)
Then room "607" is pre-assigned to his reservation
And the room is blocked from other assignments until check-in date
US-005-17: Smart Lock Integration
As a Front Desk Agent, I want to issue digital room keys via smart lock integration (BLE/RFID), So that guests can use their smartphones to access rooms and the hotel reduces physical keycard costs.
Priority: P3 | Points: 13 | Sprint: 6 | Status: Partial
Implementation Status
Smart lock adapter interface defined with ENCODE, UNLOCK, LOCK, and STATUS operations. Currently only a mock adapter is implemented. Real integration requires hardware-specific SDK (e.g., ASSA ABLOY Vostio, Salto, dormakaba). Mobile key requires guest app with BLE capability.
Acceptance Criteria
Scenario: Issue mobile key via smart lock
Given guest "Rohit Sharma" has checked in and has the hotel app installed
And room "410" has a BLE-enabled smart lock
When the front desk agent issues a mobile key
Then a digital key is sent to the guest's smartphone via push notification
And the key is valid from check-in to check-out (12:00 PM on departure date)
And the guest can unlock room "410" by holding their phone near the lock
And each unlock event is logged in the security audit trail
Scenario: Revoke mobile key on checkout
Given guest "Rohit Sharma" has an active mobile key for room "410"
When the guest checks out
Then the mobile key is automatically revoked
And any attempt to unlock the room with the expired key is denied
And the revocation is logged with timestamp
US-005-18: PBX / Wake-Up Calls
As a Front Desk Agent, I want to schedule wake-up calls and manage room phone features (DND, call forwarding) through the PMS, So that guest requests are fulfilled reliably without manual tracking.
Priority: P3 | Points: 8 | Sprint: 6 | Status: Partial
Implementation Status
PBX integration API built with endpoints for wake-up call scheduling, DND toggle, and room phone status. Tested with mock PBX only. Real integration requires SIP trunk or PBX middleware (e.g., Asterisk, Avaya). Wake-up call list displays in dashboard but hardware triggering not tested.
Acceptance Criteria
Scenario: Schedule wake-up call
Given guest "Kavita Sharma" in room "308" requests a wake-up call at 5:30 AM
When the front desk agent schedules the wake-up call via the dashboard
Then the PBX system is programmed to ring room "308" at 5:30 AM IST
And if the guest does not answer within 3 rings, the call retries after 5 minutes
And the wake-up call status (answered/unanswered) is logged
And the front desk dashboard shows pending wake-up calls for the night
Scenario: Enable DND for room
Given guest "Anil Kapoor" in room "505" requests Do Not Disturb
When the front desk agent enables DND for room "505"
Then all incoming calls to room "505" are blocked
And the room phone displays DND indicator
And the room status on the dashboard shows a DND icon
And DND is automatically cleared at check-out
US-005-19: Guest Messages & Notices
As a Front Desk Agent, I want to record and deliver messages for in-house guests, So that guests receive important communications (visitor messages, delivery notifications, management notices).
Priority: P2 | Points: 5 | Sprint: 5 | Status: Partial
Implementation Status
Guest message model exists in the database. Display on guest profile page works. Message creation form exists but scheduling (e.g., "deliver at 8 AM") and delivery confirmation (message light, SMS) not complete.
Acceptance Criteria
Scenario: Record and deliver guest message
Given guest "Ajay Kumar" is checked in to room "702"
And a visitor leaves a message at the front desk
When the agent creates a message: "Mr. Pandey visited at 3 PM, will return at 6 PM"
Then the message is saved with timestamp and agent name
And the message light on the room phone is activated (if PBX connected)
And the message appears on the guest's in-room TV welcome screen (if integrated)
And the agent can mark the message as "Delivered" when confirmed
Scenario: Schedule guest notice
Given management wants to notify all in-house guests about a fire drill at 10 AM
When the front desk manager creates a broadcast message
And schedules it for delivery at 8 AM (2 hours prior)
Then the message is queued for all occupied rooms
And can be delivered via SMS, in-room TV, and printed slips as configured
US-005-20: In-Room Dining Order Relay
As a Front Desk Agent, I want to relay in-room dining orders from phone calls to the kitchen/POS system, So that guest orders are captured digitally and charged to the correct folio.
Priority: P2 | Points: 8 | Sprint: 5 | Status: Not Started
Implementation Status
Not started. Schema for dining orders defined but POS integration (EP-007) is not yet available. Currently, in-room dining orders are taken manually by phone and paper ticket to kitchen. Folio charges are posted manually by the front desk.
Acceptance Criteria
Scenario: Relay dining order to kitchen
Given guest "Madhuri Dixit" in room "601" calls for in-room dining
And the menu includes "Paneer Butter Masala" (INR 450) and "Naan" (INR 80)
When the front desk agent enters the order in the PMS
And selects items from the digital menu with quantities
Then the order is sent to the kitchen display system (KDS)
And the order includes room number, guest name, and delivery instructions
And upon delivery confirmation, charges of INR 530 + GST are auto-posted to the folio
And the GST is calculated at 5% (restaurant in hotel with room tariff < INR 7,500)
Scenario: Cancel dining order before preparation
Given an in-room dining order has been placed for room "601"
And the kitchen status is "RECEIVED" (not yet "IN_PREPARATION")
When the guest calls to cancel the order
And the front desk agent cancels via the PMS
Then the order status changes to "CANCELLED"
And no charge is posted to the folio
And the kitchen display removes the order
US-005-21: Room Grid Real-Time View
As a Front Desk Agent, I want to see a real-time visual grid of all rooms with their current status (occupied, vacant, dirty, clean, maintenance, blocked), So that I can make instant decisions about room availability and assignments.
Priority: P0 | Points: 5 | Sprint: 1 | Status: Built
Implementation Status
Room grid built in the dashboard with color-coded status tiles. Updates via WebSocket/polling when room status changes. Supports filtering by floor, room type, and status. Clicking a room shows quick details (guest name, check-out date, housekeeping status).
Acceptance Criteria
Scenario: View room grid with real-time updates
Given the hotel has 120 rooms across 6 floors
When the front desk agent opens the room grid view
Then all 120 rooms are displayed in a grid layout grouped by floor
And each room shows a color-coded status (green=vacant clean, red=occupied, yellow=dirty, grey=maintenance)
And the grid updates within 2 seconds when a room status changes
And room count summaries are shown (e.g., "45 Occupied, 30 Vacant Clean, 15 Dirty, 5 Maintenance")
Scenario: Filter rooms by type and status
Given the front desk agent needs a clean Deluxe King room
When the agent filters by room type "Deluxe King" and status "Vacant Clean"
Then only matching rooms are highlighted on the grid
And the count shows "8 Deluxe King rooms available"
And clicking a room shows rate, floor, view type, and last cleaned time
US-005-22: Night Audit Report & Logs
As a Front Desk Manager, I want to view detailed night audit reports and logs, So that I can verify daily revenue, identify discrepancies, and maintain financial oversight.
Priority: P0 | Points: 5 | Sprint: 2 | Status: Built
Implementation Status
Night audit dashboard shows: last run status, revenue summary (room, F&B, other), occupancy metrics, rate variances, no-show count, and detailed log of all posting actions. Historical reports accessible by business date. Export to Excel available.
Acceptance Criteria
Scenario: Review night audit report
Given the night audit for business date 2026-03-04 has completed
When the front desk manager opens the night audit report
Then the report shows total room revenue (INR 4,25,000), F&B (INR 1,80,000), others (INR 45,000)
And occupancy rate (78%), ADR (INR 5,450), and RevPAR (INR 4,251) are displayed
And any rate discrepancies are highlighted in red with room numbers
And the report is downloadable as PDF and Excel
Scenario: View audit log details
Given the night audit posted charges to 78 rooms
When the manager drills into the audit log
Then each posting is listed with room number, guest name, charge amount, and GST breakup
And failed postings (if any) are highlighted with error reasons
And the manager can manually retry failed postings
Document generated: 2026-03-05 | Epic Owner: Front Desk Module Lead | Review Cycle: Bi-weekly