436 lines
10 KiB
Markdown
436 lines
10 KiB
Markdown
# XueZhanMaster Sprint 1 Issue 看板
|
||
|
||
本文档把当前最优先的 `Week 1` 与 `Week 2` 工作直接拆成真实可执行任务。
|
||
当前状态快照日期：`2026-03-20`
|
||
|
||
Sprint 目标：
|
||
|
||
- 把动作系统从“只支持定缺和出牌”扩展为“可以承接麻将主干动作”
|
||
- 为后续响应优先级裁决建立候选动作模型
|
||
- 为 H5 正式对局页拆分准备稳定的数据结构和页面结构
|
||
|
||
---
|
||
|
||
## 1. 使用说明
|
||
|
||
### 1.1 本文档解决什么问题
|
||
|
||
- 当前这一轮开发先做哪几件事
|
||
- 哪些任务已经开始，哪些还没开始
|
||
- 每个任务的前后依赖关系是什么
|
||
- 每个任务做完之后如何验收
|
||
|
||
### 1.2 看板状态定义
|
||
|
||
- `待做`：已进入本次 Sprint，但尚未开始
|
||
- `进行中`：当前优先推进中的任务
|
||
- `已完成`：本次 Sprint 内已完成并可供后续任务依赖
|
||
|
||
### 1.3 执行顺序建议
|
||
|
||
1. 先完成后端动作模型扩展
|
||
2. 再完成动作校验与事件扩展
|
||
3. 再定义响应候选和私有动作消息体
|
||
4. 最后输出 H5 页面拆分和动作面板结构
|
||
|
||
这样安排遵守：
|
||
|
||
- `KISS`：先稳住后端动作语义，再扩前端页面
|
||
- `YAGNI`：本轮不直接冲结算和持久化
|
||
- `SOLID`：规则、动作、消息、前端结构按职责拆开推进
|
||
- `DRY`：统一动作入口和统一消息模型，不走分叉
|
||
|
||
---
|
||
|
||
## 2. 待做
|
||
|
||
### S1-05 [功能] 扩展私有动作消息体，支持响应候选下发
|
||
|
||
## 背景
|
||
|
||
后续 `HU / GANG / PENG / PASS` 不是任何时刻都可点，必须先有“当前玩家可执行哪些动作”的私有候选列表。现在虽有私有动作主题，但消息体还不足以表达响应窗口和候选动作。
|
||
|
||
## 目标
|
||
|
||
把私有动作消息体扩展成可支持：
|
||
|
||
- 当前可行动作列表
|
||
- 候选动作来源
|
||
- 响应截止上下文
|
||
- 与当前回合/弃牌事件的关联关系
|
||
|
||
## 范围
|
||
|
||
- 定义候选动作 DTO
|
||
- 定义是否为响应窗口动作
|
||
- 定义关联事件 ID 或动作上下文
|
||
- 补充前端消费字段说明
|
||
|
||
## 非范围
|
||
|
||
- 不在本任务里完成最终 UI 交互
|
||
- 不在本任务里实现多人竞争裁决
|
||
|
||
## 依赖
|
||
|
||
- `S1-01`
|
||
- `S1-02`
|
||
- `S1-04`
|
||
|
||
## 产出物
|
||
|
||
- 后端私有动作消息模型
|
||
- 消息发布说明
|
||
- 前端订阅字段适配说明
|
||
|
||
## 验收标准
|
||
|
||
- 服务端能向指定用户发送结构化候选动作
|
||
- 消息能区分“主动出牌动作”和“被动响应动作”
|
||
- 前端收到后无需猜测字段语义
|
||
|
||
## 验证方式
|
||
|
||
- 后端：`mvn test`
|
||
- 前端：`npm run build`
|
||
- 手工：模拟一次弃牌后，检查候选动作消息结构是否完整
|
||
|
||
### S1-06 [研究] 响应优先级裁决规则澄清
|
||
|
||
## 背景
|
||
|
||
在真正实现多人响应之前，必须先统一项目内部的动作优先级和冲突处理规则，否则后端、前端、教学系统会各自假设，后续很容易返工。
|
||
|
||
## 目标
|
||
|
||
形成一份明确的规则澄清结果，至少回答：
|
||
|
||
- `HU / GANG / PENG / PASS` 的优先级顺序
|
||
- 多人同时可响应时的裁决方式
|
||
- 响应窗口何时打开、何时关闭
|
||
- AI 与真人竞争时是否采用同一裁决规则
|
||
|
||
## 范围
|
||
|
||
- 梳理当前产品约束
|
||
- 梳理实现层需要的最小规则集
|
||
- 输出推荐裁决策略
|
||
|
||
## 非范围
|
||
|
||
- 不在本任务里直接落代码
|
||
|
||
## 依赖
|
||
|
||
- `S1-04`
|
||
|
||
## 产出物
|
||
|
||
- 规则澄清文档
|
||
- 后续开发任务拆分建议
|
||
|
||
## 验收标准
|
||
|
||
- 可以直接指导 `S1-07`
|
||
- 后续实现不再需要对优先级做二次猜测
|
||
|
||
## 验证方式
|
||
|
||
- 文档评审
|
||
- 与主计划、阶段看板、周计划保持一致
|
||
|
||
### S1-08 [H5] 对局页信息架构与页面拆分方案
|
||
|
||
## 背景
|
||
|
||
当前 `App.vue` 是原型操作台，已经能跑主流程，但信息和状态都堆在单页里。后续如果不先定义页面结构，动作系统一扩展，前端会迅速失控。
|
||
|
||
## 目标
|
||
|
||
输出 H5 正式对局页拆分方案，明确：
|
||
|
||
- 房间页、对局页、复盘页的职责
|
||
- 对局页内的信息分区
|
||
- 私有教学面板和动作面板层级
|
||
- 公共事件区与私有区边界
|
||
|
||
## 范围
|
||
|
||
- 页面职责定义
|
||
- 组件拆分建议
|
||
- 状态归属建议
|
||
- 移动端布局区块说明
|
||
|
||
## 非范围
|
||
|
||
- 不在本任务里实现完整 UI
|
||
- 不在本任务里处理所有视觉细节
|
||
|
||
## 依赖
|
||
|
||
- `S1-05`
|
||
|
||
## 产出物
|
||
|
||
- 页面拆分文档
|
||
- 信息架构草图说明
|
||
- 下一轮前端任务拆分建议
|
||
|
||
## 验收标准
|
||
|
||
- 下一轮前端改造可以按本文档直接开始
|
||
- 公共区、私有区、动作区职责清楚
|
||
|
||
## 验证方式
|
||
|
||
- 文档评审
|
||
- 与当前 H5 要求、周计划和阶段看板一致
|
||
|
||
---
|
||
|
||
## 3. 进行中
|
||
|
||
### S1-00 [Epic] 动作系统与 H5 页面拆分准备
|
||
|
||
## 背景
|
||
|
||
当前项目已经完成房间流、开局、定缺、出牌、AI 自动推进和实时消息骨架，但动作系统仍停留在最小主干。要继续推进 `PENG / GANG / HU / PASS` 和正式 H5 对局页，必须先完成本轮 Sprint。
|
||
|
||
## 阶段目标
|
||
|
||
- 动作系统具备扩展主干
|
||
- 私有候选动作模型可表达响应窗口
|
||
- H5 下一轮页面拆分有明确执行输入
|
||
|
||
## 关键交付
|
||
|
||
- 动作枚举与请求体扩展
|
||
- 动作校验与事件扩展
|
||
- 私有动作消息体扩展
|
||
- 响应裁决规则澄清
|
||
- H5 页面拆分方案
|
||
|
||
## 不做范围
|
||
|
||
- 不做完整胡牌结算
|
||
- 不做数据库持久化
|
||
- 不做完整 H5 视觉还原
|
||
|
||
## 退出标准
|
||
|
||
- 后端已能承接新增动作类型
|
||
- 前端已知道如何接响应候选
|
||
- 下一轮 H5 正式页面改造可以直接开始
|
||
|
||
### S1-04 [功能] 响应候选模型初版
|
||
|
||
## 背景
|
||
|
||
要支持 `PENG / GANG / HU / PASS`，系统不能只知道“执行了什么”，还必须知道“现在允许谁做什么”。这个模型是后续优先级裁决、前端动作面板、教学提示的共同基础。
|
||
|
||
## 目标
|
||
|
||
定义响应候选模型，能表达：
|
||
|
||
- 当前响应来源于哪次弃牌或事件
|
||
- 哪些玩家可以响应
|
||
- 每个玩家可响应哪些动作
|
||
- 响应窗口的生命周期
|
||
|
||
## 范围
|
||
|
||
- 设计候选动作数据结构
|
||
- 设计响应窗口上下文
|
||
- 设计与座位、玩家 ID、事件 ID 的关联
|
||
|
||
## 非范围
|
||
|
||
- 不在本任务里完成最终竞争裁决实现
|
||
|
||
## 依赖
|
||
|
||
- `S1-02`
|
||
- `S1-03`
|
||
|
||
## 产出物
|
||
|
||
- 后端候选动作模型
|
||
- 前后端字段语义说明
|
||
|
||
## 验收标准
|
||
|
||
- 候选结构可表达“谁现在能做什么”
|
||
- 后续可直接承接 `PASS`
|
||
- 前端动作面板无需再自行推导
|
||
|
||
## 验证方式
|
||
|
||
- 模型评审
|
||
- 后端：`mvn test`
|
||
|
||
### S1-07 [功能] H5 动作面板字段对齐与占位接入
|
||
|
||
## 背景
|
||
|
||
后端一旦开始发送响应候选，前端至少要能消费这些字段并用最小方式展示，否则会形成后端已支持、前端完全不可见的断层。
|
||
|
||
## 目标
|
||
|
||
让 H5 原型页先具备读取并展示响应候选字段的占位能力，为后续正式动作面板铺路。
|
||
|
||
## 范围
|
||
|
||
- 订阅并解析新的私有动作消息字段
|
||
- 在原型页中增加最小占位展示
|
||
- 区分“主动动作按钮”和“响应动作按钮”
|
||
|
||
## 非范围
|
||
|
||
- 不在本任务里完成正式视觉设计
|
||
- 不在本任务里完成多状态动画
|
||
|
||
## 依赖
|
||
|
||
- `S1-05`
|
||
|
||
## 产出物
|
||
|
||
- 前端字段适配
|
||
- H5 原型占位展示
|
||
|
||
## 验收标准
|
||
|
||
- 当前原型页能看到候选动作
|
||
- 不会影响现有定缺和出牌功能
|
||
|
||
## 验证方式
|
||
|
||
- 前端：`npm run build`
|
||
- H5 手工：检查候选动作占位区是否出现
|
||
|
||
---
|
||
|
||
## 4. 已完成
|
||
|
||
### S1-BASE-01 [基础] 当前最小链路已打通
|
||
|
||
## 已完成内容
|
||
|
||
- 房间创建、加入、准备、开局
|
||
- 未满 4 人自动补 AI
|
||
- 定缺
|
||
- 真人出牌
|
||
- AI 自动推进回合
|
||
- 统一动作入口初版
|
||
- 公共事件与私有消息骨架
|
||
- H5 原型操作台
|
||
|
||
## 对 Sprint 1 的意义
|
||
|
||
这是本次 Sprint 的基础底座，后续所有任务都建立在这条最小链路上。
|
||
|
||
### S1-01 [功能] 统一动作入口支持 `PENG / GANG / HU / PASS` 基础请求模型
|
||
|
||
## 已完成内容
|
||
|
||
- `GameSessionService.performAction` 不再只在服务层硬编码放行 `SELECT_LACK_SUIT / DISCARD`
|
||
- 兼容接口 `lack / discard` 已复用统一动作入口
|
||
- `GameActionRequest` 已补轻量上下文字段 `sourceSeatNo`
|
||
- `PENG / GANG / HU / PASS` 已可进入统一动作处理链
|
||
- 当前未实现动作会由处理器统一返回 `GAME_ACTION_UNSUPPORTED`
|
||
- 补充了“新动作走统一入口”和“未知动作被拒绝”的测试
|
||
|
||
## 验收结果
|
||
|
||
- 新动作不再被服务层提前拦死
|
||
- 现有定缺和出牌链路未回归
|
||
- `mvn test` 已通过
|
||
|
||
### S1-02 [功能] 动作校验器与处理链扩展
|
||
|
||
## 已完成内容
|
||
|
||
- `PENG / GANG / HU / PASS` 已有独立处理分支入口
|
||
- 新增动作已补统一的阶段校验
|
||
- 新增动作已补统一的来源座位校验
|
||
- 需要目标牌的动作已补必填参数校验
|
||
- 当前可明确区分三类结果：
|
||
- 参数非法
|
||
- 时机非法
|
||
- 进入分支但动作尚未实现
|
||
- 已补充对应单元测试
|
||
|
||
## 验收结果
|
||
|
||
- 非法时机请求会返回 `GAME_PHASE_INVALID`
|
||
- 缺少来源座位或目标牌会返回 `GAME_ACTION_PARAM_INVALID`
|
||
- 合法进入分支的新增动作当前返回 `GAME_ACTION_UNSUPPORTED`
|
||
- `mvn test` 已通过
|
||
|
||
### S1-03 [功能] 事件模型扩展，覆盖新增动作语义
|
||
|
||
## 已完成内容
|
||
|
||
- `GameEventType` 已补齐：
|
||
- `RESPONSE_WINDOW_OPENED`
|
||
- `RESPONSE_WINDOW_CLOSED`
|
||
- `PENG_DECLARED`
|
||
- `GANG_DECLARED`
|
||
- `HU_DECLARED`
|
||
- `PASS_DECLARED`
|
||
- `GameEvent` 已新增统一事件工厂方法，覆盖：
|
||
- 开局
|
||
- 定缺
|
||
- 阶段切换
|
||
- 摸牌
|
||
- 弃牌
|
||
- 切换回合
|
||
- 未来响应窗口事件
|
||
- 未来响应动作事件
|
||
- 现有公共事件已改为复用统一工厂方法，不再在多处手工拼接载荷
|
||
- 已补充事件工厂测试，验证新增动作事件载荷格式
|
||
|
||
## 验收结果
|
||
|
||
- 事件模型已能表达新增动作语义
|
||
- 现有事件载荷格式更加统一
|
||
- 后续 `S1-04 / S1-05` 可以直接复用事件约定
|
||
- `mvn test` 已通过
|
||
|
||
---
|
||
|
||
## 5. 依赖关系图
|
||
|
||
### 5.1 后端主线
|
||
|
||
`S1-01 -> S1-02 -> S1-03 -> S1-04 -> S1-05`
|
||
|
||
### 5.2 规则澄清主线
|
||
|
||
`S1-04 -> S1-06`
|
||
|
||
### 5.3 前端准备主线
|
||
|
||
`S1-05 -> S1-07 -> S1-08`
|
||
|
||
---
|
||
|
||
## 6. 推荐领取顺序
|
||
|
||
如果下一轮马上要开始做代码，建议按下面顺序领取：
|
||
|
||
1. `S1-01`
|
||
2. `S1-02`
|
||
3. `S1-03`
|
||
4. `S1-04`
|
||
5. `S1-05`
|
||
6. `S1-07`
|
||
7. `S1-06`
|
||
8. `S1-08`
|
||
|
||
原因：
|
||
|
||
- 先把后端动作主干做稳
|
||
- 再让前端能最小消费字段
|
||
- 最后输出裁决规则和页面结构文档，指导下一轮实现
|