feat(readme): 更新 README 文档，新增定时任务与邮件推送功能说明

- 添加定时任务自动采集、邮件推送 HTML 报告等功能介绍 - 补充快速开始配置指引和 Web 配置界面使用说明 - 新增定时任务和邮件配置的 API 接口文档 - 完善部署指南，支持 PM2 和 systemd 方式 - 增加常见问题解答，涵盖定时任务与邮件相关问题 - 更新项目结构与技术栈说明，体现无数据库架构特点
2025-12-15 15:27:53 +08:00
parent b4afc1ce5a
commit 00658a3445
1 changed files with 315 additions and 16 deletions
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # 南京公共工程建设中心 - 公告采集工具

-一个用于采集南京公共工程建设中心公告信息的 Web 可视化工具。
+一个用于采集南京公共工程建设中心公告信息的 Web 可视化工具，支持定时任务和邮件推送。

 ## 功能特性

@@ -12,13 +12,36 @@
 - ✅ Web 可视化界面
 - ✅ 导出 Word/Markdown 报告
 - ✅ RESTful API 支持
+- ✅ **定时任务自动采集**
+- ✅ **邮件推送 HTML 报告**
+- ✅ **Web 配置界面**
+- ✅ **无需数据库，轻量部署**

-## 安装
+## 快速开始
+
+### 1. 安装依赖

 ```bash
 npm install
 ```

+### 2. 配置文件
+
+首次使用需要创建配置文件：
+
+```bash
+# 复制示例配置文件
+cp config.example.json config.json
+
+# 编辑配置文件（或通过 Web 界面配置）
+# 填写邮件服务器信息和定时任务设置
+```
+
+**配置文件说明：**
+
+- `config.example.json` - 配置模板（不含敏感信息，可提交到 Git）
+- `config.json` - 实际配置（包含密码等敏感信息，已在 .gitignore 中忽略）
+
 ## 使用方法

 ### 1. 启动服务器
@@ -53,6 +76,23 @@ npm start
 - 实时统计项目信息
 - 一键导出 Word/Markdown 报告

+**定时任务标签** ⭐ 新增
+
+- Web 界面配置定时任务
+- 支持 Cron 表达式自定义执行时间
+- 可选时间范围（今日/本周/本月）
+- 设置金额阈值自动筛选
+- 实时查看任务运行状态
+- 立即测试运行功能
+
+**邮件配置标签** ⭐ 新增
+
+- Web 界面配置 SMTP 邮件服务
+- 支持主流邮箱（QQ、163、Gmail 等）
+- 测试连接功能验证配置
+- 支持多个收件人
+- 自动发送精美 HTML 报告
+
 ## 报告示例

 ```markdown
@@ -143,35 +183,233 @@ Content-Type: application/json
 }
 ```

