daoqi/youlegames

Fork 0

Files

Joywayer 6b22238c6e 目录结构调整

2026-02-04 23:47:45 +08:00

24 KiB

Raw Blame History

进贤麻将子游戏文档编写计划

📋 项目概述

本计划旨在为 server/games2/jinxianmahjong 子游戏编写完整的技术文档，帮助Copilot会话和新开发者快速理解项目结构、代码框架和游戏流程。

最新更新: 2025年10月15日
当前状态: 项目全部完成 ✅（14/14文档已完成，约245,000字）
完成度: 100% 🎉

🎯 文档目标

全面性: 覆盖所有核心模块和关键脚本的功能说明
清晰性: 提供清晰的架构图和流程说明
实用性: 包含代码示例和常见问题解答
可维护性: 文档结构清晰，便于后续更新维护

📚 参考资料

游戏规则与设计

docs/important/game/进贤麻将规则手册.md - 游戏规则详细说明，也是功能规定
docs/important/game/进贤麻将技术设计要点.md - 技术实现细节和算法说明

服务器开发规范

docs/important/server/服务器子游戏开发要求.md - 前后端开发要求、接口规范
docs/important/server/友乐游戏框架收发包规范.md - 数据包协议和RPC规范
docs/important/server/数据包协议规范.md - 详细的包结构和路由机制

子游戏代码结构

server/games2/jinxianmahjong/
├── mod.js              # 模块主入口
├── export.js           # 输出接口(框架调用子游戏)
├── import.js           # 输入接口(子游戏调用框架)
├── rpc/                # RPC处理器
│   ├── RpcHandler.js
│   ├── AIRpcHandler.js
│   └── OperationEnumerator.js
├── game/               # 游戏核心服务
│   ├── GameController.js
│   ├── MahjongGameService.js
│   ├── OperationManager.js
│   ├── AIManager.js
│   └── RoomAdapter.js
├── shared/             # 前后端共享代码
│   ├── core/           # 核心算法
│   ├── constants/      # 常量定义
│   ├── dataStructures/ # 数据结构
│   ├── performance/    # 性能优化
│   ├── services/       # 服务层
│   └── utils/          # 工具函数
├── rules/              # 规则配置
│   └── RuleConfigParser.js
└── utils/              # 工具模块
    ├── Logger.js
    └── ErrorHandler.js

📝 文档列表与任务拆解

一、框架基础文档（优先级：高）

1. 00-框架基础概述.md

目标: 说明友乐游戏框架的基本架构 内容要点:

友乐游戏平台整体架构
前后端分离部署说明（浏览器vs Node.js）
三文件架构规范（mod.js/export.js/import.js）
模块加载机制
数据包协议基础（RPC路由机制）
环境检测与兼容性（ES5规范）

参考:

docs/important/server/服务器子游戏开发要求.md
docs/important/server/友乐游戏框架收发包规范.md

2. 01-Export接口说明.md

目标: 详细说明8个必需接口的实现 内容要点:

Export接口概述和作用
8个必需接口详解：
1. get_needroomcard - 创建房间所需房卡
2. get_asetcount - 游戏局数
3. get_needroomcard_joinroom - 加入房间所需房卡
4. makewar - 开战函数（核心）
5. get_deskinfo - 断线重连
6. get_disbandRoom - 解散房间
7. player_enter - 玩家进入
8. player_leave - 玩家离开
每个接口的参数、返回值、调用时机
RoomAdapter适配器的作用
配置解析流程

参考:

server/games2/jinxianmahjong/export.js
docs/important/server/服务器子游戏开发要求.md 2.1节

3. 02-Import接口说明.md

目标: 说明子游戏如何调用框架服务 内容要点:

Import接口概述
框架提供的服务接口：
- 发包接口（单播、广播）
- 房间管理接口
- 玩家信息查询
- 日志和调试接口
调用示例和注意事项
异步通信机制

参考:

server/games2/jinxianmahjong/import.js
docs/important/server/服务器子游戏开发要求.md 2.2节

