EP-018: Multi-Property & Chain Management

Business Objective

Hotel chains in India (Taj, Oberoi, Lemon Tree, OYO, and hundreds of regional chains with 3-20 properties) need a unified view across all properties to make strategic decisions. A chain GM or revenue director must compare occupancy, ADR, and RevPAR across properties in real time, manage centralized rate strategies pushed to all properties, maintain a single guest profile across the chain (so that a loyalty member at the Mumbai property is recognized at the Goa property), and produce consolidated financial reports. Without chain management, each property operates as an isolated silo, guest loyalty is fragmented, rate strategies are inconsistent, and corporate reporting requires manual aggregation from each property.

Audience

Primary: Chain GM, Revenue Director, Regional Manager
Secondary: Corporate Finance (consolidated P&L), CRM Manager (cross-property guest profiles), HR (staff transfer)
Tertiary: Property-level GMs (receiving chain rate directives), Super Admin (tenant provisioning)

Scope

In Scope

Chain dashboard with cross-property KPIs (total rooms, occupancy, ADR, RevPAR, revenue by property)
Property comparison charts (benchmarking one property against another)
Chain-wide guest management: single guest profile across properties (deduplication, merge)
Centralized rate management: define chain-level rates and push/sync to all properties
Cross-property reporting: consolidated P&L, revenue by property, occupancy trends
Property alerts and notifications (low occupancy alerts, high cancellation rates)
Staff sharing/transfer across properties within the same tenant
Chain-level loyalty program: earn points at any property, redeem at any property
Brand standards compliance tracking per property

Out of Scope

Franchise management (properties owned by different entities under brand license)
Inter-property billing/settlements (transfer pricing between properties)
Centralized procurement (purchasing is per-property)
Chain-level POS menu standardization (each property has its own F&B)

Current Implementation Status

Backend

Chain Service (analytics-service): ChainService with getChainProperties() that fetches all properties for a tenant with real-time KPIs (total rooms, occupancy, revenue, ADR, RevPAR). ChainController exposes chain metrics, property list, alerts, cross-property reports, brand standards, consolidated night audit. ChainMetricsDto with comprehensive DTOs.
Chain Rates (property-service): ChainRatesService and ChainRatesController for defining and managing chain-level rate plans. Module registered in property-service app module.
Chain Loyalty (crm-service): ChainLoyaltyService, ChainLoyaltyController, and PartnerProgramService for cross-property loyalty program management. Separate module with controller.
Guest Deduplication (guest-service): DeduplicationService in guest-service sync module. GuestSyncController exposes sync endpoints.
Multi-Tenant: Prisma schema has tenantId on properties and users. A tenant with multiple properties conceptually represents a chain.

Dashboard (02-hmp-web-dashboard)

Chain dashboard page (/chain) with metrics overview
Chain properties listing (/chain/properties) with drill-down (/chain/properties/[id])
Chain guests page (/chain/guests) for cross-property guest management
Chain rates page (/chain/rates) for centralized rate management
Chain reports page (/chain/reports) for cross-property analytics
useChain hook and chain.ts API client in dashboard lib

Gap Analysis

Area	Current State	Gap	Impact
Guest Deduplication	DeduplicationService exists	Matching algorithm (name + phone/email fuzzy match) not proven at scale; no manual merge UI for ambiguous matches; same guest at 2 properties = 2 profiles	Loyalty points fragmented; guest history incomplete at check-in
Chain Rate Push	ChainRatesService defines chain rates	No automated push mechanism to sync chain rates to property-level rate plans; requires manual property-by-property update	Rate strategy inconsistency across properties
Consolidated P&L	Chain reports endpoint exists	No automated aggregation of revenue, expenses, and profit by property into a single P&L statement; reports are revenue-only	CFO lacks consolidated financial view
Staff Transfer	User model has propertyId	No workflow to reassign a user to a different property; no transfer history tracking; role/permissions may differ per property	HR must manually deactivate at one property and recreate at another
Chain Loyalty	ChainLoyaltyService + PartnerProgramService exist	Property-level loyalty is separate from chain loyalty; points earned at Property A not automatically visible at Property B	Guest frustration when loyalty status not recognized
Property Comparison	Chain metrics available	No side-by-side comparison view; no benchmark index; no heat map visualization	Revenue director cannot quickly identify underperforming properties
Alert Engine	Not implemented for chain	No configurable alerts (occupancy < 50%, cancellation rate > 20%, ADR drop > 10%)	Problems at individual properties go unnoticed at chain level
Brand Standards	DTO defined	No scoring mechanism; no compliance checklist; no photographic evidence	Brand consistency cannot be measured or enforced
Night Audit Consolidation	ConsolidatedNightAuditDto defined	No batch execution or aggregation of night audit results across properties	Chain operations team cannot verify all properties completed night audit

