# Resort Comparison Tool - User Guide

Compare multiple resorts with automatic flight search, TripAdvisor ratings, and feature matching based on your preferences.

## 🚀 Quick Start

### Option 1: Interactive Mode
```powershell
.\compare-resorts.ps1
```
Paste your resort list when prompted.

### Option 2: Test Mode (Pre-loaded Data)
```powershell
.\compare-resorts-test.ps1
```
Uses the 14 resorts you provided for testing with departure date Jan 15, 2026.

---

## 📋 What You Get

### 1. **Comparison Grid**
- Resort rankings based on your preferences
- TripAdvisor ratings and review counts
- Price ranges ($$$ - $$$$$)
- Feature ratings (0-10 scale)

### 2. **Flight Information**
- Automatic flight links for each destination
- Skyscanner, Google Flights, and Air Canada links
- Estimated flight prices from Ottawa
- Departure date: January 15, 2026 (configurable)

### 3. **Feature Matching**
Rate these features 0-10:
- 🏖️ **Beach** - Direct beach access
- 🏊 **Pool** - Swimming pool quality
- ⛳ **Golf** - Golf courses nearby
- 💆 **Spa** - Spa & wellness facilities
- 🍽️ **Food** - Dining options
- 🎉 **Nightlife** - Entertainment
- 🛍️ **Shopping** - Shopping options
- 🏛️ **Culture** - Cultural attractions
- 🚵 **Outdoor** - Activities
- 👨‍👩‍👧‍👦 **Family** - Family-friendly

### 4. **TripAdvisor Ratings**
- Current ratings (out of 5.0)
- Number of reviews
- Integrated into match scoring

---

## 🏖️ Included Test Resorts

### Mexico - Riviera Maya & Tulum (CUN Airport)
1. **Bahia Principe Luxury Sian Ka'an** - 4.5/5 ⭐ (8,234 reviews)
2. **Catalonia Royal Tulum** - 4.5/5 ⭐ (6,421 reviews)
3. **Secrets Akumal Riviera Maya** - 4.5/5 ⭐ (9,127 reviews)
4. **UNICO 20°87° Hotel Riviera Maya** - 5.0/5 ⭐⭐⭐⭐⭐ (3,894 reviews)
5. **TRS Yucatán Hotel** - 4.5/5 ⭐ (5,621 reviews)
6. **Barcelo Maya Riviera** - 4.5/5 ⭐ (12,453 reviews)
7. **Valentin Imperial Riviera Maya** - 4.5/5 ⭐ (8,934 reviews)
8. **Grand Sirenis Riviera Maya** - 4.0/5 ⭐ (7,821 reviews)
9. **Dreams Tulum Resort & Spa** - 4.5/5 ⭐ (6,754 reviews)

### Dominican Republic - Punta Cana (PUJ Airport)
10. **Hyatt Zilara Cap Cana** - 5.0/5 ⭐⭐⭐⭐⭐ (9,821 reviews)
11. **Secrets Cap Cana** - 4.5/5 ⭐ (8,432 reviews)
12. **Dreams Onyx Resort & Spa** - 4.5/5 ⭐ (5,643 reviews)
13. **Royalton CHIC Punta Cana** - 4.5/5 ⭐ (7,234 reviews)
14. **Iberostar Grand Bávaro** - 4.5/5 ⭐ (6,821 reviews)

---

## 📊 Example Output

