# 工具模块详解

## 📋 文档概述

本文档详细说明进贤麻将的工具模块系统，包括：
- **Logger.js** - 日志管理器
- **ErrorHandler.js** - 错误处理器  
- **shared/utils** - 共享工具类
- 工具模块的使用方法和最佳实践

**文档目标**：帮助开发者正确使用日志系统和错误处理机制，提升代码质量和可维护性。

---

## 🎯 工具模块架构

### 系统组成

```
工具模块系统
├── utils/                    # 子游戏专用工具
│   ├── Logger.js            # 日志管理器
│   └── ErrorHandler.js      # 错误处理器
│
└── shared/utils/            # 前后端共享工具
    ├── ArrayUtils.js        # 数组操作工具
    ├── CardSourceInfoHelper.js     # 牌源信息辅助
    ├── GameContextHelper.js        # 游戏上下文辅助
    ├── GameStateHelper.js          # 游戏状态辅助
    ├── MahjongCardUniqueId.js      # 麻将牌唯一ID
    └── RoomConfigUtils.js          # 房间配置工具
```

### 设计原则

1. **分离关注点**：日志和错误处理分开管理
2. **ES5兼容**：兼容浏览器和Node.js环境
3. **统一接口**：提供统一的API调用方式
4. **性能优化**：最小化性能开销
5. **易于使用**：简单直观的API设计

---

## 📝 Logger.js - 日志管理器

### 核心功能

**文件位置**：`server/games2/jinxianmahjong/utils/Logger.js`  
**版本**：v1.0.0  
**总行数**：606行

Logger提供了完整的日志管理功能：
- ✅ 6级日志系统（TRACE/DEBUG/INFO/WARN/ERROR/FATAL）
- ✅ 日志格式化和美化输出
- ✅ 日志历史记录和查询
- ✅ 日志统计分析
- ✅ 性能计时功能
- ✅ 分组日志输出
- ✅ 控制台颜色支持

### 日志级别定义

```javascript
LOG_LEVELS: {
  TRACE: 0,       // 最详细的信息，用于跟踪程序执行
  DEBUG: 1,       // 调试信息，开发时使用
  INFO: 2,        // 一般信息，记录程序运行状态
  WARN: 3,        // 警告信息，可能的问题
  ERROR: 4,       // 错误信息，程序运行错误
  FATAL: 5        // 致命错误，程序无法继续运行
}
```

**级别控制**：只有 `>= currentLevel` 的日志才会输出

**颜色编码**：
| 级别 | 颜色 | 说明 |
|------|------|------|
| TRACE | 白色 | 详细跟踪信息 |
| DEBUG | 青色 | 开发调试信息 |
| INFO | 绿色 | 正常运行信息 |
| WARN | 黄色 | 警告提示信息 |
| ERROR | 红色 | 错误异常信息 |
| FATAL | 紫色 | 致命错误信息 |

### 配置参数

```javascript
config: {
  // 当前日志级别
  currentLevel: 1,            // 默认DEBUG级别
  
  // 输出设置
  enableConsole: true,        // 启用控制台输出
  enableColors: true,         // 启用颜色（如果支持）
  enableTimestamp: true,      // 启用时间戳
  enableModuleName: true,     // 启用模块名
  enableStackTrace: false,    // 启用堆栈跟踪（ERROR级别以上）
  
  // 格式设置
  timestampFormat: 'ISO',     // 时间戳格式: 'ISO', 'LOCAL', 'TIMESTAMP'
  moduleName: 'JinXianMahjong', // 模块名
  
  // 性能设置
  maxLogHistory: 1000,        // 最大日志历史记录数
  flushInterval: 0            // 刷新间隔（毫秒，0表示立即输出）
}
```

### 核心API

#### 1. 设置日志级别

```javascript
/**
 * 设置日志级别
 * @param {number|string} level - 日志级别（数字或字符串）
 */
Logger.setLevel(level)

// 使用示例
Logger.setLevel('DEBUG');     // 使用字符串
Logger.setLevel(1);           // 使用数字
Logger.setLevel('INFO');      // 只输出INFO及以上级别
```

#### 2. 记录日志

**基础日志方法**：

```javascript
/**
 * 记录日志
 * @param {string} tag - 标签（模块/功能名称）
 * @param {string} message - 日志消息
 * @param {Object} data - 附加数据（可选）
 */
Logger.trace(tag, message, data)
Logger.debug(tag, message, data)
Logger.info(tag, message, data)
Logger.warn(tag, message, data)
Logger.error(tag, message, data)
Logger.fatal(tag, message, data)
```

**使用示例**：

```javascript
// 基础日志
Logger.info('GameController', '游戏开始');

// 带附加数据的日志
Logger.debug('MahjongService', '发牌完成', {
  playerCount: 4,
  tilesPerPlayer: 13
});

// 警告日志
Logger.warn('OperationManager', '玩家操作超时', {
  playerId: 'player001',
  operation: 'discard',
  timeout: 15000
});

// 错误日志
Logger.error('RpcHandler', 'RPC调用失败', {
  method: 'player_discard',
  errorCode: 2001,
  error: error.message
});

// 致命错误
Logger.fatal('System', '系统初始化失败', {
  reason: '依赖模块加载失败'
});
```

#### 3. 分组日志

