d1kt/MINESWEEPER_README.md

扫雷游戏功能说明

功能概述

已成功添加经典Windows扫雷游戏到项目中,支持三种难度级别,并提供排行榜功能。

新增文件

后端文件

1. server/models/MinesweeperRecord.ts - 扫雷游戏记录数据模型
2. server/routes/minesweeper.ts - 扫雷游戏API路由

前端文件

1. src/components/MinesweeperGame.tsx - 扫雷游戏主界面组件
2. src/components/MinesweeperLeaderboard.tsx - 扫雷排行榜组件

修改的文件

1. server/server.ts - 添加扫雷路由注册
2. src/App.tsx - 添加扫雷游戏路由
3. src/components/Navbar.tsx - 添加扫雷游戏菜单

功能特性

1. 三种难度级别

• 初级 (9×9, 10雷): 适合新手玩家
• 中级 (16×16, 40雷): 适合有经验的玩家
• 高级 (16×30, 99雷): 适合专家级玩家

2. 游戏功能

• ✅ 经典扫雷游戏规则
• ✅ 左键点击揭开格子,右键点击插旗
• ✅ 首次点击保护(首次点击位置及周围不会有雷)
• ✅ 自动展开无雷区域
• ✅ 计时功能
• ✅ 剩余旗帜数量显示
• ✅ 游戏胜利/失败判定
• ✅ 个人最佳成绩显示

3. 排行榜功能

• ✅ 按难度分类排行
• ✅ 显示最佳时间、总游戏次数、获胜次数、胜率
• ✅ 前三名特殊标记(🥇🥈🥉)
• ✅ 分页显示
• ✅ 只统计获胜记录
• ✅ 实时更新

4. 数据统计

• ✅ 自动保存游戏记录(需登录)
• ✅ 个人最佳成绩追踪
• ✅ 游戏统计数据

访问路径

游戏页面

• 路径: /minesweeper
• 说明: 扫雷游戏主界面,可选择难度开始游戏

排行榜页面

• 路径: /minesweeper/leaderboard
• 说明: 查看各难度级别的排行榜

导航菜单

在顶部导航栏中新增"扫雷游戏"菜单,包含两个子菜单:

• 开始游戏
• 排行榜

API端点

后端API

1. 提交游戏记录

• URL: POST /api/minesweeper/record
• 需要登录: 是
• 参数:

  {
    "difficulty": "beginner|intermediate|expert",
    "timeSeconds": 123,
    "won": true
  }
  

2. 获取排行榜

• URL: GET /api/minesweeper/leaderboard/:difficulty?page=1&limit=10
• 需要登录: 否
• 示例: /api/minesweeper/leaderboard/beginner?page=1&limit=10

3. 获取个人最佳成绩

• URL: GET /api/minesweeper/personal-best/:difficulty
• 需要登录: 是
• 示例: /api/minesweeper/personal-best/beginner

4. 获取游戏统计

• URL: GET /api/minesweeper/stats
• 需要登录: 是

数据库集合

MinesweeperRecord

存储所有游戏记录,字段包括:

• userId: 用户ID
• username: 用户名
• fullname: 姓名
• difficulty: 难度级别
• timeSeconds: 完成时间(秒)
• won: 是否获胜
• createdAt: 创建时间
• updatedAt: 更新时间

使用说明

游戏规则

1. 点击格子揭开,数字表示周围8个格子中地雷的数量
2. 右键点击插旗标记可能的地雷位置
3. 揭开所有非地雷格子即可获胜
4. 点到地雷则游戏失败

登录与记录

• 游客可以玩游戏,但不会保存记录
• 登录用户的游戏记录会自动保存
• 只有获胜的记录才会计入排行榜
• 排行榜按最佳完成时间排序

个人最佳

• 登录用户可以在游戏界面看到个人最佳成绩
• 打破个人记录时会有特殊提示

技术实现

前端技术

• React + TypeScript
• Material-UI组件库
• 状态管理: useState, useEffect, useCallback
• 游戏逻辑: 纯客户端实现

后端技术

• Express路由
• MongoDB数据存储
• Mongoose聚合查询
• JWT认证(可选,支持游客模式)

游戏算法

• 随机地雷生成(避开首次点击区域)
• 深度优先搜索展开无雷区域
• 周围地雷数量计算

性能优化

1. 索引优化: 在userId和difficulty字段上创建索引
2. 聚合查询: 使用MongoDB聚合管道高效计算排行榜
3. 分页加载: 排行榜支持分页,默认每页10条记录
4. 客户端渲染: 游戏逻辑完全在客户端运行,不占用服务器资源

未来扩展建议

1. 添加游戏暂停/继续功能
2. 支持键盘快捷键操作
3. 添加音效和动画效果
4. 支持自定义皮肤主题
5. 添加每日挑战模式
6. 支持好友对战功能
7. 添加成就系统

注意事项

1. 游戏记录只在登录状态下保存
2. 排行榜只统计获胜的记录
3. 首次点击位置及周围不会有地雷(防止首次点击即失败)
4. 右键菜单被劫持用于插旗,如需访问浏览器右键菜单,请在游戏区域外点击