# 项目结构说明

## 总体定位

这是一个以交通行业情报为目标的自动化项目，当前分成五层：

1. 数据抓取
2. 文本标准化
3. 向量入库与检索
4. 报告生成
5. 邮件分发

## 顶层目录

```text
交通新闻自动报表/
├── crawler/                     # 各数据源抓取与公众号后台探测工具
├── rag/                         # 向量库处理与检索
├── report/                      # 报告生成
├── templates/                   # Web 页面模板
├── static/                      # Web 静态资源
├── data/                        # JSON、报告、诊断文件
├── vector_db/                   # Chroma 本地持久化数据
├── main.py                      # 主入口
├── generate_report_from_db.py   # 交互式报告入口
├── auto_report_and_email.py     # 报告 + 邮件脚本入口
├── email_sender.py              # SMTP 发送模块
├── email_web_app.py             # 收件人管理与手动发送 Web 界面
├── check_ip.py                  # 微信白名单辅助脚本
└── *.md                         # 说明文档
```

## crawler/

### 正式接入主流程的抓取器

- `news_crawler.py`：赛文交通网
- `wechat_crawler.py`：高德公众号官方接口抓取
- `baidu_map_crawler.py`：百度地图公众号官方接口抓取
- `ccgp_crawler.py`：中国政府采购网关键词抓取

### 辅助与探测组件

- `wechat_mp_crawler_base.py`：公众号官方接口基类
- `wechat_mp_backend_client.py`：公众号后台登录态探测工具

## rag/

- `rag_processor.py`
  - 加载 embedding 模型
  - 文本分片
  - Chroma 入库
  - URL 级 upsert
  - 相似度检索

## report/

- `report_generator.py`
  - 调用千问模型
  - 生成综合/主题报告
  - 保存 `report_*.txt`

## data/

当前会出现的典型文件：

- `news_*.json`
- `wechat_articles_*.json`
- `baidu_map_articles_*.json`
- `ccgp_results_*.json`
- `ccgp_probe_*.json`
- `gaode_backend_probe_*.json`
- `baidu_backend_probe_*.json`
- `managed_recipients.json`
- `scheduled_send_config.json`
- `report_*.txt`

## vector_db/

当前为本地持久化 Chroma 数据目录，典型内容：

- `chroma.sqlite3`
- 分段向量索引目录

## 三个主要入口怎么选

### `main.py`

默认首选，负责：

- 抓取
- 入库
- 报告

### `generate_report_from_db.py`

适合人工交互式分析，前提是向量库中已经有数据。

### `auto_report_and_email.py`

适合由任务计划程序定时调用，实现“生成报告并发送”。

## 当前需要特别注意的边界

- 后台登录态探测工具不等于主流程已切到 Cookie 抓取
- Web 界面不负责手选历史报告，它会触发新一轮抓取和报告生成
- 政府采购网抓取当前不是单一路径，而是搜索接口 + 回退栏目扫描