softleader-nuxt-core 1.0.9 → 1.2.0

package/README.md

@@ -1,91 +1,120 @@
-# Nuxt Core Layer (`softleader-nuxt-core`)
+[回到全域首頁](../../README.md)
 
-這是 Nuxt 3 Core Layer，提供可重用的基礎架構、元件和工具，協助開發團隊快速建立一致且高品質的 Nuxt 3 應用。
+# Nuxt Core 核心開發包 (`softleader-nuxt-core`)
 
-## 包含內容
+一個基於 Nuxt 3 的企業級 Layer 開發框架，提供可重用的基礎架構、元件與工具。
 
-- 設計系統元件
-- 基礎 Layout 與路由設定
-- 全域樣式與設計 Tokens
-- 共用 Composables 與 Utils
-- 統一的開發工具配置（搭配 Nuxt 3 Eslint 等）
+## 快速開始
 
-## 使用情境一：在既有專案中使用 (Layer 繼承)
+### 1. 安裝相依套件
 
-如果你已經有一個 Nuxt 3 專案，你可以直接將此 Layer 擴展進你的專案中，藉此享有所有組件、功能和設定。
+在你的 Nuxt 3 專案中執行：
 
-1. **安裝依賴**
+```bash
+npm install softleader-nuxt-core
+```
 
-   ```bash
-   npm install softleader-nuxt-core
-   ```
+### 2. 層級繼承 (Setup Layer)
 
-2. **配置 `nuxt.config.ts`**
+在你的 `nuxt.config.ts` 中擴寫核心層：
+
+```typescript
+export default defineNuxtConfig({
+  extends: ['softleader-nuxt-core']
+  // ... 其他專案設定
+})
+```
 
-   ```typescript
-   export default defineNuxtConfig({
-     extends: ["softleader-nuxt-core"],
-     // ... 其他你的專案設定
-   });
-   ```
+### 3. 配置產品參數 (Configuration)
 