```javascript
/**
 * 分组日志（用于组织相关日志）
 */
Logger.group(groupName)         // 开始分组
Logger.groupEnd()                // 结束分组
Logger.groupCollapsed(groupName) // 开始折叠分组（默认折叠）

// 使用示例
Logger.group('游戏初始化');
  Logger.info('Init', '加载配置');
  Logger.info('Init', '创建游戏状态');
  Logger.info('Init', '初始化牌墙');
Logger.groupEnd();
```

#### 4. 性能计时

```javascript
/**
 * 性能计时
 */
Logger.time(label)      // 开始计时
Logger.timeEnd(label)   // 结束计时并输出

// 使用示例
Logger.time('胡牌检测');
var result = WinDetectionFactory.detectWin(handTiles, jingInfo);
Logger.timeEnd('胡牌检测');  // 输出: 胡牌检测: 3.142ms
```

#### 5. 表格输出

```javascript
/**
 * 表格输出（用于输出结构化数据）
 * @param {Array|Object} data - 表格数据
 */
Logger.table(data)

// 使用示例
var players = [
  { id: 'p1', name: '玩家1', score: 100 },
  { id: 'p2', name: '玩家2', score: 50 },
  { id: 'p3', name: '玩家3', score: -30 },
  { id: 'p4', name: '玩家4', score: -20 }
];
Logger.table(players);
```

#### 6. 日志历史

```javascript
/**
 * 获取日志历史
 * @param {number} limit - 返回数量限制（可选）
 * @param {number} level - 过滤日志级别（可选）
 * @returns {Array} 日志历史数组
 */
Logger.getHistory(limit, level)

// 使用示例
var allLogs = Logger.getHistory();           // 获取所有日志
var last100 = Logger.getHistory(100);        // 获取最近100条
var errors = Logger.getHistory(null, Logger.LOG_LEVELS.ERROR); // 只获取错误日志
```

#### 7. 清空历史

```javascript
/**
 * 清空日志历史
 */
Logger.clearHistory()
```

#### 8. 日志统计

```javascript
/**
 * 获取日志统计信息
 * @returns {Object} 统计对象
 */
Logger.getStatistics()

// 返回示例
{
  total: 1523,              // 总日志数
  byLevel: {                // 按级别统计
    0: 234,                 // TRACE
    1: 567,                 // DEBUG
    2: 456,                 // INFO
    3: 123,                 // WARN
    4: 89,                  // ERROR
    5: 54                   // FATAL
  },
  startTime: 1697376000000, // 统计开始时间
  duration: 3600000,        // 运行时长（毫秒）
  rate: 0.42                // 日志频率（条/秒）
}
```

#### 9. 重置统计

```javascript
/**
 * 重置日志统计
 */
Logger.resetStatistics()
```

#### 10. 配置管理

```javascript
/**
 * 配置Logger
 * @param {Object} options - 配置选项
 */
Logger.configure(options)

// 使用示例
Logger.configure({
  currentLevel: Logger.LOG_LEVELS.INFO,  // 设置为INFO级别
  enableTimestamp: true,                 // 启用时间戳
  enableColors: true,                    // 启用颜色
  timestampFormat: 'ISO',                // 使用ISO格式
  maxLogHistory: 500                     // 最多保存500条历史
});
```

### 日志格式

**标准格式**：
```
[时间戳] [级别] [模块名:标签] 消息内容
```

**输出示例**：
```
[2025-10-15T10:30:45.123Z] [INFO] [JinXianMahjong:GameController] 游戏开始
[2025-10-15T10:30:45.456Z] [DEBUG] [JinXianMahjong:MahjongService] 发牌完成 { playerCount: 4, tilesPerPlayer: 13 }
[2025-10-15T10:30:46.789Z] [WARN] [JinXianMahjong:OperationManager] 玩家操作超时 { playerId: 'player001', timeout: 15000 }
[2025-10-15T10:30:47.012Z] [ERROR] [JinXianMahjong:RpcHandler] RPC调用失败 { method: 'player_discard', errorCode: 2001 }
```

### 实际使用场景

#### 场景1：游戏流程日志

```javascript
// GameController.js

GameController.prototype.startGame = function() {
  Logger.info('GameController', '======= 开始新游戏 =======');
  
  Logger.group('游戏初始化');
  Logger.debug('GameController', '玩家数量:', this.players.length);
  Logger.debug('GameController', '房间配置:', this.roomtype);
  
  try {
    // 初始化游戏状态
    Logger.time('初始化游戏状态');
    this.gameState = GameStateManager.createGameState(
      this.roomcode,
      this.roomtype,
      this.getPlayerIds()
    );
    Logger.timeEnd('初始化游戏状态');
    
    Logger.info('GameController', '游戏状态创建成功');
    
    // 初始化牌墙
    Logger.time('初始化牌墙');
    this.mahjongWall = MahjongWall.initialize(this.gameState);
    Logger.timeEnd('初始化牌墙');
    
    Logger.info('GameController', '牌墙初始化完成');
    
    // 发牌
    Logger.time('发牌');
    this.dealTiles();
    Logger.timeEnd('发牌');
    
    Logger.info('GameController', '发牌完成');
    
  } catch (error) {
    Logger.error('GameController', '游戏初始化失败', {
      error: error.message,
      stack: error.stack
    });
    throw error;
  }
  
  Logger.groupEnd();
  Logger.info('GameController', '======= 游戏初始化完成 =======');
};
```

