softleader-nuxt-core 1.2.0 → 2.2.0

package/composables/useFeatureFlag.ts

@@ -28,8 +28,11 @@ type FeaturePath =
  * @returns 功能是否啟用
  */
 function getFeatureValue(config: FeatureConfig): boolean {
+  // 安全檢查：確保是在 Node 環境或有 process polyfill
+  const hasProcess = typeof process !== 'undefined' && process.env
+
   // 優先使用環境變數
-  if (config.envKey) {
+  if (config.envKey && hasProcess) {
     const envValue = process.env[config.envKey]
     if (envValue !== undefined) {
       return envValue === 'true' || envValue === '1'
@@ -38,7 +41,7 @@ function getFeatureValue(config: FeatureConfig): boolean {
 
   // 檢查環境限制
   if (config.environments && config.environments.length > 0) {
-    const currentEnv = process.env.NODE_ENV || 'development'
+    const currentEnv = (hasProcess ? process.env.NODE_ENV : 'development') || 'development'
     const isAllEnvironments = config.environments.includes('all')
     const isCurrentEnvironment = config.environments.includes(
       currentEnv as 'development' | 'staging' | 'production'

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/core/config/theme-tokens.ts

@@ -1,7 +1,5 @@
 import { productConfig } from '../../scripts/product-loader'
 
-import { productConfig } from '../../scripts/product-loader'
-
 /**
  * 全域主題設計變數 (Design Tokens)
  * 供 Vuetify、Tailwind 或其他 UI 框架共用的基礎變數

package/layouts/default.vue

@@ -1,43 +1,43 @@
 <template>
   <div class="layout-default">
     <!-- Header: 頂部導覽列 -->
-    <header v-if="layout.header.visible" class="header" :style="{ height: `${layout.header.height}px` }">
+    <header v-if="layout?.header?.visible" class="header" :style="{ height: `${layout?.header?.height || 64}px` }">
       <div class="container d-flex align-center justify-space-between h-100">
         <div class="branding d-flex align-center gap-2">
-          <IIcon v-if="layout.branding.logo.icon && !layout.branding.logo.image" :name="layout.branding.logo.icon" size="28" color="primary" />
-          <img v-if="layout.branding.logo.image" :src="layout.branding.logo.image" class="logo-img" alt="logo" />
+          <IIcon v-if="layout?.branding?.logo?.icon && !layout?.branding?.logo?.image" :name="layout.branding.logo.icon" size="28" color="primary" />
+          <img v-if="layout?.branding?.logo?.image" :src="layout.branding.logo.image" class="logo-img" alt="logo" />
           <div class="branding-text">
-            <h1 class="logo-title">{{ layout.branding.title }}</h1>
-            <p v-if="layout.branding.subtitle" class="logo-subtitle">{{ layout.branding.subtitle }}</p>
+            <h1 class="logo-title">{{ layout?.branding?.title }}</h1>
+            <p v-if="layout?.branding?.subtitle" class="logo-subtitle">{{ layout.branding.subtitle }}</p>
           </div>
         </div>
 
         <div class="actions d-flex align-center gap-4">
           <!-- 搜尋框 -->
-          <div v-if="layout.header.search" class="search-bar">
-            <input type="text" :placeholder="layout.header.searchPlaceholder" />
+          <div v-if="layout?.header?.search" class="search-bar">
+            <input type="text" :placeholder="layout?.header?.searchPlaceholder" />
           </div>
 
           <slot name="header-actions" />
 
           <!-- 使用者選單按鈕 (示意) -->
-          <div v-if="layout.header.userMenu.visible" class="user-action">
+          <div v-if="layout?.header?.userMenu?.visible" class="user-action">
             <IIcon name="mdi-account-circle" size="32" class="cursor-pointer" />
           </div>
         </div>
       </div>
     </header>
 
-    <main class="main" :class="{ 'has-header': layout.header.visible }">
+    <main class="main" :class="{ 'has-header': layout?.header?.visible }">
       <div class="container py-10">
         <slot />
       </div>
     </main>
 
     <!-- Footer: 頁尾 -->
-    <footer v-if="layout.footer.visible" class="footer">
+    <footer v-if="layout?.footer?.visible" class="footer">
       <div class="container">
-        <div class="footer-content" v-html="layout.footer.content"></div>
+        <div class="footer-content" v-html="layout?.footer?.content"></div>
       </div>
     </footer>
   </div>
@@ -57,24 +57,25 @@ const layout = computed(() => core.layout)
 useHead({
   style: [
     {
-      innerHTML: `
+      innerHTML: computed(() => `
         :root {
           /* 基礎語意色彩 */
-          --color-primary: ${themeConfig.colors.primary};
-          --color-success: ${themeConfig.colors.success};
-          --color-warning: ${themeConfig.colors.warning};
-          --color-error: ${themeConfig.colors.error};
-          --color-info: ${themeConfig.colors.info};
+          --color-primary: ${layout.value?.theme?.primaryColor || core.theme?.primaryColor || themeConfig.colors.primary};
+          --color-primary-alpha: ${layout.value?.theme?.primaryColor || core.theme?.primaryColor || themeConfig.colors.primary}40;
+          --color-success: ${core.theme?.successColor || themeConfig.colors.success};
+          --color-warning: ${core.theme?.warningColor || themeConfig.colors.warning};
+          --color-error: ${core.theme?.errorColor || themeConfig.colors.error};
+          --color-info: ${core.theme?.infoColor || themeConfig.colors.info};
           
           /* 覆寫 main.css 中的特定變數以達成 100% 連動 */
-          --color-primary-600: ${themeConfig.colors.primary};
-          --color-primary-500: ${themeConfig.colors.primary}e6; /* 加入透明度模擬 */
+          --color-primary-600: ${layout.value?.theme?.primaryColor || core.theme?.primaryColor || themeConfig.colors.primary};
+          --color-primary-500: ${layout.value?.theme?.primaryColor || core.theme?.primaryColor || themeConfig.colors.primary}e6; /* 加入透明度模擬 */
           
           /* 基礎圓角 */
-          --radius-md: ${themeConfig.shape.borderRadius}px;
-          --radius-lg: ${themeConfig.shape.borderRadius + 4}px;
+          --radius-md: ${core.theme?.borderRadius || themeConfig.shape.borderRadius}px;
+          --radius-lg: ${(core.theme?.borderRadius || themeConfig.shape.borderRadius) + 4}px;
         }
-      `
+      `)
     }
   ]
 })

package/nuxt.config.ts

@@ -23,6 +23,22 @@ const { resolve } = createResolver(import.meta.url)
 export default defineNuxtConfig({
   ssr: false,
 
+  // Server-side Log
+  hooks: {
+    ready: () => {
+      console.log('🚀 Nuxt Core started with product:', productConfig.meta?.title, 'Color:', productConfig.theme?.primaryColor)
+    }
+  },
+
+  /** 支援配置驅動：監控 JSON 變動並自動重啟伺服器 (即改即變) */
+  watch: [
+    'configs/*.json',
+    'configs/**/*.json',
+    // 使用絕對路徑確保在不同 CWD 下都能監控到目前專案的 configs
+    `${process.cwd()}/configs/*.json`,
+    `${process.cwd()}/configs/**/*.json`
+  ],
+
   compatibilityDate: '2024-04-03',
 
   /** 編譯與打包設定 */
@@ -61,7 +77,8 @@ export default defineNuxtConfig({
       app: {
         ...projectRuntimeConfig.public.app,
         uaIdentifier:
-          projectRuntimeConfig.public.app.uaIdentifier || productConfig.branding?.uaIdentifier
+          projectRuntimeConfig.public.app.uaIdentifier || productConfig.branding?.uaIdentifier,
+        productConfig
       },
       // 將 JSON 裡的網路設定同步到 runtimeConfig (環境變數優先)
       api: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softleader-nuxt-core",
-  "version": "1.2.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",
@@ -53,7 +54,7 @@
     "typecheck": "nuxi typecheck",
     "sync-configs": "node scripts/sync-configs.mjs",
     "release": "node scripts/release.mjs",
-    "test:init": "npm pack && node bin/init.mjs init tmp-test-project && rm *.tgz"
+    "test:init": "npm pack && node bin/init.mjs init ${1:-tmp-test-project} && rm *.tgz"
   },
   "dependencies": {
     "@nuxt/eslint-config": "^0.5.7",

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/product-loader.ts

@@ -121,34 +121,107 @@ export interface ProductConfig {
  * @param rootDir 專案根目錄 (預設抓目前位置)
  * @returns 讀到的設定內容
  */
-export function getProductConfig(rootDir: string = process.cwd()): ProductConfig {
+export function getProductConfig(rootDir?: string): ProductConfig {
+  // 核心預設結構，確保不會噴 undefined 錯誤 (visible, enabled 等)
+  let config: ProductConfig = {
+    branding: {},
+    meta: {},
+    layout: {
+      header: { visible: true },
+      footer: { visible: true },
+      sidebar: { visible: true }
+    },
+    theme: {},
+    network: {},
+    features: {},
+    auth: {},
+    modules: {}
+  }
+
+  // 如果是在瀏覽器環境，直接回傳預設結構 (瀏覽器應該透過 useAppConfig 取得)
+  if (typeof process === 'undefined' || !process.cwd) {
+    return config
+  }
+
+  // 診斷日誌：寫入檔案以便查閱 (因為看見不到終端機)
+  const debugLog = (msg: string) => {
+    try {
+      fs.appendFileSync('c:\\Users\\gino.huang\\Desktop\\nuxt-layer-core-playground\\product-loader-debug.log', `[${new Date().toISOString()}] ${msg}\n`)
+    } catch (e) {}
+    console.log(msg)
+  }
+  debugLog(`>>> getProductConfig start. CWD: ${process.cwd()}, ENV: Ref=${process.env.npm_package_name}`)
+
   // 1. 決定要讀哪個設定檔
-  // 可以在 package.json 裡面用 cross-env PRODUCT_CONFIG=xxx 來指定
   const productConfigName = process.env.PRODUCT_CONFIG || 'default'
 
-  // 2. 算出檔案在哪裡
-  const configPath = path.resolve(rootDir, 'configs', `${productConfigName}.json`)
+  // 2. 智慧路徑搜尋：找出最近的 configs/ 資料夾
+  // 我們會檢查：
+  // A. 目前執行目錄 (CWD) 下的 configs/
+  // B. 往上找 5 層 (適用於從根目錄跑 workspace 指令的情況)
+  let currentSearchDir = process.cwd()
+  let configPath = ''
+
+  console.log(`[Config Debug] CWD: ${currentSearchDir}`)
+
+  for (let i = 0; i < 5; i++) {
+    const targetPath = path.resolve(currentSearchDir, 'configs', `${productConfigName}.json`)
+    debugLog(`[Config Path Check ${i}] ${targetPath}`)
+    
+    if (fs.existsSync(targetPath)) {
+      configPath = targetPath
+      break
+    }
+
+    // 額外支援：如果在根目錄跑，嘗試找 apps/${npm_package_name}/configs
+    if (i === 0) {
+      const activePackage = process.env.npm_package_name
+      const appsDir = path.resolve(currentSearchDir, 'apps')
+      debugLog(`[Config Context Check] Package: ${activePackage}, appsDir: ${appsDir}`)
+      
+      if (activePackage && fs.existsSync(path.resolve(appsDir, activePackage))) {
+        const appConfigPath = path.resolve(appsDir, activePackage, 'configs', `${productConfigName}.json`)
+        debugLog(`[Config Workspace Check] ${appConfigPath}`)
+        if (fs.existsSync(appConfigPath)) {
+          configPath = appConfigPath
+          break
+        }
+      }
 
-  // 預設給一個空的，免得找不到檔案時出錯
-  let config: ProductConfig = { modules: {} }
+      if (!configPath && fs.existsSync(appsDir)) {
+        const apps = fs.readdirSync(appsDir)
+        for (const app of apps) {
+          const appConfigPath = path.resolve(appsDir, app, 'configs', `${productConfigName}.json`)
+          if (fs.existsSync(appConfigPath)) {
+             configPath = appConfigPath
+             break 
+          }
+        }
+      }
+    }
+    
+    if (configPath) break
+
+    const nextDir = path.dirname(currentSearchDir)
+    if (nextDir === currentSearchDir) break
+    currentSearchDir = nextDir
+  }
 
-  // 3. 真的去讀檔案
-  if (fs.existsSync(configPath)) {
+  if (configPath) {
+    debugLog(`[Config Success] 最終確認讀取路徑: ${configPath}`)
     try {
       const fileContents = fs.readFileSync(configPath, 'utf8')
       const loaded = JSON.parse(fileContents)
 
-      // 有讀到東西就合併進去
       if (loaded) {
         config = { ...config, ...loaded }
+        debugLog(`[Config Success] 載入內容: title=${config.meta?.title}, color=${config.theme?.primaryColor}`)
       }
-      console.log(`[Config] 成功載入設定: ${productConfigName}`)
     } catch (e) {
-      console.error(`[Config] 讀取設定失敗 ${configPath}:`, e)
+      debugLog(`[Config Error] 讀取 JSON 失敗 ${configPath}: ${e}`)
     }
   } else {
-    // 找不到檔案，提醒一下
-    console.warn(`[Config] 找不到設定檔: ${configPath}，將不載入任何模組。`)
+    debugLog(`[Config Warning] 在任何路徑中都找不到 ${productConfigName}.json`)
   }
 
   return config

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)
+}

package/stores/app.ts

@@ -2,8 +2,31 @@ import { defineStore } from 'pinia'
 import { defaultLayoutConfig, type LayoutConfig } from '../core/config/layout'
 
 export const useAppStore = defineStore('app', () => {
-  // 狀態
-  const config = ref<LayoutConfig>({ ...defaultLayoutConfig })
+  const appConfig = useAppConfig()
+  const coreConfig = appConfig.core as any
+
+  // 狀態：從 appConfig.core 獲取初始值，若無則回退到 defaultLayoutConfig
+  const config = ref<LayoutConfig>({ 
+    ...defaultLayoutConfig,
+    ...(coreConfig?.layout || {}),
+    // 深度處理特定區塊
+    theme: {
+      ...defaultLayoutConfig.theme,
+      ...(coreConfig?.theme || {})
+    },
+    header: {
+      ...defaultLayoutConfig.header,
+      ...(coreConfig?.layout?.header || {})
+    },
+    footer: {
+      ...defaultLayoutConfig.footer,
+      ...(coreConfig?.layout?.footer || {})
+    },
+    sidebar: {
+      ...defaultLayoutConfig.sidebar,
+      ...(coreConfig?.layout?.sidebar || {})
+    }
+  })
   const drawer = ref(true)
   const loading = ref(false)