EP-005C: Night Audit
Parent Epic: EP-005 Front Desk Operations Split Note: EP-005 has been split into sub-epics EP-005A, EP-005B, EP-005C, EP-005D. This file covers night audit start/complete/rollback, pre-audit validation, no-show processing, and chain-level audit orchestration.
| Field | Value |
|---|---|
| Epic ID | EP-005C |
| Epic Name | Night Audit |
| Parent Epic | EP-005 Front Desk Operations |
| Owner | Front Desk Module Lead |
| Created | 2026-03-27 |
| Last Updated | 2026-03-27 |
| Status | In Progress |
| Priority | P0 - Critical |
1. Business Objective
Reduce the nightly end-of-day reconciliation from 2-3 hours of manual work to a fully automated 15-minute process. Night audit is the financial backbone of hotel operations — it posts room charges, taxes, closes open folios, processes no-shows, rolls the business date, and generates the Day-End Report. Errors in night audit cascade into incorrect GST filings and P&L statements. For a multi-property chain, the audit must orchestrate across all properties in sequence and surface exceptions to a central dashboard.
2. Audience
| Role | Interaction |
|---|---|
| Night Auditor | Runs pre-audit checks, initiates audit, monitors progress, resolves exceptions |
| Front Desk Manager | Reviews Day-End Report, approves rollback if exceptions require correction |
| Finance Manager | Receives consolidated audit report; reconciles with P&L |
| Chain Admin | Monitors multi-property audit status from chain dashboard (EP-018) |
3. Scope
3.1 In Scope
- Pre-audit validation report: open folios with balance, pending check-outs, un-assigned rooms, cashier shifts open
- Night audit initiation (manual trigger or scheduled cron at configurable time, default 00:01 IST)
- Room rate posting for all in-house reservations (per night, per room type, per rate plan)
- Tax posting: CGST + SGST (or IGST for inter-state) on all room charges
- Cashier shift close: balance cash drawer, reconcile card/UPI/cash totals
- No-show processing: identify reservations that were CONFIRMED but never checked in; apply no-show policy charge
- Auto-express-checkout: zero-balance in-house departures past checkout time
- Business date rollover: advance property date after all steps complete
- Day-End Report: summary of transactions, revenue by type, room statistics, exceptions
- Audit log with hash-chain integrity (tamper-evident; each entry includes SHA-256 hash of previous)
- Rollback: cancel an in-progress audit if a critical exception is found; restore pre-audit state
- Resume: continue a paused audit from the last successfully completed step
- Chain audit orchestration: property-by-property audit run with central status tracking (EP-018 integration)
- Audit history: list of past audit runs, status, duration, exception count
3.2 Out of Scope
- Folio charging and payment (EP-005B)
- GSTR-1 / GST reports (EP-012C)
- Financial P&L (EP-012B)
- Housekeeping end-of-day (EP-006)
4. Current Implementation Status
4.1 Backend — frontdesk-service
| Controller / Endpoint | Status | Notes |
|---|---|---|
POST /audit/run | Built | Full night audit; but rate posting still needs batch fix |
GET /audit/status | Built | Current run status and step progress |
GET /audit/pre-check | Built | Pre-audit validation; returns exceptions list |
POST /audit/rollback | Partial | Rollback logic exists; state restoration incomplete |
POST /audit/resume | Not Started | Step-aware resume after pause |
GET /audit/history | Built | Past runs with status and reports |
GET /audit/report/:date | Built | Day-End Report for a specific business date |
POST /audit/noshow | Not Started | Automated no-show identification and charge |
| Chain audit orchestration | Not Started | Multi-property sequencing (EP-018 dependency) |
GET /audit/cashier-shift | Partial | Summary exists; closing workflow incomplete |
4.2 Dashboard — 02-hmp-web-dashboard
| Component | Status | Notes |
|---|---|---|
| Night Audit Dashboard | Built | Status panel, logs viewer, manual trigger button |
| Pre-Audit Checklist UI | Partial | Shows exceptions; no guided resolution flow |
| Day-End Report View | Built | Revenue summary, room stats, exception log |
| Audit History List | Built | Past runs with drill-down |
5. Gap Analysis
| # | Gap | Impact | Effort | Priority |
|---|---|---|---|---|
| 1 | Rate posting is per-room loop (needs batch SQL for 200+ rooms) | High | M | P0 |
| 2 | No-show processing not automated (auditor manually identifies) | High | M | P0 |
| 3 | Rollback state restoration incomplete | High | M | P1 |
| 4 | Resume-from-step not implemented | Medium | S | P1 |
| 5 | Chain audit orchestration requires EP-018 API | Medium | L | P2 |
| 6 | Cashier shift close workflow incomplete | Medium | S | P1 |
6. User Stories
| Story ID | Title | Priority | Points | Sprint | Status |
|---|---|---|---|---|---|
| US-005-07 | Night Audit Automation | P0 | 13 | 2 | Built |
| US-005-22 | Night Audit Report & Logs | P0 | 5 | 2 | Built |
| US-005C-01 | Pre-Audit Validation Report | P0 | 5 | 2 | Built |
| US-005C-02 | No-Show Processing (Automated) | P0 | 8 | 3 | Not Started |
| US-005C-03 | Night Audit Rollback | P1 | 8 | 3 | Partial |
| US-005C-04 | Night Audit Resume | P1 | 5 | 4 | Not Started |
| US-005C-05 | Cashier Shift Close | P1 | 5 | 3 | Partial |
| US-005C-06 | Chain Audit Orchestration | P2 | 13 | 6 | Not Started |
| US-005C-07 | Scheduled Audit (Auto-Trigger) | P1 | 5 | 3 | Partial |
7. Detailed User Stories
US-005-07: Night Audit Automation
As a Night Auditor, I want to run the night audit with a single click and have the system automatically post all room rates, taxes, and close all open folios, So that the business date rolls over accurately without manual transaction-by-transaction work.
Priority: P0 | Points: 13 | Sprint: 2 | Status: Built
Implementation Status
POST /audit/run executes a multi-step pipeline: (1) pre-check, (2) lock new check-ins, (3) post room rates, (4) post taxes, (5) close cashier shift, (6) process no-shows, (7) roll business date, (8) generate report. Steps are logged with timestamps. Currently rate posting is implemented but runs per-room in a loop; batch SQL upgrade needed for scale.
Acceptance Criteria
Scenario: Successful automated night audit
Given the business date is 2026-03-27
And 62 rooms are occupied with confirmed rate plans
When the auditor clicks "Run Night Audit"
Then all 62 rooms receive room rate and tax charges in their folios
And the business date advances to 2026-03-28
And a Day-End Report is generated
And the audit completes within 15 minutes
Scenario: Audit blocked by open cashier shift
Given cashier shift for "Evening Desk" is still open with INR 12,400 cash
When the auditor initiates night audit
Then the pre-check returns: "1 cashier shift open — please close before proceeding"
And audit does not start until the shift is closed
US-005C-02: No-Show Processing (Automated)
As a Night Auditor, I want to have the audit automatically identify reservations that were never checked in and apply the no-show charge per the cancellation policy, So that no-show revenue is captured without manual intervention.
Priority: P0 | Points: 8 | Sprint: 3 | Status: Not Started
Implementation Notes
- Step 6 in the audit pipeline: query all CONFIRMED reservations with arrival date = yesterday that have no
checkedInAt - For each: apply no-show charge per
CancellationPolicy.noShowCharge(% of first night or flat) - Post charge to the reservation folio, update status to
NO_SHOW - Publish Kafka event
reservation.noShow - Send notification to guest via EP-014 (notification service)
Acceptance Criteria
Scenario: No-show charge applied during audit
Given reservation RES-2026-0314 was due to arrive 2026-03-27 but was never checked in
And the cancellation policy specifies "no-show charge = 100% of first night"
When night audit runs
Then reservation status changes to "NO_SHOW"
And a charge of INR 6,250 (one night's rate) is posted to the folio
And a no-show notification email is sent to the guest
And the Day-End Report includes "3 no-shows, total charge INR 18,750"
Scenario: No charge if flexible policy
Given a reservation with "Flexible" policy (no-show charge = 0%)
When night audit processes the no-show
Then reservation status changes to "NO_SHOW"
But no charge is posted to the folio
And the report notes "0 charge — flexible policy"
US-005C-03: Night Audit Rollback
As a Night Auditor, I want to rollback an in-progress or recently completed night audit if a critical error is discovered, So that incorrect charges can be reversed and the audit re-run after corrections.
Priority: P1 | Points: 8 | Sprint: 3 | Status: Partial
Implementation Status
POST /audit/rollback exists. It reverses rate postings (creates void line items) and resets the business date. State restoration for cashier shift and no-show charges is incomplete.
Acceptance Criteria
Scenario: Rollback after rate posting error
Given audit ran and posted incorrect rates (wrong rate plan applied)
When the auditor triggers rollback within 2 hours of audit completion
Then all rate charges posted during the audit are reversed (void line items)
And the business date reverts to the pre-audit date
And a rollback log is created with auditor name and reason
And the night audit status shows "ROLLED_BACK"
Scenario: Rollback window expired
Given audit completed more than 2 hours ago
When auditor attempts rollback
Then system rejects with "Rollback window expired — contact Finance Manager"
US-005C-06: Chain Audit Orchestration
As a Chain Admin, I want to trigger and monitor night audit across all 5 properties in the chain from a single control panel, So that I can ensure all properties complete audit and identify any that are blocked.
Priority: P2 | Points: 13 | Sprint: 6 | Status: Not Started
Implementation Notes
- Depends on EP-018 multi-property chain management
- Chain Admin calls
POST /chain/audit/runwhich iterates over all active properties - Per-property audit status polled via
GET /audit/statuswith property context header - Central status page shows: property name, status (pending/running/complete/failed), duration, exception count
- Chain audit runs properties sequentially (not in parallel) to avoid DB lock contention
Acceptance Criteria
Scenario: Chain audit with all properties succeeding
Given chain "Sunrise Hotels" has 5 properties
When the chain admin triggers "Chain Night Audit" at 01:00 IST
Then properties are audited one-by-one in configured sequence
And all 5 show "COMPLETE" by 02:30 IST
And a consolidated chain report shows total revenue across all properties
Scenario: One property fails audit
Given "Sunrise Goa" has 2 open cashier shifts
When chain audit reaches "Sunrise Goa"
Then that property's audit is marked "BLOCKED — 2 open cashier shifts"
And remaining properties continue their audit
And an alert is sent to "Sunrise Goa" Front Desk Manager
8. Dependencies
| Dependency | Type | Epic / Service | Status |
|---|---|---|---|
| Folio service (rate posting, charges) | Sibling | EP-005B / frontdesk | Available |
| Reservation service (no-show detect) | Upstream | EP-003 / reservation | Available |
| Property service (business date, config) | Upstream | EP-002 / property | Available |
| Auth (night auditor role) | Upstream | EP-001 / auth | Available |
| Notification service (no-show email) | Downstream | EP-014 / notification | Available |
| Chain management (EP-018) | Peer | EP-018 / property | Partial |
| Kafka (audit events) | Infra | Docker / Kafka | Available |
| Redis (audit state cache) | Infra | Docker / Redis | Available |
9. Acceptance Criteria (Sub-Epic Level)
- AC-EP-005C-01: Night audit runs automatically at the configured time and completes without manual intervention when no exceptions exist.
- AC-EP-005C-02: Rate and tax posting handles 200+ rooms in a single batch operation (< 60 seconds).
- AC-EP-005C-03: No-show processing identifies all unattended CONFIRMED arrivals and applies the correct policy charge.
- AC-EP-005C-04: Rollback reverses all audit-posted charges and restores the pre-audit business date within a 2-hour window.
- AC-EP-005C-05: Day-End Report includes: revenue by type, rooms sold, no-show count, exceptions, and cashier totals.
- AC-EP-005C-06: Audit log entries are hash-chained; any tampering with past entries is detectable by integrity verification.
10. Technical Notes
- Audit controller:
01-hmp-backend/apps/frontdesk-service/src/audit/audit.controller.ts - Audit service:
01-hmp-backend/apps/frontdesk-service/src/audit/audit.service.ts - Audit log hash chain:
01-hmp-backend/apps/analytics-service/src/auditlog/— SHA-256 chain linking; see EP-012 for analytics-side audit log - The
audit.service.tspipeline uses a step-tracker pattern: each step is named and its completion state persisted to Redis so thatresumecan restart from the last completed step - Batch rate posting improvement: replace per-room Prisma
create()calls with a singlecreateMany()or raw SQLINSERT INTO folio_charges SELECT ...for 10x throughput - Scheduled audit uses NestJS
@Cron()decorator; configurable per tenant viaTenantConfig.nightAuditTime(Sprint 5 deliverable)