#### 场景2：调试日志

```javascript
// MahjongGameService.js

MahjongGameService.prototype.checkWinCondition = function(playerHand, gameState) {
  Logger.debug('MahjongGameService', '开始检查胡牌条件', {
    playerId: playerHand.playerId,
    handSize: playerHand.tiles.length
  });
  
  var rules = gameState.rules;
  Logger.trace('MahjongGameService', '规则配置', {
    useJing: rules.gameRules.useJing,
    minFan: rules.winConditions.minFan
  });
  
  // 胡牌检测
  Logger.time('胡牌检测');
  var winResult = WinDetectionFactory.detectWin(playerHand, gameState.jingInfo);
  Logger.timeEnd('胡牌检测');
  
  Logger.debug('MahjongGameService', '胡牌检测结果', {
    canWin: winResult.canWin,
    patterns: winResult.patterns
  });
  
  if (!winResult.canWin) {
    Logger.debug('MahjongGameService', '不满足胡牌条件');
    return { canWin: false };
  }
  
  // 检查分数
  var score = ScoreCalculation.calculateWinScore(
    winResult.patterns,
    gameState.jingInfo,
    gameState
  );
  
  Logger.debug('MahjongGameService', '计算得分', {
    totalScore: score.totalScore,
    minFan: rules.winConditions.minFan
  });
  
  if (score.totalScore < rules.winConditions.minFan) {
    Logger.warn('MahjongGameService', '未达到起胡分数要求', {
      currentScore: score.totalScore,
      required: rules.winConditions.minFan
    });
    return {
      canWin: false,
      reason: '未达到起胡分数要求（需' + rules.winConditions.minFan + '分）'
    };
  }
  
  Logger.info('MahjongGameService', '胡牌条件满足', {
    playerId: playerHand.playerId,
    score: score.totalScore
  });
  
  return {
    canWin: true,
    patterns: winResult.patterns,
    score: score
  };
};
```

#### 场景3：错误日志

```javascript
// RpcHandler.js

RpcHandler.prototype.handleRequest = function(pack, room, callback) {
  var method = pack.cmd;
  
  Logger.info('RpcHandler', 'RPC请求', {
    method: method,
    playerId: pack.playerid
  });
  
  try {
    // 验证玩家
    if (!this._validatePlayer(pack.playerid, room)) {
      Logger.warn('RpcHandler', '玩家验证失败', {
        playerId: pack.playerid,
        roomcode: room.roomcode
      });
      return callback({ error: '玩家不存在' });
    }
    
    // 执行RPC方法
    var result = this._executeMethod(method, pack, room);
    
    Logger.debug('RpcHandler', 'RPC执行成功', {
      method: method,
      result: result
    });
    
    callback(result);
    
  } catch (error) {
    Logger.error('RpcHandler', 'RPC执行失败', {
      method: method,
      playerId: pack.playerid,
      error: error.message,
      stack: error.stack
    });
    
    callback({ error: '处理请求失败' });
  }
};
```

---

## ⚠️ ErrorHandler.js - 错误处理器

### 核心功能

**文件位置**：`server/games2/jinxianmahjong/utils/ErrorHandler.js`  
**版本**：v1.0.0  
**总行数**：659行

ErrorHandler提供了完整的错误管理功能：
- ✅ 标准化错误代码系统
- ✅ 错误分类和级别管理
- ✅ 错误创建和格式化
- ✅ 错误统计和追踪
- ✅ 安全执行包装
- ✅ 错误恢复策略

### 错误代码范围

```javascript
ERROR_CODE_RANGES: {
  CLIENT_START: 1000,           // 客户端/接口错误
  CLIENT_END: 1999,
  
  VALIDATION_START: 2000,       // 数据验证错误
  VALIDATION_END: 2999,
  
  GAME_LOGIC_START: 3000,       // 游戏逻辑错误
  GAME_LOGIC_END: 3999,
  
  BUSINESS_START: 4000,         // 业务逻辑错误
  BUSINESS_END: 4999,
  
  NETWORK_START: 5000,          // 网络通信错误
  NETWORK_END: 5999,
  
  SYSTEM_START: 9000            // 系统错误
}
```

### 错误代码定义

#### 1. 框架接口错误（1000-1999）

```javascript
INTERFACE_INVALID_PARAMS: 1001,        // 接口参数无效
INTERFACE_ROOM_NOT_FOUND: 1002,        // 房间不存在
INTERFACE_PLAYER_NOT_FOUND: 1003,      // 玩家不存在
INTERFACE_CALLBACK_MISSING: 1004,      // 回调函数缺失
INTERFACE_METHOD_NOT_IMPLEMENTED: 1005, // 接口方法未实现
INTERFACE_TIMEOUT: 1006,               // 接口调用超时
INTERFACE_UNAUTHORIZED: 1007,          // 接口未授权
INTERFACE_RATE_LIMITED: 1008,          // 接口调用频率限制
```

#### 2. 游戏逻辑错误（2000-2999）

