開發規範

✅ app/components/LoginForm.vue
✅ app/pages/product-detail.vue
✅ app/layouts/default.vue

❌ app/components/login-form.vue       （應 PascalCase）
❌ app/pages/ProductDetail.vue         （應 kebab-case）
❌ app/layouts/Default.vue             （應全小寫）

✅ app/composables/useToast.ts          （use + PascalCase）
✅ app/store/user-info.ts               （kebab-case）
✅ app/middleware/login.global.ts       （kebab + .global）
✅ server/api/health.get.ts             （kebab + HTTP 方法）

❌ app/composables/use-toast.ts         （應 use + PascalCase）
❌ app/composables/UseToast.ts          （use 必須小寫）
❌ app/store/userInfo.ts                （應 kebab-case）
❌ app/middleware/login.ts              （全域中介層必須帶 .global）

app/pages/                    路由頁面：資料取得、版面組合、路由參數處理
    ↓ 使用
app/components/               業務元件：可重複使用的頁面級 UI 邏輯
    ↓ 使用（Nuxt 自動匯入）
@swift-web/framework          框架元件：Sw* 基礎元件（SwImage、SwButton、SwModal …）

<!-- ❌ pages/product-detail.vue 單檔超過 300 行，混雜資料取得 + 複雜 UI -->
<script setup lang="ts">
defineRouteRules({ isr: 3600 })
const route = useRoute()
const { data: product } = await useAsyncData(() => api.product.detail({ id: route.params.id }))
const { data: comments } = await useAsyncData(() => api.comment.list({ productId: route.params.id }))
const isFavorited = ref(false)
const showShareDialog = ref(false)
const shareToWechat = () => { /* 30 行 */ }
const shareToWeibo = () => { /* 30 行 */ }
const handleAddToCart = () => { /* 50 行 */ }
// ...
</script>

<template>
  <div class="sw-product-detail">
    <!-- 80 行 hero 區 -->
    <!-- 60 行 評論列表 -->
    <!-- 40 行 分享彈窗 -->
    <!-- 50 行 加入購物車浮層 -->
  </div>
</template>

<!-- ✅ pages/product-detail.vue 拆為 4 個元件 -->
<script setup lang="ts">
defineRouteRules({ isr: 3600 })
const route = useRoute()
const { data: product } = await useAsyncData(() => api.product.detail({ id: route.params.id }))
useSeo({
  title: product.value?.name,
  description: product.value?.summary,
  image: product.value?.cover,
})
</script>

<template>
  <div class="sw-product-detail">
    <ProductDetailHero :product="product" />
    <ProductDetailDescription :product="product" />
    <ProductDetailComments :product-id="route.params.id" />
    <ProductDetailActions :product="product" />
  </div>
</template>

<script setup lang="ts">
/**
 * LoginForm — 使用者登入表單，用於登入頁與登入彈窗
 *
 * ── Props ────────────────────────────────────────────────────────
 * @prop mode        {'page' | 'dialog'}  必填。顯示模式。
 *                   - page：頁面模式，顯示完整背景
 *                   - dialog：彈窗模式，無背景
 * @prop redirectUrl {string}             可選。登入成功後跳轉位址。預設跳首頁。
 *
 * ── 事件 ─────────────────────────────────────────────────────────
 * @event success    登入成功時觸發，攜帶使用者資訊
 * @event cancel     使用者點擊取消時觸發（僅 dialog 模式）
 *
 * ── 使用範例 ─────────────────────────────────────────────────────
 *
 * // 範例 1：頁面模式
 * <LoginForm mode="page" />
 *
 * // 範例 2：彈窗模式 + 監聽事件
 * <LoginForm
 *   mode="dialog"
 *   redirect-url="/mine"
 *   @success="onLoginSuccess"
 *   @cancel="closeDialog"
 * />
 *
 * // 範例 3：與 useModal 搭配
 * const modal = useModal()
 * modal.open(LoginForm, { mode: 'dialog' })
 */

interface Props {
  mode: 'page' | 'dialog'
  redirectUrl?: string
}

const props = withDefaults(defineProps<Props>(), {
  redirectUrl: '/',
})

const emit = defineEmits<{
  success: [userInfo: UserInfo]
  cancel: []
}>()
</script>

