开发规范

✅ 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 } = 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: 这里要改