# 游铛铛后端API

## 技术栈

- **框架**：FastAPI
- **数据库**：MySQL 8.0
- **ORM**：SQLAlchemy
- **加密**：cryptography (RSA)
- **文档**：Swagger/OpenAPI

## 项目结构

```
backend/
├── app/
│   ├── __init__.py
│   ├── main.py              # 应用入口
│   ├── config.py            # 配置管理
│   ├── database.py          # 数据库连接
│   ├── models/              # 数据模型
│   │   ├── __init__.py
│   │   ├── user.py
│   │   ├── card.py
│   │   ├── software.py
│   │   └── ...
│   ├── schemas/             # Pydantic模型
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── ...
│   ├── api/                 # API路由
│   │   ├── __init__.py
│   │   ├── deps.py          # 依赖注入
│   │   ├── client/          # 客户端接口
│   │   │   ├── __init__.py
│   │   │   ├── auth.py
│   │   │   └── ...
│   │   └── admin/           # 管理端接口
│   │       ├── __init__.py
│   │       ├── auth.py
│   │       └── ...
│   ├── core/                # 核心功能
│   │   ├── __init__.py
│   │   ├── security.py      # 安全相关
│   │   ├── encrypt.py       # 加密工具
│   │   └── logger.py        # 日志
│   └── utils/               # 工具函数
│       ├── __init__.py
│       └── ...
├── requirements.txt
├── .env.example
└── README.md

```

## 安装依赖

```bash
pip install -r requirements.txt
```

## 配置

复制 `.env.example` 为 `.env` 并配置数据库连接信息。

## 运行

```bash
# 开发模式
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 生产模式
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
```

## API文档

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

## 🚀 新功能：心跳实时配置更新

### 功能特性

- **实时配置更新**：通过心跳机制实现客户端配置的实时更新
- **无需重启应用**：配置变更秒级生效
- **动态调整**：支持心跳间隔、超时时间、失败重试等参数的动态调整

### 实现方式

心跳API (`POST /api/user/heartbeat`) 在每次响应中包含最新的客户端配置：

```json
{
  "code": 200,
  "data": {
    "client_configs": {
      "api_timeout_seconds": 30,
      "client_heartbeat_interval_seconds": 30,
      "max_heartbeat_failures": 10,
      "max_network_failures": 15
    }
  }
}
```

### 配置管理

通过数据库 `system_config` 表管理配置：

```sql
-- 修改心跳间隔
-- 修改心跳间隔为60秒

-- 修改API超时时间
UPDATE system_config SET config_value='45' WHERE config_key='api_timeout_seconds';
```

### 详细文档

请参考：[心跳配置更新文档](./HEARTBEAT_CONFIG_UPDATE.md)


## 🚀 新功能：心跳实时配置更新

### 功能特性

- **实时配置更新**：通过心跳机制实现客户端配置的实时更新
- **无需重启应用**：配置变更秒级生效
- **动态调整**：支持心跳间隔、超时时间、失败重试等参数的动态调整

### 实现方式

心跳API (`POST /api/user/heartbeat`) 在每次响应中包含最新的客户端配置：

```json
{
  "code": 200,
  "data": {
    "client_configs": {
      "api_timeout_seconds": 30,
      "client_heartbeat_interval_seconds": 30,
      "max_heartbeat_failures": 10,
      "max_network_failures": 15
    }
  }
}
```

### 配置管理

通过数据库 `system_config` 表管理配置：

```sql
-- 修改心跳间隔
-- 修改心跳间隔为60秒

-- 修改API超时时间
UPDATE system_config SET config_value='45' WHERE config_key='api_timeout_seconds';
```

### 详细文档

请参考：[心跳配置更新文档](./HEARTBEAT_CONFIG_UPDATE.md)