softleader-nuxt-core 1.0.7 → 1.0.9

package/README.md

@@ -1,27 +1,68 @@
-# Nuxt Core Layer
+# Nuxt Core Layer (`softleader-nuxt-core`)
 
-這是 Nuxt 3 Core Layer，提供可重用的基礎架構、元件和工具。
+這是 Nuxt 3 Core Layer，提供可重用的基礎架構、元件和工具，協助開發團隊快速建立一致且高品質的 Nuxt 3 應用。
 
 ## 包含內容
 
-- 設計系統元件（Button、Card）
-- 基礎 Layout
+- 設計系統元件
+- 基礎 Layout 與路由設定
 - 全域樣式與設計 Tokens
-- 共用 Composables
-- 統一的開發工具配置（ESLint、Prettier、TypeScript）
+- 共用 Composables 與 Utils
+- 統一的開發工具配置（搭配 Nuxt 3 Eslint 等）
 
-## 使用方式
+## 使用情境一：在既有專案中使用 (Layer 繼承)
 
-在你的 Nuxt 應用中擴展此 Layer：
+如果你已經有一個 Nuxt 3 專案，你可以直接將此 Layer 擴展進你的專案中，藉此享有所有組件、功能和設定。
 
-```typescript
-// nuxt.config.ts
-export default defineNuxtConfig({
-  extends: ['@org/nuxt-core']
-})
-```
+1. **安裝依賴**
+
+   ```bash
+   npm install softleader-nuxt-core
+   ```
+
+2. **配置 `nuxt.config.ts`**
+
+   ```typescript
+   export default defineNuxtConfig({
+     extends: ["softleader-nuxt-core"],
+     // ... 其他你的專案設定
+   });
+   ```
+
+3. **啟用 ESLint / Prettier (選用)**
+   由於此專案依賴 `@nuxt/eslint-config`，建議你的專案也在根目錄設定對應的 Eslint 配置：
+   ```bash
+   npm i -D @nuxt/eslint-config eslint
+   ```
+   並在你的 `eslint.config.mjs` 中繼承 Nuxt 預設配置。
+
+---
+
+## 使用情境二：快速建立全新專案 (Scaffolding CLI)
+
+如果你想在一個新的（或空的）資料夾內建立完整包含 `softleader-nuxt-core` 的專案，我們提供了一個內建的命令列工具。
 
-## 開發
+1. **透過 npx 執行初始化腳本**
+   你可以直接使用 `npx` 搭配套件名稱，並指定你的專案名稱（例如 `my-new-app`）：
+
+   ```bash
+   npx softleader-nuxt-core init my-new-app
+   ```
+
+2. **進入專案並啟動**
+   指令執行完成後，請進入生成的專案資料夾並啟動開發伺服器：
+   ```bash
+   cd my-new-app
+   npm install # 若 CLI 尚未安裝完畢
+   npm run dev
+   ```
+   這會自動生成 `package.json`、`app.vue`、`nuxt.config.ts` 等必要檔案，並且已經預先設定好 `extends: ['softleader-nuxt-core']`。
+
+---
+
+## 開發 Core Layer 說明
+
+若你是 `softleader-nuxt-core` 的開發者：
 
 ```bash
 # 安裝依賴
@@ -33,3 +74,18 @@ npm run lint
 # 型別檢查
 npm run typecheck
 ```
+
+### 發布至 npm
+
+為了讓其他開發者能透過 `npx` 使用此腳本或載入此 Layer，您必須將本專案發布到 npm registry。
+
+1. **更新版本號**：確保 `package.json` 中的 `version` 已更新。
+2. **登入 npm** (若尚未登入)：
+   ```bash
+   npm login
+   ```
+3. **發布套件**：
+   ```bash
+   npm publish
+   ```
+   _(若是發布到公司私有 registry，請確認 `.npmrc` 中有設定正確的 registry url)_

