麻将计分器 (Mahjong Calculator)

一个现代化的麻将计分应用，支持多设备实时同步，无需服务器即可在朋友间共享游戏状态。

✨ 功能特性

核心功能

• 🎮 实时计分 - 快速记录每局胡牌结算
• 📊 排行榜 - 实时显示玩家排名和分数
• 📜 历史记录 - 完整的结算历史，支持撤回操作
• 🔄 桌面旋转 - 适配不同座位视角
• 🎯 类型识别 - 自动识别胡牌、开杠、中发白

高级功能

• 🌐 多房间支持 - 支持通过 URL 创建任意数量的独立房间
• ⚡ 实时同步 - 基于 Socket.IO 的低延迟同步，确保所有玩家状态一致
• 💾 数据持久化 - 游戏进度自动保存在服务器硬盘（data/ 目录），掉线、重启都不会丢失
• 📱 响应式设计 - 完美适配手机和平板
• 🐳 自动化部署 - Push 代码自动构建 Docker 镜像

🚀 快速开始

方式一：CasaOS 部署（最推荐）

这是最适合家庭服务器的部署方式。

1. 打开 CasaOS App Store -> Custom Install

2. 填写以下配置：

   • Docker Image: bbblq/mahjong-calculator:latest
   • App Name: Mahjong
   • Web UI Port: 80 (对应主机端口可随意，如 8888)

3. 关键配置 - 数据持久化：

   • 在 Volumes 部分添加：
     • Host: /DATA/AppFiles/Mahjong (或者任何你想要保存数据的路径)
     • Container: /app/data

   ⚠️ 注意：如果不挂载这个卷，重启容器后游戏记录会丢失！

4. 点击 Install 即可。

方式二：Docker 命令部署

docker run -d \
  --name mahjong \
  -p 8888:80 \
  -v ./mahjong-data:/app/data \
  --restart unless-stopped \
  bbblq/mahjong-calculator:latest

方式三：开发与贡献

本项目配置了完整的 CI/CD 流程。

1. Fork 本仓库
2. 修改代码
3. 推送到 GitHub
   • GitHub Actions 会自动触发
   • 自动构建前端和后端
   • 自动打包 Docker 镜像并推送
   • latest 镜像永远保持最新

📖 使用说明

多房间机制

你可以通过以下任何一种方式进入特定的房间，不同房间的数据完全独立：

1. URL 路径: http://your-server/room1
2. URL Hash: http://your-server/#/room1
3. 查询参数: http://your-server/?room=room1

默认为 default 房间。

开始游戏

1. 设置玩家姓名

   • 点击左下角设置按钮
   • 编辑四个方位的玩家姓名
   • 点击保存

2. 记录结算

   • 点击胜者的姓名标签
   • 选择结算类型（胡牌/开杠/中发白）
   • 调整各家支付分数
   • 点击"确认结算"

3. 查看历史

   • 底部面板显示所有结算记录
   • 点击"撤回"按钮可撤销最后一次操作

4. 多设备同步

   • 在同一局域网内打开应用
   • 只要 URL 中的房间名一致，所有设备自动连接并同步

🛠️ 技术栈

• 前端框架: React 18
• 构建工具: Vite 5
• 通信协议: Socket.IO (WebSocket)
• 后端运行时: Node.js + Express
• 部署: Docker (Node.js Environment)

📦 项目结构

mahjong-calculator/
├── server/              # Node.js 后端
│   ├── index.js        # 服务器入口 (Socket.io + Express)
│   └── package.json    # 后端依赖
├── src/                 # React 前端
│   ├── hooks/useGameSync.js  # 核心同步逻辑
│   └── ...
├── .github/workflows/   # CI/CD 配置
│   └── docker-publish.yml # 自动构建脚本
└── Dockerfile          # 全栈镜像构建配置

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情

📧 联系方式

享受游戏！🀄