情境：小明要修改登入功能
傳統方式：複製整個專案資料夾 → 容易混亂
Git 方式：建立 feature/login-improvement 分支 → 清楚管理

git --version

# 使用 Homebrew
brew install git

# 或使用 Xcode Command Line Tools
xcode-select --install

### 設定使用者名稱（顯示在 commit 中）
git config --global user.name "您的姓名"

### 設定電子郵件（建議使用公司信箱）
git config --global user.email "your.email@company.com"

### 驗證設定
git config --list

### 1. 產生 SSH 金鑰
ssh-keygen -t ed25519 -C "your.email@company.com"

### 2. 啟動 SSH agent
eval "$(ssh-agent -s)"

### 3. 新增金鑰到 agent
ssh-add ~/.ssh/id_ed25519

### 4. 複製公鑰內容
cat ~/.ssh/id_ed25519.pub

ssh -T git@github.com

### 啟用平行處理
git config --global pack.threads 0
git config --global index.threads 0

### 提升 push/fetch 效能
git config --global pack.packSizeLimit 2g
git config --global pack.windowMemory 256m

### 啟用檔案系統監控（Windows）
git config --global core.fsmonitor true
git config --global core.untrackedcache true

### 設定 partial clone（僅克隆需要的部分）
git clone --filter=blob:none <url>

### 設定淺層克隆（減少歷史記錄）
git clone --depth 1 <url>

### 僅下載指定分支
git clone --single-branch --branch <branch> <url>

### 增加緩衝區大小
git config --global http.postBuffer 524288000

### 設定連線超時
git config --global http.lowSpeedLimit 1000
git config --global http.lowSpeedTime 300

### 啟用 HTTP/2
git config --global http.version HTTP/2

### 使用 SSH（推薦）
git clone git@github.com:your-organization/project-name.git

### 使用 HTTPS
git clone <https://github.com/your-organization/project-name.git>

### 進入專案目錄
cd project-name

### 查看目前遠端設定
git remote -v

### 新增上游倉庫（用於同步主分支）
git remote add upstream git@github.com:main-organization/project-name.git

### 功能開發
feature/功能名稱-簡短描述
feature/user-login-validation
feature/payment-integration

### 錯誤修復
bugfix/錯誤描述
bugfix/login-session-timeout
bugfix/payment-calculation-error

### 熱修復
hotfix/緊急修復描述
hotfix/security-vulnerability

### 文件更新
docs/文件類型
docs/api-documentation
docs/user-guide

### 1. 確保在主分支並取得最新版本
git checkout main
git pull origin main

### 2. 建立並切換到新分支
git checkout -b feature/user-profile-update

### 3. 確認目前分支
git branch

<類型>[可選範圍]: <描述>

[可選本文]

[可選註腳]

### ✅ 良好的 commit message
git commit -m "feat: 新增使用者密碼強度驗證功能

- 實作密碼複雜度檢查
- 新增密碼強度指示器
- 更新相關測試案例

Closes #123"

### ❌ 不良的 commit message
git commit -m "修改"
git commit -m "update code"
git commit -m "fix bug"

### 1. 檢查工作目錄狀態
git status

### 2. 新增變更檔案
git add .                    # 新增所有變更
git add src/main/User.java   # 新增特定檔案

### 3. 提交變更
git commit -m "feat: 新增使用者註冊功能"

### 4. 推送到遠端分支
git push origin feature/user-registration

### 5. 首次推送設定上游分支
git push -u origin feature/user-registration

## 📋 變更摘要
簡述這個 PR 的目的和主要變更

## 🔧 變更內容
- [ ] 新增使用者註冊 API
- [ ] 實作 email 驗證功能
- [ ] 新增相關單元測試
- [ ] 更新 API 文件

## 🧪 測試
- [ ] 單元測試已通過
- [ ] 整合測試已通過
- [ ] 手動測試已完成

## 📸 截圖/影片
（如果是 UI 變更，請附上截圖）

## 🔗 相關 Issue
Closes #123
Related to #456

