EP-012: Analytics, Reporting & Night Audit
This epic has been split into sub-epics:
- EP-012A: KPI Dashboard & Revenue Intelligence
- EP-012B: Financial Reports
- EP-012C: Tax & Compliance Reports
- EP-012D: Report Builder & Scheduled Delivery
- EP-012E: Operational Analytics
This file is retained as the parent reference. New work should be tracked in the sub-epics above.
| Field | Value |
|---|---|
| Epic ID | EP-012 |
| Title | Analytics, Reporting & Night Audit |
| Owner | Product -- Revenue Intelligence & Operations |
| Status | Partial |
| Last Updated | 2026-03-05 |
| Target Release | R4 (Q3 2026) |
1. Business Objective
Equip Indian hotel operators with a comprehensive analytics, reporting, and night audit platform that replaces manual end-of-day procedures, automates GST compliance reporting (GSTR-1, GSTR-3B), and delivers actionable business intelligence. The system must reduce night audit time from 2-3 hours to under 30 minutes, eliminate manual GST filing errors, and provide revenue managers with real-time KPIs (occupancy, ADR, RevPAR) to optimize pricing and distribution decisions.
2. Audience
| Role | Interaction |
|---|---|
| General Manager | Views real-time KPI dashboard, receives daily summary reports |
| Revenue Manager | Analyzes RevPAR, ADR, occupancy trends; reviews forecasts |
| Night Auditor | Runs night audit procedures, resolves discrepancies |
| Finance Manager | Generates GST reports, P&L, balance sheet, aging receivables |
| Housekeeping Manager | Reviews housekeeping productivity and maintenance reports |
| F&B Manager | Monitors outlet revenue, menu item performance |
| Super Admin | Configures report permissions, manages audit log retention |
| Owner / Investor | Views financial summary, compset analysis |
3. Scope
3.1 In Scope
- Real-time dashboard KPIs: occupancy rate, ADR, RevPAR, TRevPAR, in-house guest count, arrivals/departures today
- Operational reports: daily arrivals, departures, in-house list, no-show report, VIP list, group status
- Revenue reports: room revenue by source/segment, F&B revenue by outlet, ancillary revenue
- Financial reports: Profit & Loss statement, balance sheet, cash flow statement, aging receivables/payables
- Housekeeping reports: room attendant productivity, maintenance request summary, deep clean schedule
- F&B reports: outlet-wise revenue, menu item sales analysis (contribution margin), wastage report
- GST compliance reports: GSTR-1 (outward supplies), GSTR-3B (summary return) with HSN codes (9963 for accommodation, 9996 for restaurant services)
- Night audit automation: day-end close, room rate posting, tax posting, no-show processing, balance verification, cashier shift close
- Audit logs with integrity chain (hash-linked entries for tamper evidence)
- Data export: CSV, PDF (formatted), Excel (.xlsx)
- Custom report builder (drag-and-drop dimensions and measures)
- Demand forecasting (7/30/90-day occupancy and revenue projections)
- Competitive set (compset) analysis: benchmark RevPAR, occupancy against local competitors
3.2 Out of Scope
- Full ERP / accounting system (integration with Tally/Zoho Books is a separate epic)
- Statutory audit / CA certification workflows
- STR (Smith Travel Research) data feed integration (future phase)
- Real-time POS integration for F&B itemized reporting (covered in EP-009)
4. Current Implementation Status
| Component | Service / Module | Status |
|---|---|---|
| Real-time KPI dashboard | analytics-service / dashboard | Built |
| Operational reports | analytics-service / reports | Built |
| Revenue reports | analytics-service / reports | Built |
| Financial reports (P&L, BS) | analytics-service / finance | Partial |
| Housekeeping reports | analytics-service / reports | Built |
| F&B reports | analytics-service / reports | Built |
| GST GSTR-1 report | analytics-service / gst | Partial |
| GST GSTR-3B report | analytics-service / gst | Partial |
| Night audit procedures | analytics-service / audit | Partial |
| Audit log with integrity chain | analytics-service / auditlog | Built |
| CSV/PDF/Excel export | analytics-service / export | Partial |
| Custom report builder UI | Dashboard reports module | Built |
| Custom report builder backend | analytics-service / custom | Not Started |
| Demand forecasting | analytics-service / forecast | Partial |
| Compset analysis | Dashboard competitor intelligence | Partial |
| Dashboard reports catalog | 02-hmp-web-dashboard | Built |
| Dashboard BI views | 02-hmp-web-dashboard | Built |
5. Gap Analysis
| # | Gap | Impact | Effort | Priority |
|---|---|---|---|---|
| 1 | Night audit rate posting requires manual trigger | Auditor must click per-room to post rates; should be batch automated | High | P0 |
| 2 | GST GSTR-1 filing format not validated against government schema | Report may be rejected by GST portal; manual correction needed | High | P0 |
| 3 | Financial reports (P&L, balance sheet) need chart of accounts mapping | Cannot produce standard financial statements without CoA | High | P1 |
| 4 | Custom report builder is UI-only (no backend query engine) | Users can design reports visually but cannot execute them | High | P1 |
| 5 | Forecasting models not trained on real data | Predictions are placeholder values, not actionable | Medium | P2 |
| 6 | PDF export formatting needs improvement | PDF reports have layout issues, missing headers/footers | Medium | P2 |
| 7 | Compset data requires manual entry (no automated feed) | Competitor benchmarking depends on staff manually entering data | Medium | P2 |
| 8 | Night audit no-show processing not automated | Auditor must manually identify and charge no-shows | High | P0 |
6. User Stories Summary
| ID | Title | Priority | Points | Sprint | Status |
|---|---|---|---|---|---|
| US-012-01 | Real-Time KPI Dashboard | P0 | 8 | 1 | Built |
| US-012-02 | Daily Operational Reports | P0 | 8 | 1 | Built |
| US-012-03 | Revenue Reports by Source & Segment | P0 | 8 | 1 | Built |
| US-012-04 | GST GSTR-1 Report Generation | P0 | 13 | 2 | Partial |
| US-012-05 | GST GSTR-3B Summary Report | P0 | 8 | 2 | Partial |
| US-012-06 | Night Audit Day-End Close | P0 | 13 | 2 | Partial |
| US-012-07 | Night Audit Rate & Tax Posting | P0 | 8 | 3 | Partial |
| US-012-08 | Night Audit No-Show Processing | P0 | 8 | 3 | Not Started |
| US-012-09 | Financial P&L Statement | P1 | 13 | 4 | Partial |
| US-012-10 | Balance Sheet & Cash Flow Reports | P1 | 13 | 4 | Not Started |
| US-012-11 | Aging Receivables Report | P1 | 5 | 3 | Built |
| US-012-12 | Housekeeping Productivity Report | P1 | 5 | 2 | Built |
| US-012-13 | F&B Revenue & Menu Analysis | P1 | 8 | 3 | Built |
| US-012-14 | Audit Log with Integrity Chain | P0 | 8 | 1 | Built |
| US-012-15 | Data Export (CSV, PDF, Excel) | P1 | 8 | 3 | Partial |
| US-012-16 | Custom Report Builder | P2 | 21 | 5 | Partial |
| US-012-17 | Demand Forecasting (7/30/90 day) | P2 | 13 | 5 | Partial |
| US-012-18 | Competitive Set Analysis | P2 | 8 | 6 | Partial |
| US-012-19 | Night Audit Balance Verification | P0 | 8 | 3 | Partial |
| US-012-20 | Scheduled Report Delivery | P1 | 5 | 4 | Not Started |
7. Dependencies
| Dependency | Epic/Service | Type |
|---|---|---|
| Reservation data | EP-005 / reservation-service | Hard |
| Billing & invoice data | EP-008 / billing-service | Hard |
| Guest profile data | EP-003 / guest-service | Hard |
| Property & room configuration | EP-004 / property-service | Hard |
| Housekeeping task data | EP-007 / housekeeping-service | Hard |
| F&B order & POS data | EP-009 / fnb-service | Hard |
| Kafka events for real-time updates | Infrastructure | Hard |
| Redis cache for dashboard KPIs | Infrastructure | Hard |
| Auth & RBAC for report permissions | EP-001 / auth-service | Hard |
| Tally/Zoho Books CoA mapping | External / Finance team | Soft |
8. Acceptance Criteria (Epic-Level)
- The real-time dashboard updates occupancy, ADR, and RevPAR within 30 seconds of a reservation change via Kafka events.
- Night audit can be completed in under 30 minutes with automated rate posting, tax posting, no-show processing, and balance verification.
- GSTR-1 report generates valid JSON conforming to the GST portal's upload schema, with correct HSN codes (9963 for accommodation services).
- Financial P&L maps revenue and expenses to a configurable chart of accounts and balances to zero.
- All reports support CSV, PDF, and Excel export with proper formatting, headers, and hotel branding.
- Custom report builder allows non-technical users to select dimensions, measures, and filters, and execute the query against the analytics database.
- Audit logs are hash-chained and any tampering is detectable by integrity verification.
- All reports respect tenant isolation and RBAC (Finance Manager sees financial reports; Housekeeping Manager sees only housekeeping reports).
9. KPIs
| KPI | Target | Measurement |
|---|---|---|
| Night audit duration | < 30 minutes | Time from audit start to day close |
| Dashboard data freshness | < 30 seconds | Event timestamp to dashboard render |
| GST report accuracy | 100% schema compliance | Government portal acceptance rate |
| Report generation time | < 10 seconds for standard | API response time for report endpoints |
| Report usage adoption | > 80% of managers weekly | Unique report viewers / total managers |
| Forecast accuracy (30-day) | MAPE < 15% | Predicted vs actual occupancy |
| Manual data entry reduction | -70% vs. pre-HMP baseline | Data entry tasks tracked |
10. Detailed User Stories
US-012-01: Real-Time KPI Dashboard
As a General Manager, I want to see a real-time dashboard with today's key metrics, So that I can make informed operational decisions throughout the day.
Priority: P0 | Points: 8 | Sprint: 1 | Status: Built
Implementation Status
Real-time KPI dashboard is fully built. Displays occupancy rate (%), ADR (INR), RevPAR (INR), TRevPAR (INR), rooms sold, rooms available, in-house guest count, today's arrivals, today's departures, and revenue MTD. Data is cached in Redis and refreshed via Kafka event consumers. Dashboard auto-refreshes every 30 seconds.
Acceptance Criteria
Scenario: View today's operational KPIs
Given I am logged in as General Manager for "Hotel Sunrise, Jaipur"
When I open the Analytics Dashboard
Then I see today's metrics:
| Metric | Value |
| Occupancy | 78% (62/80) |
| ADR | 6,250 INR |
| RevPAR | 4,875 INR |
| In-House Guests | 98 |
| Arrivals Today | 15 |
| Departures Today| 12 |
| Revenue MTD | 48,75,000 INR |
And revenue is formatted in Indian lakhs notation
Scenario: KPIs update in real-time on new check-in
Given the dashboard shows occupancy at 78%
When a front desk agent checks in a guest (Kafka event "reservation.checkedIn")
Then within 30 seconds the dashboard updates occupancy to 78.75% (63/80)
And in-house guest count increments accordingly
Scenario: Tenant isolation on KPI dashboard
Given I manage "Hotel Sunrise, Jaipur" (tenant A)
When I view the dashboard
Then I see only data for my tenant
And data from "Hotel Moonlight, Mumbai" (tenant B) is never included
US-012-02: Daily Operational Reports
As a Front Office Manager, I want to generate daily operational reports (arrivals, departures, in-house, no-shows), So that I can prepare the team for the day's operations.
Priority: P0 | Points: 8 | Sprint: 1 | Status: Built
Implementation Status
All daily operational reports are built and accessible from the report catalog. Each report shows guest name, room number, booking source, special requests, VIP status, and loyalty tier. Reports can be filtered by date and exported.
Acceptance Criteria
Scenario: Generate arrivals report for today
Given today is 2026-03-05 and there are 15 expected arrivals
When I select "Arrivals Report" for date 2026-03-05
Then the report lists all 15 reservations with:
| Guest Name | Room | Check-in Time | Room Type | Source | VIP | Special Requests |
And VIP guests (Diamond/Platinum tier) are highlighted at the top
And the report includes total count and room type breakdown
Scenario: Generate no-show report
Given 3 reservations for 2026-03-04 were never checked in
When I generate the "No-Show Report" for 2026-03-04
Then the report lists the 3 no-show reservations
And each shows booking source, cancellation policy, and no-show charge amount
And a summary shows total no-show revenue impact
Scenario: Export arrivals report as PDF
Given the arrivals report is displayed with 15 entries
When I click "Export PDF"
Then a PDF generates with hotel letterhead, report title, date, and the table data
And the PDF footer shows "Generated by HMP on 2026-03-05 08:30 IST"
US-012-03: Revenue Reports by Source & Segment
As a Revenue Manager, I want to analyze room revenue broken down by booking source and market segment, So that I can optimize distribution strategy and identify high-value channels.
Priority: P0 | Points: 8 | Sprint: 1 | Status: Built
Implementation Status
Revenue reports are fully built with pivot capability. Revenue can be sliced by: booking source (Direct, MakeMyTrip, Goibibo, Booking.com, Walk-in, Corporate, Travel Agent), market segment (Transient, Corporate, Group, Government, Crew), room type, and time period. Charts include bar, line, and pie visualizations.
Acceptance Criteria
Scenario: Revenue by booking source for current month
Given it is March 2026 and the hotel has earned 48,75,000 INR room revenue
When I view "Revenue by Source" for March 2026
Then I see a breakdown:
| Source | Revenue (INR) | Share | ADR (INR) | Room Nights |
| Direct | 14,62,500 | 30% | 6,500 | 225 |
| MakeMyTrip | 12,18,750 | 25% | 5,800 | 210 |
| Corporate | 9,75,000 | 20% | 5,200 | 188 |
| Walk-in | 7,31,250 | 15% | 7,000 | 105 |
| Others | 4,87,500 | 10% | 5,500 | 89 |
And a pie chart visualizes the revenue share
Scenario: Drill down into a specific source
Given I am viewing revenue by source
When I click on "MakeMyTrip" in the chart
Then a detail view shows MakeMyTrip bookings by room type, average lead time, and cancellation rate
And the OTA commission cost (15%) is shown alongside net revenue
Scenario: Compare revenue across months
Given I select comparison period January to March 2026
When the report loads
Then a line chart shows monthly revenue trend per source
And a table shows MoM growth percentage for each source
US-012-04: GST GSTR-1 Report Generation
As a Finance Manager, I want to generate GSTR-1 (outward supplies) report in the format required by the GST portal, So that I can file monthly GST returns accurately without manual data entry.
Priority: P0 | Points: 13 | Sprint: 2 | Status: Partial
Implementation Status
GSTR-1 report generation is partially implemented. The analytics-service aggregates invoice data and groups by GST rate (12% for rooms below 7,500 INR, 18% for rooms at or above 7,500 INR). HSN code 9963 is assigned for accommodation services. However, the output JSON format has not been validated against the government's GSTR-1 offline utility schema. B2C (small) vs. B2B invoice classification logic is incomplete. Place of supply determination for IGST vs CGST+SGST is partially implemented.
Acceptance Criteria
Scenario: Generate GSTR-1 for March 2026
Given the hotel (GSTIN: 27AABCU9603R1ZM, Maharashtra) had 450 invoices in March 2026
When the Finance Manager generates the GSTR-1 report
Then the report classifies invoices into:
| Section | Description | Count |
| B2B | Invoices to registered persons (with GSTIN) | 85 |
| B2C-Large | Interstate > 2,50,000 INR | 12 |
| B2C-Small | All other B2C | 353 |
And each B2B entry includes recipient GSTIN, invoice number, date, taxable value, CGST, SGST, IGST
And HSN summary shows: 9963 (Accommodation) and 9996 (Restaurant) with respective tax amounts
Scenario: Correct IGST vs CGST+SGST determination
Given a guest from Karnataka (state code 29) stays at a Maharashtra hotel (state code 27)
When the invoice is generated
Then GST is applied as IGST (interstate supply)
And the GSTR-1 report places this in the correct column
Scenario: Export GSTR-1 in government JSON format
Given the GSTR-1 report is generated
When the Finance Manager clicks "Export for GST Portal"
Then a JSON file conforming to the GSTN offline tool schema (version 2.4) is downloaded
And the file can be imported directly into the GST portal without modification
And a validation summary shows any data issues before export
US-012-05: GST GSTR-3B Summary Report
As a Finance Manager, I want to generate the GSTR-3B summary return with pre-computed values, So that I can file the monthly summary return quickly.
Priority: P0 | Points: 8 | Sprint: 2 | Status: Partial
Implementation Status
GSTR-3B summary report is partially built. It aggregates total outward supplies (taxable + exempt), total CGST/SGST/IGST liability, and input tax credit (ITC) summary. However, ITC reconciliation with purchase invoices is not connected (hotel purchase data is not in the system). Inter-state supply summary needs refinement.
Acceptance Criteria
Scenario: Generate GSTR-3B for March 2026
Given all invoices for March 2026 are finalized
When the Finance Manager generates GSTR-3B
Then the report shows:
| Table | Description | Taxable Value | IGST | CGST | SGST |
| 3.1(a) | Outward taxable supplies | 42,50,000 INR | 3,20,000 | 2,85,000 | 2,85,000 |
| 3.1(b) | Outward exempt supplies | 1,20,000 INR | - | - | - |
| 4 | Eligible ITC | (manual entry) | - | - | - |
| 6.1 | Payment of tax | - | 3,20,000 | 2,85,000 | 2,85,000 |
And the report clearly marks ITC as "Requires manual input from purchase records"
Scenario: HSN-wise summary
Given accommodation revenue at 18% GST is 35,00,000 INR and restaurant revenue at 5% GST is 7,50,000 INR
When the HSN summary section is generated
Then it shows:
| HSN Code | Description | Taxable Value | Rate | Tax Amount |
| 9963 | Accommodation | 35,00,000 INR | 18% | 6,30,000 |
| 9963 | Accommodation | 7,50,000 INR | 12% | 90,000 |
| 9996 | Restaurant | 7,50,000 INR | 5% | 37,500 |
Scenario: Compare GSTR-3B with GSTR-1 totals
Given both GSTR-1 and GSTR-3B are generated for March 2026
When I click "Reconcile"
Then the system compares outward supply totals between the two returns
And highlights any discrepancies exceeding 100 INR
US-012-06: Night Audit Day-End Close
As a Night Auditor, I want to run a structured day-end close procedure with automated checks, So that all transactions for the business day are finalized and the system advances to the next business date.
Priority: P0 | Points: 13 | Sprint: 2 | Status: Partial
Implementation Status
Night audit day-end close is partially implemented. The dashboard provides a night audit wizard with sequential steps. Steps 1 (verify open cashier shifts) and 2 (review pending transactions) are built. Steps for automated rate posting, tax posting, and final day close (business date advance) require manual intervention and are not fully automated.
Acceptance Criteria
Scenario: Complete night audit day-end close
Given it is 2026-03-05 23:30 IST and the business date is 2026-03-05
When the Night Auditor opens the Night Audit module
Then a checklist is presented:
| Step | Task | Status |
| 1 | Close all open cashier shifts | Ready |
| 2 | Post room charges & taxes | Ready |
| 3 | Process no-shows | Ready |
| 4 | Verify guest balances | Ready |
| 5 | Run trial balance | Ready |
| 6 | Advance business date | Locked |
And Step 6 unlocks only after Steps 1-5 are completed
Scenario: Advance business date
Given all night audit steps are completed with no unresolved discrepancies
When the Night Auditor clicks "Advance Business Date"
Then the system business date changes from 2026-03-05 to 2026-03-06
And a Kafka event "audit.dayClose" is published with the closed date and auditor ID
And the day close is recorded in the audit log as an immutable entry
Scenario: Prevent day close with unresolved issues
Given Step 4 (Verify guest balances) found 3 rooms with discrepancies
When the Night Auditor attempts to advance the business date
Then the system blocks with message: "3 unresolved balance discrepancies. Resolve before closing."
And the auditor can override with supervisor approval (requires a second login)
US-012-07: Night Audit Rate & Tax Posting
As a Night Auditor, I want room rates and taxes to be automatically posted to all in-house guest folios, So that charges are applied consistently without manual per-room entry.
Priority: P0 | Points: 8 | Sprint: 3 | Status: Partial
Implementation Status
Rate posting logic exists in the analytics-service but requires the auditor to manually trigger posting for each floor/block. Batch posting (all in-house rooms at once) is not implemented. Tax calculation (GST at 12% or 18% based on tariff) is correct but not applied atomically with rate posting.
Acceptance Criteria
Scenario: Batch post room rates for all in-house guests
Given 62 rooms are occupied on business date 2026-03-05
When the Night Auditor clicks "Post Room Charges" in the audit wizard
Then the system posts the nightly rate to each room's folio in a single batch operation
And GST is calculated per room based on tariff (12% for < 7,500 INR, 18% for >= 7,500 INR)
And a posting summary shows: 62 rooms posted, total room revenue 3,87,500 INR, total GST 62,250 INR
Scenario: Handle rate change mid-stay
Given guest in Room 301 had rate 8,000 INR for first 2 nights but rate changed to 7,000 INR from night 3
When rate posting runs for night 3
Then 7,000 INR is posted (not the original 8,000 INR)
And GST is calculated at 18% on 7,000 INR (still above 7,500 threshold due to original rate? -- system uses current night's rate)
And the folio shows the rate change history
Scenario: Skip posting for complimentary rooms
Given Room 501 is marked as "Complimentary" (house use)
When batch rate posting runs
Then Room 501 is skipped with zero charge
And the posting summary notes "1 complimentary room excluded"
US-012-08: Night Audit No-Show Processing
As a Night Auditor, I want the system to automatically identify no-shows and apply charges per cancellation policy, So that revenue is protected and inventory is released for walk-ins.
Priority: P0 | Points: 8 | Sprint: 3 | Status: Not Started
Implementation Status
Not implemented. No-show identification requires checking reservations with today's arrival date that were never checked in and whose arrival window has passed (e.g., after 18:00 IST or as defined in the reservation). Charging logic needs to apply the cancellation policy's no-show penalty (typically 1 night) and release the room back to inventory.
Acceptance Criteria
Scenario: Identify and process no-shows
Given 3 reservations for 2026-03-05 have arrival time passed (18:00 IST) and are not checked in
When the Night Auditor runs "Process No-Shows" in the audit wizard
Then the system lists the 3 no-show reservations:
| Guest | Room Type | Rate | Policy | No-Show Charge |
| Vikram Singh | Deluxe | 8,000 | 1 night charge | 9,440 INR |
| Neha Gupta | Standard | 4,500 | 1 night charge | 5,040 INR |
| Amit Joshi | Suite | 15,000 | Non-refundable | 35,400 INR |
And the auditor can confirm all or selectively exclude guests who called to inform late arrival
Scenario: Release no-show room inventory
Given "Vikram Singh" is confirmed as a no-show for Deluxe Room
When the no-show is processed
Then the reservation status changes to "No-Show"
And the Deluxe Room is released back to available inventory for walk-ins
And a no-show charge is posted to the guest's folio (to be collected via card on file)
Scenario: Notify no-show guest
Given Vikram Singh's no-show is processed
When the charge is posted
Then an email and SMS are sent to Vikram informing of the no-show charge
And the message includes the hotel's contact number for disputes
US-012-09: Financial P&L Statement
As a Finance Manager, I want to generate a Profit & Loss statement mapped to the hotel's chart of accounts, So that I can assess the property's financial performance.
Priority: P1 | Points: 13 | Sprint: 4 | Status: Partial
Implementation Status
Revenue aggregation (room, F&B, spa, ancillary) is built and feeds into the P&L revenue section. However, the expense side requires a chart of accounts (CoA) mapping that is not yet configured. The system cannot produce a complete P&L without expense categorization. A placeholder CoA based on the Uniform System of Accounts for the Lodging Industry (USALI) is in the schema but not connected to transaction posting.
Acceptance Criteria
Scenario: Generate P&L for March 2026
Given the chart of accounts is configured with USALI-based categories
And March 2026 transactions are finalized
When the Finance Manager generates the P&L
Then the report shows:
| Category | Amount (INR) |
| Room Revenue | 48,75,000 |
| F&B Revenue | 12,30,000 |
| Spa Revenue | 3,45,000 |
| Other Revenue | 1,50,000 |
| Total Revenue | 66,00,000 |
| Room Expenses | 8,75,000 |
| F&B Cost of Sales | 4,30,500 |
| Administrative & General | 6,60,000 |
| Sales & Marketing | 3,30,000 |
| Maintenance | 2,64,000 |
| Total Expenses | 25,59,500 |
| Gross Operating Profit | 40,40,500 |
And departmental profit margins are calculated and displayed
Scenario: Compare P&L with budget
Given a budget for March 2026 is uploaded
When the P&L is generated with "vs. Budget" toggle enabled
Then each line item shows Actual, Budget, and Variance (both INR and %)
And unfavorable variances exceeding 10% are highlighted in red
Scenario: Map transactions to chart of accounts
Given a new expense category "Energy Costs" is added to the CoA
When the Finance Manager maps electricity vendor payments to this category
Then future P&L reports include "Energy Costs" as a separate line item
US-012-10: Balance Sheet & Cash Flow Reports
As a Finance Manager / Owner, I want to generate a balance sheet and cash flow statement, So that I can understand the property's financial position and liquidity.
Priority: P1 | Points: 13 | Sprint: 4 | Status: Not Started
Implementation Status
Not implemented. Requires chart of accounts to be fully operational with asset, liability, and equity classifications. Cash flow statement needs integration with payment gateway (Razorpay) settlement data and bank reconciliation, which are not yet in scope.
Acceptance Criteria
Scenario: Generate balance sheet as of March 31, 2026
Given the chart of accounts includes asset and liability categories
When the Finance Manager generates the balance sheet for 2026-03-31
Then the report shows:
| Section | Category | Amount (INR) |
| Current Assets | Cash & Bank | 25,00,000 |
| Current Assets | Accounts Receivable | 8,50,000 |
| Current Assets | Inventory (F&B) | 2,10,000 |
| Current Liabilities| Accounts Payable | 5,30,000 |
| Current Liabilities| GST Payable | 4,85,000 |
| Current Liabilities| Advance Deposits | 6,20,000 |
And Total Assets = Total Liabilities + Equity (balance check passes)
Scenario: Cash flow statement for Q1 2026
Given January to March 2026 transactions are finalized
When the cash flow report is generated
Then it categorizes cash flows into Operating, Investing, and Financing activities
And the net cash position reconciles with the bank balance
Scenario: Handle missing data gracefully
Given some expense categories have no transactions mapped
When the balance sheet is generated
Then those categories show 0 INR (not null or error)
And a footnote indicates "Some categories may be incomplete pending chart of accounts setup"
US-012-11: Aging Receivables Report
As a Finance Manager, I want to view outstanding receivables aged by 30/60/90/120+ days, So that I can prioritize collection efforts and manage cash flow.
Priority: P1 | Points: 5 | Sprint: 3 | Status: Built
Implementation Status
Aging receivables report is fully built. Groups outstanding invoices by debtor (corporate accounts, travel agents, individual guests) and ages them into 0-30, 31-60, 61-90, and 90+ day buckets. Drill-down to individual invoices is supported.
Acceptance Criteria
Scenario: View aging receivables summary
Given there are outstanding receivables totaling 12,50,000 INR
When I generate the aging receivables report
Then the summary shows:
| Aging Bucket | Amount (INR) | Count |
| Current (0-30 days) | 5,20,000 | 28 |
| 31-60 days | 3,80,000 | 15 |
| 61-90 days | 2,10,000 | 8 |
| 90+ days | 1,40,000 | 5 |
And totals are displayed with percentage distribution
Scenario: Drill down to a specific debtor
Given "TechCorp India Pvt Ltd" has 3,20,000 INR outstanding
When I click on their name in the report
Then I see individual invoices with: Invoice #, Date, Amount, Due Date, Days Outstanding
And I can send a reminder email directly from the report
Scenario: Export aging report to Excel
Given the aging report is displayed
When I export to Excel
Then the .xlsx file includes: Summary sheet (aged buckets), Detail sheet (all invoices), and a Pivot table by debtor
US-012-12: Housekeeping Productivity Report
As a Housekeeping Manager, I want to track room attendant productivity (rooms cleaned per shift, average cleaning time), So that I can optimize staffing and identify training needs.
Priority: P1 | Points: 5 | Sprint: 2 | Status: Built
Implementation Status
Housekeeping productivity report is built using data from the housekeeping-service task completion events. Tracks rooms cleaned per attendant per shift, average cleaning time by room type, inspection pass rate, and maintenance requests raised during cleaning.
Acceptance Criteria
Scenario: Daily housekeeping productivity
Given the morning shift had 8 room attendants cleaning 62 rooms
When the Housekeeping Manager views the productivity report for 2026-03-05
Then the report shows:
| Attendant | Rooms Cleaned | Avg Time (min) | Inspection Pass % |
| Sunita K. | 9 | 28 | 100% |
| Ramesh D. | 8 | 32 | 87.5% |
| Priya M. | 7 | 35 | 100% |
| ... | ... | ... | ... |
And a benchmark line shows target: 8 rooms/shift, 30 min/room
Scenario: Cleaning time by room type
Given the hotel has Standard, Deluxe, and Suite room types
When the report shows average cleaning time by room type
Then: Standard: 25 min, Deluxe: 32 min, Suite: 48 min
And outliers (> 2x average) are flagged for review
Scenario: Maintenance requests correlation
Given 5 maintenance requests were raised during today's cleaning
When the report includes maintenance section
Then each request shows: Room, Issue Type, Attendant who reported, Status
And recurring issues (same room, same type) are highlighted
US-012-13: F&B Revenue & Menu Analysis
As an F&B Manager, I want to analyze outlet revenue and menu item performance, So that I can optimize the menu and pricing for profitability.
Priority: P1 | Points: 8 | Sprint: 3 | Status: Built
Implementation Status
F&B reporting is built with outlet-wise revenue breakdown, covers analysis, and menu item popularity ranking. Menu item contribution margin analysis is available (revenue - food cost per item). Reports pull from the fnb-service order data via Kafka events.
Acceptance Criteria
Scenario: Outlet-wise revenue for March 2026
Given the hotel has 3 F&B outlets: Restaurant, Bar, Room Service
When the F&B Manager generates the revenue report for March 2026
Then the report shows:
| Outlet | Revenue (INR) | Covers | Avg Check (INR) | Food Cost % |
| Restaurant | 7,20,000 | 1,800 | 400 | 32% |
| Bar | 3,60,000 | 900 | 400 | 25% |
| Room Service | 1,50,000 | 375 | 400 | 35% |
And total F&B revenue is 12,30,000 INR with blended food cost 31%
Scenario: Menu item popularity and margin analysis
Given the Restaurant menu has 45 active items
When I view the menu analysis report
Then items are plotted on a matrix: X-axis = Popularity (units sold), Y-axis = Contribution Margin (INR)
And items are classified as: Stars (high pop, high margin), Plowhorses (high pop, low margin), Puzzles (low pop, high margin), Dogs (low pop, low margin)
And actionable recommendations are shown (e.g., "Consider repricing Butter Chicken -- high volume but low margin")
Scenario: GST-compliant F&B pricing display
Given restaurant items are charged at 5% GST (without ITC) per Indian restaurant GST rules
When the report shows revenue breakdown
Then GST at 5% is separated from food revenue
And the HSN code 9996 is applied to all restaurant services
US-012-14: Audit Log with Integrity Chain
As a Super Admin / Auditor, I want all system actions to be recorded in a tamper-evident audit log, So that we have an immutable trail for compliance and dispute resolution.
Priority: P0 | Points: 8 | Sprint: 1 | Status: Built
Implementation Status
Audit log is fully built with hash-chaining. Every write operation (create, update, delete) across all services publishes an audit event to Kafka topic audit.log. Each entry includes: timestamp, userId, tenantId, action, entity, entityId, before/after values, IP address, and a SHA-256 hash of the previous entry (chain integrity). The audit log is stored in a dedicated audit_logs table with retention policy.
Acceptance Criteria
Scenario: Record a rate change in audit log
Given Revenue Manager changes Room 301's rate from 8,000 INR to 7,000 INR
When the change is saved
Then an audit log entry is created:
| Field | Value |
| Action | UPDATE |
| Entity | RoomRate |
| Before | { "rate": 8000, "currency": "INR" } |
| After | { "rate": 7000, "currency": "INR" } |
| UserId | user-uuid-of-revenue-manager |
| PrevHash | SHA-256 hash of previous audit entry |
Scenario: Detect tampered audit log
Given 10,000 audit log entries exist with valid hash chain
When an integrity verification is run
Then each entry's hash is recalculated and compared to the stored hash of the next entry
And if any entry was modified, the verification fails at that point with "Integrity violation at entry #4521"
Scenario: Search audit logs
Given I need to investigate changes to Reservation "BK-20260305-001"
When I search audit logs with filter entity="Reservation" AND entityId="BK-20260305-001"
Then all changes are shown chronologically: Created, Updated (room change), Updated (date change), Cancelled
And each entry shows who made the change and when
US-012-15: Data Export (CSV, PDF, Excel)
As a Any Report Viewer, I want to export any report in CSV, PDF, or Excel format, So that I can share data with stakeholders or import into external tools like Tally.
Priority: P1 | Points: 8 | Sprint: 3 | Status: Partial
Implementation Status
CSV export works for all reports. PDF export is functional but has formatting issues (table overflow on wide reports, missing page breaks, inconsistent font sizes). Excel export is partially built (data exports correctly but without formatting, headers, or multiple sheets).
Acceptance Criteria
Scenario: Export revenue report as formatted PDF
Given the monthly revenue report has 4 sections and 2 charts
When I click "Export PDF"
Then the PDF includes:
- Hotel logo and name in the header
- Report title and date range
- Formatted tables with alternating row colors
- Charts rendered as images
- Page numbers in the footer
- "Generated by HMP" watermark
And tables spanning multiple pages have repeated headers
Scenario: Export as Excel with multiple sheets
Given the F&B report has summary and detail data
When I export to Excel
Then the .xlsx file has: "Summary" sheet (outlet totals), "Detail" sheet (line items), "Charts" sheet
And the Summary sheet has INR formatting (lakhs notation) applied to numeric cells
And the file opens correctly in Microsoft Excel and Google Sheets
Scenario: Large dataset CSV export
Given the audit log report has 50,000 entries for the selected period
When I click "Export CSV"
Then the export runs asynchronously with a progress indicator
And a download link is provided when complete (within 30 seconds)
And the CSV uses UTF-8 encoding with BOM for correct Hindi text rendering in Excel
US-012-16: Custom Report Builder
As a Revenue Manager / General Manager, I want to build custom reports by selecting dimensions, measures, and filters, So that I can answer ad-hoc business questions without waiting for developer support.
Priority: P2 | Points: 21 | Sprint: 5 | Status: Partial
Implementation Status
The dashboard has a drag-and-drop report builder UI where users can select dimensions (date, room type, source, segment, outlet) and measures (revenue, room nights, ADR, occupancy, covers). Filters and date ranges can be applied. However, the backend query engine is not built -- the UI generates a query specification JSON but there is no API to execute it against the analytics database.
Acceptance Criteria
Scenario: Build a custom revenue by room type report
Given I open the Custom Report Builder
When I drag "Room Type" to Dimensions, "Revenue (INR)" and "Room Nights" to Measures, filter by "Date Range: March 2026"
Then a preview table generates showing revenue and room nights per room type
And I can add "Booking Source" as a second dimension for a cross-tab view
And the report can be saved as "My Revenue by Room Type" for future use
Scenario: Execute custom query against analytics database
Given the query specification is: { dimensions: ["room_type", "source"], measures: ["sum(revenue)", "count(nights)"], filters: [{ field: "date", op: "between", values: ["2026-03-01", "2026-03-31"] }] }
When the API processes this specification
Then it generates a safe SQL query against the analytics read replica
And returns results within 10 seconds for up to 1 million rows
And the query is parameterized to prevent SQL injection
Scenario: Share a saved custom report
Given I saved "My Revenue by Room Type" report
When I click "Share" and select "Revenue Manager" role
Then users with Revenue Manager role can see this report in their "Shared Reports" section
And they can view but not modify the report definition
US-012-17: Demand Forecasting (7/30/90 day)
As a Revenue Manager, I want to see occupancy and revenue forecasts for the next 7, 30, and 90 days, So that I can adjust pricing and staffing proactively.
Priority: P2 | Points: 13 | Sprint: 5 | Status: Partial
Implementation Status
Forecasting module exists in the analytics-service with 7/30/90-day projection endpoints. The dashboard displays forecast charts with confidence intervals. However, the forecasting models are using simple moving averages on mock historical data rather than trained ML models. Seasonality (Indian festivals, wedding season, monsoon) is not factored in. Actual historical data accumulation has not begun.
Acceptance Criteria
Scenario: View 30-day occupancy forecast
Given the Revenue Manager opens the forecasting dashboard
When they select "30-Day Occupancy Forecast"
Then a line chart shows predicted daily occupancy for the next 30 days
And each day shows: Predicted occupancy %, confidence interval (80%), on-the-books count
And known events are flagged (e.g., "Holi - 2026-03-14: Expected +20% demand")
Scenario: Revenue forecast with seasonal adjustment
Given historical data shows 40% revenue increase during October-November (Diwali/wedding season)
When the 90-day forecast is generated for July 2026 onwards
Then October-November projections reflect the seasonal uplift
And the model's MAPE (Mean Absolute Percentage Error) is displayed for transparency
Scenario: Forecast accuracy tracking
Given last month's forecast predicted 75% average occupancy
And actual occupancy was 72%
When I view the forecast accuracy dashboard
Then it shows: Predicted 75%, Actual 72%, Error 3pp, MAPE 4%
And a 12-month accuracy trend is displayed
US-012-18: Competitive Set Analysis
As a Revenue Manager, I want to benchmark my hotel's performance against local competitors, So that I can identify pricing opportunities and market position.
Priority: P2 | Points: 8 | Sprint: 6 | Status: Partial
Implementation Status
Competitor intelligence dashboard is partially built. The UI allows defining a competitive set (up to 5 competitor hotels) and entering their published rates manually. Comparison charts for ADR and estimated occupancy are available. However, there is no automated data feed -- all competitor data is manually entered. Rate shopping integration (e.g., OTA scraping or RateGain/OTA Insight API) is not implemented.
Acceptance Criteria
Scenario: Define competitive set
Given I am the Revenue Manager for "Hotel Sunrise, Jaipur"
When I define my compset: "Hotel Heritage Palace", "Radisson Jaipur", "ITC Rajputana", "Marriott Jaipur"
Then each competitor is saved with: name, star rating, room count, and location
And the compset dashboard shows all 5 properties (mine + 4 competitors) in a comparison table
Scenario: Manual rate entry and comparison
Given I enter today's BAR for competitors:
| Property | Standard Rate | Deluxe Rate |
| Hotel Sunrise | 5,500 INR | 8,000 INR |
| Hotel Heritage Palace| 6,200 INR | 9,500 INR |
| Radisson Jaipur | 5,800 INR | 8,500 INR |
When the comparison view loads
Then a bar chart shows my rates vs. compset average
And my rate index is calculated: 5,500 / avg(6,000) = 0.92 (I'm 8% below average)
And the system suggests: "Consider rate increase of 200-500 INR to improve RGI"
Scenario: Track compset performance over time
Given I have entered competitor rates weekly for the past 3 months
When I view the trend analysis
Then a line chart shows my ADR vs. compset average ADR over time
And RevPAR index (RPI) trend is displayed if occupancy estimates are available
US-012-19: Night Audit Balance Verification
As a Night Auditor, I want the system to verify that all guest folios balance correctly and flag discrepancies, So that financial integrity is maintained before day close.
Priority: P0 | Points: 8 | Sprint: 3 | Status: Partial
Implementation Status
Balance verification queries all in-house guest folios and compares charges vs. payments. The summary is displayed in the night audit wizard. However, automatic discrepancy resolution suggestions are not implemented, and the auditor must manually investigate each imbalance. The system does not yet verify city ledger and advance deposit balances.
Acceptance Criteria
Scenario: All folios balance
Given 62 rooms are in-house and all folios have charges matching payments/credits
When the balance verification step runs
Then a green checkmark shows "All 62 folios verified. No discrepancies."
And the auditor can proceed to the next step
Scenario: Detect and report discrepancies
Given Room 205 has charges totaling 12,500 INR but payments of 10,000 INR (2,500 INR balance)
And Room 410 has a credit of 500 INR (overpayment)
When balance verification runs
Then the report shows:
| Room | Guest | Charges | Payments | Balance | Issue |
| 205 | Ravi Kumar | 12,500 | 10,000 | 2,500 DR | Unpaid balance|
| 410 | Meena Shah | 8,000 | 8,500 | 500 CR | Overpayment |
And the auditor can add notes and mark as "Reviewed" or "Pending Resolution"
Scenario: Verify advance deposit balances
Given 5 future reservations have advance deposits totaling 75,000 INR
When the balance verification includes advance deposits
Then the deposit liability total is reconciled with the advance deposit bank account
And any mismatches are flagged
US-012-20: Scheduled Report Delivery
As a General Manager, I want key reports to be automatically generated and emailed on a schedule, So that I receive my daily/weekly summary without logging into the dashboard.
Priority: P1 | Points: 5 | Sprint: 4 | Status: Not Started
Implementation Status
Not implemented. There is no scheduler for report generation and no integration with the notification-service for report delivery. The General Manager currently must log in daily to view reports.
Acceptance Criteria
Scenario: Schedule daily revenue summary
Given I configure a scheduled report: "Daily Revenue Summary", recipients: GM + Finance Manager, schedule: daily at 07:00 IST, format: PDF
When 07:00 IST arrives on 2026-03-06
Then the analytics-service generates the revenue summary for 2026-03-05
And the PDF is emailed to both recipients via the notification-service
And the email subject is "Daily Revenue Summary - Hotel Sunrise - 05 Mar 2026"
Scenario: Weekly occupancy trend report
Given a weekly report is configured for every Monday at 08:00 IST
When Monday 2026-03-09 08:00 IST arrives
Then the report covers the previous week (Mon-Sun)
And includes occupancy trend chart, ADR/RevPAR comparison, and week-over-week change
Scenario: Handle report generation failure
Given the analytics database is temporarily unavailable at the scheduled time
When the report generation fails
Then the system retries 3 times with 5-minute intervals
And if all retries fail, an alert email is sent to the Super Admin
And the scheduled report is marked as "Failed" with error details in the admin console