```javascript
GAME_INVALID_ACTION: 2001,             // 无效的游戏操作
GAME_WRONG_PHASE: 2002,                // 游戏阶段错误
GAME_PLAYER_LIMIT: 2003,               // 玩家数量限制
GAME_ROOM_FULL: 2004,                  // 房间已满
GAME_ALREADY_STARTED: 2005,            // 游戏已开始
GAME_NOT_STARTED: 2006,                // 游戏未开始
GAME_INVALID_CARD: 2007,               // 无效牌张
GAME_INVALID_OPERATION: 2008,          // 无效操作
GAME_TIMEOUT: 2009,                    // 游戏操作超时
GAME_INSUFFICIENT_PLAYERS: 2010,       // 玩家不足
```

#### 3. 数据验证错误（3000-3999）

```javascript
VALIDATION_ROOMTYPE: 3001,             // RoomType格式错误
VALIDATION_CARD_DATA: 3002,            // 牌张数据无效
VALIDATION_PLAYER_DATA: 3003,          // 玩家数据无效
VALIDATION_ROOM_DATA: 3004,            // 房间数据无效
VALIDATION_GAME_STATE: 3005,           // 游戏状态无效
VALIDATION_CONFIG: 3006,               // 配置数据无效
VALIDATION_MISSING_REQUIRED: 3007,     // 缺少必需字段
VALIDATION_TYPE_MISMATCH: 3008,        // 数据类型不匹配
```

#### 4. 业务逻辑错误（4000-4999）

```javascript
BUSINESS_ROOM_CLOSED: 4001,            // 房间已关闭
BUSINESS_PLAYER_OFFLINE: 4002,         // 玩家离线
BUSINESS_INSUFFICIENT_PERMISSION: 4003, // 权限不足
BUSINESS_DUPLICATE_ACTION: 4004,       // 重复操作
BUSINESS_INVALID_STATE: 4005,          // 无效状态
BUSINESS_RESOURCE_UNAVAILABLE: 4006,   // 资源不可用
```

#### 5. 网络通信错误（5000-5999）

```javascript
NETWORK_CONNECTION_LOST: 5001,         // 连接丢失
NETWORK_TIMEOUT: 5002,                 // 网络超时
NETWORK_INVALID_RESPONSE: 5003,        // 无效响应
NETWORK_SERVER_ERROR: 5004,            // 服务器错误
```

#### 6. 系统错误（9000-9999）

```javascript
SYSTEM_UNKNOWN: 9001,                  // 未知系统错误
SYSTEM_TIMEOUT: 9002,                  // 系统超时
SYSTEM_MEMORY_ERROR: 9003,             // 内存错误
SYSTEM_CONFIGURATION_ERROR: 9004,      // 配置错误
SYSTEM_INITIALIZATION_FAILED: 9005,    // 初始化失败
SYSTEM_DEPENDENCY_ERROR: 9006          // 依赖错误
```

### 错误严重级别

```javascript
ERROR_LEVELS: {
  FATAL: 'FATAL',     // 致命错误，系统无法继续运行
  ERROR: 'ERROR',     // 错误，功能无法正常执行
  WARN: 'WARN',       // 警告，可能影响功能
  INFO: 'INFO'        // 信息，仅用于记录
}
```

### 核心API

#### 1. 创建错误对象

```javascript
/**
 * 创建错误对象
 * @param {number} code - 错误代码
 * @param {string} message - 自定义错误消息（可选）
 * @param {Object} context - 错误上下文信息（可选）
 * @param {string} level - 错误级别（可选）
 * @returns {Object} 标准化错误对象
 */
ErrorHandler.createError(code, message, context, level)

// 使用示例
var error = ErrorHandler.createError(
  ErrorHandler.ERROR_CODES.GAME_INVALID_ACTION,
  '当前阶段不允许出牌',
  {
    playerId: 'player001',
    currentPhase: 'WAITING',
    expectedPhase: 'PLAYING'
  }
);

// 返回的错误对象
{
  code: 2001,
  message: '当前阶段不允许出牌',
  level: 'ERROR',
  timestamp: 1697376000000,
  context: {
    playerId: 'player001',
    currentPhase: 'WAITING',
    expectedPhase: 'PLAYING'
  },
  stack: '...堆栈信息...',
  module: 'JinXianMahjong',
  version: '1.0.0',
  category: 'GAME_LOGIC'
}
```

#### 2. 安全执行函数

```javascript
/**
 * 包装函数执行，自动捕获错误
 * @param {Function} func - 要执行的函数
 * @param {Object} context - 执行上下文
 * @param {Array} args - 函数参数
 * @returns {Object} 执行结果 {success: boolean, result: any, error: Object}
 */
ErrorHandler.safeExecute(func, context, args)

// 使用示例
var result = ErrorHandler.safeExecute(
  function() {
    return this.performRiskyOperation();
  },
  gameController,
  []
);

if (result.success) {
  console.log('操作成功:', result.result);
} else {
  console.error('操作失败:', result.error);
}
```

#### 3. 格式化错误信息

```javascript
/**
 * 格式化错误信息用于显示
 * @param {Object} error - 错误对象
 * @returns {string} 格式化后的错误信息
 */
ErrorHandler.formatErrorMessage(error)

// 使用示例
var error = ErrorHandler.createError(2001, '无效操作');
var message = ErrorHandler.formatErrorMessage(error);
// 输出: "[ERROR:2001] 无效操作"
```

#### 4. 错误恢复

