xzmaster/docs/PHASE_TASK_BOARD.md

# 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 原型页面可走通当前最小链路