@udi-organization/udi-package 1.0.51 → 1.0.56

package/README.md

@@ -1,102 +1,345 @@
-# test1202
+# 前端套件”udi-pacakge”開發流程:
 
-測試用的 npm 套件，包含 React Button component 和實用工具函數。
+## 概述
 
-## 安裝
+前端專案共用套件 udi-package 開發規範
+目的:集中管理跨專案Component、Utils Function
+
+---
+
+## 架構說明
+
+### 編譯工具分工
+
+- **Rollup**: 編譯套件輸出為標準 npm 包格式
+- **Webpack**: 編譯 sandbox 本地開發環境,提供熱更新與套件獨立的即時預覽
+
+### 開發模式
+
+1. **正常開發模式**: 使用 npm 官方發布的套件版本
+2. **Link 開發模式**: 使用本地 udi-package 進行即時開發
+
+---
+
+## 資料夾結構
+
+```
+project-root/
+├── frontend-project/          # 前端專案
+│   ├── node_modules/
+│   ├── package.json
+│   └── .git/
+│       └── hooks/
+│           └── pre-push      # Git hook 防護
+└── udi-package/              # 共用套件 (與前端專案同層)
+    ├── src/
+    ├── dist/                 # Rollup 編譯輸出
+    └── package.json
+
+```
+
+⚠️ **重要**: `udi-package` 必須與前端專案放在同一層級,因為 Docker volume 需要使用固定路徑進行映射。
+
+---
+
+## 前置作業
+
+### 1. 資料夾配置
+
+將 `udi-package` 放置在與前端專案相同的目錄層級。
+
+### 2. 設置 Git Hook 防護
+
+在前端專案中執行以下命令:
+
+```bash
+nano .git/hooks/pre-push
+
+```
+
+貼上以下內容:
+
+```bash
+#!/bin/bash
+
+# 檢查 @udi-organization/udi-package 是否為 symlink (npm link)
+PACKAGE_PATH="node_modules/@udi-organization/udi-package"
+
+if [ -L "$PACKAGE_PATH" ]; then
+    echo "❌ 錯誤: 檢測到使用 npm link"
+    echo ""
+    echo "目前 @udi-organization/udi-package 是使用本地 link"
+    echo "請先執行以下命令切換回正式版本:"
+    echo ""
+    echo "  npm run get-udi-o"
+    echo ""
+    echo "或手動執行:"
+    echo "  npm uninstall @udi-organization/udi-package --legacy-peer"
+    echo "  npm install @udi-organization/udi-package@latest --legacy-peer"
+    echo ""
+    exit 1
+fi
+
+# 檢查通過
+echo "✓ 檢查通過: 未使用本地 link"
+exit 0
+
+```
+
+儲存並設置執行權限:
 
 ```bash
-npm install test1202
+# Ctrl+O (儲存) → Enter → Ctrl+X (退出)
+chmod +x .git/hooks/pre-push
+
 ```
 
-## 使用方式
+### 3. NPM 組織設定
+
+### 建立並加入組織
 
-### Button Component
+1. 建立個人 npm 帳號
+2. 由管理員邀請加入 `@udi-organization` 組織
+3. 執行登入:
+    
+    ```bash
+    npm login
+    
+    ```
+    
+    會自動開啟瀏覽器完成登入
+    
+4. 確認登入狀態:
+    
+    ```bash
+    npm whoami
+    
+    ```
+    
 
-```jsx
-import { Button } from 'test1202';
+---
 
-function App() {
-  return (
-    <div>
-      <Button onClick={() => alert('Clicked!')}>
-        Primary Button
-      </Button>
+## NPM Scripts 說明
 
-      <Button variant="secondary" onClick={() => console.log('Secondary')}>
-        Secondary Button
-      </Button>
+### 前端專案指令
 
-      <Button variant="success">
-        Success Button
-      </Button>
+```json
+{
+  "scripts": {
+    // 正常開發模式 自動取得最新版本udi-package - 使用 npm 官方套件
+    "dev": "npm i @udi-organization/udi-package@latest --legacy-peer && NODE_ENV=development webpack-dev-server --progress  --hot --mode=development --host=0.0.0.0",,
 
-      <Button variant="danger">
-        Danger Button
-      </Button>
+    // Link 開發模式 - 使用本地 udi-package
+    "dev-udi": "npm uninstall @udi-organization/udi-package --legacy-peer && cd ../udi-package && sudo npm link && cd ../build && npm link @udi-organization/udi-package --legacy-peer && npm run dev",
 
-      <Button disabled>
-        Disabled Button
-      </Button>
-    </div>
-  );
+    // 切換回正常模式 (不啟動專案) 也可用於取得最新版本udi-package
+    "get-udi-o": "npm i @udi-organization/udi-package@latest --legacy-peer",
+  }
 }
