first commit

docs/ISSUE_TEMPLATES_BOARD.md

@@ -0,0 +1,407 @@
+# XueZhanMaster Issue 模板与看板
+
+本文档用于统一任务拆解方式，避免每次新建任务都从零思考标题、背景、验收与风险。  
+当前状态快照日期：`2026-03-20`
+
+---
+
+## 1. 使用说明
+
+### 1.1 这份文档解决什么问题
+
+- 单个任务如何描述才算完整
+- 功能、缺陷、技术债、研究、测试等任务分别怎么写
+- 这些 Issue 在项目里如何进入“待做 / 进行中 / 已完成”的看板流转
+
+### 1.2 Issue 推荐字段
+
+每个 Issue 最少应包含：
+
+- 标题
+- 背景
+- 目标
+- 范围
+- 非范围
+- 验收标准
+- 风险与依赖
+- 验证方式
+
+### 1.3 看板状态定义
+
+- `待做`：模板已准备好，可直接拿去建 Issue
+- `进行中`：当前项目里正在高频使用的模板类型
+- `已完成`：模板已经稳定，可直接复用，不需要再大改
+
+---
+
+## 2. 待做
+
+### TPL-07 运维与可观测性任务模板
+
+- 适用场景：
+  - 后续接入鉴权、日志、告警、指标、重连监控时使用
+- 当前为什么在待做：
+  - 现阶段系统仍是原型期，尚未进入完整运维治理阶段
+- 后续纳入时机：
+  - 持久化和 WebSocket 鉴权启动后
+
+### TPL-08 数据迁移与初始化脚本模板
+
+- 适用场景：
+  - 接数据库后新增表结构和初始化脚本时使用
+- 当前为什么在待做：
+  - 表结构尚未最终落地
+
+---
+
+## 3. 进行中
+
+### TPL-01 功能开发 Issue 模板
+
+- 适用场景：
+  - 新增房间能力
+  - 新增动作系统能力
+  - 新增 H5 页面能力
+  - 新增教学或复盘功能
+- 当前正在高频使用原因：
+  - 当前项目主要仍在新功能搭建期
+
+模板：
+
+```md
+# [功能] <功能标题>
+
+## 背景
+<为什么要做，当前缺什么，影响哪些链路>
+
+## 目标
+<本次要交付什么>
+
+## 范围
+- <范围 1>
+- <范围 2>
+
+## 非范围
+- <这次明确不做什么>
+
+## 关键约束
+- 教学不能泄露隐藏信息
+- 公共消息与私有消息必须分离
+- 新动作必须走统一动作入口
+- H5 必须可用
+
+## 产出物
+- <代码>
+- <文档>
+- <测试>
+
+## 验收标准
+- <标准 1>
+- <标准 2>
+
+## 验证方式
+- 后端：`mvn test`
+- 前端：`npm run build`
+- H5 手工验收：<补充具体验收项>
+
+## 风险与依赖
+- 风险：<风险项>
+- 依赖：<依赖项>
+```
+
+### TPL-02 缺陷修复 Issue 模板
+
+- 适用场景：
+  - 规则错误
+  - WebSocket 消息错误
+  - H5 误触、遮挡、崩溃
+  - 私有消息串号
+- 当前正在高频使用原因：
+  - 动作系统和 H5 仍在快速演进，缺陷修复需求会持续出现
+
+模板：
+
+```md
+# [缺陷] <问题标题>
+
+## 问题现象
+<用户看到了什么异常>
+
+## 复现步骤
+1. <步骤 1>
+2. <步骤 2>
+3. <步骤 3>
+
+## 期望结果
+<正确表现>
+
+## 实际结果
+<当前错误表现>
+
+## 影响范围
+- <后端 / 前端 / H5 / WebSocket / 教学 / 结算>
+
+## 初步判断
+<怀疑原因，可选>
+
+## 验收标准
+- <修复后如何验证>
+
+## 验证方式
+- 自动测试：<如有>
+- 手工验证：<具体验收流程>
+```
+
+### TPL-03 技术债 / 重构 Issue 模板
+
+- 适用场景：
+  - 单文件过大
+  - 状态管理过于混乱
+  - 动作逻辑重复
+  - 文档与代码脱节
+- 当前正在高频使用原因：
+  - 当前 `App.vue` 和原型态实现天然存在后续重构需求
+
+模板：
+
+```md
+# [技术债] <任务标题>
+
+## 背景
+<当前实现为何难维护，具体痛点是什么>
+
+## 重构目标
+<本次希望改善什么>
+
+## 不变约束
+- 不改变既有对外接口语义，除非明确说明
+- 不绕开统一动作入口
+- 不破坏 H5 当前可用主流程
+
+## 拆解任务
+- <任务 1>
+- <任务 2>
+
+## 风险
+- <风险 1>
+- <风险 2>
+
+## 验收标准
+- <可维护性改进的判断标准>
+
+## 验证方式
+- `mvn test`
+- `npm run build`
+- 关键主流程回归
+```
+
+### TPL-04 H5 体验任务模板
+
+- 适用场景：
+  - 页面布局
+  - 触控交互
+  - 安全区适配
+  - 教学面板展示
+- 当前正在高频使用原因：
+  - H5 已被明确纳入正式范围，后续多个任务都需要该模板
+
+模板：
+
+```md
+# [H5] <任务标题>
+
+## 背景
+<当前 H5 在什么场景不好用>
+
+## 目标
+<要改善什么体验>
+
+## 关键场景
+- `360x800`
+- `390x844`
+- `430x932`
+
+## 任务范围
+- <布局>
+- <交互>
+- <性能或弱网>
+
+## 验收标准
+- <视口验收 1>
+- <交互验收 2>
+- <弱网验收 3>
+
+## 验证方式
+- `npm run build`
+- H5 手工验收截图或记录
+```
+
+### TPL-05 规则研究 / Spike 模板
+
+- 适用场景：
+  - 血战到底具体规则确认
+  - 响应优先级策略确认
+  - AI 决策方案对比
+- 当前正在高频使用原因：
+  - 动作系统和结算阶段都需要先做规则澄清
+
+模板：
+
+```md
+# [研究] <主题标题>
+
+## 研究问题
+<本次需要明确的规则或技术问题>
+
+## 背景
+<为什么现在必须研究这个问题>
+
+## 备选方案
+### 方案 A
+<说明>
+
+### 方案 B
+<说明>
+
+## 对比维度
+- 实现复杂度
+- 成本
+- 风险
+- 对 H5 和教学系统的影响
+
+## 结论
+<推荐方案>
+
+## 后续动作
+- <需要转成哪些功能 Issue>
+```
+
+### TPL-06 测试 / 验收任务模板
+
+- 适用场景：
+  - 某阶段完成后的验收
+  - H5 专项验收
+  - 动作系统回归测试
+- 当前正在高频使用原因：
+  - 项目正处于主流程持续扩张阶段，回归验证很重要
+
+模板：
+
+```md
+# [测试] <任务标题>
+
+## 测试目标
+<本次要验证什么>
+
+## 测试范围
+- <接口>
+- <页面>
+- <消息链路>
+
+## 用例清单
+1. <用例 1>
+2. <用例 2>
+3. <用例 3>
+
+## 通过标准
+- <标准 1>
+- <标准 2>
+
+## 执行记录
+- 后端：`mvn test`
+- 前端：`npm run build`
+- H5：<手工结果>
+```
+
+---
+
+## 4. 已完成
+
+### TPL-00 Epic / 阶段任务模板
+
+- 适用场景：
+  - 需要承接一个阶段性目标时使用
+- 已稳定原因：
+  - 当前主计划、阶段看板、周计划都可基于同一 Epic 结构展开
+
+模板：
+
+```md
+# [Epic] <阶段标题>
+
+## 背景
+<这一阶段为什么存在>
+
+## 阶段目标
+<阶段成功的定义>
+
+## 关键交付
+- <交付 1>
+- <交付 2>
+
+## 不做范围
+- <本阶段不做什么>
+
+## 依赖关系
+- 前置：<前置任务>
+- 后续：<后续任务>
+
+## 退出标准
+- <完成条件 1>
+- <完成条件 2>
+```
+
+### TPL-09 文档任务模板
+
+- 适用场景：
+  - 更新 README、开发计划、看板、接口说明
+- 已稳定原因：
+  - 当前项目已建立“文档先行 + 看板同步”的协作方式
+
+模板：
+
+```md
+# [文档] <任务标题>
+
+## 背景
+<为什么当前文档不足>
+
+## 目标
+<本次文档要补齐什么>
+
+## 范围
+- <文档 1>
+- <文档 2>
+
+## 验收标准
+- 新对话能否直接接手
+- 文档之间是否互相引用清楚
+- 是否明确状态、验收和依赖
+```
+
+---
+
+## 5. 看板流转建议
+
+### 5.1 建议流程
+
+1. 先从本页选一个合适模板
+2. 生成具体 Issue
+3. 放入项目看板 `待做`
+4. 开发开始后移到 `进行中`
+5. 验收通过后移到 `已完成`
+
+### 5.2 Issue 命名建议
+
+- `[功能] 动作系统支持 PENG / GANG / HU / PASS`
+- `[H5] 对局页改造为正式移动端布局`
+- `[缺陷] 私有教学消息错误广播给其他玩家`
+- `[技术债] 拆分 App.vue，提炼房间页与对局页`
+
+### 5.3 不建议的写法
+
+- “优化一下体验”
+- “完善麻将逻辑”
+- “改改前端”
+
+这些标题无法表达目标、范围和验收标准，不适合作为可追踪任务。