// ✅ 正確：用 withDefaults 顯式宣告
const props = withDefaults(defineProps<Props>(), {
  variant: 'primary',     // 有意義的預設值
  disabled: false,
  label: undefined,       // 無合適預設值時顯式寫 undefined
})

// ❌ 錯誤：依賴 TS 預設 undefined 隱式
const props = defineProps<Props>()

// ✅ 正確：聯合類型讓呼叫方有 IDE 補全 + 類型保護
interface Props {
  variant?: 'primary' | 'secondary' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
}

// ❌ 錯誤：裸 string 任何字串都過編譯
interface Props {
  variant?: string
  size?: string
}

// ✅ 正確：選項物件，未來加參數不 break 呼叫方
interface UploadOptions {
  file: File
  onProgress?: (percent: number) => void
  retries?: number
}
function uploadFile(opts: UploadOptions): Promise<string> { /* ... */ }

uploadFile({ file, onProgress, retries: 3 })

// ❌ 錯誤：位置參數，加第 4 個參數所有呼叫點都要改
function uploadFile(file: File, onProgress?: (p: number) => void, retries?: number): Promise<string> { /* ... */ }

<template>
  <!-- ✅ 業務封裝的按鈕元件 -->
  <button v-bind="$attrs" class="sw-primary-btn" @click="onClick">
    <slot />
  </button>
</template>

<script setup lang="ts">
defineOptions({ inheritAttrs: false })
</script>

<PrimaryBtn :disabled="loading" aria-label="提交訂單" data-testid="submit">
  提交
</PrimaryBtn>

<!-- ✅ app/components/LoginForm.vue → 根 class .sw-login-form -->
<template>
  <form class="sw-login-form">
    <input class="email" />
    <input class="password" />
    <button class="submit">登入</button>
  </form>
</template>

<!-- ✅ app/pages/about-us.vue → 根 class .sw-about-us -->
<template>
  <div class="sw-about-us">
    <h1>關於我們</h1>
  </div>
</template>

<!-- ✅ 根是包裝元件且不寫 class —— 自動豁免 -->
<template>
  <ClientOnly>
    <div class="sw-inner">...</div>
  </ClientOnly>
</template>

<!-- ❌ 寫了 class 但不帶 sw- 前綴 -->
<template>
  <form class="login-form">...</form>
  <form class="my-login">...</form>
</template>

<template>
  <form class="sw-login-form">
    <div class="header">登入</div>
    <div class="body">
      <input class="email" />
      <input class="password" />
    </div>
    <div class="footer">
      <button class="submit">登入</button>
      <button class="cancel">取消</button>
    </div>
  </form>
</template>

<style scoped>
.sw-login-form .header { font-size: 1.25rem; }
.sw-login-form .body { padding: 1rem; }
.sw-login-form .submit { background: var(--primary); }
</style>

/* ✅ 正確：狀態用形容詞形態 + is/has 前綴 */
.sw-login-form .field.has-error { border-color: var(--destructive); }
.sw-login-form .btn.is-loading { opacity: 0.6; cursor: wait; }
.sw-login-form .btn.is-disabled { opacity: 0.4; pointer-events: none; }
.sw-product-card.is-selected { box-shadow: 0 0 0 2px var(--ring); }

/* ❌ 錯誤：狀態用名詞形態，與子元素衝突 */
.sw-login-form .error { /* 是子元素還是狀態？ */ }
.sw-login-form .loading { /* 同上 */ }

/* ❌ BEM 雙底線（與 framework 風格不一致） */
.sw-login-form__header { }
.sw-login-form__submit--disabled { }

/* ❌ 子 class 帶 sw- 前綴（scoped 下冗餘） */
.sw-login-form .sw-header { }
.sw-login-form .sw-body { }

/* ❌ 根 class 不帶 sw- 前綴（違反根 class 強約束） */
.login-form { }
.app-navbar { }

/* ❌ 子 class 堆疊元件根前綴（多此一舉） */
.sw-login-form-header-item-label { }

/* ❌ 狀態用名詞形態（與子元素歧義） */
.sw-btn .loading { } /* 應改 .is-loading */
.sw-form .error { }  /* 應改 .has-error */

