# 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 不建议的写法

- “优化一下体验”
- “完善麻将逻辑”
- “改改前端”

这些标题无法表达目标、范围和验收标准，不适合作为可追踪任务。