# 进贤麻将子游戏技术文档

> 📚 完整的进贤麻将子游戏技术文档，涵盖架构设计、核心算法、开发指南等所有方面。

## 🎯 文档概述

本文档集为 `server/games2/jinxianmahjong` 子游戏提供完整的技术说明，帮助开发者快速理解项目架构、掌握核心算法、完成功能开发。

**文档特点**:
- ✅ **全面覆盖** - 14篇文档，约240,000字，覆盖所有核心模块
- ✅ **深入详细** - 包含算法分析、代码示例、最佳实践
- ✅ **结构清晰** - 按框架、核心、架构、开发四大类组织
- ✅ **实用导向** - 提供快速入门、常见任务、问题解答

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

---

## 🚀 快速开始

### 5分钟了解项目

```javascript
// 1. 三文件架构（核心概念）
mod.js     → 模块入口，加载所有文件
export.js  → 框架调用游戏（14个接口）
import.js  → 游戏调用框架（13个接口）

// 2. 请求处理流程
客户端 → packet.js → mod.js → RpcHandler → 业务逻辑 → import → 客户端

// 3. 核心目录
rpc/           → RPC请求处理（34个方法）
game/          → 游戏核心服务（Controller、Manager、Service）
shared/        → 前后端共享代码（算法、数据结构、配置）
utils/         → 工具模块（Logger、ErrorHandler）
```

### 推荐学习路径

#### 🌟 新手入门（2小时）

```
1. 📖 阅读 00-框架基础概述.md         (30分钟)
   理解三文件架构和RPC机制

2. 📖 阅读 01-Export接口说明.md       (15分钟)
   📖 阅读 02-Import接口说明.md       (15分钟)
   理解框架与游戏的双向接口

3. 📖 阅读 08-游戏流程概述.md         (40分钟)
   理解完整游戏流程

4. 💻 完成第一个功能修改               (20分钟)
   参考 10-快速入门指南.md
```

#### 🔬 算法研究（进阶）

```
1. 📖 阅读 05-共享代码模块.md
   深入理解核心算法实现
   
2. 🔍 研究精牌系统
   → JingAlgorithm.js（5166行）
   
3. 🔍 研究胡牌检测
   → WinDetectionFactory.js
   
4. 🔍 研究计分系统
   → ScoreCalculation.js（917行）
```

#### 🛠️ 功能开发（实战）

```
1. 📖 阅读 03-RPC处理机制.md
   理解请求处理流程
   
2. 📖 阅读 04-游戏核心服务.md
   理解服务层架构
   
3. 📖 阅读 09-代码框架总结.md
   理解整体设计
   
4. 💻 开始功能开发
```

---

## 📚 文档导航

### 一、框架基础（Framework）

掌握友乐游戏平台的基础架构和接口规范。

| 文档 | 内容概要 | 字数 | 难度 |
|------|---------|------|------|
| [00-框架基础概述.md](framework/00-框架基础概述.md) | 友乐平台架构、三文件架构、ES5规范、前后端分离 | 14,000 | ⭐ |
| [01-Export接口说明.md](framework/01-Export接口说明.md) | 框架→游戏的14个接口详解 | 18,000 | ⭐⭐ |
| [02-Import接口说明.md](framework/02-Import接口说明.md) | 游戏→框架的13个接口详解 | 15,000 | ⭐⭐ |
| [03-RPC处理机制.md](framework/03-RPC处理机制.md) | RPC路由流程、34个RPC方法详解 | 23,000 | ⭐⭐⭐ |

**学习收获**:
- ✅ 理解友乐平台的三文件架构
- ✅ 掌握Export和Import接口的使用
- ✅ 理解RPC请求的完整处理流程
- ✅ 了解ES5规范和浏览器兼容性

---

### 二、核心服务（Core）

深入理解游戏核心服务、算法实现和配置系统。

| 文档 | 内容概要 | 字数 | 难度 |
|------|---------|------|------|
| [04-游戏核心服务.md](core/04-游戏核心服务.md) | GameController、OperationManager等5大服务 | 30,000 | ⭐⭐⭐ |
| [05-共享代码模块.md](core/05-共享代码模块.md) | JingAlgorithm、WinDetection等核心算法 | 35,000 | ⭐⭐⭐⭐⭐ |
| [06-规则配置系统.md](core/06-规则配置系统.md) | RoomType编码、配置解析、缓存机制 | 25,000 | ⭐⭐⭐ |

