first commit

.serena/memories/coding_conventions.md

@@ -0,0 +1,9 @@
+# 编码与架构约定
+- 全程中文沟通，必要英文日志/报错保留原文并补中文解释。
+- 工程原则：优先 KISS 与 YAGNI，在当前需求可测可交付前提下再考虑 SOLID 扩展；避免过度抽象和重复逻辑（DRY）。
+- 架构策略：当前采用单体应用按业务分包，不拆微服务。
+- 后端职责边界：`room` 管房间，`game` 管对局和动作，`strategy` 管 AI 决策与建议，`teaching` 管教学输出，`ws` 管实时消息。
+- 动作扩展规则：后续 `PENG / GANG / HU / PASS` 等动作必须接入统一动作系统，不能新增专用分叉主流程。
+- 教学安全规则：教学服务只能基于 `PlayerVisibleGameState` 等玩家可见信息产出建议。
+- 实时消息规则：公共主题只发桌面/阶段/动作事件；私有主题只发可行动作、教学建议、后续个人复盘。
+- 前端约定：移动端优先，H5 是正式交付范围而不是附带兼容；TypeScript 使用严格模式；Vue 使用单文件组件与现代组合式写法。

.serena/memories/current_execution_entry.md

@@ -0,0 +1,10 @@
+# 当前执行入口
+- 当前 Sprint 文档：`docs/SPRINT_01_ISSUES_BOARD.md`。
+- Sprint 1 当前进度：`S1-01`、`S1-02`、`S1-03` 已完成，推荐的下一个编码任务是 `S1-04`。
+- `S1-03` 已完成内容：
+  - `GameEventType` 已补齐未来响应窗口和响应动作事件类型。
+  - `GameEvent` 已新增统一工厂方法，统一现有公共事件和未来响应事件的载荷格式。
+  - `GameSessionService` 与 `GameActionProcessor` 的现有公共事件已改为复用统一工厂方法。
+  - 已新增 `GameEventTest`，验证新增动作事件与标准公共事件的载荷结构。
+- 当前推荐的后续依赖主线：`S1-04 -> S1-05 -> S1-07`。
+- 注意：目前新增事件类型仍主要是模型与约定层准备，真实响应窗口和响应动作事件还没有开始实际发出，下一步要用 `S1-04` 补候选动作模型。

.serena/memories/documentation_system.md

@@ -0,0 +1,7 @@
+# 文档体系
+- 主计划文件：`docs/DEVELOPMENT_PLAN.md`，负责定义项目目标、范围、H5 要求、架构边界、阶段路线、测试验收、风险与接手说明。
+- 阶段看板：`docs/PHASE_TASK_BOARD.md`，按 `待做 / 进行中 / 已完成` 管理阶段级任务卡，适合确定当前主线优先级。
+- 周计划看板：`docs/WEEKLY_PLAN_BOARD.md`，按相对周次管理近期执行节奏，适合滚动安排最近 1 到 8 周工作。
+- Issue 模板看板：`docs/ISSUE_TEMPLATES_BOARD.md`，提供 Epic、功能、缺陷、H5、技术债、研究、测试、文档等任务模板，并说明看板流转方式。
+- README 已补全文档索引和推荐阅读顺序：先主计划，再阶段看板，再周计划，再 Issue 模板。
+- 新对话接手建议：先看文档，再根据 `进行中` 项选择下一步，当前主线优先级仍是动作系统扩展和 H5 正式对局页。

.serena/memories/project_overview.md

@@ -0,0 +1,11 @@
+# 项目概览
+- 项目名称：XueZhanMaster（血战大师）
+- 目标：构建面向四川麻将血战到底玩家的 AI 训练平台，覆盖真人邀请对局、AI 补位、AI 强度分级、局中教学、局后复盘，并同时支持 H5 Web 与 PC Web。
+- 当前阶段：单体原型阶段，已打通房间流、开局、定缺、真人出牌、AI 自动推进、公私消息 WebSocket 骨架、H5 原型页面。
+- 关键约束：教学建议必须基于玩家可见状态，不能泄露隐藏信息；公共桌面消息与私有教学/动作消息必须分离；所有新增麻将动作统一进入通用动作入口，不要额外分叉接口。
+- 后端技术栈：Java 17、Spring Boot 3.3.5、spring-boot-starter-web、validation、websocket、maven。
+- 前端技术栈：Vue 3、TypeScript、Vite、@stomp/stompjs。
+- 当前运行态：内存态房间与对局；后续规划接入 MySQL、Redis 和 AI Provider。
+- 目录结构：`backend/` 为 Spring Boot 后端，`frontend/` 为 Vue 3 + Vite 前端，`docs/` 为开发计划与任务文档。
+- 后端主要分包：`common`、`room`、`game`、`strategy`、`teaching`、`web`、`ws`。
+- 前端当前结构：`src/App.vue` 为移动端优先的房间流/对局流原型页面，`src/style.css` 为样式，后续应拆为 Home/Room/Game/Review 页面。

.serena/memories/suggested_commands.md

@@ -0,0 +1,12 @@
+# 常用命令（Windows / PowerShell）
+- 进入项目根目录：`cd D:\WorkSpace\me\xzmaster`
+- 查看目录：`Get-ChildItem`
+- 按名称递归查文件：`Get-ChildItem -Recurse -Filter <name>`
+- 文本搜索（优先 ripgrep）：`rg <pattern>`；若系统无 `rg`，可用 `Get-ChildItem -Recurse | Select-String -Pattern <pattern>`
+- 启动后端：`cd backend; mvn spring-boot:run`
+- 后端测试：`cd backend; mvn test`
+- 启动前端开发环境：`cd frontend; npm install; npm run dev`
+- 前端构建验证：`cd frontend; npm run build`
+- 前端预览：`cd frontend; npm run preview`
+- Git 基本状态（若当前目录后续接入 Git）：`git status`, `git log -5 --stat`
+- 当前工作区未确认是标准 Git 仓库前，不要假设完整 Git 流程可用。

.serena/memories/task_completion_checklist.md

@@ -0,0 +1,7 @@
+# 任务完成检查
+- 文档或代码修改后，先确认是否符合 KISS / YAGNI / SOLID / DRY，并说明是否存在潜在违背点。
+- 后端最小验证：`cd backend; mvn test`
+- 前端最小验证：`cd frontend; npm run build`
+- 如果是 H5 相关改动，补充手工验收清单：建房、入房、准备、开局、定缺、出牌、WebSocket 消息可见，视口至少覆盖 `360x800`、`390x844`、`430x932`。
+- 若引入新命令、重要约定、架构边界或回滚策略，应同步更新 Serena 记忆。
+- 若任务涉及实时消息、教学、动作系统，需再次确认：是否泄露隐藏信息、是否破坏公共/私有消息边界、是否绕过统一动作入口。