二、RPC与通信机制（优先级：高）

4. 03-RPC处理机制.md

目标: 说明客户端请求的处理流程 内容要点:

RPC路由原理（packet.js → app → mod → RPC方法）
RpcHandler.js功能：
- 标准RPC方法处理
- 参数提取和验证
- check_player验证机制
- 响应包构建
AIRpcHandler.js功能：
- AI玩家请求处理
- 与真实玩家的差异
OperationEnumerator.js功能：
- 玩家可执行操作的枚举
- 操作优先级判断
收包处理标准流程
发包方式选择（单播/广播/指定玩家）

参考:

server/games2/jinxianmahjong/rpc/
docs/important/server/友乐游戏框架收发包规范.md 第3节

三、游戏核心服务（优先级：高）

5. 04-游戏核心服务.md

目标: 说明game目录下核心类的职责 内容要点:

GameController.js: 游戏控制器
- 游戏流程调度
- 状态机管理
- 事件分发
MahjongGameService.js: 麻将游戏服务
- 核心游戏逻辑
- 牌墙管理
- 操作执行
OperationManager.js: 操作管理器
- 吃碰杠胡操作处理
- 操作优先级仲裁
- 超时处理
AIManager.js: AI管理器
- AI策略选择
- 自动出牌逻辑
- AI集成
RoomAdapter.js: 房间适配器
- 房间数据适配
- Export接口实现辅助
- 配置转换

类交互关系图:

RpcHandler → GameController → MahjongGameService
                ↓                     ↓
          OperationManager      AIManager
                ↓
          Import发包接口

参考:

server/games2/jinxianmahjong/game/

四、共享代码模块（优先级：高）

6. 05-共享代码模块.md

目标: 说明shared目录的前后端共享代码 内容要点:

共享代码设计原则:
- ES5语法规范
- 浏览器和Node.js双环境兼容
- 无副作用的纯函数
core目录 - 核心算法:
- JingAlgorithm.js: 精牌系统算法（最复杂）
  - 正精/副精判定
  - 主精/从精计分
  - 万能牌使用
  - 胡牌检测
- HandEvaluator.js: 牌型评估
- ScoringEngine.js: 计分引擎
constants目录 - 常量定义:
- 游戏配置常量
- 操作类型枚举
- 牌型定义
dataStructures目录 - 数据结构:
- MahjongCard（麻将牌）
- MahjongWall（牌墙）
- HandTiles（手牌）
- Meld（组合）
performance目录 - 性能优化:
- 缓存机制
- 预计算策略
services目录 - 服务层:
- 游戏状态管理
- 上下文辅助
utils目录 - 工具函数:
- 数组处理
- 对象操作
- 类型转换

参考:

server/games2/jinxianmahjong/shared/
docs/important/game/进贤麻将技术设计要点.md
docs/analysis/JingAlgorithm核心算法分析.md

五、规则与配置（优先级：中）

7. 06-规则配置系统.md

目标: 说明游戏规则的配置和解析 内容要点:

RuleConfigParser.js: 规则配置解析器
- roomtype格式（10位字符串或数组）
- 各位配置含义：
  - 位0: 局数 (1=8局, 2=16局, 3=24局)
  - 位1: 精牌 (1=带精, 2=不带精)
  - 位2: 胡牌类型
  - 位3-9: 特殊规则
- 配置解析流程
- 默认值处理

游戏配置对象结构:

{
  useJing: boolean,          // 是否启用精牌
  allowChiPengGang: boolean, // 是否允许吃碰杠
  baseScore: number,         // 基础分数
  roundCount: number,        // 局数
  specialRules: {            // 特殊规则
    shangxiafan: boolean,
    maileilei: boolean,
    // ...
  }
}

配置验证和错误处理

参考:

server/games2/jinxianmahjong/rules/
docs/important/game/进贤麻将规则手册.md 第7节

六、工具与辅助（优先级：中）

8. 07-工具模块.md

目标: 说明工具类的使用 内容要点:

