---
name: app-lock
description: |
  MathLock Play uygulama kilitleme sistemi: AppLockService foreground service,
  UsageStats algılama, WindowManager overlay, challenge picker, kilit ekranı,
  Xiaomi/MIUI özel izin akışı, pil optimizasyon diyalogları, ebeveyn bypass,
  timer ve flood-launch önleme. Kullanıcı "kilitleme", "AppLockService",
  "overlay", "Xiaomi", "MIUI", "challenge picker", "kilit ekranı",
  "servis duruyor", "pil optimizasyonu", "kilit açma", "kilitlenmiyor",
  "kilit ekranı", "app lock" ile ilgili soru sorduğunda aktive ol.
---

# App Lock (Uygulama Kilitleme) — Hızlı Referans

## Proje Yapısı

```
app/src/main/java/com/akn/mathlock/
  ├── service/AppLockService.kt           # Ana foreground service (~769 satır)
  ├── ChallengePickerActivity.kt          # Oyun seçim ekranı
  ├── SettingsActivity.kt                 # Ayarlar + Xiaomi kurulum sihirbazı
  ├── LockStateManager.kt                 # Kilit durumu yönetimi
  └── util/PreferenceManager.kt           # Kilitleme ile ilgili 25+ pref key

app/src/main/res/
  ├── layout/activity_challenge_picker.xml
  ├── layout/dialog_app_lock_permission.xml
  └── values/strings.xml                  # Kilit ekranı metinleri
```

## Temel Kavramlar

- **AppLockService**: Foreground service. 800ms aralıklarla `UsageStats` kontrol eder. Hedef uygulama öne çıkarsa challenge overlay'i başlatır.
- **Overlay**: `WindowManager.addView()` ile sistem üzerine kilit ekranı çizilir. `TYPE_APPLICATION_OVERLAY`.
- **Challenge**: Kilit açmak için çözülmesi gereken oyun (matematik, sayı yolculuğu, mastermind, vb.).
- **ChallengePicker**: Birden fazla oyun aktifse rastgele birini seçer; tek aktifse doğrudan o başlar.
- **Timer**: Kilit açıldıktan sonra X dakika boyunca aynı uygulama serbest. Süre dolunca tekrar kilitler.
- **Flood Launch**: Aynı uygulamanın saniyede birden fazla başlatılmasını önler.
- **Stuck Challenge**: Challenge activity'si çökerse veya kapanırsa servis 5sn içinde yeni challenge başlatır.

## Servis Yaşam Döngüsü (Özet)

1. `onCreate()` → NotificationChannel oluştur, `UsageStatsManager` al, broadcast receiver'ları kaydet.
2. `onStartCommand()` → `START_STICKY`. Intent action'a göre:
   - `ACTION_START`: Servisi başlat, polling loop'u çalıştır.
   - `ACTION_STOP`: Servisi durdur, overlay'leri kaldır.
   - `ACTION_CHECK`: Anlık UsageStats kontrolü.
3. Polling Loop (800ms):
   - Son kullanılan uygulamayı `UsageStatsManager`'dan al.
   - Hedef listedeyse ve timer dolmuşsa → `showChallenge()`.
   - Ebeveyn uygulaması (MathLock) veya sistem uygulamaları bypass.
4. `showChallenge()`:
   - Overlay kaldır (varsa).
   - `ChallengePickerActivity`'yi `FLAG_ACTIVITY_NEW_TASK | FLAG_ACTIVITY_CLEAR_TOP` ile başlat.
   - Flood-launch kontrolü: son 2 saniye içinde aynı uygulama için challenge başlatılmadıysa.
5. `onDestroy()` → Receiver'ları unregister et, overlay'leri kaldır.

Detaylı service akışı, overlay sistemi ve broadcast receiver'lar için bkz. [references/app-lock-service.md](references/app-lock-service.md).

## Challenge Picker & Timer

- `ChallengePickerActivity.kt` (~205 satır):
  - Aktif oyunları `PreferenceManager`'dan okur.
  - Birden fazla aktif oyun varsa rastgele seçer.
  - Tek oyun varsa doğrudan o aktiviteye yönlendirir.
  - `requiredCount` (örn. 3 doğru) kazanılınca `LockStateManager.unlockApp()` çağrılır.
- Timer: `PreferenceManager.getUnlockDuration()` dakika boyunca aynı uygulama serbest.
- Süre dolunca `AppLockService` tekrar challenge gösterir.

Detaylar için bkz. [references/challenge-picker.md](references/challenge-picker.md).

## Xiaomi / MIUI Özel Durumları

- MIUI pil optimizasyonu AppLockService'ı öldürür.
- `SettingsActivity.kt`'te 3 adımlı sihirbaz:
  1. Pil optimizasyonu izni (Battery Saver hariç tut).
  2. Otomatik başlatma izni (Autostart).
  3. Overlay izni (Diğer uygulamalar üzerinde göster).
- `xiaomiStepPending` pref'i ile durum makinesi yönetilir.
- Kullanıcı sihirbazı tamamlamazsa servis çalışmayabilir.

Detaylı Xiaomi akışı, izin diyalogları ve state machine için bkz. [references/xiaomi-miui.md](references/xiaomi-miui.md).

## Önemli İzinler

| İzin | Amaç | Kullanıcı Eylemi |
|------|------|------------------|
| `PACKAGE_USAGE_STATS` | Son kullanılan uygulamayı tespit et | Ayarlar → Erişim kullanım verileri → MathLock |
| `SYSTEM_ALERT_WINDOW` | Overlay kilit ekranı çiz | Ayarlar → Diğer uygulamalar üzerinde göster → MathLock |
| `FOREGROUND_SERVICE` | Servis ön planda kalır | Otomatik (Android 9+) |
| `RECEIVE_BOOT_COMPLETED` | Cihaz açılışında servis başlat | Otomatik (manifest) |
| Xiaomi Autostart | MIUI'de servisin yaşaması | Ayarlar → İzinler → Otomatik başlatma |
| Xiaomi Battery Saver | Pil optimizasyonu dışı tut | Ayarlar → Uygulamalar → MathLock → Pil |

## Hızlı Kod Referansı

```kotlin
// Servisi başlatma
val intent = Intent(context, AppLockService::class.java)
intent.action = AppLockService.ACTION_START
ContextCompat.startForegroundService(context, intent)

// Servisi durdurma
val stopIntent = Intent(context, AppLockService::class.java)
stopIntent.action = AppLockService.ACTION_STOP
context.startService(stopIntent)

// Timer kontrolü
val unlockUntil = PreferenceManager.getUnlockUntil()
val isUnlocked = System.currentTimeMillis() < unlockUntil

// Hedef uygulama kontrolü
val usageStats = usageStatsManager.queryUsageStats(...)
val lastApp = usageStats.maxByOrNull { it.lastTimeUsed }
if (targetApps.contains(lastApp?.packageName) && !isUnlocked) {
    showChallenge(lastApp.packageName)
}
```