User Stories

Story ID	Title	Priority	Points	Status	Sprint
US-018-001	Chain Dashboard with Cross-Property KPIs	P0	8	Built	7
US-018-002	Property Comparison & Benchmarking	P1	5	Partial	9
US-018-003	Chain-Wide Guest Deduplication & Merge	P0	13	Partial	9
US-018-004	Centralized Rate Management & Push	P0	8	Partial	8
US-018-005	Consolidated Cross-Property P&L Report	P1	8	Not Started	10
US-018-006	Staff Transfer Between Properties	P2	5	Not Started	12
US-018-007	Chain-Level Loyalty Program	P1	8	Partial	10
US-018-008	Property Alert & Notification Engine	P1	5	Not Started	11
US-018-009	Brand Standards Compliance Tracker	P2	5	Not Started	13

Dependencies

EP-001 (Auth & Access): Chain roles (Chain GM, Regional Manager) need RBAC permissions spanning multiple properties
EP-006 (Guest Management): Guest deduplication operates on guest-service data
EP-003 (Room & Rate Management): Chain rates push to property-level rate plans
EP-013 (Analytics & Reports): Chain reports extend the analytics-service
EP-014 (CRM & Loyalty): Chain loyalty extends property-level loyalty program
EP-019 (Platform Admin): Tenant structure underlies multi-property grouping

Acceptance Criteria (Epic Level)

Chain dashboard shows real-time KPIs for all properties under the tenant
Guest profiles are deduplicated across properties with > 95% match accuracy
Chain-level rates propagate to all properties within 5 minutes of publishing
Consolidated P&L report aggregates revenue and expenses from all properties
Loyalty points earned at any property are visible and redeemable at any other property
Property alerts trigger within 15 minutes of threshold breach
Staff can be transferred between properties with role/permission preservation

KPIs / Success Metrics

Chain dashboard load time < 3 seconds (even for 20+ properties)
Guest deduplication match accuracy > 95%
Rate push propagation time < 5 minutes to all properties
Consolidated report generation time < 30 seconds for 10 properties
Cross-property loyalty redemption rate > 15% of total redemptions
Alert false positive rate < 5%
Staff transfer completion time < 1 business day

Detailed User Stories

US-018-001: Chain Dashboard with Cross-Property KPIs

As a Chain GM, I want to view a unified dashboard showing occupancy, ADR, RevPAR, and revenue across all my properties, So that I can make strategic decisions based on real-time chain-wide performance. Priority: P0 | Points: 8 | Sprint: 7 | Status: Built

Implementation Status

