calendar-widget/README.md

Calendar Widget

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

快速开始

# 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>

返回格式:

[
  {
    "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. 克隆项目:

git clone <repository-url>
cd calendar-widget

2. 配置环境变量:

cp .env.example .env
# 编辑 .env 文件，设置 API_KEY

3. 使用 Docker Compose 启动:

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 应用
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 (可选)

开发环境

依赖安装

pip install flask peewee google-api-python-client google-auth google-auth-httplib2 google-auth-oauthlib

本地运行

# 设置环境变量
export API_KEY=your-api-key
export PORT=5000

# 运行应用
python app.py

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

License

MIT