+### 6. 获取配置
+
+```
+GET /api/config
+```
+
+返回当前配置信息（密码会被隐藏）
+
+### 7. 更新配置
+
+```
+POST /api/config
+Content-Type: application/json
+
+{
+  "scheduler": {
+    "enabled": true,
+    "cronTime": "0 9 * * *",
+    "threshold": 100000,
+    "timeRange": "today"
+  },
+  "email": {
+    "smtpHost": "smtp.qq.com",
+    "smtpPort": 587,
+    "smtpUser": "your-email@qq.com",
+    "smtpPass": "your-password",
+    "recipients": "recipient@example.com"
+  }
+}
+```
+
+### 8. 获取定时任务状态
+
+```
+GET /api/scheduler/status
+```
+
+### 9. 手动触发定时任务
+
+```
+POST /api/run-scheduled-task
+```
+
+## 定时任务配置
+
+### 通过 Web 界面配置（推荐）
+
+1. 访问 `http://localhost:3000`
+2. 切换到 **"定时任务"** 标签
+3. 配置以下选项：
+   - **启用定时任务**：勾选启用
+   - **执行时间**：选择预设时间或自定义 Cron 表达式
+   - **时间范围**：今日/本周/本月
+   - **金额阈值**：设置最低金额（单位：万元）
+4. 切换到 **"邮件配置"** 标签
+5. 配置 SMTP 邮件服务器信息
+6. 点击"测试连接"验证配置
+7. 点击"保存配置"，定时任务自动生效
+
+### 通过配置文件
+
+编辑 `config.json`：
+
+```json
+{
+  "scheduler": {
+    "enabled": true,              // 是否启用
+    "cronTime": "0 9 * * *",      // Cron表达式：每天9点
+    "threshold": 100000,           // 金额阈值（万元，10亿）
+    "description": "每天9点采集大于10亿的项目",
+    "timeRange": "today"           // 采集范围: today/thisWeek/thisMonth
+  },
+  "email": {
+    "smtpHost": "smtp.qq.com",    // SMTP服务器
+    "smtpPort": 587,               // 端口
+    "smtpUser": "your@qq.com",     // 发件邮箱
+    "smtpPass": "授权码",           // QQ邮箱授权码
+    "recipients": "to@qq.com"      // 收件人（多个用逗号分隔）
+  }
+}
+```
+
+### Cron 表达式说明
+
+格式：`分 时 日 月 周`
+
+常用示例：
+- `0 9 * * *` - 每天 9:00
+- `0 9,18 * * *` - 每天 9:00 和 18:00
+- `0 9 * * 1` - 每周一 9:00
+- `0 9 1 * *` - 每月1号 9:00
+- `0 */6 * * *` - 每 6 小时
+
+### 邮件服务配置参考
+
+**QQ 邮箱：**
+- SMTP: `smtp.qq.com`
+- 端口: `587`
+- 密码: 使用授权码（在 QQ 邮箱设置中生成）
+
+**163 邮箱：**
+- SMTP: `smtp.163.com`
+- 端口: `465`
+- 密码: 使用授权码
+
+**Gmail：**
+- SMTP: `smtp.gmail.com`
+- 端口: `587`
+- 需要开启"不够安全的应用访问"
+
+## 服务器部署
+
+### 方法 1：使用 PM2（推荐）
+
+```bash
+# 安装 PM2
+npm install -g pm2
+
+# 启动服务
+pm2 start src/server.js --name gjzx-scraper
+
+# 查看状态
+pm2 status
+
+# 查看日志
+pm2 logs gjzx-scraper
+
+# 设置开机自启
+pm2 startup
+pm2 save
+```
+
+### 方法 2：使用 systemd
+
+创建服务文件 `/etc/systemd/system/gjzx-scraper.service`：
+
+```ini
+[Unit]
+Description=GJZX Scraper Service
+After=network.target
+
+[Service]
+Type=simple
+User=your-user
+WorkingDirectory=/path/to/tool-node
+ExecStart=/usr/bin/node src/server.js
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+启动服务：
+
+```bash
+sudo systemctl enable gjzx-scraper
+sudo systemctl start gjzx-scraper
+sudo systemctl status gjzx-scraper
+```
+
+### 注意事项
+
+- ✅ **无需数据库**：项目采用无数据库架构，轻量部署
+- ✅ **配置持久化**：所有配置保存在 `config.json` 文件中
+- ✅ **进程保活**：使用 PM2 或 systemd 确保进程持续运行
+- ⚠️ **防火墙**：确保 3000 端口可访问
+- ⚠️ **配置安全**：不要将 `config.json` 提交到公开仓库
+
 ## 技术栈

 - **后端**: Node.js + Express
 - **爬虫**: Axios + Cheerio
+- **定时任务**: node-cron
+- **邮件服务**: nodemailer
 - **前端**: 原生 HTML/CSS/JavaScript
 - **编码处理**: iconv-lite (支持 GBK/UTF-8)
 - **文档导出**: docx.js
+- **架构**: 无数据库设计

 ## 项目结构

 ```
 .
 ├── src/
-│   └── server.js         # Web服务器及API
+│   ├── server.js         # Web服务器及API
+│   ├── scheduler.js      # 定时任务调度器
+│   └── emailService.js   # 邮件发送服务
 ├── public/
 │   ├── index.html        # Web界面
 │   └── app.js           # 前端逻辑