[類型] 簡短描述 (#Issue編號)

範例：
[Feature] 新增使用者註冊功能 (#123)
[Bugfix] 修復登入驗證錯誤 (#456)
[Docs] 更新 API 使用說明 (#789)

完整開發流程範例：

1. 接到任務：開發使用者頭像上傳功能
2. 建立分支：git checkout -b feature/user-avatar-upload
3. 開發程式碼：實作上傳邏輯、API、測試
4. 提交變更：git commit -m "feat: 新增使用者頭像上傳功能"
5. 推送分支：git push origin feature/user-avatar-upload
6. 建立 PR：填寫完整的 PR 描述
7. 程式碼審查：修正審查者建議
8. 合併到主分支：使用 Squash Merge
9. 刪除分支：清理遠端和本地分支

### 重新整理最近 3 個 commit
git rebase -i HEAD~3

### 重新整理到指定 commit
git rebase -i <commit-hash>

pick    - 保留 commit
reword  - 修改 commit message
edit    - 修改 commit 內容
squash  - 合併到前一個 commit
fixup   - 合併到前一個 commit（不保留 message）
drop    - 刪除 commit

### 情境：合併多個小 commit 成一個功能 commit
git rebase -i HEAD~4

### 編輯器會開啟，修改為：
### pick 1234567 feat: 新增登入功能框架
### squash 2345678 feat: 加入密碼驗證
### squash 3456789 feat: 加入錯誤處理
### squash 4567890 feat: 新增單元測試

### 將特定 commit 應用到當前分支
git cherry-pick <commit-hash>

### 應用多個 commit
git cherry-pick <commit1> <commit2>

### 應用一個範圍的 commit
git cherry-pick <commit1>..<commit2>

### 場景1：緊急修復需要應用到多個分支
git checkout main
git cherry-pick <hotfix-commit-hash>

git checkout develop
git cherry-pick <hotfix-commit-hash>

### 場景2：選擇性合併功能
git checkout feature-branch
git cherry-pick <specific-feature-commit>

### 開始 bisect
git bisect start

### 標記當前版本為有問題的版本
git bisect bad

### 標記某個已知正常的版本
git bisect good <good-commit-hash>

### Git 會自動切換到中間的 commit
### 測試後標記結果
git bisect good  # 或 git bisect bad

### 重複直到找到問題 commit
### 結束 bisect
git bisect reset

### 使用腳本自動化 bisect
git bisect start HEAD <good-commit>
git bisect run ./test-script.sh

### test-script.sh 範例
#!/bin/bash
make test
if [ $? -eq 0 ]; then
    exit 0  # 測試通過
else
    exit 1  # 測試失敗
fi

### 暫存當前變更
git stash

### 暫存包含新檔案
git stash -u

### 暫存並添加訊息
git stash push -m "暫存登入功能開發中的變更"

### 查看 stash 列表
git stash list

### 應用最近的 stash
git stash pop

### 應用特定的 stash
git stash apply stash@{1}

### 刪除 stash
git stash drop stash@{0}

### 僅 stash 特定檔案
git stash push -m "僅暫存設定檔" config.js

### 建立新分支並應用 stash
git stash branch new-feature-branch stash@{0}

### 查看 stash 的差異
git stash show -p stash@{0}

### 添加子模組
git submodule add <repository-url> <path>

### 例如
git submodule add <https://github.com/user/library.git> lib/library

### Clone 包含子模組的專案
git clone --recursive <repository-url>

### 或先 clone 再初始化子模組
git clone <repository-url>
git submodule init
git submodule update

### 更新子模組
git submodule update --remote

### 更新特定子模組
git submodule update --remote lib/library

### 總是記錄子模組的具體版本
cd lib/library
git checkout <specific-commit-or-tag>
cd ../..
git add lib/library
git commit -m "更新library到v1.2.3"

### 移除子模組
git submodule deinit lib/library
git rm lib/library
rm -rf .git/modules/lib/library

#!/bin/sh
### .git/hooks/pre-commit

### 檢查程式碼格式
if ! npm run lint; then
    echo "代碼格式檢查失敗，請修正後再commit"
    exit 1
fi

### 執行測試
if ! npm test; then
    echo "測試失敗，請修正後再commit"
    exit 1
fi

echo "Pre-commit 檢查通過"

#!/bin/sh
### .git/hooks/pre-push

### 檢查分支命名規範
branch=$(git rev-parse --abbrev-ref HEAD)
valid_pattern="^(feature|bugfix|hotfix)\/[a-z0-9-]+$"

if [[ ! $branch =~ $valid_pattern ]]; then
    echo "分支名稱不符合規範: $branch"
    echo "請使用格式: feature/feature-name"
    exit 1
fi

echo "Pre-push 檢查通過"

### 安裝 Git LFS
git lfs install

### 追蹤特定類型的檔案
git lfs track "*.psd"
git lfs track "*.mp4"
git lfs track "*.zip"

### 查看追蹤的檔案類型
git lfs track

### 提交 .gitattributes
git add .gitattributes
git commit -m "設定 Git LFS 追蹤規則"

### 查看 LFS 檔案
git lfs ls-files

### 檢查 LFS 狀態
git lfs status

### 手動添加大檔案到 LFS
git lfs track "large-file.zip"
git add large-file.zip
git commit -m "新增大型檔案"

### Clone 時不下載 LFS 檔案
git clone --filter=blob:none <url>
git lfs pull  # 需要時再下載

### 1. 切換到主分支
git checkout main

### 2. 拉取最新變更
git pull origin main

### 3. 如果有設定 upstream，也同步上游
git fetch upstream
git merge upstream/main

### 1. 切換到功能分支
git checkout feature/your-feature

### 2. 合併主分支最新變更
git merge main

### 或使用 rebase（保持線性歷史）
git rebase main

### 建議每天至少執行一次
git checkout main
git pull origin main
git checkout feature/your-feature
git merge main

### ✅ 好的實務：小而頻繁的提交
git add src/user/UserService.java
git commit -m "feat: 新增使用者驗證方法"

git add src/user/UserController.java
git commit -m "feat: 新增使用者 API 端點"

### ❌ 避免：一次大量提交
git add .
git commit -m "完成所有功能"

1. 建立分支    ←── 從最新的 main 分支建立
2. 開發階段    ←── 頻繁提交，定期同步 main
3. 完成開發    ←── 最終測試，準備 PR
4. Code Review ←── 修正建議，可能需要額外提交
5. 合併主分支  ←── Squash merge 到 main
6. 清理分支    ←── 刪除遠端和本地分支

### 查看所有分支
git branch -a

### 刪除已合併的本地分支
git branch -d feature/completed-feature

### 強制刪除本地分支
git branch -D feature/abandoned-feature

### 刪除遠端分支
git push origin --delete feature/completed-feature

### 清理已刪除的遠端分支參考
git fetch --prune

📢 **團隊溝通原則**

1. **透明化**: 所有變更都應在相關的 issue 或 PR 中討論
2. **文件化**: 重要決策應記錄在 Wiki 或討論區
3. **及時反應**: 24小時內回應 PR review 請求
4. **建設性回饋**: 提供具體、可行的改進建議

### 每日程式碼品質檢查
### 1. 執行靜態分析
npm run lint
sonar-scanner

### 2. 檢查測試覆蓋率
npm run test:coverage

### 3. 依賴套件安全掃描
npm audit

🔄 **分支管理流程**

1. **功能分支** (feature/*)
   - 生命週期: 1-2 週
   - 定期與 main 同步
   - 完成後立即刪除

2. **修復分支** (bugfix/*)
   - 生命週期: 3-5 天
   - 緊急修復可直接從 main 分支

3. **發布分支** (release/*)
   - 生命週期: 1-3 天
   - 僅允許 bug 修復和文件更新

### 小型團隊 (2-5人)
workflow: "GitHub Flow"
review_required: 1
merge_strategy: "Squash and merge"

### 中型團隊 (6-15人)
workflow: "Git Flow"
review_required: 2
merge_strategy: "Create merge commit"
branch_protection: true

### 大型團隊 (15+人)
workflow: "GitHub Flow + Feature flags"
review_required: 2-3
merge_strategy: "Squash and merge"
automated_testing: true

📚 **團隊學習計畫**

- **Code Review 學習**
  - 每週輪流擔任 review 導師
  - 分享最佳實務和常見問題

- **技術分享會**
  - 每月技術主題分享
  - Git 進階技巧工作坊

- **文件維護**
  - 每季更新開發指南
  - 新人 onboarding 流程優化

當兩個分支修改了同一個檔案的同一行時，Git 無法自動合併

### 1. 拉取最新變更時發生衝突
git pull origin main
### 輸出：Auto-merging failed; fix conflicts and then commit

### 2. 查看衝突檔案
git status
### 輸出：Unmerged paths: both modified: src/User.java

### 3. 編輯衝突檔案
### 檔案中會顯示：
### <<<<<<< HEAD
### 您的變更
### =======
### 其他人的變更
### >>>>>>> branch-name

### 4. 手動解決衝突（保留需要的程式碼）
### 刪除衝突標記，保留正確的程式碼

### 5. 標記衝突已解決
git add src/User.java

### 6. 完成合併
git commit -m "resolve: 解決 User.java 合併衝突"

### 方法1：使用 rebase 替代 merge
git checkout feature/your-feature
git rebase main

### 方法2：頻繁同步主分支
git checkout main
git pull origin main
git checkout feature/your-feature
git merge main

### 方法3：協調開發範圍
### 團隊內溝通避免同時修改相同檔案

### 如果還沒 push
git commit --amend -m "正確的 commit message"

### 如果已經 push（需要 force push，要小心）
git commit --amend -m "正確的 commit message"
git push --force-with-lease origin feature/your-branch

### 保留變更，只取消 commit
git reset --soft HEAD~1

### 完全取消變更和 commit
git reset --hard HEAD~1

### 取消多次 commit
git reset --soft HEAD~3  # 取消最近3次

### 從最後一次 commit 中移除檔案
git reset --soft HEAD~1
git reset HEAD path/to/unwanted/file
git commit -m "正確的 commit message"

### 查看被刪除的檔案
git status

### 恢復特定檔案
git checkout HEAD -- path/to/deleted/file

### 恢復所有被刪除的檔案
git checkout HEAD -- .

### 查找檔案被刪除的 commit
git log --oneline --follow -- path/to/deleted/file

### 從該 commit 的前一版本恢復檔案
git checkout <commit-hash>~1 -- path/to/deleted/file

### 提交恢復的檔案
git add path/to/deleted/file
git commit -m "restore: 恢復意外刪除的檔案"

### 常見錯誤訊息
! [rejected] main -> main (fetch first)

### 原因：遠端分支有新的變更
### 解決方法：
git pull origin main
git push origin main

### 如果有衝突，先解決衝突再 push

### ❌ 危險：可能覆蓋他人變更
git push --force origin main

### ✅ 安全：只在沒有他人變更時強制推送
git push --force-with-lease origin feature/your-branch

### 情況：在 main 分支上做了變更，但還沒 commit
### 解決：移動變更到正確分支

### 1. 暫存目前變更
git stash

### 2. 建立或切換到正確分支
git checkout -b feature/correct-branch

### 3. 恢復變更
git stash pop

### 情況：已經在 main 分支上 commit
### 解決：移動 commit 到正確分支

### 1. 建立新分支（包含錯誤的 commit）
git branch feature/correct-branch

### 2. 重置 main 分支
git reset --hard HEAD~1

### 3. 切換到正確分支
git checkout feature/correct-branch

### 查看目前狀態
git status

### 取消所有未暫存的變更
git checkout -- .

### 移除未追蹤的檔案
git clean -fd

### 取消已暫存的變更
git reset HEAD

### 完全重置到最後一次 commit
git reset --hard HEAD

### 當一切都亂了，想回到安全狀態
git reflog                    # 查看所有操作歷史
git reset --hard HEAD@{n}     # 回到特定操作前的狀態

### 備份目前狀態再進行危險操作
git branch backup-$(date +%Y%m%d-%H%M%S)

### 查看誰修改了什麼
git blame path/to/file        # 查看每行的修改者
git log -p path/to/file       # 查看檔案的修改歷史

### 診斷 Git 效能問題
git count-objects -v          # 檢查物件數量
git gc --aggressive           # 強制垃圾收集
git repack -a -d             # 重新包裝物件

### 檢查大型檔案
git rev-list --objects --all | \
  git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
  awk '/^blob/ {print substr($0,6)}' | \
  sort --numeric-sort --key=2 | \
  tail -20

### 清理無用的參考
git remote prune origin
git gc --prune=now

### 使用 partial clone 減少下載大小
git clone --filter=blob:limit=100k <url>

### 測試連線
ssh -T git@github.com
ping github.com

### 檢查 SSL 設定
git config --global http.sslVerify false  # 臨時解決方案
git config --global http.sslBackend schannel  # Windows

### 使用 HTTP 替代 SSH（臨時）
git remote set-url origin <https://github.com/user/repo.git>

### 檢查 SSH 金鑰
ssh-add -l
ssh -T git@github.com

### 重新生成 SSH 金鑰
ssh-keygen -t ed25519 -C "your.email@example.com"
ssh-add ~/.ssh/id_ed25519

### SSH 設定檔 (~/.ssh/config)
Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

### HTTP 代理設定
git config --global http.proxy <http://proxy.company.com:8080>
git config --global https.proxy <http://proxy.company.com:8080>

### SOCKS 代理設定
git config --global http.proxy socks5://localhost:1080

### 取消代理設定
git config --global --unset http.proxy
git config --global --unset https.proxy

### 使用 HTTPS 替代 SSH
git config --global url."<https://github.com/".insteadOf> git@github.com:

### 測試不同埠號
ssh -T -p 443 git@ssh.github.com

### SSH 設定使用 443 埠
Host github.com
  Hostname ssh.github.com
  Port 443
  User git

格式：<類型>/<簡短描述>-<票號>

範例：
✅ feature/user-authentication-123
✅ bugfix/login-timeout-456
✅ hotfix/security-patch-789
✅ docs/api-documentation-012

❌ my-feature
❌ fix
❌ temp-branch
❌ test123

<type>(<scope>): <subject>

<body>

<footer>

### 標題行（必須）
### - 類型：feat, fix, docs, style, refactor, test, chore
### - 範圍：可選，如 auth, payment, user
### - 主旨：簡潔描述，現在式，小寫開頭，不超過50字

### 內容（可選）
### - 詳細說明變更內容
### - 說明為什麼而非怎麼做
### - 每行不超過72字

### 註腳（可選）
### - 破壞性變更：BREAKING CHANGE: 描述
### - 關閉 Issue：Closes #123, Fixes #456
### - 相關 Issue：Related to #789

### 新功能
feat(auth): 新增 JWT token 驗證機制

實作基於 JWT 的使用者驗證系統：
- 新增 token 生成和驗證邏輯
- 整合到現有的登入流程
- 新增相關的單元測試

Closes #123

### 錯誤修復
fix(payment): 修復信用卡驗證邏輯錯誤

修正信用卡號碼驗證演算法，解決 Visa 卡無法通過驗證的問題

Fixes #456

### 文件更新
docs(api): 更新使用者 API 文件

- 新增新端點的說明
- 修正回應格式範例
- 更新錯誤代碼說明

### 重構
refactor(user): 重構使用者服務層邏輯

將使用者相關邏輯從控制器移至服務層，提高程式碼的可維護性和可測試性

### 破壞性變更
feat(api)!: 更新使用者 API 回應格式

BREAKING CHANGE: 使用者 API 的回應格式已改變，
請更新客戶端程式碼以配合新的格式

[<類型>] <簡短描述> (<票號>)

範例：
[Feature] 新增使用者二步驗證 (#123)
[Bugfix] 修復登入逾時問題 (#456)
[Hotfix] 修復支付安全漏洞 (#789)

## 📋 變更摘要
<!-- 簡述這個 PR 的目的和主要變更 -->

## 🎯 相關 Issue
<!-- 例如：Closes #123, Fixes #456, Related to #789 -->

## 🔧 變更內容
<!-- 詳細列出所有變更 -->
- [ ] 新增功能 A
- [ ] 修改功能 B
- [ ] 移除功能 C
- [ ] 更新文件 D

## 🧪 測試
<!-- 說明如何測試這些變更 -->
- [ ] 單元測試已通過
- [ ] 整合測試已通過
- [ ] 手動測試已完成
- [ ] 效能測試已通過（如適用）

## 📱 截圖/影片
<!-- 如果是 UI 變更，請附上截圖或影片 -->

## ⚠️ 注意事項
<!-- 任何需要特別注意的事項 -->
- [ ] 需要資料庫遷移
- [ ] 需要環境變數配置
- [ ] 有破壞性變更
- [ ] 需要更新部署流程

## ✅ 檢查清單
- [ ] 程式碼符合專案編碼規範
- [ ] 已新增或更新相關測試
- [ ] 已更新相關文件
- [ ] 已通過所有 CI 檢查
- [ ] 已自我審查程式碼

### ✅ 良好的回饋範例

## 💡 建議
這個方法有點長，建議拆分為更小的函數提高可讀性：
```java

// 建議拆分
public void processUser(User user) {
    validateUser(user);
    saveUser(user);
    sendNotification(user);
}

```text

## ⚠️ 問題
這裡可能會有 NPE 的風險，建議加上 null 檢查：
```java

if (user != null && user.getEmail() != null) {
    // 處理邏輯
}

```text

## 🔒 安全性
這個 SQL 查詢容易受到 SQL 注入攻擊，請使用 PreparedStatement

### ❌ 避免的回饋方式
- "這段程式碼不好"
- "重寫"
- "錯誤"

強制規則：
✅ 需要 Pull Request 才能合併
✅ 需要至少 2 位審查者同意
✅ 所有 CI 檢查必須通過
✅ 分支必須是最新版本
✅ 管理員也需要遵循規則

禁止操作：
❌ 直接推送到 main
❌ 強制推送
❌ 刪除分支

### .github/workflows/ci.yml 範例
name: CI

on:
  pull_request:
    branches: [ main ]
  push:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Set up JDK 17
      uses: actions/setup-java@v3
      with:
        java-version: '17'
        distribution: 'temurin'
    - name: Run tests
      run: mvn test
    - name: Check code style
      run: mvn checkstyle:check

### Issue 範本
#### 問題描述
清楚描述遇到的問題或需求

#### 重現步驟
1. 進入登入頁面
2. 輸入錯誤密碼
3. 點選登入按鈕
4. 看到錯誤訊息

#### 預期結果
應該顯示清楚的錯誤訊息

#### 實際結果
顯示不明確的錯誤

#### 環境資訊
- 瀏覽器：Chrome 117
- 作業系統：Windows 11
- 版本：v2.1.0

#### 附加資訊
- [ ] 這是安全性相關問題
- [ ] 這會影響所有使用者
- [ ] 已檢查是否為重複問題

標籤分類：

🐛 bug - 錯誤回報
✨ enhancement - 功能增強
📝 documentation - 文件相關
❓ question - 問題詢問
🚀 feature - 新功能
🔧 maintenance - 維護工作
🔒 security - 安全性問題
⚡ performance - 效能改善
🎨 ui/ux - 使用者介面
🧪 testing - 測試相關

優先度：
🔴 high priority - 高優先度
🟡 medium priority - 中優先度
🟢 low priority - 低優先度

狀態：
🚧 in progress - 進行中
👀 needs review - 需要審查
✅ ready - 準備就緒
❌ won't fix - 不予修復

### GitHub CLI 操作 Issues
gh issue create --title "修復登入錯誤" --body "詳細描述..." --label bug,high-priority

gh issue list --state open --assignee @me

gh issue view 123

gh issue close 123

gh issue reopen 123

標準欄位設定：

📋 Backlog (待辦事項)
- 新建立的 Issues
- 尚未開始的任務

🚧 In Progress (進行中)
- 正在開發的功能
- 指派給開發者的任務

👀 Review (審查中)
- 等待 Code Review 的 PR
- 需要測試的功能

✅ Done (完成)
- 已合併的 PR
- 已解決的 Issues

🚀 Released (已發布)
- 已部署到生產環境的功能

### 專案自動化範例
name: 專案看板自動化

on:
  issues:
    types: [opened, closed]
  pull_request:
    types: [opened, closed, merged]

jobs:
  update-project:
    runs-on: ubuntu-latest
    steps:
    - name: 移動 Issue 到進行中
      if: github.event.action == 'opened'
      uses: alex-page/github-project-automation-plus@v0.8.1
      with:
        project: 專案開發看板
        column: In Progress
        repo-token: ${{ secrets.GITHUB_TOKEN }}

### 專案 Wiki 首頁

## 📚 文件導航

### 開發相關
- [開發環境設定](開發環境設定)
- [程式碼風格指南](程式碼風格指南)
- [API 文件](API-文件)

### 部署運維
- [部署指南](部署指南)
- [監控設定](監控設定)
- [故障排除](故障排除)

### 專案管理
- [發布流程](發布流程)
- [會議記錄](會議記錄)
- [決策紀錄](決策紀錄)

## 🔗 外部連結
- [線上 Demo](https://demo.example.com)
- [API 文件](https://api.example.com/docs)
- [監控面板](https://monitoring.example.com)

### Wiki 撰寫指南

## 結構化內容
- 使用清楚的標題階層
- 提供目錄導航
- 加入相關連結

## 保持更新
- 定期檢查內容正確性
- 版本發布時更新文件
- 移除過時資訊

## 協作編輯
- 使用 Markdown 格式
- 提供編輯歷史
- 鼓勵團隊貢獻

版本號格式：主版本.次版本.修補版本

範例：v2.1.3

主版本 (Major)：不相容的 API 變更
次版本 (Minor)：向下相容的功能新增
修補版本 (Patch)：向下相容的問題修正

標籤範例：
v1.0.0 - 第一個穩定版本
v1.1.0 - 新增功能
v1.1.1 - 錯誤修復
v2.0.0 - 重大更新

### 建立標籤
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

### 使用 GitHub CLI
gh release create v1.2.0 \
  --title "版本 1.2.0" \
  --notes "
## 🚀 新功能
- 新增使用者頭像上傳功能
- 新增批次匯出功能

## 🐛 錯誤修復
- 修復登入逾時問題
- 修復檔案上傳大小限制

## 🔧 改善項目
- 提升搜尋效能
- 優化使用者介面

## 📋 完整變更紀錄
查看所有變更：[v1.1.0...v1.2.0](https://github.com/owner/repo/compare/v1.1.0...v1.2.0)
" \
  --draft

### Release Notes 範本

## 版本 v2.1.0 (2025-08-28)

### 🚀 新功能 (Features)
- **使用者管理**: 新增批次使用者匯入功能 (#123)
- **報表系統**: 新增自訂報表產生器 (#124)

### 🐛 錯誤修復 (Bug Fixes)
- **登入系統**: 修復 OAuth 登入逾時問題 (#125)
- **檔案上傳**: 修復大檔案上傳失敗問題 (#126)

### 🔧 改善項目 (Improvements)
- **效能優化**: 資料庫查詢效能提升 30% (#127)
- **使用者體驗**: 簡化設定流程 (#128)

### 💥 重大變更 (Breaking Changes)
- **API**: 移除 v1 API 支援，請升級到 v2 API
- **設定格式**: 配置檔案格式已更新，請參考遷移指南

### 📚 文件更新
- 更新 API 文件
- 新增部署指南
- 更新故障排除手冊

### 🔗 相關連結
- [完整變更清單](https://github.com/owner/repo/compare/v2.0.0...v2.1.0)
- [遷移指南](https://github.com/owner/repo/wiki/Migration-Guide-v2.1)
- [已知問題](https://github.com/owner/repo/issues?q=is%3Aissue+is%3Aopen+label%3A%22known+issue%22)

### 👥 貢獻者
感謝以下貢獻者的參與：
- @developer1 - 新功能開發
- @developer2 - 錯誤修復
- @tester1 - 測試與品質保證

分類架構：

💡 Ideas (想法建議)
- 新功能建議
- 改善提案
- 創新想法

❓ Q&A (問題解答)
- 技術問題
- 使用疑問
- 最佳實務詢問

📢 Announcements (公告)
- 版本發布
- 重要更新
- 政策變更

🗣️ General (一般討論)
- 經驗分享
- 社群交流
- 其他話題

### 安全性公告管理

## 建立安全性公告
1. Repository → Security → Advisories
2. 填寫漏洞詳細資訊
3. 評估嚴重程度 (CVSS)
4. 設定修復時程
5. 通知相關使用者

## 私人漏洞回報
- 提供安全回報管道
- 協調負責任的漏洞披露
- 管理修復流程

### .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "maven"
    directory: "/"
    schedule:
      interval: "weekly"
    assignees:
      - "security-team"
    reviewers:
      - "lead-developer"
    commit-message:
      prefix: "deps:"
      include: "scope"

### .github/workflows/codeql.yml
name: "CodeQL 安全掃描"

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  schedule:
    - cron: '30 1 * * 1'

jobs:
  analyze:
    name: 分析程式碼
    runs-on: ubuntu-latest
    
    strategy:
      fail-fast: false
      matrix:
        language: [ 'java' ]
        
    steps:
    - name: 檢出程式碼
      uses: actions/checkout@v4
      
    - name: 初始化 CodeQL
      uses: github/codeql-action/init@v3
      with:
        languages: ${{ matrix.language }}
        
    - name: 自動建構
      uses: github/codeql-action/autobuild@v3
      
    - name: 執行 CodeQL 分析
      uses: github/codeql-action/analyze@v3

### 批次管理 Issues
gh issue list --state open --json number,title | \
  jq '.[] | select(.title | contains("bug")) | .number' | \
  xargs -I {} gh issue edit {} --add-label "priority:high"

### 批次管理 PR
gh pr list --state open --author "@me" --json number | \
  jq '.[].number' | \
  xargs -I {} gh pr merge {} --squash

### 專案統計
gh issue list --state all --json state | \
  jq 'group_by(.state) | map({state: .[0].state, count: length})'

開發工具：
- SonarCloud - 程式碼品質分析
- Codecov - 測試覆蓋率
- Snyk - 安全漏洞掃描

專案管理：
- ZenHub - 進階專案管理
- Linear - 現代化問題追蹤
- Jira - 企業專案管理

通訊協作：
- Slack - 團隊通訊整合
- Microsoft Teams - 企業協作
- Discord - 社群互動

部署監控：
- Vercel - 前端部署
- Heroku - 應用程式託管
- DataDog - 應用程式監控

### VS Code 擴充套件安裝
### 1. 開啟 VS Code
### 2. 安裝 "GitHub Copilot" 擴充套件
### 3. 登入 GitHub 帳號

### 檢查 Copilot 狀態
### Ctrl+Shift+P -> "GitHub Copilot: Show Output"

// 範例：Copilot 協助生成函數
// 輸入註解，Copilot 會建議實作
// Calculate the area of a circle given radius
function calculateCircleArea(radius) {
    // Copilot 會自動建議: return Math.PI * radius * radius;
}

// 生成測試案例
// 輸入: Write test for calculateCircleArea
// Copilot 會建議完整的測試程式碼

✅ **有效使用 Copilot**

1. **清楚的註解**: 詳細描述功能需求
2. **良好的命名**: 使用有意義的變數和函數名稱
3. **上下文提供**: 在相關程式碼附近工作
4. **審查建議**: 不要盲目接受所有建議

❌ **避免事項**

1. 不要完全依賴 Copilot
2. 不要跳過程式碼審查
3. 不要忽略安全性考量
4. 不要忘記測試生成的程式碼

### Copilot 使用指南
copilot_usage:
  review_required: true
  security_check: mandatory
  documentation: required
  testing: comprehensive

### 檔案類型限制
file_restrictions:
  - no_secrets: ["*.env", "*.key", "*.pem"]
  - review_needed: ["Dockerfile", "docker-compose.yml"]
  - careful_with: ["*.sql", "*.sh", "*.ps1"]

.github/
└── workflows/
    ├── ci.yml          # 持續整合
    ├── cd.yml          # 持續部署
    ├── security.yml    # 安全檢查
    └── docs.yml        # 文件生成

### .github/workflows/ci.yml
name: Continuous Integration

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    name: 測試與品質檢查
    runs-on: ubuntu-latest
    
    strategy:
      matrix:
        java-version: [17, 21]
    
    steps:
    - name: 檢出程式碼
      uses: actions/checkout@v4
      
    - name: 設定 Java ${{ matrix.java-version }}
      uses: actions/setup-java@v4
      with:
        java-version: ${{ matrix.java-version }}
        distribution: 'temurin'
        
    - name: 快取 Maven 依賴
      uses: actions/cache@v4
      with:
        path: ~/.m2
        key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
        restore-keys: ${{ runner.os }}-m2
        
    - name: 執行測試
      run: mvn clean test
      
    - name: 生成測試報告
      uses: dorny/test-reporter@v1
      if: success() || failure()
      with:
        name: Maven Tests
        path: target/surefire-reports/*.xml
        reporter: java-junit
        
    - name: 程式碼覆蓋率
      run: mvn jacoco:report
      
    - name: 上傳覆蓋率到 Codecov
      uses: codecov/codecov-action@v3
      with:
        file: target/site/jacoco/jacoco.xml
        
  code-quality:
    name: 程式碼品質檢查
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
      
    - name: 設定 Java
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'
        
    - name: 執行 Checkstyle
      run: mvn checkstyle:check
      
    - name: 執行 SpotBugs
      run: mvn spotbugs:check
      
    - name: SonarQube 分析
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
      run: mvn sonar:sonar

### .github/workflows/multi-env.yml
name: 多環境測試

on:
  pull_request:
    branches: [ main ]

jobs:
  test:
    name: ${{ matrix.os }} - Java ${{ matrix.java }}
    runs-on: ${{ matrix.os }}
    
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        java: [17, 21]
        
    steps:
    - uses: actions/checkout@v4
    
    - name: 設定 Java ${{ matrix.java }}
      uses: actions/setup-java@v4
      with:
        java-version: ${{ matrix.java }}
        distribution: 'temurin'
        
    - name: 執行測試
      run: mvn clean test
      
    - name: 整合測試
      run: mvn verify -P integration-tests

### .github/workflows/security.yml
name: 安全檢查

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  schedule:
    - cron: '0 6 * * 1'  # 每週一早上6點執行

jobs:
  security:
    name: 安全漏洞掃描
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
    
    - name: 設定 Java
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'
        
    - name: OWASP 依賴檢查
      run: mvn org.owasp:dependency-check-maven:check
      
    - name: 上傳安全報告
      uses: actions/upload-artifact@v4
      if: always()
      with:
        name: security-reports
        path: target/dependency-check-report.html
        
    - name: CodeQL 分析
      uses: github/codeql-action/init@v3
      with:
        languages: java
        
    - name: 自動建構
      uses: github/codeql-action/autobuild@v3
      
    - name: 執行 CodeQL 分析
      uses: github/codeql-action/analyze@v3

### .github/workflows/deploy-staging.yml
name: 部署到測試環境

on:
  push:
    branches: [ develop ]

jobs:
  deploy:
    name: 部署測試環境
    runs-on: ubuntu-latest
    environment: staging
    
    steps:
    - uses: actions/checkout@v4
    
    - name: 設定 Java
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'
        
    - name: 建構應用程式
      run: mvn clean package -DskipTests
      
    - name: 建構 Docker 映像
      run: |
        docker build -t ${{ vars.DOCKER_REGISTRY }}/app:staging-${{ github.sha }} .
        docker build -t ${{ vars.DOCKER_REGISTRY }}/app:staging-latest .
        
    - name: 登入 Docker Registry
      uses: docker/login-action@v3
      with:
        registry: ${{ vars.DOCKER_REGISTRY }}
        username: ${{ secrets.DOCKER_USERNAME }}
        password: ${{ secrets.DOCKER_PASSWORD }}
        
    - name: 推送 Docker 映像
      run: |
        docker push ${{ vars.DOCKER_REGISTRY }}/app:staging-${{ github.sha }}
        docker push ${{ vars.DOCKER_REGISTRY }}/app:staging-latest
        
    - name: 部署到 Kubernetes
      uses: azure/k8s-deploy@v1
      with:
        manifests: |
          k8s/staging/deployment.yaml
          k8s/staging/service.yaml
        images: ${{ vars.DOCKER_REGISTRY }}/app:staging-${{ github.sha }}
        kubeconfig: ${{ secrets.KUBE_CONFIG_STAGING }}

### .github/workflows/deploy-production.yml
name: 部署到生產環境

on:
  release:
    types: [published]

jobs:
  deploy:
    name: 生產環境部署
    runs-on: ubuntu-latest
    environment: production
    
    steps:
    - uses: actions/checkout@v4
    
    - name: 設定 Java
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'
        
    - name: 執行完整測試
      run: mvn clean verify
      
    - name: 建構應用程式
      run: mvn clean package -DskipTests
      
    - name: 建構 Docker 映像
      run: |
        docker build -t ${{ vars.DOCKER_REGISTRY }}/app:${{ github.ref_name }} .
        docker build -t ${{ vars.DOCKER_REGISTRY }}/app:latest .
        
    - name: 安全掃描映像
      uses: aquasecurity/trivy-action@master
      with:
        image-ref: ${{ vars.DOCKER_REGISTRY }}/app:${{ github.ref_name }}
        format: 'sarif'
        output: 'trivy-results.sarif'
        
    - name: 上傳安全掃描結果
      uses: github/codeql-action/upload-sarif@v3
      with:
        sarif_file: 'trivy-results.sarif'
        
    - name: 登入 Docker Registry
      uses: docker/login-action@v3
      with:
        registry: ${{ vars.DOCKER_REGISTRY }}
        username: ${{ secrets.DOCKER_USERNAME }}
        password: ${{ secrets.DOCKER_PASSWORD }}
        
    - name: 推送 Docker 映像
      run: |
        docker push ${{ vars.DOCKER_REGISTRY }}/app:${{ github.ref_name }}
        docker push ${{ vars.DOCKER_REGISTRY }}/app:latest
        
    - name: 藍綠部署
      uses: azure/k8s-deploy@v1
      with:
        strategy: blue-green
        manifests: |
          k8s/production/deployment.yaml
          k8s/production/service.yaml
        images: ${{ vars.DOCKER_REGISTRY }}/app:${{ github.ref_name }}
        kubeconfig: ${{ secrets.KUBE_CONFIG_PRODUCTION }}
        
    - name: 健康檢查
      run: |
        sleep 30
        curl -f ${{ vars.PRODUCTION_URL }}/health || exit 1
        
    - name: 通知部署結果
      uses: 8398a7/action-slack@v3
      with:
        status: ${{ job.status }}
        channel: '#deployments'
        webhook_url: ${{ secrets.SLACK_WEBHOOK }}

### 透過 GitHub API 或 Web 介面設定
分支保護規則 (main):
✅ 需要 Pull Request 才能合併
✅ 需要狀態檢查通過:
   - ci / test (ubuntu-latest, 17)
   - ci / test (ubuntu-latest, 21)
   - ci / code-quality
   - security / security
✅ 需要分支為最新版本
✅ 需要管理員審查
✅ 限制推送權限

### .github/workflows/auto-merge.yml
name: 自動合併

on:
  pull_request:
    types: [labeled, unlabeled, synchronize, opened, edited, ready_for_review, reopened]

jobs:
  auto-merge:
    name: 自動合併 Dependabot PR
    runs-on: ubuntu-latest
    if: ${{ github.actor == 'dependabot[bot]' }}
    
    steps:
    - name: 自動核准 Dependabot PR
      uses: hmarr/auto-approve-action@v3
      with:
        github-token: ${{ secrets.GITHUB_TOKEN }}
        
    - name: 啟用自動合併
      uses: peter-evans/enable-pull-request-automerge@v3
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        pull-request-number: ${{ github.event.pull_request.number }}
        merge-method: squash

### .github/workflows/monitor.yml
name: 生產監控

on:
  schedule:
    - cron: '*/5 * * * *'  # 每5分鐘檢查一次

jobs:
  health-check:
    name: 健康檢查
    runs-on: ubuntu-latest
    
    steps:
    - name: 檢查應用程式健康狀態
      run: |
        response=$(curl -s -o /dev/null -w "%{http_code}" ${{ vars.PRODUCTION_URL }}/health)
        if [ $response -ne 200 ]; then
          echo "健康檢查失敗: HTTP $response"
          exit 1
        fi
        
    - name: 檢查資料庫連線
      run: |
        response=$(curl -s -o /dev/null -w "%{http_code}" ${{ vars.PRODUCTION_URL }}/health/db)
        if [ $response -ne 200 ]; then
          echo "資料庫檢查失敗: HTTP $response"
          exit 1
        fi
        
    - name: 失敗通知
      if: failure()
      uses: 8398a7/action-slack@v3
      with:
        status: failure
        channel: '#alerts'
        text: '🚨 生產環境健康檢查失敗！'
        webhook_url: ${{ secrets.SLACK_WEBHOOK }}

### .github/workflows/performance.yml
name: 效能測試

on:
  pull_request:
    branches: [ main ]
  schedule:
    - cron: '0 2 * * 1'  # 每週一凌晨2點

jobs:
  performance:
    name: 效能基準測試
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
    
    - name: 設定 Java
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'
        
    - name: 建構應用程式
      run: mvn clean package -DskipTests
      
    - name: 啟動應用程式
      run: |
        java -jar target/app.jar &
        sleep 30
        
    - name: JMeter 效能測試
      uses: rbhadti94/apache-jmeter-action@v0.5.0
      with:
        testFilePath: performance-tests/load-test.jmx
        outputReportsFolder: reports/
        
    - name: 上傳效能報告
      uses: actions/upload-artifact@v4
      with:
        name: performance-reports
        path: reports/
        
    - name: 效能回歸檢查
      run: |
        python scripts/performance-regression-check.py \
          --current reports/results.jtl \
          --baseline performance-baseline.json \
          --threshold 10

Repository Secrets (Settings → Secrets and variables → Actions):

🔑 必要 Secrets:
- DOCKER_USERNAME: Docker Registry 使用者名稱
- DOCKER_PASSWORD: Docker Registry 密碼
- SONAR_TOKEN: SonarQube 存取權杖
- SLACK_WEBHOOK: Slack 通知 Webhook URL
- KUBE_CONFIG_STAGING: 測試環境 Kubernetes 配置
- KUBE_CONFIG_PRODUCTION: 生產環境 Kubernetes 配置

🌍 環境變數:
- DOCKER_REGISTRY: Docker Registry 位址
- PRODUCTION_URL: 生產環境 URL
- STAGING_URL: 測試環境 URL

### 環境設定範例
environments:
  staging:
    url: <https://staging.yourapp.com>
    secrets:
      - DATABASE_URL
      - API_KEY
    protection_rules:
      required_reviewers: 1
      
  production:
    url: <https://yourapp.com>
    secrets:
      - DATABASE_URL
      - API_KEY
      - SSL_CERT
    protection_rules:
      required_reviewers: 2
      deployment_branch_policy:
        protected_branches: true

### 權限最小化原則
permissions:
  contents: read
  packages: write
  security-events: write

### 使用 GITHUB_TOKEN 而非個人存取權杖
env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

### 固定 Action 版本
uses: actions/checkout@v4  # ✅ 具體版本
uses: actions/checkout@main  # ❌ 避免使用分支

### 條件執行以節省資源
jobs:
  expensive-job:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    
  # 限制並行執行數量
  concurrency:
    group: ${{ github.workflow }}-${{ github.ref }}
    cancel-in-progress: true

### 生成強度更高的 SSH 金鑰
ssh-keygen -t ed25519 -a 100 -C "your.email@example.com"

### 設定 SSH 金鑰密碼
ssh-keygen -p -f ~/.ssh/id_ed25519

### 限制 SSH 金鑰的使用範圍
### 在 GitHub 設定中選擇 "Restrict to specific repositories"

### Token 最佳實務
✅ 設定最小權限範圍
✅ 設定 Token 有效期限
✅ 定期輪換 Token
✅ 使用環境變數存儲 Token
✅ 不要將 Token 提交到程式碼庫

### 環境變數設定
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxx"

### Git 設定使用 Token
git config --global credential.helper store

🔒 **啟用 2FA 步驟**

1. GitHub → Settings → Password and authentication
2. 選擇 "Enable two-factor authentication"
3. 使用 Authenticator App (推薦) 或 SMS
4. 儲存備用恢復碼

⚠️ **注意事項**
- 啟用 2FA 後，Git 操作需使用 Personal Access Token
- 妥善保管恢復碼
- 定期檢查授權的應用程式

# 機密檔案
*.key
*.pem
*.p12
*.pfx
.env
.env.local
.env.*.local

# 配置檔案
config/secrets.yml
config/database.yml
application-prod.properties

# IDE 設定
.vscode/settings.json
.idea/

# OS 檔案
.DS_Store
Thumbs.db

# 日誌檔案
*.log
logs/

# 依賴套件
node_modules/
target/
build/

### 安裝 git-secrets
# macOS
brew install git-secrets

# Windows (使用 Git Bash)
git clone https://github.com/awslabs/git-secrets.git
cd git-secrets
make install

### 設定 git-secrets
git secrets --install
git secrets --register-aws

### 掃描現有儲存庫
git secrets --scan
git secrets --scan-history

### 自訂規則
git secrets --add 'password\s*=\s*.+'
git secrets --add 'api[_-]?key\s*=\s*.+'

### .env 檔案範本
# .env.example
DATABASE_URL=postgresql://localhost:5432/dbname
API_KEY=your_api_key_here
SECRET_KEY=your_secret_key_here
SMTP_PASSWORD=your_smtp_password

### 使用 direnv 管理環境變數
# 安裝 direnv
brew install direnv

# 在 .envrc 中設定
export DATABASE_URL="postgresql://..."
export API_KEY="..."

# 啟用 direnv
direnv allow

### 使用 truffleHog 掃描
pip install truffleHog
trufflehog --regex --entropy=True <repository-url>

### 使用 GitGuardian
curl -sSL https://api.gitguardian.com/v1/scan | bash

### 使用 detect-secrets
pip install detect-secrets
detect-secrets scan > .secrets.baseline
detect-secrets audit .secrets.baseline

### .github/workflows/codeql.yml
name: "CodeQL 安全分析"

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]
  schedule:
    - cron: '30 1 * * 1'

jobs:
  analyze:
    name: 分析程式碼
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write

    strategy:
      fail-fast: false
      matrix:
        language: [ 'java', 'javascript' ]

    steps:
    - name: 檢出程式碼
      uses: actions/checkout@v4

    - name: 初始化 CodeQL
      uses: github/codeql-action/init@v3
      with:
        languages: ${{ matrix.language }}
        queries: security-and-quality

    - name: 自動建構
      uses: github/codeql-action/autobuild@v3

    - name: 執行 CodeQL 分析
      uses: github/codeql-action/analyze@v3
      with:
        category: "/language:${{matrix.language}}"

### sonar-project.properties
sonar.projectKey=your-project-key
sonar.organization=your-organization
sonar.sources=src
sonar.tests=src/test
sonar.java.binaries=target/classes
sonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml

### .github/workflows/sonar.yml
name: SonarQube 分析

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  sonarqube:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0

    - name: 設定 Java
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'

    - name: 快取 SonarQube 套件
      uses: actions/cache@v4
      with:
        path: ~/.sonar/cache
        key: ${{ runner.os }}-sonar

    - name: 執行測試和分析
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
      run: mvn clean verify sonar:sonar

### 多種靜態分析工具
jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    # SpotBugs
    - name: SpotBugs 分析
      run: mvn spotbugs:check

    # PMD
    - name: PMD 分析
      run: mvn pmd:check

    # Checkstyle
    - name: Checkstyle 檢查
      run: mvn checkstyle:check

    # OWASP Dependency Check
    - name: OWASP 依賴檢查
      run: mvn org.owasp:dependency-check-maven:check

### .github/dependabot.yml
version: 2
updates:
  # Maven 依賴更新
  - package-ecosystem: "maven"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
      time: "09:00"
    open-pull-requests-limit: 10
    assignees:
      - "security-team"
    reviewers:
      - "lead-developer"
    commit-message:
      prefix: "deps"
      prefix-development: "deps(dev)"
      include: "scope"
    labels:
      - "dependencies"
      - "automated"

  # npm 依賴更新
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    versioning-strategy: increase

  # Docker 基礎映像更新
  - package-ecosystem: "docker"
    directory: "/"
    schedule:
      interval: "weekly"

### Maven 依賴安全檢查
mvn dependency:tree
mvn versions:display-dependency-updates
mvn org.owasp:dependency-check-maven:check

### npm 依賴安全檢查
npm audit
npm audit fix
npm audit fix --force

### 檢視漏洞詳情
npm audit --json
mvn dependency-check:check -Dformat=JSON

### .github/workflows/snyk.yml
name: Snyk 安全掃描

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  snyk:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    - name: 執行 Snyk 測試
      uses: snyk/actions/maven@master
      env:
        SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
      with:
        args: --severity-threshold=high

    - name: 上傳結果到 GitHub
      uses: github/codeql-action/upload-sarif@v3
      if: always()
      with:
        sarif_file: snyk.sarif

### main 分支保護規則
branch_protection:
  required_pull_request_reviews:
    required_approving_review_count: 2
    dismiss_stale_reviews: true
    require_code_owner_reviews: true
    require_last_push_approval: true
    
  required_status_checks:
    strict: true
    contexts:
      - "ci / test (ubuntu-latest, 17)"
      - "ci / code-quality"
      - "security / codeql"
      - "security / dependency-check"
      
  enforce_admins: true
  required_linear_history: true
  allow_force_pushes: false
  allow_deletions: false
  required_conversation_resolution: true
  
  restrictions:
    users: []
    teams:
      - "core-team"
      - "senior-developers"

### .github/CODEOWNERS
# 預設所有檔案的擁有者
*       @organization/core-team

# 特定目錄的擁有者
/src/main/java/security/    @organization/security-team
/src/main/resources/db/     @organization/database-team
/.github/workflows/         @organization/devops-team

# 特定檔案類型
*.sql                       @organization/database-team
Dockerfile                  @organization/devops-team
*.yml                       @organization/devops-team

# 文件維護
/docs/                      @organization/tech-writers
README.md                   @organization/product-team

### .github/workflows/branch-protection.yml
name: 檢查分支保護

on:
  pull_request:
    branches: [ main ]

jobs:
  check-protection:
    runs-on: ubuntu-latest
    steps:
    - name: 檢查 PR 標題格式
      uses: deepakputhraya/action-pr-title@master
      with:
        regex: '^\[.+\] .+'
        allowed_prefixes: 'Feature,Bugfix,Hotfix,Docs,Refactor'

    - name: 檢查 PR 描述
      uses: juliangruber/pr-body-check-action@v1
      with:
        contains: '## 📋 變更摘要'

    - name: 標籤檢查
      uses: mheap/github-action-required-labels@v2
      with:
        mode: exactly
        count: 1
        labels: "bug, enhancement, documentation"

### .github/workflows/audit.yml
name: 審計日誌

on:
  push:
    branches: [ main ]
  pull_request:
    types: [ opened, closed, merged ]
  workflow_dispatch:

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
    - name: 記錄事件
      run: |
        echo "事件類型: ${{ github.event_name }}"
        echo "使用者: ${{ github.actor }}"
        echo "分支: ${{ github.ref }}"
        echo "提交: ${{ github.sha }}"
        echo "時間: $(date -u +"%Y-%m-%d %H:%M:%S UTC")"

    - name: 發送到日誌系統
      uses: fjogeleit/http-request-action@v1
      with:
        url: ${{ secrets.AUDIT_LOG_ENDPOINT }}
        method: 'POST'
        data: |
          {
            "event": "${{ github.event_name }}",
            "actor": "${{ github.actor }}",
            "repository": "${{ github.repository }}",
            "ref": "${{ github.ref }}",
            "sha": "${{ github.sha }}",
            "timestamp": "${{ github.event.head_commit.timestamp }}"
          }

### .github/workflows/security-monitoring.yml
name: 安全監控

on:
  schedule:
    - cron: '0 */6 * * *'  # 每 6 小時執行一次

jobs:
  security-check:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    - name: 檢查異常提交
      run: |
        git log --since="6 hours ago" --pretty=format:"%h - %an: %s" > recent_commits.txt
        
    - name: 檢查大型檔案
      run: |
        find . -type f -size +10M > large_files.txt
        
    - name: 檢查敏感關鍵字
      run: |
        grep -r "password\|secret\|api_key" --include="*.java" --include="*.properties" . || true
        
    - name: 生成安全報告
      if: always()
      run: |
        echo "# 安全檢查報告" > security_report.md
        echo "## 最近提交" >> security_report.md
        cat recent_commits.txt >> security_report.md
        
    - name: 上傳報告
      uses: actions/upload-artifact@v4
      with:
        name: security-report
        path: security_report.md

### 定期檢查存取權限
gh api /repos/:owner/:repo/collaborators | jq '.[].login'

### 檢查團隊成員
gh api /orgs/:org/teams/:team/members | jq '.[].login'

### 檢查部署金鑰
gh api /repos/:owner/:repo/keys

### 檢查 Webhooks
gh api /repos/:owner/:repo/hooks

### 檢查 Actions Secrets
gh secret list

📊 **安全監控指標**

### 關鍵指標
- ✅ 依賴套件漏洞數量: 0 高風險
- ✅ 程式碼掃描問題: 2 中風險, 5 低風險
- ✅ 分支保護規則: 已啟用
- ✅ 雙因素驗證: 100% 團隊成員
- ✅ 金鑰輪換: 最後更新 30 天前

### 審計檢查
- [ ] 每月存取權限審查
- [ ] 每季安全政策更新
- [ ] 每年滲透測試
- [ ] 持續依賴套件監控

📁 **Source Control 面板功能**

🔄 **Changes 區域**
- 顯示所有修改的檔案
- 支援檔案分組 (修改/新增/刪除)
- 一鍵 stage/unstage 操作

📝 **Commit 區域**
- 快速提交訊息輸入
- Commit 和 Commit & Push 按鈕
- 顯示當前分支資訊

🌿 **Branch 管理**
- 分支切換和建立
- 遠端分支同步狀態
- Merge/Rebase 快捷操作

🔧 **右鍵選單功能**

- **Open File**: 開啟檔案查看完整內容
- **Open Changes**: 並排比較修改前後
- **Stage Changes**: 將檔案加入暫存區
- **Discard Changes**: 捨棄檔案修改
- **Ignore this extension**: 自動加入 .gitignore

// settings.json
{
  "git-graph.showTags": true,
  "git-graph.showRemoteBranches": true,
  "git-graph.fetchOnStartup": true,
  "git-graph.showSignatureStatus": true
}

📊 **Git Graph 功能特色**

🌐 **圖形化歷史**
- 清楚的分支和合併視圖
- 顏色區分不同分支
- 滑鼠懸停顯示詳細資訊

🔍 **進階篩選**
- 按作者篩選提交
- 按日期範圍篩選
- 按檔案路徑篩選

⚡ **快速操作**
- 右鍵建立分支
- 直接 cherry-pick 提交
- 一鍵 merge 或 rebase

👁️ **GitLens 核心功能**

📝 **Blame 註解**
- 每行程式碼的作者和時間
- 懸停顯示完整提交資訊
- 快速跳轉到相關提交

🔍 **檔案歷史**
- 完整的檔案修改歷史
- 視覺化時間軸
- 快速比較不同版本

🌿 **分支比較**
- 分支間的差異檢視
- 提交統計和圖表
- 貢獻者分析

{
  "gitlens.blame.format": "${author} • ${date} • ${message}",
  "gitlens.blame.highlight.enabled": true,
  "gitlens.currentLine.enabled": true,
  "gitlens.hovers.currentLine.over": "line",
  "gitlens.views.repositories.files.layout": "tree"
}

⚔️ **衝突解決界面**

📍 **Current (HEAD)**
- 當前分支的變更
- 顯示為左側面板
- 標記為綠色

📍 **Incoming**
- 要合併進來的變更
- 顯示為右側面板
- 標記為藍色

📍 **Result**
- 最終合併結果
- 中間編輯面板
- 可手動編輯調整

🔧 **一鍵解決選項**

- **Accept Current**: 保留當前分支的變更
- **Accept Incoming**: 採用傳入的變更
- **Accept Both**: 保留雙方的變更
- **Compare Changes**: 詳細比較差異

#!/bin/sh
### .git/hooks/pre-commit
### VS Code 可以自動執行的 Git Hooks

### 程式碼格式檢查
npm run lint || exit 1

### 自動格式化
npm run format

### 執行快速測試
npm run test:unit || exit 1

echo "Pre-commit 檢查完成 ✅"

// .vscode/settings.json
{
  "git.confirmSync": false,
  "git.autofetch": true,
  "git.pruneOnFetch": true,
  "git.rebaseWhenSync": true,
  
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,
  "files.trimFinalNewlines": true,
  
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  }
}

### 查看設定
git config --list
git config user.name
git config user.email

### 設定別名
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.cm commit

### 查看說明
git help <command>
git <command> --help

### 初始化倉庫
git init

### 複製倉庫
git clone <url>
git clone <url> <directory>

### 查看遠端倉庫
git remote -v
git remote show origin

### 新增遠端倉庫
git remote add upstream <url>

### 查看分支
git branch                    # 本地分支
git branch -r                 # 遠端分支
git branch -a                 # 所有分支

### 建立分支
git branch <branch-name>      # 建立但不切換
git checkout -b <branch-name> # 建立並切換
git switch -c <branch-name>   # 建立並切換（新語法）

### 切換分支
git checkout <branch-name>
git switch <branch-name>      # 新語法

### 刪除分支
git branch -d <branch-name>   # 安全刪除
git branch -D <branch-name>   # 強制刪除
git push origin --delete <branch-name>  # 刪除遠端分支

### 重新命名分支
git branch -m <new-name>      # 重新命名目前分支
git branch -m <old> <new>     # 重新命名指定分支

### 查看狀態
git status
git status -s                 # 簡短格式

### 新增檔案
git add <file>                # 新增特定檔案
git add .                     # 新增所有變更
git add -A                    # 新增所有變更（包含刪除）
git add -p                    # 互動式新增

### 提交變更
git commit -m "message"       # 提交並附訊息
git commit -am "message"      # 新增並提交已追蹤檔案
git commit --amend            # 修改最後一次提交

### 查看歷史
git log                       # 詳細歷史
git log --oneline             # 簡潔歷史
git log --graph               # 圖形化歷史
git log -p                    # 顯示變更內容
git log --author="name"       # 特定作者
git log --since="2 weeks ago" # 時間範圍

### 拉取變更
git fetch                     # 取得遠端變更（不合併）
git pull                      # 取得並合併
git pull --rebase             # 取得並 rebase

### 推送變更
git push                      # 推送到預設遠端
git push origin <branch>      # 推送到特定分支
git push -u origin <branch>   # 推送並設定上游
git push --force-with-lease   # 安全的強制推送

### 合併分支
git merge <branch>            # 合併指定分支
git merge --no-ff <branch>    # 強制建立合併提交
git merge --squash <branch>   # 壓縮合併

### 檢查差異
git diff                      # 工作目錄 vs 暫存區
git diff --staged             # 暫存區 vs 最後提交
git diff HEAD                 # 工作目錄 vs 最後提交
git diff <branch1> <branch2>  # 比較分支

### 檢查檔案
git show <commit>             # 顯示特定提交
git show <commit>:<file>      # 顯示特定版本的檔案
git blame <file>              # 顯示每行的作者

### 取消變更
git checkout -- <file>        # 復原工作目錄的檔案
git reset HEAD <file>         # 取消暫存
git reset --soft HEAD~1       # 取消提交（保留變更）
git reset --hard HEAD~1       # 取消提交（刪除變更）

### 回復提交
git revert <commit>           # 建立新提交來復原
git revert --no-commit <commit>  # 復原但不提交

### 暫存變更
git stash                     # 暫存變更
git stash pop                 # 恢復暫存
git stash list                # 查看暫存清單
git stash drop                # 刪除暫存

### Rebase
git rebase <branch>           # 重新基於指定分支
git rebase -i HEAD~3          # 互動式 rebase
git rebase --continue         # 繼續 rebase
git rebase --abort            # 中止 rebase

### Cherry-pick
git cherry-pick <commit>      # 套用特定提交
git cherry-pick <start>..<end>  # 套用提交範圍

### 標籤
git tag                       # 查看標籤
git tag <tag-name>            # 建立標籤
git tag -d <tag-name>         # 刪除標籤
git push origin <tag-name>    # 推送標籤

### 清理
git clean -f                  # 刪除未追蹤檔案
git clean -fd                 # 刪除未追蹤檔案和目錄
git gc                        # 垃圾回收

### GitHub CLI (gh)
gh auth login                 # 登入 GitHub
gh repo view                  # 查看倉庫資訊
gh pr list                    # 列出 Pull Requests
gh pr create                  # 建立 Pull Request
gh pr merge                   # 合併 Pull Request
gh workflow list              # 列出工作流程
gh workflow run               # 執行工作流程
gh run list                   # 列出執行記錄
gh run watch                  # 監看執行狀態

### Actions 本地測試 (act)
act                          # 執行所有工作流程
act push                     # 模擬 push 事件
act pull_request             # 模擬 PR 事件
act -l                       # 列出可用工作
act -n                       # 乾運行模式

### Docker 相關
docker build -t app:latest . # 建構映像
docker run -p 8080:8080 app  # 執行容器
docker logs <container-id>   # 查看日誌
docker exec -it <container> bash  # 進入容器

# 查看操作歷史
git reflog

# 恢復到安全狀態
git reset --hard HEAD@{n}

# 強制同步遠端
git fetch origin
git reset --hard origin/main

# 本地測試 GitHub Actions
act

# 檢查工作流程狀態
gh run list

# 重新執行失敗的工作流程
gh run rerun <run-id>

### 1. 檢查儲存庫大小
git count-objects -vH

### 2. 清理不必要的物件
git gc --aggressive --prune=now

### 3. 檢查是否有大型檔案
git rev-list --objects --all | \
  git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
  awk '/^blob/ {print substr($0,6)}' | \
  sort --numeric-sort --key=2 | \
  tail -10

### 4. 考慮使用 Git LFS
git lfs migrate import --include="*.zip,*.pdf,*.png"

### 1. 查看所有操作歷史
git reflog

### 2. 找到分支刪除前的 commit
git reflog | grep "分支名稱"

### 3. 從 commit 重新建立分支
git checkout -b 分支名稱 <commit-hash>

### 4. 推送恢復的分支
git push origin 分支名稱

### 1. 中止當前合併
git merge --abort

### 2. 使用工具輔助合併
git mergetool

### 3. 分步驟解決衝突
git checkout --theirs <檔案>  # 使用對方版本
git checkout --ours <檔案>    # 使用我方版本

### 4. 手動編輯後標記為已解決
git add <已解決的檔案>
git commit

### 部分克隆（減少初始下載時間）
git clone --filter=blob:none <url>
git clone --filter=tree:0 <url>

### 淺層克隆（僅下載最近的歷史）
git clone --depth 1 <url>

### 僅克隆單一分支
git clone --single-branch --branch main <url>

### 啟用檔案系統監控
git config core.fsmonitor true
git config core.untrackedCache true

### 設定合理的 pack 大小
git config pack.packSizeLimit 2g
git config pack.windowMemory 256m

### 啟用平行處理
git config pack.threads 0
git config index.threads 0

🚨 **緊急情況聯絡方式**

- 生產環境問題: 值班工程師 (24/7)
- 安全事件: 資安事件回應小組
- 系統故障: 基礎設施團隊

📚 **內部學習計畫**

- 每月技術分享會
- Git 進階工作坊
- Code Review 最佳實務討論
- 新工具和功能介紹