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 记忆。
+- 若任务涉及实时消息、教学、动作系统，需再次确认：是否泄露隐藏信息、是否破坏公共/私有消息边界、是否绕过统一动作入口。

.serena/project.yml

@@ -0,0 +1,68 @@
+# language of the project (csharp, python, rust, java, typescript, go, cpp, or ruby)
+#  * For C, use cpp
+#  * For JavaScript, use typescript
+# Special requirements:
+#  * csharp: Requires the presence of a .sln file in the project folder.
+language: java
+
+# whether to use the project's gitignore file to ignore files
+# Added on 2025-04-07
+ignore_all_files_in_gitignore: true
+# list of additional paths to ignore
+# same syntax as gitignore, so you can use * and **
+# Was previously called `ignored_dirs`, please update your config if you are using that.
+# Added (renamed) on 2025-04-07
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+project_name: "xzmaster"