daoqi/youlegames
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

目录结构调整

Browse Source
This commit is contained in:
Joywayer
2026-02-04 23:47:45 +08:00
parent 6938c911c3
commit 6b22238c6e
8780 changed files with 15333 additions and 574 deletions
Download Patch File Download Diff File Expand all files Collapse all files

682
codes/games/server/docs/guides/README.md Normal file
View File

@@ -0,0 +1,682 @@
# 进贤麻将子游戏技术文档
> 📚 完整的进贤麻将子游戏技术文档，涵盖架构设计、核心算法、开发指南等所有方面。
## 🎯 文档概述
本文档集为 `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日