xzmaster/docs/WEEKLY_PLAN_BOARD.md

XueZhanMaster 周计划看板

本文档用于把阶段目标转成连续数周内可执行的工作安排。
当前状态快照日期：2026-03-20

---

1. 使用说明

1.1 这份文档解决什么问题

• 接下来 1 到 8 周应该先做什么
• 每周的重点输出是什么
• 每周结束怎么判断是否过关
• 如果周目标未完成，怎么顺延

1.2 计划原则

• 以“相对周次”而不是绝对日期表达，便于后续新对话滚动接续
• 每周只放 1 到 2 个主目标，避免过载
• 每周必须带可验证产出
• H5、动作系统、教学边界三者持续联动，不单独割裂推进

1.3 看板状态定义

• 待做：已排入未来周计划，但尚未开始
• 进行中：当前周期重点事项
• 已完成：已经形成结果，可进入下一周

---

2. 待做

Week 3 规则闭环与结算骨架

• 周目标：
  • 完成胡牌判定主干
  • 明确基础杠分和局终处理
• 关键任务：
  • 设计结算结果模型
  • 接入基础结算事件
  • 前端增加结算结果展示占位
• 周产出：
  • 后端规则判定骨架
  • 结算事件定义
  • 结算页面数据结构
• 周验收：
  • 可从开局走到一轮基础结算

Week 4 H5 正式对局页第一版

• 周目标：
  • 完成 H5 对局页结构化改造
• 关键任务：
  • 拆分 App.vue
  • 完成房间页 / 对局页基础路由或页面切换结构
  • 完成手牌区、动作区、事件区布局
• 周产出：
  • 页面拆分代码
  • H5 布局初版
• 周验收：
  • 360px 到 430px 宽度可完成当前主流程

Week 5 教学开关与私有教学体验

• 周目标：
  • 实现真人玩家独立 AI 教学开关
• 关键任务：
  • 后端开关接口
  • 前端局内开关组件
  • 私有教学消息按开关发送
• 周产出：
  • 教学开关完整链路
  • 开关状态说明文档
• 周验收：
  • A 玩家关闭教学不影响 B 玩家

Week 6 真人邀请与 AI 强度配置

• 周目标：
  • 完成房间邀请和补位 AI 强度选择
• 关键任务：
  • 房间邀请码或邀请链接
  • 房主配置区
  • AI 强度前后端联动
• 周产出：
  • 房间配置 UI
  • AI 强度配置接口
• 周验收：
  • 真实房间中可邀请真人，不足 4 人自动补 AI

Week 7 持久化第一阶段

• 周目标：
  • 房间与对局会话落库
• 关键任务：
  • 设计表结构
  • 改造房间和会话查询
  • 增加迁移脚本
• 周产出：
  • 数据库表
  • 基础持久化服务
• 周验收：
  • 不再完全依赖内存态

Week 8 复盘与错题本第一版

• 周目标：
  • 完成局后复盘最小闭环
• 关键任务：
  • 决策日志沉淀
  • 复盘结果接口
  • 复盘页和错题本占位
• 周产出：
  • 复盘接口
  • 复盘页初版
• 周验收：
  • 每局结束后至少有一个可查看的个人复盘结果

---

3. 进行中

Week 1 动作系统扩展主干

• 周目标：
  • 完成 PENG / GANG / HU / PASS 的动作模型与统一入口接入
• 当前背景：
  • 目前统一动作入口已存在，但仅支持 SELECT_LACK_SUIT / DISCARD
• 关键任务：
  • 扩展动作枚举与请求体
  • 扩展动作校验逻辑
  • 扩展事件模型
  • 补动作系统测试
• 周产出：
  • 后端动作系统主干扩展
  • 前端动作按钮占位
  • 接口说明更新
• 周验收：
  • 新动作不走专用接口
  • 测试覆盖基本主流程
• 依赖提醒：
  • 后续 Week 2 的优先级裁决依赖本周结果

Week 2 响应候选与 H5 页面拆解准备

• 周目标：
  • 完成响应候选模型，并同步为 H5 正式页面拆分做准备
• 当前背景：
  • 动作面板最终形态取决于响应候选模型
• 关键任务：
  • 定义弃牌后的可响应动作候选结构
  • 设计私有动作消息体
  • 梳理 H5 对局页的信息区块
  • 输出页面拆分草图或结构说明
• 周产出：
  • 响应候选模型说明
  • H5 页面拆分说明
• 周验收：
  • 下一轮可以直接开始 H5 页面重构

---

4. 已完成

Week 0 工程骨架与最小链路打通

• 周目标：
  • 打通前后端最小可运行链路
• 已完成内容：
  • Spring Boot 与 Vue 3 工程建立
  • 房间流跑通
  • 开局与 AI 补位
  • 定缺与出牌
  • WebSocket 公私消息骨架
  • H5 原型页面
• 验收结果：
  • mvn test 通过
  • npm run build 通过

Week 0.5 文档体系升级

• 周目标：
  • 从单一主计划升级为可持续接手的文档体系
• 已完成内容：
  • 重写 README
  • 扩写主计划
  • 新增阶段任务看板
  • 新增周计划看板
  • 新增 Issue 模板看板
• 验收结果：
  • 新对话可按文档直接继续推进

---

5. 周计划滚动规则

5.1 每周开始前

• 从阶段看板选择 1 到 2 个最高优先级任务
• 确认前置依赖是否已经满足
• 明确本周“必须完成”和“可延期”边界

5.2 每周结束后

• 未完成但仍是最高优先级的任务，顺延到下周 进行中
• 已完成的任务，回写到阶段看板的 已完成
• 新暴露出的跨模块风险，补充到主计划风险章节

5.3 不要这样排周计划

• 同一周同时推进规则、H5、持久化、复盘四大块核心开发
• 只写“优化体验”“完善功能”这种无法验收的目标
• 不写依赖关系，导致周目标互相卡死