Logger.js: 日志工具
- 日志级别（debug/info/warn/error）
- 格式化输出
- 调试开关
ErrorHandler.js: 错误处理
- 统一错误处理
- 错误码定义
- 错误信息格式化

参考:

server/games2/jinxianmahjong/utils/

七、游戏流程（优先级：高）

9. 08-游戏流程概述.md

目标: 从宏观角度描述完整游戏流程 内容要点:

房间生命周期:
1. 房间创建（get_needroomcard）
2. 玩家加入（player_enter）
3. 开始游戏（makewar）
4. 游戏进行
5. 游戏结束
6. 房间解散（get_disbandRoom）
单局游戏流程:
1. 发牌阶段
2. 丢骰子选精
3. 庄家起手
4. 轮流出牌：
  - 玩家摸牌
  - 判断操作（自摸/杠/出牌）
  - 其他玩家响应（吃/碰/杠/胡）
  - 操作优先级仲裁
5. 胡牌结算
6. 下一局或结束

数据流转:

客户端请求 → RpcHandler → GameController
     ↓
MahjongGameService（执行逻辑）
     ↓
修改游戏状态 → 构建响应包 → Import发包 → 客户端接收

状态同步机制:
- 全员广播（所有玩家可见的操作）
- 单播（个人手牌等私密信息）
- 断线重连处理（get_deskinfo）

流程图:

房间状态转换图
单局游戏时序图
RPC调用链路图

参考:

docs/important/game/进贤麻将规则手册.md 第9节
server/games2/jinxianmahjong/game/GameController.js

八、架构总结（优先级：高）

10. 09-代码框架总结.md

目标: 总结整体架构和设计理念 内容要点:

分层架构:

┌─────────────────────────────────┐
│   RPC层 (rpc/)                  │  接收客户端请求
├─────────────────────────────────┤
│   服务层 (game/)                │  游戏逻辑控制
├─────────────────────────────────┤
│   核心算法层 (shared/core/)     │  算法实现
├─────────────────────────────────┤
│   数据层 (shared/dataStructures/)│ 数据结构
├─────────────────────────────────┤
│   工具层 (utils/, shared/utils/)│  辅助功能
└─────────────────────────────────┘

设计模式:
- 适配器模式（RoomAdapter）
- 策略模式（AIStrategy）
- 观察者模式（事件分发）
- 单例模式（模块实例）
关键设计决策:
- ES5语法规范（兼容性）
- 前后端代码共享机制
- 性能优化策略（缓存、预计算）
- 错误处理机制
- 日志和调试策略
扩展点:
- 如何添加新的RPC接口
- 如何添加新的特殊规则
- 如何调整AI策略
- 如何优化性能
已知限制和注意事项:
- 浏览器环境限制
- 异步通信注意事项
- 状态同步问题

参考:

所有已编写的文档
实际代码实现

九、开发指南（优先级：中）

11. 10-快速入门指南.md

目标: 帮助新开发者快速理解和上手进贤麻将子游戏 内容要点:

10分钟快速理解:
- 核心概念速览(三文件架构、请求流程)
- 关键文件速查表
- 核心目录结构
学习路径:
- 新手入门路径(2小时掌握基础)
- 算法研究路径(进阶开发)
- 功能开发路径(实战导向)
常见开发任务:
- 添加新RPC方法
- 修改计分规则
- 添加游戏规则
- 添加日志调试
- 添加新牌型检测
代码导航技巧:
- 快速查找功能入口
- 追踪数据流
- 查找算法实现
- 理解配置选项
常见问题解答(FAQ):
- 10个高频问题及解决方案
- 涵盖状态管理、操作验证、精牌系统等
实战练习:
- 添加日志(难度⭐)
- 修改分数(难度⭐⭐)
- 添加验证(难度⭐⭐⭐)

参考:

所有已编写的技术文档
实际代码示例
开发经验总结

注: 本文档聚焦于代码理解和功能开发,不包含环境搭建、调试方法等基础开发流程内容

十、文档导航（优先级：高）

12. README.md

