Feature/navigation3

.github/git-commit-instructions.md

@@ -0,0 +1,180 @@
+## 프로젝트 컨텍스트
+
+- **기술 스택**: Kotlin, Jetpack Compose, MVVM/MVI 아키텍처, Multi-module
+- **모듈 구조**:
+  - `feature/*`: 기능별 모듈 (home, cargo-detail, myinfo 등)
+  - `core/*`: 공통 모듈 (designsystem, data, domain, network 등)
+
+## 커밋 메시지 형식
+
+```
+타입: 간단한 제목 (한국어, 50자 이내)
+
+- 변경 사항 1 (구체적으로)
+- 변경 사항 2 (파일명 포함 권장)
+- 변경 사항 3 (왜 변경했는지 포함)
+```
+
+## 타입 정의
+
+변경사항을 분석하여 가장 적합한 타입 하나를 선택하세요:
+
+- **feat**: 새로운 기능 추가
+  - 예: 새로운 화면, 새로운 컴포넌트, 새로운 API 연동
+
+- **fix**: 버그 수정
+  - 예: 크래시 수정, 잘못된 로직 수정, UI 버그 수정
+
+- **refactor**: 코드 리팩토링 (기능 변경 없음)
+  - 예: 함수 분리, 변수명 변경, 구조 개선
+
+- **style**: UI/디자인 변경 (코드 스타일 X)
+  - 예: 색상 변경, 간격 조정, 폰트 수정
+
+- **test**: 테스트 코드 추가/수정
+  - 예: 단위 테스트, UI 테스트, Integration 테스트
+
+- **chore**: 빌드, 설정, 의존성 관련
+  - 예: Gradle 업데이트, 라이브러리 추가, CI/CD 설정
+
+## 작성 규칙
+
+### 1. 제목 작성
+- 한국어로 작성
+- 50자 이내로 간결하게
+- 마침표 없이 명령형으로 작성
+- 무엇을 했는지 명확하게
+
+### 2. 본문 작성
+- 각 항목은 `-`로 시작
+- 구체적인 파일명이나 컴포넌트명 포함
+- 변경 이유나 맥락 포함 (필요시)
+- 모듈 경로 명시 (`feature/home`, `core/designsystem` 등)
+
+✅ 좋은 예:
+```
+- HomeScreenRedesign.kt: 사용자 정보 카드 컴포넌트 추가
+- CargoItemCard.kt: 화물 상태별 색상 구분 로직 구현
+- Figma 디자인(node-id: 1942-56177) 기반 레이아웃 적용
+- Material 3 디자인 시스템 적용
+```
+
+❌ 나쁜 예:
+```
+- 코드 수정
+- 파일 추가
+- 작업 완료
+```
+
+## 변경사항 분석 체크리스트
+
+커밋 메시지를 작성하기 전에 다음을 확인하세요:
+
+1. **어떤 파일이 변경되었는가?**
+   - 파일명과 경로 확인
+
+2. **무엇이 추가/수정/삭제되었는가?**
+   - 새로운 함수/클래스/컴포넌트
+   - 수정된 로직
+   - 삭제된 코드
+
+3. **왜 이 변경이 필요했는가?**
+   - 버그 수정
+   - 기능 추가
+   - 성능 개선
+   - 디자인 반영
+
+4. **이 변경의 영향 범위는?**
+   - 다른 모듈에 영향
+   - Breaking Change 여부
+   - 테스트 필요 여부
+
+## 실제 예시
+
+### 예시 1: 새 화면 추가
+```
+feat: 화물 상세 화면 추가
+
+- CargoDetailScreen.kt: 새 화면 구현
+- CargoDetailViewModel.kt: 상태 관리
+- CargoDetailUiState.kt: UI 상태 정의
+- 화물 정보, 차주 정보, 경로 정보 표시
+- 전화/문자 버튼 기능 구현
+- Navigation 연결 완료
+```
+
+### 예시 2: 버그 수정
+```
+fix: 화물 등록 시 날짜 선택 오류 수정
+
+- DatePicker.kt: 시간대 처리 로직 수정
+- LocalDateTime을 ZonedDateTime으로 변경
+- 서버와 시간대 불일치로 발생한 오류 해결
+- 테스트 케이스 추가: DatePickerTest.kt
+```
+
+### 예시 3: 리팩토링
+```
+refactor: Repository 레이어 분리 및 정리
+
+- CargoRepository.kt: Local/Remote 분리
+- CargoLocalDataSource.kt: 로컬 데이터 소스
+- CargoRemoteDataSource.kt: 리모트 데이터 소스
+- 단일 책임 원칙 적용
+- 테스트 용이성 개선
+```
+
+### 예시 4: UI 스타일 변경
+```
+style: 메인 홈 카드 디자인 수정
+
+- CargoItemCard.kt: 카드 스타일 조정
+- elevation 2dp → 4dp 변경
+- 모서리 반경 6dp → 8dp 변경
+- 그림자 색상 조정 (#000000 → #0000001A)
+- Figma 디자인과 일치하도록 수정
+```
+
+### 예시 5: 여러 타입의 변경
+가장 중요한 변경사항의 타입을 사용하세요:
+
+```
+feat: 로그인 화면 개선
+
+- LoginScreen.kt: UI 리디자인 (Figma 기반)
+- LoginViewModel.kt: 자동 로그인 기능 추가
+- PreferencesManager.kt: 로그인 상태 저장 로직
+- 버그 수정: 비밀번호 입력 시 키보드 숨김 처리
+```
+
+## 주의사항
+
+1. **하나의 커밋에는 하나의 논리적 변경만**
+   - 여러 기능을 한 커밋에 섞지 말 것
+   - 필요시 커밋을 분리
+
+2. **WIP(Work In Progress) 커밋 지양**
+   - 완전하지 않은 작업은 커밋하지 말 것
+   - 부득이한 경우 `[WIP]` 태그 사용
+
+3. **파일 경로는 프로젝트 이름 기준**
+   - ✅ `HomeScreen.kt`
+
+4. **민감 정보 포함 금지**
+   - API 키, 비밀번호, 개인정보 제외
+   - 환경 설정은 .env 파일 활용
+
+## 마지막 체크
+
+커밋하기 전 확인:
+- [ ] 타입이 명확한가?
+- [ ] 제목이 50자 이내인가?
+- [ ] 본문에 구체적인 내용이 있는가?
+- [ ] 파일명이나 컴포넌트명이 포함되었는가?
+- [ ] 변경 이유가 명확한가?
+- [ ] Breaking Change가 있다면 명시했는가?
+
+---
+
+이 가이드를 따라 일관성 있고 명확한 커밋 메시지를 작성하세요.
+