/* ✅ 推薦：淺層巢狀作語意分組 */
.sw-login-form {
  display: flex;
  flex-direction: column;

  .field {
    margin-bottom: 1rem;
    &.has-error { border-color: var(--destructive); }
  }

  .submit {
    background: var(--primary);
  }
}

/* ✅ 也合規：完全扁平（scoped 自動隔離） */
.sw-login-form { display: flex; flex-direction: column; }
.sw-login-form .field { margin-bottom: 1rem; }
.sw-login-form .field.has-error { border-color: var(--destructive); }
.sw-login-form .submit { background: var(--primary); }

/* ❌ 不推薦：深巢狀 + 嚴格 DOM 層級對齊（4 層） */
.sw-card {
  .header {
    .row {
      .col {
        .title { color: red; }
      }
    }
  }
}

/* ✅ 正確：語意 token，無 fallback */
.sw-ad-swiper {
  background: var(--background);
  border: 1px solid var(--border);
  border-radius: var(--radius);
  color: var(--foreground);
}

.sw-error-banner {
  background: var(--destructive);
  color: var(--destructive-foreground);
}

/* ❌ 帶 fallback（多此一舉，:root 已兜底） */
color: var(--primary, #3b82f6);

/* ❌ 已徹底移除的舊 token 命名（獨立色值，已不存在） */
background: var(--color-bg-dark);
border-color: var(--border-color);
padding: var(--spacing-section);

/* ❌ 手寫 CSS 直接引 Tailwind @theme 橋接變數 —— 改引語意 token var(--primary) */
color: var(--color-primary);

/* ❌ 硬編碼色值 */
background: #f5f5f5;
color: #1a1a1a;
border: 1px solid #e5e5e5;

/* ✅ 正確：filter brightness 一行搞定，dark mode 自動 */
.submit {
  background: var(--primary);
  color: var(--primary-foreground);
  transition: filter 0.15s ease;
}
.submit:hover  { filter: brightness(0.92); }
.submit:active { filter: brightness(0.85); }

.danger-btn {
  background: var(--destructive);
  color: var(--destructive-foreground);
  transition: filter 0.15s ease;
}
.danger-btn:hover { filter: brightness(0.92); }

/* ❌ 錯誤：單獨維護 hover 色 token */
.submit { background: var(--primary); }
.submit:hover { background: var(--primary-hover); } /* 已廢棄 --primary-hover */

.sw-product-card {
  padding: 1.5rem;                   /* ✅ 間距用 rem */
  font-size: 1rem;                   /* ✅ 字體用 rem */
  line-height: 1.6;                  /* ✅ 行高無單位 */
  border-radius: 0.75rem;            /* ✅ 大圓角用 rem */
  border: 1px solid var(--border);   /* ✅ 邊框寬度用 px */
  box-shadow: 0 2px 8px rgb(0 0 0 / 0.06); /* ✅ 陰影 offset 用 px */
}

.tag {
  border-radius: 4px;                /* ✅ 小圓角（< 8px）用 px 例外 */
}

@media (max-width: 768px) {          /* ✅ 媒體查詢用 px */
  .sw-product-card { padding: 1rem; }
}

.sw-product-card {
  padding: 24px;                     /* ❌ 間距應 rem */
  font-size: 16px;                   /* ❌ 字體應 rem */
  line-height: 26px;                 /* ❌ 行高應無單位（如 1.6） */
  margin: 0.5em 1em;                 /* ❌ 禁用 em（巢狀複合難追蹤） */
}

@media (max-width: 48em) {           /* ❌ 媒體查詢應 px */
  .sw-product-card { padding: 1rem; }
}

/* ✅ 正確：與 framework 斷點一致 */
.sw-product-list { display: grid; grid-template-columns: 1fr; }

@media (min-width: 768px) {
  .sw-product-list { grid-template-columns: 1fr 1fr; }
}
@media (min-width: 1024px) {
  .sw-product-list { grid-template-columns: 1fr 1fr 1fr; }
}

// ✅ 正確：unknown 強制呼叫方收窄類型
function parseResponse(data: unknown): UserInfo {
  // 實際專案中應該先校驗結構
  return data as UserInfo
}

interface ApiEnvelope {
  code: number
  data: unknown
}
function unwrap<T>(envelope: ApiEnvelope): T {
  if (envelope.code !== 0) throw new Error(`API ${envelope.code}`)
  return envelope.data as T
}

// ❌ 錯誤：any 完全放棄類型檢查
function parseResponse(data: any): any {
  return data
}

// ❌ 錯誤：函式參數 / 回傳值無類型（隱式 any）
function format(date) {
  return date.toLocaleString()
}

// ✅ 正確：as const + [number] 自動推導聯合類型
const VARIANTS = ['primary', 'secondary', 'ghost'] as const
type Variant = (typeof VARIANTS)[number]
// Variant = 'primary' | 'secondary' | 'ghost'

const RENDER_MODES = ['ssr', 'csr', 'isr', 'ssg'] as const
type RenderMode = (typeof RENDER_MODES)[number]

// ✅ 物件 as const 鎖結構
const STATUS_LABELS = {
  pending: '待支付',
  paid: '已支付',
  cancelled: '已取消',
} as const
type Status = keyof typeof STATUS_LABELS

// ❌ 錯誤：丟失字面量資訊（推斷為 string[]）
const VARIANTS = ['primary', 'secondary', 'ghost']
// typeof VARIANTS = string[]，無法精確推導

// ❌ 錯誤：手寫聯合類型（與陣列同步漂移風險）
type Variant = 'primary' | 'secondary' | 'ghost'
const VARIANTS: Variant[] = ['primary', 'secondary'] // ←漏 'ghost'，編譯還能過

// ── 一般變數 / 函式：camelCase ──
const pageTitle = ref('')
const userInfo = useUserStore()
function fetchUserInfo() {}
async function uploadFile(opts: UploadOptions): Promise<string> {}

// ── 布林值：is- / has- / can- / should- 開頭 ──
const isLoading = ref(false)
const hasError = computed(() => !!errorMsg.value)
const canSubmit = computed(() => form.valid && !isLoading.value)
const shouldShowDialog = ref(false)

// ── 模組級真常數：SCREAMING_SNAKE_CASE ──
const MAX_RETRY = 3
const DEFAULT_PAGE_SIZE = 20
const API_TIMEOUT_MS = 10_000

// ── 類型 / 介面：PascalCase，不加 I 前綴 ──
interface UserInfo { id: number; name: string }
type ApiResponse<T> = { data: T; code: number }
// ❌ interface IUserInfo（不要加 I 前綴）

// ── 模組內部輔助函式：_ 前綴 ──
function _deriveKey(requestId: string) {}
function _validateInternal(payload: unknown) {}

// ✅ 正確：Ref 後綴
const inputRef     = ref<HTMLInputElement>()
const containerRef = ref<HTMLDivElement>()
const listRef      = ref<HTMLUListElement>()
const swImageRef   = ref<InstanceType<typeof SwImage>>()

// 樣板裡
// <input ref="inputRef" />
// <SwImage ref="swImageRef" />

// ❌ 錯誤：與一般 ref 視覺混淆
const input = ref<HTMLInputElement>()
const container = ref<HTMLDivElement>()

// ✅ Nuxt / Nitro 路徑用 createError（框架理解的 statusCode）
throw createError({
  statusCode: 404,
  statusMessage: '商品不存在',
  data: { productId: id },
})

// ✅ 純 logic 路徑用 Error 子類
throw new Error('剖析失敗：缺少必填欄位 phone')

// ❌ 禁止：throw 字串字面量（丟失 stack trace）
throw '登入失敗'

// ✅ 正確：先判類型再存取 .message
try {
  await someApi()
} catch (e) {
  if (e instanceof Error) {
    console.error(e.message, e.stack)
  } else {
    console.error('未知錯誤', e)
  }
}

// ✅ 業務錯誤用自訂 Error 類
export class LoginExpiredError extends Error {
  constructor() {
    super('登入已過期')
    this.name = 'LoginExpiredError'
  }
}

// catch 處理點
try { await fetchProfile() }
catch (e) {
  if (e instanceof LoginExpiredError) {
    await navigateTo('/login')
    return
  }
  throw e
}

// ❌ 禁止：吞錯誤（不 console.warn 不 throw）
try { await someApi() } catch {}

// ❌ 錯誤：直接存取 e.message（TS 報 ts-2571）
catch (e) {
  console.error(e.message) // e 是 unknown 類型
}

// ✅ 跨模組共用：app/types/user.ts
export interface UserInfo { id: number; name: string; phone: string }
export type UserRole = 'admin' | 'member' | 'guest'

// ✅ 僅本模組使用：緊鄰定義
// app/composables/useLoginForm.ts
interface LoginFormState {  // 不外移
  phone: string
  code: string
  agreed: boolean
}
export function useLoginForm() {
  const state = reactive<LoginFormState>({ phone: '', code: '', agreed: false })
  return { state }
}

// ❌ 反例：把僅本模組用的類型放進 types/，污染全域
// app/types/login-form-state.ts ← 沒有第二個模組用，外移即過早抽象

// ✅ 推薦：直接用中文原文
$t('登录')
$t('请输入手机号')
$t('订单总计 {amount} 元', { amount: 99 })
$t('欢迎 {username}，今天是 {date}', { username, date })

// ❌ 反對：另起英文鍵名
$t('login.button')
$t('order.total.amount')
$t('common.welcome.message')

// ✅ 長文案：用簡短描述作 key
$t('首页SEO描述')
$t('关于页SEO描述')
$t('用户协议第一段')

// ❌ 禁止：把長句直接作為 key
$t('一个现代化的 Nuxt 4 脚手架模板，内置 lint、测试、国际化、主题等一切所需。')

// ✅ 正確：命名佔位符
$t('订单总计 {amount} 元', { amount: 99 })
$t('欢迎 {username}，今天是 {date}', { username, date })

// ❌ 錯誤：位置參數（與中文原文 key 風格不搭）
$t('订单总计 {0} 元', [99])
$t('Welcome {0}, today is {1}', [username, date])

// ✅ i18n/locales/zh-CN.json
{
  "关于页SEO描述": "了解 Swift Web：一个基于 Nuxt 4 的现代化工程模板...",
  "立即开始": "立即开始",
  "登录": "登录",
  "首页": "首页",
  "首页SEO描述": "一个现代化的 Nuxt 4 脚手架模板，内置 lint、测试、国际化..."
}

// ✅ i18n/locales/en.json（key 仍是中文原文）
{
  "关于页SEO描述": "Learn about Swift Web: a Nuxt 4 project template...",
  "立即开始": "Get Started",
  "登录": "Sign In",
  "首页": "Home",
  "首页SEO描述": "A modern Nuxt 4 starter template with everything you need..."
}

// 中文不區分單複數，三段都寫中文即可
$tc('{n} 条评论 | {n} 条评论 | {n} 条评论', count, { n: count })

// 其他 locale 按規則展開
// en.json: { "{n} 条评论 | {n} 条评论 | {n} 条评论": "no comments | one comment | {n} comments" }

第 1 次請求  → 伺服器端算繪 → 快取 HTML → 回傳給使用者
快取期內請求 → 直接回傳快取 HTML（零 Node.js 開銷）
快取到期後   → 下一個請求仍回傳舊快取（使用者不等待）
              同時背景重新算繪 → 更新快取

<!-- ✅ 內容詳情頁：更新不頻繁，ISR 永久快取 -->
<script setup lang="ts">
defineRouteRules({ isr: 3600 })
</script>

<!-- ✅ 首頁 / 列表頁：每小時重新整理 -->
<script setup lang="ts">
defineRouteRules({ isr: 3600 })
</script>

<!-- ✅ 關於頁 / 隱私協議：內容固定，建構時生成 -->
<script setup lang="ts">
defineRouteRules({ prerender: true })
</script>

<!-- ✅ 個人中心 / 收藏 / 歷史：必須登入，純客戶端算繪 -->
<script setup lang="ts">
defineRouteRules({ ssr: false })
</script>

<!-- ✅ 極少數需要即時資料的頁面（搜尋結果、訂單列表） -->
<script setup lang="ts">
defineRouteRules({ ssr: true })
</script>

<script setup lang="ts">
// 1. 算繪策略（必填，ESLint 強制檢查）
defineRouteRules({ isr: 3600 })

// 2. 頁面元資料
definePageMeta({ layout: 'default' })

// 3. 路由與國際化
const route = useRoute()
const { t } = useI18n()

// 4. 資料取得（必須在 setup 頂層 await，讓 SSR 拿到資料）
const { data: product, status, error } = await useAsyncData(
  `product-${route.params.id}`,
  () => api.product.detail({ id: route.params.id }),
)

// 5. SEO 資訊（用 useSeo，含 og / twitter / canonical / robots）
useSeo({
  title: product.value?.seo?.title ?? product.value?.name,
  description: product.value?.seo?.description ?? product.value?.summary,
  image: product.value?.cover,
  type: 'article',
  article: {
    author: product.value?.author,
    datePublished: product.value?.publishedAt,
    dateModified: product.value?.updatedAt,
  },
})

// 6. 錯誤兜底：錯誤頁一定要 throw createError，避免錯誤頁被 ISR 快取
if (error.value) {
  throw createError({
    statusCode: error.value.statusCode ?? 500,
    statusMessage: error.value.statusMessage ?? '商品載入失敗',
  })
}
</script>

<template>
  <div class="sw-product-detail">
    <ProductDetailSkeleton v-if="status === 'pending'" />
    <ProductDetailContent v-else :product="product" />
  </div>
</template>

<style scoped>
.sw-product-detail {
  padding: 1.5rem;
  background: var(--background);
}
</style>

// ✅ 正確：useSeo
useSeo({
  title: '商品詳情',
  description: '高品質優選商品，限時折扣',
  image: '/og/product.jpg',
  type: 'article',
  article: {
    author: '張三',
    datePublished: '2026-01-01',
    dateModified: '2026-05-08',
  },
})

// ❌ 反例：裸用 useSeoMeta
useSeoMeta({
  title: '商品詳情',
  description: '高品質優選商品，限時折扣',
  ogTitle: '商品詳情',
  ogDescription: '高品質優選商品，限時折扣',
  ogImage: '/og/product.jpg',
  twitterCard: 'summary_large_image',
  // ↑ og / twitter / canonical 都要手拼，重複且容易漏
})

// ✅ 私有頁：noindex + 靜音長度告警
useSeo({
  title: '登入',
  description: '登入 Swift Web',
  robots: 'private',          // 等價於 noindex,nofollow
  silenceLengthWarnings: true, // 私有頁 title/desc 天然短，關閉長度警告
})

// ✅ 中轉 / 重新導向頁：noindex
useSeo({
  title: '正在跳轉',
  robots: 'noindex',
  silenceLengthWarnings: true,
})

// ✅ 錯誤頁：noindex,nofollow
// app/error.vue
useSeo({
  title: '頁面不存在',
  robots: 'noindex,nofollow',
  silenceLengthWarnings: true,
})

useSeo({
  // ── 基礎 ──
  title: data.value?.seo?.title ?? data.value?.name,
  description: data.value?.seo?.description ?? data.value?.summary,
  keywords: data.value?.tags?.slice(0, 6).join('、'), // ≤ 10 個

  // ── 分享卡片圖（必傳，詳情頁用業務真實封面） ──
  image: data.value?.cover ?? '/og/default.jpg',

  // ── Article schema（詳情頁必填） ──
  type: 'article',
  article: {
    author: data.value?.author,
    datePublished: data.value?.publishedAt,
    dateModified: data.value?.updatedAt,
  },

  // canonical 預設取目前 URL，一般無需手填
})

// ❌ ISR 頁在 SSR 路徑呼叫 private API —— 使用者訂單被烙進快取，全員看到
defineRouteRules({ isr: 3600 })
const { data } = await useAsyncData(() => api.user.orders())

// ❌ 主體 + 附加資訊混在同一請求 —— is_favorited 跟著主體一起被快取
const { data } = await useAsyncData(() =>
  api.movie.detail({ id, userId: useUserStore().info?.user_id }),
)

// ✅ SSR 路徑只呼叫 public API
defineRouteRules({ isr: 3600 })
const { data } = await useAsyncData(() => api.movie.detail({ id }))

// ✅ 附加私有資訊單獨 CSR 回填（client 路徑，lint 不報也確實安全）
const isFavorited = ref(false)
onMounted(async () => {
  isFavorited.value = await api.movie.hasFavorite({ id })
})

SSR 期發請求
  ├─ 沒有 token？                 → 整段跳過（未登入訪客，零開銷）
  ├─ 本頁可快取嗎？               → 查 routeRules，isr / prerender / cache / swr 四鍵任一為真即算
  │                                 （取不到路由上下文時按「不判」處理，避免誤傷 nitro 任務）
  └─ 是 ⇒ 分檔處理
       ├─ dev + 真實登入使用者（有 user_id） → 直接 throw，當場攔住
       ├─ dev + 僅裝置匿名（無 user_id）     → console.warn，不打掛頁面
       └─ dev 與 prod 都執行：剝離 token 後重發
            └─ 後端回 errorCode 2002（「要登入」）→ **顯式 throw**，不走靜默重登重試

<!-- ❌ 自實作 image 缺 ratio + 懶載入 + 現代格式 -->
<template>
  <img :src="product.cover" :alt="product.name" />
</template>

<!-- ✅ 改用 SwImage -->
<template>
  <SwImage
    :src="product.cover"
    :alt="product.name"
    :ratio="16 / 9"
    loading="lazy"
  />
</template>

// ❌ 錯誤：頂層直接存取 window
<script setup lang="ts">
const userAgent = window.navigator.userAgent  // SSR 期 ReferenceError
const stored = localStorage.getItem('token')   // 同上
</script>

// ✅ 正確：onMounted 守衛（僅 client 執行）
<script setup lang="ts">
const userAgent = ref('')
const stored = ref<string | null>(null)
onMounted(() => {
  userAgent.value = window.navigator.userAgent
  stored.value = localStorage.getItem('token')
})
</script>

// ✅ 正確：import.meta.client 守衛
<script setup lang="ts">
let stored: string | null = null
if (import.meta.client) {
  stored = localStorage.getItem('token')
}
</script>

// ❌ 錯誤：模組級 ref 跨請求會串資料
// app/composables/useCart.ts
const items = ref<CartItem[]>([])
export function useCart() { return { items } }

// ✅ 正確：useState 每個請求獨立
// app/composables/useCart.ts
export function useCart() {
  const items = useState<CartItem[]>('cart-items', () => [])
  return { items }
}

git switch dev/main && git pull --ff-only          # 1. 從最新 dev/main 出发（本地 dev/main 永遠只 pull，不 commit）
git switch -c feat/dark-theme                      # 2. 短期分支，一個任務一條
# …開發、按 task 原子 commit…
git push -u origin feat/dark-theme                 # 3. 推分支，開 MR → dev/main
git switch dev/main                                # 4. 提完 MR 立刻切回（bot 挑刺要改時再切回去）
# MR 合併 → 遠端分支自動刪；本地：git pull --ff-only && git branch -D feat/dark-theme

<type>(<scope>): <中文描述>

[可選正文：解釋 why，不解釋 what（diff 會說話）]

[可選 footer：Closes #N / Refs #N / Co-Authored-By: ...]

feat(產品頁): 新增產品詳情頁路由與資料取得

fix(導覽): 修復行動端選單關閉後捲動鎖定問題

perf(圖片): 使用 SwImage 取代所有原生 img 標籤

chore(相依): 升級 @swift-web/framework 至 v0.7.x

feat(sw-image): 新增 avif srcset 支援

舊版只輸出 webp，部分新瀏覽器優先 avif（體積更小 30%）。
本次擴充 SwImage 的 generator script，建構期同時輸出 avif/webp/jpg 三檔。

Closes #88

fix(rendering): ISR 頁面 useFetch 錯誤回應不再被烙快取

發現 manga 詳情頁偶發 500 錯誤時，錯誤頁被 ISR 快取到所有使用者。
統一在 useFetch 後加 throw createError 兜底，讓 Nitro 不快取錯誤回應。

Refs #102

# ✅ 關閉 issue（合併後自動關閉）
git commit -m "fix(login): 修正 redirect 死迴圈 Closes #42"

# ✅ 僅引用，不關閉
git commit -m "feat(auth): 接入 OAuth 流程（進行中）參考 #15"

refactor(sw-modal): 重新命名 ImageCard 為 MediaCard

BREAKING CHANGE: ImageCard 元件已重新命名為 MediaCard，
所有頁面與元件中的 <ImageCard> 引用需同步更新為 <MediaCard>。

refactor(sw-modal)!: 重新命名 ImageCard 為 MediaCard

[AI] <type>(<scope>): <中文描述>

[可選正文]

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
AI-Tool: claude-code

# 目前倉庫 AI commit 數
git log --oneline --grep="\[AI\]" | wc -l

# 按月統計
git log --grep="\[AI\]" --format="%ad" --date=format:"%Y-%m" | sort | uniq -c

# 跨倉庫統計（在 monorepo 根目錄執行）
for repo in framework cli starter docs; do
  count=$(git -C $repo log --oneline --grep="\[AI\]" 2>/dev/null | wc -l | tr -d ' ')
  echo "$repo: $count AI commits"
done

git fetch origin dev/main dev/v1 -q
git worktree add --detach /tmp/retire-wt origin/dev/v1
git -C /tmp/retire-wt merge --no-edit origin/dev/main   # 把 dev/main 合進 dev/v1 的本地副本；衝突 hunk 先判方向（見下）
git -C /tmp/retire-wt diff origin/dev/main --stat       # 空 ⇒ dev/v1 沒有任何 dev/main 缺的內容——貼到 issue 才算判空
git worktree remove --force /tmp/retire-wt
git push origin --delete dev/v1                         # 不可逆：只在貼證 + 拍板之後

// ✅ 伺服器端拉資料用 useFetch / useAsyncData（享 SSR + hydration 最佳化）
const { data: products } = await useAsyncData('products', () => api.product.list())

// ❌ 直接 fetch（失去 SSR 資料預取 + hydration 同步）
const products = await api.product.list()   // 裸呼叫，SSR 期不預取

<!-- ✅ 用穩定 id 作 key -->
<li v-for="item in items" :key="item.id">{{ item.name }}</li>

<!-- ❌ 用 index 作 key（資料順序變動時 patch 錯位） -->
<li v-for="(item, i) in items" :key="i">{{ item.name }}</li>

// ❌ 直接算繪使用者輸入（XSS 風險）
<div v-html="userInput" />

// ✅ 用 DOMPurify 消毒後算繪
import DOMPurify from 'dompurify'
const safeHtml = computed(() => DOMPurify.sanitize(userInput.value))
// <div v-html="safeHtml" />

// ❌ 串列 await（效能反模式：A 完才請求 B）
const { data: a } = await useFetch('/api/a')
const { data: b } = await useFetch('/api/b')

// ✅ 平行 await
const [{ data: a }, { data: b }] = await Promise.all([
  useFetch('/api/a'),
  useFetch('/api/b'),
])

// ❌ computed 內 console.log / 改其他狀態
const total = computed(() => {
  console.log('計算 total')   // 副作用
  fetchExtra()                 // 更嚴重：觸發請求
  return items.value.reduce((s, i) => s + i.price, 0)
})

// ✅ 副作用用 watch / watchEffect
const total = computed(() => items.value.reduce((s, i) => s + i.price, 0))
watch(total, (n) => {
  if (n > 1000) showCouponHint()
})

<!-- ❌ 錯誤：onClick 跳轉，爬蟲看不到 -->
<button @click="router.push('/products')">查看商品</button>

<!-- ✅ 正確：用 NuxtLink / SwLink -->
<SwLink to="/products">查看商品</SwLink>

<!-- ❌ 錯誤：placeholder 取代 label -->
<input placeholder="請輸入手機號" />

<!-- ✅ 正確：label + aria-label -->
<label for="phone">手機號</label>
<input id="phone" placeholder="例：13800138000" />

/**
 * 上傳單一檔案並回傳伺服器端簽發的 URL。
 *
 * 實作細節：分片大小 4MB，失敗自動重試 3 次。
 *
 * @throws 網路故障或伺服器端拒絕時拋 UploadFailedError
 */
export async function uploadFile(file: File): Promise<string> {
  // ...
}

// ✅ TODO 必帶追溯線索
// TODO(@djatm, #142): WebSocket 心跳間隔需要隨後端設定動態調整，目前先固定 30s
const HEARTBEAT_INTERVAL = 30_000

// ❌ 錯誤：TODO 無負責人 / issue
// TODO: 這裡要改