# 吉八小

**集滿八小時** — 自動從 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
```