バックグラウンド更新は来ないことがある — 実行機会を測り、鮮度から設計をやり直した記録

import BackgroundTasks
import Foundation
 
enum RefreshLog {
    private static let lastRunKey = "bg.lastRunAt"
    private static let lastScheduleKey = "bg.lastScheduledAt"
    private static let historyKey = "bg.runHistory"
 
    static func markScheduled() {
        UserDefaults.standard.set(Date(), forKey: lastScheduleKey)
    }
 
    static func markCompleted(success: Bool) {
        let now = Date()
        UserDefaults.standard.set(now, forKey: lastRunKey)
 
        // 直近 30 件だけ保持する。解析はこの配列で足りる
        var history = UserDefaults.standard.array(forKey: historyKey) as? [[String: Any]] ?? []
        history.append([
            "at": now.timeIntervalSince1970,
            "scheduledAt": (UserDefaults.standard.object(forKey: lastScheduleKey) as? Date)?
                .timeIntervalSince1970 ?? 0,
            "success": success,
            "lowPower": ProcessInfo.processInfo.isLowPowerModeEnabled,
        ])
        UserDefaults.standard.set(Array(history.suffix(30)), forKey: historyKey)
    }
 
    /// アプリ起動時に呼ぶ。「最後に更新できてから何時間経ったか」が鮮度そのもの
    static func stalenessHours() -> Double? {
        guard let last = UserDefaults.standard.object(forKey: lastRunKey) as? Date else { return nil }
        return Date().timeIntervalSince(last) / 3600
    }
}

func scheduleRefresh() {
    let request = BGAppRefreshTaskRequest(identifier: "net.example.wallpaper.refresh")
    request.earliestBeginDate = Date(timeIntervalSinceNow: 6 * 3600)
    do {
        try BGTaskScheduler.shared.submit(request)
        RefreshLog.markScheduled()
    } catch {
        // submit の失敗は静かに起きる。ここを握り潰すと原因追跡が不可能になる
        Analytics.log("bg_submit_failed", ["reason": "\(error)"])
    }
}
 
func handle(task: BGAppRefreshTask) {
    scheduleRefresh() // 次回分を先に予約する。ここを最後に書くと expiration で失われる
 
    let work = Task {
        let ok = await WallpaperUpdater.shared.prepareNext()
        RefreshLog.markCompleted(success: ok)
        task.setTaskCompleted(success: ok)
    }
 
    task.expirationHandler = {
        work.cancel()
        RefreshLog.markCompleted(success: false)
    }
}

class WallpaperRefreshWorker(
    context: Context,
    params: WorkerParameters,
) : CoroutineWorker(context, params) {
 
    override suspend fun doWork(): Result {
        val prefs = applicationContext.getSharedPreferences("bg", Context.MODE_PRIVATE)
        val startedAt = System.currentTimeMillis()
 
        val usageStats = applicationContext.getSystemService(UsageStatsManager::class.java)
        val bucket = usageStats?.appStandbyBucket ?: -1 // rare 以下に落ちていないかを見る
 
        return try {
            WallpaperUpdater.prepareNext()
            prefs.edit()
                .putLong("lastRunAt", startedAt)
                .putInt("lastBucket", bucket)
                .apply()
            Result.success()
        } catch (e: IOException) {
            // ネットワーク起因は再試行に値する。それ以外を retry に混ぜない
            if (runAttemptCount < 3) Result.retry() else Result.failure()
        }
    }
}

func entryIndex(for date: Date, seed: UInt64, count: Int) -> Int {
    let day = Int(date.timeIntervalSince1970 / 86400)
    // 端末ごとのシードで並びをずらし、全利用者が同じ絵を見る事態を避ける
    var hasher = SplitMix64(state: seed &+ UInt64(day))
    return Int(hasher.next() % UInt64(count))
}

## background-refresh-report
 
- 入力は `metrics/bg_runs/*.json` のみ。アプリのソースは読まない
- 出力は `reports/bg_freshness_YYYY-MM-DD.md` の 1 ファイル
- p50 / p90 の staleness、実行率、バケット別内訳を必ず含める
- 前週比の悪化が p90 で 12 時間を超えたら、見出しに ⚠ を付ける
- **閾値の変更・スケジュールの修正・コードの編集は行わない**