# 定时推送功能使用指南

## 功能概述

TrendHub 现已支持定时推送功能和推送记录管理。系统可以在配置的时间窗口内自动执行爬取和推送任务，并将推送历史记录保存到本地数据库。

## 主要特性

### 1. 定时推送调度器
- ⏰ **时间窗口控制**：可配置推送的时间范围（如 09:00-18:00）
- 📅 **每日一次模式**：防止同一天内重复推送
- 🔄 **自动清理**：可配置保留天数，自动清理旧记录
- 💾 **本地存储**：使用 BoltDB 轻量级数据库存储推送记录

### 2. 推送记录管理
- 📊 **详细记录**：记录推送时间、状态、条目数、耗时等信息
- 🔍 **记录查询**：支持分页查看历史推送记录
- 📈 **状态监控**：区分成功、失败、部分成功等状态
- 🌐 **Web 界面**：可视化查看和管理推送记录

## 配置说明

在 `config.yaml` 中添加或修改以下配置：

```yaml
notification:
  enable_notification: true
  
  # 推送时间窗口控制
  push_window:
    enabled: true                    # 是否启用推送时间窗口控制
    time_range:
      start: "09:00"                 # 推送窗口开始时间（北京时间）
      end: "18:00"                   # 推送窗口结束时间（北京时间）
    once_per_day: true               # 每天在窗口内只推送一次
    push_record_retention_days: 30   # 推送记录保留天数（0表示永久保留）
  
  webhooks:
    # ... 你的 webhook 配置 ...
```

## 使用方法

### 启动 Web 模式（推荐）

```bash
# 使用默认配置启动
./trendhub -web

# 指定数据库路径
./trendhub -web -db data/push_records.db

# 指定端口
./trendhub -web -addr :8080
```

启动后：
1. 定时调度器会自动启动
2. 在配置的时间窗口内自动执行任务
3. 推送结果会自动记录到数据库
4. 访问 Web 界面查看推送记录

### Web 界面查看推送记录

1. 打开浏览器访问：`http://localhost:8080`
2. 点击顶部的"推送记录"标签
3. 查看历史推送记录，包括：
   - 推送时间
   - 执行状态（成功/失败/部分成功）
   - 推送的条目数量
   - 执行耗时
   - 错误信息（如果有）
4. 支持分页浏览历史记录

## 工作原理

### 调度流程

```
启动程序
    ↓
初始化推送数据库
    ↓
启动定时调度器
    ↓
每分钟检查一次时间窗口
    ↓
在窗口内 + 今日未推送？
    ↓
执行爬取和推送任务
    ↓
记录推送结果到数据库
    ↓
清理过期记录
```

### 推送记录结构

每条推送记录包含以下信息：

```json
{
  "id": "1234567890123456789",
  "timestamp": "2025-11-20T10:30:00Z",
  "status": "success",              // success, failed, partial
  "item_count": 25,                 // 推送的条目数
  "notifiers": ["feishu", "dingtalk"],
  "success_num": 2,
  "failed_num": 0,
  "error_msg": "",
  "duration": 5432                  // 执行耗时（毫秒）
}
```

## 注意事项

### 时间窗口
- 时间格式为 `HH:MM`（24小时制）
- 支持跨日配置（如 `22:00` 到 `02:00`）
- 每分钟检查一次是否在时间窗口内
- GitHub Actions 执行时间不稳定，建议在自有服务器上使用

### 数据库
- 数据库文件默认保存在 `data/push_records.db`
- 使用 BoltDB，无需额外安装
- 支持并发访问，线程安全
- 建议定期备份数据库文件

### 记录清理
- 设置 `push_record_retention_days: 0` 表示永久保留
- 清理操作在每次推送后自动执行
- 已删除的记录无法恢复

## 故障排查

### 调度器未启动
**问题**：日志显示"Push window disabled"

**解决方案**：
```yaml
notification:
  push_window:
    enabled: true  # 确保设置为 true
```

### 推送记录为空
**问题**：Web 界面显示"暂无推送记录"

**可能原因**：
1. 还未触发过推送
2. 不在时间窗口内
3. 今日已推送（如果启用了 once_per_day）
4. 数据库文件权限问题

**解决方案**：
- 检查日志确认调度器是否正常工作
- 手动执行一次任务测试
- 检查数据库文件权限

### 数据库错误
**问题**：无法打开数据库

**解决方案**：
```bash
# 确保数据目录存在
mkdir -p data

# 检查文件权限
chmod 755 data
chmod 644 data/push_records.db  # 如果文件已存在
```

## API 接口

### 获取推送记录

```http
GET /api/push-records?limit=20&offset=0
```

**参数**：
- `limit`: 每页记录数（默认 20）
- `offset`: 偏移量（用于分页）

**响应**：
```json
{
  "records": [
    {
      "id": "...",
      "timestamp": "2025-11-20T10:30:00Z",
      "status": "success",
      "item_count": 25,
      "duration": 5432,
      ...
    }
  ],
  "total": 100
}
```

## 最佳实践

1. **生产环境部署**
   - 使用 Docker 或 systemd 守护进程运行
   - 配置合适的时间窗口避免高峰时段
   - 定期备份数据库文件

2. **测试配置**
   - 先手动运行几次测试推送是否正常
   - 设置较短的时间窗口用于测试
   - 观察日志确认调度器正常工作

3. **监控告警**
   - 定期检查推送记录
   - 关注失败记录并及时处理
   - 设置记录保留天数避免磁盘占满

4. **性能优化**
   - 根据实际需求调整 `request_interval`
   - 合理设置记录保留天数
   - 避免在同一时间窗口内频繁推送

## 版本信息

- 功能版本：v2.0.0
- 添加时间：2025-11-20
- 依赖：go.etcd.io/bbolt v1.4.3+