# Net-Games 网游系统架构文档

> **版本**: v2.0  
> **更新日期**: 2026-04-09  
> **状态**: 生产就绪

---

## 1. 系统概述

### 1.1 项目定位
基于 **Flask-SocketIO** 的多人实时棋牌游戏引擎，支持人类玩家与 AI 玩家对战。采用权威服务端架构，所有游戏逻辑在服务端验证执行。

### 1.2 核心特性
- ✅ 权威服务端架构（防作弊）
- ✅ 用户认证系统（登录/注册/积分）
- ✅ 多角色支持：人类、规则AI、DeepSeek大模型AI
- ✅ 房间制对战（2-3人）
- ✅ AI托管机制（断线/超时自动托管）
- ✅ 回合超时管理（30秒/回合）
- ✅ 断线重连支持
- ✅ 单点登录控制
- ✅ 可扩展的游戏插件机制

### 1.3 技术栈
| 层级 | 技术 | 说明 |
|------|------|------|
| 服务端 | Python 3.11 + Flask | Web框架 |
| 实时通信 | Flask-SocketIO | WebSocket封装 |
| 数据库 | SQLite | 用户认证、积分存储 |
| 前端 | 原生HTML/JS/CSS | 无需构建 |
| AI接口 | DeepSeek API | 大模型决策 |
| 部署 | Systemd | 系统服务 |

---

## 2. 目录结构

```
/home/ubuntu/nanocode/net-games/
├── server.py                 # 主服务入口 (1772行)
├── config.py                 # 全局配置
├── net_games_auth.db         # SQLite数据库
│
├── engine/                   # 游戏引擎核心
│   ├── __init__.py
│   ├── room_manager.py       # 房间管理器 (391行)
│   ├── game_base.py          # 游戏基类 (236行)
│   ├── player.py             # 玩家抽象 (154行)
│   ├── ai_adapter.py         # AI适配器基类
│   └── test_game.py          # 测试游戏
│
├── doudizhu/                 # 斗地主游戏实现
│   ├── __init__.py
│   ├── game.py               # 斗地主游戏逻辑 (470行)
│   ├── game_logic.py         # 牌型判断、规则
│   └── ai_adapters.py        # 斗地主AI适配器 (443行)
│
├── chinese-chess/            # 中国象棋（预留）
│   └── ...
│
├── client/                   # 斗地主客户端
│   ├── index.html
│   ├── style.css
│   └── game.js               # 前端逻辑 (1617行)
│
├── hub/                      # 游戏大厅
│   └── index.html
│
├── docs/                     # 文档
│   ├── ARCHITECTURE.md       # 本文件
│   ├── API.md                # API接口文档
│   ├── DATABASE.md           # 数据库设计
│   ├── UI_DESIGN_GUIDELINES.md # UI设计规范
│   └── PHASE1_SUMMARY.md     # 阶段总结
│
└── instance/                 # 数据目录
    └── net_games_auth.db
```

---

## 3. 系统架构

