408 lines
7.2 KiB
Markdown
408 lines
7.2 KiB
Markdown
# 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 不建议的写法
|
||
|
||
- “优化一下体验”
|
||
- “完善麻将逻辑”
|
||
- “改改前端”
|
||
|
||
这些标题无法表达目标、范围和验收标准，不适合作为可追踪任务。
|