EP-012E: Operational Analytics
Parent Epic: EP-012 Analytics, Reporting & Night Audit Split Note: EP-012 has been split into sub-epics EP-012A, EP-012B, EP-012C, EP-012D, EP-012E. This file covers control center, SOP management, labor analytics, exceptions tracking, housekeeping KPIs, channel analytics, overbooking analytics, owner portal, and pilot health monitoring.
| Field | Value |
|---|---|
| Epic ID | EP-012E |
| Epic Name | Operational Analytics |
| Parent Epic | EP-012 Analytics, Reporting & Night Audit |
| Owner | Product — Revenue Intelligence & Operations |
| Created | 2026-03-27 |
| Last Updated | 2026-03-27 |
| Status | Partial / Not Started |
| Target Release | R4-R5 (Q3-Q4 2026) |
1. Business Objective
Operational excellence analytics helps department heads identify inefficiencies, compliance gaps, and emerging issues before they affect guests. Housekeeping managers who can see room-attendant productivity by floor can rebalance assignments in real time. Channel managers who see overbooking risk at 14:00 can release inventory or hedge bookings. The owner portal gives investors the monthly financial narrative without requiring a call with the GM. Pilot health monitoring gives the HMP Customer Success team early warning when a new hotel deployment is failing to adopt the platform.
2. Audience
| Role | Interaction |
|---|---|
| General Manager | Control center, SOP compliance, exception alerts |
| Housekeeping Mgr | Room attendant productivity KPIs, room turnaround time, deep clean schedule |
| Revenue Manager | Channel analytics, overbooking risk, pickup pace |
| HR / Finance | Labor analytics, shift productivity, cost-per-occupied-room |
| Owner / Investor | Owner portal: monthly financial narrative, NOI, investment return metrics |
| Chain Admin | Cross-property operational comparisons |
| HMP Customer Success | Pilot health monitoring: feature adoption, error rates, API health |
3. Scope
3.1 In Scope
- Control Center: real-time operational status panel — pending check-ins, in-progress housekeeping, open service recovery complaints, POS queues
- SOP Management: define hotel SOPs (e.g., "Room cleaned within 3h of checkout"), track compliance %, flag violations
- Labor Analytics: shifts logged, rooms cleaned per attendant, check-ins per front desk agent, cost per occupied room
- Exceptions Tracking: daily exceptions summary — folio discrepancies, unresolved complaints, no-shows, maintenance overdue
- Housekeeping KPIs: room turnaround time, attendant productivity (rooms/hour), deep clean completion %, maintenance backlog
- Channel Analytics: booking pace by channel vs. forecast, channel mix trending, overbooking risk score
- Overbooking Analytics: current overbooking level by room type, predicted walk probability, suggested inventory adjustment
- Owner / Investor Portal: monthly NOI, occupancy trend, RevPAR vs. budget, capital expenditure summary
- Pilot Health Monitoring: feature adoption rates, API error rates by service, slow endpoints, onboarding checklist completion (for HMP CS team)
3.2 Out of Scope
- Real-time KPI dashboard (EP-012A)
- Financial P&L and compliance reports (EP-012B, EP-012C)
- Custom report builder (EP-012D)
- Housekeeping task management (EP-006)
- Channel manager OTA connectivity (EP-009)
4. Current Implementation Status
4.1 Backend — analytics-service
| Controller / Endpoint | Status | Notes |
|---|---|---|
GET /analytics/control-center | Not Started | Aggregation of pending operational items |
GET /analytics/sop | Not Started | SOP definitions and compliance tracking |
GET /analytics/labor | Not Started | Shift productivity data |
GET /analytics/exceptions | Not Started | Daily exceptions summary |
GET /analytics/housekeeping/kpis | Partial | Room attendant productivity (Sprint 2 gap item) |
GET /analytics/housekeeping/turnaround | Not Started | Avg. room turnaround time by floor/type |
GET /analytics/channels | Not Started | Channel pace, mix, pickup trend |
GET /analytics/overbooking | Not Started | Overbooking risk score by room type |
GET /analytics/owner-portal | Not Started | Monthly NOI, occupancy, RevPAR vs. budget |
GET /analytics/pilot-health | Not Started | Feature adoption, API health, error rates |
GET /kpi/trends | Partial | KPI trend endpoint (Phase 2 deliverable, EP-021) |
4.2 Dashboard — 02-hmp-web-dashboard
| Component | Status | Notes |
|---|---|---|
| Control Center page | Not Started | - |
| SOP Management page | Not Started | - |
| Labor Analytics page | Not Started | - |
| Housekeeping KPIs page | Partial | Basic chart; no turnaround time or productivity tiles |
| Channel Analytics page | Not Started | - |
| Overbooking Risk panel | Not Started | - |
| Owner Portal | Not Started | - |
| Pilot Health Dashboard | Not Started | (Super Admin / HMP internal only) |
5. Gap Analysis
| # | Gap | Impact | Effort | Priority |
|---|---|---|---|---|
| 1 | Control center aggregation API not built | Medium | M | P2 |
| 2 | SOP definitions and compliance tracking entirely missing | Medium | L | P2 |
| 3 | Labor analytics requires shift data integration with housekeeping | Medium | L | P2 |
| 4 | Channel analytics (pace vs. forecast) needs OTA event feed | Medium | M | P2 |
| 5 | Overbooking risk requires forecast model + booking pace data | Medium | M | P2 |
| 6 | Owner portal NOI calculation requires expense data from P&L | Medium | M | P2 |
| 7 | Pilot health monitoring entirely missing (internal tool) | Low | M | P3 |
6. User Stories
| Story ID | Title | Priority | Points | Sprint | Status |
|---|---|---|---|---|---|
| US-012E-01 | Control Center (Operational Status Panel) | P2 | 8 | 5 | Not Started |
| US-012E-02 | SOP Management & Compliance Tracking | P2 | 13 | 6 | Not Started |
| US-012E-03 | Labor Analytics | P2 | 8 | 6 | Not Started |
| US-012E-04 | Daily Exceptions Summary | P2 | 5 | 5 | Not Started |
| US-012E-05 | Housekeeping KPIs & Turnaround Analytics | P2 | 8 | 5 | Partial |
| US-012E-06 | Channel Analytics & Booking Pace | P2 | 8 | 5 | Not Started |
| US-012E-07 | Overbooking Risk & Inventory Advisory | P2 | 8 | 5 | Not Started |
| US-012E-08 | Owner / Investor Portal | P2 | 13 | 6 | Not Started |
| US-012E-09 | Pilot Health Monitoring | P3 | 8 | 7 | Not Started |
7. Detailed User Stories
US-012E-01: Control Center (Operational Status Panel)
As a General Manager, I want to see a single operational control center screen that shows all pending actions across departments, So that I can identify bottlenecks and direct staff resources in real time.
Priority: P2 | Points: 8 | Sprint: 5 | Status: Not Started
Implementation Notes
GET /analytics/control-center— aggregates from multiple services:- Pending check-ins past ETA (reservations with arrival = today and not checked in)
- Rooms awaiting cleaning with guest expected > 1h (housekeeping)
- Open service recovery complaints (front desk)
- Pending maintenance requests > 24h (housekeeping)
- POS KOT queue depth (pos-service)
- Data cached in Redis with 60s TTL; refreshed by Kafka events
Acceptance Criteria
Scenario: Control center shows real-time operational status
Given it is 14:00 and the hotel has various pending items
When the GM opens the Control Center
Then they see a dashboard with:
| Category | Count | SLA Status |
| Arrivals not yet checked in | 3 | 2 overdue |
| Rooms pending cleaning | 8 | 3 overdue |
| Open complaints | 2 | 1 breached |
| Pending maintenance > 24h | 1 | Overdue |
| POS KOT queue (avg wait) | 12m | OK |
And clicking any row drills down to the department's task list
Scenario: All clear status
Given all operational items are resolved at 22:00
When the GM views the control center
Then all categories show 0 pending items
And a "All Clear — Hotel operating normally" banner is displayed
US-012E-05: Housekeeping KPIs & Turnaround Analytics
As a Housekeeping Manager, I want to see room attendant productivity and room turnaround time analytics, So that I can identify which floors or attendants are underperforming and rebalance assignments.
Priority: P2 | Points: 8 | Sprint: 5 | Status: Partial
Implementation Status
GET /analytics/housekeeping/kpis returns basic housekeeping productivity data. Room turnaround time (time from checkout to room marked CLEAN) and attendant-level breakdowns are not yet computed.
Acceptance Criteria
Scenario: View attendant productivity for today
Given 4 room attendants are on shift today
When the Housekeeping Manager opens the KPI dashboard
Then they see per attendant:
| Attendant | Rooms Assigned | Rooms Cleaned | Avg Time/Room | Productivity Score |
| Sunita Devi | 14 | 12 | 22 minutes | 86% |
| Rekha Singh | 14 | 14 | 18 minutes | 100% |
And the property average turnaround time is shown: "avg 23 min (target: 30 min)"
And rooms over 45 minutes are flagged in red
Scenario: Floor-level turnaround time
When the manager selects "Floor 4"
Then they see all rooms on floor 4 with checkout time, cleaning start time, and completion time
And the floor average is compared against the property average
US-012E-06: Channel Analytics & Booking Pace
As a Revenue Manager, I want to see booking pace by channel compared to last year and forecast, So that I can identify when a channel is underperforming and take corrective action (rate adjustment, promotional offer).
Priority: P2 | Points: 8 | Sprint: 5 | Status: Not Started
Implementation Notes
GET /analytics/channels?from=&to=&propertyId=- Booking pace: reservations created per day by channel, cumulative to arrival date
- Comparison: current year pace vs. same period last year (STLY) and forecast
- Channel mix pie: % of total revenue by channel (rolling 30 days)
- OTA commission impact: gross vs. net revenue by channel (requires commission % from EP-009)
Acceptance Criteria
Scenario: View booking pace for next 30 days
Given today is 2026-03-27
When the Revenue Manager opens Channel Analytics for the next 30 days
Then they see a pace chart: bookings received per day by channel for the 30-day window
And STLY overlay shows last year's pace for the same period
And "Pickup Gap" shows: "MakeMyTrip is 18% behind last year's pace for this period"
Scenario: Channel mix trending
When they select "90-day trend"
Then a stacked area chart shows how the channel mix has shifted over 90 days
And direct bookings trending up is highlighted as a positive signal
US-012E-07: Overbooking Risk & Inventory Advisory
As a Revenue Manager, I want to see the current overbooking level by room type and a risk score indicating the probability of needing to walk a guest, So that I can proactively adjust inventory (release or hold rooms) before it becomes a guest complaint.
Priority: P2 | Points: 8 | Sprint: 5 | Status: Not Started
Implementation Notes
GET /analytics/overbooking?arrival_date=&propertyId=- Inputs: rooms confirmed > rooms available by room type, historical no-show rate (%), historical cancellation rate (%)
- Risk score = simple binomial: P(arrivals > capacity) given historical no-show/cancellation rates
- Advisory: "Deluxe King: 2 overbooking buffer, 12% walk risk — consider placing 1 room on waitlist"
- Integrates with EP-009 channel manager to close inventory on OTA channels if risk > 20%
Acceptance Criteria
Scenario: Low overbooking risk
Given Deluxe King has 20 rooms confirmed for tomorrow and 22 rooms available
And historical no-show rate for that room type is 15%
When the Revenue Manager checks overbooking analytics for tomorrow
Then risk score shows "Low — 3% walk probability"
And recommendation: "No action needed"
Scenario: High overbooking risk
Given Standard Twin has 25 rooms confirmed for tomorrow and 22 rooms available (3 overbooked)
And no-show rate is only 5% (high-season, low cancellation)
When the Revenue Manager checks
Then risk score shows "HIGH — 62% walk probability"
And recommendation: "Close Standard Twin inventory on all OTA channels"
And one-click "Close Inventory" button triggers EP-009 channel manager update
US-012E-08: Owner / Investor Portal
As a Hotel Owner, I want to log in to a dedicated portal and see my hotel's financial performance in a clean, investor-friendly summary, So that I don't need to request reports from the GM or interpret raw hotel jargon.
Priority: P2 | Points: 13 | Sprint: 6 | Status: Not Started
Implementation Notes
- New RBAC role:
OWNERwith read-only access to financial and KPI dashboards GET /analytics/owner-portal?month=&propertyId=- Summary cards: Occupancy, RevPAR, Total Revenue, Total Expenses, GOP, GOP%, NOI
- Month-over-month trend chart for each metric
- Year-to-date performance vs. budget
- Capital expenditure log (manual input by GM or Finance Manager)
- No operational detail (no guest names, no housekeeping data)
Acceptance Criteria
Scenario: Owner views monthly performance summary
Given owner "Sunil Malhotra" has OWNER role for "Hotel Sunrise, Jaipur"
When he logs in and opens the Owner Portal for March 2026
Then he sees:
- Occupancy: 78% (vs. 72% budget)
- RevPAR: ₹4,875 (vs. ₹4,500 budget)
- Total Revenue: ₹63,50,000
- GOP: ₹28,10,000 (44.3%)
- NOI (after debt service): ₹18,40,000
And a trend chart shows 6-month RevPAR history
And a comparison "vs. last March: +8.2% RevPAR growth"
Scenario: Owner cannot access guest data
Given Sunil is logged in as OWNER
When he tries to navigate to "Guest Management"
Then the system returns 403 Forbidden
US-012E-09: Pilot Health Monitoring
As a HMP Customer Success Manager, I want to see a health dashboard for each pilot hotel showing feature adoption rates, API error rates, and onboarding completion, So that I can proactively support hotels that are struggling with adoption before they churn.
Priority: P3 | Points: 8 | Sprint: 7 | Status: Not Started
Implementation Notes
- Accessible only to
SUPER_ADMINrole (HMP internal) GET /analytics/pilot-health/:tenantId- Feature adoption: % of feature categories used in the last 30 days (check-in, folio, night audit, reports, channel management)
- API health: error rate per service (from Prometheus metrics), slow endpoints (p95 > 2s)
- Onboarding checklist: rooms configured, rate plans set, first reservation, first check-in, first night audit
- Risk score: RED (< 30% feature adoption), AMBER (30-60%), GREEN (> 60%)
- Feeds into CS team Grafana dashboard via Prometheus metrics export
Acceptance Criteria
Scenario: Pilot hotel showing low adoption
Given "Hotel Lotus, Nashik" has been onboarded for 30 days
And only check-in and check-out features have been used (no reports, no channel manager)
When the CS Manager opens pilot health for Hotel Lotus
Then the risk score shows RED with adoption at 22%
And the "Unused features" list shows: Reports, Channel Manager, Night Audit, F&B POS
And "Suggested action: Schedule a training session for Reports module"
Scenario: Healthy pilot hotel
Given "Hotel Sunrise, Jaipur" uses all modules regularly
When the CS Manager checks the health dashboard
Then adoption shows GREEN at 87%
And API error rate is < 0.1%
And all 5 onboarding checklist items are marked complete
8. Dependencies
| Dependency | Type | Epic / Service | Status |
|---|---|---|---|
| Housekeeping task data (turnaround time) | Upstream | EP-006 / housekeeping | Available |
| Reservation data (overbooking, pace) | Upstream | EP-003 / reservation | Available |
| Channel management (OTA commission, close) | Peer | EP-009 / channel | Partial |
| Front desk (complaints, control center) | Peer | EP-005D / frontdesk | Available |
| POS (KOT queue depth) | Peer | EP-007 / pos | Available |
| Financial P&L (owner portal NOI) | Sibling | EP-012B / analytics | Partial |
| Prometheus metrics (pilot health) | Infra | libs/common / MetricsModule | Built |
| Auth / RBAC (OWNER role, SUPER_ADMIN) | Upstream | EP-001 / auth | Available |
| Kafka (real-time aggregation) | Infra | Docker / Kafka | Available |
| Redis (control center cache, 60s TTL) | Infra | Docker / Redis | Available |
9. Acceptance Criteria (Sub-Epic Level)
- AC-EP-012E-01: Control center aggregates pending items across all departments and updates within 60 seconds of a status change.
- AC-EP-012E-02: Housekeeping KPI dashboard shows per-attendant productivity and room turnaround time with SLA color coding.
- AC-EP-012E-03: Channel analytics shows booking pace vs. STLY and identifies channels trending below forecast with percentage gap.
- AC-EP-012E-04: Overbooking risk score correctly identifies HIGH risk scenarios (walk probability > 50%) for the arrival date.
- AC-EP-012E-05: Owner portal is accessible only to OWNER role; no guest PII or operational detail is exposed.
- AC-EP-012E-06: Pilot health monitoring classifies hotels into RED/AMBER/GREEN bands based on feature adoption; accessible only to SUPER_ADMIN.
- AC-EP-012E-07: All operational analytics respect tenant isolation — data from one property never appears in another's analytics.
10. Technical Notes
- Analytics controller:
01-hmp-backend/apps/analytics-service/src/analytics/analytics.controller.ts— new endpoints inOperationalAnalyticsModule - Housekeeping KPIs: Join
housekeeping_tasks(completed_at, started_at, assigned_to, room_id) withrooms(floor, room_type_id) - Channel pace query: Join
reservations(created_at, arrival_date, booking_source) grouped by (booking_source, created_date); compare to STLY by adjusting date window - Overbooking risk:
P(walk) = 1 − Binomial.CDF(rooms_available, confirmed_count, 1 − historical_noshow_rate)— implement as a utility function in analytics-service - Owner portal: Create
OWNERrole in auth-service RBAC; restrict to analytics read scopes only; nofrontdesk:*orguest:*scopes - Pilot health Prometheus metrics:
hmp_feature_usage_total{tenant_id, feature}counter incremented on each API call; exported at/metricsendpoint via MetricsModule (Phase 3 deliverable) - SOP compliance: SOP definitions stored in a new
sop_definitionstable (property-service); compliance events sourced from housekeeping task timestamps and complaint resolution logs