package/bin/init.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execSync } from 'node:child_process'
+import { parseArgs } from 'node:util'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+const options = {
+  help: {
+    type: 'boolean',
+    short: 'h'
+  }
+}
+
+const { values, positionals } = parseArgs({ options, allowPositionals: true })
+
+if (values.help) {
+  console.log(`
+用法 (Usage): npx softleader-nuxt-core init [project-name]
+
+參數 (Arguments):
+  [project-name]  要建立的專案資料夾名稱 (預設: my-nuxt-app)
+
+選項 (Options):
+  -h, --help      顯示此幫助訊息
+`)
+  process.exit(0)
+}
+
+// 取得專案名稱，預設為 my-nuxt-app
+const projectName = positionals[0] || 'my-nuxt-app'
+// 解析出目標資料夾的絕對路徑
+const targetDir = path.resolve(process.cwd(), projectName)
+// 產生合法的 npm package name (轉小寫並移除非英數字元)
+const packageName = path.basename(targetDir).toLowerCase().replace(/[^a-z0-9-]/g, '') || 'my-nuxt-app'
+
+// 檢查資料夾是否已存在
+if (fs.existsSync(targetDir)) {
+  console.error(`錯誤 (Error): 目錄 "${projectName}" 已經存在。`)
+  process.exit(1)
+}
+
+console.log(`開始在 ${targetDir} 建立 Nuxt 3 專案...`)
+
+// 1. 建立目標資料夾
+fs.mkdirSync(targetDir, { recursive: true })
+
+// 2. 建立 package.json
+const packageJson = {
+  name: packageName,
+  version: "1.0.0",
+  private: true,
+  type: "module",
+  scripts: {
+    "build": "nuxt build",
+    "dev": "nuxt dev",
+    "generate": "nuxt generate",
+    "preview": "nuxt preview",
+    "postinstall": "nuxt prepare"
+  },
+  dependencies: {
+    "softleader-nuxt-core": "latest"
+  },
+  devDependencies: {
+    "nuxt": "^3.15.4",
+    "vue": "latest",
+    "vue-router": "latest"
+  }
+}
+
+fs.writeFileSync(
+  path.join(targetDir, 'package.json'),
+  JSON.stringify(packageJson, null, 2)
+)
+
+// 3. 建立 nuxt.config.ts (預設繼承 softleader-nuxt-core Layer)
+const nuxtConfigTs = `// https://nuxt.com/docs/api/configuration/nuxt-config
+export default defineNuxtConfig({
+  extends: ['softleader-nuxt-core'],
+  compatibilityDate: '2024-04-03',
+  devtools: { enabled: true }
+})
+`
+fs.writeFileSync(path.join(targetDir, 'nuxt.config.ts'), nuxtConfigTs)
+
+// 4. 建立基礎的 app.vue
+const appVue = `<template>
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>
+`
+fs.writeFileSync(path.join(targetDir, 'app.vue'), appVue)
+
+// 5. 建立範例頁面 pages/index.vue
+const pagesDir = path.join(targetDir, 'pages')
+fs.mkdirSync(pagesDir)
+const indexVue = `<template>
+  <IStack vertical justify="center" align="center" class="min-h-screen bg-gray-50 p-6">
+    <ICard class="w-full max-w-2xl px-8 py-10 text-center shadow-lg rounded-2xl">
+      <IIcon name="heroicons:rocket-launch" class="text-6xl text-primary-500 mb-6 mx-auto" />
+      <h1 class="text-3xl font-bold text-gray-800 mb-4">歡迎使用 Softleader Nuxt Core!</h1>
+      <p class="text-gray-600 mb-8 leading-relaxed">
+        您的專案已經成功建立。現在你可以直接使用 Layer 內建的設計系統元件，加速你的開發流程。
+      </p>
+      
+      <IAlert type="success" show-icon class="mb-8 text-left">
+        <strong>準備就緒！</strong> 嘗試編輯 <code>pages/index.vue</code> 來查看熱更新效果。
+      </IAlert>
+
+      <IStack gap="4" justify="center">
+        <IButton type="primary" size="large" href="https://nuxt.com/docs" target="_blank">
+          <IIcon name="heroicons:book-open" class="mr-2" />
+          Nuxt 官方文件
+        </IButton>
+        <IButton variant="outlined" size="large" href="https://github.com" target="_blank">
+          <IIcon name="bx:bxl-github" class="mr-2" />
+          元件庫指南
+        </IButton>
+      </IStack>
+    </ICard>
+  </IStack>
+</template>
+`
+fs.writeFileSync(path.join(pagesDir, 'index.vue'), indexVue)
+
+// 6. 建立 tsconfig.json 以支援 TypeScript 型別檢查
+const tsconfig = `{
+  "extends": "./.nuxt/tsconfig.json"
+}
+`
+fs.writeFileSync(path.join(targetDir, 'tsconfig.json'), tsconfig)
+
+// 7. 初始化 Git 儲存庫並安裝 npm 依賴
+try {
+  console.log('正在安裝依賴，這可能需要一點時間 (Installing dependencies)...')
+  execSync('npm install', { cwd: targetDir, stdio: 'inherit' })
+  
+  console.log('正在初始化 Git 儲存庫 (Initializing git repository)...')
+  execSync('git init', { cwd: targetDir, stdio: 'ignore' })
+} catch (error) {
+  console.log('警告 (Warning): 自動安裝指令執行失敗。您可能需要手動進入資料夾執行 npm install。')
+}
+
+console.log(`
+專案 "${projectName}" 已準備就緒！
+
+下一步 (Next steps):
+  cd ${projectName}
+  npm run dev
+`)

