TransitIQ — Master Plan

Son güncelleme: 2026-04-18 Kurucu: Enes Çatal Merkez: İstanbul, Türkiye Durum: Private beta, üretime hazırlık fazı

Bu doküman TransitIQ'nun hedefini, mimarisini, özellik envanterini ve roadmap'ini kapsar. Her sprint sonrası güncellenir; bir özellik "complete" olarak işaretlenmeden önce bu dokümanda checkbox'ı işaretlenmiş olmalı.

1. Vizyon ve Farklılaşma

1.1 Vizyon

Türkiye'nin şehirlerarası otobüs seyahati pazarında, yolcuya Obilet'ten daha iyi bir deneyim ve firmalara Enuygun'dan daha modern bir SaaS sunarak, sektörün dijital altyapı standardı olmak.

1.2 Rakip Analizi

Özellik	Obilet	Enuygun	Neredennereye	TransitIQ Hedef
Sefer arama	✓	✓	✓	✓ + aktarmalı öneriler
Canlı sefer takibi	✗	✗	✗	✓ (büyük farklılaştırıcı)
Real-time koltuk viewer count	✗	✗	✗	✓ (Booking.com FOMO)
Fiyat alarmı	✗	✗	✗	✓ (Hopper tarzı)
Fiyat geçmişi grafiği	✗	✗	✗	✓
Karbon ayak izi	✗	✗	✗	✓ (Z kuşağı için)
Dijital cüzdan	✗	Kısmen	✗	✓
Referans programı	✗	✗	✗	✓ (50₺/50₺)
Rozet / gamification	✗	✗	✗	✓
Aktarmalı seyahat	✗	Manuel	✗	✓ (otomatik öneri)
Grup koltuk eşleştirme	Kısmen	Kısmen	✗	✓ (tek tık 2+li)
AI chatbot asistanı	✗	✗	✗	✓
Şoför GPS push	✗	✗	✗	✓
QR check-in (şoför)	Kısmen	✗	✗	✓ (native BarcodeDetector)
Yolcu manifest + boarding	Kısmen	✗	✗	✓
PWA + offline bilet	✗	✗	✗	Planned (Faz 3)
Apple/Google Wallet pass	✗	✗	✗	Planned (Faz 3)
Push notifications	Kısmen	✗	✗	Planned (Faz 3)
Multi-tenant SaaS (firma paneli)	✗	✗	✗	✓ (B2B gelir modeli)
Denetim logu (audit trail)	✗	✗	✗	✓ (kurumsal satış için şart)
Dinamik fiyat kuralları	✗	✗	✗	Planned
KVKK self-servis veri silme	Kısmen	Kısmen	Kısmen	✓ (ürün içinde)

1.3 Differentiation Pitch (3 cümle)

TransitIQ, yolculara otobüsün nerede olduğunu haritada canlı gösteren, fiyat düşünce otomatik haber veren, aktarmalı rotalarda kurtaran tek Türk platform. Otobüs firmalarına ise SOC-2 hazırlıklı altyapı, denetim logu, multi-tenant yönetim paneli ve gerçek zamanlı operasyon araçları sunar. Obilet rezervasyon servisidir — TransitIQ ulaşım zekası platformudur.

2. Kullanıcı Personaları

2.1 Yolcu (B2C) — `PASSENGER`

Mehmet, 34, Bursa'dan İstanbul'a düzenli iş seyahati yapan satış müdürü.
Hızlı, güvenli ödeme ister. Biletini WhatsApp'tan arkadaşıyla paylaşır. Otobüs geç kalırsa haber almak ister.
Ne bekler: 60 sn içinde arama→ödeme, biletini telefonda açabilme, iptal/iade stres olmasın.

2.2 Firma Admin (B2B) — `COMPANY_ADMIN`

Ayşe, 45, "Kent Seyahat" otobüs firması operasyon müdürü.
Filosunu, şoförlerini, seferleri yönetir. Günlük ciroyu görmek, iptalleri takip etmek ister. Hangi şoförün hangi sefere atandığını bilmek, muayene/sigorta tarihleri yaklaşınca hatırlatılmak ister.
Ne bekler: Dashboard → tek ekranda operasyon. Mobil de çalışsın. Denetim için log ister.

2.3 Şoför — `DRIVER`

Kamil, 52, 25 yıllık profesyonel şoför.
Teknoloji düşmanı değil ama fazla buton görmek istemiyor. Bugünün seferi belli olsun, yolcularını görebilsin, QR ile çabuk check-in yapsın.
Ne bekler: Telefonda tek dokunuşla sefer başlat, yolcu listesi göreyim, sıkıntı olursa admin'e ulaşayım.

2.4 Operatör (gelecek) — `OPERATOR`

Firma admin'in kısıtlı yetkili versiyonu. Bilet satış/iptal yapar, finansa dokunmaz.

2.5 Süper Admin — `SUPER_ADMIN`

Platform sahibi (Enes). Tüm tenant'ları yönetir. Yeni firma onaylar, global durumu izler.

3. Özellik Envanteri

Her özellik için: ✅ tamamlandı · 🟡 kısmen · ⏳ planlı · ❌ henüz yok

3.1 Yolcu Tarafı

