first commit

docs/PHASE_TASK_BOARD.md

@@ -0,0 +1,361 @@
+# XueZhanMaster 阶段任务看板
+
+本文档把主计划拆成可以直接推进的阶段任务卡。  
+当前状态快照日期：`2026-03-20`
+
+---
+
+## 1. 使用说明
+
+### 1.1 本文档解决什么问题
+
+- 当前项目整体还有哪些阶段没有完成
+- 每个阶段到底要交付什么
+- 什么算开始、什么算完成
+- 当前应该先推哪个阶段
+
+### 1.2 看板状态定义
+
+- `待做`：已确认进入路线图，但尚未实质启动
+- `进行中`：已有代码、文档或设计工作在推进
+- `已完成`：阶段目标的最小闭环已经形成
+
+### 1.3 卡片字段说明
+
+每个任务卡尽量包含：
+
+- 编号
+- 所属阶段
+- 目标
+- 核心任务
+- 产出物
+- 前置依赖
+- 验收标准
+- 风险提示
+
+---
+
+## 2. 待做
+
+### P2-02 响应窗口与优先级裁决
+
+- 所属阶段：`M2 动作系统扩展`
+- 目标：在出牌后正确生成候选响应，并按血战到底规则裁决动作优先级
+- 核心任务：
+  - 设计响应窗口模型
+  - 识别 `HU / GANG / PENG / PASS` 候选
+  - 统一裁决优先级
+  - 处理多人同时可响应的场景
+- 产出物：
+  - 后端优先级裁决逻辑
+  - WebSocket 私有候选动作消息
+  - 规则说明文档补充
+- 前置依赖：
+  - `P2-01` 基础动作枚举与统一入口扩展
+- 验收标准：
+  - 对任一弃牌都可给出正确响应候选
+  - 多人竞争时能按约定优先级决议
+  - 未行动玩家不会被错误推进回合
+- 风险提示：
+  - 容易绕开统一动作入口
+  - 容易混淆公共事件与私有候选动作
+
+### P3-01 血战到底规则闭环与结算
+
+- 所属阶段：`M3 规则与结算`
+- 目标：完成基础胡牌判定、杠分与局终处理
+- 核心任务：
+  - 胡牌判定
+  - 基础番型与分数策略
+  - 杠分处理
+  - 单局结束条件
+  - 血战到底继续流程
+- 产出物：
+  - 规则判定服务
+  - 结算结果模型
+  - 结算事件与状态落地
+- 前置依赖：
+  - `P2-01`
+  - `P2-02`
+- 验收标准：
+  - 能从开局走到完整结算
+  - 胡牌与流转状态一致
+  - 结算结果可被前端展示
+- 风险提示：
+  - 规则理解偏差会导致后续复盘失真
+
+### P4-02 正式 H5 对局页面
+
+- 所属阶段：`M4 H5 正式对局体验`
+- 目标：把当前原型操作台升级为真正可玩的 H5 对局页
+- 核心任务：
+  - 页面拆分为房间页 / 对局页 / 复盘页
+  - 手牌区、弃牌区、信息区、动作区布局
+  - 私有教学卡片和展开逻辑
+  - 弱网下状态提示和重连提示
+- 产出物：
+  - 页面组件结构
+  - H5 样式方案
+  - 手工验收记录
+- 前置依赖：
+  - 当前 `App.vue` 原型
+  - 基础动作消息和教学消息保持稳定
+- 验收标准：
+  - `360px` 到 `430px` 宽度可完整操作
+  - 不依赖开发辅助信息也能完成主流程
+  - 公共区域与私有教学区域清晰
+- 风险提示：
+  - 页面过度堆信息会造成遮挡和误触
+
+### P5-01 真人邀请与 AI 强度配置
+
+- 所属阶段：`M4 H5 正式对局体验` + `M5 教学系统扩展`
+- 目标：支持房间邀请、AI 补位强度选择和真实多人协作体验
+- 核心任务：
+  - 房间邀请码或链接
+  - AI 补位强度选择
+  - 房主视角的房间管理区
+  - 未满 4 人时自动补位策略
+- 产出物：
+  - 房间配置接口
+  - 前端房间配置 UI
+  - 强度枚举说明
+- 前置依赖：
+  - 房间流稳定
+- 验收标准：
+  - 能邀请真人加入
+  - 缺人时 AI 自动补位
+  - 补位 AI 强度对外可配
+
+### P5-02 玩家独立 AI 教学开关
+
+- 所属阶段：`M5 教学系统扩展`
+- 目标：允许每位真人玩家独立开关自己的 AI 教学，不影响其他人
+- 核心任务：
+  - 教学开关接口
+  - 玩家偏好模型
+  - 私有消息按玩家开关发送
+  - 前端局内教学开关控件
+- 产出物：
+  - 开关接口
+  - 前端开关交互
+  - 教学开关状态同步策略
+- 前置依赖：
+  - 私有教学消息通道稳定
+- 验收标准：
+  - 任一真人关闭教学后，不再收到自己的教学消息
+  - 其他玩家不受影响
+  - 开关状态在当前局中持续有效
+
+### P6-01 房间与对局持久化
+
+- 所属阶段：`M6 持久化与稳定性`
+- 目标：将关键房间与对局状态从内存态过渡到数据库
+- 核心任务：
+  - `room / room_seat / game_session` 落库
+  - 状态恢复策略
+  - 查询接口切换
+  - 基础迁移脚本
+- 产出物：
+  - 数据表
+  - Repository / Mapper
+  - 持久化后的服务层改造
+- 前置依赖：
+  - 房间与对局主干稳定
+- 验收标准：
+  - 服务重启后关键状态可恢复或可追踪
+  - 房间和对局查询不依赖纯内存态
+
+### P6-02 WebSocket 鉴权与重连恢复
+
+- 所属阶段：`M6 持久化与稳定性`
+- 目标：补足实时系统的身份边界和弱网恢复能力
+- 核心任务：
+  - 连接鉴权
+  - 私有主题与用户绑定
+  - 前端重连策略
+  - 重连后状态重拉
+- 产出物：
+  - 鉴权方案
+  - 前端重连流程
+  - 异常提示规则
+- 前置依赖：
+  - 基础持久化能力
+- 验收标准：
+  - 私有消息不能被其他玩家订阅
+  - 弱网重连后可恢复当前视角状态
+
+### P7-01 局后复盘与错题本
+
+- 所属阶段：`M7 复盘与成长闭环`
+- 目标：构建“对局结束后还能继续学”的成长系统
+- 核心任务：
+  - 决策日志沉淀
+  - 局后个人复盘生成
+  - 关键错误点提取
+  - 错题本模型
+- 产出物：
+  - 复盘接口
+  - 复盘页
+  - 错题本结构
+- 前置依赖：
+  - 规则与结算稳定
+  - 教学解释链路稳定
+- 验收标准：
+  - 每局结束后可获得个人复盘
+  - 可沉淀到错题本并二次查看
+
+---
+
+## 3. 进行中
+
+### P2-01 动作系统扩展主干
+
+- 所属阶段：`M2 动作系统扩展`
+- 目标：把当前仅支持 `SELECT_LACK_SUIT / DISCARD` 的动作系统扩成麻将主干动作系统
+- 当前状态：
+  - 已有统一动作入口
+  - 已有 `GameActionProcessor` 骨架
+  - 已有事件流与私有动作消息通道
+- 核心任务：
+  - 扩展动作枚举
+  - 定义 `PENG / GANG / HU / PASS` 请求模型
+  - 统一动作校验
+  - 动作执行后产生标准事件
+- 当前卡点：
+  - 需要明确响应候选模型与优先级裁决机制
+- 产出物：
+  - 扩展后的动作处理器
+  - 新动作测试
+  - 前端动作按钮映射
+- 验收标准：
+  - 所有新增动作仍通过同一入口提交
+  - 执行后状态与事件同步一致
+
+### P4-01 H5 体验重构设计
+
+- 所属阶段：`M4 H5 正式对局体验`
+- 目标：在不打断当前可运行原型的前提下，拆出正式 H5 页面结构
+- 当前状态：
+  - `App.vue` 已覆盖房间流和局内主操作
+  - WebSocket 已可接公共事件、私有动作、私有教学
+- 核心任务：
+  - 梳理房间页、对局页、复盘页的信息架构
+  - 定义移动端布局分区
+  - 明确教学面板和动作面板的层级
+- 当前卡点：
+  - 动作系统仍在扩展，最终动作面板尚未稳定
+- 产出物：
+  - 页面拆分方案
+  - 状态模型拆分方案
+  - H5 交互清单
+- 验收标准：
+  - 页面拆分方案可直接指导下一轮前端编码
+
+---
+
+## 4. 已完成
+
+### DOC-01 文档体系升级
+
+- 所属阶段：跨阶段支撑任务
+- 目标：把原先偏概述的计划文档升级成“主计划 + 阶段任务 + 周计划 + Issue 模板”体系
+- 已完成内容：
+  - 扩写主计划
+  - 新增阶段任务看板
+  - 新增周计划看板
+  - 新增 Issue 模板看板
+  - 更新 README 索引
+- 验收结果：
+  - 新对话仅通过阅读文档就能接着推进
+
+### P0-01 项目骨架初始化
+
+- 所属阶段：`M1 房间流与单局主干`
+- 目标：建立前后端可运行的最小工程骨架
+- 已完成内容：
+  - Spring Boot 后端初始化
+  - Vue 3 + Vite 前端初始化
+  - 基础目录结构建立
+- 验收结果：
+  - 后端可启动
+  - 前端可启动和构建
+
+### P1-01 房间流闭环
+
+- 所属阶段：`M1 房间流与单局主干`
+- 目标：完成建房、入房、准备、开局的基本流程
+- 已完成内容：
+  - 创建房间
+  - 查询房间
+  - 加入房间
+  - 准备 / 取消准备
+  - 房主开局
+- 验收结果：
+  - 真人房间流已可操作
+
+### P1-02 不满 4 人自动补 AI
+
+- 所属阶段：`M1 房间流与单局主干`
+- 目标：开局时自动补齐 AI，形成最小对局环境
+- 已完成内容：
+  - 未满 4 人自动补 AI
+  - AI 强度枚举骨架
+- 验收结果：
+  - 可在真人人数不足时启动单局
+
+### P1-03 对局主干与定缺
+
+- 所属阶段：`M1 房间流与单局主干`
+- 目标：建立从开局到定缺再到正式出牌的最小对局阶段流转
+- 已完成内容：
+  - 生成 `GameSession`
+  - 真人定缺
+  - 全员定缺后进入 `PLAYING`
+- 验收结果：
+  - 单局进入可出牌状态
+
+### P1-04 统一动作入口初版
+
+- 所属阶段：`M1 房间流与单局主干`
+- 目标：避免为不同动作堆散乱接口
+- 已完成内容：
+  - `POST /api/games/{gameId}/actions`
+  - 当前支持 `SELECT_LACK_SUIT` 与 `DISCARD`
+  - 保留兼容接口
+- 验收结果：
+  - 当前动作已统一进入动作处理链
+
+### P1-05 AI 自动推进与事件骨架
+
+- 所属阶段：`M1 房间流与单局主干`
+- 目标：在真人出牌后推动 AI 行动，直到回到真人回合
+- 已完成内容：
+  - 真人出牌
+  - AI 自动推进回合
+  - 事件列表与事件类型骨架
+- 验收结果：
+  - 单局能持续推进，不停在第一步
+
+### P1-06 WebSocket 公私消息骨架
+
+- 所属阶段：`M1 房间流与单局主干`
+- 目标：建立公共事件和私有消息分离的实时链路
+- 已完成内容：
+  - STOMP 配置
+  - 公共事件主题
+  - 私有动作主题
+  - 私有教学主题
+- 验收结果：
+  - 前端已可订阅三类主题
+
+### P1-07 H5 原型操作台
+
+- 所属阶段：`M1 房间流与单局主干`
+- 目标：让移动端先具备完整主流程操作能力
+- 已完成内容：
+  - `App.vue` 支持建房、入房、准备、开局、定缺、出牌
+  - 已接入 STOMP 订阅
+  - `vite.config.ts` 已代理 `/api` 和 `/ws`
+- 验收结果：
+  - H5 原型页面可走通当前最小链路