138 lines
4.4 KiB
Markdown
138 lines
4.4 KiB
Markdown
# 吉八小
|
||
|
||
**集滿八小時** — 自動從 GitLab 任務看板抓取工作項目，用 **Grok LLM** 分析後填入 [PTS 工時系統](https://tw-timesheet.supermicro.com/PTS/)。可選併入 **Teams / Outlook 網頁行事曆**會議時數。
|
||
|
||
## 功能
|
||
|
||
- 網頁輸入 **PTS 帳密** → 直接打 PTS Login API（Windows/NTLM；可選 Forms）
|
||
- 可選：網頁輸入 **Microsoft 帳密** → 優先 Graph 帳密 API；MFA 時改瀏覽器登入，之後仍打行事曆 API
|
||
- 從 GitLab 抓取任務（看板 Bug + 目前衝刺 milestone）
|
||
- **Grok** 產生專業英文 Description 與時數分配
|
||
- 每日最多 **8 小時**（0.5h 單位）
|
||
- Chrome Extension **備援**同步 PTS Token
|
||
- **CompBase 刷卡補填**（獨立分頁 `/compbase`）：NTLM 登入出勤系統 → 掃「應刷未刷」→ 一鍵補刷退
|
||
|
||
## 架構
|
||
|
||
```
|
||
Web UI 帳密 → PTS Windows/NTLM Login → Backend
|
||
Web UI 帳密 → Playwright / Outlook 爬蟲 → 會議時數
|
||
GitLab API → 任務 ↗
|
||
Grok API → 分析填寫計畫 ↗
|
||
（備援）Chrome Extension → PTS Token
|
||
```
|
||
|
||
## 快速開始
|
||
|
||
### 1. 安裝
|
||
|
||
```bash
|
||
cd pts
|
||
make setup
|
||
```
|
||
|
||
會安裝 Python 依賴與 Playwright Chromium。
|
||
|
||
### 2. 編輯 `.env`
|
||
|
||
```env
|
||
GITLAB_TOKEN=你的_gitlab_token
|
||
XAI_API_KEY=你的_grok_api_key
|
||
```
|
||
|
||
其餘設定（PTS / Teams 帳密、專案名等）建議在 Web UI 操作；密碼會以 Fernet 加密寫入本機 `settings.json`。
|
||
|
||
### 3. 啟動並登入
|
||
|
||
**本機 Python：**
|
||
|
||
```bash
|
||
make start
|
||
```
|
||
|
||
**Docker（不存本機資料，`/data` 用 tmpfs，關容器即消失）：**
|
||
|
||
```bash
|
||
make docker-start
|
||
# 或: make docker-up
|
||
```
|
||
|
||
可選：在專案根目錄 `.env` 放 `GITLAB_TOKEN` / `XAI_API_KEY` 等，compose 會注入容器環境變數（仍不會掛載資料目錄）。
|
||
|
||
開啟 http://localhost:8765
|
||
|
||
停止 Docker：`make docker-down`
|
||
|
||
1. **PTS**：輸入帳號（建議 `DOMAIN\user`）與密碼 → **登入 PTS**
|
||
2. **Teams**（選用）：勾選啟用 → 輸入 Microsoft 帳密 → **登入並抓行事曆**
|
||
- 有 MFA 時會開瀏覽器視窗，請完成驗證
|
||
3. **進階設定**：GitLab Token / Grok / 專案 / 排程
|
||
|
||
### 4. 一鍵填寫
|
||
|
||
```bash
|
||
make preview # 預覽
|
||
make dry-run # 試跑
|
||
make fill # 正式填今天
|
||
```
|
||
|
||
## Make 指令
|
||
|
||
| 指令 | 說明 |
|
||
|------|------|
|
||
| `make setup` | venv、依賴、Playwright Chromium |
|
||
| `make status` | 檢查設定與連線 |
|
||
| `make preview` / `make fill` | 預覽 / 填寫今天 |
|
||
| `make fill-range START=... END=...` | 補寫區間 |
|
||
| `make start` | 啟動 Web UI（http://localhost:8765） |
|
||
|
||
## 帳密與安全
|
||
|
||
- 密碼以 **Fernet** 加密存在本機資料目錄；金鑰為 `data/.secret_key`（或 Docker 的 `/data/.secret_key`）
|
||
- **僅供個人本機使用**，勿提交 settings / secret key 到 git
|
||
- PTS Token 過期時：先 Refresh，失敗則用儲存帳密重登
|
||
- Teams session 存在 `teams_browser_state.json`；過期會嘗試重登（若觸發 MFA 需再互動一次）
|
||
|
||
## 備援：Chrome Extension
|
||
|
||
若公司網路僅允許瀏覽器 Windows SSO、帳密 API 不可用：
|
||
|
||
1. 下載 UI 底部「備援」區塊的 Extension
|
||
2. 登入 PTS 網頁後同步 Token 到後端
|
||
|
||
## 常見問題
|
||
|
||
**PTS 登入失敗**
|
||
→ 確認在公司網路/VPN；帳號試 `DOMAIN\user`；或改用 Extension 備援。
|
||
|
||
**Teams / Docker 如何完成 MFA**
|
||
→ Docker 內建 **Xvfb + noVNC**：設定頁按「登入」會跳出 MFA 面板
|
||
- **互動畫面**（http://主機:6080）：可點擊、輸入，跟真的 Chrome 一樣
|
||
- **即時截圖**：約每 1.5 秒更新，方便對 Authenticator 數字
|
||
→ 登入流程中瀏覽器會**保持開啟最多約 10 分鐘**，完成 MFA 前不會關掉。
|
||
→ 需映射埠 `6080`（`docker-compose` 已設定）。若 iframe 空白，用「新分頁開啟」。
|
||
|
||
**Missing PTS session**
|
||
→ 在 Web UI 重新登入 PTS，或用 Extension 同步。
|
||
|
||
**Project not found**
|
||
→ 進階設定中 `Project Name` 需與 PTS 下拉一致。
|
||
|
||
## 專案結構
|
||
|
||
```
|
||
pts/
|
||
├── backend/
|
||
│ ├── main.py
|
||
│ └── services/
|
||
│ ├── pts_client.py # PTS API + 帳密登入
|
||
│ ├── teams_calendar_scraper.py # Outlook 網頁爬蟲
|
||
│ ├── secret_box.py # 密碼加密
|
||
│ ├── gitlab_client.py
|
||
│ ├── grok_client.py
|
||
│ └── planner.py
|
||
├── extension/ # 備援憑證同步
|
||
├── frontend/ # Web UI
|
||
└── Makefile
|
||
```
|