feat(receiver,setting): 수신자 등록에 카카오톡 초대 발급·수락 흐름을 잇는다 (#944)

app/src/main/AndroidManifest.xml

@@ -97,6 +97,21 @@
 
                 <category android:name="android.intent.category.LAUNCHER" />
             </intent-filter>
+            <!--
+              카카오톡 초대 메시지의 버튼이 앱을 여는 스킴 — `kakao{앱키}://kakaolink?inviteToken=…` (#944).
+              host 가 `kakaolink` 라 같은 스킴의 `oauth`(AuthCodeHandlerActivity)와 갈린다.
+              launchMode 는 그대로 둔다 — #1111 이 알림 진입에서 같은 판단을 했다(manifest 를 올리면
+              모든 진입의 태스크 동작이 바뀐다). 앱이 떠 있는 채로 들어오면 인스턴스가 하나 더 쌓일 수
+              있지만, 토큰은 기기 저장소에 남기고 어느 인스턴스든 그 저장소를 보므로 흐름은 같다.
+            -->
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data
+                        android:host="kakaolink"
+                        android:scheme="kakao${KAKAO_NATIVE_APP_KEY}" />
+            </intent-filter>
         </activity>
 
         <!--

app/src/main/java/com/afternote/afternote_fe/MainActivity.kt

@@ -9,6 +9,7 @@ import androidx.core.net.toUri
 import androidx.core.splashscreen.SplashScreen.Companion.installSplashScreen
 import androidx.fragment.app.FragmentActivity
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import com.afternote.afternote_fe.invitation.ReceiverInvitationIntentContract
 import com.afternote.afternote_fe.navigation.AppNavigation
 import com.afternote.afternote_fe.notification.NotificationIntentContract
 import com.afternote.afternote_fe.update.ForceUpdateGate
@@ -41,6 +42,7 @@ class MainActivity : FragmentActivity() {
         enableLightEdgeToEdge()
 
         enqueueNotificationIntent(intent)
+        enqueueInvitationIntent(intent)
 
         if (BuildConfig.DEBUG && intent.getBooleanExtra(EXTRA_DEBUG_START_TIMELETTER, false)) {
             setContent {
@@ -60,7 +62,10 @@ class MainActivity : FragmentActivity() {
             AfternoteTheme {
                 val startRoute by viewModel.startRoute.collectAsStateWithLifecycle()
                 startRoute?.let { route ->
-                    AppNavigation(startDestination = route)
+                    AppNavigation(
+                        startDestination = route,
+                        mainViewModel = viewModel,
+                    )
                 }
                 val forceUpdatePrompt by forceUpdateGate.prompt.collectAsStateWithLifecycle()
                 forceUpdatePrompt?.let { prompt ->
@@ -88,6 +93,18 @@ class MainActivity : FragmentActivity() {
         super.onNewIntent(intent)
         setIntent(intent)
         enqueueNotificationIntent(intent)
+        enqueueInvitationIntent(intent)
+    }
+
+    /**
+     * 카카오톡 초대 링크 진입 (#944). 토큰은 기기 저장소에 남기고, 띄울지는 앱 루트가 인증 상태와
+     * 함께 판정한다. 같은 Intent 가 재생성으로 다시 와도 같은 토큰을 다시 쓰는 것이라 재처리 방지가
+     * 따로 필요 없다 — 처분 기록은 [MainViewModel] 이 SavedState 로 갖는다.
+     */
+    private fun enqueueInvitationIntent(intent: Intent) {
+        ReceiverInvitationIntentContract
+            .fromIntent(intent)
+            ?.let(viewModel::enqueueInvitationToken)
     }
 
     private fun enqueueNotificationIntent(intent: Intent) {

app/src/main/java/com/afternote/afternote_fe/MainViewModel.kt

@@ -4,22 +4,26 @@ import androidx.lifecycle.SavedStateHandle
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.afternote.afternote_fe.notification.NotificationEntryRequest
+import com.afternote.core.domain.repository.PendingReceiverInvitationStore
 import com.afternote.core.domain.repository.auth.AuthRepository
 import com.afternote.core.ui.Route
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.SharingStarted
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.flow.combine
 import kotlinx.coroutines.flow.map
 import kotlinx.coroutines.flow.stateIn
+import kotlinx.coroutines.launch
 import javax.inject.Inject
 
 @HiltViewModel
 class MainViewModel
     @Inject
     constructor(
         authRepository: AuthRepository,
+        private val pendingInvitationStore: PendingReceiverInvitationStore,
         private val savedStateHandle: SavedStateHandle,
     ) : ViewModel() {
         private val pendingNotificationEntryState = MutableStateFlow<NotificationEntryRequest?>(null)
@@ -28,20 +32,83 @@ class MainViewModel
         internal val pendingNotificationEntry: StateFlow<NotificationEntryRequest?> =
             pendingNotificationEntryState.asStateFlow()
 
+        private val isLoggedIn: StateFlow<Boolean?> =
+            authRepository.isLoggedIn.stateIn(
+                scope = viewModelScope,
+                started = SharingStarted.WhileSubscribed(5_000),
+                initialValue = null,
+            )
+
         /**
          * 초기 진입 시 null(로딩)이며, [AuthRepository.isLoggedIn]이 방출된 뒤 목적지가 확정된다.
          * null 여부가 기존 `isLoading`과 동일한 역할을 한다.
          */
         val startRoute: StateFlow<Route?> =
-            authRepository.isLoggedIn
-                .map { isLoggedIn ->
-                    if (isLoggedIn) Route.Home else Route.Onboarding
+            isLoggedIn
+                .map { loggedIn ->
+                    when (loggedIn) {
+                        null -> null
+                        true -> Route.Home
+                        false -> Route.Onboarding
+                    }
                 }.stateIn(
                     scope = viewModelScope,
                     started = SharingStarted.WhileSubscribed(5_000),
                     initialValue = null,
                 )
 
+        /**
+         * 이 Activity 안에서 처분(수락·보류·거절)이 끝난 초대 토큰 — 다시 띄우지 않는다 (#944).
+         * SavedState 에 두어 재생성 뒤에도 같은 토큰으로 랜딩이 또 뜨지 않는다.
+         */
+        private val settledInvitationToken: StateFlow<String?> =
+            savedStateHandle.getStateFlow(SETTLED_INVITATION_TOKEN_KEY, null)
+
+        /** 로그인 뒤 다시 띄우기로 한 토큰 — 랜딩에서 «수락» 을 눌렀는데 로그인 전이었던 경우. */
+        private val invitationAwaitingLogin: StateFlow<String?> =
+            savedStateHandle.getStateFlow(INVITATION_AWAITING_LOGIN_KEY, null)
+
+        /**
+         * 지금 랜딩을 띄워야 하는 초대 토큰. null 이면 띄울 것이 없다.
+         *
+         * 보관 토큰이 있고, 이 Activity 에서 아직 처분되지 않았으며, 로그인 대기로 미뤄 둔 토큰이면
+         * 로그인이 확정된 뒤에만 값을 낸다. 로그인 여부는 [startRoute] 와 같은 스트림을 본다 —
+         * 앱 루트의 인증 경계를 그대로 재사용한다.
+         */
+        val pendingInvitationToken: StateFlow<String?> =
+            combine(
+                pendingInvitationStore.pendingToken,
+                isLoggedIn,
+                settledInvitationToken,
+                invitationAwaitingLogin,
+            ) { token, loggedIn, settled, awaitingLogin ->
+                when {
+                    token == null || loggedIn == null -> null
+                    token == settled -> null
+                    token == awaitingLogin && !loggedIn -> null
+                    else -> token
+                }
+            }.stateIn(
+                scope = viewModelScope,
+                started = SharingStarted.WhileSubscribed(5_000),
+                initialValue = null,
+            )
+
+        /** 스킴 Intent 에서 뽑은 토큰을 보관한다. 같은 Intent 가 재생성으로 다시 와도 같은 값이라 무해하다. */
+        internal fun enqueueInvitationToken(token: String) {
+            viewModelScope.launch { pendingInvitationStore.save(token) }
+        }
+
+        /** 랜딩에서 로그인이 필요하다고 판정됐다 — 로그인이 끝날 때까지 이 토큰의 랜딩을 미룬다. */
+        internal fun deferInvitationUntilLogin(token: String) {
+            savedStateHandle[INVITATION_AWAITING_LOGIN_KEY] = token
+        }
+
+        /** 랜딩이 닫혔다(수락 완료·나중에·거절 안내 확인). 이 Activity 에서 이 토큰으로는 다시 띄우지 않는다. */
+        internal fun settleInvitation(token: String) {
+            savedStateHandle[SETTLED_INVITATION_TOKEN_KEY] = token
+        }
+
         /**
          * 새 알림 발생을 큐에 넣는다. Activity 재생성 때 같은 initial Intent가 다시 전달되더라도
          * [SavedStateHandle]에 기록한 마지막 소비 identity면 다시 수신 이벤트를 만들지 않는다.
@@ -65,5 +132,7 @@ class MainViewModel
 
         private companion object {
             const val CONSUMED_NOTIFICATION_IDENTITY_KEY = "consumed_notification_entry_identity"
+            const val SETTLED_INVITATION_TOKEN_KEY = "settled_receiver_invitation_token"
+            const val INVITATION_AWAITING_LOGIN_KEY = "receiver_invitation_awaiting_login"
         }
     }

app/src/main/java/com/afternote/afternote_fe/invitation/ReceiverInvitationIntentContract.kt

@@ -0,0 +1,42 @@
+package com.afternote.afternote_fe.invitation
+
+import android.content.Intent
+
+/**
+ * 카카오톡 초대 메시지 버튼이 여는 `kakao{앱키}://kakaolink?inviteToken=…` Intent 를 해석한다 (#944).
+ *
+ * `NotificationIntentContract` 처럼 순수 객체다 — 판정 규칙은 [resolve] 하나에 모여 있고,
+ * `MainActivity` 는 [fromIntent] 만 부른다.
+ *
+ * 토큰은 서버가 발급한 43자 base64url 이다. 형식 밖 값은 우리가 만든 링크가 아니므로 저장하지 않는다 —
+ * 스킴은 누구나 던질 수 있어 검증 없이 보관하면 임의 문자열이 서버 경로 세그먼트까지 흘러간다.
+ */
+internal object ReceiverInvitationIntentContract {
+    fun fromIntent(intent: Intent): String? {
+        val data = runCatching { intent.data }.getOrNull() ?: return null
+        return resolve(
+            scheme = data.scheme,
+            host = data.host,
+            rawToken = runCatching { data.getQueryParameter(QUERY_INVITE_TOKEN) }.getOrNull(),
+        )
+    }
+
+    private fun resolve(
+        scheme: String?,
+        host: String?,
+        rawToken: String?,
+    ): String? {
+        if (scheme == null || !scheme.startsWith(SCHEME_PREFIX)) return null
+        if (host != HOST_KAKAOLINK) return null
+        val token = rawToken?.takeIf { TOKEN_FORMAT.matches(it) } ?: return null
+        return token
+    }
+
+    /** 카카오 네이티브 앱 키를 붙인 스킴 — 키 값 자체는 매니페스트 플레이스홀더가 맞춘다. */
+    private const val SCHEME_PREFIX = "kakao"
+    private const val HOST_KAKAOLINK = "kakaolink"
+    private const val QUERY_INVITE_TOKEN = "inviteToken"
+
+    /** base64url 문자만, 길이 상한 128 — 서버 발급 길이(43)의 여유분이지 계약값은 아니다. */
+    private val TOKEN_FORMAT = Regex("^[A-Za-z0-9_-]{1,128}$")
+}

app/src/main/java/com/afternote/afternote_fe/navigation/AppNavigation.kt

@@ -10,6 +10,7 @@ import androidx.compose.material3.Scaffold
 import androidx.compose.material3.SnackbarHost
 import androidx.compose.material3.SnackbarHostState
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
@@ -21,9 +22,11 @@ import androidx.hilt.lifecycle.viewmodel.compose.hiltViewModel
 import androidx.lifecycle.Lifecycle
 import androidx.lifecycle.compose.LifecycleEventEffect
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import androidx.navigation.NavDestination.Companion.hasRoute
 import androidx.navigation.compose.NavHost
 import androidx.navigation.compose.composable
 import androidx.navigation.compose.currentBackStackEntryAsState
+import com.afternote.afternote_fe.MainViewModel
 import com.afternote.afternote_fe.notification.NotificationPermissionEffect
 import com.afternote.core.ui.Route
 import com.afternote.core.ui.bottombar.BottomBar
@@ -38,20 +41,44 @@ import com.afternote.feature.home.presentation.HomeTabViewModel
 import com.afternote.feature.home.presentation.receiver.ReceiverHomeEntry
 import com.afternote.feature.mindrecord.presentation.navigation.mindRecordNavGraph
 import com.afternote.feature.onboarding.presentation.navigation.OnboardingNavHost
+import com.afternote.feature.receiver.presentation.navigation.ReceiverInvitationNavHost
 import com.afternote.feature.receiver.presentation.navigation.ReceiverNavHost
 import com.afternote.feature.setting.presentation.navigation.settingNavGraph
 import com.afternote.feature.timeletter.presentation.navigation.timeLetterNavGraph
 import kotlinx.coroutines.launch
 
 @Composable
-fun AppNavigation(
+internal fun AppNavigation(
     startDestination: Route,
     modifier: Modifier = Modifier,
     appState: AppState = rememberAfternoteAppState(),
+    mainViewModel: MainViewModel = hiltViewModel(),
 ) {
     val navEntry by appState.navController.currentBackStackEntryAsState()
     val currentDestination = navEntry?.destination
 
+    // 카카오톡 초대 링크로 들어온 토큰이 있으면 지금 화면 위에 랜딩을 올린다 (#944). 로그인 전이면
+    // 온보딩 위, 로그인 뒤면 홈 위다. 로그인이 끝나 온보딩이 홈으로 갈아치워지면 destination 키가
+    // 바뀌어 다시 판정하고, 처분이 끝난 토큰은 ViewModel 이 null 로 내려 다시 뜨지 않는다.
+    val pendingInvitationToken by mainViewModel.pendingInvitationToken.collectAsStateWithLifecycle()
+    val authenticatedStartRoute by mainViewModel.startRoute.collectAsStateWithLifecycle()
+    val isOnInvitation = currentDestination?.hasRoute(Route.ReceiverInvitation::class) == true
+    LaunchedEffect(pendingInvitationToken, currentDestination?.id) {
+        if (pendingInvitationToken != null && currentDestination != null && !isOnInvitation) {
+            appState.navController.navigate(Route.ReceiverInvitation) { launchSingleTop = true }
+        }
+    }
+    val receiverInvitationExternalActions =
+        rememberReceiverInvitationExternalActions(
+            appState = appState,
+            onSettled = {
+                pendingInvitationToken?.let(mainViewModel::settleInvitation)
+            },
+            onDeferredUntilLogin = {
+                pendingInvitationToken?.let(mainViewModel::deferInvitationUntilLogin)
+            },
+        )
+
     // 로컬 Nav3 스택의 깊이는 Nav2 destination 에 안 보인다 — 애프터노트 host 가 올려 주는 신호를
     // 바텀바 판정에 합성한다. 피처를 떠나면 host 가 true 로 되돌려 다른 탭 판정을 오염시키지 않는다.
     var isAfternoteStackAtRoot by remember { mutableStateOf(true) }
@@ -134,6 +161,14 @@ fun AppNavigation(
                     navigationCallbacks = rootNavigationCallbacks,
                 )
             }
+            composable<Route.ReceiverInvitation> {
+                ReceiverInvitationNavHost(
+                    // 앱 루트의 인증 경계(startRoute)를 그대로 재사용한다 — 로그인 판정을 따로 두지 않는다.
+                    isLoggedIn = authenticatedStartRoute == Route.Home,
+                    boundary = rootNavigationCallbacks,
+                    externalActions = receiverInvitationExternalActions,
+                )
+            }
 
             // ── 아직 Navigation 2 인 그래프 — #1695 · #1696 · #1697 이 각각 이관한다.
             composable<Route.Home> {

app/src/main/java/com/afternote/afternote_fe/navigation/AppNavigationActions.kt

@@ -14,6 +14,7 @@ import com.afternote.feature.home.presentation.receiver.ReceiverHomeActions
 import com.afternote.feature.mindrecord.presentation.navigation.MindRecordNavActions
 import com.afternote.feature.mindrecord.presentation.navigation.MindRecordRoute
 import com.afternote.feature.onboarding.presentation.navigation.OnboardingExternalActions
+import com.afternote.feature.receiver.presentation.navigation.ReceiverInvitationExternalActions
 import com.afternote.feature.receiver.presentation.navigation.model.ReceiverRoute
 import com.afternote.feature.setting.presentation.navigation.SettingNavActions
 import com.afternote.feature.setting.presentation.navigation.SettingRoute
@@ -426,3 +427,42 @@ fun rememberReceiverHomeActions(appState: AppState): ReceiverHomeActions =
             onNavigateToAfternote = { appState.navController.navigate(Route.ReceivedAfternote) },
         )
     }
+
+/**
+ * 카카오톡 초대 랜딩 로컬 스택이 셸에 남긴 이동 (#944).
+ *
+ * 랜딩은 현재 화면 위에 push 된 것이라, 닫을 때는 pop 으로 원래 자리(온보딩 또는 홈)로 돌아간다.
+ *
+ * @param onSettled 이 토큰의 처분이 끝났다 — 같은 Activity 에서 다시 띄우지 않는다.
+ * @param onDeferredUntilLogin 로그인 전이라 미뤘다 — 로그인이 확정되면 다시 띄운다.
+ */
+@Composable
+fun rememberReceiverInvitationExternalActions(
+    appState: AppState,
+    onSettled: () -> Unit,
+    onDeferredUntilLogin: () -> Unit,
+): ReceiverInvitationExternalActions {
+    val onSettledState by rememberUpdatedState(onSettled)
+    val onDeferredState by rememberUpdatedState(onDeferredUntilLogin)
+    return remember(appState) {
+        object : ReceiverInvitationExternalActions {
+            override fun requestLogin() {
+                onDeferredState()
+                // 랜딩 아래는 온보딩이다(로그인 전이라 startDestination 이 Onboarding) — 내리면 Welcome 이 보인다.
+                appState.navController.popBackStack()
+            }
+
+            override fun openReceivedRecords() {
+                onSettledState()
+                appState.navController.navigate(Route.Receiver) {
+                    popUpTo<Route.ReceiverInvitation> { inclusive = true }
+                }
+            }
+
+            override fun close() {
+                onSettledState()
+                appState.navController.popBackStack()
+            }
+        }
+    }
+}