Swift Web 介紹

Swift Web 生態

@swift-web/cli        命令列腳手架（發布在私有 npm）
  └─ sw create / add / config / info / upgrade / run

@swift-web/framework  核心框架模組（發布在私有 npm）
  └─ 元件 / Composable / Store / 插件 / 中介層 / 模組選項

@swift-web/starter    專案工程模板（發布在私有 npm，僅供 cli 拉取，業務方不直接裝）
  └─ sw create 時用 `npm pack @swift-web/starter` 拉最新版本

@swift-web/standards  生態規範單一事實源（發布在私有 npm）
  └─ 開發規範 rules / ESLint / Prettier / Stylelint 可分發設定 / commit-msg 校驗

pnpm add -g @swift-web/cli
sw create YC001-WEB-我的專案
sw add page product-detail
sw upgrade

// 登入與鑑權
useLoginCheck() // 檢查登入態，未登入跳轉
useLoginBy() // 多方式登入（手機號／帳號密碼等）
useLoginDialog() // 彈出登入對話框
useAuthReady() // 等待登入流程結束（device + 憑證嘗試都跑過）

// UI 互動
useModal() // 命令式彈窗
useToast() // 訊息提示（成功／錯誤／警告）

// 媒體 / 上傳 / 解密
useUploader() // 檔案分片上傳
useDecryptedAsset() // 加密資源（.bnc）解密 + IndexedDB 快取

// 主題
useTheme() // 主題管理（mode 感知：resolvedTheme + toggle/system/dark/light；無條件註冊）

// SEO
useSeo() // 統一 SEO 入口（og / canonical / JSON-LD / robots）

// 埋點與廣告
useTracker() // 集團 WebSDK 統一埋點（track 自訂事件）
useAdTrack() // 廣告曝光／點擊埋點欄位自動組裝
useAdFrequency() // 廣告展示頻率控制（加密快取）
useExposure() // 通用進視口一次性曝光偵測（內容卡片曝光埋點 / 自有 SDK 逃生艙）

// PWA
useAddToHomescreen() // 加入主畫面（A2HS）能力偵測與觸發

// 互動 / 導覽
useHoverPreview() // 卡片 hover 放大浮層預覽的機制層（意圖判定 + 定位純函式）
useExternalRedirect() // 外部連結中轉頁：白名單校驗 + noindex + 倒數跳轉
useVideoPlayerPrefs() // 播放器偏好：跳過片頭片尾 / 自動播放下一集

useUserStore() // 使用者資訊（登入態、token、使用者資料）
useSystemStore() // 系統資訊（伺服器端注入的全域設定）

swiftConfig: {
  theme: { mode: 'toggle' },                          // 主題模式（system/toggle/dark/light）
  i18n: { enabled: true, defaultLocale: 'zh-CN' },   // 多語言
  pwa: true,                                          // PWA
  auth: {                                             // 路由守衛 + client auth init
    guardedPaths: ['/mine'],
    guestPaths: ['/login', '/register'],
  },
  obfuscate: true,                                    // JS 混淆（正式預設開啟）
  websocket: true,                                    // WebSocket 客戶端
  errorHandler: { enabled: true, endpoint: '/_error-report' },  // 全域錯誤監控
  styles: { reset: true, responsive: true },          // CSS 基礎層注入開關
  systemInfo: true,                                   // /system/info 拉取（false / 物件 可選）
  suppressConsole: true,                              // 正式環境停用 console
  image: { provider: 'noop' },                        // SwImage provider 路由
  manualChunks: {},                                   // Vite 自訂分包
  request: { timeout: 20_000 },                       // $request 全域逾時 / 全域 headers
  seo: {                                              // SEO 套件（永久啟用）
    aiBotPolicy: 'allow',                             // AI 訓練爬蟲策略（'allow' | 'disallow'）
    sitemap: { exclude: ['/preview/**'] },            // sitemap 追加排除路徑（私有路徑已預設排除）
  },
  tracker: true,                                      // 集團統一埋點底座（設定缺失自動降級靜默）
}

專案目錄/
├── app/
│   ├── components/      業務元件（PascalCase 命名）
│   ├── pages/           路由頁面（kebab-case 命名）
│   ├── layouts/         版面配置檔案（全小寫命名）
│   ├── composables/     業務級 composable
│   ├── store/           業務級 Pinia store
│   ├── api/             API 模組（按功能分檔案）
│   ├── assets/          CSS 變數、全域樣式
│   └── plugins/         業務級插件
├── public/
│   └── images/          圖片原始檔案（jpg/png/webp/svg）
├── i18n/                多語言翻譯檔案（zh-CN/zh-TW/en）
├── server/              Nitro 伺服器端 API
├── .env                 本地環境變數（不提交 git）
├── nuxt.config.ts       Nuxt 設定（含框架模組選項）
└── swift.config.json    Swift Web 專案中繼資料

┌─────────────────────────────────────────┐
│           業務層（starter）              │
│   app/pages → app/components → app/api │
│              ↓ 使用（自動匯入）          │
├─────────────────────────────────────────┤
│          框架層（framework）             │
│   Sw* 元件 / use* composable / store   │
│      不得反向引用業務層內容              │
└─────────────────────────────────────────┘