# KPPACHONG-SPORT

**Repository Path**: zccgit06/KPPACHONG-SPORT

## Basic Information

- **Project Name**: KPPACHONG-SPORT
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-30
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KPPACHONG-SPORT - NBA 数据爬虫系统

> 一个专业的 NBA 数据采集系统，通过 API 爬取球队、球员、赛程、新闻等多维数据并存入 MySQL 数据库，提供可视化 GUI 管理界面。

## 目录

- [项目简介](#项目简介)
- [功能特性](#功能特性)
- [技术栈](#技术栈)
- [目录结构](#目录结构)
- [数据库设计](#数据库设计)
- [安装与运行](#安装与运行)
- [配置说明](#配置说明)
- [使用示例](#使用示例)
- [日志系统](#日志系统)

## 项目简介

KPPACHONG-SPORT 是一个面向 NBA 体育数据的自动化采集系统。系统通过调用 `api.nba.cn` 开放 API，按三个阶段有序采集：

1. **索引采集阶段** - 获取球队索引和球员索引
2. **数据采集阶段** - 获取球员数据、球队数据、球队阵容、赛程数据、赛程详情
3. **新闻爬取阶段** - 获取 NBA 新闻列表及详情

所有采集到的数据统一存储到 MySQL 数据库的 `kaopu` 库中，可通过两种 GUI 界面进行管理和控制。

## 功能特性

- **三阶段有序爬取**：索引采集 -> 数据采集 -> 新闻爬取，各阶段按顺序执行，前一阶段完成后自动进入下一阶段
- **8 个独立爬虫模块**：
  - 球队索引（`spider_nba_team_index.py`）
  - 球员索引（`spider_nba_player_index.py`）
  - 球员数据（`spider_nba_player_stats.py`）
  - 球队数据（`spider_nba_team_stats.py`）
  - 球队阵容（`spider_nba_team_lineup.py`）
  - 赛程数据（`spider_nba_schedule.py`）
  - 赛程详情（`spider_nba_schedule_data.py`）
  - 新闻爬取（`spider_nba_news.py`）
- **连接池管理**：内置数据库连接池，支持多并发安全获取与释放连接
- **双重 GUI 界面**：
  - 经典版（`gui.py`）- 简洁按钮式操作
  - 增强版（`index.py`）- 暗色主题、动画进度条、实时日志、多阶段监控
- **完善日志系统**：按大小轮转切割，按事件类型分类存储，支持控制台和文件双输出
- **数据去重**：自动检测已存在数据，避免重复插入
- **新闻内容解析**：支持从压缩的 `cnt_attr` 数组中提取新闻正文
- **赛事数据可视化工具**：`utils/match_display.py` 提供赛事卡片 HTML 渲染、比分格式化等功能

## 技术栈

| 类别 | 技术选型 |
|------|----------|
| 编程语言 | Python 3.13 |
| 数据库 | MySQL 8.0 |
| ORM/驱动 | PyMySQL |
| 网络请求 | Requests |
| GUI 框架 | Tkinter |
| 日志处理 | Python logging（自定义 SizeRotatingFileHandler） |
| 数据处理 | JSON、Zlib、Base64 |
| 辅助工具 | XPinyin（拼音转换） |

## 目录结构

```
KPPACHONG-SPORT/
├── main.py                  # 主入口 - 基于适配器的爬虫编排器
├── gui.py                   # GUI 界面（经典版）- 按钮式操作
├── index.py                 # GUI 界面（增强版）- 暗色主题+动画进度条
├── config.py                # 配置管理器 - 数据库/Crawler/多网站配置
├── config.ini               # 数据库连接配置文件
├── logger.py                # 日志管理器 - 按大小轮转+分类存储
├── mysql.py                 # 数据库管理器 - 连接池+CRUD 操作
│
├── core/                    # 爬虫核心模块
│   ├── spider_nba_team_index.py      # 球队索引爬虫
│   ├── spider_nba_player_index.py    # 球员索引爬虫
│   ├── spider_nba_player_stats.py    # 球员数据统计爬虫
│   ├── spider_nba_team_stats.py      # 球队数据统计爬虫
│   ├── spider_nba_team_lineup.py     # 球队阵容爬虫
│   ├── spider_nba_schedule.py        # 赛程数据爬虫
│   ├── spider_nba_schedule_data.py   # 赛程详情/比分数据爬虫
│   ├── spider_nba_standings.py       # 球队排名数据爬虫
│   ├── spider_nba_news.py            # 新闻爬取爬虫
│   └── common.py                     # 爬虫共享基类与常量（新）
│
├── utils/                   # 工具模块
│   └── match_display.py             # 赛事数据显示工具（HTML卡片/格式化）
│
├── database/                # 数据库相关
│   └── base.sql                     # 数据库建表脚本
│
├── json/                    # 空目录（已清理所有未使用的 API 响应缓存）
│
├── logs/                    # 日志输出目录（自动创建）
├── reports/                 # 报告输出目录
└── .workbuddy/              # 项目工作区配置
```

## 数据库设计

### 核心业务表（NBA 数据）

| 表名 | 说明 |
|------|------|
| `kp_sports_lq_team` | 球队基本信息表 |
| `kp_sports_lq_player` | 球员基本信息表 |
| `kp_sports_lq_player_season_stats` | 球员赛季统计数据 |
| `kp_sports_lq_player_game_data` | 球员单场数据 |
| `kp_sports_lq_team_season_stats` | 球队赛季统计数据 |
| `kp_sports_lq_game_data` | 比赛数据表 |
| `kp_sports_lq_player_ranking` | 球员排名表 |
| `kp_sports_lq_team_ranking` | 球队排名表 |
| `kp_sports_type` | 体育类型表（NBA 等） |
| `kp_news` | 新闻表 |
| `kp_news_category` | 新闻分类表 |

> 完整建表语句请参见 `database/base.sql`。

## 安装与运行

### 环境要求

- Python 3.13+
- MySQL 8.0+
- 网络连接（用于访问 NBA API）

### 安装步骤

1. **克隆项目**

```bash
git clone <repository-url>
cd KPPACHONG-SPORT
```

2. **安装依赖**

```bash
pip install pymysql requests xpinyin
```

3. **初始化数据库**

```bash
mysql -u root -p < database/base.sql
```

4. **配置数据库连接**

编辑 `config.ini` 文件：

```ini
[database]
host=127.0.0.1
port=3306
user=root
password=你的密码
database=kaopu
```

## 配置说明

### 配置文件

| 文件 | 用途 |
|------|------|
| `config.ini` | 数据库连接配置（主机、端口、用户名、密码、库名） |
| `config.py` | 配置管理器，自动加载 INI 配置并提供编程接口 |

### API 配置

爬虫模块直接使用 `api.nba.cn` 的公开 API，配置信息（`app_key`、`sign` 等）硬编码在各爬虫文件中，无需额外配置。

### 日志配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| 日志目录 | `logs/` | 日志文件存放路径 |
| 单文件大小 | 10MB | 超过此大小自动切割 |
| 保留份数 | 5 | 旧日志备份数量 |

## 使用示例

### 方式一：启动增强版 GUI（推荐）

```bash
python index.py
```

打开增强版图形界面后：
1. 点击右侧 **"开始爬取"** 按钮
2. 系统自动按三个阶段依次执行 8 个爬虫
3. 左侧实时显示进度条、阶段标签和执行日志
4. 可点击 **"停止"** 按钮中断爬取

### 方式二：启动经典版 GUI

```bash
python gui.py
```

打开经典界面后，点击对应按钮逐个执行爬虫任务。

### 方式三：命令行运行

```bash
python main.py
```

直接运行主入口，通过 `NBACrawler` 和 `DataProcessor` 类自动执行完整数据流。

### 新闻爬取单独运行

```python
from core.spider_nba_news import NBANewsCrawler

with NBANewsCrawler() as crawler:
    result = crawler.crawl_news(max_pages=10, page_size=20)
    print(result)
```

### 赛事数据显示

```python
from utils.match_display import format_match_info, render_match_card, parse_match_summary

# 格式化赛事信息
info_text = format_match_info(match_data)

# 渲染 HTML 赛事卡片
html_card = render_match_card(match_data)

# 解析压缩的 match_summary 数据
summary = parse_match_summary(compressed_data)
```

## 日志系统

日志采用分类存储 + 大小轮转机制：

- **主日志**：`logs/nba_crawler_YYYY-MM-DD.log`
- **分类日志**：`logs/user_action/`、`logs/system_event/`、`logs/error/`、`logs/crawler/`、`logs/data/`、`logs/api/`
- **自动切割**：超过 10MB 时自动归档为 `.1`、`.2` ... `.5`

日志级别：`DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL`

## 许可证

本项目仅供学习和研究使用。