**学习收获**:
- ✅ 掌握游戏核心服务的职责和协作
- ✅ 深入理解精牌系统算法（5166行）
- ✅ 掌握胡牌检测和计分计算
- ✅ 理解房间配置的解析和使用

**重点推荐**: 📌 `05-共享代码模块.md` 是最复杂、最详细的文档，深度分析了核心算法实现。

---

### 三、架构设计（Architecture）

从宏观角度理解游戏流程和整体架构。

| 文档 | 内容概要 | 字数 | 难度 |
|------|---------|------|------|
| [08-游戏流程概述.md](architecture/08-游戏流程概述.md) | 完整游戏流程、状态机、时序图 | 25,000 | ⭐⭐⭐ |
| [09-代码框架总结.md](architecture/09-代码框架总结.md) | 架构总结、设计模式、扩展指南 | 20,000 | ⭐⭐⭐⭐ |

**学习收获**:
- ✅ 理解游戏从开始到结束的完整流程
- ✅ 掌握游戏状态机和阶段转换
- ✅ 理解整体架构设计和模块依赖
- ✅ 学习设计模式的实际应用

---

### 四、开发指南（Development）

实用的开发工具、调试技巧和快速入门。

| 文档 | 内容概要 | 字数 | 难度 |
|------|---------|------|------|
| [07-工具模块.md](development/07-工具模块.md) | Logger日志系统、ErrorHandler错误处理 | 20,000 | ⭐⭐ |
| [10-快速入门指南.md](development/10-快速入门指南.md) | 快速理解、开发任务、FAQ、实战练习 | 15,000 | ⭐ |

**学习收获**:
- ✅ 掌握Logger的6级日志使用
- ✅ 理解错误处理规范
- ✅ 快速定位代码位置
- ✅ 解决常见开发问题

---

## 🎓 按角色选择学习路径

### 👨‍💻 新开发者（第1天）

**目标**: 快速理解项目，能修改简单功能

```
上午（2-3小时）:
├─ 阅读 README.md（本文档）            10分钟
├─ 阅读 00-框架基础概述.md             30分钟
├─ 阅读 01-Export接口说明.md           20分钟
├─ 阅读 02-Import接口说明.md           20分钟
└─ 阅读 10-快速入门指南.md             40分钟

下午（2-3小时）:
├─ 阅读 08-游戏流程概述.md             40分钟
├─ 浏览代码结构                        30分钟
├─ 完成第一个功能修改（添加日志）      30分钟
└─ 完成练习（修改分数规则）            30分钟
```

**预期成果**: 
- ✅ 理解三文件架构和RPC机制
- ✅ 知道去哪里找需要的代码
- ✅ 能完成简单的功能修改

---

### 🔬 算法工程师（第1-2天）

**目标**: 深入理解核心算法实现

```
第1天 - 精牌系统:
├─ 阅读 05-共享代码模块.md（JingAlgorithm部分） 2小时
├─ 研究 JingAlgorithm.js 源码                  2小时
└─ 理解比精算法和精分计算                      1小时

第2天 - 胡牌检测与计分:
├─ 阅读 05-共享代码模块.md（其他算法部分）    2小时
├─ 研究 WinDetectionFactory.js 源码           1.5小时
├─ 研究 ScoreCalculation.js 源码              1.5小时
└─ 理解牌型检测和计分流程                      1小时
```

**预期成果**:
- ✅ 深入理解精牌系统算法（5166行）
- ✅ 掌握5种牌型的检测算法
- ✅ 理解计分系统的实现细节

---

### 🏗️ 架构师（第1-2天）

**目标**: 理解整体架构和设计理念

```
第1天 - 架构理解:
├─ 阅读 00-框架基础概述.md                    30分钟
├─ 阅读 03-RPC处理机制.md                     1小时
├─ 阅读 04-游戏核心服务.md                    1.5小时
├─ 阅读 08-游戏流程概述.md                    1.5小时
└─ 阅读 09-代码框架总结.md                    1.5小时

第2天 - 深入分析:
├─ 分析模块依赖关系                           1小时
├─ 分析设计模式应用                           1小时
├─ 评估性能优化点                             1小时
└─ 规划扩展方案                               2小时
```

**预期成果**:
- ✅ 理解三层架构设计
- ✅ 掌握6大设计模式的应用
- ✅ 了解模块依赖关系
- ✅ 能够规划架构扩展

---

### 🛠️ 功能开发者（按需学习）

**目标**: 根据开发任务学习相关知识