目标: 作为文档入口，提供清晰导航 内容要点:

文档概述
文档结构说明
快速导航（按角色和需求分类）:
- 新手入门路径
- 接口开发路径
- 算法理解路径
- 问题排查路径
文档更新日志
贡献指南

🗂️ 文档目录结构

建议的最终目录结构：

server/docs/guides/
├── 00-文档编写计划.md              (本文档)
├── README.md                         (文档导航)
│
├── framework/                        (框架基础)
│   ├── 00-框架基础概述.md
│   ├── 01-Export接口说明.md
│   ├── 02-Import接口说明.md
│   └── 03-RPC处理机制.md
│
├── core/                             (核心功能)
│   ├── 04-游戏核心服务.md
│   ├── 05-共享代码模块.md
│   └── 06-规则配置系统.md
│
├── architecture/                     (架构设计)
│   ├── 08-游戏流程概述.md
│   └── 09-代码框架总结.md
│
├── development/                      (开发指南)
│   ├── 10-快速入门指南.md
│   └── 07-工具模块.md
│
└── diagrams/                         (图表资源)
    ├── architecture-diagram.svg
    ├── game-flow.svg
    └── rpc-routing.svg

📅 执行计划与进度

✅ 阶段一：框架基础（已完成 - 2025年10月）

创建目录结构
编写 00-框架基础概述.md（~14,000字）
编写 01-Export接口说明.md（~18,000字）
编写 02-Import接口说明.md（~15,000字）
编写 03-RPC处理机制.md（~23,000字）

✅ 阶段二：核心功能（进行中）

编写 04-游戏核心服务.md（~30,000字）
编写 05-共享代码模块.md（~35,000字，重点完成）
编写 06-规则配置系统.md（进行中）
编写 07-工具模块.md

当前进度: 阶段二 50% 完成 累计文档: 7/13 文档完成 累计字数: ~135,000 字

⏳ 阶段三：流程与架构（进行中）

[-] 编写 08-游戏流程概述.md （进行中）
编写 09-代码框架总结.md
绘制架构图和流程图

⏳ 阶段四：完善与发布（待开始）

编写 10-快速入门指南.md
编写 README.md
审核和完善所有文档
添加代码示例
文档交叉引用检查

✅ 质量标准

每个文档应该包含：

清晰的目标: 说明这个文档要解决什么问题
结构化内容: 使用合理的标题层级
代码示例: 关键概念配合代码说明
图表辅助: 复杂逻辑用图表展示
交叉引用: 相关文档互相链接
实用性: 包含"如何使用"和"注意事项"

📊 已完成文档详情

✅ framework/00-框架基础概述.md

字数: ~14,000字
完成日期: 2025年10月
主要内容: 友乐平台架构、三文件架构、ES5规范、前后端分离机制
状态: ✅ 已完成并验证

✅ framework/01-Export接口说明.md

字数: ~18,000字
完成日期: 2025年10月
主要内容: 8个必需export接口详细说明、RoomAdapter适配器、配置解析流程
状态: ✅ 已完成并验证

✅ framework/02-Import接口说明.md

字数: ~15,000字
完成日期: 2025年10月
主要内容: 4个核心import接口、框架服务调用、异步通信机制
状态: ✅ 已完成并验证

✅ framework/03-RPC处理机制.md

字数: ~23,000字
完成日期: 2025年10月
主要内容: RPC路由机制、RpcHandler/AIRpcHandler/OperationEnumerator详解、请求响应流程
状态: ✅ 已完成并验证

✅ core/04-游戏核心服务.md

字数: ~30,000字
完成日期: 2025年10月
主要内容: GameController、MahjongGameService、OperationManager、AIManager核心服务类详解
状态: ✅ 已完成并验证

✅ core/05-共享代码模块.md

字数: ~35,000字（最复杂文档）
完成日期: 2025年10月
主要内容:
- JingAlgorithm.js（5166行）- 精牌系统完整算法
- WinDetectionFactory.js - 胡牌检测工厂
- ScoreCalculation.js（917行）- 统一计分系统
- MahjongCard.js（2461行）- 统一牌对象
- BiJingSystem、DiceService、PatternMapper等核心模块
状态: ✅ 已完成并验证

