# Calendar Widget

一个功能完整的任务管理系统，提供 Web 界面、RESTful API、Google Calendar 集成，以及 iOS Scriptable 小组件支持。

## 快速开始

```bash
# 1. 克隆项目
git clone <repository-url>
cd calendar-widget

# 2. 启动服务
docker-compose up -d

# 3. 访问 Web 界面
open http://localhost:5000
```

## 功能特性

- 🌐 **Web 管理界面**: 美观的任务管理页面，支持增删改查和拖拽排序
- 📋 **任务管理**: 基于最小执行间隔的任务追踪系统
- 📅 **Google Calendar 集成**: 自动将任务同步到 Google 日历
- 🚦 **智能状态显示**: 根据任务执行时间自动显示红黄绿三色状态
- 📱 **iOS Widget 支持**: 通过 Scriptable 在 iOS 桌面显示任务状态
- 🔄 **自动刷新**: Widget 每分钟自动更新状态
- 💾 **数据持久化**: SQLite 数据库存储，支持 Docker 卷挂载
- 🎯 **拖拽排序**: Web 界面支持任务拖拽重新排序

## 系统架构

### 后端服务 (Flask)
- **app.py**: 主应用程序，提供 RESTful API 和 Web 界面
- **templates/**: HTML 模板目录，包含任务管理界面
- **数据库**: SQLite 存储任务信息
- **认证**: 基于 API Key 的请求认证
- **时区**: 使用亚洲/上海时区 (北京时间)

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

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

## 访问入口

### Web 管理界面
直接访问 `http://your-server:5000/` 即可使用完整的任务管理界面，功能包括：
- 创建新任务（设置名称和最小间隔天数）
- 编辑现有任务
- 删除任务
- 拖拽排序任务
- 执行任务（添加到 Google Calendar）

## API 接口

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

返回格式:
```json
[
  {
    "id": 1,
    "name": "任务名称",
    "color": "green|yellow|red",
    "min_interval_days": 7,
    "last_execution_time": "2025-01-01T12:00:00+08:00",
    "priority": 1
  }
]
```

### 创建任务
```
POST /tasks
Headers: X-API-Key: <your-api-key>
Content-Type: application/json

{
  "name": "任务名称",
  "min_interval_days": 7,
  "priority": 0
}
```

### 更新任务
```
PUT /tasks/<task_id>
Headers: X-API-Key: <your-api-key>
Content-Type: application/json

{
  "name": "新任务名称",
  "min_interval_days": 5
}
```

### 删除任务
```
DELETE /tasks/<task_id>
Headers: X-API-Key: <your-api-key>
```

### 重新排序任务
```
POST /tasks/reorder
Headers: X-API-Key: <your-api-key>
Content-Type: application/json

{
  "task_ids": [3, 1, 2]  // 按优先级从高到低排列的任务ID
}
```

### 创建日程
```
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. 克隆项目:
```bash
git clone <repository-url>
cd calendar-widget
```

2. 配置环境变量:
```bash
cp .env.example .env
# 编辑 .env 文件，设置 API_KEY
```

3. 使用 Docker Compose 启动:
```bash
docker-compose up -d
```

4. 数据持久化:
   - 任务数据库自动保存到: `./data/tasks.db`
   - Google 凭证文件（可选）: `./credentials.json`

5. 访问服务:
   - Web 界面: `http://localhost:5000/`
   - API 端点: `http://localhost:5000/tasks`

### Google Calendar 配置（可选）

如果需要将任务同步到 Google Calendar：

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

注意：即使没有配置 Google Calendar，任务管理功能仍可正常使用

### 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.10+, Flask, Peewee ORM
- **前端**: HTML5, CSS3, JavaScript (原生)
- **数据库**: SQLite
- **容器**: Docker, Docker Compose
- **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
# 设置环境变量
export API_KEY=your-api-key
export PORT=5000

# 运行应用
python app.py
```

然后访问 `http://localhost:5000/` 使用 Web 界面

## License

MIT