XueZhanMaster

XueZhanMaster（血战大师） 是一个基于 AI 的四川麻将血战到底训练平台。

项目目标不是只做一个“会打麻将”的程序，而是做一个兼顾：

• 真人邀请对局
• AI 补位
• AI 强度分级
• 局中 AI 教学
• 局后个人复盘
• H5 与 PC Web 双端可用

的完整训练系统。

当前技术栈

• 后端：Spring Boot 3 + Java 17
• 前端：Vue 3 + TypeScript + Vite
• 实时通信：WebSocket / STOMP
• 当前运行态：内存态房间与游戏会话
• 后续规划：MySQL、Redis、AI Provider 接入

当前已实现

• 房间创建
• 房间加入
• 真人准备
• 房主开局
• 不满 4 人自动补 AI
• 定缺
• 真人出牌
• AI 自动推进回合
• 公共事件与私有消息的 WebSocket 骨架
• H5 房间流原型页面

目录结构

backend/   Spring Boot 后端
frontend/  Vue 3 + Vite 前端
docs/      开发计划、阶段任务、周计划、Issue 模板看板

运行方式

后端

cd backend
mvn spring-boot:run

前端

cd frontend
npm install
npm run dev

前端默认通过 Vite 代理访问 http://localhost:8080，并代理 /ws 到后端 WebSocket 端点。

验证方式

后端测试

cd backend
mvn test

前端构建

cd frontend
npm run build

文档索引

主计划

• 详细开发计划

主计划负责回答 4 个问题：

1. 这个项目最终要做成什么
2. 当前做到哪一步
3. 后面按什么顺序推进
4. H5、教学、动作系统、持久化这些关键问题各自的边界是什么

执行拆分文档

• 阶段任务看板
• 周计划看板
• Issue 模板与看板
• Sprint 1 Issue 看板
• 响应优先级规则澄清

这三份文档用于把主计划进一步拆成可直接执行的落地材料：

• 阶段任务看板：回答“当前整个项目有哪些阶段、每个阶段要交付什么”
• 周计划看板：回答“接下来每周做什么、如何验收、怎样滚动调整”
• Issue 模板与看板：回答“单个任务如何立项、描述、拆解、验收、进入看板”
• Sprint 1 Issue 看板：回答“当前这一轮开发具体先做哪些真实任务、按什么顺序推进”
• 响应优先级规则澄清：回答“碰 / 杠 / 胡 / 过 的冲突怎么裁决、哪些属于项目 V1 约定”

推荐阅读顺序

如果是新对话或新成员接手，建议按以下顺序进入：

1. 先看 详细开发计划
2. 再看 阶段任务看板
3. 再看 周计划看板
4. 再看 Issue 模板与看板
5. 最后从 Sprint 1 Issue 看板 直接领取当前要做的任务

当前推荐下一步

1. 补全 PENG / GANG / HU / PASS 与响应优先级
2. 把 H5 对局页面从原型操作台升级为正式页面结构
3. 接入房间与对局持久化
4. 增加真人玩家独立 AI 教学开关
5. 增加局后复盘和错题本