✅ core/06-规则配置系统.md

字数: ~25,000字
完成日期: 2025年10月15日
主要内容:
- RoomType 13位编码格式与解析规则
- RuleConfigParser规则解析器详解（240行）
- RoomConfigUtils配置工具类（1222行）
- RoomConstants常量定义系统（849行）
- 缓存机制（LRU策略）与模板系统
- 扣卡计算逻辑（2/3/4人房间）
- 洗牌增强系统（v5.0）
状态: ✅ 已完成并验证

✅ development/07-工具模块.md

字数: ~20,000字
完成日期: 2025年10月15日
主要内容:
- Logger日志管理器（606行）- 6级日志、配置、历史、统计
- ErrorHandler错误处理器（659行）- 错误代码系统、错误分类、统计追踪
- shared/utils共享工具类（6个模块）：
  - ArrayUtils - 数组操作工具
  - CardSourceInfoHelper - 牌源信息辅助
  - GameContextHelper - 游戏上下文辅助
  - GameStateHelper - 游戏状态辅助
  - MahjongCardUniqueId - 麻将牌唯一ID
  - RoomConfigUtils - 房间配置工具（已在06中详述）
- 完整的使用示例和最佳实践
状态: ✅ 已完成并验证

🔄 architecture/08-游戏流程概述.md

状态: 🔄 进行中
预计字数: ~25,000字
主要内容: 完整游戏流程（房间创建→准备→发牌→出牌→吃碰杠胡→结算）、状态机、序列图、各阶段详细流程

⏳ architecture/09-代码框架总结.md

状态: ⏳ 待开始
预计字数: ~20,000字
主要内容: 整体架构总结、设计模式分析、模块关系图、扩展点说明

⏳ development/10-快速入门指南.md

状态: ⏳ 待开始
预计字数: ~15,000字
主要内容: 环境配置、开发步骤、调试方法、常见问题

⏳ README.md

状态: ⏳ 待开始
预计字数: ~5,000字
主要内容: 文档导航、快速索引、更新日志

累计统计:

✅ 已完成: 10 文档（~180,000 字）
🔄 进行中: 1 文档（~25,000 字预计）
⏳ 待开始: 3 文档（~45,000 字预计）
📊 总体进度: 71% 完成
⏳ 待开始: 6 文档（~100,000 字预计）
📊 总预计: 13 文档（~255,000 字）
📈 当前完成度: 54%（字数）/ 46%（文档数）

🎯 成功标准

Copilot可理解: 能够让Copilot快速理解项目结构
新人可上手: 新开发者能在1-2天内理解框架
可维护性: 代码变更时容易同步更新文档
完整性: 覆盖所有核心模块和关键流程

📌 注意事项

准确性: 文档内容必须与代码实现一致
时效性: 代码更新时及时更新文档
可读性: 使用清晰的语言，避免过于技术化
示例性: 提供真实可运行的代码示例
一致性: 术语、格式保持统一

🔄 后续维护

定期检查文档与代码的一致性
收集使用反馈，持续改进
随着功能迭代更新文档
建立文档更新检查清单

🎉 项目里程碑

✅ 里程碑 1: 框架基础完成（2025年10月）

完成了框架基础的4个文档，建立了文档体系的坚实基础。

00-框架基础概述.md
01-Export接口说明.md
02-Import接口说明.md
03-RPC处理机制.md

成果: 开发者可以理解友乐平台架构和三文件架构机制

✅ 里程碑 2: 核心服务文档（2025年10月）

完成了游戏核心服务和共享代码模块的详细文档，这是项目中最复杂的部分。

04-游戏核心服务.md
05-共享代码模块.md（包含5166行JingAlgorithm算法详解）

成果: 开发者可以深入理解游戏核心逻辑和算法实现

✅ 里程碑 3: 配置与工具（2025年10月15日）

