# Location Validation Implementation

## Overview
Ash Transfer has specific service area restrictions to ensure quality service delivery. The location validation system enforces these business rules across both frontend and backend.

## Business Rules

### ✅ ACCEPTED Bookings
1. **Airport Transfers**
   - Pickup in service area → Any UK airport
   - Any UK airport → Dropoff in service area
   - Examples:
     * Manchester M1 → Heathrow Airport ✅
     * Manchester Airport → Liverpool L1 ✅
     * Chester CH1 → Gatwick Airport ✅

2. **Local Transfers**
   - Both pickup AND dropoff within service area
   - Examples:
     * Manchester → Liverpool ✅
     * Chester → Bolton ✅
     * Salford → Stockport ✅

3. **Service Area to/from Other Locations**
   - One location in service area, other location outside
   - Examples:
     * Manchester → Birmingham ✅
     * Leeds → Liverpool ✅

### ❌ REJECTED Bookings
- **Both locations outside service area AND no airport involved**
- Examples:
  * London → Birmingham ❌
  * Leeds → Sheffield ❌
  * Edinburgh → Glasgow ❌

## Service Areas

### Greater Manchester
**Postcodes:** M1-M50, M60, M90, WN, BL, OL, SK (partial), WA (partial)
**Towns/Cities:**
- Manchester, Salford, Stockport, Bolton, Bury, Oldham
- Rochdale, Wigan, Trafford, Altrincham, Sale, Urmston
- Stretford, Ashton-under-Lyne, Stalybridge, Hyde, Denton
- Leigh, Eccles, Swinton, Radcliffe, Prestwich, Whitefield
- Middleton, Failsworth, Chadderton, Shaw, Heywood, Ramsbottom

### Chester Area
**Postcodes:** CH1-CH4, CH65-CH66
**Towns:**
- Chester, Ellesmere Port, Neston, Frodsham

### Liverpool & Merseyside
**Postcodes:** L1-L40, L70, L75, L80
**Towns/Cities:**
- Liverpool, Bootle, Crosby, Formby, Maghull, Kirkby
- Huyton, Prescot, Knowsley, Halewood, Speke, Garston
- Allerton, Childwall, Woolton, Wavertree, Mossley Hill
- West Derby, Anfield, Walton, Aintree, Fazakerley
- Birkenhead, Wallasey, Bebington, Heswall, Wirral

### All UK Airports
- Manchester (MAN), Liverpool (LJL), Heathrow (LHR), Gatwick (LGW)
- Stansted (STN), Luton (LTN), City (LCY), Birmingham (BHX)
- East Midlands (EMA), Leeds Bradford (LBA), Newcastle (NCL)
- Edinburgh (EDI), Glasgow (GLA), Aberdeen (ABZ), Belfast (BFS/BHD)
- Bristol (BRS), Cardiff (CWR), Southampton (SOU), Exeter (EXT)
- And all other UK airports

## Implementation Files

### Backend
**File:** `/server/utils/locationValidator.js`
- `validateBookingLocations(pickup, dropoff)` - Main validation function
- `isUKAirport(location)` - Check if location is a UK airport
- `isInServiceArea(location)` - Check if location is in service area
- `getValidationMessage(result)` - User-friendly error messages

**Integration:** `/server/routes/bookings.js`
- Validates locations before creating bookings
- Returns 400 error with detailed message if invalid

### Frontend
**File:** `/public/js/locationValidator.js`
- Client-side validation matching backend rules
- Real-time feedback in quotation form

**Integration:** `/public/quotation.html`
- Validates on form submission
- Shows user-friendly error messages
- Prevents invalid booking attempts

## Testing

### Run Tests
```bash
cd /home/user/ashtransfer-fullstack
node server/utils/locationValidator.test.js
```

### Test Coverage
✅ 12/12 tests passing
- 8 valid booking scenarios
- 4 invalid booking scenarios
- Unit tests for airport and service area detection

### Example Test Cases
```javascript
// Valid
validateBookingLocations('Manchester M1', 'Heathrow Airport')
// → { valid: true, message: 'Valid airport transfer' }

validateBookingLocations('Chester CH1', 'Liverpool L3')
// → { valid: true, message: 'Valid local transfer' }

// Invalid
validateBookingLocations('London SW1A', 'Birmingham B1')
// → { valid: false, message: 'Sorry, we only accept...' }
```

## User Experience

### Validation Messages
When a booking is rejected, users see:

```
⚠️ Sorry, we only accept bookings where the pickup or dropoff 
is in the Greater Manchester, Chester, or Liverpool area.

✅ However, we provide transfers to/from ANY UK airport.

📍 Service Areas:
   • Greater Manchester (all areas)
   • Chester and surrounding areas
   • Liverpool and Merseyside
   • Any UK airport

📞 Need help? Call +44 7860 261578
```

### Frontend Validation
- Validates immediately on form submission
- Shows warning message in yellow banner
- Prevents API call for invalid bookings
- Clears message when user changes inputs

### Backend Validation
- Double-checks all booking requests
- Returns 400 status with error details
- Prevents invalid bookings from being stored
- Provides consistent error messages

## API Response Examples

### Successful Booking
```json
{
  "message": "Booking created successfully",
  "booking": {
    "booking_reference": "ASH123456ABCD",
    "pickup_location": "Manchester M1 1AA",
    "dropoff_location": "Heathrow Airport",
    "total_price": 250.00,
    ...
  }
}
```

### Location Validation Error
```json
{
  "error": "Location not in service area",
  "message": "Sorry, we only accept bookings where the pickup or dropoff is in the Greater Manchester, Chester, or Liverpool area. However, we do provide transfers to/from any UK airport.\n\nService Areas:\n• Greater Manchester (all areas)\n• Chester and surrounding areas\n• Liverpool and Merseyside\n• Any UK airport for collection or delivery\n\nContact us: +44 7860 261578",
  "details": {
    "pickup": false,
    "dropoff": false,
    "airportInvolved": false,
    "suggestion": "Please ensure at least one location is in Manchester, Chester, Liverpool, or any UK airport."
  }
}
```

## Maintenance

### Adding New Service Areas
Edit `locationValidator.js` (both frontend and backend):

```javascript
// Add new postcode
SERVICE_AREA_POSTCODES.push('NEW_POSTCODE');

// Add new town/city
SERVICE_AREA_TOWNS.push('new town name');
```

### Adding New Airports
```javascript
UK_AIRPORTS.push('new airport name', 'NAP', 'new airport code');
```

### Testing Changes
Always run the test suite after modifications:
```bash
node server/utils/locationValidator.test.js
```

## Deployment Checklist
- [x] Backend validator implemented
- [x] Frontend validator implemented
- [x] Backend integration (bookings.js)
- [x] Frontend integration (quotation.html)
- [x] Test suite created and passing
- [x] Documentation complete
- [ ] Deploy and monitor real-world usage
- [ ] Collect user feedback on edge cases
- [ ] Refine service area boundaries if needed

## Support

For questions or issues:
- **Phone:** +44 7860 261578
- **Email:** info@ashtransfer.com
- **WhatsApp:** +44 7860 261578

---

**Last Updated:** 2026-01-29
**Version:** 1.0
**Status:** Production Ready ✅