```javascript
/**
 * 尝试从错误中恢复
 * @param {Object} error - 错误对象
 * @param {Function} recoveryFunc - 恢复函数
 * @returns {boolean} 是否成功恢复
 */
ErrorHandler.tryRecover(error, recoveryFunc)

// 使用示例
var recovered = ErrorHandler.tryRecover(error, function() {
  // 尝试恢复逻辑
  return game.resetToLastValidState();
});

if (recovered) {
  Logger.info('ErrorHandler', '已成功从错误中恢复');
} else {
  Logger.error('ErrorHandler', '无法从错误中恢复');
}
```

#### 5. 错误统计

```javascript
/**
 * 获取错误统计信息
 * @returns {Object} 统计对象
 */
ErrorHandler.getStatistics()

// 返回示例
{
  total: 45,
  byCode: {
    2001: 12,
    3001: 8,
    4001: 5
  },
  byLevel: {
    FATAL: 1,
    ERROR: 25,
    WARN: 15,
    INFO: 4
  },
  recent: [...]  // 最近100条错误
}
```

### 实际使用场景

#### 场景1：接口参数验证

```javascript
// export.js - Export.makewar()

export.makewar = function(room, roomtype) {
  try {
    // 参数验证
    if (!room) {
      throw ErrorHandler.createError(
        ErrorHandler.ERROR_CODES.INTERFACE_INVALID_PARAMS,
        'room参数不能为空',
        { functionName: 'makewar' }
      );
    }
    
    if (!roomtype) {
      throw ErrorHandler.createError(
        ErrorHandler.ERROR_CODES.INTERFACE_INVALID_PARAMS,
        'roomtype参数不能为空',
        { functionName: 'makewar' }
      );
    }
    
    // 验证roomtype格式
    var validation = RoomConfigUtils.validate(roomtype);
    if (!validation.isValid) {
      throw ErrorHandler.createError(
        ErrorHandler.ERROR_CODES.VALIDATION_ROOMTYPE,
        'roomtype格式错误: ' + validation.errors.join(', '),
        { roomtype: roomtype, errors: validation.errors }
      );
    }
    
    // 创建游戏
    Logger.info('Export', '开始创建游戏');
    var gameState = GameStateManager.createGameState(
      room.roomcode,
      roomtype,
      room.getPlayerIds()
    );
    
    return { success: true, gameState: gameState };
    
  } catch (error) {
    Logger.error('Export', 'makewar失败', {
      error: error.message,
      code: error.code
    });
    
    return {
      success: false,
      error: ErrorHandler.formatErrorMessage(error)
    };
  }
};
```

#### 场景2：游戏逻辑错误处理

```javascript
// OperationManager.js

OperationManager.prototype.validateDiscard = function(playerId, tileCode) {
  // 检查游戏是否开始
  if (this.gameState.phase !== 'PLAYING') {
    return ErrorHandler.createError(
      ErrorHandler.ERROR_CODES.GAME_WRONG_PHASE,
      '游戏未在进行中',
      {
        currentPhase: this.gameState.phase,
        expectedPhase: 'PLAYING'
      }
    );
  }
  
  // 检查是否轮到该玩家
  if (this.gameState.currentPlayerIndex !== this._getPlayerIndex(playerId)) {
    return ErrorHandler.createError(
      ErrorHandler.ERROR_CODES.GAME_INVALID_ACTION,
      '不是该玩家的回合',
      {
        playerId: playerId,
        currentPlayer: this.gameState.players[this.gameState.currentPlayerIndex].id
      }
    );
  }
  
  // 检查玩家是否持有该牌
  var player = this._getPlayer(playerId);
  if (!this._hasCard(player.handTiles, tileCode)) {
    return ErrorHandler.createError(
      ErrorHandler.ERROR_CODES.GAME_INVALID_CARD,
      '玩家手中没有该牌',
      {
        playerId: playerId,
        tileCode: tileCode,
        handTiles: player.handTiles.map(function(t) { return t.code; })
      }
    );
  }
  
  // 验证通过
  return null;
};

// 使用验证结果
OperationManager.prototype.performDiscard = function(playerId, tileCode) {
  var validationError = this.validateDiscard(playerId, tileCode);
  
  if (validationError) {
    Logger.warn('OperationManager', '出牌验证失败', {
      error: validationError.message,
      code: validationError.code
    });
    return {
      success: false,
      error: validationError
    };
  }
  
  // 执行出牌操作
  // ...
  
  return { success: true };
};
```

#### 场景3：安全执行包装

```javascript
// GameController.js

GameController.prototype.processPlayerAction = function(playerId, action) {
  Logger.info('GameController', '处理玩家操作', {
    playerId: playerId,
    action: action.type
  });
  
  // 使用安全执行包装
  var result = ErrorHandler.safeExecute(
    function() {
      // 可能抛出异常的代码
      return this._executeAction(playerId, action);
    },
    this,
    []
  );
  
  if (!result.success) {
    // 操作失败，记录错误
    Logger.error('GameController', '操作执行失败', {
      playerId: playerId,
      action: action.type,
      error: result.error.message
    });
    
    // 尝试恢复
    var recovered = ErrorHandler.tryRecover(result.error, function() {
      // 恢复到上一个有效状态
      return this._rollbackToLastState();
    }.bind(this));
    
    if (recovered) {
      Logger.info('GameController', '已成功从错误中恢复');
    }
    
    return {
      success: false,
      error: ErrorHandler.formatErrorMessage(result.error)
    };
  }
  
  Logger.debug('GameController', '操作执行成功', {
    playerId: playerId,
    result: result.result
  });
  
  return {
    success: true,
    result: result.result
  };
};
```