+
 ```
 
-#### Props
+### udi-package 套件指令
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `children` | `ReactNode` | - | 按鈕內容 |
-| `onClick` | `Function` | - | 點擊事件處理函數 |
-| `variant` | `'primary'` \| `'secondary'` \| `'success'` \| `'danger'` | `'primary'` | 按鈕樣式變體 |
-| `disabled` | `boolean` | `false` | 是否禁用按鈕 |
-| `className` | `string` | `''` | 自訂 CSS class |
+```json
+{
+  "scripts": {
+    // 監聽模式 - 自動編譯變更
+    "watch": "rollup -c --watch",
 
-### 工具函數
+    // 單次編譯
+    "build": "rollup -c",
 
-```javascript
-import { greet, add } from 'test1202';
+    // 發布新版本
+    "release": "自動更新版本號並發布至 npm"
+  }
+}
 
-console.log(greet('World')); // "Hello, World! 103"
-console.log(add(2, 3));      // 5
-console.log(add(10, 25));    // 35
 ```
 
-## 功能特色
+---
 
-- ✅ 同時支援 CommonJS 和 ES Modules
-- ✅ 包含多種按鈕樣式變體
-- ✅ 輕量且無額外依賴（除了 React peer dependency）
+## 開發流程
 
-## 開發
+### 情境一: 不需修改 udi-package
 
 ```bash
-# 安裝依賴
-npm install
-
-# 啟動開發環境
+# 直接啟動專案
 npm run dev
 
-# 建置套件
+```
+
+### 情境二: 需要開發 udi-package
+
+### 步驟 1: 啟動套件監聽
+
+在 `udi-package` 目錄執行:
+
+```bash
+npm run watch
+# 或單次編譯
 npm run build
+
 ```
 
-開發環境會在 `http://localhost:3000` 啟動，您可以在瀏覽器中即時預覽和測試 component。
+### 步驟 2: 啟動 Link 開發模式
 
-## 專案結構
+在前端專案目錄執行:
+
+```bash
+npm run dev-udi
 
 ```
-npmPackageTest/
-├── dev/              # 開發測試環境
-├── src/              # 原始碼
-│   ├── Button.jsx    # Button component
-│   └── index.js      # 主入口
-├── dist/             # 建置輸出
-│   ├── index.cjs.js  # CommonJS 版本
-│   └── index.esm.js  # ES Module 版本
-└── package.json
+
+### 步驟 3: 開發與測試
+
+- 修改 `udi-package/src` 中的程式碼
+- Rollup 會自動編譯至 `dist/` 目錄
+- 前端專案透過 link 即時取得更新
+
+### 步驟 4: 發布新版本
+
+⚠️ **發布前檢查**:
+
+- 確保所有變更已 commit
+- 不可有未被 Git 追蹤的檔案
+
+```bash
+# 在 udi-package 目錄
+git add .
+git commit -m "feat: 新功能說明"
+git push origin "new feature branch"
+npm run release
+
 ```
 
-## License
+---
+
+## Git 推送流程
+
+### 完整推送步驟
+
+1. **建立 Feature Branch**
+    
+    ```bash
+    git checkout -b feature/your-feature-name
+    
+    ```
+    
+2. **持續開發與提交**
+    
+    ```bash
+    git add .
+    git commit -m "feat: 功能描述"
+    git push origin feature/your-feature-name
+    
+    ```
+    
+3. **推送前切換回正常模式**
+    
+    ```bash
+    # 方法一: 只切換不啟動
+    npm run get-udi-o
+    
+    # 方法二: 切換並驗證專案
+    npm run dev
+    
+    ```
+    
+4. **驗證專案正常運作**
+    - 確認專案可正常啟動
+    - 確認功能運作正常
+    - 確認 package.json 包含正式的套件依賴
+5. **推送到 GitLab**
+    
+    ```bash
+    git push origin feature/your-feature-name
+    
+    ```
+    
+    > Git hook 會自動檢查是否為 link 模式,防止錯誤推送
+    > 
+6. **通過 Pipeline 後合併**
+    - 確認 GitLab CI/CD Pipeline 全部通過
+    - 提交 Merge Request 至 `dev` 分支
+    - Code Review 通過後合併
+
+---
+
+## 常見問題處理
+
+### Q1: 推送時出現 "檢測到使用 npm link" 錯誤
+
+**原因**: 目前處於 link 開發模式
+
+**解決**:
+
+```bash
+npm run get-udi-o
+# 或
+npm run dev  # 切換並驗證專案
+
+```
+
+### Q2: udi-package 修改後前端專案沒有更新
+
+**檢查項目**:
+
+1. 確認 `udi-package` 目錄是否執行 `npm run watch`
+2. 確認前端專案是否使用 `npm run dev-udi` 啟動
+3. 檢查編譯是否有錯誤訊息
+
+### Q3: npm link 權限問題
+
+**解決**: 使用 `sudo` 執行 link 指令
+
+```bash
+cd ../udi-package
+sudo npm link
+
+```
+
+### Q4: 發布失敗 - 未登入或權限不足
+
+**解決**:
+
+```bash
+npm login
+npm whoami  # 確認登入狀態
+
+```
+
+---
+
+## 快速參考
+
+### 常用指令速查
+
+| 情境 | 指令 |
+| --- | --- |
+| 正常開發 | `npm run dev` |
+| 開發套件 | `npm run dev-udi` |
+| 切換回正常模式 | `npm run get-udi-o` |
+| 套件監聽編譯 | `npm run watch` (在 udi-package) |
+| 發布新版本 | `npm run release` (在 udi-package) |
+| 檢查登入狀態 | `npm whoami` |
+
+### 檢查清單
+
+**開發前**
+
+- [ ]  udi-package 與專案在同層目錄
+- [ ]  Git hook 已設置
+- [ ]  npm 已登入正確組織
+
+**推送前**
+
+- [ ]  切換回正常模式 (`npm run get-udi-o`)
+- [ ]  專案可正常運作
+- [ ]  所有變更已 commit
+
+**發布套件前**
 
-ISC
+- [ ]  所有變更已 commit
+- [ ]  無未追蹤檔案
+- [ ]  npm 已登入