https://github.com/timhuang1204/issue-gantt-sync
將 Issue 同步到 Google Sheet 甘特圖並生成工作量報表，用於團隊資源分配分析。支援 GitLab，未來可擴展至其他平台。
https://github.com/timhuang1204/issue-gantt-sync
gantt-chart gitlab google-sheets project-managment python resource-management team-management workload-analysis
Last synced: 2 months ago
JSON representation
將 Issue 同步到 Google Sheet 甘特圖並生成工作量報表，用於團隊資源分配分析。支援 GitLab，未來可擴展至其他平台。
- Host: GitHub
- URL: https://github.com/timhuang1204/issue-gantt-sync
- Owner: timhuang1204
- License: apache-2.0
- Created: 2025-05-22T17:41:08.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-20T07:46:44.000Z (3 months ago)
- Last Synced: 2026-03-21T00:37:00.761Z (3 months ago)
- Topics: gantt-chart, gitlab, google-sheets, project-managment, python, resource-management, team-management, workload-analysis
- Language: Python
- Homepage:
- Size: 211 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
# GitLab Issue 到 Google Sheet 甘特圖同步工具
[](https://python.org)
[](LICENSE)
[]()
## 專案簡介
本工具專為雲端運維團隊設計，能夠自動從 GitLab 專案中擷取 Issue 資訊，同步至 Google Sheet 並以甘特圖形式呈現，同時生成詳細的雙月工作分析報表。主要用於追蹤團隊成員在不同工作類型（VCS、VKS、VDS 等）的時間分配，協助管理層進行資源規劃與績效評估。
### 核心功能
- 📊 **自動化甘特圖生成**：將 GitLab Issue 轉換為視覺化時間軸
- 📈 **樞紐分析表報表**：生成詳細的工作類型分析與趨勢比較
- 🔄 **智能同步機制**：避免重複處理，僅同步新增 Issue
- 👥 **多人協作支援**：單一 Issue 可由多人共同處理
- 🎯 **靈活專案配置**：支援標籤篩選或全開放 Issue 擷取
- 📅 **時間範圍控制**：可設定起始日期進行過濾
## 系統架構
```
GitLab API ──► 數據處理器 ──► Google Sheet ──► 甘特圖 ──► 樞紐分析表報表
↓ ↓ ↓ ↓ ↓
Issue 擷取 標籤篩選 時間軸生成 進度追蹤 工作分析
```
### 模組結構
| 模組 | 功能說明 |
|------|----------|
| `main.py` | 主程序入口，整合各模組功能 |
| `argument_parser.py` | 命令行參數解析，支援報表與年份參數 |
| `config_handler.py` | 配置管理，支援欄位定義與用戶角色 |
| `gitlab_api_handler.py` | GitLab API 互動，含重試機制 |
| `data_processor.py` | 數據處理與篩選邏輯 |
| `google_sheet_api_handler.py` | Google Sheet API 操作 |
| `worksheet_manager.py` | 甘特圖工作表管理 |
| `report_generator.py` | 樞紐分析表報表生成 |
| `utils.py` | 日期處理與工具函數 |
| `logger.py` | 系統日誌管理 |
## 安裝與設定
### 1. 系統需求
- Python 3.6 或更高版本
- 網路連線至 GitLab 和 Google API
- GitLab API 存取權限
- Google API 服務帳號憑證
### 2. 安裝依賴套件
```bash
pip install -r requirements.txt
```
**主要依賴套件：**
```txt
google-api-python-client==2.79.0
google-auth==2.16.0
google-auth-httplib2==0.1.0
google-auth-oauthlib==1.0.0
python-gitlab==3.13.0
pyyaml==6.0
systemd-python==234
requests==2.28.2
```
### 3. Google API 設定
1. 前往 [Google Cloud Console](https://console.cloud.google.com/)
2. 創建專案並啟用 Google Sheets API
3. 創建服務帳號並下載 JSON 憑證檔案
4. 將 Google Sheet 共享給服務帳號的電子郵件地址
5. 更新 `config.yaml` 中的憑證路徑
### 4. GitLab API 設定
1. 登入 GitLab 並前往個人設定
2. 創建具有 `api` 權限的個人存取權杖
3. 更新 `config.yaml` 中的權杖資訊
## 配置檔案說明
### 基本配置結構
```yaml
# Google Sheet 配置
google_sheet:
credentials_path: "/path/to/credentials.json"
spreadsheet_id: "your_spreadsheet_id"
# 報表設定
report_settings:
workday_highlight_method: "outlier" # 高亮方法：outlier (離群值) 或 top_n (前 N 個最大值)
workday_highlight_outlier_multiplier: 1.5 # 離群值倍數（使用 Q3 + multiplier * IQR），預設 1.5
# 工作表欄位定義
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 # 只抓取根據全域標籤篩選的 issue
# 以下段落是設定所有 issue 都抓取
- project_id: 456
name: "專案名稱"
fetch_all_open_issues: true # 擷取所有開放 issue
# 全域標籤列表
label_list:
- "A::B"
- "C::D"
- "E::F"
# 使用者與角色管理
user_list:
- "user1"
- "user2"
- "manager1"
user_roles:
managers: # 主管角色（排除在個人報表外）
- "manager1"
# 工作分類定義
# 若有新增項目，只有觸發 `新建工作表` 的行為才會套用新的項目，
# 舊有的需要在 Google Sheet 的 資料 > 資料驗證 進行修改
type_list:
- "A"
- "B"
- "C"
- "其他"
subtype_list:
- "客服進單"
- "日常維運"
- "硬體報修"
- "專案支援"
# 日誌配置
log_config:
level: "INFO"
tag: "gitlab-gantt-sync"
console_output: false
```
## 使用方法
### 基本操作
```bash
# 僅更新甘特圖（不生成報表）
python3 main.py
# 僅生成樞紐分析表報表（跳過 GitLab Issue 同步）
python3 main.py -r
python3 main.py --report
# 指定年份生成報表
python3 main.py -r -y 2025
python3 main.py --report --year 2025
# 指定年份更新甘特圖
python3 main.py -y 2024
# 生成年度工作樞紐分析表
python3 main.py -a
python3 main.py --annual-work
# 指定年份生成年度工作樞紐分析表
python3 main.py -a -y 2025
```
### 命令行參數
| 參數 | 說明 |
|------|------|
| `-r`, `--report` | 生成雙月報表。若指定此參數，則僅生成報表，跳過 GitLab Issue 同步。 |
| `-y`, `--year` | 指定報表年度。若不指定則使用當年。 |
| `-a`, `--annual-work` | 生成年度工作樞紐分析表。從報表工作表的 K-N 欄讀取數據，生成按 SubType/Type 分類的樞紐分析表。 |
### 自動化部署
#### Crontab 設定範例
```bash
# 每日凌晨更新甘特圖
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
```
#### systemd 服務設定
```ini
[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
```
## 工作流程說明
### 1. 自動化部分
- ✅ 從 GitLab 擷取 Issue 資訊並填入 A、B 欄
- ✅ 自動生成完整年度甘特圖時間軸
- ✅ 創建 Owner、Type、SubType 下拉選單
- ✅ 創建 Closed 欄位的核取方塊
- ✅ 設定週末背景色與欄位格式
### 2. 手動操作部分
- 📝 **C 欄 (Owner)**：選擇負責人
- 📝 **D 欄 (Type)**：選擇工作類型（VCS、VKS、VDS等）
- 📝 **E 欄 (SubType)**：選擇子類型（客服進單、日常維運等）
- 📝 **F 欄 (Closed)**：勾選是否已關閉
- 📝 **G 欄 (Note)**：填寫備註
- 📝 **時間軸區域**：填入處理 Issue 的人員名稱（支援多人，以逗號分隔）
### 3. 報表產出
- 📊 系統自動根據甘特圖數據生成雙月樞紐分析表
- 📈 顯示各人員在不同工作類型的時間分配
- 📉 計算各類型工作的佔比及與前期的變化趨勢
- 👤 為每個一般使用者（非主管）生成獨立報表頁籤
## 報表功能詳解
### 樞紐分析表結構
| 欄位 | 說明 |
|------|------|
| Type | 工作類型（VCS、VKS等） |
| SubType | 第二階分類（客服進單、日常維運等） |
| Issue | 具體 Issue 標題 |
| Workday | 工作天數 |
| Workday 佔比 | 該 Issue 在總工作天數中的比例 |
| Workday @ SubType 佔比 | SubType 在總工作天數中的比例 |
| SubType 與前次雙月差異 | 與前一個雙月期間的變化 |
| Workday @ Type 佔比 | Type 在總工作天數中的比例 |
| Type 與前次雙月差異 | 與前一個雙月期間的變化 |
### 報表特色
- 🎯 **Issue 級別統計**：精確到每個 Issue 的工作天數
- 📊 **多層次分析**：Type → SubType → Issue 的階層結構
- 📈 **趨勢比較**：與前一個雙月期間的百分比變化
- 👥 **個人化報表**：每位成員獨立的工作統計頁籤
- 🔢 **自動計算**：合併儲存格與百分比格式自動處理
### Workday 高亮標示條件
報表中會自動將花費時間較多的 Issue 以黃色背景標示（Workday 和 Workday 佔比欄位）。
#### 離群值檢測演算法（IQR 方法）
系統使用四分位距（Interquartile Range, IQR）方法檢測離群值：
1. **計算四分位數**：
- Q1（第 25 百分位數）
- Q3（第 75 百分位數）
- IQR = Q3 - Q1
2. **計算閾值**：
```
threshold = Q3 + multiplier × IQR
```
- 預設 `multiplier = 1.5`（可在 `config.yaml` 中調整）
3. **標示條件**：
- 當 `Workday > threshold` 時，該列的 Workday 和 Workday 佔比欄位會以黃色背景標示
- 若數據量少於 4 筆，則僅標示最大值
4. **適用範圍**：
- 雙月報表：各期間獨立計算閾值
- 年度總覽：使用全年數據計算閾值
#### 配置選項
```yaml
google_sheet:
report_settings:
workday_highlight_method: "outlier" # 高亮方法
workday_highlight_outlier_multiplier: 1.5 # IQR 倍數
```
## 故障排除
### 常見問題
#### 1. Google API 認證錯誤
```bash
# 檢查憑證檔案路徑和權限
ls -la /path/to/credentials.json
```
**解決方案：**
- 確認憑證檔案存在且可讀取
- 檢查服務帳號是否有 Google Sheet 存取權限
- 驗證 spreadsheet_id 是否正確
#### 2. GitLab API 連線失敗
```bash
# 測試 API 連線
curl -H "PRIVATE-TOKEN: your_token" "https://your-gitlab.com/api/v4/projects"
```
**解決方案：**
- 檢查 GitLab URL 和 token 設定
- 確認 token 具有 `api` 權限
- 檢查網路連線狀態
#### 3. 工作表結構錯誤
**症狀：** 時間軸生成失敗或數據同步異常
**解決方案：**
- 檢查 `config.yaml` 中的欄位定義
- 確認工作表標頭與預期一致
- 重新生成工作表或手動調整結構
### 日誌查看
```bash
# 查看系統日誌
journalctl -t gitlab-gantt-sync
# 查看最近的錯誤
journalctl -t gitlab-gantt-sync -p err --since "1 hour ago"
# 即時監控日誌
journalctl -t gitlab-gantt-sync -f
```
### 除錯模式
```yaml
# 臨時啟用除錯模式
log_config:
level: "DEBUG"
console_output: true
```
## 效能調優
### API 配額管理
- **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. 系統將自動適配新的欄位結構
### 新增專案監控
```yaml
gitlab:
project_id_list:
- project_id: 新專案ID
name: "專案名稱"
fetch_all_open_issues: true # 或使用標籤篩選
```