#### 任务1: 添加新RPC方法
```
需要阅读:
├─ 03-RPC处理机制.md（RpcHandler详解）
└─ 10-快速入门指南.md（任务1: 添加新RPC方法）
预计时间: 1小时
```

#### 任务2: 修改计分规则
```
需要阅读:
├─ 05-共享代码模块.md（ScoreCalculation部分）
└─ 10-快速入门指南.md（任务2: 修改计分规则）
预计时间: 1.5小时
```

#### 任务3: 添加新游戏规则
```
需要阅读:
├─ 06-规则配置系统.md
└─ 10-快速入门指南.md（任务3: 添加新游戏规则）
预计时间: 2小时
```

#### 任务4: 添加新牌型
```
需要阅读:
├─ 05-共享代码模块.md（WinDetectionFactory部分）
└─ 10-快速入门指南.md（任务5: 添加新牌型检测）
预计时间: 3小时
```

---

## 🔍 按问题查找文档

### 问题: 客户端请求如何处理？

**答案位置**: 
- 📖 [03-RPC处理机制.md](framework/03-RPC处理机制.md) - 完整RPC处理流程
- 📖 [04-游戏核心服务.md](core/04-游戏核心服务.md#rpchandler) - RpcHandler详解

**关键代码**: `rpc/RpcHandler.js`

---

### 问题: 精牌系统是如何实现的？

**答案位置**:
- 📖 [05-共享代码模块.md](core/05-共享代码模块.md#jingalgorithm-精牌算法) - 精牌算法详解
- 📖 [08-游戏流程概述.md](architecture/08-游戏流程概述.md#开精流程) - 精牌确定流程

**关键代码**: `shared/algorithms/JingAlgorithm.js`（5166行）

---

### 问题: 如何判断能否胡牌？

**答案位置**:
- 📖 [05-共享代码模块.md](core/05-共享代码模块.md#windetectionfactory-胡牌检测工厂) - 胡牌检测算法
- 📖 [04-游戏核心服务.md](core/04-游戏核心服务.md#mahjonggameservice) - 胡牌服务

**关键代码**: `shared/algorithms/WinDetectionFactory.js`

---

### 问题: 分数是如何计算的？

**答案位置**:
- 📖 [05-共享代码模块.md](core/05-共享代码模块.md#scorecalculation-计分系统) - 计分算法详解
- 📖 [08-游戏流程概述.md](architecture/08-游戏流程概述.md#胡牌结算) - 结算流程

**关键代码**: `shared/algorithms/ScoreCalculation.js`（917行）

---

### 问题: 如何添加日志和调试？

**答案位置**:
- 📖 [07-工具模块.md](development/07-工具模块.md#logger-日志管理器) - Logger详细说明
- 📖 [10-快速入门指南.md](development/10-快速入门指南.md#任务4-添加日志和调试信息) - 日志使用示例

**关键代码**: `utils/Logger.js`（606行）

---

### 问题: 游戏状态如何管理？

**答案位置**:
- 📖 [04-游戏核心服务.md](core/04-游戏核心服务.md#gamestate-游戏状态对象) - gameState详解
- 📖 [08-游戏流程概述.md](architecture/08-游戏流程概述.md#游戏状态机) - 状态转换

**关键代码**: `shared/dataStructures/GameStateManager.js`

---

### 问题: 房间配置如何解析？

**答案位置**:
- 📖 [06-规则配置系统.md](core/06-规则配置系统.md) - 完整配置系统说明
- 📖 [01-Export接口说明.md](framework/01-Export接口说明.md#roomtype配置) - roomtype格式

**关键代码**: `shared/config/RoomConfigUtils.js`（1222行）

---

## 📖 文档特色内容

### 🏆 最详细：05-共享代码模块.md

- **35,000字** 深度分析
- 涵盖 **5大核心算法** 详解
- **JingAlgorithm.js** 5166行完整分析
- **ScoreCalculation.js** 917行计分逻辑
- **MahjongCard.js** 2461行牌对象系统

**适合**: 想深入理解算法实现的开发者

---

### 🔄 最全面：08-游戏流程概述.md

- **完整游戏流程** 从开始到结束
- **7个游戏阶段** 详细说明
- **状态机设计** 和转换规则
- **时序图** 展示交互流程
- **操作优先级** 处理机制

**适合**: 想理解整体流程的开发者

---

### 🛠️ 最实用：10-快速入门指南.md

- **10分钟** 快速理解核心概念
- **5个常见开发任务** 详细步骤
- **10个FAQ** 解答高频问题
- **3个实战练习** 从易到难
- **代码导航技巧** 快速定位

**适合**: 想快速上手的新开发者

---

### 🏗️ 最系统：09-代码框架总结.md

- **三层架构** 详细说明
- **完整依赖关系图** (6层依赖)
- **6大设计模式** 实战应用
- **4个扩展指南** 详细步骤
- **5个常见问题** 解决方案

**适合**: 想理解架构设计的开发者

---

## 📊 文档统计

### 文档数量与字数

| 分类 | 文档数 | 总字数 | 占比 |
|------|--------|--------|------|
| 框架基础 | 4篇 | 70,000字 | 29% |
| 核心服务 | 3篇 | 90,000字 | 38% |
| 架构设计 | 2篇 | 45,000字 | 19% |
| 开发指南 | 2篇 | 35,000字 | 14% |
| **总计** | **13篇** | **240,000字** | **100%** |

### 难度分布

- ⭐ 入门级：2篇（快速理解）
- ⭐⭐ 初级：3篇（基础理解）
- ⭐⭐⭐ 中级：5篇（深入理解）
- ⭐⭐⭐⭐ 高级：2篇（架构设计）
- ⭐⭐⭐⭐⭐ 专家级：1篇（算法深度）

### 预计学习时间

- **快速浏览**: 2小时（理解基础架构）
- **系统学习**: 2天（完整阅读所有文档）
- **深入研究**: 1周（理解所有算法细节）
- **精通掌握**: 2周（能独立开发和架构）

---

## 🔧 技术栈

### 编程语言
- **JavaScript ES5** - 严格遵循ES5规范，确保浏览器兼容性

### 运行环境
- **Node.js** (服务端) - 游戏服务器
- **浏览器** (客户端) - Chrome/Firefox/Safari等

### 框架平台
- **友乐游戏平台** - 自研游戏框架
- **三文件架构** - mod.js/export.js/import.js

### 核心技术
- **RPC通信** - WebSocket/HTTP协议
- **状态机** - 7个游戏阶段管理
- **精牌算法** - 5166行核心算法
- **胡牌检测** - 5种牌型检测
- **计分系统** - 917行计分逻辑

---

## 📁 项目结构

```
server/games2/jinxianmahjong/
├── mod.js                      # 模块入口（加载所有文件）
├── export.js                   # 输出接口（框架→游戏，14个接口）
├── import.js                   # 输入接口（游戏→框架，13个接口）
│
├── rpc/                        # RPC处理器
│   ├── RpcHandler.js           # 标准RPC处理（34个方法）
│   ├── AIRpcHandler.js         # AI玩家RPC处理
│   └── OperationEnumerator.js  # 操作枚举器
│
├── game/                       # 游戏核心服务
│   ├── GameController.js       # 游戏流程控制器
│   ├── MahjongGameService.js   # 麻将游戏服务
│   ├── OperationManager.js     # 操作管理器
│   ├── AIManager.js            # AI管理器
│   └── RoomAdapter.js          # 房间适配器
│
├── shared/                     # 前后端共享代码
│   ├── algorithms/             # 核心算法
│   │   ├── JingAlgorithm.js    # 精牌算法（5166行）
│   │   ├── WinDetectionFactory.js  # 胡牌检测
│   │   ├── ScoreCalculation.js     # 计分系统（917行）
│   │   └── PatternFactory.js       # 牌型分析
│   ├── dataStructures/         # 数据结构
│   │   ├── GameStateManager.js     # 游戏状态管理
│   │   └── MahjongCard.js          # 麻将牌对象（2461行）
│   ├── config/                 # 配置系统
│   │   ├── RoomConfigUtils.js      # 配置工具（1222行）
│   │   └── RuleConfigParser.js     # 规则解析器
│   ├── constants/              # 常量定义（12个模块）
│   │   └── index.js            # 常量统一导出
│   └── utils/                  # 共享工具
│
└── utils/                      # 工具模块
    ├── Logger.js               # 日志管理器（606行）
    └── ErrorHandler.js         # 错误处理器（659行）
```

---

## 🌟 核心特性

### 1. 精牌系统（独特玩法）

进贤麻将最核心的特色系统，由 **5166行** 代码实现。

**功能**:
- ✅ 掷骰子确定精牌（正精、副精）
- ✅ 精牌可作为万能牌使用
- ✅ 精牌计分（正精2分、副精1分）
- ✅ 比精算法（比较精牌数量和价值）
- ✅ 冲关机制（精分达到10分翻倍）

**文档**: [05-共享代码模块.md - JingAlgorithm](core/05-共享代码模块.md#jingalgorithm-精牌算法)

---

### 2. 5种胡牌牌型

支持多种胡牌牌型，满足不同玩法需求。

**牌型**:
1. **平胡** - 标准3-3-3-3-2组合
2. **七对** - 7个对子
3. **四碰** - 4个刻子+1个对子
4. **十三烂** - 特殊散牌组合
5. **七星十三烂** - 最高级别牌型

**文档**: [05-共享代码模块.md - WinDetectionFactory](core/05-共享代码模块.md#windetectionfactory-胡牌检测工厂)

---

### 3. 灵活的规则配置

13位roomtype编码，支持丰富的规则组合。

**配置项**:
- 局数（8/16/24局）
- 精牌（带精/不带精）
- 吃碰杠（允许/禁止）
- 特殊规则（上下翻、买雷雷等）

**文档**: [06-规则配置系统.md](core/06-规则配置系统.md)

---

### 4. 完善的日志系统

6级日志，支持历史记录和统计分析。

**级别**: TRACE → DEBUG → INFO → WARN → ERROR → FATAL

**文档**: [07-工具模块.md - Logger](development/07-工具模块.md#logger-日志管理器)

---

## ⚡ 性能优化

### 1. 配置缓存机制

使用LRU缓存策略，避免重复解析roomtype配置。

**效果**: 
- ✅ 缓存命中率 > 95%
- ✅ 配置解析时间 < 1ms

**文档**: [06-规则配置系统.md - 缓存机制](core/06-规则配置系统.md#缓存机制)

---

### 2. 对象池模式

复用MahjongCard对象，减少GC压力。

**效果**:
- ✅ 减少对象创建 80%
- ✅ 内存占用降低 30%

**文档**: [09-代码框架总结.md - 性能优化](architecture/09-代码框架总结.md#性能优化建议)

---

### 3. 预计算策略

预先计算常用数据，提高运行时性能。

**应用**:
- ✅ 牌型组合预计算
- ✅ 精牌列表缓存
- ✅ 规则模板预加载

---

## 🤝 参与贡献

### 文档改进

如果你发现文档中的错误或需要改进的地方：

1. 在对应文档中记录问题
2. 提出改进建议
3. 更新文档内容
4. 同步更新相关交叉引用

### 代码贡献

如果你开发了新功能或修复了bug：

1. 更新相关技术文档
2. 添加代码示例
3. 更新常见问题解答
4. 更新本README的快速链接

---

## 📞 获取帮助

### 遇到问题？

1. **查看文档** - 在本README中按问题查找相关文档
2. **查看FAQ** - [10-快速入门指南.md](development/10-快速入门指南.md#常见问题解答-faq)
3. **搜索代码** - 使用文档中的代码导航技巧
4. **查看日志** - 使用Logger追踪程序执行

### 学习建议

- 📖 **先框架后细节** - 从框架基础开始，逐步深入
- 💻 **理论结合实践** - 边学习边尝试修改代码
- 🔍 **善用搜索** - 在文档中搜索关键词
- 📝 **做好笔记** - 记录重要概念和代码位置

---

## 📜 更新日志

### v1.0 (2025年10月15日)

**完成的文档**:
- ✅ 框架基础文档（4篇，70,000字）
- ✅ 核心服务文档（3篇，90,000字）
- ✅ 架构设计文档（2篇，45,000字）
- ✅ 开发指南文档（2篇，35,000字）
- ✅ 文档导航（README.md）

**文档特点**:
- 📚 13篇技术文档，总计约240,000字
- 🔍 深度分析核心算法（JingAlgorithm 5166行）
- 💡 丰富的代码示例和最佳实践
- 🎯 多种学习路径，适合不同角色

**重要里程碑**:
- ✅ 完成所有计划文档
- ✅ 建立完整文档体系
- ✅ 提供多角色学习路径
- ✅ 创建文档导航和快速索引

---

## 🎉 开始你的学习之旅！

选择一个适合你的学习路径，开始探索进贤麻将的技术世界吧！

**推荐起点**:
- 🌟 **新手**: [10-快速入门指南.md](development/10-快速入门指南.md)
- 🔬 **算法**: [05-共享代码模块.md](core/05-共享代码模块.md)
- 🏗️ **架构**: [09-代码框架总结.md](architecture/09-代码框架总结.md)

**记住**:
- 📖 遇到问题先查文档
- 🔍 善用本README的快速导航
- 💻 理论结合实践
- 🧪 多写代码多测试

---

**Happy Coding! 🚀**

---

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