# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

这是一个短视频解析平台，聚合多家短视频解析接口（抖音、TikTok、哔哩哔哩），提供用户系统、限流控制、队列管理和管理后台。

技术栈：Python + Flask + MySQL + Redis

## 常用命令

### 开发环境设置

```bash
# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 然后编辑 .env 文件配置数据库和Redis连接

# 创建数据库
mysql -u root -p
CREATE DATABASE video_parser CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 导入数据库表结构
mysql -u root -p video_parser < database/schema.sql

# 初始化管理员账号（用户名: shihao, 密码: 80012029Lz）
python init_admin.py

# 初始化解析接口数据
python init_data.py
```

### 运行应用

```bash
# 开发模式
python app.py

# 生产模式（使用Gunicorn）
gunicorn -w 4 -b 0.0.0.0:5000 app:app
```

### 测试和调试

```bash
# 测试数据库连接
python test_db.py

# 检查环境配置
python check_env.py

# 测试邮件发送功能
python test_email.py

# 单独运行定时任务（健康检查）
python scheduler.py
```

### Redis 服务

```bash
# Windows下启动Redis（项目包含Redis-x64-5.0.14.1）
cd Redis-x64-5.0.14.1
redis-server.exe redis.windows.conf
```

## 核心架构

### 解析器工厂模式（parsers/factory.py）

- `ParserFactory.create_parser(api_config)` - 根据API配置创建对应平台的解析器实例
- `ParserFactory.get_parser_for_platform(platform)` - 获取指定平台的解析器，支持负载均衡（哔哩哔哩使用加权随机选择）
- `ParserFactory.detect_platform(video_url)` - 自动检测视频链接所属平台

所有解析器继承自 `BaseParser`（parsers/base.py），必须实现 `parse(video_url)` 方法，返回统一格式：
```python
{
    "cover": "封面URL",
    "video_url": "视频URL",
    "title": "标题",
    "description": "简介"
}
```

**添加新平台解析器**：
1. 在 `parsers/` 目录创建新的解析器文件（如 `kuaishou.py`）
2. 继承 `BaseParser` 并实现 `parse()` 方法
3. 在 `parsers/factory.py` 的 `create_parser()` 中添加平台映射
4. 在数据库 `parser_apis` 表中添加新接口配置
5. 在 `ParserFactory.detect_platform()` 中添加 URL 检测规则

### 队列与并发控制（utils/queue.py）

- `ParseQueue` - 解析任务队列管理器，支持Redis和内存队列双模式
  - `add_task()` - 添加任务到队列
  - `get_task()` - 从队列获取任务
  - `complete_task()` - 完成任务并存储结果
  - `get_result()` - 获取任务结果
  - **降级机制**：Redis 连接失败时自动降级到内存队列（重启后数据丢失）

- `ConcurrencyController` - 并发控制器
  - `can_process()` - 检查是否可以处理新任务（基于 `max_concurrent` 配置）
  - `wait_for_slot()` - 等待可用槽位

### 健康检查与定时任务（scheduler.py）

使用 APScheduler 定时检查各平台解析接口的健康状态：
- 根据 `health_check_config` 表配置的间隔执行检查
- 检查结果记录到 `health_check_logs` 表
- 更新 `parser_apis` 表的 `health_status` 和 `fail_count`

### 路由结构

- `routes/main.py` - 主页路由
- `routes/auth.py` - 用户认证（注册、登录、验证码、重置密码）
- `routes/parser.py` - 解析API（`/api/parse`, `/api/task/<task_id>`, `/api/queue-status`）
- `routes/admin.py` - 管理后台（用户管理、接口管理、配置管理、统计数据）

### 数据模型（models/__init__.py）

核心模型：
- `User` / `UserGroup` - 用户和分组（支持不同限流策略）
- `Admin` - 管理员（支持2FA）
- `ParserAPI` - 解析接口配置（支持权重、健康状态、统计数据）
- `SMTPConfig` - SMTP配置（支持多配置负载均衡）
- `ParseLog` / `DailyParseStat` - 解析日志和统计
- `HealthCheckConfig` / `HealthCheckLog` - 健康检查配置和日志

### 限流机制（utils/limiter.py）

