# pingpong-site

**Repository Path**: jgh06/pingpong-site

## Basic Information

- **Project Name**: pingpong-site
- **Description**: 世界乒乓爱好者网站
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-03
- **Last Updated**: 2026-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 世界乒乓爱好者网站

一个面向业余乒乓球爱好者的社群网站，提供赛事资讯、在线报名、积分排行、俱乐部查询与入会申请等服务，并内置 AI 智能问答助手，帮助球友快速找到所需信息。

## ✨ 功能特性

- **首页概览**：展示热门赛事、积分榜 TOP、推荐俱乐部
- **积分排行榜**：按积分降序排列，支持地区与关键词搜索
- **赛事中心**：赛事列表、赛事详情、在线报名（含重复报名校验）
- **俱乐部查询**：俱乐部列表、地区/关键词筛选、入会申请
- **会员体系**：注册、登录（普通用户 / 管理员）
- **管理后台**：数据看板、赛事管理、报名管理、俱乐部管理、入会申请审核
- **AI 智能问答**：基于意图识别的在线客服助手（`/api/chat`）

## 🛠 技术栈

- Python 3.11+
- Flask 3.0
- SQLite
- Jinja2（Flask 内置模板引擎）
- pytest 测试框架

## 📦 项目结构

```
pingpong-site/
├── app.py                  # Flask 应用入口与全部路由
├── chat_agent.py           # AI 问答意图识别与回复逻辑
├── config.py               # 应用配置（密钥、数据库路径、调试开关）
├── requirements.txt        # 依赖清单
├── database/
│   ├── schema.sql          # 数据库表结构
│   └── seed.sql            # 演示数据
├── templates/              # Jinja2 HTML 模板（含管理后台）
├── static/                 # CSS/JS 静态资源
├── tests/                  # pytest 自动化测试
└── .codeartsdoer/specs/    # SDD 规格文档
```

## 🚀 快速开始

### 环境要求

- Python 3.11 及以上版本

### 安装与运行

```powershell
# 1. 创建并激活虚拟环境
py -m venv .venv
.\.venv\Scripts\Activate.ps1

# 2. 安装依赖
pip install -r requirements.txt

# 3. 启动应用
python app.py
```

启动后访问：<http://127.0.0.1:5000>

> 应用首次启动会自动创建 `pingpong.db` 数据库，并写入演示数据。

## ⚙️ 配置与环境变量

应用配置集中在 `config.py`，当前为硬编码默认值：

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `SECRET_KEY` | Flask 会话签名密钥 | 内置固定值 |
| `DATABASE` | SQLite 数据库路径 | 项目根目录 `pingpong.db` |
| `DEBUG` | 调试模式开关 | `True` |

> **生产环境建议**：将上述配置改为通过环境变量注入，例如 `os.environ.get("SECRET_KEY")`，并将 `DEBUG` 设为 `False`，避免硬编码密钥泄密。

## 🧪 测试

```powershell
pytest -q
```

## 🔐 演示账号

| 角色 | 用户名 | 密码 |
|------|--------|------|
| 普通用户 | demo | demo123 |
| 管理员 | admin | admin123 |

## 📚 API 接口

### 智能问答 `POST /api/chat`

供前端 AI 问答助手调用，请求与响应均为 `application/json`。

**请求体**：

```json
{ "message": "北京有哪些俱乐部？" }
```

**响应体**：

```json
{ "reply": "……" }
```

## 🗄 数据库表结构

| 表名 | 说明 |
|------|------|
| `users` | 用户（含管理员与演示账号） |
| `players` | 球员与积分排行 |
| `tournaments` | 赛事 |
| `registrations` | 赛事报名记录 |
| `clubs` | 俱乐部 |
| `venues` | 球馆 |
| `club_applications` | 俱乐部入会申请 |

## 🚢 部署（生产环境）

```bash
# 安装生产级 WSGI 服务器
pip install waitress

# 启动服务
waitress-serve --listen=0.0.0.0:5000 app:app
```

部署前请务必将 `DEBUG` 设为 `False`，并通过环境变量设置独立的 `SECRET_KEY`。

## 说明

- 所有数据当前均为演示数据。
- 应用首次启动会自动建库并写入演示数据。
- 页面支持桌面端与移动端（390px）响应式布局。