# 国家课程资源抓取工具

一个遵循 `抓取流程.md` 的 Python 爬虫工具，用于从 `part_100.json` 提取 `version_id`，获取详细 JSON 信息，提取 PDF 和 m3u8 URL，并下载相关资源。

## 功能特性

- ✅ 支持本地和远程 part JSON 文件
- ✅ 自动提取版本 ID 和资源信息
- ✅ 支持 PDF 和 m3u8 视频资源下载
- ✅ 智能文件名清理和中文支持
- ✅ 层次化目录结构组织
- ✅ 详细的清单文件记录
- ✅ Token 认证支持
- ✅ 可配置的默认参数

## 安装依赖

```bash
pip install -r requirements.txt
```

## 使用方法

### 基本用法

#### 1. 解析本地 part 文件并打印版本 ID
```bash
python3 scraper.py --part-file example_part_100.json --test
```

#### 2. 从远程 URL 获取 part 文件
```bash
python3 scraper.py --part-url "https://example.com/part_100.json" --test
```

#### 3. 完整下载流程（需要 token）
```bash
python3 scraper.py --part-file example_part_100.json --out downloaded --token 'MAC id="...",nonce="...",mac="..."'
```

#### 4. 使用远程 part 文件并下载
```bash
python3 scraper.py --part-url "https://example.com/part_100.json" --out downloaded --token "your-token"
```

### 命令行参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--part-file` | 本地 part JSON 文件路径 | `example_part_100.json` |
| `--part-url` | 远程 part JSON 文件 URL | `None` |
| `--out` | 输出目录 | `downloaded` |
| `--token` | X-Nd-Auth header 值 | `None` |
| `--list-only` | 仅列出资源不下载 | `False` |
| `--limit` | 处理版本ID数量限制 | `0` (无限制) |
| `--only-pdf` | 仅下载PDF文件 | `False` |
| `--test` | 仅测试解析不下载 | `False` |
| `--flat-structure` | 使用扁平目录结构 | `False` |

### 配置说明

所有配置参数都在 `config.py` 文件中集中管理：

```python
# 文件路径配置
DEFAULT_PART_FILE = "example_part_100.json"
DEFAULT_OUTPUT_DIR = "downloaded"

# API 端点配置
DETAIL_BASE_URL = "https://s-file-2.ykt.cbern.com.cn/zxx/ndrv2/national_lesson/resources/details"

# 默认值配置
DEFAULT_MATERIAL_NAME = "未知教材"
DEFAULT_CHAPTER_NAME = "未知章节"
DEFAULT_COURSE_TITLE = "未知课程"
DEFAULT_FILENAME = "unnamed"

# 认证配置
DEFAULT_TOKEN = None  # 设置您的默认 token

# 其他配置...
```

## 输出结构

### 层次化目录结构（默认）
```
downloaded/
├── 教材名称/
│   ├── 章节名称/
│   │   ├── 课程名称_version后6位/
│   │   │   ├── 资源文件.pdf
│   │   │   ├── 资源文件.m3u8
│   │   │   └── manifest.json
│   │   └── ...
│   └── ...
└── manifest_all.json
```

### 扁平目录结构（使用 --flat-structure）
```
downloaded/
├── version_id_1/
│   ├── 资源文件.pdf
│   ├── 资源文件.m3u8
│   └── manifest.json
├── version_id_2/
│   └── ...
└── manifest_all.json
```

## 配置文件说明

### config.py
包含所有可配置参数，便于集中管理：
- 文件路径和URL配置
- 默认值和限制设置
- 网络超时和块大小
- 认证token配置

### 清单文件
每个版本目录包含 `manifest.json`，记录下载详情：
```json
{
  "version_id": "xxx",
  "resources": [
    {
      "url": "https://...",
      "filename": "文件名.pdf",
      "label": "资源标签",
      "status": "ok/error"
    }
  ]
}
```

## 高级用法

### 1. 仅列出资源不下载
```bash
python3 scraper.py --part-file example_part_100.json --list-only
```

### 2. 限制处理数量
```bash
python3 scraper.py --part-file example_part_100.json --limit 5
```

### 3. 仅下载PDF文件
```bash
python3 scraper.py --part-file example_part_100.json --only-pdf
```

### 4. 使用自定义配置
修改 `config.py` 文件中的配置项，然后正常运行程序。

## 错误处理

- 网络请求失败会自动重试并记录错误
- 文件下载失败会在manifest中标记状态
- 文件名冲突会自动添加序号解决
- 支持请求超时和重试机制

## 开发说明

### 项目结构
```
.
├── scraper.py          # 主程序
├── config.py           # 配置文件
├── requirements.txt    # 依赖文件
├── example_part_100.json      # 示例part文件
├── example_version_id.json    # 示例版本文件
├── test_hardcoded_values.py   # 测试脚本
└── OPTIMIZATION_SUMMARY.md    # 优化总结
```

### 测试验证
```bash
# 运行测试脚本验证配置
python3 test_hardcoded_values.py

# 测试基本功能
python3 scraper.py --test
```

## 注意事项

1. 确保网络连接正常，特别是访问远程资源时
2. 如需认证，请正确配置 token 参数
3. 输出目录需要有写入权限
4. 大文件下载请确保磁盘空间充足
5. 建议使用稳定的网络环境

## 技术支持

如有问题请参考：
- `抓取流程.md` - 详细的操作流程说明
- `OPTIMIZATION_SUMMARY.md` - 代码优化说明
- 配置文件中的注释说明

## 版本历史

- v1.0 - 初始版本，支持基本抓取功能
- v1.1 - 优化硬编码值，增加配置管理
- v1.2 - 增强错误处理和日志记录