Ubuntu
853 lines
16 KiB
Markdown
853 lines
16 KiB
Markdown
# Net-Games API 接口文档
|
|
|
|
> **版本**: v2.0
|
|
> **更新日期**: 2026-04-09
|
|
> **服务端**: Flask-SocketIO on port 8900
|
|
|
|
---
|
|
|
|
## 1. HTTP REST API
|
|
|
|
### 1.1 认证相关
|
|
|
|
#### `GET /api/auth/status` - 检查登录状态
|
|
**响应:**
|
|
```json
|
|
{
|
|
"authenticated": true,
|
|
"user": {
|
|
"id": 1,
|
|
"username": "caixianming",
|
|
"nickname": "蔡叔叔",
|
|
"created_at": "2026-04-01T10:00:00",
|
|
"role": "user",
|
|
"is_admin": false
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `POST /api/auth/login` - 用户登录
|
|
**请求:**
|
|
```json
|
|
{
|
|
"username": "caixianming",
|
|
"password": "cxm123456"
|
|
}
|
|
```
|
|
|
|
**响应:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "登录成功",
|
|
"user": {
|
|
"id": 1,
|
|
"username": "caixianming",
|
|
"nickname": "蔡叔叔",
|
|
"role": "user",
|
|
"is_admin": false
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `POST /api/auth/register` - 用户注册
|
|
**请求:**
|
|
```json
|
|
{
|
|
"username": "newuser",
|
|
"password": "password123"
|
|
}
|
|
```
|
|
|
|
**响应:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "注册成功",
|
|
"user": {...}
|
|
}
|
|
```
|
|
|
|
#### `POST /api/auth/logout` - 用户登出
|
|
**响应:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "已登出"
|
|
}
|
|
```
|
|
|
|
### 1.2 用户相关
|
|
|
|
#### `GET /api/user/profile` - 获取个人资料
|
|
**响应:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"user": {
|
|
"id": 1,
|
|
"username": "caixianming",
|
|
"nickname": "蔡叔叔",
|
|
"created_at": "2026-04-01T10:00:00"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `PUT /api/user/profile` - 更新昵称
|
|
**请求:**
|
|
```json
|
|
{
|
|
"nickname": "新昵称"
|
|
}
|
|
```
|
|
|
|
#### `PUT /api/user/password` - 修改密码
|
|
**请求:**
|
|
```json
|
|
{
|
|
"old_password": "旧密码",
|
|
"new_password": "新密码"
|
|
}
|
|
```
|
|
|
|
#### `GET /api/user/scores` - 获取各游戏积分
|
|
**响应:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"scores": {
|
|
"doudizhu": 100,
|
|
"chinese_chess": 50
|
|
}
|
|
}
|
|
```
|
|
|
|
### 1.3 房间相关
|
|
|
|
#### `GET /api/rooms` - 获取房间列表
|
|
**查询参数:**
|
|
- `game_type` - 游戏类型过滤 (可选)
|
|
- `status` - 状态过滤: waiting/playing (默认: waiting)
|
|
|
|
**响应:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"rooms": [
|
|
{
|
|
"id": "room_xxx",
|
|
"code": "A1B2C3",
|
|
"game_type": "doudizhu",
|
|
"status": "waiting",
|
|
"max_players": 3,
|
|
"player_count": 1,
|
|
"host_id": "player_xxx",
|
|
"created_at": 1234567890,
|
|
"players": [...]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### `GET /api/rooms/<room_code>` - 获取房间信息
|
|
**响应:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"room": {
|
|
"id": "room_xxx",
|
|
"code": "A1B2C3",
|
|
"game_type": "doudizhu",
|
|
"status": "playing",
|
|
"players": [...],
|
|
"game": {...}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 1.4 统计相关
|
|
|
|
#### `GET /api/stats` - 获取服务统计（公开）
|
|
**响应:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"stats": {
|
|
"total_rooms": 10,
|
|
"waiting_rooms": 3,
|
|
"playing_rooms": 7,
|
|
"total_players": 21
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `GET /api/admin/stats` - 管理员详细统计
|
|
**响应:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"stats": {
|
|
"total_rooms": 10,
|
|
"waiting_rooms": 3,
|
|
"playing_rooms": 7,
|
|
"total_players": 21,
|
|
"online_users": 15,
|
|
"by_game": {
|
|
"doudizhu": {...}
|
|
},
|
|
"rooms": [...]
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `DELETE /api/admin/rooms/<room_code>` - 强制关闭房间
|
|
**响应:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "房间 A1B2C3 已关闭"
|
|
}
|
|
```
|
|
|
|
|
|
---
|
|
|
|
## 2. Socket.IO 事件
|
|
|
|
### 2.1 连接管理
|
|
|
|
#### `connect` - 客户端连接
|
|
**服务端响应:**
|
|
```json
|
|
{
|
|
"event": "connected",
|
|
"data": {
|
|
"socket_id": "xxx",
|
|
"message": "欢迎连接到 Net-Games",
|
|
"has_active_game": true,
|
|
"room_code": "A1B2C3",
|
|
"room_id": "room_xxx"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `disconnect` - 客户端断开
|
|
- 服务端自动处理，标记玩家为离线
|
|
- 30秒后启用AI托管
|
|
|
|
#### `ping` / `pong` - 心跳
|
|
**客户端发送:**
|
|
```json
|
|
{
|
|
"event": "ping",
|
|
"data": {"timestamp": 1234567890}
|
|
}
|
|
```
|
|
|
|
**服务端响应:**
|
|
```json
|
|
{
|
|
"event": "pong",
|
|
"data": {
|
|
"timestamp": 1234567890,
|
|
"server_time": 1234567890
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2.2 房间管理事件
|
|
|
|
#### `create_room` - 创建房间
|
|
**客户端发送:**
|
|
```json
|
|
{
|
|
"game_type": "doudizhu",
|
|
"player_name": "蔡叔叔",
|
|
"config": {
|
|
"max_players": 3
|
|
},
|
|
"ai_players": [
|
|
{"name": "AI-规则", "ai_type": "rule"},
|
|
{"name": "AI-DeepSeek", "ai_type": "deepseek"}
|
|
]
|
|
}
|
|
```
|
|
|
|
**服务端响应 (创建者):**
|
|
```json
|
|
{
|
|
"event": "room_created",
|
|
"data": {
|
|
"success": true,
|
|
"room": {
|
|
"id": "room_xxx",
|
|
"code": "A1B2C3",
|
|
"game_type": "doudizhu",
|
|
"status": "waiting",
|
|
"max_players": 3,
|
|
"player_count": 3,
|
|
"host_id": "player_xxx",
|
|
"players": [...]
|
|
},
|
|
"player": {
|
|
"id": "player_xxx",
|
|
"name": "蔡叔叔",
|
|
"seat_number": 0,
|
|
"is_ready": false
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**错误响应:**
|
|
```json
|
|
{
|
|
"event": "error",
|
|
"data": {
|
|
"code": "ALREADY_ONLINE",
|
|
"message": "账号 \"蔡叔叔\" 已在游戏中"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `join_room` - 加入房间
|
|
**客户端发送:**
|
|
```json
|
|
{
|
|
"room_code": "A1B2C3",
|
|
"player_name": "玩家B"
|
|
}
|
|
```
|
|
|
|
**服务端响应 (加入者):**
|
|
```json
|
|
{
|
|
"event": "room_joined",
|
|
"data": {
|
|
"success": true,
|
|
"room": {...},
|
|
"player": {...}
|
|
}
|
|
}
|
|
```
|
|
|
|
**广播 (其他玩家):**
|
|
```json
|
|
{
|
|
"event": "player_joined",
|
|
"data": {
|
|
"player": {
|
|
"id": "player_yyy",
|
|
"name": "玩家B",
|
|
"seat_number": 1,
|
|
"is_ready": false
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `leave_room` - 离开房间
|
|
**服务端响应 (离开者):**
|
|
```json
|
|
{
|
|
"event": "room_left",
|
|
"data": {"success": true}
|
|
}
|
|
```
|
|
|
|
**广播 (其他玩家):**
|
|
```json
|
|
{
|
|
"event": "player_left",
|
|
"data": {
|
|
"player_id": "player_xxx",
|
|
"player_name": "蔡叔叔"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `reconnect_room` - 断线重连
|
|
**客户端发送:**
|
|
```json
|
|
{
|
|
"room_code": "A1B2C3",
|
|
"player_id": "player_xxx",
|
|
"player_name": "蔡叔叔"
|
|
}
|
|
```
|
|
|
|
**服务端响应 (重连者):**
|
|
```json
|
|
{
|
|
"event": "reconnect_success",
|
|
"data": {
|
|
"player_id": "player_xxx",
|
|
"player": {...},
|
|
"room": {...},
|
|
"was_ai_controlled": true,
|
|
"message": "重连成功，欢迎回到游戏！"
|
|
}
|
|
}
|
|
```
|
|
|
|
**广播 (其他玩家):**
|
|
```json
|
|
{
|
|
"event": "player_reconnected",
|
|
"data": {
|
|
"player_id": "player_xxx",
|
|
"player_name": "蔡叔叔",
|
|
"was_ai_controlled": true,
|
|
"message": "蔡叔叔 已回到游戏"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2.3 游戏准备事件
|
|
|
|
#### `set_ready` - 设置准备状态
|
|
**客户端发送:**
|
|
```json
|
|
{
|
|
"ready": true
|
|
}
|
|
```
|
|
|
|
**广播 (所有人):**
|
|
```json
|
|
{
|
|
"event": "room_updated",
|
|
"data": {
|
|
"room": {...}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `start_game` - 开始游戏（仅房主）
|
|
**广播 (所有人):**
|
|
```json
|
|
{
|
|
"event": "game_started",
|
|
"data": {
|
|
"room": {
|
|
"id": "room_xxx",
|
|
"status": "playing",
|
|
"game": {
|
|
"state": {
|
|
"phase": "playing",
|
|
"current_turn": "player_xxx",
|
|
"data": {
|
|
"phase": "calling",
|
|
"lord_id": null,
|
|
"bottom_cards": [],
|
|
"player_cards_count": {"player_xxx": 17, ...}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
### 2.4 游戏操作事件
|
|
|
|
#### `game_action` - 游戏操作
|
|
**客户端发送:**
|
|
```json
|
|
{
|
|
"action": "call",
|
|
"data": {"want": true}
|
|
}
|
|
```
|
|
|
|
**action 类型:**
|
|
- `call` - 叫地主 (data: `{want: true/false}`)
|
|
- `play` - 出牌 (data: `{card_ids: [...]}`)
|
|
- `pass` - 不出/过 (data: `{}`)
|
|
- `toggle_trustee` - 切换托管状态
|
|
|
|
**成功广播 (所有人):**
|
|
```json
|
|
{
|
|
"event": "state_update",
|
|
"data": {
|
|
"action": "play",
|
|
"player_id": "player_xxx",
|
|
"result": {
|
|
"success": true,
|
|
"message": "出牌成功",
|
|
"played_cards": [...],
|
|
"card_type": {"type": "pair", "name": "对子"}
|
|
},
|
|
"game_state": {...}
|
|
}
|
|
}
|
|
```
|
|
|
|
**失败响应 (仅操作者):**
|
|
```json
|
|
{
|
|
"event": "action_failed",
|
|
"data": {
|
|
"action": "play",
|
|
"message": "牌型不合法"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2.5 游戏结束事件
|
|
|
|
#### `game_ended` - 游戏结束广播
|
|
```json
|
|
{
|
|
"event": "game_ended",
|
|
"data": {
|
|
"winner": {
|
|
"id": "player_xxx",
|
|
"player_id": "player_xxx",
|
|
"name": "蔡叔叔",
|
|
"is_lord": true
|
|
},
|
|
"winner_id": "player_xxx",
|
|
"room": {...},
|
|
"scores": {
|
|
"player_xxx": {
|
|
"name": "蔡叔叔",
|
|
"change": 6,
|
|
"total": 106,
|
|
"is_lord": true,
|
|
"is_winner": true,
|
|
"is_ai": false
|
|
},
|
|
"player_yyy": {
|
|
"name": "AI-规则",
|
|
"change": 0,
|
|
"total": 0,
|
|
"is_ai": true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2.6 托管与超时事件
|
|
|
|
#### `trustee_changed` - 托管状态变更
|
|
```json
|
|
{
|
|
"event": "trustee_changed",
|
|
"data": {
|
|
"player_id": "player_xxx",
|
|
"player_name": "蔡叔叔",
|
|
"is_trustee": true,
|
|
"message": "蔡叔叔 进入了托管模式"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `player_ai_controlled` - 玩家被AI托管
|
|
```json
|
|
{
|
|
"event": "player_ai_controlled",
|
|
"data": {
|
|
"player_id": "player_xxx",
|
|
"player_name": "蔡叔叔",
|
|
"reason": "timeout",
|
|
"message": "蔡叔叔 超时3次，已启用AI托管"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `player_disconnected` - 玩家断开连接
|
|
```json
|
|
{
|
|
"event": "player_disconnected",
|
|
"data": {
|
|
"player_id": "player_xxx",
|
|
"player_name": "蔡叔叔",
|
|
"will_ai_control": true
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `turn_timeout_auto` - 超时自动操作
|
|
```json
|
|
{
|
|
"event": "turn_timeout_auto",
|
|
"data": {
|
|
"player_id": "player_xxx",
|
|
"player_name": "蔡叔叔",
|
|
"action": "pass",
|
|
"action_name": "不要",
|
|
"timeout_count": 1,
|
|
"game_state": {...},
|
|
"message": "蔡叔叔 超时，自动不要 (1/3)"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2.7 错误事件
|
|
|
|
#### `error` - 错误通知
|
|
```json
|
|
{
|
|
"event": "error",
|
|
"data": {
|
|
"code": "NOT_YOUR_TURN",
|
|
"message": "不是你的回合"
|
|
}
|
|
}
|
|
```
|
|
|
|
**常见错误码:**
|
|
| 错误码 | 说明 |
|
|
|--------|------|
|
|
| `NOT_IN_ROOM` | 不在任何房间中 |
|
|
| `ROOM_NOT_FOUND` | 房间不存在 |
|
|
| `ROOM_FULL` | 房间已满 |
|
|
| `GAME_NOT_STARTED` | 游戏未开始 |
|
|
| `NOT_HOST` | 只有房主可以开始游戏 |
|
|
| `NOT_YOUR_TURN` | 不是你的回合 |
|
|
| `ALREADY_ONLINE` | 已在其他游戏中 |
|
|
| `INVALID_CARDS` | 牌型不合法 |
|
|
| `CANNOT_BEAT` | 管不起上家的牌 |
|
|
| `AI_PLAYER` | AI玩家不能进行此操作 |
|
|
|
|
---
|
|
|
|
## 3. 游戏状态结构
|
|
|
|
### 3.1 斗地主游戏状态
|
|
```json
|
|
{
|
|
"room_id": "room_xxx",
|
|
"game_type": "doudizhu",
|
|
"min_players": 3,
|
|
"max_players": 3,
|
|
"player_count": 3,
|
|
"is_started": true,
|
|
"is_ended": false,
|
|
|
|
"state": {
|
|
"game_type": "doudizhu",
|
|
"room_id": "room_xxx",
|
|
"phase": "playing",
|
|
"round": 1,
|
|
"turn_count": 5,
|
|
"current_turn": "player_xxx",
|
|
"winner": null,
|
|
|
|
"player_states": {
|
|
"player_xxx": {
|
|
"name": "蔡叔叔",
|
|
"is_ai": false,
|
|
"seat": 0,
|
|
"cards": [...],
|
|
"card_count": 17
|
|
}
|
|
},
|
|
|
|
"data": {
|
|
"phase": "playing",
|
|
"current_turn": "player_xxx",
|
|
"lord_id": "player_xxx",
|
|
"bottom_cards": [...],
|
|
"desktop_cards": {
|
|
"type": "pair",
|
|
"value": 5,
|
|
"name": "对子"
|
|
},
|
|
"last_played_id": "player_yyy",
|
|
"pass_count": 0,
|
|
"player_cards_count": {
|
|
"player_xxx": 17,
|
|
"player_yyy": 15,
|
|
"player_zzz": 16
|
|
}
|
|
},
|
|
|
|
"history": [...]
|
|
},
|
|
|
|
"players": {
|
|
"player_xxx": {
|
|
"id": "player_xxx",
|
|
"name": "蔡叔叔",
|
|
"type": "human",
|
|
"is_ai": false,
|
|
"is_connected": true,
|
|
"is_ai_controlled": false,
|
|
"seat_number": 0,
|
|
"is_ready": true,
|
|
"role": "landlord"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3.2 玩家视角 (Player View)
|
|
客户端通过 `player_view` 字段只能看到自己的手牌：
|
|
```json
|
|
{
|
|
"my_cards": [
|
|
{"id": "card_1", "suit": "spade", "rank": "A", "value": 14},
|
|
{"id": "card_2", "suit": "heart", "rank": "K", "value": 13}
|
|
],
|
|
"my_cards_count": 17
|
|
}
|
|
```
|
|
|
|
|
|
---
|
|
|
|
## 4. AI 接口
|
|
|
|
### 4.1 AI 适配器基类
|
|
```python
|
|
class AIAdapter(ABC):
|
|
@abstractmethod
|
|
async def make_decision(self, game_state: dict,
|
|
available_actions: list,
|
|
player_context: dict) -> dict:
|
|
"""
|
|
返回决策结果
|
|
{
|
|
"action": "play" | "pass" | "call",
|
|
"data": {...},
|
|
"reasoning": "决策理由"
|
|
}
|
|
"""
|
|
pass
|
|
```
|
|
|
|
### 4.2 AI 类型
|
|
| AI类型 | 说明 | 适用游戏 |
|
|
|--------|------|----------|
|
|
| `rule` | 基于规则的贪心策略 | 斗地主 |
|
|
| `deepseek` | DeepSeek 大模型 | 通用 |
|
|
| `minimax` | Minimax + Alpha-Beta | 象棋 |
|
|
|
|
### 4.3 AI 输入格式
|
|
```json
|
|
{
|
|
"game_state": {
|
|
"status": "playing",
|
|
"current_turn": "ai_player_1",
|
|
"phase": "playing",
|
|
"desktop_cards": {...},
|
|
"player_cards_count": {...}
|
|
},
|
|
"available_actions": ["play", "pass"],
|
|
"player_context": {
|
|
"cards": [...],
|
|
"is_lord": false,
|
|
"teammate_cards": 17
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 游戏流程时序图
|
|
|
|
### 5.1 创建房间并游戏
|
|
```
|
|
┌─────────┐ ┌──────────┐ ┌──────────┐
|
|
│ Client │ │ Server │ │ AI │
|
|
└────┬────┘ └────┬─────┘ └────┬─────┘
|
|
│ │ │
|
|
│ create_room │ │
|
|
│ ─────────────>│ │
|
|
│ │ create room │
|
|
│ │ add AI players │
|
|
│ room_created │ │
|
|
│ <─────────────│ │
|
|
│ │ │
|
|
│ start_game │ │
|
|
│ ─────────────>│ │
|
|
│ │ start game │
|
|
│ game_started │ │
|
|
│ <─────────────│ │
|
|
│ │ │
|
|
│ state_update │ │
|
|
│ <─────────────│ │
|
|
│ │ │
|
|
│ │ ──────────────>│
|
|
│ │ AI decision │
|
|
│ │ <──────────────│
|
|
│ │ │
|
|
│ state_update │ │
|
|
│ <─────────────│ (broadcast) │
|
|
```
|
|
|
|
### 5.2 断线重连流程
|
|
```
|
|
┌─────────┐ ┌──────────┐ ┌──────────┐
|
|
│ Client │ │ Server │ │ Room │
|
|
└────┬────┘ └────┬─────┘ └────┬─────┘
|
|
│ │ │
|
|
│ disconnect │ │
|
|
│ ────────X │ │
|
|
│ │ mark offline │
|
|
│ │ start 30s timer│
|
|
│ │ │
|
|
│ reconnect │ │
|
|
│ ─────────────>│ │
|
|
│ │ find player │
|
|
│ │ ──────────────>│
|
|
│ │ <──────────────│
|
|
│ │ │
|
|
│ reconnect_success │
|
|
│ <─────────────│ │
|
|
│ │ cancel timer │
|
|
│ │ │
|
|
│ (30s后如果没有重连) │
|
|
│ │ enable AI ctrl │
|
|
│ │ │
|
|
│ player_ai_controlled │
|
|
│ <─────────────│ (broadcast) │
|
|
```
|
|
|
|
---
|
|
|
|
## 6. 配置说明
|
|
|
|
### 6.1 环境变量
|
|
| 变量名 | 默认值 | 说明 |
|
|
|--------|--------|------|
|
|
| `NET_GAMES_HOST` | `0.0.0.0` | 服务监听地址 |
|
|
| `NET_GAMES_PORT` | `8900` | 服务端口 |
|
|
| `NET_GAMES_DEBUG` | `true` | 调试模式 |
|
|
| `DATABASE_URL` | `sqlite:///./netgames.db` | 数据库连接 |
|
|
| `DEEPSEEK_API_KEY` | - | DeepSeek API 密钥 |
|
|
| `LOG_LEVEL` | `INFO` | 日志级别 |
|
|
|
|
### 6.2 游戏配置 (config.py)
|
|
```python
|
|
ROOM_MAX_PLAYERS = {
|
|
'doudizhu': 3,
|
|
'chinese_chess': 2,
|
|
}
|
|
|
|
ROOM_CODE_LENGTH = 6
|
|
ROOM_INACTIVE_TIMEOUT_MINUTES = 30
|
|
AI_TIMEOUT_SECONDS = 30
|
|
TURN_TIMEOUT_SECONDS = 30 # 回合超时
|
|
MAX_TIMEOUT_COUNT = 3 # 最大超时次数
|
|
```
|
|
|
|
---
|
|
|
|
## 7. 更新日志
|
|
|
|
| 日期 | 版本 | 变更内容 |
|
|
|------|------|----------|
|
|
| 2026-04-09 | v2.0 | 更新为实际实现版本，添加认证API、托管机制、超时处理 |
|
|
| 2026-04-08 | v1.0 | 初始设计文档 |
|
|
|
|
---
|
|
|
|
*文档版本: v2.0*
|
|
*最后更新: 2026-04-09*
|