# osu! API 模拟服务器

这是一个使用 FastAPI + MySQL + Redis 实现的 osu! API 模拟服务器，提供了完整的用户认证和数据管理功能。

## 功能特性

- **OAuth 2.0 认证**: 支持密码流和刷新令牌流
- **用户数据管理**: 完整的用户信息、统计数据、成就等
- **多游戏模式支持**: osu!, taiko, fruits, mania
- **数据库持久化**: MySQL 存储用户数据
- **缓存支持**: Redis 缓存令牌和会话信息
- **容器化部署**: Docker 和 Docker Compose 支持

## API 端点

### 认证端点
- `POST /oauth/token` - OAuth 令牌获取/刷新

### 用户端点
- `GET /api/v2/me/{ruleset}` - 获取当前用户信息

### 其他端点
- `GET /` - 根端点
- `GET /health` - 健康检查

## 快速开始

### 使用 Docker Compose (推荐)

1. 克隆项目
```bash
git clone <repository-url>
cd osu_lazer_api
```

2. 启动服务
```bash
docker-compose up -d
```

3. 创建示例数据
```bash
docker-compose exec api python create_sample_data.py
```

4. 测试 API
```bash
# 获取访问令牌
curl -X POST http://localhost:8000/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=Googujiang&password=password123&client_id=5&client_secret=FGc9GAtyHzeQDshWP5Ah7dega8hJACAJpQtw6OXk&scope=*"

# 使用令牌获取用户信息
curl -X GET http://localhost:8000/api/v2/me/osu \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### 本地开发

1. 安装依赖
```bash
pip install -r requirements.txt
```

2. 配置环境变量
```bash
# 复制服务器配置文件
cp .env .env.local

# 复制客户端配置文件（用于测试脚本）
cp .env.client .env.client.local
```

3. 启动 MySQL 和 Redis
```bash
# 使用 Docker
docker run -d --name mysql -e MYSQL_ROOT_PASSWORD=password -e MYSQL_DATABASE=osu_api -p 3306:3306 mysql:8.0
docker run -d --name redis -p 6379:6379 redis:7-alpine
```

4. 创建示例数据
```bash
python create_sample_data.py
```

5. 启动应用
```bash
uvicorn main:app --reload
```

6. 测试 API
```bash
# 使用测试脚本（会自动加载 .env 文件）
python test_api.py

# 或使用原始示例脚本
python osu_api_example.py
```

## 项目结构

```
osu_lazer_api/
├── app/
│   ├── __init__.py
│   ├── models.py          # Pydantic 数据模型
│   ├── database.py        # SQLAlchemy 数据库模型
│   ├── config.py          # 配置设置
│   ├── dependencies.py    # 依赖注入
│   ├── auth.py           # 认证和令牌管理
│   └── utils.py          # 工具函数
├── main.py               # FastAPI 应用主文件
├── create_sample_data.py # 示例数据创建脚本
├── requirements.txt      # Python 依赖
├── .env                 # 环境变量配置
├── docker-compose.yml   # Docker Compose 配置
├── Dockerfile          # Docker 镜像配置
└── README.md           # 项目说明
```

## 示例用户

创建示例数据后，您可以使用以下凭据进行测试：

- **用户名**: `Googujiang`
- **密码**: `password123`
- **用户ID**: `15651670`

## 环境变量配置

项目包含两个环境配置文件：

### 服务器配置 (`.env`)
用于配置 FastAPI 服务器的运行参数：

| 变量名 | 描述 | 默认值 |
|--------|------|--------|
| `DATABASE_URL` | MySQL 数据库连接字符串 | `mysql+pymysql://root:password@localhost:3306/osu_api` |
| `REDIS_URL` | Redis 连接字符串 | `redis://localhost:6379/0` |
| `SECRET_KEY` | JWT 签名密钥 | `your-secret-key-here` |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | 访问令牌过期时间（分钟） | `1440` |
| `OSU_CLIENT_ID` | OAuth 客户端 ID | `5` |
| `OSU_CLIENT_SECRET` | OAuth 客户端密钥 | `FGc9GAtyHzeQDshWP5Ah7dega8hJACAJpQtw6OXk` |
| `HOST` | 服务器监听地址 | `0.0.0.0` |
| `PORT` | 服务器监听端口 | `8000` |
| `DEBUG` | 调试模式 | `True` |

### 客户端配置 (`.env.client`)
用于配置客户端脚本的 API 连接参数：

| 变量名 | 描述 | 默认值 |
|--------|------|--------|
| `OSU_CLIENT_ID` | OAuth 客户端 ID | `5` |
| `OSU_CLIENT_SECRET` | OAuth 客户端密钥 | `FGc9GAtyHzeQDshWP5Ah7dega8hJACAJpQtw6OXk` |
| `OSU_API_URL` | API 服务器地址 | `http://localhost:8000` |

> **注意**: 在生产环境中，请务必更改默认的密钥和密码！

## API 使用示例

### 获取访问令牌

```bash
curl -X POST http://localhost:8000/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=Googujiang&password=password123&client_id=5&client_secret=FGc9GAtyHzeQDshWP5Ah7dega8hJACAJpQtw6OXk&scope=*"
```

响应：
```json
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "abc123...",
  "scope": "*"
}
```

### 获取用户信息

```bash
curl -X GET http://localhost:8000/api/v2/me/osu \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### 刷新令牌

```bash
curl -X POST http://localhost:8000/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN&client_id=5&client_secret=FGc9GAtyHzeQDshWP5Ah7dega8hJACAJpQtw6OXk"
```

## 开发

### 添加新用户

您可以通过修改 `create_sample_data.py` 文件来添加更多示例用户，或者扩展 API 来支持用户注册功能。

### 扩展功能

- 添加更多 API 端点（排行榜、谱面信息等）
- 实现实时功能（WebSocket）
- 添加管理面板
- 实现数据导入/导出功能

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！