[GAMSS-41] feat: Android 멀티모듈 기반 및 공통 아키텍처 구축

.github/workflows/ci.yml

@@ -47,6 +47,9 @@ jobs:
         with:
           validate-wrappers: true
 
+      - name: Write google-services.json
+        run: echo "${{ secrets.GOOGLE_SERVICES_JSON }}" | base64 -d > app/google-services.json
+
       - name: Run ${{ matrix.task }}
         run: ./gradlew ${{ matrix.task }} --stacktrace
 

.gitignore

@@ -3,6 +3,8 @@
 .idea/
 .kotlin/
 build/
+bin/
 local.properties
 */build/
 .worktree-*
+app/google-services.json

README.md

@@ -69,23 +69,31 @@ API 키 등 비밀 값이 필요한 경우에도 `local.properties`에 두고 
 
 ## 프로젝트 구조
 
-멀티모듈 구조로 구성한다. 세부 모듈 구성은 진행 상황에 따라 확정한다.
+멀티모듈 구조로 구성한다. 새 feature나 데이터 소스를 추가할 때도 아래 구조와 의존성 방향을 따른다.
 
 ```
 GAMSS-Android/
-├─ app/           # 앱 진입점, DI 구성, 네비게이션 호스트 (예정)
-├─ core/          # 공통 유틸, 디자인 시스템, 네트워크/DB 기반 (예정)
-├─ feature/       # 화면 단위 기능 모듈 (예정)
-├─ data/          # 데이터 소스, 저장소 구현 (예정)
-└─ gradle/        # 버전 카탈로그, wrapper
+├─ app/                # 앱 진입점, Hilt DI 그래프 조립, Navigation3 호스트
+├─ domain/             # UseCase, Repository 인터페이스, 도메인 모델 (순수 Kotlin/JVM, Android 의존성 없음)
+├─ data/                # Repository 구현체, 원격(remote)·로컬 데이터 소스, DI 모듈(di)
+├─ core/
+│   ├─ common/         # 모듈 간 공유되는 순수 유틸 (AppResult 등)
+│   └─ ui/             # 공용 Compose UI 컴포넌트 (GamssBottomBar 등)
+├─ feature/
+│   └─ home/           # 화면 단위 기능 모듈. 화면별로 하나씩 추가한다
+└─ gradle/             # 버전 카탈로그, wrapper
 ```
 
-| 모듈 | 역할 |
-| --- | --- |
-| `app` | 앱 진입점, DI 그래프 구성, 네비게이션 호스트 |
-| `core` | 여러 기능에서 공유하는 공통 코드 (UI 컴포넌트, 네트워크·DB 기반, 유틸) |
-| `feature` | 화면 단위 기능 모듈 (기능별로 분리) |
-| `data` | 데이터 소스 및 저장소(Repository) 구현 |
+| 모듈 | 역할 | 의존하는 모듈 |
+| --- | --- | --- |
+| `app` | 앱 진입점, Hilt DI 그래프 조립, Navigation3 호스트 | `domain`, `data`, `core:common`, `core:ui`, `feature:*` |
+| `domain` | UseCase, Repository 인터페이스, 도메인 모델 | 없음 |
+| `data` | Repository 구현, 원격/로컬 데이터 소스, Hilt DI 모듈 | `domain`, `core:common` |
+| `core:common` | 여러 모듈이 공유하는 순수 유틸 | 없음 |
+| `core:ui` | 공용 Compose UI 컴포넌트 | 없음 |
+| `feature:*` | 화면 단위 기능 모듈 (기능별로 분리) | `core:ui` (필요 시 `domain`) |
+
+**의존성 규칙**: 안쪽 레이어(`domain`)는 바깥쪽 어떤 모듈도 참조하지 않는다. `data`, `feature`, `app`은 `domain`이 정의한 인터페이스(Repository, UseCase)에 의존하고, 구현은 바깥쪽(`data`)에 둔다. `app`은 조립부이므로 예외적으로 전체 모듈을 참조한다.
 
 ## 기술 스택
 

app/build.gradle.kts

