Keepiluv · chanho0908 · May 30, 2026 · May 13, 2026 · May 13, 2026 · May 13, 2026
diff --git a/.gitignore b/.gitignore
@@ -92,3 +92,7 @@ lint/tmp/
 /public/.well-known
 .firebase/
 .claude
+.codex
+.agents
+AGENTS.md
+CLAUDE.md
diff --git a/core/result/src/main/java/com/twix/result/Extension.kt b/core/result/src/main/java/com/twix/result/Extension.kt
@@ -0,0 +1,7 @@
+package com.twix.result
+
+fun <T> AppResult<T>.errorOrNull() =
+    when (this) {
+        is AppResult.Error -> error
+        is AppResult.Success -> null
+    }
diff --git a/core/ui/src/main/java/com/twix/ui/base/BaseViewModel.kt b/core/ui/src/main/java/com/twix/ui/base/BaseViewModel.kt
@@ -86,13 +86,13 @@ abstract class BaseViewModel<S : State, I : Intent, SE : SideEffect>(
     /**
      * 서버 통신 메서드 호출 및 응답을 처리하는 헬퍼 메서드
      *
-     * LoadableState를 구현한 경우 자동으로 isLoading과 error를 업데이트한다.
+     * DefaultLoadableState를 구현한 경우 자동으로 isLoading과 error를 업데이트한다.
      * 일반 State를 구현한 경우 onStart/onFinally로 화면별 로딩 상태를 직접 관리해야 한다.
      *
      * ## 에러 처리 가이드라인
      *
      * ### 1. 데이터 로딩 (초기 로드, 화면 진입 시)
-     * - LoadableState 구현 시 자동으로 error 상태 업데이트
+     * - DefaultLoadableState 구현 시 자동으로 error 상태 업데이트
      * - `onError = null` 또는 추가 로직만 처리
      * - 사용 예: 화면 진입 시 데이터 fetch, 리스트 초기 로드
      *
@@ -140,43 +140,58 @@ abstract class BaseViewModel<S : State, I : Intent, SE : SideEffect>(
 
     /**
      * 에러 초기화
-     * LoadableState를 구현한 경우 자동으로 error를 null로 업데이트
+     * DefaultLoadableState를 구현한 경우 자동으로 error를 null로 업데이트
      */
     private fun clearError() {
-        if (currentState is LoadableState) {
-            reduce { (this as LoadableState).copyLoadableState(error = null) as S }
-        }
+        reduceLoadableState { copyState(error = null) }
     }
 
     /**
      * 로딩 상태 시작
-     * LoadableState를 구현한 경우 자동으로 isLoading을 true로 업데이트
+     * DefaultLoadableState를 구현한 경우 자동으로 isLoading을 true로 업데이트
      */
     private fun startLoading() {
         loadingCount.update { it + 1 }
-        if (currentState is LoadableState && loadingCount.value == 1) {
-            reduce { (this as LoadableState).copyLoadableState(isLoading = true) as S }
+        if (loadingCount.value == 1) {
+            reduceLoadableState { copyState(isLoading = true) }
         }
     }
 
     /**
      * 로딩 상태 종료
-     * LoadableState를 구현한 경우 자동으로 isLoading을 false로 업데이트
+     * DefaultLoadableState를 구현한 경우 자동으로 isLoading을 false로 업데이트
      */
     private fun stopLoading() {
         loadingCount.update { maxOf(0, it - 1) }
-        if (currentState is LoadableState && loadingCount.value == 0) {
-            reduce { (this as LoadableState).copyLoadableState(isLoading = false) as S }
+        if (loadingCount.value == 0) {
+            reduceLoadableState { copyState(isLoading = false) }
         }
     }
 
     /**
      * 에러 업데이트
-     * LoadableState를 구현한 경우 자동으로 error를 업데이트
+     * DefaultLoadableState를 구현한 경우 자동으로 error를 업데이트
      */
     private fun updateError(error: AppError) {
-        if (currentState is LoadableState) {
-            reduce { (this as LoadableState).copyLoadableState(error = error) as S }
+        reduceLoadableState { copyState(error = error) }
+    }
+
+    /**
+     * AppResult를 loading/error 상태 변경 없이 처리한다.
+     *
+     * best effort 요청처럼 DefaultLoadableState를 변경하지 않아야 하는 경우 사용한다.
+     */
+    protected suspend fun <D> handleResultWithoutLoadableStateUpdate(
+        result: AppResult<D>,
+        onSuccess: (D) -> Unit = {},
+        onError: (suspend (AppError) -> Unit)? = null,
+    ) {
+        when (result) {
+            is AppResult.Success -> onSuccess(result.data)
+            is AppResult.Error -> {
+                handleError(result.error)
+                onError?.invoke(result.error)
+            }
         }
     }
 
@@ -191,7 +206,7 @@ abstract class BaseViewModel<S : State, I : Intent, SE : SideEffect>(
         when (result) {
             is AppResult.Success -> onSuccess(result.data)
             is AppResult.Error -> {
-                // 공통 처리: 로깅 및 LoadableState 에러 업데이트
+                // 공통 처리: 로깅 및 DefaultLoadableState 에러 업데이트
                 handleError(result.error)
                 updateError(result.error)
                 // 메서드별 처리: 특정 화면만의 UX ex) 다이얼로그/토스트
@@ -200,6 +215,16 @@ abstract class BaseViewModel<S : State, I : Intent, SE : SideEffect>(
         }
     }
 
+    private inline fun reduceLoadableState(crossinline reducer: DefaultLoadableState.() -> DefaultLoadableState) {
+        if (currentState !is DefaultLoadableState) return
+
+        reduce {
+            val loadableState = this as? DefaultLoadableState ?: return@reduce this
+            @Suppress("UNCHECKED_CAST")
+            loadableState.reducer() as S
+        }
+    }
+
     /**
      * Throwable용 핸들러 ex) Intent 처리 중 발생한 예외
      * */

diff --git a/core/ui/src/main/java/com/twix/ui/base/ContentLoadableState.kt b/core/ui/src/main/java/com/twix/ui/base/ContentLoadableState.kt
@@ -0,0 +1,29 @@
+package com.twix.ui.base
+
+/**
+ * 로딩/에러 상태와 함께 “콘텐츠가 한 번이라도 성공적으로 로드되었는지”를 표현하는 상태 계약.
+ *
+ * 초기 진입 시에는 전체 화면 로딩/에러를, 이후 재조회 시에는 기존 UI 위 overlay loading을
+ * 보여줘야 하는 화면이 구현한다.
+ */
+interface ContentLoadableState : DefaultLoadableState {
+    val hasLoadedContent: Boolean
+
+    /**
+     * 초기 화면 진입 단계에서 전체 UI 대신 loading Indicator를 보여줘야 하는지 여부.
+     */
+    val showLoading: Boolean
+        get() = isLoading && !hasLoadedContent
+
+    /**
+     * 초기 화면 진입 단계에서 전체 UI 대신 ErrorScreen를 보여줘야 하는지 여부.
+     */
+    val showError: Boolean
+        get() = error != null && !hasLoadedContent
+
+    /**
+     * 기존 UI 위에 loading Indicator를 보여줘야 하는지 여부.
+     */
+    val showOverlayLoading: Boolean
+        get() = isLoading && hasLoadedContent
+}
diff --git a/core/ui/src/main/java/com/twix/ui/base/DefaultLoadableState.kt b/core/ui/src/main/java/com/twix/ui/base/DefaultLoadableState.kt
@@ -0,0 +1,19 @@
+package com.twix.ui.base
+
+import com.twix.result.AppError
+
+/**
+ * 비동기 요청의 로딩/에러만 공통으로 관리하는 최소 상태 계약.
+ *
+ * 단순 액션 화면처럼 “기존 콘텐츠 유지 여부”를 별도로 판단할 필요가 없는 경우
+ * 이 인터페이스만 구현하면 된다.
+ */
+interface DefaultLoadableState : State {
+    val isLoading: Boolean
+    val error: AppError?
+
+    fun copyState(
+        isLoading: Boolean = this.isLoading,
+        error: AppError? = this.error,
+    ): DefaultLoadableState
+}
diff --git a/core/ui/src/main/java/com/twix/ui/base/LoadableState.kt b/core/ui/src/main/java/com/twix/ui/base/LoadableState.kt
diff --git a/feature/goal-editor/src/main/java/com/twix/goal_editor/GoalEditorScreen.kt b/feature/goal-editor/src/main/java/com/twix/goal_editor/GoalEditorScreen.kt
@@ -46,6 +46,8 @@ import com.twix.designsystem.components.bottomsheet.model.CommonBottomSheetConfi
 import com.twix.designsystem.components.button.AppButton
 import com.twix.designsystem.components.calendar.Calendar
 import com.twix.designsystem.components.dialog.CommonDialog
+import com.twix.designsystem.components.error.ErrorScreen
+import com.twix.designsystem.components.loading.TwixLoadingOverlay
 import com.twix.designsystem.components.text.AppText
 import com.twix.designsystem.components.toast.ToastManager
 import com.twix.designsystem.components.toast.model.ToastData
@@ -116,6 +118,7 @@ fun GoalEditorRoute(
         uiState = uiState,
         isEdit = goalId != -1L,
         onBack = navigateToBack,
+        onRetry = { viewModel.dispatch(GoalEditorIntent.InitGoal(goalId)) },
         onCommitTitle = { viewModel.dispatch(GoalEditorIntent.SetTitle(it)) },
         onSelectRepeatType = { viewModel.dispatch(GoalEditorIntent.SetRepeatType(it)) },
         onCommitIcon = { viewModel.dispatch(GoalEditorIntent.SetIcon(it)) },
@@ -132,6 +135,7 @@ fun GoalEditorScreen(
     uiState: GoalEditorUiState,
     isEdit: Boolean = false,
     onBack: () -> Unit,
+    onRetry: () -> Unit,
     onCommitTitle: (String) -> Unit,
     onSelectRepeatType: (RepeatCycle) -> Unit,
     onCommitIcon: (GoalIconType) -> Unit,
@@ -141,6 +145,16 @@ fun GoalEditorScreen(
     onToggleEndDateEnabled: (Boolean) -> Unit,
     onComplete: () -> Unit,
 ) {
+    if (isEdit && uiState.showLoading) {
+        TwixLoadingOverlay()
+        return
+    }
+
+    if (isEdit && uiState.showError) {
+        ErrorScreen(onClickRetry = onRetry, onClickBack = onBack)
+        return
+    }
+
     var showRepeatCountBottomSheet by remember { mutableStateOf(false) }
     var showCalendarBottomSheet by remember { mutableStateOf(false) }
     var showIconEditorDialog by remember { mutableStateOf(false) }
@@ -506,6 +520,7 @@ private fun Preview() {
         GoalEditorScreen(
             uiState = uiState,
             onBack = {},
+            onRetry = {},
             onCommitTitle = {},
             onSelectRepeatType = {},
             onCommitEndDate = {},

diff --git a/feature/goal-editor/src/main/java/com/twix/goal_editor/GoalEditorViewModel.kt b/feature/goal-editor/src/main/java/com/twix/goal_editor/GoalEditorViewModel.kt
@@ -102,6 +102,7 @@ class GoalEditorViewModel(
                 startDate = goal.startDate.validStartDate(),
                 endDate = (goal.endDate ?: LocalDate.now()).validEndDate(goal.startDate.validStartDate()),
                 endDateEnabled = goal.endDate != null,
+                hasLoadedContent = true,
             )
         }
     }
@@ -192,12 +193,6 @@ class GoalEditorViewModel(
             onSuccess = { setGoal(it) },
             onError = {
                 initializedGoalId = null
-                emitSideEffect(
-                    GoalEditorSideEffect.ShowToast(
-                        R.string.toast_goal_fetch_failed,
-                        ToastType.ERROR,
-                    ),
-                )
             },
         )
     }

diff --git a/feature/goal-editor/src/main/java/com/twix/goal_editor/model/GoalEditorUiState.kt b/feature/goal-editor/src/main/java/com/twix/goal_editor/model/GoalEditorUiState.kt
@@ -4,7 +4,7 @@ import androidx.compose.runtime.Immutable
 import com.twix.domain.model.enums.GoalIconType
 import com.twix.domain.model.enums.RepeatCycle
 import com.twix.result.AppError
-import com.twix.ui.base.LoadableState
+import com.twix.ui.base.ContentLoadableState
 import java.time.LocalDate
 
 @Immutable
@@ -17,9 +17,10 @@ data class GoalEditorUiState(
     val endDateEnabled: Boolean = false,
     val endDate: LocalDate = LocalDate.now(),
     val isSaving: Boolean = false,
+    override val hasLoadedContent: Boolean = false,
     override val isLoading: Boolean = false,
     override val error: AppError? = null,
-) : LoadableState {
+) : ContentLoadableState {
     val isSaveEnabled: Boolean
         get() = goalTitle.isNotBlank()
 
@@ -29,8 +30,8 @@ data class GoalEditorUiState(
     val canSave: Boolean
         get() = isSaveEnabled && isEndDateValid && !isSaving
 
-    override fun copyLoadableState(
+    override fun copyState(
         isLoading: Boolean,
         error: AppError?,
-    ): LoadableState = copy(isLoading = isLoading, error = error)
+    ): ContentLoadableState = copy(isLoading = isLoading, error = error)
 }
diff --git a/feature/goal-manage/src/main/java/com/twix/goal_manage/GoalManageIntent.kt b/feature/goal-manage/src/main/java/com/twix/goal_manage/GoalManageIntent.kt
@@ -4,6 +4,8 @@ import com.twix.ui.base.Intent
 import java.time.LocalDate
 
 sealed interface GoalManageIntent : Intent {
+    data object Retry : GoalManageIntent
+
     data class SetSelectedDate(
         val date: LocalDate,
     ) : GoalManageIntent