package/components/uiInterface/IAlert.vue

@@ -37,7 +37,7 @@ withDefaults(defineProps<Props>(), {
         v-if="title"
         class="alert-title"
       >
-        {{ title }}
+        title：{{ title }}
       </div>
       <div class="alert-text">
         <slot>{{ text }}</slot>

package/composables/useApiRegistry.ts

@@ -0,0 +1,30 @@
+import type { App } from 'vue'
+
+/**
+ * API Registry (擴充運作模式)
+ * 
+ * 讓外部專案可以動態註冊自己的 Repository 到 $api 中
+ */
+class ApiRegistry {
+  private repositories: Record<string, any> = {}
+
+  /**
+   * 註冊 Repository
+   * @param name 模組名稱 (例如 'order')
+   * @param repository 實作物件
+   */
+  register(name: string, repository: any) {
+    this.repositories[name] = repository
+  }
+
+  /**
+   * 取得所有已註冊的 Repositories
+   */
+  getExports() {
+    return this.repositories
+  }
+}
+
+const registry = new ApiRegistry()
+
+export const useApiRegistry = () => registry

package/core/repositories/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Internal Repositories (預設空的)
+ * 
+ * 這裡只放 Core Layer 運作絕對必要的 Repository。
+ * 其餘業務邏輯應由 App 層透過 ApiRegistry 註冊。
+ */
+const internalRepositories = {}
+
+export default internalRepositories

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softleader-nuxt-core",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Nuxt 3 Core Layer - 可重用的基礎架構",
   "type": "module",
   "files": [
@@ -13,7 +13,6 @@
     "layouts",
     "modules",
     "plugins",
-    "repositories",
     "router",
     "scripts",
     "styles",
@@ -30,6 +29,9 @@
     ".": "./nuxt.config.ts",
     "./utils/scanner": "./router/routes-scanner.ts"
   },
+  "bin": {
+    "softleader-nuxt-core": "./bin/init.mjs"
+  },
   "scripts": {
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",

package/plugins/api.ts

@@ -1,27 +1,35 @@
-import repositories from '../repositories'
+import { useApiRegistry } from '../composables/useApiRegistry'
+import repositories from '../core/repositories'
 
 /**
- * API Plugin (整合層)
+ * API Plugin (整合層 - Registry 模式)
  *
  * 職責：
- * 1. 將 repositories (資料層) 掛載到 Nuxt App 實體
- * 2. 提供全域唯一的存取點 $api
- *
- * 使用範例：
- * ```ts
- * const { $api } = useNuxtApp()
- *
- * // 呼叫 User 模組
- * const { data: users } = await $api.user.getUsers()
- *
- * // 呼叫 Order 模組
- * const { data: order } = await $api.order.getOrderById(1)
- * ```
+ * 1. 初始化 API Registry
+ * 2. 預註冊 Core 層提供的基礎 Repositories
+ * 3. 提供全域唯一的存取點 $api
  */
 export default defineNuxtPlugin(() => {
+  const registry = useApiRegistry()
+
+  // 1. 預註冊 Core 層的 Repositories
+  if (repositories) {
+    Object.entries(repositories).forEach(([name, repo]) => {
+      registry.register(name, repo)
+    })
+  }
+
+  // 2. 建立一個 Proxy 物件，讓 $api 可以動態存取註冊進來的內容
+  // 這解決了「App 層註冊的內容，在 Core 層也能透過 $api 存取」的問題
+  const apiProxy = new Proxy({}, {
+    get(target, prop: string) {
+      return registry.getExports()[prop]
+    }
+  })
+
   return {
     provide: {
-      api: repositories
+      api: apiProxy
     }
   }
 })

package/.eslintrc.cjs

@@ -1,25 +0,0 @@
-module.exports = {
-  root: true,
-  env: {
-    browser: true,
-    node: true,
-    es2022: true
-  },
-  extends: [
-    '@nuxt/eslint-config',
-    'plugin:@typescript-eslint/recommended'
-  ],
-  parser: '@typescript-eslint/parser',
-  parserOptions: {
-    ecmaVersion: 2022,
-    sourceType: 'module'
-  },
-  plugins: ['@typescript-eslint'],
-  rules: {
-    // 自訂規則
-    'vue/multi-word-component-names': 'off',
-    '@typescript-eslint/no-explicit-any': 'warn',
-    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
-    'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off'
-  }
-}

package/.prettierrc

@@ -1,10 +0,0 @@
-{
-  "semi": false,
-  "singleQuote": true,
-  "tabWidth": 2,
-  "useTabs": false,
-  "trailingComma": "none",
-  "printWidth": 100,
-  "arrowParens": "avoid",
-  "endOfLine": "auto"
-}

package/repositories/index.ts

@@ -1,20 +0,0 @@
-import user from './modules/user'
-import auth from './modules/auth'
-
-
-/**
- * Repository Index (資料層)
- *
- * 職責：
- * 1. 自動掃描 modules 資料夾下的所有檔案
- * 2. 將它們打包成一個大物件匯出
- * 3. 不依賴 Nuxt，純粹的資料定義
- */
-
-const repositories = {
-  user,
-  auth,
-
-}
-
-export default repositories

package/repositories/modules/auth.ts

@@ -1,30 +0,0 @@
-
-import type { UseFetchOptions } from 'nuxt/app'
-
-// 定義 Client，指向 /auth (假設後端路由是 /api/auth)
-const api = useClient('/auth')
-
-export default {
-  /**
-   * 使用者登入
-   * @param credentials { username, password }
-   * @param options
-   */
-  login(credentials: any, options: UseFetchOptions<any> = {}) {
-    return api.post('/login', credentials, options)
-  },
-
-  /**
-   * 使用者登出 (如果有的話)
-   */
-  logout() {
-    return api.post('/logout')
-  },
-
-  /**
-   * 取得當前使用者資訊 (Session/Me)
-   */
-  getProfile() {
-    return api.get('/me')
-  }
-}

package/repositories/modules/user.ts

@@ -1,101 +0,0 @@
-
-import type { UseFetchOptions } from 'nuxt/app'
-import type { UserListResponse } from '../../types/api'
-
-type MaybeRef<T> = T | Ref<T>
-
-interface UserQueryParams {
-  page?: MaybeRef<number>
-  itemsPerPage?: MaybeRef<number>
-  q?: MaybeRef<string>
-}
-
-// 1. 定義 Client
-const api = useClient('/users')
-
-export default {
-  /**
-   * 取得使用者列表
-   * @param params - 查詢參數 (如分頁、搜尋關鍵字)
-   * @param options - 其他 Fetch 選項
-   * @returns List of users
-   */
-  getUsers(params: UserQueryParams = {}, options: UseFetchOptions<UserListResponse> = {}) {
-    return api.get<UserListResponse>('/', {
-      query: params,
-      ...options
-    })
-  },
-
-  /**
-   * 根據 ID 取得單一使用者
-   * @param id - 使用者 ID
-   * @returns User detail
-   */
-  getUserById(id: MaybeRef<number>) {
-    return api.get<any>(`/${unref(id)}`)
-  },
-
-  /**
-   * [範例] 建立使用者
-   * @param userData - 使用者資料物件
-   * @returns Created user data
-   */
-  createUser(userData: any) {
-    return api.post('/', userData)
-  },
-
-  /**
-   * [範例] 搜尋使用者
-   * @param keyword - 搜尋關鍵字
-   * @returns Search results
-   */
-  searchUsers(keyword: Ref<string>) {
-    return api.get('/search', {
-      query: { q: keyword },
-      watch: [keyword]
-    })
-  },
-
-  /**
-   * [範例] 更新使用者
-   * @param id - 使用者 ID
-   * @param userData - 更新的使用者資料
-   * @returns Updated user data
-   */
-  updateUser(id: number, userData: any) {
-    return api.put(`/${id}`, userData)
-  },
-
-  /**
-   * [範例] 刪除使用者
-   * @param id - 使用者 ID
-   * @returns Deletion result
-   */
-  deleteUser(id: number) {
-    return api.delete(`/${id}`)
-  },
-
-  /**
-   * [範例] 取得大量資料 (延遲載入)
-   * @returns Heavy data report
-   */
-  getHeavyData() {
-    // 注意：這裡是 /heavy-report，因為 api base 是 /users
-    // 假設 heavy-report 也是在 /users 下，否則需另外處理
-    // 原始碼是 useApi('/heavy-report')，這可能不在 /users 下
-    // 為了安全，這裡假設它是獨立的
-    // 如果是獨立的，應該用 useApi 或另外一個 useClient
-    // 這裡我判斷它可能是 /users/heavy-report 的筆誤，或者真的是 root level
-    // 為了保持功能，我這裡用 root client 處理 (假設它不是 users/*)
-    // 但原檔放在 user.ts 卻叫 /heavy-report 有點怪
-    // 我先維持原路徑：/heavy-report (不接在 /users 後面)
-
-    // 這裡特別展示：如何在 policy 模式下呼叫「外面」的 API
-    // 方法 1: 使用 useApi
-    // return useApi('/heavy-report', { lazy: true })
-
-    // 方法 2 (如果它其實是 user 報表):
-    return useApi('/heavy-report', { lazy: true })
-  }
-}