From 3f6559b179f0d1fdd0713975aa7fc44cb200ca86 Mon Sep 17 00:00:00 2001
From: Ching L <loooching@gmail.com>
Date: Thu, 11 Sep 2025 15:41:32 +0800
Subject: [PATCH] docs(readme): update README with project details

---
 README.md | 128 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 127 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 6715dc3..f7e5f50 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,128 @@
-# calendar-widget
+# 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