# 微信公众号抓取指南

## 当前项目中的两条公众号数据链路

项目里当前同时存在两种公众号处理方式：

1. 官方接口抓取链路
2. 微信公众平台后台登录态探测链路

它们用途不同，不要混用理解。

## 1. 官方接口抓取链路

### 对应文件

- `crawler/wechat_crawler.py`：高德地图公众号
- `crawler/baidu_map_crawler.py`：百度地图公众号
- `crawler/wechat_mp_crawler_base.py`：通用基类

### 这条链路的特点

- 被 `main.py` 正式集成
- 依赖 `AppID/AppSecret`
- 通过微信官方素材接口和草稿接口获取内容
- 可直接进入统一向量库流程

### 环境变量

```env
WECHAT_APPID=...
WECHAT_APPSECRET=...
BAIDU_MAP_APPID=...
BAIDU_MAP_APPSECRET=...
```

### 当前抓取逻辑

1. 先取 `access_token`
2. 读取永久图文素材数量
3. 如果永久素材为空，回退读取草稿箱
4. 解析图文内容
5. 根据关键词过滤
6. 保存为 JSON
7. 如果通过 `crawl_and_save(..., save_to_rag=True)` 调用，则写入向量库

### 直接运行示例

```bash
python crawler/wechat_crawler.py
python crawler/baidu_map_crawler.py
```

### 通过主流程运行

```bash
python main.py --mode crawl --sources wechat
python main.py --mode crawl --sources baidu
python main.py --mode full --sources wechat,baidu
```

### 数据结构

官方接口解析后的文章字段包括：

```json
{
  "title": "文章标题",
  "author": "作者",
  "digest": "摘要",
  "content": "正文纯文本",
  "content_html": "正文HTML",
  "content_source_url": "原文地址",
  "thumb_url": "封面图地址",
  "url": "微信文章URL",
  "date": "2026-04-29",
  "update_time": "2026-04-29 10:00:00",
  "timestamp": 1777428000,
  "source": "高德地图公众号",
  "crawl_time": "2026-04-29 10:05:00"
}
```

## 2. 后台登录态探测链路

### 对应文件

- `crawler/wechat_mp_backend_client.py`

### 这条链路的用途

- 用公众号后台登录 Cookie 做验证和排查
- 可搜索公众号账号、列文章、尝试抓正文
- 适合测试“高德地图官方号 / 百度地图官方号”是否能拿到有效文章
- 默认不被 `main.py` 调用

### 需要的条件

- 有效的 `WECHAT_MP_COOKIE`
- 可用的微信公众号后台登录态
- 抓正文时需要本机 Edge + Selenium

### 示例

```bash
python -m crawler.wechat_mp_backend_client --biz-query AMap --count 5 --fetch-content
```

## IP 白名单说明

如果走的是“官方接口抓取链路”，可能遇到微信 IP 白名单限制；见：

- [WECHAT_IP_WHITELIST_GUIDE.md](WECHAT_IP_WHITELIST_GUIDE.md)

如果走的是“后台登录态探测链路”，它依赖的是 Cookie 和后台权限，不走 `AppID/AppSecret` 白名单流程。

## 当前项目中的实际边界

- `main.py` 当前只接入官方接口抓取链路
- 后台登录态探测工具主要用于验证真实公众号文章能否访问
- “探测成功”不等于“主流程已改为走后台链路”

## 常见问题

### 配置了公众号数据源但被跳过

检查：

- `WECHAT_APPID` / `WECHAT_APPSECRET`
- `BAIDU_MAP_APPID` / `BAIDU_MAP_APPSECRET`

### access_token 获取失败

优先检查：

1. AppID 和 AppSecret 是否正确
2. IP 是否在白名单
3. 公众号是否具备接口权限

### 探测工具能拿到文章，但主流程抓不到

这是正常现象，说明：

- 后台登录态探测链路可用
- 但 `main.py` 仍在走官方接口链路

## 已删除的旧说明

以下说法不再准确：

- 当前项目只有一种公众号抓取方式
- 所有“高德 / 百度”测试结果都来自官方接口
- 后台登录态探测工具已经接入 `main.py`