ChainService.getChainProperties() fetches all active properties for the tenant, calculates per-property occupancy (occupied rooms / total rooms), revenue (today's reservation totals), ADR, and RevPAR. ChainController exposes /chain/properties, /chain/metrics, /chain/alerts. Dashboard /chain page renders the overview with property cards. useChain hook and API client handle data fetching.

Acceptance Criteria

Scenario: View chain-wide KPIs
  Given the chain "Heritage Hotels India" has 5 properties in Mumbai, Delhi, Goa, Jaipur, and Bangalore
  When the Chain GM opens the Chain Dashboard
  Then the dashboard shows aggregate KPIs:
    | Metric         | Value              |
    | Total Rooms    | 750                |
    | Overall Occ.   | 72%                |
    | Chain ADR      | INR 6,800          |
    | Chain RevPAR   | INR 4,896          |
    | Today Revenue  | INR 36,72,000      |
  And each property is listed with its individual KPIs
  And a map or card layout shows property locations with color-coded occupancy

Scenario: Drill down to property detail
  Given the Chain GM views the chain dashboard
  When they click on "Heritage Hotels Goa"
  Then the view navigates to the property-specific dashboard (`/chain/properties/[id]`)
  And shows room-level occupancy, arrivals/departures today, and revenue breakdown
  And the Chain GM can navigate back to the chain view without losing context

US-018-002: Property Comparison & Benchmarking

As a Revenue Director, I want to compare KPIs between two or more properties side-by-side, So that I can identify underperforming properties and take corrective action. Priority: P1 | Points: 5 | Sprint: 9 | Status: Partial

Implementation Status

Chain metrics are available per property. Dashboard chain page exists but lacks dedicated comparison view with side-by-side charts and benchmark indexing.

Acceptance Criteria

Scenario: Compare two properties side-by-side
  Given the Revenue Director selects "Heritage Hotels Mumbai" and "Heritage Hotels Delhi" for comparison
  When the comparison view loads
  Then a side-by-side table shows:
    | Metric      | Mumbai    | Delhi     | Delta     |
    | Rooms       | 200       | 180       | +20       |
    | Occupancy   | 78%       | 65%       | +13pp     |
    | ADR         | INR 8,500 | INR 7,200 | +INR 1,300|
    | RevPAR      | INR 6,630 | INR 4,680 | +INR 1,950|
    | Revenue MTD | 51L       | 38L       | +13L      |
  And line charts show 30-day trends for occupancy and ADR with both properties overlaid

Scenario: Chain benchmark index
  Given the chain has 5 properties
  When the Revenue Director opens the benchmark report
  Then each property shows a "Chain Index" score where 100 = chain average
  And Mumbai at 115 (above average) is green, Delhi at 87 (below average) is amber
  And the lowest-performing property is highlighted with recommended actions

US-018-003: Chain-Wide Guest Deduplication & Merge

As a CRM Manager, I want to identify and merge duplicate guest profiles across properties, So that each guest has a single unified profile with complete stay history and loyalty status. Priority: P0 | Points: 13 | Sprint: 9 | Status: Partial

Implementation Status

DeduplicationService in guest-service and GuestSyncController exist. Guest model is per-property (propertyId on Guest). Gap: deduplication algorithm needs fuzzy matching (Levenshtein on name, exact on phone/email); no merge UI for ambiguous matches; no "golden record" concept (single source of truth across properties); merged guest needs reservation history from all properties.

Acceptance Criteria

Scenario: Automatic deduplication match detection
  Given guest "Priya Sharma" (phone +91-9876543210) exists at Mumbai property
  And guest "Priya Sharma" (phone +91-9876543210) exists at Goa property
  When the nightly deduplication job runs
  Then the system identifies the match with confidence score 98% (exact phone + exact name)
  And creates a merge suggestion with both profiles displayed side-by-side
  And the CRM Manager receives a notification: "1 potential duplicate guest found"

Scenario: Manual merge of duplicate profiles
  Given the CRM Manager reviews a merge suggestion for "Priya Sharma"
  And Mumbai profile has 5 stays, 12,000 loyalty points
  And Goa profile has 2 stays, 4,000 loyalty points
  When the CRM Manager clicks "Merge" and selects Mumbai as the primary profile
  Then the golden record retains Mumbai's profile data (email, address, preferences)
  And Goa reservations are linked to the golden record
  And loyalty points are combined: 16,000 total
  And total stays updates to 7 across both properties
  And the Goa duplicate is soft-deleted with a reference to the golden record

Scenario: Fuzzy match for name variations
  Given guest "Priya S. Sharma" exists at Delhi with email priya@email.com
  And guest "Priya Sharma" exists at Jaipur with email priya@email.com
  When deduplication runs
  Then the system matches on exact email despite name variation
  And confidence score is 90% (exact email, fuzzy name match)
  And the suggestion is flagged for manual review

US-018-004: Centralized Rate Management & Push

As a Revenue Director, I want to define chain-level rate plans and push them to all properties, So that pricing strategy is consistent across the chain and I do not have to update each property individually. Priority: P0 | Points: 8 | Sprint: 8 | Status: Partial

Implementation Status

ChainRatesService and ChainRatesController in property-service allow defining chain-level rates. Dashboard chain rates page (/chain/rates) provides UI for rate management. Gap: no automated push/sync mechanism to copy chain rate definitions to property-level RatePlan and RatePlanRate records; no selective push (e.g., push to Mumbai and Delhi but not Goa); no override allowance (property GM can adjust by +/- 10%).

Acceptance Criteria

Scenario: Define and push chain BAR rate
  Given the Revenue Director creates a chain rate plan "Chain BAR Q2 2026"
  With rates:
    | Room Type    | Weekday   | Weekend    |
    | Standard     | INR 5,000 | INR 6,500  |
    | Deluxe       | INR 8,000 | INR 10,000 |
    | Suite        | INR 15,000| INR 18,000 |
  When they click "Push to All Properties"
  Then each property receives the chain rate plan with rates mapped to their local room types
  And existing property BAR rates are updated to match chain rates
  And a sync log records: pushed to 5/5 properties, 0 failures

Scenario: Property-level override with chain approval
  Given chain rate for "Standard Weekday" is INR 5,000
  And the Jaipur property GM wants to reduce to INR 4,500 for a local event
  When the GM submits an override request for INR 4,500 with reason "Jaipur Literature Festival"
  Then the request goes to the Revenue Director for approval
  And upon approval, Jaipur's rate updates to INR 4,500 for the specified date range
  And the chain dashboard shows Jaipur marked as "Override Active" for those dates

Scenario: Selective rate push to specific properties
  Given a new corporate rate plan "TCS Corporate Rate" is created at chain level
  When the Revenue Director pushes it to Mumbai and Bangalore only (TCS offices)
  Then only Mumbai and Bangalore properties receive the rate plan
  And Delhi, Goa, and Jaipur are unaffected
  And the push report shows: "Pushed to 2/5 properties (selected)"

US-018-005: Consolidated Cross-Property P&L Report

As a Corporate Finance Controller, I want to generate a consolidated P&L report across all properties, So that I can present chain-wide financial performance to the board without manual aggregation. Priority: P1 | Points: 8 | Sprint: 10 | Status: Not Started

Implementation Status

Chain reports endpoint exists in analytics-service ChainController. CrossPropertyReportDto is defined. Gap: no P&L aggregation logic; no expense data collection (HMP tracks revenue but not operational expenses); no inter-property elimination; no comparison with budget.

Acceptance Criteria

Scenario: Consolidated monthly P&L
  Given the chain has 5 properties with the following March 2026 data:
    | Property   | Room Rev   | F&B Rev    | Spa Rev   | Other Rev  |
    | Mumbai     | 1.2 Cr     | 40L        | 12L       | 8L         |
    | Delhi      | 95L        | 35L        | 10L       | 5L         |
    | Goa        | 80L        | 50L        | 25L       | 10L        |
    | Jaipur     | 60L        | 20L        | 5L        | 3L         |
    | Bangalore  | 1.0 Cr     | 38L        | 15L       | 7L         |
  When the finance controller generates the consolidated P&L for March 2026
  Then the report shows:
    | Line Item           | Chain Total    |
    | Room Revenue        | 4.55 Cr        |
    | F&B Revenue         | 1.83 Cr        |
    | Spa Revenue         | 67L            |
    | Other Revenue       | 33L            |
    | Total Revenue       | 7.38 Cr        |
  And each line item can be expanded to show per-property breakdown
  And the report is exportable as Excel and PDF

Scenario: Month-over-month comparison
  Given March 2026 total revenue is INR 7.38 Cr
  And February 2026 total revenue was INR 6.90 Cr
  When the P&L report includes MoM comparison
  Then the variance shows +INR 48L (+6.9%)
  And properties contributing to growth vs decline are highlighted

US-018-006: Staff Transfer Between Properties

As an HR Manager, I want to transfer a staff member from one property to another within the chain, So that the employee retains their user account, training records, and appropriate role at the new property. Priority: P2 | Points: 5 | Sprint: 12 | Status: Not Started

Implementation Status

User model has propertyId which can theoretically be updated. No transfer workflow, no transfer history, no role mapping between properties (e.g., Front Desk Lead at Mumbai may become Front Desk Agent at Delhi), no approval chain.

Acceptance Criteria

Scenario: Transfer front desk agent to another property
  Given staff member "Rahul Verma" (FRONT_DESK role) is assigned to Heritage Hotels Mumbai
  When the HR Manager initiates a transfer to Heritage Hotels Delhi effective March 15, 2026
  Then a transfer request is created with:
    | Field            | Value                    |
    | employee         | Rahul Verma              |
    | fromProperty     | Heritage Hotels Mumbai   |
    | toProperty       | Heritage Hotels Delhi    |
    | effectiveDate    | 2026-03-15               |
    | newRole          | FRONT_DESK (same)        |
  And the Mumbai GM and Delhi GM receive approval requests
  And upon both approvals, the user's propertyId updates to Delhi on the effective date
  And Rahul retains his login credentials and audit history

Scenario: Transfer with role change
  Given staff member "Anita Desai" is a HOUSEKEEPING role at Goa property
  When she is transferred to Mumbai as FRONT_DESK role
  Then her permissions update to match the FRONT_DESK role at Mumbai
  And her previous HOUSEKEEPING permissions at Goa are revoked
  And the transfer history records both property and role changes

US-018-007: Chain-Level Loyalty Program

As a Guest, I want to earn and redeem loyalty points at any property in the chain, So that my loyalty status is recognized regardless of which property I visit. Priority: P1 | Points: 8 | Sprint: 10 | Status: Partial

Implementation Status

ChainLoyaltyService and ChainLoyaltyController in crm-service with partner program support. Property-level LoyaltyProgram, LoyaltyTier, LoyaltyMember, PointsTransaction models exist. Gap: property-level loyalty operates independently; points earned at Property A are stored per-property; no chain-level aggregation of points balance; no cross-property redemption verification.

Acceptance Criteria

Scenario: Earn points at Mumbai, redeem at Goa
  Given guest "Priya Sharma" is a chain loyalty member (Gold tier, 15,000 points)
  And she earned 5,000 points from her last stay at Heritage Hotels Mumbai
  When she checks in at Heritage Hotels Goa and requests a room upgrade using 3,000 points
  Then the front desk agent sees her chain-wide loyalty status: Gold, 15,000 points
  And redeems 3,000 points for the upgrade
  And her balance updates to 12,000 points chain-wide
  And the points transaction records: source=Goa, type=REDEEM, referenceId=reservation_id

Scenario: Chain loyalty tier calculation
  Given chain loyalty tiers are: Silver (5,000 pts), Gold (15,000 pts), Platinum (50,000 pts)
  And guest "Priya Sharma" has earned 12,000 points at Mumbai and 4,000 at Delhi (total 16,000)
  When the monthly tier evaluation runs
  Then Priya qualifies for Gold tier based on chain-wide total of 16,000 points
  And she would not have qualified based on either property alone
  And her tier upgrade is reflected at all properties immediately

US-018-008: Property Alert & Notification Engine

As a Regional Manager, I want to receive automatic alerts when a property's KPIs breach configured thresholds, So that I can intervene early before performance deteriorates further. Priority: P1 | Points: 5 | Sprint: 11 | Status: Not Started

Implementation Status

ChainController has an alerts endpoint but no automated threshold monitoring or notification system. Alert DTOs are defined but not populated by any scheduled job.

Acceptance Criteria

Scenario: Low occupancy alert
  Given the alert rule "Occupancy < 50% for any property" is configured
  And Heritage Hotels Delhi current occupancy drops to 45%
  When the hourly monitoring job runs
  Then the system creates an alert: "Delhi occupancy at 45% (threshold: 50%)"
  And the Regional Manager receives an email and push notification
  And the alert appears on the chain dashboard with severity "WARNING"

Scenario: High cancellation rate alert
  Given the alert rule "Cancellation rate > 15% over 7-day rolling window" is configured
  And Heritage Hotels Jaipur has 18% cancellation rate this week
  When the monitoring job detects the breach
  Then an alert is created with property name, current rate, threshold, and affected period
  And the alert includes top cancellation reasons (if available)
  And the Regional Manager can acknowledge the alert and add notes

US-018-009: Brand Standards Compliance Tracker

As a Chain GM, I want to track brand standards compliance across all properties, So that guest experience is consistent and the brand reputation is maintained. Priority: P2 | Points: 5 | Sprint: 13 | Status: Not Started

Implementation Status

PropertyBrandStandardsDto is defined in chain metrics DTOs. No scoring mechanism, no checklist engine, no photo evidence, no compliance reporting.

Acceptance Criteria

Scenario: Brand standards audit checklist
  Given the chain has defined brand standards across 5 categories:
    | Category         | Items | Weight |
    | Room Quality     | 20    | 30%    |
    | F&B Standards    | 15    | 25%    |
    | Staff Grooming   | 10    | 15%    |
    | Common Areas     | 15    | 20%    |
    | Digital Presence | 5     | 10%    |
  When the Regional Manager completes the quarterly audit for Heritage Hotels Goa
  Then each item is scored (1-5) with optional photo evidence
  And the property's overall brand compliance score is calculated (weighted average)
  And the score is displayed on the chain dashboard: "Goa: 4.2/5 (84%)"
  And properties below 3.5/5 are flagged for improvement action

Scenario: Brand compliance trend
  Given Heritage Hotels Mumbai scored 3.8 in Q3 2025, 4.0 in Q4 2025, 4.3 in Q1 2026
  When the Chain GM views the brand compliance trend report
  Then a line chart shows the improving trajectory for Mumbai
  And all properties are plotted on the same chart for comparison
  And the chain average trend line is shown as a benchmark

Business Objective​

Audience​

Scope​

In Scope​

Out of Scope​

Current Implementation Status​

Backend​

Dashboard (02-hmp-web-dashboard)​

Gap Analysis​

User Stories​

Dependencies​

Acceptance Criteria (Epic Level)​

KPIs / Success Metrics​

Detailed User Stories​

US-018-001: Chain Dashboard with Cross-Property KPIs​

Implementation Status​

Acceptance Criteria​

US-018-002: Property Comparison & Benchmarking​

Implementation Status​

Acceptance Criteria​

US-018-003: Chain-Wide Guest Deduplication & Merge​

Implementation Status​

Acceptance Criteria​

US-018-004: Centralized Rate Management & Push​

Implementation Status​

Acceptance Criteria​

US-018-005: Consolidated Cross-Property P&L Report​

Implementation Status​

Acceptance Criteria​

US-018-006: Staff Transfer Between Properties​

Implementation Status​

Acceptance Criteria​

US-018-007: Chain-Level Loyalty Program​

Implementation Status​

Acceptance Criteria​

US-018-008: Property Alert & Notification Engine​

Implementation Status​

Acceptance Criteria​

US-018-009: Brand Standards Compliance Tracker​

Implementation Status​

Acceptance Criteria​

Business Objective

Audience

Scope

In Scope

Out of Scope

Current Implementation Status

Backend

Dashboard (02-hmp-web-dashboard)

Gap Analysis

User Stories

Dependencies

Acceptance Criteria (Epic Level)

KPIs / Success Metrics

Detailed User Stories

US-018-001: Chain Dashboard with Cross-Property KPIs

Implementation Status

Acceptance Criteria

US-018-002: Property Comparison & Benchmarking

Implementation Status

Acceptance Criteria

US-018-003: Chain-Wide Guest Deduplication & Merge

Implementation Status

Acceptance Criteria

US-018-004: Centralized Rate Management & Push

Implementation Status

Acceptance Criteria

US-018-005: Consolidated Cross-Property P&L Report

Implementation Status

Acceptance Criteria

US-018-006: Staff Transfer Between Properties

Implementation Status

Acceptance Criteria

US-018-007: Chain-Level Loyalty Program

Implementation Status

Acceptance Criteria

US-018-008: Property Alert & Notification Engine

Implementation Status

Acceptance Criteria

US-018-009: Brand Standards Compliance Tracker

Implementation Status

Acceptance Criteria