# worldcup

**Repository Path**: to-doing/worldcup

## Basic Information

- **Project Name**: worldcup
- **Description**: 世界杯
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-06
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FIFA World Cup 2026 数据管理系统

基于 FastAPI + React 的世界杯数据管理系统，支持 API 和爬虫双通道数据采集，提供球队、比赛、球员数据管理、可视化展示和预测分析功能。

## 功能特性

- **赛程管理** — 支持按小组筛选，显示比赛时间、比分、状态
- **积分榜** — 按小组分组显示球队积分排名
- **射手榜** — 球员进球排名，含头像和球队信息
- **助攻榜** — 球员助攻排名
- **淘汰赛对阵** — 完整的淘汰赛树状图，含已晋级和待定队伍
- **实时同步** — 支持从 ESPN API 自动同步比赛数据

## 技术栈

- **后端**: Python 3.10+ / FastAPI / SQLAlchemy / PostgreSQL
- **前端**: React 18 + TypeScript + Vite
- **数据源**: ESPN API (实时) + 网易163 (辅助)

## 项目结构

```
WorldCup/
├── backend/                # 后端目录
│   ├── app/               # FastAPI 应用
│   │   ├── api/           # API 路由
│   │   ├── models/        # 数据模型
│   │   └── schemas/       # Pydantic 模式
│   ├── scripts/           # 数据同步脚本
│   └── docs/              # 文档
├── frontend/              # 前端目录
│   └── src/
│       ├── pages/         # 页面组件
│       ├── components/    # 公共组件
│       └── styles/        # 样式文件
└── README.md
```

## 快速开始

### 后端

```bash
cd backend

# 安装依赖
uv sync

# 配置环境变量 (参考 .env.example)
cp .env.example .env

# 启动服务
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### 前端

```bash
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

访问 http://localhost:3000

## 数据同步

```bash
# 同步比赛比分
cd backend
python scripts/sync_all_matches.py

# 同步射手榜/助攻榜
python scripts/sync_player_stats.py

# 从网易获取球员头像
node scripts/extract_headshots.js
python scripts/update_headshots.py
```

详细说明请参考 [docs/sync_guide.md](backend/docs/sync_guide.md)

## API 文档

启动后端服务后访问:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## 页面功能

| 页面 | 路径 | 功能 |
|------|------|------|
| 赛程 | /schedule | 按日期和小组展示比赛 |
| 积分榜 | /standings | 12组积分排名 |
| 射手榜 | /scorers | 球员进球排名 |
| 助攻榜 | /assists | 球员助攻排名 |
| 淘汰赛 | /bracket | 对阵树状图 |
| 球队 | /teams | 球队列表 |

## 环境变量

```env
DATABASE_URL=postgresql://user:pass@host:port/dbname
API_FOOTBALL_KEY=your_key
FOOTBALL_DATA_KEY=your_key
```

## License

MIT License - 详见 [LICENSE](LICENSE)