# mj **Repository Path**: duling/mj ## Basic Information - **Project Name**: mj - **Description**: No description available - **Primary Language**: Unknown - **License**: AFL-3.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-03-28 - **Last Updated**: 2026-07-14 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # MAJIANG 项目功能介绍 > **项目名称**：MJGame（血流成河·血战到底） > **仓库地址**：[gitee.com/duling/mj](https://gitee.com/duling/mj) > **项目定位**：商用级多人在线四川麻将游戏平台，支持 2000 人级在线 > **当前状态**：混合架构阶段（本地运行时 + Redis 持久化基线），UI 迁移进行中 --- ## 一、项目总览 MAJIANG 是一款面向商用上线的**四川麻将游戏平台**，采用前后端分离 + 游戏客户端的**三端架构**，支持"血战到底"和"血流成河"双玩法，并扩展支持广东麻将、斗地主、跑胡子、牛牛、德州扑克、扎金花、十三水等共 **8 种棋牌游戏**。 ### 架构全景 ``` ┌──────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐ │ AdminUI │────>│ AdminHost │ │ ApiHost │ │ (Vue3 + Vite) │ │ (.NET 10 / Kestrel) │ │ (.NET 10 / Kestrel)│ │ 管理后台 :8080 │ │ 管理 API │ │ 玩家API + SignalR │ └──────────────────┘ └──────────┬───────────┘ └──────────┬───────────┘ │ │ └──────────┬──────────────────┘ │ ┌──────────▼───────────┐ │ MJGame.Domain │ │ (领域层) │ │ · Auth 认证 │ │ · Game 游戏引擎 │ │ · Social 社交 │ │ · Match 匹配 │ │ · Shop 商城 │ │ · Admin 风控管理 │ │ · SystemConfig 配置 │ └──────────┬───────────┘ │ ┌──────────▼───────────┐ │ FreeSql + Redis │ │ (MySQL + 多库Redis) │ └──────────────────────┘ ┌──────────────────┐ │ UI │────> HTTP REST + SignalR │ (Godot 4.6) │ (BackendApiClient + RealtimeClient) │ C# / .NET 8 │ └──────────────────┘ ``` --- ## 二、技术栈 | 层级 | 技术 | 说明 | |------|------|------| | **管理后台** | Vue 3.5 + TypeScript 5.9 + Vite 7 | 基于 vue-pure-admin 模板 | | **UI 框架** | Element Plus 2.11 + Tailwind CSS 4.1 | 管理后台 UI | | **图表** | ECharts 6 | 风控数据可视化 | | **后端框架** | ASP.NET Core (.NET 10) | 双宿主部署 | | **ORM** | FreeSql | 支持 InMemory / MySQL 双实现 | | **缓存** | Redis 6.0+（主从+哨兵） | DB0 房间/DB1 锁/DB2 匹配，三库隔离 | | **数据库** | MySQL 8.0 | 财务唯一权威数据源 | | **实时通信** | SignalR | WebSocket 长连接 | | **认证** | JWT Bearer | AccessToken + RefreshToken | | **任务调度** | Hangfire | 后台作业 | | **日志** | NLog | 结构化日志 | | **游戏客户端** | Godot 4.6 + C# (.NET 8) | 纯展示层，防作弊 | | **物理引擎** | Jolt Physics | 3D 物理效果 | | **平台** | Windows (d3d12) / Android | 跨平台 | | **开发工具** | godot-mcp-bridge | AI 辅助 Godot 开发 | --- ## 三、核心功能模块 ### 3.1 游戏玩法系统 #### 四川麻将双玩法 | 维度 | 血战到底 | 血流成河 | |------|---------|---------| | **胡牌** | 胡后离场，终止操作 | 胡后保留手牌继续，可多次胡 | | **一炮多响** | 仅 1 人胡，逆时针优先 | 多人同时胡，各自结算 | | **对局人数** | 胡 1 人离场 1 人 | 全程 4 人满桌 | | **结束条件** | 3 家胡 / 剩 1 人 / 牌墙空 | 仅牌墙摸空 | | **缺门违规** | 无法参与胡牌判定 | 判定为花猪处罚 | | **查大叫** | 仅对未胡牌玩家 | 对所有听牌玩家（含已胡） | #### 基础规则 - 4 人对局，**108 张牌**（筒/条/万，无风牌字牌） - 支持操作：**胡、明杠、暗杠、补杠**；严禁吃牌 - 胡牌优先级：**自摸 > 抢杠胡 > 杠上炮 > 点炮** - 起胡线：**无最低番数限制** #### 番型与计分 | 番型 | 倍数 | |------|------| | 平胡 | 1 倍 | | 对对胡 | 2 倍 | | 清一色 | 3 倍 | | 小七对 | 3 倍 | | 龙七对 | 4 倍 | | 杠上花 / 杠上炮 / 抢杠胡 | +2 倍 | | 海底捞月 | +2 倍 | #### 杠分规则（刮风下雨） | 杠类型 | 扣分规则 | |--------|----------| | 直杠 | 放杠者扣 2 倍底分 | | 补杠 | 其余 3 家各扣 1 倍底分 | | 暗杠 | 其余 3 家各扣 2 倍底分 | #### 特殊处罚 - **花猪**：未按规则缺门的玩家，赔付所有玩家 3 倍底分 - **查大叫**：对听牌未胡玩家，按最大番型计分 #### 对局前置阶段 | 阶段 | 倒计时 | 说明 | |------|--------|------| | 换三张 | 20s | 选择 3 张同花色牌交换 | | 定缺 | 20s | 选择一种花色作为缺门 | | 出牌 | 15s | 每回合出牌限时 | | 胡杠碰响应 | 15s | 响应操作限时 | | 离线重连 | 30s | 超时自动切托管 | #### 多游戏支持 | 规则集 | 游戏名称 | |--------|----------| | `blood-battle` | 血战到底（默认） | | `blood-river` | 血流成河 | | `guang-dong-mahjong` | 广东麻将 | | `pao-hu-zi` | 跑胡子 | | `dou-di-zhu` | 斗地主 | | `zha-jin-hua` | 扎金花 | | `niu-niu` | 牛牛 | | `texas-holdem` | 德州扑克 | | `shi-san-shui` | 十三水 | --- ### 3.2 胜率调控系统（核心风控引擎） 这是项目的**核心差异化功能**，通过偏置算法控制玩家胜率体验。 #### 用户分层目标 | 用户群体 | 默认目标胜率 | |---------|-------------| | 新用户（7 天内） | 55% | | 流失召回用户 | 60% | | 低活跃用户 | 52% | | 付费/高活跃用户 | 无目标（正常随机） | #### 偏置手段 | 偏置方式 | 机制 | 作用域 | |----------|------|--------| | **洗牌局部调牌** | 基于孤张→局部支持度做最多 N 次换牌 | 洗牌阶段 | | **摸牌偏置** | 5% 概率优先摸听牌 | 目标用户已听牌场景 | | **AI 出牌偏置** | 3% 概率优先打目标用户听牌 | 仅 AI 托管对手 | #### 防察觉兜底 - **连胜限制**：超过最大连胜局数自动抑制 - **月度胜率封顶**：上限 70% / 下限 30% - **大牌限制**：仅偏置小牌听口，避免大牌操控痕迹 - **Rollout 分桶**：80% 命中 / 20% 不开启灰度 - **风控自动禁用**：异常指标触发自动关闭偏置 #### 11 项可配置参数 | 配置键 | 说明 | |--------|------| | `winrate.strategy.enabled` | 总开关 | | `winrate.strategy.draw_bias_percent` | 摸牌偏置百分比 | | `winrate.strategy.discard_bias_percent` | 出牌偏置百分比 | | `winrate.strategy.rollout_percent` | 灰度发布百分比 | | `winrate.strategy.risk_auto_disable_enabled` | 风控自动禁用 | | `winrate.strategy.monthly_win_rate_cap_percent` | 月度胜率上限 | | `winrate.strategy.monthly_win_rate_floor_percent` | 月度胜率下限 | | `winrate.strategy.monthly_win_rate_min_rounds` | 月度最小局数 | | `winrate.strategy.max_consecutive_wins` | 最大连胜局数 | | `winrate.strategy.shuffle_bias_exchange_limit` | 洗牌偏置交换限制 | | `winrate.strategy.big_hand_fan_threshold` | 大番阈值 | --- ### 3.3 房间管理系统 | 功能 | 说明 | |------|------| | 创建房间 | 选择规则集、底分、局数等参数 | | 加入房间 | 房号加入 / 匹配加入 | | 准备/取消 | 玩家准备状态切换 | | 房主转移 | 房主离开时自动转移 | | 投票解散 | 发起投票、全员同意方可解散 | | 金币匹配 | 自动匹配同段位玩家 | --- ### 3.4 断线重连与 AI 托管 | 功能 | 说明 | |------|------| | **快照机制** | Redis 存储完整牌局快照 + 增量同步 | | **30 秒离线切托管** | 超时自动启动 AI 托管 | | **恢复手动** | 重连后可主动恢复手动控制 | | **AI 托管策略** | 自动缺门 / 听牌判断 / 胡牌 / 安全牌出牌 | | **跨服务器重连** | 支持 A/B 双服务器任意重连 | | **门控刷新** | `TableRealtimeRefreshGate` / `RoomRealtimeRefreshGate` 防重入 | --- ### 3.5 社交系统 | 功能 | API | 说明 | |------|-----|------| | 好友列表 | `GET /api/friends` | 查看好友 | | 好友申请 | `POST /api/friends/apply` | 申请加好友 | | 接受申请 | `POST /api/friends/requests/{id}/accept` | 同意好友 | | 赠送金币 | `POST /api/friends/{uid}/gift-gold` | 好友间赠金 | | 创建队伍 | `POST /api/teams` | 组队开黑 | | 邀请入队 | `POST /api/teams/{id}/invite` | 邀请好友 | | 好友状态 | SignalR `/hubs/friend` | 实时在线状态 | --- ### 3.6 商城系统 | 功能 | API | 说明 | |------|-----|------| | 商品列表 | `GET /api/shop/goods` | 浏览可购买商品 | | 购买商品 | `POST /api/shop/buy` | 下单购买 | --- ### 3.7 排行与战绩 | 功能 | API | 说明 | |------|-----|------| | 金币排行 | `GET /api/rankings/gold` | 金币排行榜 | | 对战排行 | `GET /api/rankings/battle` | 对战积分排行 | | 战绩总览 | `GET /api/records/summary` | 个人战绩统计 | | 邮件系统 | `GET /api/mail/list` | 系统邮件 | --- ### 3.8 运营风控后台 #### 风控总览仪表盘 - 24h 偏置次数统计 - 月度胜率突破告警 - 抑制操作统计 - ECharts 可视化图表 #### 风控事件类型 | 事件类型 | 说明 | |----------|------| | `monthly_cap_breach` | 月度胜率上限突破 | | `monthly_floor_breach` | 月度胜率下限突破 | | `consecutive_wins_exceeded` | 连胜超限 | | `bias_suppression` | 偏置抑制触发 | #### 策略事件类型 | 事件类型 | 说明 | |----------|------| | `tile_bias` | 偏牌操作 | | `winrate_adjust` | 胜率调整 | | `streak_protection` | 连胜保护 | | `losing_catchup` | 败者追赶 | | `tile_suggestion` | 牌型推荐 | #### 审计日志 - 记录所有管理操作（登录、配置更新、启用/禁用） - 支持按操作类型、状态、时间范围筛选 --- ## 四、API 端点一览 ### 4.1 玩家端 API（ApiHost） | 分类 | 端点 | 方法 | |------|------|------| | **认证** | `/api/auth/register` | POST | | | `/api/auth/login` | POST | | | `/api/auth/refresh-token` | POST | | **用户** | `/api/user/profile` | GET | | **大厅** | `/api/lobby/home` | GET | | | `/api/lobby/resume-state` | GET | | **匹配** | `/api/match/gold/start` | POST | | | `/api/match/gold/cancel` | POST | | **房间** | `/api/rooms` | POST | | | `/api/rooms/join` | POST | | | `/api/rooms/{id}` | GET | | | `/api/rooms/{id}/ready` | POST | | | `/api/rooms/{id}/leave` | POST | | | `/api/rooms/{id}/start` | POST | | | `/api/rooms/{id}/dissolve/start` | POST | | | `/api/rooms/{id}/dissolve/vote` | POST | | **游戏** | `/api/games/{id}/snapshot` | GET | | | `/api/games/{id}/reconnect-snapshot` | GET | | | `/api/games/{id}/exchange-three` | POST | | | `/api/games/{id}/ding-que` | POST | | | `/api/games/{id}/play-card` | POST | | | `/api/games/{id}/pass` | POST | | | `/api/games/{id}/peng` | POST | | | `/api/games/{id}/gang` | POST | | | `/api/games/{id}/hu` | POST | | | `/api/games/{id}/chi` | POST | | | `/api/games/{id}/next-round` | POST | | | `/api/games/{id}/leave` | POST | | | `/api/games/{id}/resume-control` | POST | | **好友** | `/api/friends` | GET | | | `/api/friends/apply` | POST | | | `/api/friends/{uid}/gift-gold` | POST | | **队伍** | `/api/teams` | POST | | | `/api/teams/current` | GET | | | `/api/teams/{id}/invite` | POST | | **商城** | `/api/shop/goods` | GET | | | `/api/shop/buy` | POST | | **排行** | `/api/rankings/gold` | GET | | | `/api/rankings/battle` | GET | | **战绩** | `/api/records/summary` | GET | | **邮件** | `/api/mail/list` | GET | ### 4.2 管理端 API（AdminHost） | 端点 | 方法 | 功能 | |------|------|------| | `/admin/auth/login` | POST | 管理员登录 | | `/admin/audits` | GET | 审计日志 | | `/admin/winrate-strategy/configs` | GET | 胜率策略配置列表 | | `/admin/winrate-strategy/configs/{key}` | GET/PUT | 单项配置读写 | | `/admin/winrate-strategy/configs/{key}/enable` | POST | 启用配置 | | `/admin/winrate-strategy/configs/{key}/disable` | POST | 禁用配置 | | `/admin/winrate-strategy/events` | GET | 策略事件 | | `/admin/winrate-strategy/risk-report/summary` | GET | 风控摘要 | | `/admin/winrate-strategy/risk-incidents` | GET | 风控事件 | | `/admin/gameplay-timing/configs` | GET | 时长配置列表 | | `/admin/gameplay-timing/configs/{key}` | GET/PUT | 单项时长配置 | | `/admin/gameplay-timing/configs/{key}/enable` | POST | 启用 | | `/admin/gameplay-timing/configs/{key}/disable` | POST | 禁用 | ### 4.3 SignalR 实时 Hub | Hub 路径 | 功能 | |----------|------| | `/hubs/game` | 牌桌实时状态推送 | | `/hubs/room` | 房间实时状态推送 | | `/hubs/friend` | 好友在线状态 | | `/hubs/team` | 队伍实时通信 | --- ## 五、客户端界面 ### 5.1 页面流程 ``` BootScreen → LoginScreen → LobbyScreen → RoomScreen → TableScreen → FinalResultScreen ↕ ↕ ↕ 各种 Popup 准备/解散 换三张/定缺/操作 ``` ### 5.2 屏幕（Screen） | 屏幕 | 功能 | |------|------| | BootScreen | 启动/加载屏 | | LoginScreen | 登录（账号/注册/游客） | | LobbyScreen | 大厅（匹配/房间/商城/邮件/设置/战绩） | | RoomScreen | 房间等待（准备/邀请/解散投票） | | TableScreen | 牌桌（出牌/碰杠胡/换三张/定缺） | | GenericTableScreen | 通用牌桌（扑克类游戏） | | FinalResultScreen | 最终结果 | ### 5.3 弹窗（Popup） | 弹窗 | 功能 | |------|------| | AccountLoginPopup | 账号登录 | | AccountRegisterPopup | 账号注册 | | CreateRoomPopup | 创建房间 | | JoinRoomPopup | 加入房间 | | MatchPopup | 匹配 | | ExchangeThreePopup | 换三张 | | DingQuePopup | 定缺 | | RoundResultPopup | 单局结果 | | MailPopup | 邮件 | | SettingsPopup | 设置 | | FeedbackPopup | 反馈 | | RulePopup | 规则 | | ShopDataPopup | 商城 | | PortalDataPopup | 战绩排行 | | RoomNoticePopup | 房间通知 | | SharePopup | 分享 | | SimplePopup | 通用简单弹窗 | ### 5.4 牌桌组件 | 组件 | 功能 | |------|------| | TableHandTile | 手牌 | | TableSurfaceTileCard | 桌面牌 | | TableDiscardFlow | 出牌流 | | TableMeldFlow / TableMeldStack | 副露展示 | | TableGangMeldGroup | 杠副露组 | | TableWallTile | 牌墙 | | TableSeatCard | 座位卡 | | TableDiceFace | 骰子 | | TableCountdownDigit | 倒计时 | | TablePromptTileCard | 提示牌 | | TableCenterActionEffect | 桌中动作特效 | | ActionPanel / ActionPanelButton | 操作面板（碰/杠/胡/过） | --- ## 六、数据架构 ### 6.1 Redis 多库隔离 | 库 | 用途 | 关键 Key | |----|------|----------| | DB0 | 房间与对局状态 | `game:{tid}:snapshot`、`game:{tid}:runtime`、`game:{tid}:ops`、`game:{tid}:settlement`、`room:{rid}:*` | | DB1 | 分布式锁与操作队列 | 互斥锁、幂等队列 | | DB2 | 用户缓存与匹配队列 | 用户在线状态、匹配票据 | ### 6.2 MySQL 核心实体 | 模块 | 实体 | |------|------| | 认证 | AuthUser、AuthUserPassword、AuthUserSession、AuthUserWallet、AuthUserRecord | | 游戏 | GameTable、GameEvent、GameSettlement、WinrateStrategyEvent、MonthlyWinrateSummary | | 社交 | Friendship、FriendRequest、FriendGiftGoldLog、Team、TeamMember、TeamInvite | | 商城 | ShopGood、ShopOrder | | 匹配 | MatchTicket | | 大厅 | PortalMail | | 系统 | SystemConfig、AdminAuditLog | --- ## 七、安全与并发 | 机制 | 说明 | |------|------| | **分布式锁** | Redis DB1 跨实例互斥 | | **幂等操作** | RequestId 去重 | | **乐观锁** | MySQL version 字段防并发超扣 | | **原子更新** | Redis Lua 脚本原子操作 | | **财务安全** | 积分暂存 Redis，整局结束后统一写入 MySQL | | **JWT 认证** | AccessToken + RefreshToken 双令牌 | | **401 自动刷新** | 客户端自动续期 | | **5xx 重试** | 后端 API 调用自动重试 | --- ## 八、开发辅助工具 ### godot-mcp-bridge 基于 **Model Context Protocol (MCP)** 的桥接工具，将 Godot 编辑器端点桥接到标准 I/O 流，使 AI 代理能够通过 MCP 协议与 Godot 编辑器交互，辅助 UI 开发。 --- ## 九、项目当前进展 ### UI 迁移进度（C# BuildUi → .tscn 场景文件） | 状态 | 组件 | |------|------| | ✅ 已完成 | BootScreen、ActionPanel、AccountLoginPopup、AccountRegisterPopup、RulePopup、SimplePopup、DingQuePopup、ExchangeThreePopup | | 🔄 进行中 | SharePopup | | ⏳ 待迁移 | SettingsPopup、FeedbackPopup、MailPopup、JoinRoomPopup、CreateRoomPopup、MatchPopup、RoundResultPopup、FinalResultScreen、RoomScreen、TableScreen | ### 架构差异追踪 | 差异项 | 优先级 | 状态 | |--------|--------|------| | 体系定位冲突（文档"无内存状态" vs 实际混合运行时） | P1 | 追踪中 | | 存储模型冲突（文档细粒度 Key vs 实际快照读写） | P1 | 追踪中 | | 胜率配置语义冲突 | P2 | 追踪中 | --- ## 十、部署架构 | 组件 | 部署方式 | |------|----------| | ApiHost | 双服务器固定部署（A/B），无动态扩容 | | AdminHost | 独立宿主 | | Redis | 1 主 2 从 3 哨兵，AOF + RDB 混合持久化 | | MySQL | 单实例（财务唯一权威） | | UI 客户端 | Windows / Android 分发 | --- > **总结**：MAJIANG 是一个功能完备的商用级在线棋牌平台，核心差异化在于**胜率调控引擎**和**多游戏支持**，技术栈覆盖 Vue3 管理后台、.NET 10 后端、Godot 4.6 游戏客户端，采用 Redis 多库隔离 + MySQL 财务权威的混合存储架构，当前处于架构优化和 UI 迁移阶段。