cae33176af
Some checks failed
continuous-integration/drone/push Build is failing
- Added full-featured web UI with drag-and-drop task sorting - Implemented CRUD API endpoints for task management - Added task reordering endpoint with priority support - Created responsive HTML interface with inline styles - Updated Docker configuration for web service deployment - Added requirements.txt for dependency management - Enhanced README with web interface documentation - Made Google Calendar integration optional
229 lines
5.5 KiB
Markdown
229 lines
5.5 KiB
Markdown
# 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
|