Add university scraper system with backend, frontend, and configs
- Add src/university_scraper module with scraper, analyzer, and CLI - Add backend FastAPI service with API endpoints and database models - Add frontend React app with university management pages - Add configs for Harvard, Manchester, and UCL universities - Add artifacts with various scraper implementations - Add Docker compose configuration for deployment - Update .gitignore to exclude generated files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
yangxiaoyu-crypto
261
SYSTEM_DESIGN.md
Normal file
261
SYSTEM_DESIGN.md
Normal file
@ -0,0 +1,261 @@
|
||||
# 大学爬虫Web系统设计方案
|
||||
|
||||
## 一、系统架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 前端 (React/Vue) │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
|
||||
│ │ 输入大学URL │ │ 一键生成脚本 │ │ 查看/验证爬取数据 │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 后端 API (FastAPI) │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────<E29480><E29480>───────────────────┐ │
|
||||
│ │ 脚本生成API │ │ 脚本执行API │ │ 数据查询API │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────┼─────────────────┐
|
||||
▼ ▼ ▼
|
||||
┌───────────────────┐ ┌───────────────┐ ┌───────────────────────┐
|
||||
│ PostgreSQL │ │ 任务队列 │ │ Agent (Claude) │
|
||||
│ 数据库 │ │ (Celery) │ │ 分析+生成脚本 │
|
||||
│ - 爬虫脚本 │ └───────────────┘ └───────────────────────┘
|
||||
│ - 爬取结果 │
|
||||
│ - 执行日志 │
|
||||
└───────────────────┘
|
||||
```
|
||||
|
||||
## 二、技术栈选择
|
||||
|
||||
### 后端
|
||||
- **框架**: FastAPI (Python，与现有爬虫代码无缝集成)
|
||||
- **数据库**: PostgreSQL (存储脚本、结果、日志)
|
||||
- **任务队列**: Celery + Redis (异步执行爬虫任务)
|
||||
- **ORM**: SQLAlchemy
|
||||
|
||||
### 前端
|
||||
- **框架**: React + TypeScript (或 Vue.js)
|
||||
- **UI库**: Ant Design / Material-UI
|
||||
- **状态管理**: React Query (数据获取和缓存)
|
||||
|
||||
### 部署
|
||||
- **容器化**: Docker + Docker Compose
|
||||
- **云平台**: 可部署到 AWS/阿里云/腾讯云
|
||||
|
||||
## 三、数据库设计
|
||||
|
||||
```sql
|
||||
-- 大学表
|
||||
CREATE TABLE universities (
|
||||
id SERIAL PRIMARY KEY,
|
||||
name VARCHAR(255) NOT NULL,
|
||||
url VARCHAR(500) NOT NULL,
|
||||
country VARCHAR(100),
|
||||
created_at TIMESTAMP DEFAULT NOW(),
|
||||
updated_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
|
||||
-- 爬虫脚本表
|
||||
CREATE TABLE scraper_scripts (
|
||||
id SERIAL PRIMARY KEY,
|
||||
university_id INTEGER REFERENCES universities(id),
|
||||
script_name VARCHAR(255) NOT NULL,
|
||||
script_content TEXT NOT NULL, -- Python脚本代码
|
||||
config_content TEXT, -- YAML配置
|
||||
version INTEGER DEFAULT 1,
|
||||
status VARCHAR(50) DEFAULT 'draft', -- draft, active, deprecated
|
||||
created_at TIMESTAMP DEFAULT NOW(),
|
||||
updated_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
|
||||
-- 爬取任务表
|
||||
CREATE TABLE scrape_jobs (
|
||||
id SERIAL PRIMARY KEY,
|
||||
university_id INTEGER REFERENCES universities(id),
|
||||
script_id INTEGER REFERENCES scraper_scripts(id),
|
||||
status VARCHAR(50) DEFAULT 'pending', -- pending, running, completed, failed
|
||||
started_at TIMESTAMP,
|
||||
completed_at TIMESTAMP,
|
||||
error_message TEXT,
|
||||
created_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
|
||||
-- 爬取结果表 (JSON存储层级数据)
|
||||
CREATE TABLE scrape_results (
|
||||
id SERIAL PRIMARY KEY,
|
||||
job_id INTEGER REFERENCES scrape_jobs(id),
|
||||
university_id INTEGER REFERENCES universities(id),
|
||||
result_data JSONB NOT NULL, -- 学院→项目→导师 JSON数据
|
||||
schools_count INTEGER,
|
||||
programs_count INTEGER,
|
||||
faculty_count INTEGER,
|
||||
created_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
|
||||
-- 执行日志表
|
||||
CREATE TABLE scrape_logs (
|
||||
id SERIAL PRIMARY KEY,
|
||||
job_id INTEGER REFERENCES scrape_jobs(id),
|
||||
level VARCHAR(20), -- info, warning, error
|
||||
message TEXT,
|
||||
created_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
```
|
||||
|
||||
## 四、API接口设计
|
||||
|
||||
### 1. 大学管理
|
||||
```
|
||||
POST /api/universities 创建大学
|
||||
GET /api/universities 获取大学列表
|
||||
GET /api/universities/{id} 获取大学详情
|
||||
DELETE /api/universities/{id} 删除大学
|
||||
```
|
||||
|
||||
### 2. 爬虫脚本
|
||||
```
|
||||
POST /api/scripts/generate 生成爬虫脚本 (Agent自动分析)
|
||||
GET /api/scripts/{university_id} 获取大学的爬虫脚本
|
||||
PUT /api/scripts/{id} 更新脚本
|
||||
```
|
||||
|
||||
### 3. 爬取任务
|
||||
```
|
||||
POST /api/jobs/start/{university_id} 启动爬取任务
|
||||
GET /api/jobs/{id} 获取任务状态
|
||||
GET /api/jobs/university/{id} 获取大学的任务列表
|
||||
POST /api/jobs/{id}/cancel 取消任务
|
||||
```
|
||||
|
||||
### 4. 数据结果
|
||||
```
|
||||
GET /api/results/{university_id} 获取爬取结果
|
||||
GET /api/results/{university_id}/schools 获取学院列表
|
||||
GET /api/results/{university_id}/programs 获取项目列表
|
||||
GET /api/results/{university_id}/faculty 获取导师列表
|
||||
GET /api/results/{university_id}/export?format=json 导出数据
|
||||
```
|
||||
|
||||
## 五、前端页面设计
|
||||
|
||||
### 页面1: 首页/大学列表
|
||||
- 显示已添加的大学列表
|
||||
- "添加新大学" 按钮
|
||||
- 每个大学卡片显示：名称、状态、项目数、导师数、操作按钮
|
||||
|
||||
### 页面2: 添加大学 (一键生成脚本)
|
||||
- 输入框：大学官网URL
|
||||
- "分析并生成脚本" 按钮
|
||||
- 显示分析进度和日志
|
||||
- 生成完成后自动跳转到管理页面
|
||||
|
||||
### 页面3: 大学管理页面
|
||||
- 大学基本信息
|
||||
- 爬虫脚本状态
|
||||
- "一键运行爬虫" 按钮
|
||||
- 运行进度和日志实时显示
|
||||
- 历史任务列表
|
||||
|
||||
### 页面4: 数据查看页面
|
||||
- 树形结构展示：学院 → 项目 → 导师
|
||||
- 搜索和筛选功能
|
||||
- 数据导出按钮 (JSON/Excel)
|
||||
- 数据校验和编辑功能
|
||||
|
||||
## 六、实现步骤
|
||||
|
||||
### 阶段1: 后端基础 (优先)
|
||||
1. 创建 FastAPI 项目结构
|
||||
2. 设计数据库模型 (SQLAlchemy)
|
||||
3. 实现基础 CRUD API
|
||||
4. 集成现有爬虫代码
|
||||
|
||||
### 阶段2: 脚本生成与执行
|
||||
1. 实现 Agent 自动分析逻辑
|
||||
2. 实现脚本存储和版本管理
|
||||
3. 集成 Celery 异步任务队列
|
||||
4. 实现爬虫执行和日志记录
|
||||
|
||||
### 阶段3: 前端开发
|
||||
1. 搭建 React 项目
|
||||
2. 实现大学列表页面
|
||||
3. 实现脚本生成页面
|
||||
4. 实现数据查看页面
|
||||
|
||||
### 阶段4: 部署上线
|
||||
1. Docker 容器化
|
||||
2. 部署到云服务器
|
||||
3. 配置域名和 HTTPS
|
||||
|
||||
## 七、目录结构
|
||||
|
||||
```
|
||||
university-scraper-web/
|
||||
├── backend/
|
||||
│ ├── app/
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── main.py # FastAPI入口
|
||||
│ │ ├── config.py # 配置
|
||||
│ │ ├── database.py # 数据库连接
|
||||
│ │ ├── models/ # SQLAlchemy模型
|
||||
│ │ │ ├── university.py
|
||||
│ │ │ ├── script.py
|
||||
│ │ │ ├── job.py
|
||||
│ │ │ └── result.py
|
||||
│ │ ├── schemas/ # Pydantic模型
|
||||
│ │ ├── api/ # API路由
|
||||
│ │ │ ├── universities.py
|
||||
│ │ │ ├── scripts.py
|
||||
│ │ │ ├── jobs.py
|
||||
│ │ │ └── results.py
|
||||
│ │ ├── services/ # 业务逻辑
|
||||
│ │ │ ├── scraper_service.py
|
||||
│ │ │ └── agent_service.py
|
||||
│ │ └── tasks/ # Celery任务
|
||||
│ │ └── scrape_task.py
|
||||
│ ├── requirements.txt
|
||||
│ └── Dockerfile
|
||||
├── frontend/
|
||||
│ ├── src/
|
||||
│ │ ├── components/
|
||||
│ │ ├── pages/
|
||||
│ │ ├── services/
|
||||
│ │ └── App.tsx
|
||||
│ ├── package.json
|
||||
│ └── Dockerfile
|
||||
├── docker-compose.yml
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## 八、关于脚本存储位置的建议
|
||||
|
||||
### 推荐方案：PostgreSQL + 文件系统混合
|
||||
|
||||
1. **PostgreSQL 存储**:
|
||||
- 脚本元数据 (名称、版本、状态)
|
||||
- 脚本代码内容 (TEXT字段)
|
||||
- 配置文件内容 (JSONB字段)
|
||||
- 爬取结果 (JSONB字段)
|
||||
|
||||
2. **优点**:
|
||||
- 事务支持，数据一致性
|
||||
- 版本管理方便
|
||||
- 查询和搜索方便
|
||||
- 备份和迁移简单
|
||||
- 与后端集成紧密
|
||||
|
||||
3. **云部署选项**:
|
||||
- AWS RDS PostgreSQL
|
||||
- 阿里云 RDS PostgreSQL
|
||||
- 腾讯云 TDSQL-C
|
||||
|
||||
### 备选方案：MongoDB
|
||||
|
||||
如果数据结构经常变化，可以考虑 MongoDB：
|
||||
- 灵活的文档结构
|
||||
- 适合存储层级化的爬取结果
|
||||
- 但 Python 生态对 PostgreSQL 支持更好
|
||||
Reference in New Issue
Block a user