### Top 3 Resorts View
```
========================================
   🏆 TOP 3 RESORTS FOR YOU
========================================

🥇 #1: UNICO 20°87° Hotel Riviera Maya
    📍 Riviera Maya, Mexico [CUN]
    ⭐⭐⭐⭐⭐ 5.0/5.0 (3,894 reviews)
    💰 $$$$$ | ✈️  $500-$800
    🎯 Match Score: 942/1000
    Best Features:
      • pool: ██████████ 10/10
      • spa: ██████████ 10/10
      • food: ██████████ 10/10
    🔗 Flights: https://www.skyscanner.ca/...

🥈 #2: Secrets Akumal Riviera Maya
    📍 Akumal, Mexico [CUN]
    ⭐⭐⭐⭐⭐ 4.5/5.0 (9,127 reviews)
    💰 $$$$$ | ✈️  $500-$800
    🎯 Match Score: 938/1000
    ...

🥉 #3: Hyatt Zilara Cap Cana
    📍 Cap Cana, Dominican Republic [PUJ]
    ⭐⭐⭐⭐⭐ 5.0/5.0 (9,821 reviews)
    💰 $$$$$ | ✈️  $600-$900
    🎯 Match Score: 932/1000
    ...
```

### Comparison Table
```
# Resort                    Dest          Airport Rating Price Beach Pool Spa Food Score
- ------                    ----          ------- ------ ----- ----- ---- --- ---- -----
1 UNICO 20°87° Hotel        Riviera Maya  CUN     5.0/5  $$$$$ 9     10   10  10   942
2 Secrets Akumal            Akumal        CUN     4.5/5  $$$$$ 10    9    9   9    938
3 Hyatt Zilara Cap Cana     Cap Cana      PUJ     5.0/5  $$$$$ 10    9    9   9    932
4 Secrets Cap Cana          Cap Cana      PUJ     4.5/5  $$$$$ 10    9    9   9    925
...
```

---

## 🎯 How Feature Matching Works

Your preferences are matched against each resort's profile:

### Example: If you rate Beach:10, Pool:8, Spa:8

**UNICO 20°87° Scores High:**
- Beach: 9/10 × Your rating (10) = 90 points
- Pool: 10/10 × Your rating (8) = 80 points
- Spa: 10/10 × Your rating (8) = 80 points
- **Strong match!**

**Grand Sirenis Scores Lower:**
- Beach: 8/10 × Your rating (10) = 80 points
- Pool: 8/10 × Your rating (8) = 64 points
- Spa: 7/10 × Your rating (8) = 56 points
- **Weaker match**

The system combines:
1. Feature matching score
2. TripAdvisor rating bonus
3. Normalized to 0-1000 scale

---

## ✈️ Flight Information

### Automatic Flight Links Generated For:

**From:** Ottawa (YOW)  
**To:** CUN (Cancun) or PUJ (Punta Cana)  
**Date:** January 15, 2026  
**Return:** January 22, 2026 (7 nights)

Each resort gets:
- **Skyscanner Link** - Direct search with dates
- **Google Flights Link** - Google's flight search
- **Air Canada Link** - Book directly with AC

### Estimated Flight Prices
- **Ottawa → Cancun (CUN):** $500-$800 CAD
- **Ottawa → Punta Cana (PUJ):** $600-$900 CAD

*Prices are estimates. Click links for current prices.*

---

## 📤 Export Features

### CSV Export
Includes all data:
- Rankings and match scores
- All 10 feature ratings
- TripAdvisor data
- Flight links (clickable in Excel)
- Price ranges

**Filename Format:**
```
resort_comparison_test_2025-10-29_143052.csv
```

### What's in the CSV:
```
Rank,Resort,Destination,Country,Airport,DepartureDate,ReturnDate,
TripAdvisorRating,TripAdvisorReviews,PriceRange,AllInclusive,
MatchScore,Beach,Pool,Golf,Spa,Food,Nightlife,Shopping,Culture,
Outdoor,Family,EstFlightPrice,SkyscannerLink,GoogleFlightsLink,
AirCanadaLink
```

---

## 🔧 Customization

### Change Departure Date
In `compare-resorts-test.ps1`, modify:
```powershell
$departureDate = "2026-01-15"  # Change to your date
```

### Change Trip Length
```powershell
$tripLength = 7  # Change to 5, 10, 14, etc.
```

### Change Origin City
```powershell
$origin = "YOW"  # Change to YYZ, YUL, YVR, etc.
```

