# FWAuto 用量追蹤系統 - 完整教學

## 概述

本系統讓你可以追蹤 FWAuto AI 功能的使用量，包含：
- Google OAuth 登入
- 自動記錄每次 AI 執行的 token 用量和費用
- 網頁 Dashboard 查看用量統計

## 系統架構

```
┌─────────────────────────────────────────────────────────────────┐
│  用戶                                                           │
│                                                                 │
│  1. fwauto auth login → 開啟瀏覽器 Google 登入                  │
│  2. fwauto feat "..." → 執行 AI 功能                            │
│  3. 瀏覽器查看 Dashboard → 查看用量統計                          │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│  FWAuto CLI                                                     │
│                                                                 │
│  ai_brain.py 執行 Claude Agent SDK                              │
│       │                                                         │
│       └─► ResultMessage (含 usage + cost)                       │
│               │                                                 │
│               └─► POST /api/report-usage ──────────────────────►│
└─────────────────────────────────────────────────────────────────┘
                                                                  │
                            ┌─────────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│  Flask Server (localhost:5000)                                  │
│                                                                 │
│  • Google OAuth 登入                                            │
│  • 用量回報 API                                                  │
│  • 網頁 Dashboard                                               │
│  • SQLite 資料庫                                                │
└─────────────────────────────────────────────────────────────────┘
```

---

## 第一部分：環境設定

### 1.1 安裝 FWAuto（全域安裝）

```bash
cd /path/to/FWAuto-main
uv tool install --force --editable .
```

安裝後可直接使用 `fwauto` 指令。

### 1.2 安裝 Flask Server 依賴

```bash
cd /path/to/FWAuto-main/flask_server
pip install -r requirements.txt
```

---

## 第二部分：Google OAuth 設定

### 2.1 建立 Google Cloud 專案

