useLoginCheck()

useLoginCheck() 是 framework 鑑權體系的核心 composable。在業務操作前呼叫，未登入時按 mode 自動引導使用者（頁面跳轉或彈窗），已登入直接放行。

簽名：useLoginCheck(options?): Promise<boolean> —— 直接回傳 Promise（已登入 true / 未登入 false）；不是回傳包含 isLoggedIn 的物件。

基本用法

<script setup lang="ts">
async function submitComment() {
  // 未登入時跳轉 /login?redirect=當前路徑，已登入回傳 true
  if (!(await useLoginCheck())) return

  await request('/comment/add', { body: { content: text.value } })
}
</script>

彈窗模式（桌面端推薦）

桌面端點讚、收藏等不希望「跳走」的輕互動，用彈窗登入：

<script setup lang="ts">
const { open } = useLoginDialog()

async function onLike() {
  if (!(await useLoginCheck({ mode: 'dialog', openDialog: open }))) return

  await request('/like/toggle', { body: { id } })
}
</script>

強制登入後不回到原頁

敏感操作（如修改 email 後跳首頁確認資訊）用 redirectBack: false：

await useLoginCheck({ redirectBack: false })

參數

參數	類型	預設	說明
`mode`	`'page' \| 'dialog'`	`'page'`	未登入時的引導方式：`page` 跳轉 `/login`；`dialog` 呼叫 `openDialog` 彈窗
`redirectBack`	`boolean`	`true`	登入後是否帶 `?redirect=當前路徑` 回傳（`mode: 'page'` 時有效）
`openDialog`	`() => void`	—	`mode: 'dialog'` 時呼叫此函式開啟彈窗。通常傳 `useLoginDialog()` 的 `open`

回傳值

Promise<boolean> —— true = 已登入，可繼續業務；false = 未登入，已自動引導（頁面已跳轉或彈窗已開啟），呼叫方應 early return

直接回傳 Promise<boolean>，不是物件。當前簽名見原始碼 src/runtime/composables/useLoginCheck.ts。

與全域響應式登入狀態的關係

判斷「使用者當前是否已登入」用 useUserStore() 的 isLoggedIn（響應式 ref，跨標籤頁 cookie 同步）：

<template>
  <div v-if="userStore.isLoggedIn">
    <UserProfile />
  </div>
  <div v-else>
    <NuxtLink to="/login">請登入後查看</NuxtLink>
  </div>
</template>

<script setup lang="ts">
const userStore = useUserStore()
</script>

useLoginCheck() 是一次性副作用（「未登入就引導」），不要在模板裡 await 它當響應式狀態用。

與路由守衛的關係

framework 內建的 login.global middleware 不呼叫 useLoginCheck()，而是直接讀 userStore.isLoggedIn 判斷（更輕量，無副作用）。守衛路徑在 nuxt.config.ts 的 swiftConfig.auth.guardedPaths 配置：

// nuxt.config.ts
export default defineNuxtConfig({
  swiftConfig: {
    auth: {
      guardedPaths: ['/mine', '/profile', '/settings'],
      guestPaths: ['/login', '/register'],
    },
  },
})

useLoginCheck() 主要服務於業務側細粒度引導（具體操作前檢查），不是 middleware 替代品。

注意事項

必須 await，否則後續業務在登入未完成時就跑了（Rule UL-001）—— 回傳 Promise<boolean>（true=已登入 / false=未登入且已跳轉登入頁或已彈登入框）。不 await 會導致拿到 null userInfo、向後端發未認證請求、或出現「先報錯後跳登入頁」的怪現象。標準寫法 if (!(await useLoginCheck())) return。
TS 的 no-floating-promises 只兜住一部分 —— 條件分支裡的巢狀呼叫、忘記給外層函式加 async 等場景仍會漏，寫的時候自己多看一眼。
它與 useLoginDialog() 語意完全不同 —— 本函式做登入判斷（已登入直接放行）；useLoginDialog() 只切彈窗顯隱、不判斷（見 Rule ULD-001）。要「未登入才攔 + 等結果」一律用本函式。