---

## 🛠️ shared/utils - 共享工具类

### ArrayUtils.js - 数组操作工具

**功能**：提供数组操作的辅助方法

**常用方法**：
```javascript
// 数组去重
ArrayUtils.unique(array)

// 数组打乱（洗牌）
ArrayUtils.shuffle(array)

// 数组查找
ArrayUtils.findIndex(array, predicate)

// 数组分组
ArrayUtils.groupBy(array, keyFunc)
```

### CardSourceInfoHelper.js - 牌源信息辅助

**功能**：管理麻将牌的来源信息

**主要方法**：
```javascript
// 创建牌源信息
CardSourceInfoHelper.create(source, round, turn)

// 验证牌源信息
CardSourceInfoHelper.validate(sourceInfo)
```

### GameContextHelper.js - 游戏上下文辅助

**功能**：管理游戏上下文信息

**主要方法**：
```javascript
// 创建游戏上下文
GameContextHelper.create(roomcode, round, phase)

// 更新上下文
GameContextHelper.update(context, updates)
```

### GameStateHelper.js - 游戏状态辅助

**功能**：游戏状态的辅助操作

**主要方法**：
```javascript
// 验证游戏状态
GameStateHelper.validate(gameState)

// 克隆游戏状态
GameStateHelper.clone(gameState)

// 比较游戏状态
GameStateHelper.compare(state1, state2)
```

### MahjongCardUniqueId.js - 麻将牌唯一ID

**功能**：生成和管理麻将牌的唯一标识

**主要方法**：
```javascript
// 生成唯一ID（10-145）
MahjongCardUniqueId.generate(code, index)

// 从唯一ID获取牌码
MahjongCardUniqueId.getCode(uniqueId)

// 验证唯一ID
MahjongCardUniqueId.validate(uniqueId)
```

### RoomConfigUtils.js - 房间配置工具

**功能**：房间配置的解析和验证（详见 [06-规则配置系统.md](../core/06-规则配置系统.md)）

---

## 💡 使用最佳实践

### 1. 日志级别选择

```javascript
// ✓ 推荐：根据环境设置日志级别
if (process.env.NODE_ENV === 'production') {
  Logger.setLevel('WARN');  // 生产环境只记录警告和错误
} else {
  Logger.setLevel('DEBUG'); // 开发环境记录调试信息
}

// ✓ 推荐：使用合适的日志级别
Logger.trace('Module', '详细跟踪信息');  // 非常详细，仅开发调试用
Logger.debug('Module', '调试信息');       // 开发时使用
Logger.info('Module', '正常运行信息');    // 关键流程节点
Logger.warn('Module', '警告信息');        // 可能的问题
Logger.error('Module', '错误信息');       // 功能异常
Logger.fatal('Module', '致命错误');       // 系统无法继续

// ✗ 不推荐：滥用日志级别
Logger.error('Module', '玩家进入房间');  // 这应该是INFO级别
Logger.info('Module', '系统崩溃');       // 这应该是FATAL级别
```

### 2. 日志标签规范

```javascript
// ✓ 推荐：使用清晰的标签
Logger.info('GameController', '游戏开始');
Logger.debug('MahjongService', '发牌完成');
Logger.warn('OperationManager', '操作超时');

// ✗ 不推荐：标签不清晰
Logger.info('GC', 'start');          // 太简短
Logger.info('游戏', '开始');          // 使用中文不便于过滤
```

### 3. 附加数据使用

```javascript
// ✓ 推荐：提供有用的上下文信息
Logger.error('RpcHandler', 'RPC调用失败', {
  method: 'player_discard',
  playerId: 'player001',
  errorCode: 2001,
  timestamp: Date.now()
});

// ✗ 不推荐：数据过多或无用
Logger.info('Module', '操作', {
  // 包含整个gameState对象（太大）
  gameState: this.gameState
});
```

### 4. 性能考虑

```javascript
// ✓ 推荐：仅在需要时记录日志
if (Logger.config.currentLevel <= Logger.LOG_LEVELS.DEBUG) {
  var expensiveData = this._calculateExpensiveData();
  Logger.debug('Module', '详细数据', expensiveData);
}

// ✗ 不推荐：总是计算数据
var expensiveData = this._calculateExpensiveData();
Logger.debug('Module', '详细数据', expensiveData);  // DEBUG被禁用时也会计算
```

### 5. 错误处理策略

```javascript
// ✓ 推荐：创建标准化错误
throw ErrorHandler.createError(
  ErrorHandler.ERROR_CODES.GAME_INVALID_ACTION,
  '具体的错误描述',
  { 有用的上下文信息 }
);

// ✓ 推荐：使用安全执行
var result = ErrorHandler.safeExecute(riskyFunction, context, args);
if (!result.success) {
  // 处理错误
}

// ✗ 不推荐：直接抛出字符串
throw '出错了';  // 没有错误码，无法分类

// ✗ 不推荐：忽略错误
try {
  riskyOperation();
} catch (error) {
  // 什么都不做，错误被吞噬
}
```