### Add Your Own Resorts
Edit `lib/resorts.ts` and add to `RESORT_DATABASE`:
```typescript
"your resort name": {
  name: "Your Resort Name",
  destination: "City",
  country: "Country",
  airportCode: "XXX",
  features: {
    beach: 9, pool: 8, golf: 7, spa: 8,
    food: 9, nightlife: 7, shopping: 6,
    culture: 5, outdoor: 8, family: 9
  },
  tripAdvisorRating: 4.5,
  tripAdvisorReviews: 5000,
  priceRange: "$$$$",
  allInclusive: true
}
```

---

## 💡 Tips for Best Results

### 1. Be Honest with Preferences
- Rate only what matters to you
- Don't rate everything 10/10
- Focus on 3-5 key features

### 2. Check Multiple Sources
- Open Skyscanner for best flight prices
- Use Google Flights for flexible dates
- Check Air Canada for direct flights

### 3. Read Recent Reviews
- TripAdvisor ratings are included
- Click through to read recent reviews
- Check for seasonal differences

### 4. Consider Total Cost
- Resort price range ($$$ - $$$$$)
- Flight estimates provided
- All-inclusive = more value

### 5. Compare Similar Resorts
- Group Mexico resorts together
- Compare DR resorts separately
- Different airports = different flight prices

---

## 📱 Sample Session

```powershell
PS> .\compare-resorts-test.ps1

========================================
   Resort Comparison Tool - TEST MODE
========================================

Testing with 14 pre-loaded resorts:
  • Bahia Principe Luxury Sian Ka'an
  • Catalonia Royal Tulum
  ...

Travel Details (pre-configured):
  From: YOW (Ottawa)
  Departure: 2026-01-15
  Trip Length: 7 nights

Rate your feature preferences (0-10):
Press Enter to use default values

Beach importance (0-10, default: 10): 10
Pool importance (0-10, default: 8): 9
Golf importance (0-10, default: 5): 3
Spa importance (0-10, default: 8): 9
Food importance (0-10, default: 9): 10
Nightlife importance (0-10, default: 7): 6

Your preferences:
  beach: ██████████ 10/10
  pool: █████████ 9/10
  spa: █████████ 9/10
  food: ██████████ 10/10
  golf: ███ 3/10
  nightlife: ██████ 6/10

Analyzing resorts and searching flights...

========================================
   ✓ Analysis Complete!
========================================

[Results displayed...]

Export to CSV? (y/n): y
✓ Exported to resort_comparison_test_2025-10-29_143052.csv

Open flights for #1 resort? (y/n): y
Opening flights for UNICO 20°87° Hotel Riviera Maya...

🎉 Comparison complete! Happy vacation planning! 🏖️✈️
```

---

## 🆘 Troubleshooting

**"Unable to connect to the remote server"**
- Make sure dev server is running: `npm run dev`
- Check it's on port 4000
- Wait 5 seconds after starting server

**"Resort not found in database"**
- Check spelling of resort name
- Resort may not be in database yet
- Add it manually to `lib/resorts.ts`

**Script won't execute**
```powershell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
```

**Need to add more resorts**
- Edit `lib/resorts.ts`
- Add to `RESORT_DATABASE` object
- Restart server: `npm run dev`

---

## 📈 Understanding Match Scores

**900-1000:** Perfect match - Resort excels in your priorities  
**800-899:** Excellent match - Strong alignment with preferences  
**700-799:** Good match - Meets most requirements  
**600-699:** Fair match - Some alignment  
**Below 600:** Poor match - Consider other options

**Score Components:**
- Feature matching (70%)
- TripAdvisor rating (30%)

---

## 🎉 Next Steps

1. **Run the test** - `.\compare-resorts-test.ps1`
2. **Review top 3** - Check flight prices
3. **Export CSV** - Compare in Excel
4. **Book flights** - Click Skyscanner links
5. **Book resort** - Search resort name + "all-inclusive deals"

---

Happy resort hunting! 🏖️✈️🌴