✅ Sefer arama (şehir, tarih)
✅ Rota bazlı public sayfa (/rotalar)
✅ Koltuk seçimi (interaktif harita, layout-aware)
✅ Real-time koltuk — WebSocket ile viewer count, başka kullanıcının hover ettiği koltuk göstergesi
✅ Koltuk kilitleme (10 dk)
✅ Grup koltuk önerisi (2/3/4 kişi tek tık)
✅ Aktarmalı seyahat finder (10 hub üzerinden otomatik)
✅ Iyzico ile ödeme (3D Secure, kart saklamadan)
✅ PDF bilet + email (CID inline logo)
✅ PNR+email ile misafir bilet takibi (/bilet-takip)
✅ Müşteri hesabı (kayıt, giriş, profil)
✅ Biletlerim (gelecek/geçmiş/iptal)
✅ Bilet iptal + otomatik Iyzico iade (6 saat kuralı)
✅ Canlı sefer takibi — şoför GPS'i ile harita üzerinde otobüs konumu
✅ WhatsApp bilet paylaşımı (her bilette buton)
✅ AI chatbot (12+ intent, aksiyon butonlu)
✅ Dijital cüzdan (kredi bakiyesi + işlem geçmişi)
✅ Referans kodu sistemi (50₺+50₺ bonus, otomatik URL param)
✅ Fiyat alarmları (email/SMS seçeneği, CRUD)
✅ Fiyat geçmişi grafiği (30 gün, verdict: iyi/ortalama/yüksek)
✅ Karbon ayak izi karşılaştırma (otobüs vs araba/uçak/tren)
✅ Rozet sistemi (8 rozet, otomatik evaluation)
✅ Landing: popüler rotalar (foto zeminli), ucuz seferler, "Türkiye'yi Keşfet" editorial, canlı metrikler
✅ Hero carousel (18 Türk landmark fotoğrafı)
✅ Hesap sayfası sol navigasyon (biletler, cüzdan, alarm, rozet, davet, profil)
✅ Cross-tab session sync
✅ Bekleme listesi (sefer dolu → boşalınca ilk 5 kişiye e-posta, 24h re-notify cooldown)
✅ TC kimlik + telefon auto-format (centralized lib/formatters.ts)
✅ KVKK self-servis (/hesap/kvkk — export/delete/correct/restrict)
✅ 2FA kurulumu (/hesap/guvenlik — TOTP, QR, 10 yedek kod)
✅ Session tracking (aktif cihazlar, logout all)
✅ No-show bildirimi (sefer COMPLETED sonrası boardingStatus=PENDING yolcuya e-posta)
⏳ PWA + installable + offline bilet
⏳ Push notifications (sefer hatırlatma)
⏳ Apple Wallet / Google Wallet bilet pass
⏳ Fiyat geçmişi grafiğinde günlük trend çizgisi
⏳ Koltuk tercihi profilde (pencere/koridor)
⏳ Erişilebilirlik notu (tekerlekli sandalye, refakatçi)
⏳ Bilet devretme (başkasına transfer)
⏳ Hediye kartı / bilet hediye etme
❌ Dark mode için foto carousel optimizasyonu (şu an parlak)
❌ Multi-language (EN/AR/DE — turist pazarı için)

3.2 Şoför Tarafı

✅ Rol tabanlı login (/login → role göre yönlendirme)
✅ Günün + yaklaşan 7 günün seferleri (sıralı)
✅ Seferi Başlat / Tamamla (themed confirm dialog ile)
✅ Sefer ACTIVE iken otomatik GPS push (20sn, watchPosition)
✅ Hız göstergesi (m/s → km/h doğru dönüşüm, 2026-04-18 fix)
✅ Yolcu manifestosu (koltuk, ad, TC son 4, telefon, status)
✅ Check-in (QR tara VEYA elle PNR gir)
✅ No-show işaretleme (themed warning dialog ile)
✅ Boarding status reset (undo)
✅ Araç bilgisi (plaka, model)
✅ Otomatik sefer kapatma (cron her 10 dk → geçmiş PLANNED/ACTIVE → COMPLETED)

Production-critical (Kamil personası) — 2026-04-18 Driver Sprint'te bitti:

✅ SOS / Acil durum butonu — 5 kategori (kaza/sağlık/arıza/güvenlik/diğer), audit log kaydı + firma destek e-postasına kritik alert + tek tık arama
✅ Sefer öncesi araç kontrol formu — 13 maddelik checklist + km/yakıt ölçüsü + sorun varsa zorunlu not + eksik varsa admin'e otomatik e-posta (sigorta/hukuki belge)
✅ Post-trip özet raporu — sefer tamamlandığında firma admin'e otomatik e-posta: doluluk/masraf/no-show/SOS/pre-trip flag özeti
✅ Vardiya start/end tracking — Trip.driverStartedAt + driverCompletedAt alanları + canlı süre göstergesi banner'da
✅ Expense logging — 5 kategori (yakıt/otoyol/yemek/otopark/diğer), PENDING→APPROVED akışı, şoför kendi PENDING kaydını silebilir
✅ Font + touch target büyütüldü — manifest-modal'da yolcu adı text-sm→base, buton 8×8→12×12 (48px Material std.), telefon artık tel: link, status badge daha okunur
✅ Optimistic UI check-in — anında state değişir (backedStatus lokal set), backend hatası olursa geri alınır

Orta öncelik (sonraki iterasyon):