### 3.1 整体架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                          客户端层                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │  浏览器玩家  │  │  浏览器玩家  │  │  AI玩家     │             │
│  │  (Socket.IO)│  │  (Socket.IO)│  │  (内部调用)  │             │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘             │
└─────────┼────────────────┼────────────────┼────────────────────┘
          │                │                │
          └────────────────┴────────────────┘
                           │ WebSocket (Socket.IO)
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                         服务层 (Flask)                            │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    HTTP Routes                          │    │
│  │  /api/auth/*  /api/user/*  /api/rooms/*  /api/admin/*   │    │
│  └─────────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                   Socket.IO Handlers                    │    │
│  │  connect  create_room  join_room  game_action  ...      │    │
│  └─────────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                   RoomManager (单例)                     │    │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐                │    │
│  │  │ Room #1 │  │ Room #2 │  │ Room #N │                │    │
│  │  │ 斗地主   │  │ 斗地主   │  │ 象棋    │                │    │
│  │  │ 3玩家   │  │ 2玩家   │  │ 2玩家   │                │    │
│  │  └────┬────┘  └────┬────┘  └────┬────┘                │    │
│  └───────┼────────────┼────────────┼───────────────────────┘    │
│          │            │            │                            │
│          ▼            ▼            ▼                            │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                   Game Instances                        │    │
│  │  ┌──────────────┐  ┌──────────────┐                    │    │
│  │  │ DoudizhuGame │  │ TestGame     │  ...               │    │
│  │  │ - game logic │  │ - game logic │                    │    │
│  │  │ - state mgmt │  │ - state mgmt │                    │    │
│  │  └──────┬───────┘  └──────────────┘                    │    │
│  └─────────┼───────────────────────────────────────────────┘    │
│            │                                                    │
│            ▼                                                    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                   AI Adapter Center                     │    │
│  │  ┌──────────┐  ┌──────────────┐  ┌──────────────┐      │    │
│  │  │ RuleAI   │  │ DeepSeekAI   │  │ MinimaxAI    │      │    │
│  │  │ (斗地主)  │  │ (通用)        │  │ (象棋预留)    │      │    │
│  │  └──────────┘  └──────────────┘  └──────────────┘      │    │
│  └─────────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                   Database (SQLite)                     │    │
│  │  ┌─────────┐  ┌─────────┐                             │    │
│  │  │ users   │  │ rooms   │  (内存缓存)                   │    │
│  │  └─────────┘  └─────────┘                             │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
```


### 3.2 核心组件职责

| 组件 | 文件 | 职责 |
|------|------|------|
| **Flask App** | `server.py` | HTTP服务、Socket.IO、认证、API路由 |
| **RoomManager** | `engine/room_manager.py` | 单例模式管理所有房间生命周期 |
| **Room** | `engine/room_manager.py` | 房间状态、玩家管理、游戏实例容器 |
| **GameBase** | `engine/game_base.py` | 游戏抽象基类，定义通用接口 |
| **Player** | `engine/player.py` | 玩家基类，HumanPlayer/AIPlayer |
| **AIAdapter** | `engine/ai_adapter.py` | AI决策接口统一封装 |
| **DoudizhuGame** | `doudizhu/game.py` | 斗地主具体实现 |

### 3.3 关键数据流

#### 3.3.1 游戏操作处理流程
```
┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  Client  │     │  Server  │     │   Room   │     │   Game   │
└────┬─────┘     └────┬─────┘     └────┬─────┘     └────┬─────┘
     │                │                │                │
     │ game_action    │                │                │
     │ ──────────────>│                │                │
     │                │ handle_game_action              │
     │                │ ──────────────────────────────>│
     │                │                │                │
     │                │                │ game.handle_action()
     │                │                │                │
     │                │                │                │
     │                │                │ 验证操作合法性   │
     │                │                │ 更新游戏状态     │
     │                │                │                │
     │                │ state_update   │                │
     │ <──────────────│ (broadcast)    │                │
     │                │                │                │
     │                │ check_winner() │                │
     │                │ ──────────────────────────────>│
     │                │                │                │
     │  game_ended    │                │                │
     │ <──────────────│ (broadcast)    │                │
```

#### 3.3.2 AI决策流程
```
┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  Game    │     │  Server  │     │ AI Thread│     │ AIAdapter│
└────┬─────┘     └────┬─────┘     └────┬─────┘     └────┬─────┘
     │                │                │                │
     │ get_current_player()            │                │
     │ ───────────────────────────────>│                │
     │                │                │                │
     │                │ process_ai_turn│                │
     │                │ ──────────────>│                │
     │                │                │ make_decision()│
     │                │                │ ──────────────>│
     │                │                │                │
     │                │                │  异步API调用   │
     │                │                │ (DeepSeek)     │
     │                │                │ <──────────────│
     │                │                │                │
     │                │                │ handle_action()│
     │                │                │ ──────────────>│
     │                │ state_update   │                │
     │                │ (broadcast)    │                │
```

---

## 4. 核心类设计

### 4.1 RoomManager (单例模式)
```python
class RoomManager:
    _instance = None
    _lock = Lock()
    
    def __new__(cls):
        # 线程安全的单例
        
    def create_room(game_type, max_players, config)
    def join_room(room_code, player) -> (bool, str)
    def start_game(room_id) -> (bool, str)
    def get_room(room_id=None, room_code=None) -> Room
    def cleanup_inactive_rooms(max_inactive_minutes=30)
```

### 4.2 Room 类
```python
class Room:
    id: str           # room_uuid
    code: str         # A1B2C3 (6位房间号)
    game_type: str    # doudizhu
    status: str       # waiting/playing/ended/closed
    
    players: Dict[str, Player]
    seats: Dict[int, Optional[str]]
    host_id: Optional[str]
    game: Optional[GameBase]
    
    def add_player(player) -> bool
    def remove_player(player_id) -> bool
    def start_game(game_class) -> bool
    def to_dict(include_game_state=True) -> dict
```

### 4.3 GameBase 抽象基类
```python
class GameBase(ABC):
    room_id: str
    game_type: str
    state: GameState
    players: Dict[str, Player]
    player_order: List[str]
    
    @abstractmethod
    def handle_action(player_id, action, data) -> dict
    @abstractmethod
    def get_valid_actions(player_id) -> List[str]
    @abstractmethod
    def check_winner() -> Optional[str]
    
    def to_dict() -> dict
```

### 4.4 Player 类层次
```python
class Player(ABC):
    id: str
    name: str
    type: PlayerType
    is_connected: bool
    is_ai_controlled: bool  # AI托管状态
    offline_since: Optional[float]
    
    def connect(socket_id)
    def disconnect()
    def enable_ai_control()
    def disable_ai_control()

class HumanPlayer(Player):
    @property
    def is_ai(self) -> False

class AIPlayer(Player):
    ai_type: str  # rule/deepseek/minimax
    @property
    def is_ai(self) -> True
```


---

## 5. 关键机制

### 5.1 单点登录与身份识别

```python
# 使用用户名或昵称作为身份标识
identity_key = current_user.username if current_user.is_authenticated else player_name

# 活跃玩家映射
active_usernames: Dict[str, str] = {}  # username -> player_id

# 用户-房间映射（支持跨浏览器重连）
user_room_map: Dict[str, str] = {}  # username -> room_id

# Socket-玩家映射
socket_player_map: Dict[str, str] = {}  # socket_id -> player_id
```

**单点登录检查流程:**
1. 创建房间/加入房间时检查 `identity_key` 是否在 `active_usernames`
2. 如果存在且玩家在线，拒绝新连接
3. 如果存在但玩家离线，允许重连并替换
4. 断开连接时从 `active_usernames` 移除

### 5.2 AI托管机制

**触发条件:**
1. 玩家主动断开连接（关闭浏览器）→ 30秒后自动托管
2. 回合超时（30秒无操作）→ 累计3次后自动托管
3. 玩家主动点击"托管"按钮

**托管流程:**
```python
def ai_control_after_timeout(room_id, player_id, timeout=30):
    time.sleep(timeout)
    if player.offline_since is None:
        return  # 已重连，取消托管
    
    player.enable_ai_control()
    # 通知所有玩家
    emit('player_ai_controlled', {...})
    
    # 如果是当前回合，立即触发AI
    if current_turn == player_id:
        check_and_trigger_ai(room_id)
```

**取消托管:**
- 玩家重连时自动取消托管
- 玩家手动点击"取消托管"

### 5.3 回合超时管理

```python
# 配置
TURN_TIMEOUT_SECONDS = 30  # 每回合30秒
MAX_TIMEOUT_COUNT = 3      # 最大超时3次

# 定时器管理
room_turn_timers: Dict[str, Timer] = {}  # room_id -> Timer
player_timeout_count: Dict[str, int] = {}  # player_id -> count

def start_turn_timer(room_id):
    cancel_turn_timer(room_id)
    timer = threading.Timer(TURN_TIMEOUT_SECONDS, handle_turn_timeout, args=[room_id])
    room_turn_timers[room_id] = timer

def handle_turn_timeout(room_id):
    player_timeout_count[player_id] += 1
    
    if timeout_count >= MAX_TIMEOUT_COUNT:
        player.enable_ai_control()  # 启用托管
    else:
        _execute_auto_pass(room, game, player_id)  # 自动不要
```

### 5.4 断线重连机制

**重连匹配优先级:**
1. 已登录用户通过 `username` 匹配
2. 通过 `player_id` 匹配（保存在localStorage）
3. 通过 `player_name` 匹配（已断开状态的玩家）

**重连流程:**
```
1. 客户端尝试 reconnect_room
2. 服务端通过 user_room_map 或 player_name 查找原玩家
3. 单点登录检查（确保没有其他活跃连接）
4. player.connect(new_socket_id) - 更新连接状态
5. player.disable_ai_control() - 取消托管
6. 加入 Socket.IO room
7. 广播 player_reconnected 事件
8. 恢复游戏状态
```

### 5.5 房间清理策略

```python
def cleanup_inactive_rooms(max_inactive_minutes=30):
    for room in rooms:
        all_disconnected = all(not p.is_connected for p in room.human_players)
        inactive_time = now - room.last_activity
        
        if all_disconnected:
            if room.status == 'ended' and inactive_time > 5*60:
                cleanup_room(room)  # 已结束，5分钟后清理
            elif inactive_time > 10*60:
                cleanup_room(room)  # 进行中，10分钟后清理
        elif inactive_time > max_inactive_minutes*60:
            cleanup_room(room)  # 不活跃，30分钟后清理
```

清理任务每5分钟运行一次（后台线程）。

---

## 6. 游戏扩展机制

### 6.1 添加新游戏的步骤

1. **创建游戏目录**
```
newgame/
├── __init__.py
├── game.py          # 继承 GameBase
├── game_logic.py    # 游戏规则
└── ai_adapters.py   # AI适配器
```

2. **实现 GameBase 子类**
```python
class NewGame(GameBase):
    @property
    def min_players(self) -> int: return 2
    
    @property
    def max_players(self) -> int: return 2
    
    def handle_action(self, player_id, action, data) -> dict:
        # 实现游戏逻辑
        pass
    
    def check_winner(self) -> Optional[str]:
        # 检查获胜者
        pass
```

3. **注册游戏类型** (server.py)
```python
from newgame import NewGame
room_manager.register_game('newgame', NewGame)
```

### 6.2 AI适配器接口

```python
class AIAdapter(ABC):
    @abstractmethod
    async def make_decision(self, game_state, available_actions, player_context):
        return {
            "action": "play",
            "data": {"card_ids": [...]},
            "reasoning": "决策理由"
        }
```


---

## 7. 部署与运维

### 7.1 服务配置
```ini
# /etc/systemd/system/net-games.service
[Unit]
Description=Net-Games Server
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/nanocode/net-games
Environment=NET_GAMES_HOST=0.0.0.0
Environment=NET_GAMES_PORT=8900
Environment=NET_GAMES_DEBUG=false
Environment=DEEPSEEK_API_KEY=xxx
ExecStart=/usr/bin/python3 /home/ubuntu/nanocode/net-games/server.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

### 7.2 端口规划
| 服务 | 端口 | 说明 |
|------|------|------|
| Net-Games | 8900 | 网游系统（本服务）|
| Happy-Games | 8895 | 单机小游戏 |
| Personal-Blog | 8888/8889 | 博客系统 |

### 7.3 监控指标
- 在线房间数 (`/api/stats`)
- 在线玩家数
- AI调用次数/成本
- 平均游戏时长

---

## 8. 安全设计

### 8.1 认证安全
- 密码使用 werkzeug 哈希存储
- Session cookie 设置 HttpOnly, SameSite
- Flask-Login 管理登录状态

### 8.2 游戏安全
- 权威服务端：所有操作服务端验证
- 客户端仅展示，不执行游戏逻辑
- AI API Key 仅在服务端使用

### 8.3 防作弊
- 牌面仅发送给对应玩家（player_view）
- 操作合法性服务端验证
- 单点登录防止多开

---

## 9. 更新日志

| 日期 | 版本 | 变更内容 |
|------|------|----------|
| 2026-04-09 | v2.0 | 更新为实际实现版本，添加认证系统、AI托管、超时管理、断线重连 |
| 2026-04-08 | v1.0 | 初始设计文档，基础架构设计 |

---

## 10. 参考文档

- [API.md](./API.md) - 详细接口文档
- [DATABASE.md](./DATABASE.md) - 数据库设计
- [UI_DESIGN_GUIDELINES.md](./UI_DESIGN_GUIDELINES.md) - UI设计规范

---

*文档版本: v2.0*  
*最后更新: 2026-04-09*  
*维护者: 开发团队*