✨ feat(offline): implement complete offline mode with routing fallback hierarchy

[MasuRii]

📝 Summary

This PR implements comprehensive offline mode for PH Fare Calculator, enabling fare calculations even without internet connectivity. The feature includes a 4-level routing fallback hierarchy, automatic map tile caching, geocoding cache with 7-day expiration, and accuracy indicators showing calculation precision.

✨ Changes

🆕 New Services (4)

Service	Purpose	Key Features
OfflineModeService	Global state management	Toggle control, connectivity monitoring, user preferences
RoutingRepository	Hierarchical routing fallback	OSRM → Cache → Graph → Haversine fallbacks
RouteCacheService	24-hour route caching	LRU eviction, JSON persistence
GeocodingCacheService	7-day geocoding cache	Forward/reverse geocoding with TTL

🆕 New Models (1)

Model	Purpose
AccuracyLevel	Enum with Precise (Green), Estimated (Yellow), Approximate (Orange)

🔧 Modified Services

• HybridEngine: Integrated offline mode toggle
• ConnectivityService: Enhanced monitoring with state callbacks
• OSRM RoutingService: Cache integration for online routes
• HaversineRoutingService: Fallback routing capabilities

🎨 New UI Components

• Offline mode toggle in main screen header
• Offline mode toggle in settings screen
• Accuracy level badges on fare results
• Route source indicators
• Cross-region warning banner
• Offline status banner

📁 Files Changed

Total: 53 files

• 15 new files (services, models, widgets, tests)
• 31 modified files (core, presentation, services)
• 2 deleted files (test artifacts)

Lines Changed: +4,662 / -496

🧪 Testing

Test Suite Results

Test Type	Count	Status
Unit tests	34	✅ Pass (OfflineModeService)
Integration tests	3	✅ Pass (end-to-end workflows)
Performance tests	3	✅ Pass (cache operations)
Widget tests	7	✅ Pass (UI components)
Total	371	100% Pass Rate

New Test Coverage

• offline_mode_service_test.dart: 34 tests
• offline_workflow_test.dart: 3 integration tests
• offline_performance_test.dart: 3 performance tests
• offline_screens_test.dart: 7 widget tests

Regression Tests Added

• repro_accuracy_consistency_test.dart: Accuracy level consistency
• repro_accuracy_sort_ui_test.dart: Sort option compatibility
• repro_connectivity_persistence.dart: Offline toggle persistence

🔧 Technical Highlights

Routing Fallback Hierarchy

┌─────────────────────────────────────────────┐
│  Level 1: OSRM (Online) → Precise (Green)  │
│  ↓ If unavailable                           │
│  Level 2: Cache (24h) → Estimated (Yellow) │
│  ↓ If unavailable                           │
│  Level 3: Train/Ferry Graph → Estimated    │
│  ↓ If unavailable                           │
│  Level 4: Haversine → Approximate (Orange) │
└─────────────────────────────────────────────┘

Auto-Caching Strategy

• Map Tiles: 5,000 tile limit with LRU eviction
• Routes: 24-hour expiration
• Geocoding: 7-day expiration
• Trigger: Automatic when browsing online
• Opt-in: Users enable to start caching

Accuracy Level System

Level	Color	Source	Use Case
Precise	🟢 Green	OSRM (online)	Full routing with road data
Estimated	🟡 Yellow	Cache/Graph	Cached routes or train/ferry networks
Approximate	🟠 Orange	Haversine	Straight-line distance fallback

⚠️ Breaking Changes

None - All changes are backward compatible.

Migration Strategy

• Existing users: Offline mode defaults to OFF (opt-out)
• New users: Offline mode defaults to ON (opt-in)
• No manual migration required
• All existing fare calculation behavior preserved

🔗 Related Issues

• Closes: ✨ Theme System Overhaul with Light/Dark/System toggle and Theme-Aware Map Tiles (v2.1.0) #6 (Offline mode functionality)
• Related: feat(ui): Complete UI/UX Overhaul with Material 3 Design #4 (Route caching)
• Related: 🐛 Fix offline map download issues and add UX improvements #5 (Geocoding offline support)

📋 Checklist

• Code compiles and builds successfully
• All tests pass (371/371, 100%)
• Documentation updated (README, CHANGELOG)
• No breaking changes
• Performance tested (cache benchmarks added)
• Edge cases handled (13 scenarios documented)
• Accessibility features implemented (semantic labels)
• Migration strategy defined (opt-out for existing users)

📚 Documentation

User-Facing

• README.md: Offline mode section with usage guide
• CHANGELOG.md: v2.3.0 release notes

Technical

• Architecture Decision Records: 3 (state management, routing fallback, auto-caching)
• Component diagrams: 8 Mermaid diagrams
• Edge case analysis: 13 scenarios documented

🛠️ Verification Steps

1. Build Verification

   flutter build apk --release

2. Test Execution

   flutter test --coverage
   # Expected: 371/371 passing

3. Manual Testing

   • Toggle offline mode in main screen
   • Enable offline mode in settings
   • Verify fare calculations work without internet
   • Check accuracy indicators on results
   • Test cross-region route warnings

📦 Version Information

• Version: 2.3.0+1
• Commit: 74f8aef
• Branch: feature/offline-mode → main