@@ -1,9 +1,13 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
 plugins {
     alias(libs.plugins.androidApplication)
     alias(libs.plugins.composeCompiler)
     alias(libs.plugins.kotlinSerialization)
     alias(libs.plugins.ksp)
     alias(libs.plugins.hilt)
+    alias(libs.plugins.googleServices)
+    alias(libs.plugins.firebaseCrashlytics)
 }
 
 android {
@@ -36,28 +40,39 @@ android {
 
 kotlin {
     compilerOptions {
-        jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
+        jvmTarget = JvmTarget.JVM_17
     }
 }
 
 dependencies {
-    implementation(projects.core)
+
     implementation(projects.domain)
     implementation(projects.data)
+    implementation(projects.core.common)
+    implementation(projects.core.ui)
+    implementation(projects.feature.home)
+    implementation(projects.feature.chat)
+    implementation(projects.feature.calendar)
 
     implementation(platform(libs.compose.bom))
     implementation(libs.compose.ui)
     implementation(libs.compose.ui.graphics)
     implementation(libs.compose.ui.tooling.preview)
     implementation(libs.compose.material3)
+    implementation(libs.compose.material.icons.core)
     implementation(libs.androidx.activity.compose)
     implementation(libs.androidx.lifecycle.runtime.ktx)
+    implementation(libs.androidx.lifecycle.viewmodel.navigation3)
 
     implementation(libs.navigation3.runtime)
     implementation(libs.navigation3.ui)
 
     implementation(libs.hilt.android)
     ksp(libs.hilt.compiler)
 
+    implementation(platform(libs.firebase.bom))
+    implementation(libs.firebase.crashlytics)
+    implementation(libs.firebase.analytics)
+
     debugImplementation(libs.compose.ui.tooling)
 }

app/src/main/kotlin/com/gamss/android/app/MainActivity.kt

@@ -4,7 +4,7 @@ import android.os.Bundle
 import androidx.activity.ComponentActivity
 import androidx.activity.compose.setContent
 import androidx.activity.enableEdgeToEdge
-import com.gamss.android.app.navigation.AppNavHost
+import com.gamss.android.app.navigation.GamssNavHost
 import com.gamss.android.app.ui.theme.GamssTheme
 import dagger.hilt.android.AndroidEntryPoint
 
@@ -15,7 +15,7 @@ class MainActivity : ComponentActivity() {
         enableEdgeToEdge()
         setContent {
             GamssTheme {
-                AppNavHost()
+                GamssNavHost()
             }
         }
     }

app/src/main/kotlin/com/gamss/android/app/navigation/GamssNavHost.kt

@@ -0,0 +1,53 @@
+package com.gamss.android.app.navigation
+
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.Scaffold
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Modifier
+import androidx.navigation3.runtime.entryProvider
+import androidx.navigation3.ui.NavDisplay
+import com.gamss.android.core.ui.GamssBottomBar
+import com.gamss.android.feature.calendar.CalendarScreen
+import com.gamss.android.feature.calendar.navigation.CalendarKey
+import com.gamss.android.feature.chat.ChattingListScreen
+import com.gamss.android.feature.chat.navigation.ChatKey
+import com.gamss.android.feature.home.HomeScreen
+import com.gamss.android.feature.home.navigation.HomeKey
+
+@Composable
+fun GamssNavHost() {
+    val navigationState = rememberNavigationState(
+        startKey = HomeKey,
+        topLevelKeys = topLevelDestinationKeys,
+    )
+    val navigator = remember(navigationState) { Navigator(navigationState) }
+
+    Scaffold(
+        bottomBar = {
+            if (navigationState.currentKey == navigationState.currentTopLevelKey) {
+                GamssBottomBar(
+                    items = topLevelBottomBarItems,
+                    selectedValue = navigationState.currentTopLevelKey,
+                    onItemClick = navigator::navigate,
+                )
+            }
+        },
+    ) { innerPadding ->
+        NavDisplay(
+            modifier = Modifier.padding(innerPadding),
+            entries = navigationState.toEntries(
+                entryProvider = entryProvider {
+                    entry<HomeKey> { HomeScreen() }
+                    entry<ChatKey> { ChattingListScreen() }
+                    entry<CalendarKey> { CalendarScreen() }
+                },
+            ),
+            onBack = {
+                if (navigationState.canGoBack) {
+                    navigator.goBack()
+                }
+            },
+        )
+    }
+}

app/src/main/kotlin/com/gamss/android/app/navigation/NavigationState.kt

@@ -0,0 +1,90 @@
+package com.gamss.android.app.navigation
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.derivedStateOf
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.remember
+import androidx.lifecycle.viewmodel.navigation3.rememberViewModelStoreNavEntryDecorator
+import androidx.navigation3.runtime.NavBackStack
+import androidx.navigation3.runtime.NavEntry
+import androidx.navigation3.runtime.NavKey
+import androidx.navigation3.runtime.rememberDecoratedNavEntries
+import androidx.navigation3.runtime.rememberNavBackStack
+import androidx.navigation3.runtime.rememberSaveableStateHolderNavEntryDecorator
+
+/**
+ * GAMSS 메인 탭 네비게이션 상태를 생성한다.
+ *
+ * Navigation3의 back stack은 rememberSaveable 기반으로 동작하므로 화면 회전이나
+ * 프로세스 재생성 이후에도 복원 가능한 key를 사용해야 한다.
+ *
+ * @param startKey 앱의 메인 영역에서 처음 보여줄 최상위 key
+ * @param topLevelKeys bottom bar에 연결되는 최상위 key 목록
+ */
+@Composable
+fun rememberNavigationState(
+    startKey: NavKey,
+    topLevelKeys: Set<NavKey>,
+): NavigationState {
+    val topLevelStack = rememberNavBackStack(startKey)
+    val subStacks = topLevelKeys.associateWith { key -> rememberNavBackStack(key) }
+
+    return remember(startKey, topLevelKeys) {
+        NavigationState(
+            startKey = startKey,
+            topLevelStack = topLevelStack,
+            subStacks = subStacks,
+        )
+    }
+}
+
+/**
+ * bottom bar 기반 화면 전환을 위한 상태 홀더.
+ *
+ * topLevelStack은 사용자가 방문한 탭 순서를 저장하고, subStacks는 각 탭 내부의 상세 화면
+ * stack을 따로 저장한다. 탭을 전환해도 탭의 상세 화면 흐름을 유지할 수 있다.
+ */
+class NavigationState(
+    val startKey: NavKey,
+    val topLevelStack: NavBackStack<NavKey>,
+    val subStacks: Map<NavKey, NavBackStack<NavKey>>,
+) {
+    val currentTopLevelKey: NavKey by derivedStateOf { topLevelStack.last() }
+
+    val topLevelKeys
+        get() = subStacks.keys
+
+    val currentSubStack: NavBackStack<NavKey>
+        get() = subStacks[currentTopLevelKey]
+            ?: error("현재 탭($currentTopLevelKey)에 해당하는 back stack이 없습니다.")
+
+    val currentKey: NavKey by derivedStateOf { currentSubStack.last() }
+
+    val canGoBack: Boolean by derivedStateOf { currentKey != startKey }
+}
+
+/**
+ * NavigationState를 NavDisplay에서 사용할 entry 목록으로 변환한다.
+ *
+ * 각 탭의 sub stack에 saveable state와 ViewModelStore decorator를 붙여서, 탭 전환 중에도
+ * 화면 상태와 ViewModel 생명주기가 탭별 back stack에 맞게 유지되도록 한다.
+ */
+@Composable
+fun NavigationState.toEntries(
+    entryProvider: (NavKey) -> NavEntry<NavKey>,
+): List<NavEntry<NavKey>> {
+    val decoratedEntries = subStacks.mapValues { (_, stack) ->
+        val decorators = listOf(
+            rememberSaveableStateHolderNavEntryDecorator<NavKey>(),
+            rememberViewModelStoreNavEntryDecorator<NavKey>(),
+        )
+        rememberDecoratedNavEntries(
+            backStack = stack,
+            entryDecorators = decorators,
+            entryProvider = entryProvider,
+        )
+    }
+
+    return topLevelStack
+        .flatMap { decoratedEntries[it] ?: emptyList() }
+}

app/src/main/kotlin/com/gamss/android/app/navigation/Navigator.kt

@@ -0,0 +1,75 @@
+package com.gamss.android.app.navigation
+
+import androidx.navigation3.runtime.NavKey
+
+/**
+ * NavigationState를 변경하는 앱 전용 navigator.
+ *
+ * GAMSS의 bottom bar 정책을 한 곳에 모아둔다.
+ * - 현재 탭을 다시 선택하면 해당 탭의 root 화면으로 이동
+ * - 다른 탭을 선택하면 방문한 탭 순서를 topLevelStack에 기록
+ * - 상세 화면은 현재 탭의 sub stack에 쌓되, 같은 key가 이미 있으면 마지막으로 이동
+ */
+class Navigator(val state: NavigationState) {
+
+    /**
+     * 지정한 key로 이동한다.
+     * top-level key인지, 현재 탭인지, 상세 key인지에 따라 stack 갱신 규칙이 달라진다.
+     */
+    fun navigate(key: NavKey) {
+        when (key) {
+            state.currentTopLevelKey -> clearSubStack()
+            in state.topLevelKeys -> goToTopLevel(key)
+            else -> goToKey(key)
+        }
+    }
+
+    /**
+     * 현재 위치에서 뒤로 이동한다.
+     *
+     * 현재 탭의 root 화면에서는 이전에 방문한 탭으로 돌아가고, 상세 화면에서는 현재 탭의
+     * sub stack에서 한 단계 pop한다.
+     */
+    fun goBack() {
+        when (state.currentKey) {
+            state.startKey -> Unit
+            state.currentTopLevelKey -> {
+                state.topLevelStack.removeLastOrNull()
+            }
+            else -> state.currentSubStack.removeLastOrNull()
+        }
+    }
+
+    /**
+     * 현재 탭의 상세 화면으로 이동한다.
+     */
+    private fun goToKey(key: NavKey) {
+        state.currentSubStack.apply {
+            remove(key)
+            add(key)
+        }
+    }
+
+    /**
+     * 다른 top-level 탭으로 이동한다.
+     */
+    private fun goToTopLevel(key: NavKey) {
+        state.topLevelStack.apply {
+            if (key == state.startKey) {
+                clear()
+            } else {
+                remove(key)
+            }
+            add(key)
+        }
+    }
+
+    /**
+     * 현재 탭을 다시 선택했을 때 root 화면만 남긴다.
+     */
+    private fun clearSubStack() {
+        state.currentSubStack.run {
+            if (size > 1) subList(1, size).clear()
+        }
+    }
+}