softleader-nuxt-core 2.0.0 → 2.2.0

package/composables/useModules.ts

@@ -1,18 +1,18 @@
-/**
- * 核心邏輯模組入口 (Centralized Logic Modules Entry)
- * 提供專案規範中要求的核心 Composable。
- */
-export function useModules() {
-  return {
-    /** 分頁管理 */
-    usePagination,
-    /** API 請求 */
-    useApi,
-    /** 檔案下載 */
-    useFileDownload,
-    /** 檔案上傳 */
-    useFileUpload,
-    /** 資料驗證 */
-    useValidation
-  }
-}
+/**
+ * 核心邏輯模組入口 (Centralized Logic Modules Entry)
+ * 提供專案規範中要求的核心 Composable。
+ */
+export function useModules() {
+  return {
+    /** 分頁管理 */
+    usePagination,
+    /** API 請求 */
+    useApi,
+    /** 檔案下載 */
+    useFileDownload,
+    /** 檔案上傳 */
+    useFileUpload,
+    /** 資料驗證 */
+    useValidation
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softleader-nuxt-core",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Nuxt 3 Core Layer - 可重用的基礎架構",
   "type": "module",
   "files": [
@@ -19,6 +19,7 @@
     "utils",
     "stores",
     "types",
+    "repositories",
     "bin",
     "schemas",
     "nuxt.config.ts",

package/repositories/index.ts

@@ -0,0 +1,18 @@
+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

@@ -0,0 +1,29 @@
+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

@@ -0,0 +1,100 @@
+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 })
+  }
+}

package/scripts/release.mjs

@@ -1,24 +1,24 @@
-import { execSync } from 'child_process'
-
-/**
- * 自動化發布腳本
- * 用法:
- *   npm run release         (預設 patch: 1.1.0 -> 1.1.1)
- *   npm run release minor   (1.1.0 -> 1.2.0)
- *   npm run release major   (1.1.0 -> 2.0.0)
- */
-
-const type = process.argv[2] || 'patch'
-
-try {
-  console.log(`\n\x1b[36m[Release] Step 1: Bumping version (${type})...\x1b[0m`)
-  execSync(`npm version ${type} --no-git-tag-version`, { stdio: 'inherit' })
-
-  console.log(`\n\x1b[36m[Release] Step 2: Publishing to npm...\x1b[0m`)
-  execSync('npm publish', { stdio: 'inherit' })
-
-  console.log('\n\x1b[32m[Release] Successfully published! 🎉\x1b[0m\n')
-} catch (error) {
-  console.error('\n\x1b[31m[Release] Failed to publish:\x1b[0m', error.message)
-  process.exit(1)
-}
+import { execSync } from 'child_process'
+
+/**
+ * 自動化發布腳本
+ * 用法:
+ *   npm run release         (預設 patch: 1.1.0 -> 1.1.1)
+ *   npm run release minor   (1.1.0 -> 1.2.0)
+ *   npm run release major   (1.1.0 -> 2.0.0)
+ */
+
+const type = process.argv[2] || 'patch'
+
+try {
+  console.log(`\n\x1b[36m[Release] Step 1: Bumping version (${type})...\x1b[0m`)
+  execSync(`npm version ${type} --no-git-tag-version`, { stdio: 'inherit' })
+
+  console.log(`\n\x1b[36m[Release] Step 2: Publishing to npm...\x1b[0m`)
+  execSync('npm publish', { stdio: 'inherit' })
+
+  console.log('\n\x1b[32m[Release] Successfully published! 🎉\x1b[0m\n')
+} catch (error) {
+  console.error('\n\x1b[31m[Release] Failed to publish:\x1b[0m', error.message)
+  process.exit(1)
+}