# 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 房间流原型页面

## 目录结构

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

## 运行方式

### 后端

```bash
cd backend
mvn spring-boot:run
```

### 前端

```bash
cd frontend
npm install
npm run dev
```

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

## 验证方式

### 后端测试

```bash
cd backend
mvn test
```

### 前端构建

```bash
cd frontend
npm run build
```

## 文档索引

### 主计划

- [详细开发计划](/D:/WorkSpace/me/xzmaster/docs/DEVELOPMENT_PLAN.md)

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

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

### 执行拆分文档

- [阶段任务看板](/D:/WorkSpace/me/xzmaster/docs/PHASE_TASK_BOARD.md)
- [周计划看板](/D:/WorkSpace/me/xzmaster/docs/WEEKLY_PLAN_BOARD.md)
- [Issue 模板与看板](/D:/WorkSpace/me/xzmaster/docs/ISSUE_TEMPLATES_BOARD.md)
- [Sprint 1 Issue 看板](/D:/WorkSpace/me/xzmaster/docs/SPRINT_01_ISSUES_BOARD.md)

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

- `阶段任务看板`：回答“当前整个项目有哪些阶段、每个阶段要交付什么”
- `周计划看板`：回答“接下来每周做什么、如何验收、怎样滚动调整”
- `Issue 模板与看板`：回答“单个任务如何立项、描述、拆解、验收、进入看板”
- `Sprint 1 Issue 看板`：回答“当前这一轮开发具体先做哪些真实任务、按什么顺序推进”

### 推荐阅读顺序

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

1. 先看 [详细开发计划](/D:/WorkSpace/me/xzmaster/docs/DEVELOPMENT_PLAN.md)
2. 再看 [阶段任务看板](/D:/WorkSpace/me/xzmaster/docs/PHASE_TASK_BOARD.md)
3. 再看 [周计划看板](/D:/WorkSpace/me/xzmaster/docs/WEEKLY_PLAN_BOARD.md)
4. 再看 [Issue 模板与看板](/D:/WorkSpace/me/xzmaster/docs/ISSUE_TEMPLATES_BOARD.md)
5. 最后从 [Sprint 1 Issue 看板](/D:/WorkSpace/me/xzmaster/docs/SPRINT_01_ISSUES_BOARD.md) 直接领取当前要做的任务

## 当前推荐下一步

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