# 热点雷达 (Hotspot Radar)

Sage 框架模块 — 指定来源的热点聚合分析平台，支持动态添加来源。

## 功能

- **多类型来源**：API / RSS / Browser (HTML抓取) / Crawler (递归爬虫)
- **调度管理**：cron 定时 + 间隔模式，retry 策略
- **抓取日志**：每次执行一条审计记录（耗时/成功数/错误/HTTP状态码）
- **热点分类**：5级状态 — emerging → rising → hot → cooling → expired
- **五维分析**：时效 / 热度 / 内容 / 传播 / 受众，每维度 0-100 分
- **预警规则**：热度阈值 / 加速度 / 情感触发，email/webhook/sms 通知

## 目录结构

```
hotspot/
├── json/                    # Sage 表定义（放入 Sage 的 json/ 目录）
│   ├── hotspot_source.json
│   ├── hotspot_schedule.json
│   ├── hotspot_fetch_log.json
│   ├── hotspot_item.json
│   ├── hotspot_analysis.json
│   └── hotspot_alert.json
├── wwwroot/hotspot/          # Web UI + 后端端点（放入 Sage 的 wwwroot/hotspot/）
│   ├── index.ui              # 仪表盘（7 统计卡片 + 6 标签页）
│   ├── stats.dspy            # 统计 API
│   ├── fetch_now.dspy        # 抓取引擎（3种模式）
│   └── analyze.dspy          # 分析引擎（5维 + 状态分类）
├── ddl/mysql.sql             # 建表 SQL
├── install/                  # 安装片段
│   ├── load_path_append.txt  # 追加到 load_path.py
│   └── menu_append.json      # 追加到 menu.ui
└── README.md
```

## 安装

### 1. 复制文件到 Sage 部署目录

```bash
SAGE_ROOT=/path/to/sage
cp json/hotspot_*.json $SAGE_ROOT/json/
cp -r wwwroot/hotspot $SAGE_ROOT/wwwroot/
```

### 2. 建表

```bash
mysql -u user -p sage < ddl/mysql.sql
```

### 3. 注册权限

在 `load_path.py` 的 `"""` 结束符前追加 `install/load_path_append.txt` 的内容，然后运行：

```bash
cd $SAGE_ROOT && python load_path.py
```

### 4. 添加菜单

在 `wwwroot/menu.ui` 的 `items` 数组中追加 `install/menu_append.json` 的内容。

### 5. 重启 Sage

访问 `/hotspot` 即可看到仪表盘。

## 使用流程

1. **来源管理** 标签页 → 添加来源（选择 type: api/rss/browser/crawler）
2. **调度配置** 标签页 → 为来源配置抓取频率
3. 仪表盘点击「立即抓取全部来源」
4. **抓取日志** 标签页 → 检查执行结果
5. 点击「执行分析」→ 自动计算五维评分和状态分类
6. **热点条目** 标签页 → 按状态筛选浏览
7. **预警规则** 标签页 → 设置自动告警

## 来源类型说明

| type | 适用场景 | 配置要点 |
|------|---------|---------|
| `rss` | RSS/Atom feed | url 指向 feed 地址 |
| `api` | REST API | url + api_key + headers + fetch_method |
| `browser` | 网页热点列表 | url + browser_wait_selector |
| `crawler` | 递归抓取 | url + crawler_depth + crawler_rules |

## 依赖

- Sage >= 0.0.1
- aiohttp (Python)
- MySQL / MariaDB