# 餐智库后端服务

餐饮行业知识库后端，提供采集管道、结构化引擎和 RAG 问答 API。

## 目录结构

```
backend/
├── app.py              # Flask API 服务（端口 8788）
├── crawler.py          # 采集管道：公众号文章抓取 + 视频号 ASR
├── video_downloader.py # 视频号批量下载管理器（调用 wx_channels_download API）
├── structurer.py       # 结构化引擎：LLM 打标签/摘要/要点/品牌识别
├── daily_pipeline.py   # 每日增量流水线：备份/采集/分析/向量/行业信号
├── rag.py              # RAG 问答：向量检索 + LLM 生成
├── schema.sql          # SQLite 数据库 schema
├── requirements.txt    # Python 依赖
├── .env.example        # 环境变量模板
├── video_config.json   # 视频源配置（账号、finder、下载目录）
├── video_sources.json  # 旧格式视频源（兼容）
├── run.sh              # 一键启动脚本
└── data/               # SQLite 数据库目录（自动创建）
```

## 快速开始

### 1. 安装依赖

```bash
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
playwright install chromium
```

### 2. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env，填入你的 DASHSCOPE_API_KEY
```

### 3. 启动服务

```bash
# 方式一：一键启动前后端
./run.sh

# 方式二：仅启动后端
python app.py
```

### 4. 数据采集与分析流程

```bash
# 步骤1：采集公众号文章
python crawler.py --source-type 公众号

# 步骤2：视频号批量下载（需要先启动 wx_channels_download 工具）
#   2a. 启动下载工具（另开终端）
#       sudo networksetup -setv6off Wi-Fi          # 禁用 IPv6（关键！）
#       sudo <工具路径>/wx_video_download           # 以管理员启动
#       # 然后重启微信，打开视频号
#
#   2b. 自动检测新视频并下载
python video_downloader.py
#       # 下载完成后自动触发 ASR 转写入库
#
#   2c. 仅下载不转写
python video_downloader.py --no-transcribe
#
#   2d. 仅检查工具是否运行
python video_downloader.py --check

# 步骤3：采集视频号内容（本地视频 → FFmpeg 提取音频 → FunASR 转写）
# 如果已通过 video_downloader.py 自动转写，可跳过此步
# 需要先配置 video_config.json 指定视频文件所在目录
# 需要本地安装 FFmpeg 和 FunASR
python crawler.py --source-type 视频号

# 步骤4：批量结构化分析
python structurer.py analyze

# 步骤5：提取跨文章行业信号
python structurer.py signals --days 30

# 步骤6：生成向量嵌入（用于 RAG 检索）
python structurer.py embed
```

### 5. 每日自动流水线

```bash
python3 daily_pipeline.py status
python3 daily_pipeline.py daily
python3 daily_pipeline.py full --skip-crawl
```

`daily` 仅处理新增或变化内容；`full` 强制重新分析和重建向量。任务包含数据库备份、运行锁、步骤日志和最近14份备份保留。运行前必须在 `.env` 配置 `DASHSCOPE_API_KEY`。

macOS 定时任务模板为 `com.cibank.daily-pipeline.plist`，默认每天 02:00 运行。安装后可用以下命令检查：

```bash
launchctl print gui/$(id -u)/com.cibank.daily-pipeline
```

### 6. 视频号下载工具配置

视频号内容获取使用 [wx_channels_download](https://github.com/ltaoo/wx_channels_download) 工具，
详细配置指南参考 [微信视频号批量下载工具配置指南.md](../../VIBank/微信视频号批量下载工具配置指南.md)。

**关键步骤**：
1. 下载工具预编译版本（macOS arm64）
2. `xattr -d com.apple.quarantine wx_video_download` 去除隔离标记
3. 禁用 IPv6：`sudo networksetup -setv6off Wi-Fi`（macOS 必做！）
4. 关闭 VPN / 代理软件
5. `sudo wx_video_download` 以管理员启动
6. 重启微信，打开视频号
7. 配置 `video_config.json` 指定视频号账号和下载目录
8. 运行 `python video_downloader.py` 自动检测并下载新视频

**使用完毕后恢复**：
```bash
sudo networksetup -setv6automatic Wi-Fi   # 恢复 IPv6
```

## API 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/health` | 健康检查 |
| GET | `/api/stats` | 概览统计 |
| GET | `/api/dashboard` | 仪表盘数据 |
| GET | `/api/intel` | 情报流列表（支持 type/category/q 筛选） |
| GET | `/api/intel/<id>` | 情报详情 |
| GET | `/api/brands` | 品牌库列表 |
| GET | `/api/brands/<id>` | 品牌详情 |
| GET | `/api/analysis` | 赛道分析数据 |
| GET | `/api/reports` | 报告列表 |
| POST | `/api/qa/ask` | RAG 问答 |
| POST | `/api/crawl/run` | 触发采集 |
| POST | `/api/analyze/run` | 触发结构化分析 |
| GET | `/api/crawl/runs` | 采集运行记录 |
| GET | `/api/sources?type=` | 信源列表（支持按类型筛选） |
| POST | `/api/sources` | 添加信源 |
| PUT | `/api/sources/<id>` | 编辑信源 |
| DELETE | `/api/sources/<id>` | 删除信源 |
| POST | `/api/sources/<id>/toggle` | 启用/停用信源 |

## 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `DASHSCOPE_API_KEY` | 阿里云通义千问 API Key | 必填 |
| `QWEN_MODEL` | 使用的千问模型 | `qwen-plus` |
| `EMBEDDING_MODEL` | 文本向量模型 | `text-embedding-v3` |
| `PORT` | Flask 服务端口 | `8765` |
| `CRAWL_ARTICLE_PAUSE` | 文章采集间隔（秒） | `2.0` |
| `CRAWL_LIST_PAUSE` | 列表页滚动间隔（秒） | `1.5` |
| `CRAWL_MAX_SCROLLS` | 列表页最大滚动次数 | `15` |
| `CRAWL_LOOKBACK_DAYS` | 回溯天数 | `7` |
| `FFMPEG_PATH` | FFmpeg 可执行文件路径 | `/usr/local/bin/ffmpeg` |
| `FFPROBE_PATH` | ffprobe 可执行文件路径 | `/usr/local/bin/ffprobe` |
| `FUNASR_PATH` | FunASR 可执行文件路径 | `/usr/local/bin/funasr` |
| `ASR_MODEL` | ASR 模型名称 | `sensevoice` |
| `ASR_HOTWORDS` | ASR 热词（提升餐饮术语识别率） | 餐饮行业热词 |
| `VIDEO_AUDIO_ROOT` | 提取的音频文件存储目录 | `backend/data/audio` |
| `WX_VIDEO_API` | wx_channels_download 工具 API 地址 | `http://127.0.0.1:2022` |

## 前端集成

前端通过 Vite 代理将 `/api` 请求转发到后端 `http://127.0.0.1:8788`。后端不可用时，前端显示加载失败或空状态。