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