# guandan-api

**Repository Path**: lirui666/guandan-api

## Basic Information

- **Project Name**: guandan-api
- **Description**: 掼蛋比赛 PHP
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-05-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 掼蛋赛事助手 API

掼蛋赛事管理系统后端 API，基于 ThinkPHP 8 开发。

## 功能特性

- **用户系统**：注册、登录、JWT 认证
- **赛事管理**：创建、编辑、删除赛事，生成唯一赛事码
- **队伍管理**：创建队伍、管理队员
- **报名系统**：赛事报名、缴费管理
- **赛程生成**：支持循环赛和淘汰赛，自动生成赛程
- **比分录入**：比赛结果录入，淘汰赛自动晋级
- **管理员系统**：管理员权限管理

## 技术栈

- PHP 8.0+
- ThinkPHP 8.0
- MySQL 5.7+
- JWT 认证 (firebase/php-jwt)

## 安装指南

### 1. 克隆项目

```bash
git clone https://github.com/guandan/guandan-api.git
cd guandan-api
```

### 2. 安装依赖

```bash
composer install
```

### 3. 配置环境

```bash
cp .env.example .env
```

编辑 `.env` 文件，配置数据库连接：

```ini
DB_HOST = 127.0.0.1
DB_NAME = guandan
DB_USER = root
DB_PASS = your_password
DB_PORT = 3306

JWT_SECRET = your_random_secret_key_change_this
```

### 4. 创建数据库

```bash
# 创建数据库
mysql -u root -p -e "CREATE DATABASE guandan CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 方式一：使用 SQL 文件导入
mysql -u root -p guandan < database/migrations/init.sql

# 方式二：使用 ThinkPHP 迁移（如果已安装 think-migration）
php think migrate:run
```

### 5. 设置目录权限

```bash
chmod -R 755 runtime/
chmod -R 755 public/uploads/
```

### 6. 配置 Web 服务器

将网站根目录指向 `public/` 目录。

**Nginx 配置示例：**

```nginx
server {
    listen 80;
    server_name api.guandan.example;
    root /var/www/guandan-api/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}
```

**Apache 配置示例：**

```apache
<VirtualHost *:80>
    ServerName api.guandan.example
    DocumentRoot /var/www/guandan-api/public

    <Directory /var/www/guandan-api/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>
```

## API 接口文档

### 基础信息

- 基础 URL: `http://your-domain/api/`
- 响应格式: JSON
- 认证方式: Bearer Token

### 公共接口

#### 用户认证

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/api/auth/register` | 用户注册 |
| POST | `/api/auth/login` | 用户登录 |

#### 赛事查询

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/competitions` | 赛事列表 |
| GET | `/api/competitions/:id` | 赛事详情 |
| GET | `/api/competitions/:id/teams` | 参赛队伍 |
| GET | `/api/competitions/:id/matches` | 赛程 |
| GET | `/api/competitions/:id/rankings` | 排名 |

### 需要登录的接口

Header 需携带: `Authorization: Bearer <token>`

#### 用户相关

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/api/auth/logout` | 退出登录 |
| GET | `/api/auth/me` | 当前用户信息 |
| GET | `/api/user/profile` | 个人资料 |
| PUT | `/api/user/profile` | 更新资料 |

#### 队伍管理

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/teams/my` | 我的队伍 |
| POST | `/api/teams` | 创建队伍 |
| PUT | `/api/teams/:id` | 更新队伍 |
| DELETE | `/api/teams/:id` | 删除队伍 |

#### 赛事报名

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/api/competitions/:id/register` | 报名参赛 |

### 管理员接口

需要管理员权限

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/api/competitions` | 创建赛事 |
| PUT | `/api/competitions/:id` | 更新赛事 |
| DELETE | `/api/competitions/:id` | 删除赛事 |
| POST | `/api/competitions/:id/schedule` | 生成赛程 |
| PUT | `/api/matches/:id/score` | 录入比分 |
| GET | `/api/admins` | 管理员列表 |
| POST | `/api/admins` | 添加管理员 |
| DELETE | `/api/admins/:id` | 移除管理员 |

## 请求/响应示例

### 注册

**请求：**
```json
POST /api/auth/register
{
    "phone": "13800138000",
    "password": "123456",
    "nickname": "张三"
}
```

**响应：**
```json
{
    "code": 200,
    "msg": "注册成功",
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
        "user": {
            "id": 1,
            "nickname": "张三",
            "phone": "13800138000",
            "balance": "500.00"
        }
    },
    "time": 1705500000
}
```

### 创建赛事

**请求：**
```json
POST /api/competitions
Authorization: Bearer <token>
{
    "name": "春季掼蛋大赛",
    "format": "elimination",
    "max_teams": 16,
    "team_size": 2,
    "location": "市中心体育馆"
}
```

## 项目结构

```
guandan-api/
├── app/
│   ├── api/
│   │   ├── controller/      # 控制器
│   │   ├── model/           # 数据模型
│   │   └── middleware/      # 中间件
│   └── common.php           # 公共函数
├── config/                  # 配置文件
├── database/
│   └── migrations/          # 数据库迁移
├── public/                  # 网站根目录
├── route/
│   └── app.php             # 路由定义
├── composer.json
└── .env
```

## 开发说明

### 配置说明

- `config/app.php` - 应用配置
- `config/database.php` - 数据库配置
- `config/jwt.php` - JWT 配置
- `config/middleware.php` - 中间件配置

### 常用命令

```bash
# 清除缓存
php think clear

# 运行迁移
php think migrate:run

# 创建迁移
php think migrate:create AddNewField
```

## 许可证

MIT License