# 大学爬虫Web系统设计方案

## 一、系统架构

```
┌─────────────────────────────────────────────────────────────────┐
│                         前端 (React/Vue)                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │  输入大学URL │  │ 一键生成脚本 │  │    查看/验证爬取数据     │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      后端 API (FastAPI)                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────��───────────────────┐  │
│  │ 脚本生成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 支持更好