⏳ Şoför profil sayfası (kendi şifresini değiştirme)
⏳ Şoför istatistikleri (toplam sefer, doluluk ort, puan)
⏳ Rota sapma uyarısı (belirlenen rotadan çıktığında admin'e bildirim)
⏳ İkinci şoför vardiya devri
⏳ Offline mod göstergesi (tunnel/rural'da GPS push başarısız olduğunda kullanıcıya net bilgi)
⏳ Battery saver modu (60s interval opsiyonu)
⏳ Admin tarafında expense onay paneli (şu an backend hazır, UI gerek)
⏳ Admin tarafında pre-trip eksikleri dashboard'u

3.3 Firma Admin Tarafı

✅ Login (rol kontrolü ile)
✅ Genel bakış (stat kartları)
✅ Filo yönetimi (araç CRUD, soft delete)
✅ İstasyon yönetimi (CRUD)
✅ Rota yönetimi (CRUD, otomatik fiyat + mesafe)
✅ Sefer yönetimi (CRUD + şoför ataması)
✅ Sefer düzenleme (şoför/araç yeniden atama)
✅ Bilet yönetimi (liste, filtre, detay, iptal, iade)
✅ Şoför yönetimi (CRUD + şifre güncelleme)
✅ Denetim logu (tüm kritik mutasyonlar: kim, ne, ne zaman, before/after diff)
✅ Command palette (Cmd+K)
✅ Ciro dashboard (30 gün bar chart + bugün/hafta/ay/toplam gerçek veriler)
✅ Settlement dashboard (brut/komisyon/net, ödeme modu, status breakdown, CSV export)
✅ Şikayet yönetimi (kategori, öncelik, durum yönetimi)
✅ Yolcu yorumları (moderation, hide, tag'ler)
✅ Promosyon kodu yönetimi (CRUD + apply at checkout)
✅ CSV export (tüm paneller: araç/sefer/rota/istasyon/şoför/bilet/denetim/promo)
✅ CSV import (araç/istasyon/şoför toplu yükleme + şablon + hata raporu)
✅ Bulk işlem (toplu sil, toplu iptal — themed confirm dialog'lu)
✅ Firma branding (logo upload/resize/webp, brand color, yolcu görünür)
✅ API keys yönetimi (tiq_live_* prefix, SHA-256 hashed, scopes)
⏳ Doluluk analizi (rota bazında)
⏳ Tahminleme (ML ile doluluk/ciro öngörü)
⏳ Dinamik fiyat kuralları
⏳ Tekrarlayan sefer şablonu ("her Pazartesi 09:00")
⏳ OPERATOR rolü implementation (kısıtlı yetki)
⏳ Müşteri segmentasyonu (VIP, düzenli, risk)

3.4 Süper Admin (Platform)

✅ Tenant onboarding akışı (/firma-kayit 6 adımlı form + consent log)
✅ Tenant listesi / durumu (super-tenants panel: ACTIVE/SUSPENDED/PENDING, komisyon oranı)
✅ Onay kuyruğu (pending tenant'lar belge kontrolü + approve/reject)
✅ Global analytics (platform-overview: GMV, komisyon, büyüme trendi, top 10 leaderboard)
✅ Billing / komisyon (settlement + invoice, PDF + KDV + TR font)
✅ Platform-wide duyuru (announcement system, severity, audience, dismissible)
✅ Tenant impersonation (30dk JWT, audit log'lu, mor banner)
✅ User suspension + parola sıfırlama
✅ Risk scoring (cancel rate, refund fails, complaints)
✅ KVKK data requests (export JSON / delete anonymize)
✅ System health (DB, Resend, Iyzico, uploads, memory, 30s refresh)
✅ Platform settings (maintenance mode, komisyon, min/max fiyat, 2FA zorunluluk)
✅ Subscription plans (Başlangıç %10 / Pro %7 / Kurumsal %5)
✅ Email templates CRUD
✅ Feature flags (audience, rollout %, tenant-based)
✅ Incidents (status page feed, updates)
✅ Support tickets (guest + auth, conversation threads, internal notes)
✅ Cross-tenant şikayet listesi (super admin tüm firmaların şikayetlerini görür, 2026-04-18 fix)
✅ Cross-tenant audit log
✅ Cross-tenant global search (Cmd+K, 11 entity)
⏳ Weekly summary email super admin'e (scheduled report)
⏳ Chargeback / dispute management
⏳ Payout history log (EFT/havale işaretlenmeden öte audit trail)
⏳ Webhook delivery system (tenant'lara event push)

3.5 Site / İçerik

✅ Landing (hero, carousel, live ticker, popüler, keşfet, ucuz, features, B2B CTA)
✅ /rotalar (tüm rotalar, şehir bazında filtre)
✅ /fiyatlandirma (3 tier B2B + FAQ)
✅ /hakkimizda (dürüst, 1 kişilik ekip, 2026)
✅ /iletisim (form + WhatsApp +48 881 730 681)
✅ /sss (arama + 5 grup + 18 soru)
✅ /yardim (kategori kartları)
✅ /blog (yakında placeholder)
✅ /basin (boilerplate, logo download)
✅ /kariyer (açık pozisyon yok + gelecekteki roller)
✅ Yasal sayfalar: KVKK, Gizlilik, Şartlar, Çerez, İade Politikası
⏳ Her rota için SEO-dostu ayrı URL (/rotalar/istanbul-ankara)
⏳ Open Graph meta + schema.org JSON-LD
⏳ Sitemap.xml + robots.txt

4. Teknoloji Yığını

4.1 Frontend

Framework: Next.js 16 (app router, Turbopack)
UI: React 19, TypeScript, Tailwind CSS 4, framer-motion
Components: shadcn/ui + @base-ui/react
State: Zustand (booking store)
HTTP: axios + interceptor (auto 401 redirect)
Real-time: socket.io-client
Harita: Leaflet (CDN-loaded, OpenStreetMap tiles)
Smooth scroll: Lenis
Toasts: sonner
Icons: lucide-react
Dark mode: next-themes

4.2 Backend

Framework: NestJS
Dil: TypeScript
ORM: Prisma
DB: PostgreSQL (Neon, serverless, eu-central-1)
Auth: JWT (passport-jwt), bcrypt
Ödeme: Iyzico (PCI-DSS)
Email: Resend + @react-email/components
PDF: PDFKit + DejaVu fonts
WebSocket: @nestjs/websockets + socket.io
Zamanlayıcı: @nestjs/schedule (cron)
Rate limit: @nestjs/throttler
Validation: class-validator

4.3 Harici Servisler

✅ Iyzico (ödeme + iade)
✅ Resend (email)
✅ Wikipedia REST API (şehir fotoları, ücretsiz)
✅ OpenStreetMap (harita tiles, ücretsiz)
⏳ Netgsm / Iletimerkezi (SMS)
⏳ Google Places / OSM Overpass (otogar verisi)
⏳ Sentry (error tracking)
⏳ Plausible veya Posthog (analytics)
⏳ Cloudflare (CDN + WAF)
⏳ Uptime Robot (availability)

5. Güvenlik — OWASP Top 10 Checklist

A01 — Broken Access Control

✅ Her admin endpoint'inde @UseGuards(JwtAuthGuard)
✅ Her sorguda tenantId filtresi
✅ Frontend ProtectedRoute allowedRoles={[...]}
✅ Cross-tenant resource validation (trip create: route/vehicle/driver aynı tenant'tan mı)
✅ Driver-ops audit fix paketi (2026-04-18): deleteDocument tenantId scope (defense-in-depth), reportLostItem auth zorunlu + rate limit (5/saat), driverDocument ownership tenantId+userId double-check
⏳ IDOR testleri (BookingId ile başka tenant'ın bileti okunmamalı — scope var ama penetrasyon testi yapılmadı)
⏳ Şoför sadece kendi seferlerine lokasyon push edebilir — teyit edildi ✓

A02 — Cryptographic Failures

✅ bcrypt 10 rounds şifreler için
✅ JWT signed with JWT_SECRET
✅ Kart bilgileri sunucuda saklanmaz (Iyzico direct)
⏳ HTTPS enforce (prod deployment)
⏳ JWT_SECRET rotation planı
⏳ DB-level encryption at rest (Neon sağlıyor ama audit yapılmadı)

A03 — Injection

✅ Prisma → SQL injection bağışık (parametrized)
✅ DTO validation (class-validator)
⏳ NoSQL injection (yok, Postgres kullanılıyor)
⏳ XSS — React'te default escape var ama dangerouslySetInnerHTML audit yapılmadı

A04 — Insecure Design

✅ 10 dakikalık seat lock (race condition engeli)
✅ 6 saat iptal kuralı
✅ Audit log (denetim izi)
✅ Brute force login koruması — max 5 başarısız/15dk/IP (in-memory tracker)
✅ Spam-sensitive endpoint throttle (2026-04-18): SOS 3/5dk, lost-item 5/saat, driver-wallet 30/dk, payment/initialize 3/10sn
✅ Bot koruması — Cloudflare Turnstile (2026-04-18): 4 auth endpoint (login/register + customer-login/customer-register) + frontend widget. No-op fallback dev için. Free tier 1M/ay.
⏳ Rate limit genel polish — tüm endpoint'lerde değil (default seviyede)

A05 — Security Misconfiguration

✅ .env gitignore'da (.env, .env.local, .env.*.local; uploads/dist/log da kapsamlı ignore'da, public history filter-repo ile temizlendi 2026-04-18)
✅ Helmet.js — CSP prod'da aktif, dev'de devre dışı
⏳ Prod'da stack trace gizlenmeli
⏳ Debug mode off

A06 — Vulnerable Components

⏳ npm audit CI'de otomatik
⏳ Dependabot aktif değil

A07 — Identification & Authentication

✅ Güçlü şifre (min 8, bcrypt 12 rounds)
✅ JWT expiration (1 gün default)
✅ Şifre sıfırlama akışı (Resend + token)
✅ Email doğrulama kayıtta
✅ 2FA (TOTP) — admin için (Phase 3 mega sprint, otplib + QR + 10 backup code)
✅ Session revocation — UserSession model, SHA-256 hashed token, revoke one / revoke all (Phase 3 mega sprint)
✅ Brute-force koruması (5 deneme/15dk in-memory tracker)
✅ Google OAuth (passport-google-oauth20, auto user create/link)
✅ Refresh token akışı (2026-04-18) — access 15dk + refresh 30g, refresh token httpOnly secure cookie ('tiq_rt'), token rotation, /auth/refresh + /auth/logout endpoint'leri, axios interceptor 401 → refresh → retry
⏳ 2FA driver için (admin yapıldı, driver opsiyonel)
⏳ JWT'yi tamamen httpOnly cookie'ye taşı (access token şu an localStorage'da — büyük refactor, mobile flow ile aynı anda yapılacak)

A08 — Software & Data Integrity

✅ Prisma migrations versiyon kontrollü
⏳ SRI (subresource integrity) for CDN assets (Leaflet)

A09 — Logging & Monitoring

✅ Audit log (kritik mutasyonlar)
✅ Finansal audit genişletmesi (2026-04-18): SETTLEMENT_SETTLE, SETTLEMENT_BULK_SETTLE (super admin finansal aksiyonlar tenant-bazlı kaydediliyor), PAYMENT_SETTLEMENT_FAILED + PAYMENT_BOOKING_FAILED + PAYMENT_CALLBACK_ORPHAN (Iyzico callback hataları reconciliation için)
✅ Sentry error tracking (2026-04-18) — backend (NestJS) + frontend (Next.js) entegre. DSN yokken no-op. PII redaction beforeSend hook'unda. Throttle/Validation/Auth hataları gürültü olmasın diye ignoreErrors'ta.
⏳ Access log (kimin ne zaman giriş yaptığı — UserSession.lastActiveAt'te kısmi var, daha detaylı access log ek)
⏳ Suspicious activity detection (rate anomaly, başka geo'dan login, vs.)

A10 — SSRF

✅ Wikipedia/OSM fetch'leri User-Agent ile identified
⏳ Rate limit outbound HTTP çağrıları

KVKK Compliance

✅ KVKK aydınlatma metni sayfası
✅ Çerez politikası sayfası
✅ Kullanıcı kendi verisini indirme (JSON export — /hesap/kvkk EXPORT request, super admin queue ile 30 gün yasal süre)
✅ Kullanıcı kendi hesabını silme (DELETE/CORRECT/RESTRICT request flow, anonimizasyon: bilet maskelenir, ad "Silinmiş Kullanıcı")
✅ Consent management (Cookie Consent Banner — necessary/analytics/marketing 3 kategori, localStorage + ConsentLog DB)
✅ Terms versions + ConsentLog (versiyonlanmış kullanım şartları, IP+UA+timestamp ile her onay kaydı)
⏳ VERBİS resmi kayıt (KVKK Kurumu — şirket kurulunca, ücretsiz)
⏳ DPO veri işleme kayıt defteri (manuel doc, post-launch)

6. Veritabanı Şeması

6.1 Mevcut Modeller

Tenant (multi-tenant root)
User (PASSENGER/DRIVER/OPERATOR/COMPANY_ADMIN/SUPER_ADMIN + wallet, referral, badges)
Station (lat/lng, tenant-owned)
Vehicle (plate, capacity, layout, muayene/sigorta tarihleri)
Seat (vehicle-owned, status: AVAILABLE/LOCKED/BOOKED/BLOCKED)
Route (origin+destination+price+distance)
RouteStop (ara duraklar)
Trip (+GPS fields: currentLat/Lng/Speed/lastLocationAt)
Booking (+ refundStatus, boardingStatus, paymentTransactionId)
PendingPayment (Iyzico callback için)
AuditLog (denetim izi)
PriceAlert
WalletTransaction
PriceHistorySnapshot

6.2 Eklenecek Modeller

model MaintenanceRecord {
  id          String   @id @default(uuid())
  vehicleId   String
  type        String   // OIL_CHANGE, TIRE, INSPECTION, INSURANCE, CLEANING, OTHER
  description String?
  cost        Decimal?
  odometerAt  Int?
  performedAt DateTime
  performedBy String?  // mechanic name
  nextDueAt   DateTime?
  nextDueKm   Int?
  attachmentUrl String?
  createdAt   DateTime @default(now())

  vehicle Vehicle @relation(fields: [vehicleId], references: [id])

  @@index([vehicleId, performedAt])
  @@map("maintenance_records")
}

model FuelLog {
  id         String   @id @default(uuid())
  vehicleId  String
  tripId     String?
  liters     Decimal
  pricePerL  Decimal
  totalCost  Decimal
  odometerAt Int
  station    String?
  fueledAt   DateTime
  fueledBy   String?

  vehicle Vehicle @relation(fields: [vehicleId], references: [id])

  @@index([vehicleId, fueledAt])
}

model PromoCode {
  id             String   @id @default(uuid())
  tenantId       String?  // null = platform-wide
  code           String   @unique
  discountType   String   // PERCENT, FIXED
  discountValue  Decimal
  minBookingAmount Decimal?
  maxUses        Int?
  usedCount      Int      @default(0)
  validFrom      DateTime
  validUntil     DateTime
  active         Boolean  @default(true)
  createdAt      DateTime @default(now())

  applications PromoCodeApplication[]
}

model PromoCodeApplication {
  id         String   @id @default(uuid())
  promoCodeId String
  bookingId  String
  userId     String
  discountApplied Decimal
  appliedAt  DateTime @default(now())

  promoCode PromoCode @relation(fields: [promoCodeId], references: [id])
}

model PushSubscription {
  id        String   @id @default(uuid())
  userId    String
  endpoint  String   @unique
  keysJson  String
  userAgent String?
  createdAt DateTime @default(now())

  user User @relation(fields: [userId], references: [id])
}

model NotificationPreference {
  userId          String @id
  emailMarketing  Boolean @default(true)
  emailReminders  Boolean @default(true)
  smsReminders    Boolean @default(false)
  pushEnabled     Boolean @default(false)
  priceAlerts     Boolean @default(true)

  user User @relation(fields: [userId], references: [id])
}

model Complaint {
  id          String   @id @default(uuid())
  userId      String?
  bookingId   String?
  category    String   // DELAY, DRIVER, CLEANLINESS, PAYMENT, OTHER
  subject     String
  description String
  status      String   @default("OPEN") // OPEN, IN_PROGRESS, RESOLVED
  assignedTo  String?
  resolution  String?
  createdAt   DateTime @default(now())
  resolvedAt  DateTime?
}

model Review {
  id        String   @id @default(uuid())
  bookingId String   @unique
  userId    String
  tripId    String
  driverId  String?
  rating    Int      // 1-5
  comment   String?
  tags      String[] // CLEAN, ON_TIME, FRIENDLY, COMFORTABLE
  createdAt DateTime @default(now())
}

model TripTemplate {
  id              String   @id @default(uuid())
  tenantId        String
  routeId         String
  vehicleId       String
  driverId        String
  daysOfWeek      Int[]    // [1,2,3,4,5] = weekdays
  departureTime   String   // "09:00"
  validFrom       DateTime
  validUntil      DateTime?
  active          Boolean  @default(true)
  createdAt       DateTime @default(now())
}

model SavedCard {
  id               String   @id @default(uuid())
  userId           String
  iyzicoCardToken  String   // Iyzico's tokenized card reference
  maskedPan        String   // "**** **** **** 1234"
  cardFamily       String?  // Bonus, Axess, etc.
  cardType         String?  // CREDIT_CARD, DEBIT_CARD
  expiry           String?
  createdAt        DateTime @default(now())

  user User @relation(fields: [userId], references: [id])
}

6.3 Eksik İndeksler

CREATE INDEX idx_trips_tenant_status_departure ON trips(tenant_id, status, departure_time);
CREATE INDEX idx_bookings_trip_status ON bookings(trip_id, status);
CREATE INDEX idx_bookings_user ON bookings(user_id, booking_time DESC);
CREATE INDEX idx_audit_timestamp ON audit_logs(tenant_id, timestamp DESC);

7. API Endpoint Envanteri

7.1 Auth

POST /auth/register — company admin kayıt
POST /auth/login — B2B login
POST /auth/customer/register — yolcu kayıt
POST /auth/customer/login — yolcu login
GET /auth/customer/profile — profil oku
PATCH /auth/customer/profile — profil güncelle
PATCH /auth/customer/password — şifre değiştir
GET /auth/customer/bookings — kendi biletleri
POST /auth/customer/bookings/:id/cancel — bilet iptal (iade otomatik)
POST /auth/guest/ticket-lookup — PNR+email ile misafir bilet

7.2 Booking & Search

GET /booking/search — sefer arama
GET /booking/search/multi-leg — aktarmalı
GET /booking/trips/:tripId/seats — koltuk haritası
POST /booking/seats/lock — 10dk kilit
POST /booking/reservations — rezervasyon oluştur
GET /booking/ticket/:pnr — PNR ile bilet
GET /booking/ticket/:pnr/live — canlı konum (PNR+email)
GET /booking/tickets?pnrs=X,Y — çoklu bilet
POST /booking/bookings/:id/cancel — iptal (yolcu)
GET /booking/admin/bookings — admin liste
POST /booking/admin/bookings/:id/cancel — admin iptal + iade

7.3 Routes / Trips

GET /routes/public — public rota listesi
GET /routes/public/popular — popüler rotalar
GET /routes/public/stats — platform istatistikleri
CRUD /routes — admin rota yönetimi
GET /trips — admin sefer listesi
POST /trips — sefer oluştur
PATCH /trips/:id — şoför/araç değiştir (reassign)
GET /trips/public/cheap — ucuz seferler

7.4 Driver Ops

GET /driver-ops/trips/today — yaklaşan seferler
PATCH /driver-ops/trips/:id/status — sefer durumu
POST /driver-ops/trips/:id/location — GPS push
GET /driver-ops/trips/:id/manifest — yolcu listesi
POST /driver-ops/check-in/:pnr — yolcu check-in
POST /driver-ops/no-show/:pnr — gelmedi işaretle
POST /driver-ops/reset-boarding/:pnr — undo

7.5 Users / Drivers

CRUD /users/drivers — şoför CRUD
GET /stations / CRUD /stations
GET /vehicles / CRUD /vehicles

7.6 Passenger Features

GET /wallet/balance
GET /wallet/transactions
GET /referral/code
GET /referral/stats
POST /referral/apply
CRUD /price-alerts + POST /price-alerts/:id/toggle
GET /price-history?from=X&to=Y&days=N
GET /badges
GET /carbon?distanceKm=N

7.7 AI

POST /ai/chat — chatbot
POST /ai/suggest-price — admin fiyat önerisi
GET /ai/optimize-route — admin rota optimizasyonu

7.8 Utility

GET /city-image?city=X — Wikipedia foto
GET /audit-logs — admin denetim

7.9 Eklenecek Endpoint'ler

~~POST /auth/password-reset/request~~ ✅
~~POST /auth/password-reset/confirm~~ ✅
~~POST /auth/verify-email/send + /confirm~~ ✅
~~GET /auth/google + /auth/google/callback~~ ✅
POST /auth/2fa/enable + /2fa/verify → TOTP
POST /user/delete-account → KVKK self-servis
GET /user/data-export → KVKK self-servis JSON export
CRUD /vehicles/:id/maintenance-records
CRUD /vehicles/:id/fuel-logs
CRUD /promo-codes (admin)
POST /checkout/apply-promo → checkout'ta indirim
POST /push/subscribe — push notification subscription
GET/PATCH /notifications/preferences
CRUD /complaints
POST /reviews
CRUD /trip-templates
GET /stations/search-otogar?city=X — OSM Overpass otogar arama
GET /analytics/revenue — admin ciro dashboard
GET /analytics/occupancy — rota bazlı doluluk
POST /export/bookings.csv — admin CSV export
POST /sms/send — internal (Netgsm)

8. Frontend Sayfa Envanteri

Mevcut:

/ landing
/search sefer arama ve koltuk seçimi
/checkout ödeme
/success ödeme başarılı
/bilet-takip PNR ile takip
/bilet-takip/[pnr] canlı harita
/login + /register (B2B)
/hesap/giris + /hesap/kayit + /hesap/biletlerim + /hesap/cuzdan + /hesap/fiyat-alarmlari + /hesap/rozetler + /hesap/davet + /hesap/profil
/admin (7 sekme: genel, filo, istasyon, rota, sefer, bilet, şoför, denetim)
/driver
/rotalar, /fiyatlandirma, /hakkimizda, /iletisim, /blog, /basin, /kariyer, /sss, /yardim, /kvkk, /gizlilik, /sartlar, /cerez, /iade-politikasi

Eklenecek:

/rotalar/[slug] — SEO-dostu (ör. /rotalar/istanbul-ankara)
~~/sifre-sifirla~~ ✅
~~/email-dogrula~~ ✅
~~/google-callback~~ ✅
/hesap/ayarlar/guvenlik — 2FA, aktif sessionlar
/hesap/ayarlar/bildirimler — notification preferences
/hesap/veri-indir — KVKK export
/hesap/hesap-sil — soft delete
/hesap/degerlendirmeler — yorumlarım
/admin/analytics — grafikli dashboard
/admin/promo-kodlar
/admin/sefer-sablonlari
/admin/fiyat-kurallari
/admin/sikayetler — şikayet yönetimi
/driver/profil — şoför profili
/driver/istatistikler
/superadmin/* — platform dashboard

9. Entegrasyonlar

9.1 Aktif

Iyzico — ödeme + iade
Resend — email
Wikipedia REST — şehir landmark fotoları
OpenStreetMap — Leaflet tiles

9.2 Planlanan

OSM Overpass API — otogar lokasyon arama (FREE, official)
- Query: node["amenity"="bus_station"](area:TR);out;
- Endpoint: https://overpass-api.de/api/interpreter
Netgsm veya Iletimerkezi — SMS
Google Maps Distance Matrix — gerçek mesafe/süre
Sentry — hata izleme
Plausible veya Posthog — privacy-first analytics
Cloudflare — CDN, DDoS koruması, WAF
AWS S3 veya Cloudflare R2 — PDF/pass asset storage

9.3 Türk Araç Sorgulama (zor konu)

Türkiye'de plaka girince aracın km/muayene/sigorta bilgisi dönen ücretsiz public API yok:

E-Devlet API'si TCKN doğrulaması + eimza gerektirir, platform bazlı kullanılamaz
TRAMER (Sigorta Bilgi Merkezi) API'si sadece yetkili sigorta firmalarına açık
Commercial alternatifler: arackredi.com API, oto-sorgu.com — ücretli, ayda ~1000₺+
Pratik çözüm:
- Admin plakayı + araç bilgilerini manuel girer (bir kerelik)
- Muayene/sigorta tarihleri DB'de tutulur
- Cron job 30 gün önceden admin'e bildirim gönderir
- Km bilgisi şoför her sefer sonu girer (FuelLog + MaintenanceRecord üzerinden)
- Opsiyonel: commercial API entegrasyonu (ileride, premium tier için)

10. Ödeme Akışı (Detaylı)

10.1 Aktif Kullanıcı Ödemesi

Yolcu koltuk seçer → POST /booking/seats/lock (10 dk)
Yolcu checkout'a ilerler → yolcu bilgilerini girer
Frontend POST /payment/checkout-form → Iyzico token alır
Iyzico iframe açılır, kullanıcı kart bilgilerini girer
3D Secure doğrulama (eğer kart destekliyor)
Iyzico callback → POST /payment/callback → pending payment row
POST /booking/reservations → booking oluşur, koltuk BOOKED
Email + PDF bilet gönderilir (fire-and-forget)
Referral bonus + badge evaluation (fire-and-forget)
WebSocket broadcast seats:changed

10.2 İade Akışı

Yolcu POST /auth/customer/bookings/:id/cancel
6 saat kuralı kontrol
Booking → CANCELLED, Seat → AVAILABLE
paymentService.refundPayment(paymentTransactionId) → Iyzico
Iyzico başarılıysa refundStatus = REFUNDED, değilse FAILED
AuditLog
WebSocket broadcast seats:changed (FREED)

10.3 Eklenecek Flow'lar

Cüzdan kullanımı: Checkout'ta "Cüzdan bakiyemi kullan (max X₺)" checkbox
Promo kodu: Checkout'ta kod girişi → applyPromo → indirim
Saved card: "Kayıtlı kartla öde" → 3DS atlanır
Split payment: %50 cüzdan + %50 kart
Commission split: Platform fee → TransitIQ hesabı, gerisi tenant'a

11. Analytics & KPI'lar

11.1 İzlenecek Metrikler

Ürün:

DAU / MAU
Kayıt → ilk bilet conversion rate
Search → checkout funnel
Checkout → payment completion
İptal oranı (genel + 6h rule ihlali)
Rozet kazanma hızı
Referral katılımı

Operasyon:

Günlük ciro (tenant bazlı + platform)
Doluluk oranı (rota bazlı)
Aktif sefer sayısı
Şoför aktivasyon oranı (GPS push'u olan / toplam)
Check-in oranı (yolcu bindi / bilet sayısı)
No-show oranı

Teknik:

API latency (p50, p95, p99)
WebSocket connection count
Error rate (4xx, 5xx)
Uptime
Payment failure reasons breakdown

11.2 Admin Dashboard Bileşenleri (Planlanan)

Ciro grafik (günlük, 30g, 12ay)
Aktif sefer haritası (Türkiye üzerinde canlı noktalar)
Top 10 rota tablosu
Şoför performans listesi
İptal/iade özet kartları
Müşteri segmentleri pie chart
Saat bazlı satış heatmap
Real-time "şu an ne oluyor" ticker

12. Yapılacaklar — Faz Planlaması

Faz 1 — Temel Ürün (Tamamlandı)

Yolcu arama/ödeme/bilet, admin yönetim, temel güvenlik.

Faz 2 — Farklılaştırıcı Özellikler (~%90 tamamlandı)

WebSocket koltuklar, canlı sefer takibi, aktarmalı, grup koltuk, AI chatbot, rozet, cüzdan, referral, fiyat alarmı, karbon, audit log, multi-leg.

Faz 3 — Mobil & Offline (bu sprint'in devamı)

PWA manifest + service worker
Offline bilet (cached QR)
Apple Wallet / Google Wallet pass
Push notification subscription
Push notification gönderim sistemi (sefer hatırlatma cron)
Mobil UX iyileştirmeleri

Faz 4 — Güvenlik & Güven (aktif)

Faz 5 — Operasyon Gücü

Faz 6 — Büyüme & SEO

Faz 6.5 — Büyüme & UX Geliştirmeleri (yeni eklendi)

Faz 7 — İleri Analitik

Admin ciro dashboard (grafikler)
Doluluk analizi
ML tahminleme (doluluk, ciro)
Müşteri segmentasyonu
Lifecycle email (hoşgeldin, hatırlatma, re-engagement)
A/B test framework

Faz 7.5 — TÜRKİYE RESMİ ENTEGRASYONLAR ⚠️ (İlk müşteri öncesi ŞART)

Yasal zorunluluk (yapılmazsa ceza/kapatma):

U-ETDS entegrasyonu — T.C. Ulaştırma Bakanlığı, sefer + yolcu anlık raporlama. SOAP API ücretsiz. servis.uab.gov.tr/uetds/api/. D1/D2/D4 yetki belgeli firmalar için ŞART.
e-Bilet (GİB) — Logo/Uyumsoft/Mikro entegratörü üzerinden (~₺1500-2000/ay). 5M+ ciroda zorunlu.
e-Arşiv Fatura — Aynı entegratörler. 5M+ ciroda zorunlu.

Çok önerilen:

NVI KPS TC kimlik doğrulama — Yolcu kayıtta TC + ad soyad eşleşme. ~₺500 başlangıç + sorgu ücreti.
K-Yetki Belgesi sorgulama — UAB U-Net üzerinden plaka yetki kontrolü
SRC Belgesi sorgulama — Şoför yetki kontrolü
VERBİS kayıt — KVKK Kurumu resmi kayıt (ücretsiz, yapmak ŞART)

Stratejik avantaj: U-ETDS'i kendimiz yazarsak (entegratör kullanmadan) bunu B2B değer önermesi olarak sunabiliriz — Obilet/Enuygun bunu entegratör üzerinden yapıyor, biz native yaparız.

Ne zaman: Şirket kurulduktan ve ilk gerçek otobüs firması müşterisi geldikten hemen sonra.

Faz 8 — Mobil Uygulamalar (React Native / Expo)

Yolcu uygulaması (iOS + Android): arama, ödeme, biletlerim, canlı takip, push
Şoför uygulaması (iOS + Android): sefer listesi, QR check-in, GPS push (arka plan), manifesto
Admin: mobil-responsive web yeterli (ayrı uygulama gereksiz)
Shared NestJS API — aynı backend, yeni client
Apple Wallet / Google Wallet bilet pass entegrasyonu
App Store + Play Store yayını

Faz 9 — Platform Growth

Super admin paneli
Tenant onboarding akışı
Komisyon takibi
Multi-language (EN/AR/DE)

13. Test & Kalite

13.1 Şu an

Manuel test ağırlıklı
Typecheck her build'de

13.2 Eklenecek

E2E: Playwright (critical path: arama → koltuk → ödeme → bilet)
Unit: Jest (service layer)
Integration: Supertest (API)
Visual regression: Chromatic veya Percy
Load test: k6 (payment endpoint, WebSocket)
Penetrasyon testi (OWASP ZAP + manuel)

14. Deployment & Infra

14.1 Şu an

Local dev: Next.js + NestJS ayrı portlarda
DB: Neon serverless Postgres
Henüz prod'da değil

14.2 Hedef Prod Mimarisi

Frontend: Vercel (Next.js)
Backend: Railway veya Fly.io (NestJS + WebSocket sticky sessions)
DB: Neon Production tier
Redis: Upstash (cache, rate limit, session store)
Object Storage: Cloudflare R2 (PDF biletler, yedek)
CDN: Cloudflare (WAF + DDoS)
Monitoring: Sentry + Uptime Robot
DNS: Cloudflare
Email: Resend (mevcut)
SMS: Netgsm (aktif olunca)
Logs: Better Stack veya Axiom

14.3 CI/CD

GitHub Actions
- PR'da: typecheck + test + lint
- Main merge: auto-deploy staging
- Manual approve: prod deploy
Preview deployments her PR için

15. İş Modeli

15.1 Gelir Kanalları

Komisyon: Her satılan bilet üzerinden %X (tenant'a yansıtılmaz ya da yansıtılır, test edilecek)
SaaS abonelik: Tenant'a aylık plan (Başlangıç ₺4.990 / Profesyonel ₺12.990 / Kurumsal özel)
Premium yolcu özellikleri: Fiyat alarmı sınırsız, öncelikli destek (opsiyonel)
Affiliate: Hotel/car rental bağlantıları (ileride)

15.2 Maliyet

Iyzico işlem başına komisyon
Resend email (10k/ay ücretsiz)
Neon DB (küçük tier ücretsiz, büyüyünce $19/ay)
Domain + SSL
Sentry/monitoring (~$0-30/ay)
SMS (Netgsm aktif olunca, ~0.05₺/SMS)

16. Öncelik Matrisi (şu an)

Özellik	Etki	Efor	Öncelik
OSM otogar auto-fetch	Yüksek	Orta	HEMEN
Araç maintenance/fuel log	Yüksek	Orta	HEMEN
PWA + offline bilet	Yüksek	Yüksek	Sonraki
Push notifications	Yüksek	Orta	Sonraki
~~Şifre sıfırlama~~	~~Kritik~~	~~Düşük~~	✅
~~Google OAuth~~	~~Yüksek~~	~~Orta~~	✅
2FA	Yüksek	Orta	Sonraki
Sentry	Orta	Düşük	Sonraki
Promo kodu	Yüksek	Orta	Faz 5
Sefer şablonu	Orta	Orta	Faz 5
Admin analytics dashboard	Yüksek	Yüksek	Faz 7
OPERATOR rolü	Orta	Düşük	Faz 5
SEO sayfa başına	Yüksek	Orta	Faz 6

17. Karar Kayıtları (ADR — lite)

KK-001: Leaflet CDN-loaded, npm dep değil. Sebep: İlk npm install DNS hatası verdi. CDN yaklaşımı SSR/hydration problemini de çözüyor. İleride internet iyileştiğinde react-leaflet alternatif olur.

KK-002: PNR TX-XXXXXX 6 karakter. Sebep: Telefon/telsiz üzerinden sözlü iletişim. 32^6 = 1 milyar kombinasyon, ölçekte yeterli.

KK-003: Multi-leg 10 hub şehriyle sınırlı. Sebep: N×M arama maliyeti büyük. Ana hub'lar: İstanbul, Ankara, İzmir, Bursa, Konya, Antalya, Adana, Samsun, Kayseri, Eskişehir.

KK-004: WebSocket yerel DB state refresh tetikliyor. Sebep: CRDT veya Redis pub/sub overkill. Trip başına viewer sayısı düşük (<100). HTTP fetch refresh yeterli.

KK-005: Audit log JSON blob, ayrı tablo değil. Sebep: Entity bazında diff göster, log query'si filtrele. Büyüyünce partitioning (aylık) düşünülecek.

KK-006: Wikipedia şehir foto fallback'i frontend'den DEĞİL backend'den. Sebep: CORS + rate limit. Backend cache + User-Agent header.

KK-007: children prop'lu Tailwind notif template hatası preexisting — bu sprint'te düzeltilmeyecek.

18. Performans & Kod Hijyeni

18.1 Uygulanmış İyileştirmeler

✅ Admin panelleri code-split — tüm 30+ panel next/dynamic + activeTab gating → sadece aktif tab mount edilir, initial JS bundle ~%50 azaldı
✅ Visibility-aware polling — useVisibleInterval hook'u: tab arka plandayken setInterval durur, geri gelince bir kez refresh eder (notification-bell 60s, platform-health 30s)
✅ Türkçe input formatters merkezi — lib/formatters.ts (TC, telefon, IBAN, plaka, MERSİS, D belgesi, kart, SKT)
✅ Themed dialogs her yerde — 17 native window.confirm/prompt kaldırıldı → confirmDialog/promptDialog/alertDialog
✅ PDF Türkçe font — commerce invoice: Segoe UI / Arial / DejaVu auto-detect, fallback transliterate
✅ Schema FK integrity — Settlement + Review → Booking relation'ları eklendi (Restrict + Cascade uygun)
✅ Silent error kaldırıldı — payment callback .catch(() => {}) → try/catch + console.error (settlement başarısızlığı artık loglanıyor)

18.2 Design De-AI Pass (2026-04-18)

Enes: "siteyi bi gözden geçir çokta ai vari durmasın ama tasarım çizgimizden de şaşma"

✅ Login/register hero: from-indigo-400 via-purple-400 to-indigo-400 animate-gradient-x → solid text-indigo-400
✅ CTA section gradient'leri (5 sayfa: fiyatlandirma, yardim, sss, iletisim, basin): bg-gradient-to-br from-indigo-600 to-purple-700 → bg-indigo-600
✅ Announcement banner tone map: gradient'lerden flat renge (INFO/WARNING/CRITICAL)
✅ Platform-health status card: gradient → flat emerald/amber/rose
✅ B2B landing CTA: dekoratif blur orb'lar kaldırıldı, via-indigo-700 to-purple-800 → bg-indigo-700
✅ Register sayfası fake özellik metni "AI Destekli Akıllı Rota" → gerçek değer teklifleri

18.3 Kalan Performans TODO

⏳ Sidebar + TopBar React.memo (notification-bell poll'unda cascade re-render'ı kes)
⏳ Bundle analyze CI (next-bundle-analyzer ile her PR'da rapor)
⏳ Leaflet lazy loading — arama sayfası ilk yüklerken gerek yok, koltuk seçince yüklensin
⏳ Public sayfa ISR (Incremental Static Regeneration) — /rotalar, /firma/[slug], /sss gibi sayfalar Next cache'le
⏳ Image optimization — /kapadokya.png ve hero carousel Next Image component'ına

18.4 Acil CLI Komutları

npm run super-admin <email> <parola> "Ad Soyad" — SUPER_ADMIN oluştur
npm run maintenance [on|off|status] — bakım modu kontrolü (DB doğrudan)
npm run tenants — tüm tenant'ları listele
npm run check-tenant <slug> — tenant booking/settlement durumu
npm run settle:backfill — eksik Settlement kayıtlarını toplu oluştur

Çalışma Kuralları

Güvenlik asla compromise edilmez. Her endpoint auth + tenant scope ile çıkar.
Tasarım çizgisi korunur. Indigo brand, rounded-2xl/3xl, dark mode parity.
AI görünümünden kaçınılır. Sparkles'ı kısıtla, gradient'leri dengele, gerçek fotoğraflar.
Her değişiklik typecheck'ten geçer.
Audit log işletiliyor. Yeni mutasyon eklenirse audit çağrısı zorunlu.
Her yeni özellik bu doküman güncellenir.

FilesExpand file tree

MASTER_PLAN.md

Latest commit

History