### 6. 日志和错误配合使用

```javascript
// ✓ 推荐：记录错误日志
try {
  performOperation();
} catch (error) {
  var standardError = ErrorHandler.createError(
    ErrorHandler.ERROR_CODES.GAME_INVALID_ACTION,
    error.message,
    { operation: 'performOperation' }
  );
  
  Logger.error('Module', '操作失败', {
    error: standardError.message,
    code: standardError.code
  });
  
  throw standardError;
}

// ✗ 不推荐：只记录日志或只抛出错误
try {
  performOperation();
} catch (error) {
  Logger.error('Module', error.message);  // 只记录，不抛出
  // 或
  throw error;  // 只抛出，不记录
}
```

---

## 🔍 调试技巧

### 1. 启用详细日志

```javascript
// 临时启用TRACE级别查看所有日志
Logger.setLevel('TRACE');

// 执行需要调试的代码
someFunction();

// 恢复原来的级别
Logger.setLevel('INFO');
```

### 2. 使用日志分组

```javascript
// 使用分组整理相关日志
Logger.group('===== 玩家操作处理 =====');
Logger.info('Operation', '验证玩家');
Logger.debug('Operation', '检查游戏状态');
Logger.debug('Operation', '执行操作');
Logger.info('Operation', '操作完成');
Logger.groupEnd();
```

### 3. 性能分析

```javascript
// 使用计时功能分析性能
Logger.time('完整游戏流程');

Logger.time('初始化');
initialize();
Logger.timeEnd('初始化');

Logger.time('发牌');
dealTiles();
Logger.timeEnd('发牌');

Logger.time('游戏进行');
playGame();
Logger.timeEnd('游戏进行');

Logger.timeEnd('完整游戏流程');
```

### 4. 查看错误历史

```javascript
// 获取最近的错误
var errors = ErrorHandler.getStatistics().recent;
Logger.table(errors);

// 分析错误分布
var stats = ErrorHandler.getStatistics();
Logger.info('ErrorStats', '错误统计', {
  total: stats.total,
  byLevel: stats.byLevel,
  topErrors: Object.keys(stats.byCode)
    .sort(function(a, b) {
      return stats.byCode[b] - stats.byCode[a];
    })
    .slice(0, 5)
});
```

### 5. 日志过滤

```javascript
// 只查看特定级别的日志
var errorLogs = Logger.getHistory(null, Logger.LOG_LEVELS.ERROR);
var warnLogs = Logger.getHistory(null, Logger.LOG_LEVELS.WARN);

// 只查看最近的日志
var recent = Logger.getHistory(50);  // 最近50条

// 自定义过滤
var gameLogs = Logger.getHistory().filter(function(log) {
  return log.tag.indexOf('Game') !== -1;
});
```

---

## 📚 完整使用示例

### 示例1：模块初始化

```javascript
// 模块入口文件

(function() {
  'use strict';
  
  // 配置Logger
  Logger.configure({
    currentLevel: Logger.LOG_LEVELS.DEBUG,
    enableTimestamp: true,
    enableColors: true,
    moduleName: 'JinXianMahjong'
  });
  
  Logger.info('System', '======= 进贤麻将系统启动 =======');
  Logger.info('System', '版本:', '1.0.0');
  Logger.info('System', '环境:', process.env.NODE_ENV || 'development');
  
  // 初始化系统
  try {
    Logger.group('系统初始化');
    
    Logger.time('加载配置');
    var config = loadConfiguration();
    Logger.timeEnd('加载配置');
    Logger.debug('System', '配置加载完成', config);
    
    Logger.time('初始化数据库');
    initializeDatabase();
    Logger.timeEnd('初始化数据库');
    Logger.info('System', '数据库初始化完成');
    
    Logger.time('注册游戏模块');
    registerGameModule();
    Logger.timeEnd('注册游戏模块');
    Logger.info('System', '游戏模块注册完成');
    
    Logger.groupEnd();
    Logger.info('System', '======= 系统启动完成 =======');
    
  } catch (error) {
    var systemError = ErrorHandler.createError(
      ErrorHandler.ERROR_CODES.SYSTEM_INITIALIZATION_FAILED,
      '系统初始化失败: ' + error.message,
      { error: error.stack },
      ErrorHandler.ERROR_LEVELS.FATAL
    );
    
    Logger.fatal('System', '系统启动失败', {
      error: systemError.message,
      code: systemError.code
    });
    
    process.exit(1);
  }
})();
```

### 示例2：完整的操作流程

