# Habit Tracker ChatGPT App

一個在 ChatGPT 裡追蹤每日習慣的 App,用 **ChatGPT Apps SDK / MCP** 建構。
使用者可以用自然語言(「新增喝水習慣」「幫我打卡」),也可以在內嵌的視覺化
介面直接操作;兩種方式共用同一套後端邏輯。資料存在本機 SQLite。

## 功能

- 新增 / 更新 / 刪除習慣,可設定每天的目標次數(`target_per_day`)
- 打卡(check-in),自動計算**連續天數(streak)**與今日進度
- 「今日待完成」檢視:列出今天還沒達標的習慣
- 內嵌 React widget:清單、打卡按鈕、新增表單,操作即時同步

## 架構概觀

```
使用者 ─┬─ 對 ChatGPT 說話 ──► 模型呼叫工具
        └─ 點 widget 按鈕 ──► 介面呼叫工具
                                 │
                                 ▼
                    MCP server (server/app.py, /mcp)
                                 │
                     repository.py ──► SQLite
                                 │
                    回傳 structured_content
                                 ▼
                ChatGPT 渲染 React widget(iframe)
```

- **MCP 工具分兩組**:給模型用的(模型自己決定何時呼叫)與只給介面用的
  `widget_*` 別名(對模型隱形,由 widget 按鈕觸發)。兩組指向同一批函式。
- **衍生狀態不落地**:streak、今日進度都在讀取時即時算出(`habits_with_status`),
  不存快取欄位,永遠是最新的。
- widget 執行期的細節(沙箱 iframe、CORS/CSP、postMessage 橋)見
  [`docs/widget-architecture.md`](docs/widget-architecture.md)。

## 檔案結構

```
habittrack/
├── server/
│   ├── config.py       # 環境變數設定
│   ├── database.py      # SQLite engine + session + 建表
│   ├── models.py        # Habit / CheckIn 資料表
│   ├── repository.py    # 資料存取 + streak / 今日進度計算
│   └── app.py           # MCP server、工具、widget resource、HTTP 路由
├── web/src/
│   ├── types.ts         # 前後端共用型別
│   ├── bridge.ts        # 封裝與 ChatGPT host 的橋接
│   ├── App.tsx          # React widget
│   └── main.tsx         # 掛載 React
├── tests/               # repository 單元測試
└── docs/
    └── widget-architecture.md
```

## 本機開發

```bash
# 1. 後端
cp .env.example .env          # 預設用 SQLite,可直接跑
uv sync
uv run pytest                 # 跑測試

# 2. 前端(改動後要重新 build)
cd web && npm install && npm run build && cd ..

# 3. 啟動(MCP 端點 /mcp,健康檢查 /health、/ready)
uv run uvicorn server.app:app --host 0.0.0.0 --port 2100 --reload
```

ChatGPT 只接受 HTTPS,所以用 ngrok 對外暴露,再到 **Developer Mode** 註冊:

```bash
ngrok http 2100
# 把 .env 的 PUBLIC_BASE_URL 設成 ngrok 的 https 網址,重啟 server
# 在 ChatGPT 註冊 https://<ngrok-host>/mcp(No authentication)
```

> `PUBLIC_BASE_URL` 同時是 widget 載入資產的網址與 CSP 白名單,務必設成對外的
> HTTPS origin(無尾斜線);改動後要重啟 server。

## 環境變數

| 變數 | 說明 | 預設 |
| --- | --- | --- |
| `DATABASE_URL` | 資料庫連線字串 | `sqlite:///habits.db` |
| `PUBLIC_BASE_URL` | widget 資產與 CSP 的對外 origin | `http://localhost:2100` |
| `ENVIRONMENT` | 環境名稱 | `development` |

## 說明

目前為單機、無驗證的私人 Developer Mode 版本。若要分享或上線,需另外加上
OAuth 與 per-user 資料隔離。