zjpb.net/NEWS_FEATURE_v2.2.md

# ZJPB v2.2.0 - 新闻搜索功能

**版本**: v2.2.0
**发布日期**: 2025-01-30
**主要功能**: 集成博查Web Search API，自动获取网站相关新闻

---

## 📋 功能概述

v2.2.0版本引入了全新的新闻搜索和展示功能，通过博查AI搜索引擎API，自动为每个网站获取最新的相关新闻，并在网站详情页进行展示。

### ✨ 核心特性

1. **智能新闻搜索** 🔍
   - 基于网站名称自动搜索相关新闻
   - 支持自定义搜索时间范围（一天、一周、一月、一年）
   - 自动排除网站自身的内容，确保新闻来源多样性

2. **新闻管理系统** 📰
   - 后台新闻列表管理
   - 支持手动编辑和删除新闻
   - 新闻来源信息展示（网站名称、图标）

3. **前台新闻展示** 🎨
   - 网站详情页展示最多5条相关新闻
   - 显示新闻标题、摘要、来源、发布时间
   - 点击新闻直接跳转到原文链接

4. **定期任务支持** ⏰
   - 提供cron任务脚本，支持定期批量获取新闻
   - 可配置获取数量、时间范围等参数

---

## 🚀 快速开始

### 1. 配置博查API

在`.env`文件中添加博查API配置：

```env
# 博查 Web Search API配置
BOCHA_API_KEY=sk-your-api-key-here
BOCHA_BASE_URL=https://api.bocha.cn
```