`RateLimiter` 类实现基于用户分组的每日限流：
- `check_limit(user_id, ip_address)` - 检查是否超过限制，返回 `{allowed, current, limit, remaining}`
- `increment_count(user_id, ip_address, success)` - 增加解析计数

默认限流配置：
- 游客：可通过 `site_configs` 表的 `guest_daily_limit` 配置（默认5次/天）
- 普通用户（group_id=2）：10次/天
- VIP用户（group_id=3）：50次/天
- SVIP用户（group_id=4）：200次/天

限流数据存储在 `daily_parse_stats` 表，按 user_id 或 ip_address 统计。

### 管理员认证（utils/admin_auth.py）

- `@admin_required` - 装饰器，保护管理后台路由（API返回401 JSON，页面重定向到登录）
- `verify_2fa(admin, code)` - 验证TOTP 2FA代码
- `generate_2fa_secret()` / `get_2fa_qrcode_url()` - 2FA设置辅助函数

## 应用初始化流程（app.py）

1. 创建Flask应用并加载配置（config.py）
2. 初始化数据库（Flask-SQLAlchemy）
3. 初始化登录管理器（Flask-Login）
4. 初始化Redis连接（支持降级到内存队列）
5. 注册蓝图（auth, parser, admin, main）
6. 启动定时任务调度器（非调试模式或主进程）

## 环境变量配置（.env）

必需配置：
- `SECRET_KEY` - Flask密钥
- `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME` - MySQL配置
- `REDIS_HOST`, `REDIS_PORT`, `REDIS_DB`, `REDIS_PASSWORD` - Redis配置（可选，失败时降级到内存队列）
- `MAX_CONCURRENT` - 最大并发解析数（默认3）
- `SESSION_LIFETIME` - 会话过期时间（秒，默认7200）

**注意**：
- SMTP 配置存储在数据库 `smtp_configs` 表中，通过管理后台管理
- 站点配置（Logo、标题、公告等）存储在 `site_configs` 表中
- 首次运行前必须执行 `init_admin.py` 和 `init_data.py` 初始化数据

## 解析请求流程

1. 用户提交视频URL → `routes/parser.py:parse_video()`
2. 限流检查 → `utils/limiter.py:RateLimiter.check_limit()`
3. 平台检测 → `parsers/factory.py:ParserFactory.detect_platform()`
4. 并发检查 → `utils/queue.py:ConcurrencyController.can_process()`
   - 可处理：立即执行 `_process_task()`
   - 队列满：返回 `task_id`，前端轮询 `/api/task/<task_id>`
5. 解析执行 → 遍历该平台所有启用的API，依次尝试直到成功（failover机制）
6. 结果存储 → Redis（1小时过期）或内存队列

**API Failover 机制**（`routes/parser.py:110-170`）：
- 按顺序尝试所有启用的API（不考虑健康状态）
- 任一成功即返回，失败则继续下一个
- 全部失败才返回错误

## 访问地址

- 前台首页：`http://localhost:5000`
- 管理后台：`http://localhost:5000/admin/login`（默认账号：shihao / 80012029Lz）
- API文档：参考 `API文档.md`

## 常见问题

### 数据库相关
- 修改数据库表结构后，需手动执行 SQL 更新语句（项目未使用迁移工具）
- 确保数据库字符集为 `utf8mb4`，避免 emoji 等特殊字符存储问题

### Redis 相关
- Windows 环境已包含 Redis 服务端（`Redis-x64-5.0.14.1/`）
- Redis 不可用时系统会自动降级到内存队列，但重启后队列数据会丢失
- 生产环境建议使用独立的 Redis 服务

### 邮件发送
- 首次部署需在管理后台配置 SMTP（或使用 `开发文档/默认SMPT.md` 中的默认配置）
- 使用 `python test_email.py` 测试邮件发送功能
- 支持多 SMTP 配置负载均衡，提高邮件发送成功率

### 解析接口
- 哔哩哔哩平台支持 3 个接口负载均衡，通过权重分配流量
- 健康检查失败会发送邮件告警给管理员
- 接口配置在 `parser_apis` 表中，可通过管理后台动态启用/禁用