Add EV charging discovery feature (disabled by flag)
- Create EVChargingService using MapKit POI search for EV chargers - Add ItineraryBuilder.enrichWithEVChargers() for post-planning enrichment - Update TravelSection in TripDetailView with expandable charger list - Add FeatureFlags.enableEVCharging toggle (default: false) - Include EVChargingFeature.md documenting API overhead 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Trey t
142
SportsTime/Core/EVChargingFeature.md
Normal file
142
SportsTime/Core/EVChargingFeature.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# EV Charging Feature
|
||||
|
||||
## Overview
|
||||
|
||||
When `FeatureFlags.enableEVCharging = true`, the app discovers EV charging stations along planned trip routes using Apple's MapKit APIs.
|
||||
|
||||
## Feature Flag
|
||||
|
||||
```swift
|
||||
// SportsTime/Core/FeatureFlags.swift
|
||||
enum FeatureFlags {
|
||||
static let enableEVCharging = false // Set to true to enable
|
||||
}
|
||||
```
|
||||
|
||||
## API Calls
|
||||
|
||||
### 1. MKDirections (Route Calculation)
|
||||
|
||||
**Purpose:** Get actual driving route polylines between stops
|
||||
|
||||
**When called:** After trip planning completes, for each travel segment
|
||||
|
||||
**Call pattern:**
|
||||
- 1 call per travel segment (city-to-city)
|
||||
- A 5-city trip = 4 MKDirections calls
|
||||
|
||||
**Response includes:**
|
||||
- Route polyline (used for EV charger search)
|
||||
- Actual driving distance (replaces Haversine estimate)
|
||||
- Expected travel time
|
||||
|
||||
### 2. MKLocalPointsOfInterestRequest (EV Charger Search)
|
||||
|
||||
**Purpose:** Find EV charging stations near sample points along the route
|
||||
|
||||
**When called:** For each sample point along the route polyline
|
||||
|
||||
**Call pattern:**
|
||||
- Routes are sampled every 100 miles
|
||||
- Each sample point triggers 1 POI search
|
||||
- 5-mile search radius around each point
|
||||
|
||||
**Example:**
|
||||
| Route Distance | Sample Points | POI Searches |
|
||||
|----------------|---------------|--------------|
|
||||
| 100 miles | 2 (start+end) | 2 calls |
|
||||
| 300 miles | 4 | 4 calls |
|
||||
| 500 miles | 6 | 6 calls |
|
||||
|
||||
## Total API Overhead
|
||||
|
||||
### Per Travel Segment
|
||||
```
|
||||
1 MKDirections call + (distance_miles / 100) MKLocalSearch calls
|
||||
```
|
||||
|
||||
### Example: Boston → New York → Philadelphia → Washington DC
|
||||
|
||||
| Segment | Distance | MKDirections | POI Searches | Total |
|
||||
|---------|----------|--------------|--------------|-------|
|
||||
| BOS→NYC | 215 mi | 1 | 3 | 4 |
|
||||
| NYC→PHL | 95 mi | 1 | 2 | 3 |
|
||||
| PHL→DC | 140 mi | 1 | 2 | 3 |
|
||||
| **Total** | | **3** | **7** | **10 calls** |
|
||||
|
||||
## Performance Impact
|
||||
|
||||
### Latency Added to Trip Planning
|
||||
|
||||
| Component | Time per Call | Notes |
|
||||
|-----------|---------------|-------|
|
||||
| MKDirections | 200-500ms | Network round-trip |
|
||||
| MKLocalSearch (POI) | 100-300ms | Per sample point |
|
||||
|
||||
**Typical overhead:** 2-5 seconds added to trip planning
|
||||
|
||||
### Parallel Processing
|
||||
|
||||
- All travel segments are enriched in parallel (using Swift TaskGroup)
|
||||
- POI searches within a segment are sequential (to avoid rate limiting)
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
### Apple MapKit Limits
|
||||
|
||||
- MapKit has daily quotas based on your Apple Developer account
|
||||
- Free tier: ~25,000 service requests/day
|
||||
- Paid tier: Higher limits available
|
||||
|
||||
### Our Mitigations
|
||||
|
||||
1. **Feature is opt-in** - Only runs when user enables "EV Charging Needed"
|
||||
2. **Reasonable sampling** - 100-mile intervals, not every mile
|
||||
3. **Deduplication** - Chargers appearing in multiple searches are deduplicated
|
||||
4. **Fail gracefully** - If POI search fails, trip planning continues without chargers
|
||||
|
||||
## Data Flow
|
||||
|
||||
```
|
||||
User enables "EV Charging Needed" toggle
|
||||
↓
|
||||
Trip planning runs (sync, Haversine estimates)
|
||||
↓
|
||||
ItineraryBuilder.enrichWithEVChargers() called
|
||||
↓
|
||||
For each travel segment (in parallel):
|
||||
├── MKDirections.calculate() → Get polyline
|
||||
└── EVChargingService.findChargersAlongRoute()
|
||||
├── Sample polyline every 100 miles
|
||||
├── MKLocalPointsOfInterestRequest per sample
|
||||
├── Filter to .evCharger category
|
||||
└── Deduplicate results
|
||||
↓
|
||||
TravelSegment.evChargingStops populated
|
||||
↓
|
||||
TripDetailView shows expandable charger list
|
||||
```
|
||||
|
||||
## Files Involved
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `Core/FeatureFlags.swift` | Feature toggle |
|
||||
| `Core/Services/EVChargingService.swift` | POI search logic |
|
||||
| `Planning/Engine/ItineraryBuilder.swift` | Enrichment orchestration |
|
||||
| `Features/Trip/ViewModels/TripCreationViewModel.swift` | Triggers enrichment |
|
||||
| `Features/Trip/Views/TripDetailView.swift` | Displays chargers |
|
||||
| `Core/Models/Domain/TravelSegment.swift` | EVChargingStop model |
|
||||
|
||||
## Testing Notes
|
||||
|
||||
1. **Simulator limitations** - MapKit POI results may be limited in simulator
|
||||
2. **Test on device** - Real EV charger data requires physical device
|
||||
3. **Monitor console** - Look for `[ItineraryBuilder]` log messages showing charger counts
|
||||
|
||||
## Future Improvements
|
||||
|
||||
- Cache EV charger results to reduce API calls on re-planning
|
||||
- Allow configurable sample interval (50mi for shorter range EVs)
|
||||
- Show chargers on the map view
|
||||
- Filter by charger network (Tesla, Electrify America, etc.)
|
||||
Reference in New Issue
Block a user