build-logic/src/main/kotlin/brake.android.feature.gradle.kts

@@ -32,9 +32,7 @@ dependencies {
 
     val libs = project.extensions.libs
     implementation(libs.findLibrary("hilt.navigation.compose").get())
-    implementation(libs.findLibrary("androidx.compose.navigation").get())
     implementation(libs.findLibrary("androidx.compose.material.icon").get())
-    androidTestImplementation(libs.findLibrary("androidx.compose.navigation.test").get())
 
     implementation(libs.findLibrary("androidx.lifecycle.viewModelCompose").get())
     implementation(libs.findLibrary("androidx.lifecycle.runtimeCompose").get())

core/navigation/build.gradle.kts

@@ -12,5 +12,6 @@ android {
 
 dependencies {
 	implementation(libs.kotlinx.serialization.json)
-	implementation(libs.androidx.compose.navigation)
+	api(libs.androidx.navigation3.runtime)
+	api(libs.androidx.navigation3.ui)
 }

core/navigation/src/main/java/com/teambrake/brake/core/navigation/action/NavigatorAction.kt

@@ -1,19 +1,19 @@
 package com.teambrake.brake.core.navigation.action
 
-import androidx.navigation.NavOptions
+import com.teambrake.brake.core.navigation.route.LaunchMode
 
 interface NavigatorAction {
-	fun popBackStack(navOptions: NavOptions? = null)
-	fun navigateToLogin(navOptions: NavOptions? = null)
-	fun navigateToSignup(navOptions: NavOptions? = null)
-	fun navigateToGuide(navOptions: NavOptions? = null)
-	fun navigateToPrivacy(navOptions: NavOptions? = null)
-	fun navigateToTerms(navOptions: NavOptions? = null)
-	fun navigateToComplete(navOptions: NavOptions? = null)
-	fun navigateToPermission(navOptions: NavOptions? = null)
-	fun navigateToHome(navOptions: NavOptions? = null)
-	fun navigateToRegistry(groupId: Long?, navOptions: NavOptions? = null)
-	fun navigateToNickname(navOptions: NavOptions? = null)
-	fun navigateToOpinion(navOptions: NavOptions? = null)
-	fun navigateToInquiry(navOptions: NavOptions? = null)
+	fun popBackStack()
+	fun navigateToLogin(launchMode: LaunchMode = LaunchMode.CLEAR_ALL)
+	fun navigateToSignup(launchMode: LaunchMode = LaunchMode.STANDARD)
+	fun navigateToGuide(launchMode: LaunchMode = LaunchMode.STANDARD)
+	fun navigateToPrivacy(launchMode: LaunchMode = LaunchMode.STANDARD)
+	fun navigateToTerms(launchMode: LaunchMode = LaunchMode.STANDARD)
+	fun navigateToComplete(launchMode: LaunchMode = LaunchMode.STANDARD)
+	fun navigateToPermission(launchMode: LaunchMode = LaunchMode.STANDARD)
+	fun navigateToHome(launchMode: LaunchMode = LaunchMode.CLEAR_ALL)
+	fun navigateToRegistry(groupId: Long? = null, launchMode: LaunchMode = LaunchMode.STANDARD)
+	fun navigateToNickname(launchMode: LaunchMode = LaunchMode.STANDARD)
+	fun navigateToOpinion(launchMode: LaunchMode = LaunchMode.STANDARD)
+	fun navigateToInquiry(launchMode: LaunchMode = LaunchMode.STANDARD)
 }

core/navigation/src/main/java/com/teambrake/brake/core/navigation/provider/NavigatorProvider.kt

@@ -1,8 +1,7 @@
 package com.teambrake.brake.core.navigation.provider
 
-import androidx.navigation.NavOptions
+import com.teambrake.brake.core.navigation.route.Route
 
 interface NavigatorProvider {
-	fun getNavOptionsClearingBackStack(): NavOptions
-	fun getPreviousDestination(): String
+	fun getPreviousDestination(): Route?
 }

core/navigation/src/main/java/com/teambrake/brake/core/navigation/route/LaunchMode.kt

@@ -0,0 +1,31 @@
+package com.teambrake.brake.core.navigation.route
+
+/**
+ * 네비게이션 시 백스택 관리 방식을 정의하는 LaunchMode
+ *
+ * Android의 launchMode와 유사한 개념으로 설계됨
+ */
+enum class LaunchMode {
+	/**
+	 * 항상 새로운 인스턴스를 백스택에 추가
+	 * 기본 동작
+	 */
+	STANDARD,
+
+	/**
+	 * 대상 Route가 이미 백스택의 최상단에 있으면 재사용
+	 * 그렇지 않으면 새로 추가
+	 */
+	SINGLE_TOP,
+
+	/**
+	 * 백스택에서 대상 Route를 찾아 그 위의 모든 Route를 제거
+	 * Route가 백스택에 없으면 새로 추가
+	 */
+	CLEAR_TOP,
+
+	/**
+	 * 백스택을 완전히 비우고 새로운 Route만 남김
+	 */
+	CLEAR_ALL,
+}

core/navigation/src/main/java/com/teambrake/brake/core/navigation/route/Route.kt

@@ -1,15 +1,5 @@
 package com.teambrake.brake.core.navigation.route
 
-import timber.log.Timber
+import androidx.navigation3.runtime.NavKey
 
-interface Route
-
-/**
- * 2025-08-03 기준
- * Jetpack Compose Type-Safe Navigation 내부에서 Route 타입을 문자열로 변환하는 방식과 동일한 변환 함수
- * Jetpack Compose Type-Safe Navigation 내부 변환 방식이 변경될 수 있음
- */
-fun Route.stringRoute(): String {
-	Timber.d("stringRoute: ${this::class.qualifiedName}")
-	return this::class.qualifiedName ?: ""
-}
+interface Route : NavKey

core/navigation/src/main/java/com/teambrake/brake/core/navigation/route/RouteStack.kt

@@ -0,0 +1,11 @@
+package com.teambrake.brake.core.navigation.route
+
+data class RouteStack(
+	val backStack: List<Route> = emptyList(),
+) {
+	val current: Route? = backStack.lastOrNull()
+
+	val previous: Route? = backStack.dropLast(1).lastOrNull()
+
+	constructor(startDestination: Route) : this(backStack = listOf(startDestination))
+}

core/navigation/src/main/java/com/teambrake/brake/core/navigation/route/SubRoute.kt

@@ -3,6 +3,7 @@ package com.teambrake.brake.core.navigation.route
 import kotlinx.serialization.Serializable
 
 interface SubRoute : Route {
+
 	@Serializable
 	data class Registry(val groupId: Long? = null) : SubRoute
 

gradle/libs.versions.toml

@@ -2,7 +2,7 @@
 ## SDK version
 compileSdk = "36"
 minSdk = "28"
-targetSdk = "35"
+targetSdk = "36"
 
 ## App version
 versionCode = "11"
@@ -182,6 +182,10 @@ material = "1.12.0"
 accompanistPermissions = "0.37.3"
 snapper = "0.3.0"
 
+# Navigation 3
+nav3Core = "1.0.1"
+lifecycleViewmodelNav3 = "2.10.0"
+
 [libraries]
 # Gradle
 android-gradlePlugin = { group = "com.android.tools.build", name = "gradle", version.ref = "agp" }
@@ -206,12 +210,15 @@ androidx-compose-ui-test = { group = "androidx.compose.ui", name = "ui-test-juni
 androidx-compose-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling" }
 androidx-compose-ui-tooling-preview = { group = "androidx.compose.ui", name = "ui-tooling-preview" }
 androidx-compose-ui-testManifest = { group = "androidx.compose.ui", name = "ui-test-manifest" }
-androidx-compose-navigation = { group = "androidx.navigation", name = "navigation-compose", version.ref = "androidxComposeNavigation" }
-androidx-compose-navigation-test = { group = "androidx.navigation", name = "navigation-testing", version.ref = "androidxComposeNavigation" }
 androidx-compose-material-icon = { module = "androidx.compose.material:material-icons-extended" }
 androidx-constraintlayout-compose = { group = "androidx.constraintlayout", name = "constraintlayout-compose", version.ref = "androidxComposeConstraintlayout" }
 compose-compiler-gradle-plugin = { module = "org.jetbrains.kotlin:compose-compiler-gradle-plugin", version.ref = "kotlin" }
 
+# Navigation 3
+androidx-navigation3-runtime = { module = "androidx.navigation3:navigation3-runtime", version.ref = "nav3Core" }
+androidx-navigation3-ui = { module = "androidx.navigation3:navigation3-ui", version.ref = "nav3Core" }
+androidx-lifecycle-viewmodel-navigation3 = { module = "androidx.lifecycle:lifecycle-viewmodel-navigation3", version.ref = "lifecycleViewmodelNav3" }
+
 # Credentials
 androidx-credentials = { group = "androidx.credentials", name = "credentials", version.ref = "androidxCredentials" }
 androidx-credentials-play-services-auth = { group = "androidx.credentials", name = "credentials-play-services-auth", version.ref = "androidxCredentials" }

presentation/home/src/main/java/com/teambrake/brake/presentation/home/HomeScreen.kt

@@ -20,7 +20,7 @@ import androidx.compose.runtime.remember
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.platform.LocalContext
 import androidx.core.content.ContextCompat
-import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.hilt.lifecycle.viewmodel.compose.hiltViewModel
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import com.teambrake.brake.core.designsystem.theme.LinerGradient
 import com.teambrake.brake.core.navigation.compositionlocal.LocalMainAction

presentation/home/src/main/java/com/teambrake/brake/presentation/home/navEntry/HomeNavEntry.kt

@@ -0,0 +1,13 @@
+package com.teambrake.brake.presentation.home.navEntry
+
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.navigation3.runtime.EntryProviderScope
+import androidx.navigation3.runtime.NavKey
+import com.teambrake.brake.core.navigation.route.MainTabRoute
+import com.teambrake.brake.presentation.home.HomeRoute
+
+fun EntryProviderScope<NavKey>.homeNavEntry(padding: PaddingValues) {
+	entry<MainTabRoute.Home> {
+		HomeRoute(padding = padding)
+	}
+}