-3. **啟用 ESLint / Prettier (選用)**
-   由於此專案依賴 `@nuxt/eslint-config`，建議你的專案也在根目錄設定對應的 Eslint 配置：
-   ```bash
-   npm i -D @nuxt/eslint-config eslint
-   ```
-   並在你的 `eslint.config.mjs` 中繼承 Nuxt 預設配置。
+在專案根目錄建立 `configs/default.json`。核心層會自動讀取此檔案並應用於全域。詳細配置請參考 **[環境與產品配置指南](#)**。
 
 ---
 
-## 使用情境二：快速建立全新專案 (Scaffolding CLI)
+## 開發指南 (Development Guide)
+
+為了讓開發人員能順利建立與維護專案，請參考以下文件循序漸進地了解核心功能：
+
+### 1. 核心架構與基礎 (Core Architecture & Basics)
+
+了解層級設計理念、如何透過繼承快速啟動，以及配置系統。
+
+- **[Nuxt Core 導論與介面理念 (README_TEAM.md)](./docs/README_TEAM.md)**
+- **[核心配置系統 (nuxt.schema.ts)](./nuxt.schema.ts)**
+- **[開發環境與 Playground 聯動 (README.md)](../../README.md)**
+
+### 2. UI 與組件規範 (UI & Component Standards)
+
+學習如何使用介面層組件，確保 UI 一致性與可替換性。
+
+- **[UI Interface 封裝理念 (IButton.vue)](./components/uiInterface/IButton.vue)**
+- **[設計系統與 Tokens (styles/)](./styles/)**
+- **[透傳屬性 ($attrs) 與彈性設計 (IDataTable.vue)](./components/uiInterface/IDataTable.vue)**
+
+### 3. 資料映射與業務邏輯 (Data Mapping & Logic)
+
+掌握自動化的資料層掃描與全域選項系統。
 
-如果你想在一個新的（或空的）資料夾內建立完整包含 `softleader-nuxt-core` 的專案，我們提供了一個內建的命令列工具。
+- **[Smart Client 與 API 請求 (useApi.ts)](./composables/useApi.ts)**
+- **[自動化儲存庫掃描 (repositories-scanner.ts)](./modules/repositories-scanner.ts)**
+- **[全域與本地選項管理 (useOptions.ts)](./composables/useOptions.ts)**
 
-1. **透過 npx 執行初始化腳本**
-   你可以直接使用 `npx` 搭配套件名稱，並指定你的專案名稱（例如 `my-new-app`）：
+### 4. 架構進階應用 (Advanced Layer Usage)
 
-   ```bash
-   npx softleader-nuxt-core init my-new-app
-   ```
+深入了解路由擴充、Mock Server 以及攔截器機制。
 
-2. **進入專案並啟動**
-   指令執行完成後，請進入生成的專案資料夾並啟動開發伺服器：
-   ```bash
-   cd my-new-app
-   npm install # 若 CLI 尚未安裝完畢
-   npm run dev
-   ```
-   這會自動生成 `package.json`、`app.vue`、`nuxt.config.ts` 等必要檔案，並且已經預先設定好 `extends: ['softleader-nuxt-core']`。
+- **[動態路由掃描 (routes-scanner.ts)](./router/routes-scanner.ts)**
+- **[API 請求與回應攔截器 (interceptors/)](./utils/api/interceptors/)**
+- **[純前端 Mock 機制實作 (useApi.ts)](./composables/useApi.ts)**
+
+### 5. 發布與維運 (Publish & Maintenance)
+
+了解如何維護核心包、發布至套件庫以及版本管理。
+
+- **[NPM 套件打包與發布流程 (package.json)](./package.json)**
+- **[Git 工作流與 Commit 規範 (README.md)](../../README.md)**
+- **[疑難排解與除錯指南 (error.ts)](./utils/api/error.ts)**
+- **[CLI 工具設計原理 - 為何 `init` 不放在 scripts？ (bin/init.mjs)](./bin/init.mjs)**
+  - **全域執行能力**：放到 `bin` 欄位，才能讓使用者在「沒有專案的空目錄」下，直接透過 `npx softleader-nuxt-core init` 從無到有建立專案。如果是 `scripts`，就必須先有專案且安裝了套件才能跑，這會有雞生蛋的問題。
+  - **系統整合**：`bin` 腳本（搭配 `#!/usr/bin/env node`）會被 npm 註冊為命令列工具，自動建立符號連結並賦予執行權限。
+  - **職責分離**：`scripts` 是給「當下這個專案」的開發者用的任務；而 `bin` 則是提供給「套件的使用者」在終端機呼叫的工具。
 
 ---
 
-## 開發 Core Layer 說明
+## 文件索引
 
-若你是 `softleader-nuxt-core` 的開發者：
+### 1. 核心手冊 (必讀)
 
-```bash
-# 安裝依賴
-npm install
+- **[團隊開發指南 (README_TEAM.md)](./docs/README_TEAM.md)**: 小組員如何快速上手與配置。
+- **[核心配置系統 (nuxt.schema.ts)](./nuxt.schema.ts)**: 配置項架構定義。
+- **[核心入口 (nuxt.config.ts)](./nuxt.config.ts)**: Layer 的主配置入口。
 
-# Lint
-npm run lint
+### 2. 結構參考
 
-# 型別檢查
-npm run typecheck
-```
+- **[產品配置腳本 (scripts/product-loader.ts)](./scripts/product-loader.ts)**: 處理 JSON 配置的載入核心。
+- **[自動掃描器 (modules/)](./modules/)**: Repositories 與 Options 的掃描實作。
+
+### 3. 元件與 Composable
+
+- **[介面層組件範例 (IButton)](./components/uiInterface/IButton.vue)**: 標準化組件實作。
+- **[核心 Composable (useApi)](./composables/useApi.ts)**: 統一的 API 連線封裝。
+- **[選項管理 (useOptions)](./composables/useOptions.ts)**: 全域選項代理實作。
+
+### 4. 設定檔優先級規則 (Configuration Precedence)
+
+當你在不同的地方定義了相同的變數時（例如 API URL 或逾時設定），系統會依照以下**嚴格的優先順序**覆蓋：
+
+1. **`.env` (最高)**：系統環境變數，通常由 CI/CD 或本地開發者手動設置。
+2. **`nuxt.config.ts` (次之)**：專案層級的 `runtimeConfig`。
+3. **`configs/default.json` (最底)**：全域的預設藍圖設置。
+
+> **最佳實踐**：請將「固定的開發結構設定（如模組開關）」寫進 JSON，將「隨環境變動的機敏資訊（如連線字串、API 端點）」寫進 `.env`。
+
+### 5. 資料串接
 
-### 發布至 npm
+- **[API 錯誤處理](./utils/api/error.ts)**: 統一的報錯處理機制。
+- **[認證攔截器](./utils/api/interceptors/request.ts)**: 處理 Header 注入邏輯。
 
-為了讓其他開發者能透過 `npx` 使用此腳本或載入此 Layer，您必須將本專案發布到 npm registry。
+### 5. 疑難排解
 
-1. **更新版本號**：確保 `package.json` 中的 `version` 已更新。
-2. **登入 npm** (若尚未登入)：
-   ```bash
-   npm login
-   ```
-3. **發布套件**：
-   ```bash
-   npm publish
-   ```
-   _(若是發布到公司私有 registry，請確認 `.npmrc` 中有設定正確的 registry url)_
+- **[Repository 型別修正範例 (repositories/user.ts)](../../apps/playground-app/repositories/user.ts)**: 解決 TS 推導問題的示範。

package/assets/css/layout.css

@@ -166,28 +166,64 @@ body {
 }
 
 /* Margin Utilities */
-.mt-sm { margin-top: var(--spacing-sm); }
-.mt-md { margin-top: var(--spacing-md); }
-.mt-lg { margin-top: var(--spacing-lg); }
-.mt-xl { margin-top: var(--spacing-xl); }
-.mt-2xl { margin-top: var(--spacing-2xl); }
-
-.mb-sm { margin-bottom: var(--spacing-sm); }
-.mb-md { margin-bottom: var(--spacing-md); }
-.mb-lg { margin-bottom: var(--spacing-lg); }
-.mb-xl { margin-bottom: var(--spacing-xl); }
-.mb-2xl { margin-bottom: var(--spacing-2xl); }
+.mt-sm {
+  margin-top: var(--spacing-sm);
+}
+.mt-md {
+  margin-top: var(--spacing-md);
+}
+.mt-lg {
+  margin-top: var(--spacing-lg);
+}
+.mt-xl {
+  margin-top: var(--spacing-xl);
+}
+.mt-2xl {
+  margin-top: var(--spacing-2xl);
+}
+
+.mb-sm {
+  margin-bottom: var(--spacing-sm);
+}
+.mb-md {
+  margin-bottom: var(--spacing-md);
+}
+.mb-lg {
+  margin-bottom: var(--spacing-lg);
+}
+.mb-xl {
+  margin-bottom: var(--spacing-xl);
+}
+.mb-2xl {
+  margin-bottom: var(--spacing-2xl);
+}
 
 /* Padding Utilities */
-.pt-sm { padding-top: var(--spacing-sm); }
-.pt-md { padding-top: var(--spacing-md); }
-.pt-lg { padding-top: var(--spacing-lg); }
-.pt-xl { padding-top: var(--spacing-xl); }
-
-.pb-sm { padding-bottom: var(--spacing-sm); }
-.pb-md { padding-bottom: var(--spacing-md); }
-.pb-lg { padding-bottom: var(--spacing-lg); }
-.pb-xl { padding-bottom: var(--spacing-xl); }
+.pt-sm {
+  padding-top: var(--spacing-sm);
+}
+.pt-md {
+  padding-top: var(--spacing-md);
+}
+.pt-lg {
+  padding-top: var(--spacing-lg);
+}
+.pt-xl {
+  padding-top: var(--spacing-xl);
+}
+
+.pb-sm {
+  padding-bottom: var(--spacing-sm);
+}
+.pb-md {
+  padding-bottom: var(--spacing-md);
+}
+.pb-lg {
+  padding-bottom: var(--spacing-lg);
+}
+.pb-xl {
+  padding-bottom: var(--spacing-xl);
+}
 
 /* Responsive Utilities */
 .hidden {