University-Playwright-Codegen-Agent/SYSTEM_DESIGN.md

大学爬虫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/阿里云/腾讯云

三、数据库设计

-- 大学表
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 支持更好