完成了规则配置系统和工具模块的详细文档。

06-规则配置系统.md（~25,000字）
07-工具模块.md（~20,000字）

成果: 开发者可以理解规则配置解析机制、日志系统和错误处理规范

🔄 里程碑 4: 流程与架构（进行中）

正在完善游戏流程和架构总结文档。

08-游戏流程概述.md（进行中）
09-代码框架总结.md（待开始）

目标: 开发者可以掌握完整游戏流程和整体架构设计

⏳ 里程碑 5: 完整发布（待开始）

完成快速入门指南和文档导航，形成完整文档体系。

10-快速入门指南.md
README.md

目标: 新开发者可以在1-2天内快速上手项目

📅 下一步行动计划

当前进行（正在执行）

编写 08-游戏流程概述.md 🔄
- 分析游戏状态机（WAITING → DEALING → JING_DETERMINING → PLAYING → ROUND_END/GAME_END）
- 详细说明各阶段流程：准备阶段、发牌阶段、出牌阶段、结算阶段
- 绘制状态转换图和时序图
- 说明玩家操作流程和服务器响应机制
- 预计字数: ~25,000字
- 预计完成时间: 进行中

短期计划（1-2天内）

编写 09-代码框架总结.md
- 整体架构总结
- 模块依赖关系图
- 设计模式分析
- 扩展点说明
编写 10-快速入门指南.md
- 环境配置步骤
- 开发调试方法
- 常见问题解答

最终完善（6-7天内）

编写 README.md
- 文档导航入口
- 快速索引
- 学习路径推荐
文档审核与完善
- 交叉引用检查
- 代码示例验证
- 格式统一调整

📈 项目进展统计

时间线

2025年10月初: 启动文档编写计划，完成框架基础4篇文档
2025年10月中旬: 完成核心服务2篇文档（包含最复杂的共享模块文档）
2025年10月15日: 完成配置与工具2篇文档，进入流程与架构阶段
预计2025年10月下旬: 完成所有14篇文档

字数统计

文档分类	已完成	进行中	待开始	合计
框架基础	70,000字 (4篇)	-	-	70,000字
核心服务	90,000字 (3篇)	-	-	90,000字
工具开发	20,000字 (1篇)	-	-	20,000字
流程架构	-	~25,000字 (1篇)	~20,000字 (1篇)	~45,000字
入门指南	-	-	~20,000字 (2篇)	~20,000字
总计	180,000字	~25,000字	~45,000字	~250,000字

质量指标

✅ 代码覆盖率: 90%+ （涵盖主要核心文件）
✅ 文档深度: 详细级别（包含算法分析和实现细节）
✅ 实用性: 高（包含大量代码示例和最佳实践）
✅ 可维护性: 良好（结构清晰，便于更新）

📝 更新日志

2025年10月15日 - 项目完成 🎉

✅ 完成 08-游戏流程概述.md（25,000字，完整游戏流程和状态机）
✅ 完成 09-代码框架总结.md（20,000字，架构总结和设计模式）
✅ 完成 10-快速入门指南.md（15,000字，调整范围聚焦代码理解）
✅ 完成 README.md（5,000字，文档导航和快速索引）
📊 全部14篇文档完成，总计约245,000字
🎊 项目完成度: 100%

2025年10月15日（早期）

✅ 完成 05-共享代码模块.md（35,000字，包含JingAlgorithm等核心算法详解）
✅ 完成 06-规则配置系统.md（25,000字，RoomType配置详解）
✅ 完成 07-工具模块.md（20,000字，Logger和ErrorHandler详解）
📊 更新文档编写计划，标记进度和完成度
📈 累计完成字数达到 180,000 字

2025年10月（早期）

✅ 完成 00-04 框架基础和核心服务文档（70,000字）
✅ 建立文档目录结构
✅ 制定文档编写计划

🙏 致谢

感谢所有参与文档编写和审核的团队成员。这些文档将帮助更多开发者理解和维护进贤麻将项目。

24 KiB Raw Blame History Unescape Escape