first commit

README.md

@@ -0,0 +1,123 @@
+# 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. 增加局后复盘和错题本