# Calendar Widget

一个基于 Flask 的任务管理系统，集成 Google Calendar 日程安排功能，并配套 iOS Scriptable 小组件展示。

## 功能特性

- 📋 **任务管理**: 基于最小执行间隔的任务追踪系统
- 📅 **Google Calendar 集成**: 自动将任务同步到 Google 日历
- 🚦 **智能状态显示**: 根据任务执行时间自动显示红黄绿三色状态
- 📱 **iOS Widget 支持**: 通过 Scriptable 在 iOS 桌面显示任务状态
- 🔄 **自动刷新**: Widget 每分钟自动更新状态
- 💾 **离线缓存**: API 不可用时自动使用本地缓存

## 系统架构

### 后端 API (Flask)
- **app.py**: 主应用程序，提供 RESTful API
- **数据库**: SQLite 存储任务信息
- **认证**: 基于 API Key 的请求认证
- **时区**: 使用亚洲/上海时区 (北京时间)

### 前端 Widget (Scriptable)
- **widget.js**: iOS Scriptable 小组件脚本
- **布局支持**: 小型、中型、大型三种尺寸
- **交互**: 点击任务即可快速记录执行

### 部署架构
- **容器化**: Docker 镜像部署
- **CI/CD**: Drone CI 自动构建和部署
- **服务编排**: Docker Compose 管理服务

## API 接口

### 获取任务列表
```
GET /tasks
Headers: X-API-Key: <your-api-key>
```

返回格式:
```json
[
  {
    "id": 1,
    "name": "任务名称",
    "color": "green|yellow|red"
  }
]
```

### 创建日程
```
POST /tasks/<task_id>/schedule
Headers: X-API-Key: <your-api-key>
```

## 部署指南

### 环境变量配置

| 变量名                    | 说明                    | 默认值           |
| ------------------------- | ----------------------- | ---------------- |
| `API_KEY`                 | API 认证密钥            | change-me        |
| `TASK_DB`                 | 数据库文件路径          | tasks.db         |
| `GOOGLE_CREDENTIALS_FILE` | Google 服务账号凭证文件 | credentials.json |
| `CALENDAR_ID`             | Google Calendar ID      | primary          |
| `PORT`                    | 服务端口                | 5000             |

### Docker 部署

1. 使用 Docker Compose:
```bash
docker-compose up -d
```

2. 配置要求:
   - 挂载 SQLite 数据库文件: `./tasks.db:/app/tasks.db`
   - 挂载 Google 凭证文件: `<path-to-credentials>:/app/credentials.json`

### Google Calendar 配置

1. 创建 Google Cloud 项目
2. 启用 Google Calendar API
3. 创建服务账号并下载 JSON 凭证
4. 将凭证文件放置在项目目录，命名为 `credentials.json`
5. 将服务账号邮箱添加到目标日历的共享用户

### iOS Widget 配置

1. 在 iPhone 上安装 [Scriptable](https://scriptable.app/) 应用
2. 将 `widget.js` 内容复制到 Scriptable
3. 修改脚本中的配置:
   - `API_KEY`: 与后端一致的 API 密钥
   - `API_HOST`: 后端 API 地址
4. 添加 Scriptable Widget 到桌面
5. 选择对应的脚本

## 任务状态规则

任务颜色根据最后执行时间计算:
- 🟢 **绿色**: 执行时间 ≤ 最小间隔的 2/3
- 🟡 **黄色**: 执行时间 > 最小间隔的 2/3 且 ≤ 最小间隔
- 🔴 **红色**: 执行时间 > 最小间隔

## 技术栈

- **后端**: Python 3.9+, Flask, Peewee ORM
- **数据库**: SQLite
- **容器**: Docker
- **CI/CD**: Drone CI
- **前端**: JavaScript (Scriptable iOS)
- **集成**: Google Calendar API

## 开发环境

### 依赖安装
```bash
pip install flask peewee google-api-python-client google-auth google-auth-httplib2 google-auth-oauthlib
```

### 本地运行
```bash
python app.py
```

## License

MIT