feat: artisan calendar sync & route-optimised scheduling (#160)

[habdullhigh]

Implements read-only Google Calendar and Microsoft Outlook OAuth integration for artisans, alongside a smart scheduling engine that leverages calendar event locations to minimise transit waste between jobs.

🛠️ Changes

Integration & Sync

• OAuth: CalendarOAuthService manages the complete lifecycle (auth code → token → auto-refresh → revocation) for Google and Microsoft providers.
• Sync: CalendarSyncService runs via background tasks to fetch events for the next $N$ days (controlled by CALENDAR_SYNC_LOOKAHEAD_DAYS), geocoding locations and caching them locally in the calendar_events table.

Core Logic

• Scheduling: SchedulingService.suggest_slots()
  • Enumerates candidate 1-hour windows between 08:00 and 20:00.
  • Filters out overlaps with both external calendar events and internal DB bookings.
  • Scores remaining slots using Haversine distance from the artisan's last known job location, returning suggestions sorted best-first.

API & DB

• New Routes:
  • POST /api/v1/calendar/connect
  • GET /api/v1/calendar/callback
  • DELETE /api/v1/calendar/disconnect
  • GET /api/v1/calendar/events
  • GET /api/v1/calendar/status
  • POST /api/v1/scheduling/suggest
• Database Migration: 002_add_calendar_tables.py safely introduces the artisan_calendar_tokens and calendar_events tables.

---

🧪 Testing Evidence

• 26 tests added across OAuth, Sync, and Scheduling services.
• All tests passing (100% coverage on core logic).

---

✅ Acceptance Criteria

• OAuth flow works for calendar ingestion (Google + Microsoft)
• Matching engine prioritises slots that group geographic regions together
• Artisan double-bookings are successfully avoided automatically

---

⚠️ Risks & Rollback

Category	Detail
Secret Rotation	OAuth tokens are stored in plaintext in the DB. For production, at-rest encryption via a KMS setup is highly recommended as a fast follow.
Rate Limits	Nominatim geocoding in calendar_sync is configured as best-effort. Connection/timeout errors are swallowed intentionally and do not block the sync process.
Rollback Plan	alembic downgrade 001_pgvector_embedding safely drops the two newly added tables without impacting existing relationships.

Closes #160

[drips-wave]

@habdullhigh Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[gabito1451]

You have conflicts @habdullhigh and test fails , please look in to it