本工具專為雲端運維團隊設計，能夠自動從 GitLab 專案中擷取 Issue 資訊，同步至 Google Sheet 並以甘特圖形式呈現，同時生成詳細的雙月工作分析報表。主要用於追蹤團隊成員在不同工作類型（VCS、VKS、VDS 等）的時間分配，協助管理層進行資源規劃與績效評估。

• 📊 自動化甘特圖生成：將 GitLab Issue 轉換為視覺化時間軸
• 📈 樞紐分析表報表：生成詳細的工作類型分析與趨勢比較
• 🔄 智能同步機制：避免重複處理，僅同步新增 Issue
• 👥 多人協作支援：單一 Issue 可由多人共同處理
• 🎯 靈活專案配置：支援標籤篩選或全開放 Issue 擷取
• 📅 時間範圍控制：可設定起始日期進行過濾

GitLab API ──► 數據處理器 ──► Google Sheet ──► 甘特圖 ──► 樞紐分析表報表
    ↓              ↓              ↓           ↓           ↓
  Issue 擷取    標籤篩選      時間軸生成   進度追蹤    工作分析

• Python 3.6 或更高版本
• 網路連線至 GitLab 和 Google API
• GitLab API 存取權限
• Google API 服務帳號憑證

pip install -r requirements.txt

主要依賴套件：

google-api-python-client==2.79.0
google-auth==2.16.0
python-gitlab==3.13.0
pyyaml==6.0
systemd-python==234
requests==2.28.2

1. 前往 Google Cloud Console
2. 創建專案並啟用 Google Sheets API
3. 創建服務帳號並下載 JSON 憑證檔案
4. 將 Google Sheet 共享給服務帳號的電子郵件地址
5. 更新 config.yaml 中的憑證路徑

1. 登入 GitLab 並前往個人設定
2. 創建具有 api 權限的個人存取權杖
3. 更新 config.yaml 中的權杖資訊

# Google Sheet 配置
google_sheet:
  credentials_path: "/path/to/credentials.json"
  spreadsheet_id: "your_spreadsheet_id"

  # 工作表欄位定義（新功能）
  worksheet_columns:
    gitlab_link: 0        # A 欄 - GitLab 連結
    issue_title: 1        # B 欄 - Issue 標題
    owner: 2              # C 欄 - 負責人
    type: 3               # D 欄 - 工作類型
    subtype: 4            # E 欄 - 第二階工作類型
    closed: 5             # F 欄 - 是否關閉
    note: 6               # G 欄 - 備註
    timeline_start: 7     # H 欄 - 時間軸開始位置

# GitLab 配置
gitlab:
  base_url: "https://your-gitlab.com"
  token: "your_api_token"

  # 專案設定（支援混合模式）
  project_id_list:
    - 123  # 使用全域標籤篩選
    - project_id: 456
      name: "專案名稱"
      fetch_all_open_issues: true  # 擷取所有開放 issue

  # 全域標籤列表
  label_list:
    - "VCS::GOC"
    - "VCS::GPU"
    - "STG::Ceph"

  # 使用者與角色管理
  user_list:
    - "user1"
    - "user2"
    - "manager1"

  user_roles:
    managers:  # 主管角色（排除在個人報表外）
      - "manager1"

  # 工作分類定義
  type_list:
    - "VCS"
    - "VKS"
    - "VDS"
    - "其他"

  subtype_list:
    - "客服進單"
    - "日常維運"
    - "硬體報修"
    - "專案支援"

# 日誌配置
log_config:
  level: "INFO"
  tag: "gitlab-gantt-sync"
  console_output: false

# 僅更新甘特圖（不生成報表）
python3 main.py

# 更新甘特圖並生成樞紐分析表報表
python3 main.py -r
python3 main.py --report

# 每日凌晨更新甘特圖
0 0 * * * /usr/bin/python3 /path/to/main.py

# 每月1日生成報表
0 0 1 * * /usr/bin/python3 /path/to/main.py --report

# 每週一檢查並同步
0 8 * * 1 /usr/bin/python3 /path/to/main.py

[Unit]
Description=GitLab Issue Gantt Sync
After=network.target

[Service]
Type=oneshot
User=ubuntu
ExecStart=/usr/bin/python3 /path/to/main.py
WorkingDirectory=/path/to/project

• ✅ 從 GitLab 擷取 Issue 資訊並填入 A、B 欄
• ✅ 自動生成完整年度甘特圖時間軸
• ✅ 創建 Owner、Type、SubType 下拉選單
• ✅ 創建 Closed 欄位的核取方塊
• ✅ 設定週末背景色與欄位格式

• 📝 C 欄 (Owner)：選擇負責人
• 📝 D 欄 (Type)：選擇工作類型（VCS、VKS、VDS等）
• 📝 E 欄 (SubType)：選擇子類型（客服進單、日常維運等）
• 📝 F 欄 (Closed)：勾選是否已關閉
• 📝 G 欄 (Note)：填寫備註
• 📝 時間軸區域：填入處理 Issue 的人員名稱（支援多人，以逗號分隔）

• 📊 系統自動根據甘特圖數據生成雙月樞紐分析表
• 📈 顯示各人員在不同工作類型的時間分配
• 📉 計算各類型工作的佔比及與前期的變化趨勢
• 👤 為每個一般使用者（非主管）生成獨立報表頁籤

• 🎯 Issue 級別統計：精確到每個 Issue 的工作天數
• 📊 多層次分析：Type → SubType → Issue 的階層結構
• 📈 趨勢比較：與前一個雙月期間的百分比變化
• 👥 個人化報表：每位成員獨立的工作統計頁籤
• 🔢 自動計算：合併儲存格與百分比格式自動處理

# 檢查憑證檔案路徑和權限
ls -la /path/to/credentials.json

解決方案：

• 確認憑證檔案存在且可讀取
• 檢查服務帳號是否有 Google Sheet 存取權限
• 驗證 spreadsheet_id 是否正確

# 測試 API 連線
curl -H "PRIVATE-TOKEN: your_token" "https://your-gitlab.com/api/v4/projects"

解決方案：

• 檢查 GitLab URL 和 token 設定
• 確認 token 具有 api 權限
• 檢查網路連線狀態

症狀： 時間軸生成失敗或數據同步異常

解決方案：

• 檢查 config.yaml 中的欄位定義
• 確認工作表標頭與預期一致
• 重新生成工作表或手動調整結構

# 查看系統日誌
journalctl -t gitlab-gantt-sync

# 查看最近的錯誤
journalctl -t gitlab-gantt-sync -p err --since "1 hour ago"

# 即時監控日誌
journalctl -t gitlab-gantt-sync -f

# 臨時啟用除錯模式
log_config:
  level: "DEBUG"
  console_output: true

• Google Sheets API：預設每批次 3 個請求，間隔 0.5 秒
• GitLab API：重試機制 3 次，間隔 5 分鐘
• 報表生成：用戶間延遲 15 秒，避免配額超限

• 工作表數據快取，避免重複 API 調用
• 時間軸解析結果快取，提升報表生成效率

1. 編輯 config.yaml 中的 type_list 和 subtype_list
2. 重新執行程式，下拉選單將自動更新

1. 修改 config.yaml 中的 worksheet_columns
2. 調整 expected_headers 對應的標頭名稱
3. 系統將自動適配新的欄位結構

gitlab:
  project_id_list:
    - project_id: 新專案ID
      name: "專案名稱"
      fetch_all_open_issues: true  # 或使用標籤篩選