+├── config.json          # 配置文件（不提交到Git）
+├── config.example.json  # 配置示例
 ├── package.json
 └── README.md
 ```

+## 架构特点
+
+### 无数据库设计
+
+本项目采用**无数据库架构**，具有以下特点：
+
+- ✅ **轻量部署**：无需安装和配置数据库
+- ✅ **实时数据**：每次从源站实时抓取最新数据
+- ✅ **配置简单**：只需配置 config.json 文件
+- ✅ **邮件归档**：报告通过邮件发送，邮箱即为历史记录
+- ✅ **低资源消耗**：内存占用小，适合小型服务器
+
+### 数据流程
+
+```
+定时触发 → 抓取网站数据 → 解析提取 → 筛选过滤 → 生成报告 → 发送邮件
+   ↑                                                        ↓
+   └──────────────────── 配置文件 ──────────────────────────┘
+```
+
 ## 注意事项

-1. 采集速度已限制为每条延迟 500ms-1s,避免请求过快
-2. 仅支持 gjzx.nanjing.gov.cn 域名的详情页解析
-3. 金额提取基于正则匹配,支持多种格式(预算金额、最高限价等)
-4. Web 服务器默认端口 3000,可在 server.js 中修改
-5. 按时间范围采集会在检测到所有公告早于起始日期时自动停止
-6. 编码自动识别,支持 GBK 和 UTF-8 网页
+1. **采集速度**：已限制为每条延迟 500ms-1s，避免请求过快
+2. **域名支持**：仅支持 gjzx.nanjing.gov.cn 域名的详情页解析
+3. **金额提取**：基于正则匹配，支持多种格式（预算金额、最高限价等）
+4. **端口配置**：Web 服务器默认端口 3000，可在 server.js 中修改
+5. **智能停止**：按时间范围采集会在检测到所有公告早于起始日期时自动停止
+6. **编码处理**：自动识别，支持 GBK 和 UTF-8 网页
+7. **配置安全**：config.json 包含敏感信息，已加入 .gitignore，不要提交到公开仓库
+8. **进程保活**：部署时使用 PM2 或 systemd 确保定时任务持续运行

 ## 核心功能说明

@@ -204,24 +442,85 @@ Content-Type: application/json

 ## 常见问题

-### Q: 为什么采集速度比较慢?
+### Q: 为什么采集速度比较慢？

-A: 为了避免对服务器造成过大压力,程序限制了请求频率(每条延迟 500ms-1s)。这是一个负责任的爬虫设计。
+A: 为了避免对服务器造成过大压力，程序限制了请求频率（每条延迟 500ms-1s）。这是一个负责任的爬虫设计。

-### Q: 如何采集指定日期范围的公告?
+### Q: 如何采集指定日期范围的公告？

-A: 在 Web 界面的"详情采集"和"生成报告"标签中勾选"按时间范围采集",然后输入起始和结束日期即可。
+A: 在 Web 界面的"详情采集"和"生成报告"标签中勾选"按时间范围采集"，然后输入起始和结束日期即可。

-### Q: 导出的报告在哪里?
+### Q: 导出的报告在哪里？

 A: 点击"导出 Word"或"导出 Markdown"按钮后会自动下载到浏览器的默认下载目录。

-### Q: 可以采集其他网站吗?
+### Q: 可以采集其他网站吗？

-A: 需要修改 server.js 中的 BASE_URL 和相应的解析函数,因为不同网站的 HTML 结构不同。
+A: 需要修改 server.js 中的 BASE_URL 和相应的解析函数，因为不同网站的 HTML 结构不同。
+
+### Q: 需要安装数据库吗？
+
+A: **不需要！** 本项目采用无数据库架构，只需安装 Node.js 依赖即可运行。所有配置保存在 config.json 文件中，报告通过邮件发送。
+
+### Q: 定时任务配置后不生效怎么办？
+
+A: 请检查以下几点：
+1. `config.json` 中 `scheduler.enabled` 是否为 `true`
+2. 邮件配置是否正确（SMTP 服务器、用户名、密码）
+3. Node.js 进程是否持续运行（使用 PM2 查看状态）
+4. 查看服务器日志是否有错误信息
+
+### Q: 如何修改定时任务的执行时间？
+
+A: 有两种方式：
+1. **Web 界面**（推荐）：访问网页，切换到"定时任务"标签，选择预设时间或自定义 Cron 表达式，点击保存
+2. **配置文件**：编辑 `config.json` 中的 `scheduler.cronTime` 字段
+
+### Q: 邮件发送失败怎么办？
+
+A: 常见原因：
+1. **QQ 邮箱**：需要使用授权码，不是登录密码（在 QQ 邮箱设置 → 账户 → POP3/SMTP 服务中生成）
+2. **端口问题**：QQ 邮箱使用 587，某些邮箱可能需要 465（SSL）
+3. **防火墙**：确保服务器可以访问 SMTP 端口
+4. **测试连接**：在"邮件配置"标签中使用"测试连接"功能验证配置
+
+### Q: 如何查看定时任务运行日志？
+
+A: 如果使用 PM2 部署：
+```bash
+pm2 logs gjzx-scraper
+```
+
+如果使用 systemd：
+```bash
+sudo journalctl -u gjzx-scraper -f
+```
+
+### Q: 服务器重启后定时任务还会运行吗？
+
+A: 需要设置开机自启：
+- **PM2 方式**：执行 `pm2 startup` 和 `pm2 save`
+- **systemd 方式**：执行 `sudo systemctl enable gjzx-scraper`
+
+### Q: 可以设置多个定时任务吗？
+
+A: 当前版本只支持一个定时任务。如需多个任务，可以：
+1. 使用 Cron 表达式设置多个时间点（如 `0 9,18 * * *` 表示每天 9:00 和 18:00）
+2. 部署多个实例，使用不同的配置文件和端口

 ## 更新日志

+### v1.1.0 (2025-12-15)
+
+- ✨ 新增定时任务功能（node-cron）
+- ✨ 新增邮件推送服务（nodemailer）
+- ✨ 新增 Web 配置界面（定时任务 + 邮件配置）
+- ✨ 支持多时间范围（今日/本周/本月）
+- ✨ 配置 API（读取/更新配置）
+- ✨ 定时任务状态查询
+- ✨ 手动触发任务功能
+- 📝 完善文档，新增部署指南
+
 ### v1.0.0 (2025-12-12)

 - Web 可视化界面