[G1-Sync] Manual knowledge update

10_Wiki/Topics/Coding/Android_Navigation_Compose.md

@@ -0,0 +1,125 @@
+---
+id: android-navigation-compose
+title: Android Navigation (Compose) — 타입 안전 라우팅
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [android, navigation, compose, vibe-coding]
+tech_stack: { language: "Kotlin / Navigation-Compose 2.8+", applicable_to: ["Android"] }
+applied_in: []
+aliases: [NavController, NavGraph, type-safe routes, deep link]
+---
+
+# Android Navigation (Compose)
+
+> Navigation-Compose 2.8+ 의 **타입 안전 routes** (Kotlin Serialization). 옛 string route 시대는 끝. **NavGraph 분할 + 단방향 dependency** 가 modular 앱의 표준.
+
+## 📖 핵심 개념
+- 각 destination = `@Serializable` data class.
+- NavController.navigate(Object) — 타입 안전.
+- 인자 자동 SavedStateHandle 주입.
+- Deep link, animation, nested graph 모두 지원.
+
+## 💻 코드 패턴
+
+### 타입 안전 destination
+```kotlin
+@Serializable data object HomeRoute
+@Serializable data class ProfileRoute(val userId: String)
+@Serializable data class OrderRoute(val orderId: String, val highlight: Boolean = false)
+```
+
+### NavHost + composable
+```kotlin
+@Composable
+fun AppNav(nav: NavHostController) {
+    NavHost(navController = nav, startDestination = HomeRoute) {
+        composable<HomeRoute> {
+            HomeScreen(onUserClick = { id -> nav.navigate(ProfileRoute(id)) })
+        }
+        composable<ProfileRoute> { entry ->
+            val args = entry.toRoute<ProfileRoute>()
+            ProfileScreen(userId = args.userId, onBack = { nav.popBackStack() })
+        }
+        composable<OrderRoute> { entry ->
+            val args = entry.toRoute<OrderRoute>()
+            OrderScreen(args.orderId, args.highlight)
+        }
+    }
+}
+```
+
+### ViewModel 자동 인자 주입
+```kotlin
+@HiltViewModel
+class ProfileViewModel @Inject constructor(
+    savedState: SavedStateHandle,
+    private val repo: UserRepo,
+) : ViewModel() {
+    private val args: ProfileRoute = savedState.toRoute()
+    val userFlow = repo.observe(args.userId)
+}
+```
+
+### Nested graph (모듈)
+```kotlin
+fun NavGraphBuilder.authGraph(nav: NavController) {
+    navigation<AuthGraph>(startDestination = LoginRoute) {
+        composable<LoginRoute> { LoginScreen(onSuccess = { nav.navigate(HomeRoute) { popUpTo<AuthGraph> { inclusive = true } } }) }
+        composable<SignupRoute> { SignupScreen() }
+    }
+}
+
+@Serializable data object AuthGraph
+@Serializable data object LoginRoute
+@Serializable data object SignupRoute
+```
+
+### Deep link
+```kotlin
+composable<OrderRoute>(
+    deepLinks = listOf(navDeepLink<OrderRoute>(basePath = "https://example.com/orders"))
+) { ... }
+```
+
+URL `https://example.com/orders/123?highlight=true` → OrderRoute(orderId="123", highlight=true).
+
+### Pop / 백스택 관리
+```kotlin
+nav.navigate(HomeRoute) {
+    popUpTo<AuthGraph> { inclusive = true } // login graph 모두 pop
+    launchSingleTop = true                   // 같은 destination 재진입 안 함
+}
+
+nav.popBackStack()
+nav.popBackStack(route = HomeRoute, inclusive = false) // 특정 destination 까지 pop
+```
+
+## 🤔 의사결정 기준
+| 상황 | 권장 |
+|---|---|
+| 신규 Android Compose | navigation-compose 2.8+ + 타입 안전 routes |
+| 큰 앱 모듈화 | nested graph per feature module |
+| Deep link / 외부 호출 | deepLinks block |
+| Multi-platform (KMM) | Decompose / Voyager |
+| Tab + per-tab back stack | rememberNavController 별 또는 BottomNav + saveState |
+
+## ❌ 안티패턴
+- **String route + manual encoding**: 옛 패턴. 2.8+ 의 typed routes.
+- **모든 destination 한 NavGraphBuilder**: 거대 파일. nested graph 로 모듈 분리.
+- **navigate 후 popBackStack 잊음**: 백스택 누적.
+- **ViewModel 에 NavController 주입**: lifecycle 불일치 + 테스트 어려움. Composable 에서 callback.
+- **Activity 가 NavController 보유 + Fragment 가 별도**: 동기화 깨짐.
+- **deeplink path 안에 user id**: 인증 안 된 사용자가 직접 호출 → 권한 검증 필수.
+- **animation 무시**: 기본 fade 만 — UX 평범. enterTransition / exitTransition.
+
+## 🤖 LLM 활용 힌트
+- @Serializable data class destination + composable<Route> + entry.toRoute().
+- ViewModel 은 SavedStateHandle.toRoute() 로 인자.
+
+## 🔗 관련 문서
+- [[Android_Compose_State_Hoisting]]
+- [[Android_Modularization]]