ReminderBot/README.md

Telegram 提醒机器人

一个功能完善的 Telegram 提醒机器人，支持多用户、多种提醒类型和中国节假日规避。

功能特性

• 多种提醒类型：一次性 / 每日 / 每周 / 间隔重复
• 时间窗口控制：间隔提醒支持设置活跃时间段（如 09:00–22:00）
• 中国节假日规避：可选跳过节假日
• 交互式操作：内联按钮支持完成、延期、暂停、删除
• 多用户隔离：每位用户独立管理自己的提醒
• Docker 部署：容器化部署，数据持久化

快速开始

1. 获取 Bot Token

向 @BotFather 发送 /newbot 命令获取 Token。

2. 配置环境变量

cp .env.example .env
# 编辑 .env，填写 BOT_TOKEN

3. 启动

Docker 方式：

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 — 容器化部署