[G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00
parent f0befc887a
commit 93ec7e9056
363 changed files with 68333 additions and 64 deletions
@@ -0,0 +1,106 @@
+---
+id: android-workmanager-patterns
+title: WorkManager — 신뢰성 있는 백그라운드 작업
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [android, workmanager, background, vibe-coding]
+tech_stack: { language: "Kotlin / WorkManager 2.9+", applicable_to: ["Android"] }
+applied_in: []
+aliases: [periodic work, one-time work, constraints, deferred]
+---
+
+# WorkManager 패턴
+
+> "배터리 / 네트워크 / 충전" 조건 충족 시 OS 가 알아서 실행해주는 영속 작업 큐. **process 죽어도 살아남음**. 즉각 백그라운드 작업이 아닌 "결국 실행되어야 함" 인 작업에 적합.
+
+## 📖 핵심 개념
+- One-time vs Periodic (최소 15분).
+- Constraints: 네트워크 / 충전 / idle / 배터리.
+- Backoff: 실패 시 재시도 정책.
+- Unique work: 같은 이름의 작업 중복 방지.
+
+## 💻 코드 패턴
+
+### CoroutineWorker
+```kotlin
+@HiltWorker
+class SyncWorker @AssistedInject constructor(
+    @Assisted ctx: Context,
+    @Assisted params: WorkerParameters,
+    private val repo: SyncRepository,
+) : CoroutineWorker(ctx, params) {
+
+    override suspend fun doWork(): Result = try {
+        val sinceMs = inputData.getLong("since", 0L)
+        repo.pullChanges(sinceMs)
+        Result.success(workDataOf("count" to 42))
+    } catch (e: IOException) {
+        if (runAttemptCount < 3) Result.retry() else Result.failure()
+    } catch (e: Exception) {
+        Result.failure()
+    }
+}
+```
+
+### Enqueue with constraints
+```kotlin
+val req = OneTimeWorkRequestBuilder<SyncWorker>()
+    .setConstraints(Constraints.Builder()
+        .setRequiredNetworkType(NetworkType.UNMETERED)
+        .setRequiresCharging(true)
+        .build())
+    .setInputData(workDataOf("since" to lastSyncMs))
+    .setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 30, TimeUnit.SECONDS)
+    .build()
+
+WorkManager.getInstance(context)
+    .enqueueUniqueWork("sync-changes", ExistingWorkPolicy.KEEP, req)
+```
+
+### Periodic
+```kotlin
+val req = PeriodicWorkRequestBuilder<SyncWorker>(1, TimeUnit.HOURS)
+    .setConstraints(networkConstraints)
+    .build()
+WorkManager.getInstance(context)
+    .enqueueUniquePeriodicWork("hourly-sync", ExistingPeriodicWorkPolicy.KEEP, req)
+```
+
+### Foreground (긴 작업)
+```kotlin
+override suspend fun doWork(): Result {
+    setForeground(createForegroundInfo()) // 알림 표시
+    return processLongJob()
+}
+```
+
+## 🤔 의사결정 기준
+| 작업 | 도구 |
+|---|---|
+| 즉시 1회 (UI 동안) | viewModelScope |
+| 화면 닫혀도 계속 (5분 이내) | Service (foreground) |
+| 결국 실행돼야 함 (나중 OK) | WorkManager one-time |
+| 주기적 (≥15분) | WorkManager periodic |
+| 긴 다운로드 + 진행 표시 | WorkManager + foreground info |
+| 특정 시각 alarm | AlarmManager (정확 시각) — WorkManager 는 시각 보장 X |
+
+## ❌ 안티패턴
+- **WorkManager 를 즉시 작업에**: OS 가 지연 가능. 즉시 = Service 또는 coroutine.
+- **enqueue 대신 enqueueUnique 안 씀**: 같은 작업 중복 큐잉.
+- **Result.failure() 인데 사용자 모름**: 실패 알림 누락. observe + UI 표시.
+- **input/output Data 가 큼 (>10KB)**: Bundle 크기 한계. ID 만 전달, 본문은 DB/file.
+- **doWork 가 너무 오래 (>10분)**: OS 가 강제 종료. expedited work 또는 foreground.
+- **Hilt 통합 빠뜨림**: 의존성 주입 안 됨. HiltWorker + WorkerFactory 등록.
+- **periodic 15분 미만**: OS 가 무시.
+
+## 🤖 LLM 활용 힌트
+- 상황 분류 → 작업 도구 매트릭스 먼저 그리기.
+- HiltWorker 통합 코드 같이.
+
+## 🔗 관련 문서
+- [[Android_Kotlin_Coroutines_Scopes]]
+- [[Backpressure_Patterns]]