获取API Key：访问 [博查AI开放平台](https://open.bocha.cn) 注册并获取API密钥。

### 2. 数据库迁移

运行迁移脚本，为News表添加新字段：

```bash
python migrate_news_fields.py
```

迁移会添加以下字段：
- `source_name`: 新闻来源网站名称
- `source_icon`: 新闻来源网站图标URL

### 3. 测试新闻获取

#### 方法1：使用Python测试脚本

```bash
# 测试NewsSearcher类
python utils/news_searcher.py
```

#### 方法2：使用后台API

登录后台后，使用API接口：

**单个网站获取新闻**：
```bash
curl -X POST http://localhost:5000/api/fetch-site-news \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": 1,
    "count": 10,
    "freshness": "oneMonth"
  }'
```

**批量获取新闻**：
```bash
curl -X POST http://localhost:5000/api/fetch-all-news \
  -H "Content-Type: application/json" \
  -d '{
    "count": 5,
    "freshness": "oneMonth",
    "limit": 10
  }'
```

### 4. 查看新闻

1. 访问任意网站详情页（例如：`http://localhost:5000/site/12345678`）
2. 滚动到页面下方，查看"相关新闻"部分
3. 点击新闻标题或"阅读全文"链接跳转到原文

---

## 📖 使用指南

### 后台管理

#### 新闻管理界面

1. 登录后台：`http://localhost:5000/admin`
2. 点击左侧菜单"新闻管理"
3. 可以查看、编辑、删除已获取的新闻

**新闻列表字段**：
- ID
- 关联网站
- 新闻标题
- 来源网站
- 新闻类型
- 发布时间
- 是否启用

#### 手动获取新闻

虽然提供了API接口，但目前没有直接的后台UI按钮。可以通过以下方式触发：

1. 使用API接口（参见快速开始）
2. 使用定期任务脚本（参见下文）

### 定期任务设置

使用`fetch_news_cron.py`脚本定期自动获取新闻。

#### 手动执行

```bash
# 默认参数：处理10个网站，每个网站获取5条新闻，时间范围一个月
python fetch_news_cron.py

# 自定义参数
python fetch_news_cron.py --limit 20 --count 10 --freshness oneWeek
```

**参数说明**：
- `--limit`: 处理的网站数量限制（默认：10）
- `--count`: 每个网站获取的新闻数量（默认：5）
- `--freshness`: 新闻时间范围（可选：noLimit, oneDay, oneWeek, oneMonth, oneYear）

#### 配置Crontab

在Linux服务器上配置定期任务：

```bash
# 编辑crontab
crontab -e

# 添加以下行（每天早上8点执行）
0 8 * * * cd /opt/1panel/apps/zjpb && /opt/1panel/apps/zjpb/venv/bin/python fetch_news_cron.py --limit 10 >> logs/news_fetch.log 2>&1

# 或每6小时执行一次
0 */6 * * * cd /opt/1panel/apps/zjpb && /opt/1panel/apps/zjpb/venv/bin/python fetch_news_cron.py --limit 20 >> logs/news_fetch.log 2>&1
```

**注意**：
- 确保创建`logs`目录：`mkdir -p logs`
- 修改路径为实际的项目路径
- 根据API配额合理设置执行频率

---

## 🗂️ 文件结构

### 新增文件

```
zjpb/
├── utils/
│   └── news_searcher.py          # 博查API封装类
├── migrate_news_fields.py        # 数据库迁移脚本
├── fetch_news_cron.py            # 定期任务脚本
└── NEWS_FEATURE_v2.2.md          # 本文档
```

### 修改文件

```
zjpb/
├── config.py                     # 添加博查API配置
├── models.py                     # News模型添加source_name/source_icon字段
├── app.py                        # 添加新闻获取API路由，更新NewsAdmin
└── templates/
    └── detail_new.html          # 优化新闻展示UI
```

---

## 🔧 技术实现

### API集成

使用博查Web Search API进行新闻搜索：

- **接口地址**: `https://api.bocha.cn/v1/web-search`
- **认证方式**: Bearer Token
- **请求方法**: POST
- **返回格式**: JSON

### 数据模型

News模型字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键 |
| site_id | Integer | 关联网站ID（外键） |
| title | String(200) | 新闻标题 |
| content | Text | 新闻内容/摘要 |
| news_type | String(50) | 新闻类型 |
| url | String(500) | 新闻链接 |
| source_name | String(100) | ⭐ 来源网站名称（新增） |
| source_icon | String(500) | ⭐ 来源网站图标（新增） |
| published_at | DateTime | 发布时间 |
| is_active | Boolean | 是否启用 |
| created_at | DateTime | 创建时间 |
| updated_at | DateTime | 更新时间 |

### API路由

**1. 单个网站获取新闻**

- **路径**: `/api/fetch-site-news`
- **方法**: POST
- **权限**: 需要登录
- **参数**:
  ```json
  {
    "site_id": 1,
    "count": 10,
    "freshness": "oneMonth"
  }
  ```

**2. 批量获取新闻**

- **路径**: `/api/fetch-all-news`
- **方法**: POST
- **权限**: 需要登录
- **参数**:
  ```json
  {
    "count": 5,
    "freshness": "oneMonth",
    "limit": 10
  }
  ```

---

## 📊 配置选项

在`config.py`中的新闻相关配置：

```python
# 博查 Web Search API配置
BOCHA_API_KEY = os.environ.get('BOCHA_API_KEY')
BOCHA_BASE_URL = os.environ.get('BOCHA_BASE_URL') or 'https://api.bocha.cn'
BOCHA_SEARCH_ENDPOINT = '/v1/web-search'

# 新闻搜索配置
NEWS_SEARCH_COUNT = 10              # 每次搜索返回的新闻数量
NEWS_SEARCH_FRESHNESS = 'oneMonth'  # 默认搜索一个月内的新闻
NEWS_SEARCH_SUMMARY = True          # 是否显示摘要
```

---

## ⚠️ 注意事项

### API配额限制

- 博查API根据充值金额有请求频率限制
- 建议合理设置定期任务频率，避免过度消耗配额
- 详情参见：[博查API定价](https://open.bocha.cn)

### 去重机制

系统会根据新闻URL自动去重，同一条新闻不会重复保存。

### 搜索策略

- 搜索关键词：`{网站名称} 最新 新闻`
- 自动排除：网站自身域名的内容
- 时间优先：优先显示最新发布的新闻

### 性能优化

- 批量获取时建议限制数量（`--limit 10-20`）
- 避免短时间内频繁调用API
- 数据库查询已优化，使用索引和去重

---

## 🐛 故障排查

### 1. 新闻获取失败

**可能原因**：
- 博查API Key未配置或无效
- API配额不足
- 网络连接问题

**解决方法**：
```bash
# 检查环境变量
python -c "import os; from dotenv import load_dotenv; load_dotenv(); print(os.getenv('BOCHA_API_KEY'))"

# 测试API连接
python utils/news_searcher.py
```

### 2. 数据库字段不存在

**错误信息**：`Unknown column 'source_name' in 'field list'`

**解决方法**：
```bash
# 运行数据库迁移
python migrate_news_fields.py
```

### 3. 详情页不显示新闻

**可能原因**：
- 数据库中没有该网站的新闻记录
- 新闻被设置为不启用（is_active=False）

**解决方法**：
```bash
# 为该网站获取新闻
curl -X POST http://localhost:5000/api/fetch-site-news \
  -H "Content-Type: application/json" \
  -d '{"site_id": YOUR_SITE_ID}'
```

### 4. 定期任务不执行

**检查清单**：
- [ ] Crontab配置是否正确
- [ ] Python路径是否正确
- [ ] 日志文件是否有写入权限
- [ ] 查看cron日志：`grep CRON /var/log/syslog`

---

## 📈 未来改进

### 计划功能

- [ ] 后台UI按钮直接触发新闻获取
- [ ] 新闻分类和标签支持
- [ ] 新闻摘要AI优化
- [ ] 新闻热度排序
- [ ] 用户收藏新闻功能
- [ ] 新闻RSS订阅

### 性能优化

- [ ] 使用异步任务队列（Celery）
- [ ] 新闻缓存机制
- [ ] 图片CDN加速

---

## 📞 技术支持

- **项目名称**: ZJPB - 焦提示词 | AI工具导航
- **版本**: v2.2.0
- **发布日期**: 2025-01-30
- **博查API文档**: https://bocha-ai.feishu.cn/wiki/RXEOw02rFiwzGSkd9mUcqoeAnNK

---

## 📝 更新日志

### v2.2.0 (2025-01-30)

**新增**：
- ✨ 集成博查Web Search API
- ✨ 新闻自动搜索和存储功能
- ✨ News模型添加source_name和source_icon字段
- ✨ 网站详情页新闻展示优化
- ✨ 后台新闻管理界面增强
- ✨ 定期任务脚本（fetch_news_cron.py）
- ✨ API路由：/api/fetch-site-news 和 /api/fetch-all-news

**修改**：
- 🔧 config.py添加博查API配置
- 🔧 NewsAdmin添加source_name字段显示
- 🔧 detail_new.html优化新闻展示UI

**文档**：
- 📖 NEWS_FEATURE_v2.2.md 功能文档
- 📖 migrate_news_fields.py 迁移脚本文档

---

**祝您使用愉快！** 🎉