# 游戏流程概述

## 📋 文档概述

本文档详细说明进贤麻将的完整游戏流程，包括：
- **状态机设计** - 游戏阶段转换规则
- **完整流程** - 从房间创建到游戏结束
- **各阶段详解** - 准备、发牌、出牌、结算等
- **时序关系** - 操作顺序和同步机制

**文档目标**：帮助开发者理解游戏的完整运行流程，掌握各阶段的处理逻辑和状态转换规则。

---

## 🎮 游戏流程总览

### 核心流程图

```
房间创建 → 玩家准备 → 开始游戏 → 游戏进行 → 局数结束 → 游戏结束
   ↓          ↓          ↓          ↓          ↓          ↓
创建房间    玩家加入    开战函数    状态机      计分结算    总结算
Export接口  玩家管理    makewar    WAITING→    单局结算    多局统计
配置解析    准备状态            DEALING→     精分计算    总分排名
                              PLAYING→
                              SETTLEMENT
```

### 流程阶段划分

| 阶段 | 主要功能 | 涉及模块 | 持续时间 |
|------|----------|----------|----------|
| **房间创建** | 创建游戏房间，解析配置 | Export.makewar, RoomAdapter | 即时 |
| **准备阶段** | 玩家加入，等待准备 | Import.prepare, GameController | 最长5分钟 |
| **发牌阶段** | 洗牌、发牌、开精 | MahjongWall, DiceService | 3-5秒 |
| **出牌阶段** | 玩家出牌、操作响应 | OperationManager, RpcHandler | 每局约5-10分钟 |
| **结算阶段** | 胡牌计分、精分结算 | ScoreCalculation, JingAlgorithm | 3-5秒 |
| **游戏结束** | 多局统计、排名 | GameController | 即时 |

---

## 🔄 游戏状态机

### 状态定义

进贤麻将使用严格的状态机控制游戏流程，确保操作的合法性和顺序性。

```javascript
// 游戏状态定义（GameStateManager.js）
GAME_PHASES: {
  WAITING: 'waiting',               // 等待状态：等待玩家准备
  DEALING: 'dealing',               // 发牌状态：洗牌、发牌、开精
  JING_DETERMINING: 'jing_determining',  // 确定精牌状态：掷骰子选精
  PLAYING: 'playing',               // 游戏进行状态：出牌、吃碰杠胡
  RESPONDING: 'responding',         // 响应状态：等待玩家操作响应
  ROUND_END: 'round_end',          // 局结束状态：单局结算
  GAME_END: 'game_end'             // 游戏结束状态：总结算
}
```

### 状态转换规则

```
┌─────────────────────────────────────────────────────────────┐
│                      游戏状态机流程图                         │
└─────────────────────────────────────────────────────────────┘

        ┌──────────┐
        │ WAITING  │  房间创建后的初始状态
        │  等待     │  所有玩家准备完毕→DEALING
        └────┬─────┘
             │ all_ready
             ↓
        ┌──────────┐
        │ DEALING  │  执行发牌流程
        │  发牌     │  发牌完成→JING_DETERMINING
        └────┬─────┘
             │ deal_complete
             ↓
     ┌───────────────────┐
     │JING_DETERMINING   │  掷骰子确定精牌
     │  确定精牌          │  精牌确定→PLAYING
     └────┬─────────────┘
          │ jing_determined
          ↓
        ┌──────────┐
   ┌───→│ PLAYING  │  玩家轮流出牌、操作
   │    │  游戏中   │  有玩家胡牌→ROUND_END
   │    └────┬─────┘  流局→ROUND_END
   │         │ win/draw
   │         ↓
   │    ┌──────────┐
   │    │ROUND_END │  单局结算、计分
   │    │ 局结束    │  继续下局→DEALING
   │    └────┬─────┘  所有局结束→GAME_END
   │         │
   │         ├─continue→ DEALING (下一局)
   │         │
   └─────────┘
             │ game_over
             ↓
        ┌──────────┐
        │GAME_END  │  游戏结束、总结算
        │ 游戏结束  │
        └──────────┘
```

### 状态转换函数

```javascript
/**
 * 状态转换核心方法
 * @param {Object} gameState - 游戏状态对象
 * @param {string} newPhase - 目标状态
 * @param {Object} transitionData - 转换数据
 * @returns {Object} 转换结果 {success, oldPhase, newPhase, errors}
 */
GameStateManager.transitionToPhase(gameState, newPhase, transitionData)

// 示例：从等待状态转换到发牌状态
var result = GameStateManager.transitionToPhase(
  gameState, 
  'dealing', 
  { reason: 'all_ready' }
);

if (result.success) {
  console.log('状态转换成功:', result.newPhase);
} else {
  console.error('状态转换失败:', result.errors);
}
```

