update

Author: TypeThe0ry

README.md

@@ -1,154 +1,278 @@
 # 雀阁 · 纸牌房
 
-> **Forked from** [laivv/doudizhu](https://github.com/laivv/doudizhu.git)
+雀阁是一个基于 Node.js、Socket.IO 和 Vue 2 的在线纸牌房项目。项目最初 fork 自 [laivv/doudizhu](https://github.com/laivv/doudizhu.git)，现在已重构为“房间制 + 多玩法”的纸牌游戏平台，当前支持斗地主和掼蛋，并预留继续接入新玩法的结构。
 
-> 基于 Node.js + Vue 2 + Socket.IO 的多人在线纸牌房，支持 **动态开房 / 快速匹配 / 好友房号 / 斗地主 / 掼蛋 / 观战 / 国风音画**。
+## 功能概览
 
+- 动态房间：支持公开房、私密房、房号加入、快速入局。
+- 斗地主：三人叫分、地主底牌、地主/农民阵营、炸弹与春天倍率、AI 对手、智囊推荐。
+- 掼蛋：四人两副牌、固定对家、级牌升级、红桃级牌逢人配、AI 补位、智囊推荐、局内队伍计分板。
+- 观战模式：可不入座观看正在进行的房间。
+- AI 系统：空位可补 AI，真人可顶替等待态 AI，AI 会自动重新准备。
+- 聊天系统：房间内自由文本聊天。
+- 音效与特效：出牌、不出、炸弹、王炸、同花顺等有局内反馈，可静音。
+- 积分系统：可选 MySQL 持久化，斗地主和掼蛋积分榜独立统计。
+- Discuz SSO：可选 JWT 单点登录，支持同步 Discuz 用户名和头像。
+- 移动端：大厅可响应式使用；牌桌在手机端要求横屏。
 
----
+## 快速开始
 
-## 特性
+要求 Node.js 18 或更高版本。
 
-- **动态房间** — 玩家可以开公开房、开私密房、输入房号加入好友房，也可以快速入局自动匹配空房。
-- **多玩法架构** — 斗地主与掼蛋作为独立玩法接入，后续可继续扩展新的纸牌规则。
-- **斗地主** — 三人叫分、底牌、地主/农民阵营、炸弹翻倍、春天结算、AI 陪玩与智囊推荐。
-- **掼蛋** — 四人两副牌、对家组队、级牌升级、红桃级牌逢人配、炸弹/同花顺/四王炸、头游队伍升级结算。
-- **AI 对手** — 斗地主房内一键「召唤 A I 对手」，自动填空座；真人加入时 AI 自动让座、全员退房时自动清场。
-- **观战模式** — 不入座也能旁观对局，棋谱牌势一览无余。
-- **智囊推荐** — 自己回合点「智 囊」即可由内置 AI 自动选出最经济的合法跟牌。
-- **国风视效** — 玉绿背景、朱漆按钮、鎏金徽印；地主登场金光，农民登场玉色光晕；炸弹/王炸/飞机各自专属字幕特效。
-- **Web Audio 音效** — 出牌、不出、叫分、炸弹皆有合成音色，可一键静音。
-- **房间聊天** — 茶馆闲话面板，自由输入或下拉选「快语」短句。
-- **移动端适配** — 大厅、开房、手牌、聊天和操作按钮针对手机竖屏做了响应式布局。
-- **可选 SSO** — 内置 JWT 校验入口，便于与 Discuz 等论坛对接（参见 [discuz-sso/README.md](discuz-sso/README.md)）。
+```bash
+npm install
+npm start
+```
 
----
+默认监听 `8002`：
 
-## 截图
+```text
+http://localhost:8002/
+```
 
-<img width="1702" height="1255" alt="f2f1befc878f15cbbcc39238c5bf0546" src="https://github.com/user-attachments/assets/c0f47639-e6af-4997-acc0-a038c1d9f319" />
-<img width="1700" height="1257" alt="e2384b186038c64b40103a9f2db9d653" src="https://github.com/user-attachments/assets/87b166c5-42a3-408c-bd00-d52e17a57634" />
+本地指定端口：
 
+```powershell
+$env:PORT='8012'
+node server.js
+```
 
----
+## 配置
 
-## 快速开始
+项目启动时按以下优先级读取配置：
 
-确保已安装 Node.js（建议 ≥ 18）。
+1. 环境变量
+2. 根目录 `config.json`
+3. 代码默认值
 
-```sh
-git clone https://github.com/laivv/doudizhu.git
-cd doudizhu
-npm install
-npm start
+复制示例配置：
+
+```bash
+cp config.example.json config.json
 ```
 
-默认监听 **8002** 端口，浏览器访问：
+`config.json` 已加入 `.gitignore`，不要提交真实密钥和数据库密码。
 
-```
-http://localhost:8002
-```
+常用配置：
+
+| 字段 / 环境变量 | 说明 | 默认值 |
+| --- | --- | --- |
+| `PORT` | HTTP / Socket.IO 监听端口 | `8002` |
+| `JWT_SECRET` | Discuz SSO JWT 密钥，必须与论坛端一致 | `change_this_in_production` |
+| `DB_HOST` | MySQL 地址 | `127.0.0.1` |
+| `DB_PORT` | MySQL 端口 | `3306` |
+| `DB_USER` | MySQL 用户名 | 无 |
+| `DB_PASSWORD` | MySQL 密码 | 空 |
+| `DB_NAME` | MySQL 数据库名 | 无 |
+| `DB_TABLE_PREFIX` | 表前缀，建议与 Discuz 一致 | `pre_` |
+| `DB_DISABLE` | 设为 `1` 禁用数据库持久化 | 未启用 |
+| `SCORE_BASE` | 每个基础分对应的积分 | `1` |
+| `DISCUZ_AVATAR_BASE` | Discuz 头像 URL 模板，支持 `{uid}` | `https://zwwx.club/uc_server/avatar.php?uid={uid}&size=middle` |
 
-输入「雅号」后即可进入大厅：
+## 玩法说明
 
-- 选择「斗地主」或「掼蛋」后点「快速入局」。
-- 点「开公开房」等待陌生玩家加入。
-- 点「开私密房」后把房号发给朋友。
-- 输入好友给你的房号可直接加入。
+### 斗地主
 
----
+- 三人参与。
+- 叫分后分为地主与农民两方。
+- 地主获得底牌。
+- 支持常见斗地主牌型，牌型识别由 `static/js/parser.js` 和 `game.js` 处理。
+- 结算时地主按双倍基础分输赢，农民按单倍基础分输赢。
 
-## 操作指南
+### 掼蛋
 
-### 自己回合的按钮顺序
+- 四人参与，两副牌，每人 27 张。
+- 座位 `0/2` 为一队，`1/3` 为一队。
+- 当前级牌从 `2` 开始，红桃级牌为逢人配。
+- 头游队伍升级：双下 `+3`，二三名 `+2`，其他胜局 `+1`。
 
-```
-[ 出 牌 ]   [ 智 囊 ]   [ 不 出 ]
-   ↑ 朱漆      ↑ 墨色      ↑ 玉绿
-```
+第一类牌型：
 
-- **出 牌**：将选中的牌打出（必须是合法牌型，且能压过上家）。
-- **智 囊**：让 AI 自动帮你选牌；若无可压制的牌会提示「建议不出」。
-- **不 出**：跳过本轮（仅当上家不是自己时可见）。
+- 单张：任意一张牌。
+- 对子：两张点数相同的牌，包括对大王或对小王。
+- 三连对：三对连续对子，例如 `223344`。
+- 三同张：三张点数相同的牌。
+- 二连三：两组三同张，例如 `333444`。
+- 三带二：三同张带一个对子，例如 `55522`。
+- 顺子：五张连续单牌，例如 `23456`。
 
-### 房间与等待区
+第一类牌型之间必须牌型相同才能压牌；三带二只比较三同张大小。
 
-- **准 备**：标记自己已就绪；三人全部就绪自动开局。
-- **召 唤 A I 对 手**：斗地主房内有空座时显示，把所有空位填上 AI。
-- **请 走 A I**：斗地主房内有 AI 时显示，清退所有 AI 等真人。
-- **房号**：房间顶部显示，私密房可复制房号给好友加入。
+连续牌型中，`A` 可以作为最小值，也可以作为 `K+1`。例如 `A2345`、`23456`、`10JQKA`、`AA2233`、`QQKKAA` 都是合法连续牌型。
 
-### 叫分
+第二类牌型：
 
-听到「叫分」环节时，依次显示可叫分数（1/2/3）和「不叫」按钮，点击即可。
+- 炸弹：四张或四张以上点数相同的牌。
+- 同花顺：五张花色相同的顺子。
+- 天王炸：大小王各两张。
 
-### 掼蛋
+第二类可以压任意第一类。第二类内部顺序：
 
-- 四人开局，两副牌，每人 27 张。
-- 0/2 与 1/3 为固定对家。
-- 当前级牌从 2 开始，红桃级牌为逢人配，可参与常规牌型组合。
-- 支持单张、对子、三张、三带二、顺子、连对、钢板、炸弹、同花顺、四王炸。
-- 头游队伍按名次升级：双下 +3，二三名 +2，其余 +1。
+- 天王炸最大。
+- 炸弹张数越多越大，张数相同比点数。
+- 同花顺按顺子点数比较。
+- 同花顺可以压五张及以下炸弹，六张及以上炸弹大于同花顺。
 
-### AI 让座规则
+## 智囊与 AI
 
-- 真人入座时若该位被 AI 占用且未在游戏中 → AI **拱手让座**。
-- 桌内最后一名真人离席 / 掉线 → 服务端自动清退该桌所有 AI 并重置牌局。
-- 一局结束后，留在桌上的 AI **自动重新就绪**；若全员就绪则立即开下一局。
+斗地主智囊由 `static/js/ai-suggest.js` 提供。
 
----
+掼蛋智囊由 `static/js/guandan-suggest.js` 提供，服务端机器人与前端“智囊”共用同一套规则分析。策略原则：
 
-## 技术栈
+- 自由出牌时优先减少手数。
+- 跟牌时尽量用最小可压牌。
+- 队友出牌时通常不压，除非可以直接走完。
+- 炸弹和逢人配会尽量保留，除非局势需要。
 
-| 层 | 选型 |
+## 积分系统
+
+数据库持久化是可选能力。未配置数据库时，游戏仍可正常运行，但不会保存积分。
+
+启动时自动创建两张表：
+
+```text
+pre_doudizhu_score
+pre_guandan_score
+```
+
+表前缀由 `DB_TABLE_PREFIX` 决定。
+
+HTTP 查询接口：
+
+| 接口 | 说明 |
 | --- | --- |
-| 服务端 | Node.js · Express · Socket.IO 4 · jsonwebtoken |
-| 前端 | Vue 2（CDN 单文件）· jQuery · layer 弹层 |
-| 通信 | WebSocket（事件：`CREATE_ROOM` / `JOIN_ROOM` / `QUICK_JOIN` / `SITDOWN` / `PREPARE` / `CALL_SCORE` / `PLAY_CARD` / `USER_MESSAGE` / `SPECTATE` / `ADD_BOTS` / `REMOVE_BOTS` …） |
-| 音效 | 原生 Web Audio API（无第三方依赖） |
-| 牌型校验 | `static/js/parser.js`（A / AA / AAA / AAAB / AAABB / ABCDE / AABBCC / AAABBB / AAAABC / AAAABBCC / AAAA / KING） |
-| AI 决策 | `static/js/ai-suggest.js`（同时供前端「智囊」与服务端「机器人」使用） |
+| `GET /api/score/me?gameType=doudizhu&token=<JWT>` | 当前用户斗地主战绩 |
+| `GET /api/score/me?gameType=guandan&token=<JWT>` | 当前用户掼蛋战绩 |
+| `GET /api/score/top?gameType=doudizhu&limit=20` | 斗地主积分榜 |
+| `GET /api/score/top?gameType=guandan&limit=20` | 掼蛋积分榜 |
+
+只有通过 JWT 登录的真人玩家会计入积分。游客、AI、观战用户不记录。
 
----
+## Discuz SSO
+
+项目支持通过 Discuz 签发 JWT 进行单点登录。
+
+- 论坛端示例代码在 `discuz-sso/`。
+- 游戏端通过 Socket.IO `auth.token` 校验 JWT。
+- 登录成功后可同步 Discuz 用户名和头像。
+
+详细部署见 [discuz-sso/README.md](discuz-sso/README.md)。
 
 ## 项目结构
 
-```
-quege-card-room/
-├── server.js              # Express + Socket.IO 入口；含 AI 机器人调度
-├── game.js                # 游戏状态机（发牌 / 叫分 / 出牌 / 胜负）
-├── guandan-game.js        # 掼蛋状态机（两副牌 / 级牌 / 逢人配 / 升级）
-├── core-ai.js             # 服务端 AI 辅助
-├── core-validator.js      # 服务端牌型校验
-├── package.json
-├── discuz-sso/            # 可选：与 Discuz 论坛 SSO 对接示例
+```text
+.
+├── server.js                    # Express + Socket.IO 入口、房间、AI、API
+├── game.js                      # 斗地主状态机
+├── guandan-game.js              # 掼蛋状态机与服务端判牌
+├── db.js                        # 分玩法积分持久化
+├── core-ai.js                   # 原斗地主 AI 辅助
+├── core-validator.js            # 原斗地主校验辅助
+├── config.example.json          # 本地配置示例
+├── discuz-sso/                  # Discuz JWT SSO 示例
 └── static/
-    ├── index.html         # Vue SPA 单页
+    ├── index.html               # Vue 2 单页应用
     ├── css/
-    │   ├── base.css
-    │   ├── style.css      # 国风主题样式
-    │   └── theme.css
-    ├── images/
-    │   └── screenshots/   # 文档截图
+    │   ├── theme.css            # 主题变量
+    │   └── style.css            # 主要布局与组件样式
+    ├── images/                  # 扑克图、桌面素材
     └── js/
-        ├── parser.js      # 牌型识别
-        ├── ai-suggest.js  # AI 选牌引擎（前后端共用）
-        ├── effects.js     # 特效字幕 + Web Audio 音效
+        ├── parser.js            # 斗地主牌型解析
+        ├── ai-suggest.js        # 斗地主智囊
+        ├── guandan-suggest.js   # 掼蛋智囊
+        ├── effects.js           # 音效与特效
         ├── vue.min.js
         ├── jquery.min.js
-        └── layer/         # layer 弹层组件
+        └── layer/               # 弹窗组件
 ```
 
----
-
-## 可选：Discuz SSO 对接
-
-若要让论坛会员免登录进入游戏，可参考 [discuz-sso/README.md](discuz-sso/README.md)：论坛侧颁发 JWT，前端在 `?token=` 中带入，服务端 `io.use` 中间件校验通过后建立连接。
+## 常用 Socket 事件
+
+客户端到服务端：
+
+- `LOGIN`
+- `CREATE_ROOM`
+- `QUICK_JOIN`
+- `JOIN_ROOM`
+- `SITDOWN`
+- `PREPARE`
+- `CALL_SCORE`
+- `PLAY_CARD`
+- `USER_MESSAGE`
+- `SPECTATE`
+- `ADD_BOTS`
+- `REMOVE_BOTS`
+
+服务端到客户端：
+
+- `LOGIN_SUCCESS`
+- `LOGIN_FAIL`
+- `REFRESH_LIST`
+- `POS_STATUS_CHANGE`
+- `GAME_START`
+- `CTX_USER_CHANGE`
+- `CTX_PLAY_CHANGE`
+- `SHOW_TOP_CARD`
+- `PLAY_CARD_SUCCESS`
+- `PLAY_CARD_ERROR`
+- `GAME_OVER`
+- `USER_MESSAGE`
+- `MY_SCORE`
+
+## 开发与验证
+
+语法检查：
+
+```bash
+node --check server.js
+node --check db.js
+node --check game.js
+node --check guandan-game.js
+node --check static/js/guandan-suggest.js
+node --check static/js/effects.js
+```
 
----
+本地规则回归建议覆盖：
+
+- 掼蛋 `A2345`、`23456`、`10JQKA`
+- 掼蛋三连对、二连三、三带二
+- 同花顺压五张炸，六张炸压同花顺
+- 天王炸压所有牌型
+- 斗地主叫分、底牌、出牌、结算
+
+## 部署建议
+
+- 使用 HTTPS，特别是启用 Discuz SSO 时。
+- 生产环境必须设置强随机 `JWT_SECRET`。
+- 建议用 systemd、pm2 或容器托管 Node 进程。
+- 如在 Cloudflare 等代理后运行，保留 WebSocket 支持。
+- 数据库账号只授予游戏积分表需要的权限。
+
+systemd 示例：
+
+```ini
+[Unit]
+Description=Quege Card Room
+After=network.target
+
+[Service]
+WorkingDirectory=/var/www/quege-card-room
+ExecStart=/usr/bin/node server.js
+Restart=always
+Environment=PORT=8002
+Environment=JWT_SECRET=replace-with-a-strong-secret
+Environment=DB_HOST=127.0.0.1
+Environment=DB_USER=discuz
+Environment=DB_PASSWORD=replace-with-db-password
+Environment=DB_NAME=discuz
+Environment=DB_TABLE_PREFIX=pre_
+
+[Install]
+WantedBy=multi-user.target
+```
 
 ## License
 
-MIT — 详见 LICENSE。
+代码以 [MIT License](LICENSE) 发布。
 
-> 注：`static/images/` 内的扑克 / 桌面贴图素材来源于网络，**不在 MIT 许可范围内**，仅作演示用途；如商业使用请自行替换。
+`static/images/` 中的牌面、桌面等素材仅作为演示资源；商业使用请确认素材授权或自行替换。

config.example.json

@@ -9,5 +9,6 @@
   "DB_NAME": "zwwx_discuz",
   "DB_TABLE_PREFIX": "pre_",
   "DB_DISABLE": 0,
-  "SCORE_BASE": 1
+  "SCORE_BASE": 1,
+  "DISCUZ_AVATAR_BASE": "https://zwwx.club/uc_server/avatar.php?uid={uid}&size=middle"
 }