# Kaptanspor Mobil Entegrasyon & API Dokümantasyonu (MOBILE_ARCH.md) Bu kılavuz, Kaptanspor Canlı Monitör Sistemi'nin mobil uygulaması (**Kap Order**) ve sunucu arasındaki haberleşme mimarisini, kimlik doğrulama süreçlerini, HTTP API uç noktalarını ve Socket.io canlı veri akışını belgeler. Başka bir geliştirici veya sistem bu dokümantasyonu referans alarak yeni istemciler geliştirebilir veya sisteme entegre olabilir. --- ## 🏗️ 1. Genel Mimari ve İletişim Akışı Mobil uygulama, doğrudan `kappmes.com` (Hub Portal) ve `kaptanspor.com.tr` (E-Ticaret/CRM) sunucularındaki IP whitelist engeline takılmamak için **`monitor.kappmes.com` Node.js ara sunucusu (Port 4000)** üzerinden haberleşir. Ara sunucu, e-ticaret ve Hub veritabanlarına güvenli kanallardan erişerek mobil uygulamaya veri sağlar. ``` +-------------------+ +-----------------------+ +----------------------+ | | HTTPS | monitor.kappmes.com | Localhost| kappmes.com (Hub) | | Kap Order App | --------> | (Node.js Proxy) | --------> | (Portal - 5002) | | (iOS & Android) | Socket | (Port 4000) | +----------------------+ | | +-----------------------+ | | | | v | | | HTTPS +----------------------+ | | +---------------------> | kaptanspor.com.tr | | | | (ERP / CRM secure) | +-------------------+ +----------------------+ ``` --- ## 🔒 2. Kimlik Doğrulama (Authentication) & Güvenlik Sistemde iki farklı kimlik doğrulama yöntemi desteklenir: 1. **Dinamik Login & Kısa Ömürlü JWT (Önerilen):** Kullanıcı adı ve şifre ile giriş yapılır, sunucudan kısa ömürlü bir JWT alınır. 2. **Statik Mobil Token Bypass:** Test veya hızlı geliştirme süreçleri için `MOBILE_API_TOKEN` parametresi ile isteklerin doğrulanması sağlanır. ### A. Giriş (Login) ve JWT Alma Uç Noktası Kullanıcı giriş yaptığında bu API çağrılarak Hub portalında doğrulanır ve JWT üretilir. * **URL:** `https://monitor.kappmes.com/api/mobile/login` * **Metot:** `POST` * **İstek Gövdesi (JSON):** ```json { "username": "kaptanspor_kullanici", "password": "kullanici_sifresi" } ``` * **Başarılı Yanıt (JSON):** ```json { "success": true, "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6...", "username": "kaptanspor_kullanici", "isAdmin": false } ``` * **Hatalı Yanıt (JSON):** ```json { "success": false, "error": "Hatalı kullanıcı adı veya şifre!" } ``` --- ## 📡 3. HTTP API Referansı Tüm API isteklerinde yetkilendirme için header alanına **JWT** eklenmeli ya da query parametresi olarak gönderilmelidir: - **Header:** `Authorization: Bearer ` veya `x-mobile-token: ` - **Query:** `?mobile_token=` veya `?token=` ### A. Sipariş Detaylarını Getir (ve Mağaza Stokları) Sipariş detaylarını, ürünleri, varyantları ve ürünlerin Hitit mağaza depolarındaki fiziksel stok durumunu döner. E-ticaret sunucusu kapalıysa, veriyi yerel önbellek JSON dosyasından çeker. * **URL:** `https://monitor.kappmes.com/api/order-detail` * **Metot:** `GET` * **Parametreler:** - `siparis_no` (Zorunlu): Sipariş numarası veya referans numarası (Örn: `187399`). - `mobile_token` veya `token` (Zorunlu): Yetkilendirme token'ı. * **Yanıt Yapısı (JSON):** ```json { "success": true, "offline": false, "order": { "siparis_no": "187399", "customer": "Ahmet Yılmaz", "sales_channel": "KaptanSpor.com.tr", "items": [ { "product_name": "Nike Air Max 270", "variant": "BEDEN: 42.5 / RENK: Siyah", "quantity": 1, "price": "4250.00", "stok_kodu": "NK-AM270-BLK-425", "depolar": [ { "depo_adi": "Malatya Park AVM", "stok_durumu": "1 ADET" }, { "depo_adi": "Merkez Depo", "stok_durumu": "3 ADET" } ] } ] } } ``` ### B. Expo Push Notification Token Kaydı Mobil cihaz bildirim alabilmek için aldığı Expo Push Token değerini bu API ile sunucuya kaydeder. * **URL:** `https://monitor.kappmes.com/api/mobile/register-token` * **Metot:** `POST` * **İstek Gövdesi (JSON):** ```json { "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]", "username": "kaptanspor_kullanici" } ``` * **Yanıt Yapısı (JSON):** ```json { "success": true, "message": "Token registered successfully" } ``` --- ## 🔌 4. Socket.io Canlı Akış Referansı Mobil uygulama ile sunucu arasındaki canlı haberleşme Socket.io protokolü ile sağlanır. * **Socket Sunucu Adresi:** `wss://monitor.kappmes.com` * **Bağlantı Ayarları (JSON Auth):** ```javascript const socket = io("https://monitor.kappmes.com", { auth: { mobile_token: "JWT_VEYA_STATIC_TOKEN" }, transports: ["websocket"] }); ``` ### Sunucu Tarafından İstemciye Gönderilen Olaylar (Listen Events) #### 1. `initial_state` Bağlantı kurulduğu anda sunucunun o anki tüm hafıza durumunu (metrics, akış, ziyaretçiler) topluca gönderir. * **Payload:** ```json { "visitor_count": { "active": 145 }, "flow": [ ... ], "ops": { "daily": { "orders": 12, "revenue": 45890.50 }, "monthly": { "orders": 340, "revenue": 1452900.00 } }, "trendyol": { "pending_orders": 4, "total_today": 18 } } ``` #### 2. `new_order` Sistemde yeni bir işlem (Sipariş, Üye, Destek Talebi, Instagram mesajı vb.) gerçekleştiğinde tetiklenir. Mobil bildirim ve sesler bu olay üzerinden yönetilir. * **Payload:** ```json { "type": "SİPARİŞ", "title": "Yeni Sipariş Oluşturuldu", "user": "Mehmet Can", "desc": "#187401 nolu sipariş KaptanSpor.com.tr kanalından alındı.", "time": "2026-07-21T10:40:00Z", "badge": "primary", "details": { "siparis_no": "187401", "amount": 2500.00, "items": [ ... ] } } ``` #### 3. `metrics_update` Genel operasyon rakamları veya canlı akış listesi güncellendiğinde tetiklenir. * **Payload:** `{ ops: { ... }, flow: [ ... ] }` --- ## 💾 5. Hata Toleransı & Çevrimdışı Yapı (Resilience) E-Ticaret sitesinde oluşabilecek kesintilerde sipariş detaylarına erişilebilmesi için kurulan yapı: 1. **Lokal Kayıt (Write):** Sunucuya gelen her `/api/webhooks/order` isteğindeki sipariş verisi otomatik olarak `sessions/orders/${ref_no}.json` dosyasına yazılır. 2. **Çevrimdışı Okuma (Read Fallback):** Uygulama `/api/order-detail?siparis_no=X` sorgusu attığında, e-ticaret API'si hata verirse sunucu otomatik olarak yerel dosyadaki JSON'ı döner. Böylece siparişin kaybolması veya okunanamaması engellenir. --- ## 🔔 6. Arka Plan Bildirimleri (Push Notifications) Uygulama arka planda kapalıyken de bildirimlerin gitmesi için **Expo EAS Push** bulut servisleri kullanılır. 1. Sunucu `/api/webhooks/order` üzerinden yeni işlem aldığında `sessions/push_tokens.json` dosyasındaki cihaz token'larını okur. 2. Sunucu, Expo API endpoint'ine (`https://exp.host/--/api/v2/push/send`) POST isteği gönderir: ```json [ { "to": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]", "title": "🛒 Yeni Sipariş!", "body": "Ahmet Yılmaz — ₺4,250.00", "sound": "default", "data": { "siparis_no": "187399" } } ] ``` 3. Expo bulut sunucuları, Apple Geliştirici Hesabı sertifikalarını kullanarak bildirimi Apple APNs sistemine iletir. APNs ise bildirimi hedef iOS cihaza ulaştırır. --- ## 📱 7. Mobil Uygulama Proje Yapısı (Kap Order) Uygulama, **React Native + Expo SDK** kullanılarak geliştirilmiştir. Klasör ve dosya yapısı aşağıdaki gibidir: ``` KapOrder/ ├── App.js # Uygulama giriş noktası, push bildirimleri ve rota yönetimi ├── app.json # Expo yapılandırma ayarları (App name, bundle ID, splash vb.) ├── package.json # Bağımlılıklar (Socket.io-client, SecureStore, Haptics vb.) └── src/ ├── constants.js # Renk paleti, socket URL, durum badge konfigürasyonları ├── components/ │ ├── EventCard.js # İşlem akışındaki satırların (Sipariş, Instagram vb.) gösterim kartı │ ├── MetricsHeader.js # Üst kısımda ciro ve Trendyol oranlarını gösteren metrik bileşeni │ └── OrderDetailModal.js# Detaylı ürün, varyant ve depo stoklarını gösteren modal pencere ├── hooks/ │ └── useSocket.js # Socket.io bağlantısını yöneten ve durumları güncelleyen özel hook └── screens/ ├── LoginScreen.js # Kullanıcı adı/şifre giriş ekranı (SecureStore entegrasyonlu) ├── FlowScreen.js # Ana dashboard, alt menü (Bottom Tab) ve filtreleme ekranı └── AnalyticsScreen.js # Google Analytics (GA4) anlık ziyaretçi takip ekranı ``` ### Ekranlar Arası Geçiş ve Veri Paylaşımı: - **Giriş Kontrolü:** `App.js`, `expo-secure-store` içerisinde geçerli bir JWT olup olmadığını kontrol eder. JWT yoksa kullanıcıyı `LoginScreen`'e yönlendirir. Başarılı girişte JWT kaydedilip `FlowScreen` açılır. - **Canlı Veri Senkronizasyonu:** `useSocket.js` hook'u sunucuyla websocket bağlantısını ayakta tutar. Alınan yeni eventler ve metrikler React state üzerinden alt ekranlara ve bileşenlere (FlatList, MetricsHeader vb.) aktarılır. - **İlave İstekler:** Cihaz titreşimi için `expo-haptics`, yerel anlık bildirim balonları için `expo-notifications` kütüphaneleri kullanılarak native bir kullanıcı deneyimi hedeflenmiştir.