calendar-widget/README.md

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>

返回格式:

[
  {
    "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:

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 应用
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

开发环境

依赖安装

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

本地运行

python app.py

License

MIT