1. 前往 [Google Cloud Console](https://console.cloud.google.com/)
2. 點擊上方專案選擇器 → **新增專案**
3. 專案名稱：`FWAuto`
4. 點擊 **建立**

### 2.2 設定 OAuth 同意畫面

1. 左側選單 → **APIs & Services** → **OAuth consent screen**
2. 選擇 **External** → **建立**
3. 填寫：
   | 欄位 | 內容 |
   |------|------|
   | 應用程式名稱 | `FWAuto` |
   | 使用者支援電子郵件 | 你的 email |
   | 開發人員聯絡資訊 | 你的 email |
4. 點擊 **儲存並繼續**（連續 3 次）

### 2.3 建立 OAuth 憑證

1. 左側選單 → **Credentials**
2. 點擊 **+ CREATE CREDENTIALS** → **OAuth client ID**
3. 應用程式類型：**Web application**
4. 名稱：`FWAuto`
5. **Authorized redirect URIs** 加入：
   ```
   http://localhost:5000/auth/google/callback
   ```
6. 點擊 **建立**
7. 複製 **Client ID** 和 **Client Secret**

### 2.4 設定憑證到 Flask Server

編輯 `flask_server/app.py`，找到這段並填入你的憑證：

```python
# Google OAuth 配置
GOOGLE_CLIENT_ID = "你的-client-id.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET = "你的-client-secret"
```

或使用環境變數：

```bash
export GOOGLE_CLIENT_ID="你的-client-id"
export GOOGLE_CLIENT_SECRET="你的-client-secret"
```

---

## 第三部分：啟動服務

### 3.1 啟動 Flask Server

```bash
cd /path/to/FWAuto-main/flask_server
python app.py
```

看到以下訊息表示啟動成功：

```
============================================================
🚀 FWAuto Usage Server
============================================================
   Database: .../flask_server/fwauto_usage.db
   URL: http://localhost:5000
```

### 3.2 確認服務運行

瀏覽器打開 `http://localhost:5000`，應該看到首頁。

---

## 第四部分：CLI 使用教學

### 4.1 認證指令

| 指令 | 功能 |
|------|------|
| `fwauto auth status` | 查看登入狀態 |
| `fwauto auth login` | Google OAuth 登入 |
| `fwauto auth login --dev` | 開發測試登入（不需要 Google） |
| `fwauto auth logout` | 登出 |

### 4.2 登入流程

```bash
# 1. 查看狀態（應顯示未登入）
fwauto auth status

# 2. 執行登入（會開啟瀏覽器）
fwauto auth login

# 3. 在瀏覽器中選擇 Google 帳號登入

# 4. 登入成功後，終端機會顯示成功訊息

# 5. 確認已登入
fwauto auth status
```

### 4.3 執行 AI 功能

```bash
# 進入專案目錄
cd /path/to/your-project

# 執行 AI 功能（會自動記錄用量）
fwauto feat "實作某個功能"
```

### 4.4 登出

```bash
fwauto auth logout
```

---

## 第五部分：網頁 Dashboard

### 5.1 存取 Dashboard

瀏覽器打開：`http://localhost:5000`

### 5.2 登入方式

- **Google 登入**：點擊「🔐 Google 登入」
- **開發測試**：點擊「🔧 開發測試登入」

### 5.3 Dashboard 功能

登入後可查看：

| 區塊 | 內容 |
|------|------|
| 今日用量 | 今天使用的 tokens 和費用 |
| 本月用量 | 本月使用的 tokens 和費用 |
| 總計用量 | 歷史總計 tokens 和費用 |
| 使用記錄 | 最近 20 筆使用明細 |

### 5.4 登出

點擊右上角「登出」連結。

---

## 第六部分：完整測試流程

### 測試步驟

```bash
# 【終端機 1】啟動 Flask Server
cd /path/to/FWAuto-main/flask_server
python app.py

# 【終端機 2】測試 FWAuto CLI

# 1. 確認未登入
fwauto auth status
# 預期：顯示「❌ 未登入」

# 2. 執行登入
fwauto auth login
# 預期：開啟瀏覽器，完成 Google 登入後顯示成功

# 3. 確認已登入
fwauto auth status
# 預期：顯示「✅ 已登入」和用戶資訊

# 4. 進入測試專案
cd /path/to/test-project

# 5. 執行 AI 功能
fwauto feat "新增一個 hello 函數"
# 預期：AI 執行完成，用量自動回報到 Server

# 6. 查看用量
# 瀏覽器打開 http://localhost:5000/dashboard
# 預期：看到剛才的使用記錄

# 7. 登出
fwauto auth logout
# 預期：顯示「已登出」
```

---

## 第七部分：API 文件

### 認證 API

| 端點 | 方法 | 說明 |
|------|------|------|
| `/auth/login` | GET | CLI 登入入口 |
| `/auth/web-login` | GET | 網頁登入入口 |
| `/auth/google/callback` | GET | Google OAuth 回調 |
| `/auth/dev-login` | GET | 開發測試登入 |
| `/logout` | GET | 登出 |

### 用量 API

| 端點 | 方法 | 說明 |
|------|------|------|
| `/api/report-usage` | POST | 回報 AI 用量 |
| `/api/usage` | GET | 查詢用量統計 |
| `/api/usage/history` | GET | 查詢用量歷史 |

### API 認證

API 請求需要在 Header 加入 token：

```
Authorization: Bearer <user_token>
```

### 用量回報格式

```json
POST /api/report-usage
{
    "task_type": "implement_feature",
    "model": "claude-sonnet-4",
    "input_tokens": 5000,
    "output_tokens": 2000,
    "total_cost_usd": 0.035,
    "duration_ms": 45000,
    "num_turns": 8
}
```

### 用量查詢回應

```json
GET /api/usage
{
    "user": {
        "email": "user@example.com",
        "name": "User Name"
    },
    "daily": {
        "input_tokens": 5000,
        "output_tokens": 2000,
        "total_tokens": 7000,
        "cost_usd": 0.035,
        "requests": 3
    },
    "monthly": { ... },
    "total": { ... }
}
```

---

## 第八部分：檔案結構

```
FWAuto-main/
├── src/fwauto/
│   ├── auth.py              # 認證模組
│   ├── cli.py               # CLI 指令（含 auth 子指令）
│   └── nodes/
│       └── ai_brain.py      # AI 節點（含用量回報）
│
├── flask_server/
│   ├── app.py               # Flask 主程式
│   ├── schema.sql           # 資料庫 Schema
│   ├── requirements.txt     # Python 依賴
│   ├── fwauto_usage.db      # SQLite 資料庫（自動建立）
│   └── README.md            # Flask Server 說明
│
└── docs/
    └── USAGE_TRACKING_GUIDE.md  # 本文件
```

---

## 第九部分：配置檔案

### 用戶認證配置

位置：`~/.fwauto_auth.json`

```json
{
    "user_token": "ut-xxxxxxxxxxxxxxxx",
    "email": "user@example.com",
    "name": "User Name",
    "server_url": "http://localhost:5000"
}
```

### 資料庫

位置：`flask_server/fwauto_usage.db`（SQLite）

資料表：
- `users` - 用戶資料
- `usage_log` - 用量記錄

---

## 第十部分：常見問題

### Q1: 執行 fwauto 顯示 command not found

**解決方案**：全域安裝 FWAuto

```bash
cd /path/to/FWAuto-main
uv tool install --force --editable .
```

### Q2: Google 登入顯示 invalid_client

**解決方案**：確認 Google OAuth 憑證設定正確

1. 檢查 `app.py` 中的 `GOOGLE_CLIENT_ID` 和 `GOOGLE_CLIENT_SECRET`
2. 確認 Redirect URI 設定為 `http://localhost:5000/auth/google/callback`

### Q3: Google 登入顯示 redirect_uri_mismatch

**解決方案**：確認 Redirect URI 完全一致

在 Google Cloud Console 的 Redirect URI 必須是：
```
http://localhost:5000/auth/google/callback
```

注意：
- 開頭是 `http` 不是 `https`
- 結尾沒有 `/`

### Q4: 用量沒有記錄到 Dashboard

**解決方案**：

1. 確認 Flask Server 正在運行
2. 確認已登入（`fwauto auth status`）
3. 確認 AI 執行完成（沒有中途取消）

### Q5: 如何重設資料庫

```bash
cd /path/to/FWAuto-main/flask_server
rm fwauto_usage.db
python app.py  # 會自動重建資料庫
```

---

## 第十一部分：部署到正式環境

### 修改 Server URL

1. 編輯 `src/fwauto/auth.py`：
   ```python
   AUTH_SERVER_URL = "https://your-domain.com"
   ```

2. 編輯 `flask_server/app.py`：
   ```python
   GOOGLE_REDIRECT_URI = "https://your-domain.com/auth/google/callback"
   ```

3. 更新 Google Cloud Console 的 Redirect URI

### 使用 Gunicorn 運行

```bash
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 app:app
```

### 使用 HTTPS

建議使用 nginx 反向代理 + Let's Encrypt SSL 憑證。

---

## 快速參考

### CLI 指令

```bash
fwauto auth status      # 查看登入狀態
fwauto auth login       # Google 登入
fwauto auth login --dev # 開發測試登入
fwauto auth logout      # 登出
fwauto feat "..."       # AI 功能
```

### 網頁 URL

| URL | 說明 |
|-----|------|
| http://localhost:5000 | 首頁 |
| http://localhost:5000/dashboard | 用量 Dashboard |
| http://localhost:5000/docs | API 文件 |

### 重要檔案

| 檔案 | 說明 |
|------|------|
| `~/.fwauto_auth.json` | 用戶認證配置 |
| `flask_server/fwauto_usage.db` | 用量資料庫 |
| `flask_server/app.py` | Flask Server |