```javascript
// 玩家出牌操作的完整流程

function handlePlayerDiscard(playerId, tileCode) {
  Logger.info('DiscardHandler', '======= 处理玩家出牌 =======', {
    playerId: playerId,
    tileCode: tileCode
  });
  
  try {
    Logger.group('出牌验证');
    
    // 1. 参数验证
    Logger.debug('Validation', '验证参数');
    if (!playerId || !tileCode) {
      throw ErrorHandler.createError(
        ErrorHandler.ERROR_CODES.INTERFACE_INVALID_PARAMS,
        '出牌参数无效',
        { playerId: playerId, tileCode: tileCode }
      );
    }
    
    // 2. 玩家验证
    Logger.debug('Validation', '验证玩家');
    var player = getPlayer(playerId);
    if (!player) {
      throw ErrorHandler.createError(
        ErrorHandler.ERROR_CODES.INTERFACE_PLAYER_NOT_FOUND,
        '玩家不存在',
        { playerId: playerId }
      );
    }
    
    // 3. 游戏状态验证
    Logger.debug('Validation', '验证游戏状态');
    var gameState = getGameState();
    if (gameState.phase !== 'PLAYING') {
      throw ErrorHandler.createError(
        ErrorHandler.ERROR_CODES.GAME_WRONG_PHASE,
        '游戏未在进行中',
        { currentPhase: gameState.phase }
      );
    }
    
    // 4. 回合验证
    Logger.debug('Validation', '验证玩家回合');
    if (!isPlayerTurn(playerId)) {
      throw ErrorHandler.createError(
        ErrorHandler.ERROR_CODES.GAME_INVALID_ACTION,
        '不是该玩家的回合',
        { playerId: playerId, currentPlayer: getCurrentPlayer() }
      );
    }
    
    Logger.groupEnd();
    Logger.info('Validation', '验证通过');
    
    // 5. 执行出牌
    Logger.group('执行出牌');
    Logger.time('出牌操作');
    
    var result = ErrorHandler.safeExecute(
      function() {
        return performDiscard(player, tileCode);
      },
      this,
      []
    );
    
    Logger.timeEnd('出牌操作');
    
    if (!result.success) {
      throw result.error;
    }
    
    Logger.info('Discard', '出牌成功', {
      playerId: playerId,
      tileCode: tileCode,
      discardedTile: result.result
    });
    
    Logger.groupEnd();
    
    // 6. 检查其他玩家的响应
    Logger.group('检查玩家响应');
    var responses = checkPlayerResponses(tileCode);
    Logger.debug('Response', '玩家响应', responses);
    Logger.groupEnd();
    
    // 7. 广播消息
    Logger.debug('Broadcast', '广播出牌消息');
    broadcastDiscard(playerId, tileCode, responses);
    
    Logger.info('DiscardHandler', '======= 出牌处理完成 =======');
    
    return {
      success: true,
      result: {
        playerId: playerId,
        tile: tileCode,
        responses: responses
      }
    };
    
  } catch (error) {
    Logger.error('DiscardHandler', '出牌处理失败', {
      error: error.message,
      code: error.code,
      playerId: playerId,
      tileCode: tileCode
    });
    
    // 记录错误统计
    var stats = ErrorHandler.getStatistics();
    Logger.warn('DiscardHandler', '当前错误统计', {
      total: stats.total,
      recent: stats.recent.length
    });
    
    return {
      success: false,
      error: ErrorHandler.formatErrorMessage(error)
    };
  }
}
```

---

## 🔗 相关文档链接

- **上一篇**：[06-规则配置系统.md](../core/06-规则配置系统.md) - 规则配置解析
- **下一篇**：[08-游戏流程概述.md](../architecture/08-游戏流程概述.md) - 完整游戏流程
- **参考**：
  - [03-RPC处理机制.md](../framework/03-RPC处理机制.md) - RPC错误处理
  - [04-游戏核心服务.md](../core/04-游戏核心服务.md) - 服务层日志使用

---

## 📝 附录

### A. Logger配置选项完整列表

```javascript
{
  currentLevel: 0-5,              // 当前日志级别
  enableConsole: true/false,      // 启用控制台输出
  enableColors: true/false,       // 启用颜色
  enableTimestamp: true/false,    // 启用时间戳
  enableModuleName: true/false,   // 启用模块名
  enableStackTrace: true/false,   // 启用堆栈跟踪
  timestampFormat: 'ISO'/'LOCAL'/'TIMESTAMP', // 时间戳格式
  moduleName: 'string',           // 模块名
  maxLogHistory: number,          // 最大历史记录数
  flushInterval: number           // 刷新间隔（毫秒）
}
```

### B. 错误代码快速查询

| 范围 | 类别 | 说明 |
|------|------|------|
| 1000-1999 | 框架接口错误 | Export/Import接口相关 |
| 2000-2999 | 游戏逻辑错误 | 游戏规则和操作相关 |
| 3000-3999 | 数据验证错误 | 参数和数据格式验证 |
| 4000-4999 | 业务逻辑错误 | 业务规则和状态相关 |
| 5000-5999 | 网络通信错误 | 网络连接和通信相关 |
| 9000-9999 | 系统错误 | 系统级别的严重错误 |

### C. 常用日志模式

```javascript
// 1. 方法入口/出口模式
function someMethod(param) {
  Logger.debug('Module', 'someMethod 入口', { param: param });
  try {
    // 方法逻辑
    var result = doSomething(param);
    Logger.debug('Module', 'someMethod 出口', { result: result });
    return result;
  } catch (error) {
    Logger.error('Module', 'someMethod 异常', { error: error.message });
    throw error;
  }
}

// 2. 状态变更模式
function changeState(newState) {
  Logger.info('StateManager', '状态变更', {
    from: this.currentState,
    to: newState
  });
  this.currentState = newState;
}

// 3. 性能监控模式
function performanceMonitor(operation) {
  Logger.time(operation.name);
  var result = operation.execute();
  Logger.timeEnd(operation.name);
  return result;
}
```

---

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