---

## 📊 完整游戏流程

### 第一步：房间创建

**触发时机**：玩家在客户端点击"创建房间"

**执行流程**：

```javascript
// 1. 客户端发送创建房间请求
// youle_app.js → packet.js → mod.js

// 2. 框架调用export.makewar()
export.makewar = function(room, roomtype) {
  // 2.1 验证参数
  if (!room || !roomtype) {
    return { error: '参数无效' };
  }
  
  // 2.2 解析roomtype配置
  var config = RoomConfigUtils.parse(roomtype);
  
  // 2.3 创建游戏状态
  var gameState = GameStateManager.createGameState(
    room.roomcode,
    roomtype,
    room.getPlayerIds()
  );
  
  // 2.4 初始化游戏控制器
  var controller = new GameController(room, gameState);
  
  // 2.5 保存到room对象
  room.gameController = controller;
  room.gameState = gameState;
  
  return { success: true };
};
```

**关键点**：
- ✅ 解析房间配置（局数、规则、超时设置）
- ✅ 创建游戏状态对象（包含所有游戏数据）
- ✅ 初始化玩家状态（4个座位，即使不足4人）
- ✅ 设置初始状态为 `WAITING`

**相关文档**：
- [01-Export接口说明.md](../framework/01-Export接口说明.md#4-makewar-开战函数) - makewar接口详解
- [06-规则配置系统.md](../core/06-规则配置系统.md) - roomtype解析

---

### 第二步：准备阶段（WAITING）

**状态特征**：`phase = 'waiting'`

**主要任务**：
1. 等待玩家加入房间
2. 玩家点击准备
3. 全员准备后开始游戏

#### 2.1 玩家加入

```javascript
// 玩家加入房间
export.player_enter = function(room, player) {
  // 1. 分配座位号（0-3）
  var seat = room.findEmptySeat();
  player.seat = seat;
  
  // 2. 初始化玩家游戏信息
  player.gameinfo = {
    isprepare: 0,      // 准备状态：0-未准备，1-已准备
    score: 0,          // 当前分数
    totalScore: 0      // 累计分数
  };
  
  // 3. 广播玩家加入消息
  import.broadcastPlayerJoin(room, player);
  
  return { success: true };
};
```

#### 2.2 玩家准备

```javascript
// RPC: player_ready
RpcHandler.prototype.player_ready = function(pack, room, callback) {
  var playerId = pack.playerid;
  
  // 1. 设置准备状态
  var player = room.getPlayer(playerId);
  player.gameinfo.isprepare = 1;
  
  // 2. 检查是否全员准备
  var allReady = room.checkAllReady();
  
  // 3. 广播准备消息
  import.broadcastPlayerReady(room, playerId);
  
  // 4. 如果全员准备，开始游戏
  if (allReady) {
    this._startGame(room);
  }
  
  callback({ success: true, allReady: allReady });
};
```

#### 2.3 开始游戏

```javascript
RpcHandler.prototype._startGame = function(room) {
  var gameState = room.gameState;
  
  // 1. 状态转换：WAITING → DEALING
  var result = GameStateManager.transitionToPhase(
    gameState, 
    'dealing',
    { reason: 'all_ready' }
  );
  
  if (!result.success) {
    console.error('状态转换失败:', result.errors);
    return;
  }
  
  // 2. 确定首局庄家（通过掷骰子）
  var dealer = this._determineDealerBydice(room);
  
  // 3. 开始新局
  GameStateManager.startNewRound(gameState, dealer);
  
  // 4. 执行发牌流程
  this._dealCards(room);
};
```

**超时处理**：
- **准备超时**：默认5分钟（300秒）
- **超时后**：未准备玩家自动离开或托管

---

### 第三步：发牌阶段（DEALING）

**状态特征**：`phase = 'dealing'`

**主要任务**：
1. 洗牌（Shuffle）
2. 配牌（Deal）
3. 开精（Determine Jing）

#### 3.1 洗牌流程

```javascript
// MahjongWall.js - 洗牌
MahjongWall.prototype.shuffle = function() {
  // 1. 创建136张牌
  var allCards = this._createAllCards();  // [1m, 1m, 1m, 1m, 2m, ...]
  
  // 2. Fisher-Yates洗牌算法
  for (var i = allCards.length - 1; i > 0; i--) {
    var j = Math.floor(Math.random() * (i + 1));
    var temp = allCards[i];
    allCards[i] = allCards[j];
    allCards[j] = temp;
  }
  
  // 3. 转换为牌墩（17墩 × 4排 = 68墩 = 136张）
  this.wall = this._convertToWall(allCards);
  
  // 4. 标记洗牌完成
  this.shuffled = true;
  
  return allCards;
};
```

**洗牌增强系统（v5.0）**：
- 支持特定规则的洗牌干预
- 确保精牌分布的合理性
- 详见 [06-规则配置系统.md](../core/06-规则配置系统.md#洗牌增强系统)

#### 3.2 发牌流程

```javascript
// MahjongWall.js - 发牌
MahjongWall.prototype.dealCards = function(players, dealer) {
  var dealedCards = [];
  
  // 1. 确定开始位置（从庄家开始）
  var currentPlayer = dealer;
  
  // 2. 四家各发12张（每次4张，共3轮）
  for (var round = 0; round < 3; round++) {
    for (var i = 0; i < players.length; i++) {
      var player = players[currentPlayer];
      
      // 每次发4张
      for (var j = 0; j < 4; j++) {
        var card = this._drawCard();  // 从牌墙抓牌
        player.handCards.push(card);
        dealedCards.push({
          playerId: player.id,
          card: card,
          uniqueId: card.uniqueId
        });
      }
      
      currentPlayer = (currentPlayer + 1) % players.length;
    }
  }
  
  // 3. 四家各补1张（共4张）
  for (var i = 0; i < players.length; i++) {
    var player = players[currentPlayer];
    var card = this._drawCard();
    player.handCards.push(card);  // 现在每人13张
    dealedCards.push({
      playerId: player.id,
      card: card,
      uniqueId: card.uniqueId
    });
    
    currentPlayer = (currentPlayer + 1) % players.length;
  }
  
  // 4. 庄家再补1张（庄家14张，闲家13张）
  var dealerPlayer = players[dealer];
  var card = this._drawCard();
  dealerPlayer.handCards.push(card);
  dealedCards.push({
    playerId: dealerPlayer.id,
    card: card,
    uniqueId: card.uniqueId
  });
  
  return dealedCards;
};
```

**牌源信息标记**：
- 发牌时自动设置 `sourceInfo.sourceType = 'dealt'`
- 记录发牌轮次和座位信息
- 用于追踪牌的来源，支持调试和验证

#### 3.3 开精流程

```javascript
// DiceService.js - 掷骰子选精
DiceService.prototype.rollForJing = function(gameState) {
  // 1. 庄家掷两个骰子
  var dice1 = this._rollDice();  // 1-6
  var dice2 = this._rollDice();  // 1-6
  var total = dice1 + dice2;     // 2-12
  
  // 2. 从牌墙后往前数，定位精牌位置
  var jingPosition = this._locateJingPosition(total);
  
  // 3. 翻开精牌
  var jingCard = gameState.wall.getCardAt(jingPosition);
  
  // 4. 确定正精和副精
  var zhengJing = jingCard.code;          // 正精：翻开的牌
  var fuJing = this._getNextCard(zhengJing);  // 副精：正精+1
  
  // 5. 保存精牌信息
  gameState.jingInfo = {
    zhengJing: zhengJing,      // 正精（如：'5m'）
    fuJing: fuJing,            // 副精（如：'6m'）
    diceResult: { dice1: dice1, dice2: dice2, total: total },
    position: jingPosition,
    timestamp: Date.now()
  };
  
  // 6. 状态转换：DEALING → PLAYING
  GameStateManager.transitionToPhase(
    gameState, 
    'playing',
    { reason: 'jing_determined' }
  );
  
  return gameState.jingInfo;
};
```

**精牌规则**：
- **正精**：翻开的牌，每张计2分，可当万能牌
- **副精**：正精+1的牌，每张计1分，可当万能牌
- **循环规则**：9万→1万，北风→东风，白板→红中

**相关文档**：
- [05-共享代码模块.md](../core/05-共享代码模块.md#dicese rvice-掷骰子服务) - DiceService详解

---

### 第四步：出牌阶段（PLAYING）

**状态特征**：`phase = 'playing'`

**主要任务**：
1. 玩家轮流出牌
2. 其他玩家响应（吃碰杠胡）
3. 操作优先级处理
4. 超时托管

#### 4.1 出牌流程

```javascript
// RPC: player_discard
RpcHandler.prototype.player_discard = function(pack, room, callback) {
  var playerId = pack.playerid;
  var tileCode = pack.data.tile;  // 出的牌（如：'3m'）
  
  // 1. 验证操作合法性
  var validation = OperationManager.validateDiscard(
    room.gameState,
    playerId,
    tileCode
  );
  
  if (!validation.valid) {
    return callback({ error: validation.error });
  }
  
  // 2. 执行出牌
  var result = OperationManager.performDiscard(
    room.gameState,
    playerId,
    tileCode
  );
  
  // 3. 记录出牌操作
  GameStateManager.recordAction(room.gameState, {
    type: 'discard',
    playerId: playerId,
    tile: tileCode,
    timestamp: Date.now()
  });
  
  // 4. 广播出牌消息
  import.broadcastDiscard(room, playerId, tileCode);
  
  // 5. 检查其他玩家的响应（吃碰杠胡）
  var responses = OperationManager.checkResponses(
    room.gameState,
    tileCode
  );
  
  // 6. 如果有响应，等待操作
  if (responses.length > 0) {
    this._waitForResponses(room, responses, callback);
  } else {
    // 7. 无响应，下家摸牌
    this._nextPlayerDraw(room, callback);
  }
};
```

#### 4.2 操作响应流程

**操作优先级**（从高到低）：
1. **胡牌**（最高优先级，多人胡牌按下家优先）
2. **杠牌**（与胡牌平级，玩家可选择）
3. **碰牌**
4. **吃牌**（最低优先级，仅下家可吃）

```javascript
// OperationManager.js - 检查响应
OperationManager.prototype.checkResponses = function(gameState, discardedTile) {
  var responses = [];
  var currentPlayer = gameState.currentPlayer;
  
  // 1. 检查每个玩家的可用操作
  for (var i = 0; i < gameState.players.length; i++) {
    if (i === currentPlayer) continue;  // 跳过出牌者
    
    var player = gameState.players[i];
    var availableOps = [];
    
    // 1.1 检查胡牌
    if (this._canWin(player, discardedTile, gameState)) {
      availableOps.push({
        type: 'win',
        priority: 1,  // 最高优先级
        tile: discardedTile
      });
    }
    
    // 1.2 检查杠牌
    if (this._canKong(player, discardedTile)) {
      availableOps.push({
        type: 'kong',
        priority: 1,  // 与胡牌平级
        tile: discardedTile
      });
    }
    
    // 1.3 检查碰牌
    if (this._canPong(player, discardedTile)) {
      availableOps.push({
        type: 'pong',
        priority: 2,
        tile: discardedTile
      });
    }
    
    // 1.4 检查吃牌（仅下家）
    var nextPlayer = (currentPlayer + 1) % gameState.players.length;
    if (i === nextPlayer && this._canChow(player, discardedTile)) {
      availableOps.push({
        type: 'chow',
        priority: 3,  // 最低优先级
        tile: discardedTile,
        combinations: this._getChowCombinations(player, discardedTile)
      });
    }
    
    // 1.5 添加到响应列表
    if (availableOps.length > 0) {
      responses.push({
        playerId: player.id,
        seat: i,
        operations: availableOps,
        timeout: 5000  // 5秒操作时间
      });
    }
  }
  
  // 2. 按优先级排序
  responses.sort(function(a, b) {
    var aPriority = Math.min.apply(null, a.operations.map(function(op) { return op.priority; }));
    var bPriority = Math.min.apply(null, b.operations.map(function(op) { return op.priority; }));
    return aPriority - bPriority;
  });
  
  return responses;
};
```

#### 4.3 胡牌检测

```javascript
// WinDetectionFactory.js - 胡牌检测
WinDetectionFactory.detectWin = function(handTiles, jingInfo, gameState) {
  // 1. 基础验证
  if (!handTiles || handTiles.length % 3 !== 2) {
    return { canWin: false, reason: '手牌数量不符合胡牌要求' };
  }
  
  // 2. 检测所有可能的胡牌牌型
  var patterns = [];
  
  // 2.1 平胡检测
  var pinghuResult = this._checkPinghu(handTiles, jingInfo);
  if (pinghuResult.canWin) {
    patterns.push({
      type: 'pinghu',
      hasJing: pinghuResult.hasJing,
      baseScore: pinghuResult.hasJing ? 4 : 8,
      combinations: pinghuResult.combinations
    });
  }
  
  // 2.2 七对检测
  var qiduiResult = this._checkQidui(handTiles, jingInfo);
  if (qiduiResult.canWin) {
    patterns.push({
      type: 'qidui',
      hasJing: qiduiResult.hasJing,
      baseScore: qiduiResult.hasJing ? 8 : 64
    });
  }
  
  // 2.3 四碰检测
  var sipengResult = this._checkSipeng(handTiles, jingInfo);
  if (sipengResult.canWin) {
    patterns.push({
      type: 'sipeng',
      hasJing: sipengResult.hasJing,
      baseScore: sipengResult.hasJing ? 32 : 64
    });
  }
  
  // 2.4 十三烂检测
  var shisanlanResult = this._checkShisanlan(handTiles, jingInfo);
  if (shisanlanResult.canWin) {
    patterns.push({
      type: 'shisanlan',
      hasJing: shisanlanResult.hasJing,
      baseScore: shisanlanResult.hasJing ? 8 : 16
    });
  }
  
  // 2.5 七星十三烂检测
  var qixingshisanlanResult = this._checkQixingShisanlan(handTiles, jingInfo);
  if (qixingshisanlanResult.canWin) {
    patterns.push({
      type: 'qixing_shisanlan',
      hasJing: qixingshisanlanResult.hasJing,
      baseScore: qixingshisanlanResult.hasJing ? 32 : 64
    });
  }
  
  // 3. 返回检测结果
  if (patterns.length === 0) {
    return { canWin: false, reason: '未组成任何胡牌牌型' };
  }
  
  return {
    canWin: true,
    patterns: patterns,
    bestPattern: this._selectBestPattern(patterns)
  };
};
```

**胡牌检测算法详解**：
- 详见 [05-共享代码模块.md](../core/05-共享代码模块.md#windetectionfactory-胡牌检测工厂)
- 精牌万能牌处理：[进贤麻将规则手册.md](../../../../docs/important/game/进贤麻将规则手册.md#万能牌技术实现)

#### 4.4 操作超时处理

```javascript
// OperationManager.js - 操作超时
OperationManager.prototype._startOperationTimeout = function(gameState, playerId, timeout) {
  var self = this;
  var timerId = setTimeout(function() {
    // 1. 检查玩家是否已操作
    if (gameState.currentAction.playerId !== playerId) {
      return;  // 已经操作过了
    }
    
    // 2. 超时处理
    if (gameState.rules.gameplayOptions.kuaiban) {
      // 快版模式：自动托管
      self._autoPlay(gameState, playerId);
    } else {
      // 标准模式：等待玩家操作
      // 可以发送提醒消息
      import.sendTimeoutWarning(gameState.room, playerId);
    }
  }, timeout);
  
  // 3. 保存定时器ID
  gameState.currentAction.timerId = timerId;
  
  return timerId;
};
```

---

### 第五步：结算阶段（ROUND_END）

**状态特征**：`phase = 'round_end'`

**触发条件**：
1. 有玩家胡牌
2. 流局（剩余17墩牌）

#### 5.1 胡牌结算

```javascript
// ScoreCalculation.js - 胡牌计分
ScoreCalculation.calculateWinScore = function(winResult, gameState) {
  var scores = {
    baseScore: 0,      // 牌型基础分
    bonusScore: 0,     // 奖励分（无精+5、精钓+5等）
    jingScore: 0,      // 精分
    multiplier: 1,     // 倍数（冲关、杠开等）
    totalScore: 0      // 总分
  };
  
  // 1. 计算牌型基础分
  var pattern = winResult.bestPattern;
  scores.baseScore = pattern.baseScore;
  
  // 2. 计算奖励分
  if (!pattern.hasJing) {
    scores.bonusScore += 5;  // 无精奖励
  }
  
  if (winResult.isJingdiao) {
    scores.bonusScore += 5;  // 精钓奖励
  }
  
  if (winResult.isGangkai) {
    scores.multiplier *= 2;  // 杠开翻倍
  }
  
  // 3. 计算精分
  scores.jingScore = JingAlgorithm.calculateJingScore(
    gameState.players[winResult.winnerId].handCards,
    gameState.jingInfo
  );
  
  // 4. 检查冲关
  if (scores.jingScore >= 10) {
    var chongguanMultiplier = JingAlgorithm.calculateChongguan(scores.jingScore);
    scores.multiplier *= chongguanMultiplier;
  }
  
  // 5. 计算总分
  scores.totalScore = (scores.baseScore + scores.bonusScore) * scores.multiplier + scores.jingScore;
  
  return scores;
};
```

#### 5.2 分数分配

```javascript
// ScoreCalculation.js - 分数分配
ScoreCalculation.distributeScore = function(winResult, gameState) {
  var winner = winResult.winnerId;
  var loser = winResult.loserId;  // 放炮者，自摸时为null
  var isDealer = (winner === gameState.dealer);
  var isSelfDraw = (loser === null);
  
  var distribution = [];
  
  if (isSelfDraw) {
    // 自摸：所有其他玩家给分
    for (var i = 0; i < gameState.players.length; i++) {
      if (i === winner) continue;
      
      var score = this._calculatePayment(
        isDealer,
        i === gameState.dealer,
        winResult.totalScore
      );
      
      distribution.push({
        from: i,
        to: winner,
        amount: score
      });
    }
  } else {
    // 放炮
    if (isDealer) {
      // 庄家胡牌
      // 放炮者给全分，其他玩家给一半
      var fullScore = winResult.totalScore;
      var halfScore = Math.floor(fullScore / 2);
      
      distribution.push({
        from: loser,
        to: winner,
        amount: fullScore
      });
      
      for (var i = 0; i < gameState.players.length; i++) {
        if (i === winner || i === loser) continue;
        distribution.push({
          from: i,
          to: winner,
          amount: halfScore
        });
      }
    } else {
      // 闲家胡牌
      // 放炮者根据身份给分
      var loserIsDealer = (loser === gameState.dealer);
      var payment = this._calculatePayment(false, loserIsDealer, winResult.totalScore);
      
      distribution.push({
        from: loser,
        to: winner,
        amount: payment
      });
    }
  }
  
  // 应用分数变化
  distribution.forEach(function(transfer) {
    gameState.players[transfer.from].score -= transfer.amount;
    gameState.players[transfer.to].score += transfer.amount;
  });
  
  return distribution;
};
```

**计分规则详解**：
- 详见 [进贤麻将规则手册.md](../../../../docs/important/game/进贤麻将规则手册.md#胡牌计分)
- 不同身份、不同胡牌方式的计分差异

#### 5.3 局结束处理

```javascript
// GameController.js - 局结束
GameController.prototype.endRound = function(roundResult) {
  var gameState = this.gameState;
  
  // 1. 保存局结果
  gameState.history.rounds.push({
    roundNumber: gameState.currentRound,
    winner: roundResult.winnerId,
    pattern: roundResult.pattern,
    scores: roundResult.scores,
    distribution: roundResult.distribution,
    timestamp: Date.now()
  });
  
  // 2. 状态转换：PLAYING → ROUND_END
  GameStateManager.transitionToPhase(
    gameState,
    'round_end',
    { reason: 'win', winnerId: roundResult.winnerId }
  );
  
  // 3. 广播结算消息
  import.broadcastRoundEnd(this.room, roundResult);
  
  // 4. 检查游戏是否结束
  if (gameState.currentRound >= gameState.totalRounds) {
    this.endGame();
  } else {
    // 5. 准备下一局
    this.prepareNextRound();
  }
};
```

---

### 第六步：游戏结束（GAME_END）

**状态特征**：`phase = 'game_end'`

**触发条件**：所有局数完成

#### 6.1 游戏总结算

```javascript
// GameController.js - 游戏结束
GameController.prototype.endGame = function() {
  var gameState = this.gameState;
  
  // 1. 计算总分
  var finalScores = gameState.players.map(function(player) {
    return {
      playerId: player.id,
      totalScore: player.score,
      wins: player.statistics.wins,
      losses: player.statistics.losses
    };
  });
  
  // 2. 排名
  finalScores.sort(function(a, b) {
    return b.totalScore - a.totalScore;
  });
  
  // 3. 状态转换：ROUND_END → GAME_END
  GameStateManager.transitionToPhase(
    gameState,
    'game_end',
    { reason: 'all_rounds_complete' }
  );
  
  // 4. 广播游戏结束
  import.broadcastGameEnd(this.room, {
    finalScores: finalScores,
    totalRounds: gameState.totalRounds,
    duration: Date.now() - gameState.createTime
  });
  
  // 5. 保存游戏记录
  this._saveGameRecord(finalScores);
  
  // 6. 清理资源
  this._cleanup();
};
```

---

## ⏱️ 时序图

### 完整游戏时序图

```
客户端A    客户端B    客户端C    客户端D    服务器      GameController
   │          │          │          │          │              │
   ├─创建房间──────────────────────────────────>│              │
   │          │          │          │          ├─makewar────>│
   │          │          │          │          │<─成功───────┤
   │<─房间创建成功─────────────────────────────┤              │
   │          │          │          │          │              │
   │          ├─加入房间──────────────────────>│              │
   │          │          │          │          ├─player_enter>│
   │<─────────┴─玩家B加入─────────────────────┤              │
   │          │<─加入成功────────────────────┤              │
   │          │          │          │          │              │
   │          │          ├─加入房间──────────>│              │
   │<─────────┴──────────┴─玩家C加入─────────┤              │
   │          │          │<─加入成功──────────┤              │
   │          │          │          │          │              │
   │─准备────────────────────────────────────>│              │
   │          │─准备────────────────────────>│              │
   │          │          │─准备────────────>│              │
   │          │          │          │          │              │
   │          │          │          │          ├─全员准备────>│
   │          │          │          │          │              ├─开始游戏
   │          │          │          │          │              ├─洗牌
   │          │          │          │          │              ├─发牌
   │          │          │          │          │              ├─开精
   │<─────────┴──────────┴──────────发牌完成─┤              │
   │          │          │          │          │              │
   │─出牌(3m)────────────────────────────────>│              │
   │          │          │          │          ├─检查响应────>│
   │          │<─────────┴──────────可碰/可胡─┤              │
   │          │─碰牌────────────────────────>│              │
   │          │          │          │          │              ├─执行碰牌
   │<─────────┴──────────┴──────────玩家B碰牌┤              │
   │          │          │          │          │              │
   │          │─出牌(5m)────────────────────>│              │
   │          │          │          │          ├─检查响应────>│
   │<─────────┴──────────┴──────────无响应───┤              │
   │          │          │          │          │              ├─下家摸牌
   │          │          │<─────────轮到玩家C─┤              │
   │          │          │          │          │              │
   ...（出牌循环）...
   │          │          │          │          │              │
   │─出牌(8m)────────────────────────────────>│              │
   │          │<─────────┴──────────可胡──────┤              │
   │          │─胡牌────────────────────────>│              │
   │          │          │          │          ├─胡牌检测────>│
   │          │          │          │          ├─计算分数────>│
   │<─────────┴──────────┴──────────结算结果─┤              │
   │          │          │          │          │              │
   │<─────────┴──────────┴──────────准备下局─┤              │
   │          │          │          │          │              ├─开始新局
   ...（继续下一局）...
   │          │          │          │          │              │
   │<─────────┴──────────┴──────────游戏结束─┤              │
   │          │          │          │          │              │
```

### 单局流程时序

```
[准备阶段]      [发牌阶段]      [游戏阶段]      [结算阶段]
    │               │               │               │
    ├─玩家加入      │               │               │
    ├─玩家准备      │               │               │
    ├─全员就绪      │               │               │
    │               │               │               │
    │  状态转换:    │               │               │
    │  WAITING →    │               │               │
    │    DEALING    │               │               │
    │               ├─洗牌          │               │
    │               ├─发牌          │               │
    │               ├─开精          │               │
    │               │               │               │
    │               │  状态转换:    │               │
    │               │  DEALING →    │               │
    │               │    PLAYING    │               │
    │               │               ├─庄家出牌      │
    │               │               ├─其他玩家响应  │
    │               │               ├─下家摸牌      │
    │               │               ├─继续出牌      │
    │               │               ├─...循环...    │
    │               │               ├─胡牌/流局     │
    │               │               │               │
    │               │               │  状态转换:    │
    │               │               │  PLAYING →    │
    │               │               │  ROUND_END    │
    │               │               │               ├─计算分数
    │               │               │               ├─分配分数
    │               │               │               ├─广播结果
    │               │               │               ├─检查游戏结束
    │               │               │               │
    └───────────────┴───────────────┴───────────────┘
```

---

## 🔧 关键技术点

### 1. 状态同步机制

```javascript
// Import.js - 广播消息
import.broadcastGameState = function(room, updateType, data) {
  // 1. 构建消息包
  var message = {
    cmd: 'game_state_update',
    type: updateType,
    data: data,
    timestamp: Date.now()
  };
  
  // 2. 发送给所有玩家
  room.players.forEach(function(player) {
    import.sendToPlayer(player, message);
  });
};
```

**同步时机**：
- 玩家加入/离开
- 状态转换
- 玩家操作（出牌、吃碰杠胡）
- 分数变化
- 局结束/游戏结束

### 2. 断线重连

```javascript
// Export.js - 断线重连
export.get_deskinfo = function(room, player) {
  var gameState = room.gameState;
  
  // 1. 构建完整游戏信息
  var deskInfo = {
    phase: gameState.phase,
    currentRound: gameState.currentRound,
    totalRounds: gameState.totalRounds,
    currentPlayer: gameState.currentPlayer,
    dealer: gameState.dealer,
    
    // 2. 玩家信息
    players: gameState.players.map(function(p) {
      return {
        id: p.id,
        seat: p.seat,
        score: p.score,
        handCount: p.id === player.id ? p.handCards.length : null,  // 只返回自己的手牌数
        discards: p.discards.map(function(c) { return c.code; })
      };
    }),
    
    // 3. 玩家自己的手牌
    myHandCards: this._getPlayerHandCards(gameState, player.id),
    
    // 4. 精牌信息
    jingInfo: gameState.jingInfo,
    
    // 5. 当前操作
    currentAction: gameState.currentAction
  };
  
  return deskInfo;
};
```

### 3. 操作队列管理

```javascript
// OperationManager.js - 操作队列
OperationManager.prototype.queueOperation = function(operation) {
  // 1. 添加到队列
  this.operationQueue.push(operation);
  
  // 2. 如果当前没有操作在执行，开始执行
  if (!this.isProcessing) {
    this.processQueue();
  }
};

OperationManager.prototype.processQueue = function() {
  if (this.operationQueue.length === 0) {
    this.isProcessing = false;
    return;
  }
  
  this.isProcessing = true;
  var operation = this.operationQueue.shift();
  
  // 执行操作
  this.executeOperation(operation, function(error, result) {
    if (error) {
      console.error('操作执行失败:', error);
    }
    
    // 继续处理队列
    this.processQueue();
  }.bind(this));
};
```

---

## 📚 相关文档链接

- **上一篇**：[07-工具模块.md](../development/07-工具模块.md) - 日志和错误处理
- **下一篇**：[09-代码框架总结.md](09-代码框架总结.md) - 整体架构总结
- **参考**：
  - [01-Export接口说明.md](../framework/01-Export接口说明.md) - Export接口详解
  - [03-RPC处理机制.md](../framework/03-RPC处理机制.md) - RPC路由机制
  - [04-游戏核心服务.md](../core/04-游戏核心服务.md) - 核心服务类
  - [05-共享代码模块.md](../core/05-共享代码模块.md) - 算法详解
  - [进贤麻将规则手册.md](../../../../docs/important/game/进贤麻将规则手册.md) - 游戏规则

---

## 📝 附录

### A. 游戏阶段常量

```javascript
// GameConstants.js
GAME_PHASES: {
  WAITING: 'waiting',
  DEALING: 'dealing',
  JING_DETERMINING: 'jing_determining',
  PLAYING: 'playing',
  RESPONDING: 'responding',
  ROUND_END: 'round_end',
  GAME_END: 'game_end'
}
```

### B. 操作类型常量

```javascript
// GameConstants.js
OPERATION_TYPES: {
  DISCARD: 'discard',      // 出牌
  DRAW: 'draw',            // 摸牌
  CHOW: 'chow',            // 吃牌
  PONG: 'pong',            // 碰牌
  KONG: 'kong',            // 杠牌
  WIN: 'win',              // 胡牌
  PASS: 'pass'             // 过
}
```

### C. 超时设置

```javascript
// RoomConstants.js
TIMEOUTS: {
  READY: 300000,           // 准备超时：5分钟
  DISCARD: 30000,          // 出牌超时：30秒
  RESPONSE: 5000,          // 响应超时：5秒
  FAST_MODE_DISCARD: 15000,// 快版出牌：15秒
  FAST_MODE_RESPONSE: 3000 // 快版响应：3秒
}
```

### D. 常见问题

**Q1: 游戏状态转换失败怎么处理？**

A: 检查转换规则是否合法，使用 `GameStateManager.validateStateTransition()` 验证。

**Q2: 断线重连后手牌数据不完整？**

A: 确保 `export.get_deskinfo()` 正确返回玩家手牌信息，检查数据序列化。

**Q3: 操作超时没有自动处理？**

A: 检查 `gameState.rules.gameplayOptions.kuaiban` 配置，确保快版模式正确启用。

**Q4: 多人同时胡牌如何处理？**

A: 按下家优先原则，使用 `OperationManager.resolveMultipleWins()` 解决冲突。

---

**文档版本**：v1.0  
**最后更新**：2025年10月15日  
**维护者**：进贤麻将开发团队