121 lines
3.6 KiB
Markdown
121 lines
3.6 KiB
Markdown
# Telegram 提醒机器人
|
||
|
||
一个功能完善的 Telegram 提醒机器人，支持多用户、多种提醒类型和中国节假日规避。
|
||
|
||
## 功能特性
|
||
|
||
- **多种提醒类型**：一次性 / 每日 / 每周 / 间隔重复
|
||
- **时间窗口控制**：间隔提醒支持设置活跃时间段（如 09:00–22:00）
|
||
- **中国节假日规避**：可选跳过节假日
|
||
- **交互式操作**：内联按钮支持完成、延期、暂停、删除
|
||
- **多用户隔离**：每位用户独立管理自己的提醒
|
||
- **Docker 部署**：容器化部署，数据持久化
|
||
|
||
## 快速开始
|
||
|
||
### 1. 获取 Bot Token
|
||
|
||
向 [@BotFather](https://t.me/BotFather) 发送 `/newbot` 命令获取 Token。
|
||
|
||
### 2. 配置环境变量
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# 编辑 .env，填写 BOT_TOKEN
|
||
```
|
||
|
||
### 3. 启动
|
||
|
||
**Docker 方式**：
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
|
||
## 使用说明
|
||
|
||
### 命令
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `/start` | 显示欢迎信息和主菜单 |
|
||
| `/new` | 新建提醒 |
|
||
| `/list` | 查看我的提醒 |
|
||
| `/help` | 帮助信息 |
|
||
|
||
### 创建提醒
|
||
|
||
1. 发送 `/new` 或点击 **➕ 新建提醒**
|
||
2. 选择提醒类型
|
||
3. 输入标题（必填）和描述（可选）
|
||
4. 根据类型输入时间参数
|
||
5. 选择是否跳过节假日
|
||
6. 确认创建
|
||
|
||
### 提醒类型
|
||
|
||
| 类型 | 说明 | 时间格式示例 |
|
||
|------|------|-------------|
|
||
| 一次性 | 在指定日期时间提醒一次 | `2026-06-01 09:00` |
|
||
| 每日 | 每天固定时间提醒 | `09:00` |
|
||
| 每周 | 每周指定星期几提醒（1=周一，7=周日）| `1,3,5` 然后 `09:00` |
|
||
| 间隔 | 在时间窗口内每 N 分钟提醒一次 | 间隔 `30`，窗口 `09:00-22:00` |
|
||
|
||
### 提醒操作
|
||
|
||
收到提醒消息后，可点击以下按钮：
|
||
|
||
- ✅ **完成**：标记为完成，停止后续提醒
|
||
- ⏰ **延期10分钟**：10分钟后再次提醒
|
||
- ⏸ **暂停**：暂停提醒（可在列表中恢复）
|
||
- 🗑 **删除**：永久删除提醒
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
reminderBot/
|
||
├── bot/
|
||
│ ├── main.py # 应用入口
|
||
│ ├── config.py # 配置管理
|
||
│ ├── states.py # 会话状态常量
|
||
│ ├── handlers/ # 命令处理器
|
||
│ │ ├── start.py # /start 欢迎
|
||
│ │ ├── reminder.py # 创建提醒向导
|
||
│ │ ├── list.py # 提醒列表
|
||
│ │ └── callback.py # 内联按钮回调
|
||
│ ├── models/ # 数据模型
|
||
│ │ ├── database.py # 数据库连接
|
||
│ │ ├── user.py # 用户模型
|
||
│ │ └── reminder.py # 提醒模型
|
||
│ ├── scheduler/ # 调度器
|
||
│ │ ├── job_manager.py # 任务管理
|
||
│ │ └── executor.py # 执行器
|
||
│ └── utils/ # 工具函数
|
||
│ ├── holiday.py # 节假日判断
|
||
│ └── keyboards.py # 键盘布局
|
||
├── data/ # SQLite 数据库（持久化卷）
|
||
├── logs/ # 日志（持久化卷）
|
||
├── .env.example
|
||
├── requirements.txt
|
||
├── Dockerfile
|
||
└── docker-compose.yml
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| `BOT_TOKEN` | Telegram Bot Token | 必填 |
|
||
| `DATABASE_URL` | SQLite 数据库路径 | `sqlite:////app/data/reminders.db` |
|
||
| `LOG_LEVEL` | 日志级别 | `INFO` |
|
||
| `DEFAULT_TIMEZONE` | 默认时区 | `Asia/Shanghai` |
|
||
|
||
## 技术栈
|
||
|
||
- **Python 3.11**
|
||
- **python-telegram-bot 20.7** — Bot 框架
|
||
- **APScheduler 3.10** — 任务调度
|
||
- **SQLAlchemy 2.0** — ORM
|
||
- **chinese-calendar** — 中国节假日判断
|
||
- **Docker** — 容器化部署
|