TAPD 使用与 Git 提交规范
适用：使用 TAPD（企业版/标准版）做项目管理、GitHub 托管代码的研发团队
目录
💡 文档中
需求编号、工作区编号、你的中文姓名等是占位符，实际使用时替换为真实值，或直接从 TAPD「源码关键字」复制。
第一部分 核心理念
一句话：TAPD 是团队的"工作流转中枢"。
核心理念：所有"要干的活"——需求、缺陷、任务——都在 TAPD 里：
创建 → 分配 → 跟踪状态 → 完成
代码（在 GitHub）是干活的结果，通过"提交时带 TAPD 编号"自动关联，回到 TAPD 形成闭环：
[TAPD 需求] ——分配——> [开发写代码] ——提交带编号——> [自动关联回 TAPD]
^ |
| |
+-------------------- 形成闭环，可追溯 <-------------+最重要的原则 —— 让所有活儿都进 TAPD！
-
✅ 正确：需求/bug 在 TAPD 建工单，再开发
-
❌ 错误：微信说一句"帮我改下登录"，直接改代码（没记录、没法追溯）
第二部分 TAPD 项目搭建
2.1 创建项目（管理员操作，只需做一次）
-
登录 TAPD（从企业微信"工作台 → TAPD"进入，自动登录）
-
左侧"项目协作"旁点
+ -
选项目模板：
-
轻量协作：流程简单，适合小团队 / 流程轻
-
敏捷开发：有完整的需求-迭代-测试-缺陷流程
建议：先用轻量协作跑通，流程成熟后再升级
-
-
填写：
-
项目名称：中文项目名
-
项目英文名：拼音或英文，如
myproject
⚠️ 英文名创建后【不可修改】！想好再填
-
-
创建完成
2.2 开启应用
项目设置 → 应用设置，把要用到的应用打开：
| 应用 | 作用 |
|---|---|
| 需求 | 管理功能点 |
| 缺陷 | 管理 bug |
| 迭代 | 管理开发周期 |
| Github源码 | 关联 GitHub（见 2.4） |
| 任务 / 测试用例 / 测试计划 / 文档 | 可选，按需开启 |
开关打开后，对应菜单才会出现。按团队实际需要勾选即可。
2.3 添加成员
-
项目设置 → 成员与权限 → 项目成员 → 添加成员 -
输入同事姓名（前提：他已在企业微信组织内）
-
分配角色（权限不同）：
| 角色 | 权限 |
|---|---|
| 项目管理员 | 最高权限（建项目、配应用、管成员） |
| 开发 | 处理需求/缺陷、提交代码 |
| 测试 | 写用例、提缺陷、回归验证 |
| 只读 | 只能看，不能改 |
2.4 连接 GitHub 仓库（让代码提交自动关联 TAPD）
原理（3 步）：TAPD 启用 Github源码应用 → GitHub 配 Webhook → 提交时带编号
第一步：TAPD 端
-
项目设置 → 应用设置 → 启用 "Github源码" -
复制 TAPD 给的 Webhook 回调地址（一串
https://开头的网址）
第二步：GitHub 端（前提：需要是仓库管理员，能看到 Settings）
-
打开 GitHub 仓库 →
Settings → Webhooks → Add webhook -
填写：
字段 值 Payload URL 粘贴上一步 TAPD 的地址 Content type application/json（别选 form！）触发事件 Just the push eventActive 勾选 ✅ -
Add webhook保存 -
看到 绿色对勾 / Last delivery was successful = 网络通了 ✅
第三步：验证是否真正关联成功
⚠️ 绿勾只代表"通知送达"，不代表"关联到工作项"！
-
在 TAPD 建一个测试需求，记下编号
-
在 GitHub 提交一次代码，commit 带上从 TAPD 复制的源码关键字：
git commit -m "测试 <粘贴TAPD源码关键字>" git push -
回到该需求详情页 → 切到【Github提交】标签 → 看到刚才的提交记录 = 关联成功 🎉
更换仓库（如测试仓库换正式仓库）： TAPD 解除旧关联 → 旧 GitHub 仓库删 Webhook → 新仓库按上面重配
第三部分 Git 提交规范
3.1 提交前：先拿 TAPD 源码关键字
-
TAPD 打开要关联的需求 / 缺陷
-
点详情页【源码关键字】（也叫提交码）→ 复制
会得到类似这样一段（整段复制，别拆、别改数字）：
--story=需求编号@tapd-工作区编号 --user=你的中文姓名其中"工作区编号"是 TAPD 自动生成的项目标识，复制即可，无需手动填写。
3.2 Commit Message 格式
<类型>: <简短说明> <TAPD源码关键字>示例：
feat: 完善个人资料页面 <粘贴TAPD源码关键字>3.3 类型前缀（建议）
| 前缀 | 用途 | 示例 |
|---|---|---|
feat |
新功能 | feat: 新增头像上传 |
fix |
修 Bug | fix: 修复登录白屏 |
docs |
文档 | docs: 更新 README |
style |
格式调整 | style: 统一缩进 |
refactor |
重构 | refactor: 抽取公共组件 |
chore |
杂务/依赖 | chore: 升级依赖版本 |
3.4 三类工作项关键字
| 工作项 | 关键字 | 备注 |
|---|---|---|
| 需求 | --story=编号@tapd-工作区编号 |
常用 |
| 缺陷 | --bug=编号@tapd-工作区编号 |
常用 |
| 任务 | --task=编号@tapd-工作区编号 |
需先开启"任务"应用 |
编号 +
@tapd-工作区编号这段，直接从 TAPD「源码关键字」复制。
3.5 正确示例（照着抄）
# 做需求
git commit -m "feat: 新增头像上传功能 --story=需求编号@tapd-工作区编号 --user=你的中文姓名"
# 修缺陷
git commit -m "fix: 修复首页白屏问题 --bug=缺陷编号@tapd-工作区编号 --user=你的中文姓名"
# 改文档（文档类可不带编号）
git commit -m "docs: 更新部署说明"3.6 错误示例（别这么写）
git commit -m "update" # ❌ 没说明没编号
git commit -m "修复了bug" # ❌ 没编号关联不上
git commit -m "--story=需求编号@tapd-工作区编号" # ❌ 只有关键字没说明
git commit -m "修复 --task=编号 --user=工号" # ❌ 编号写错/用工号3.7 分支命名规范
| 场景 | 分支名 |
|---|---|
| 做需求 | feature/story-需求编号-简述 |
| 修缺陷 | bugfix/bug-缺陷编号-简述 |
| 主干 | main（受保护，不直接推） |
3.8 提交流程
-
从
main拉新分支（名带 TAPD 编号） -
开发，多次小提交（每步都带编号）
-
推 GitHub，提 Pull Request（PR）
-
至少 1 人 Code Review 通过后合并
-
合并后删临时分支
第四部分 TAPD 日常使用
4.1 如何建立"需求"
-
顶部菜单 → 需求 → 新建需求
-
填写：
-
标题：一句话说清要做什么（如"用户能上传头像"）
-
描述：详细说明、验收标准
-
负责人：指派给谁开发
-
所属迭代：放进哪个迭代
-
优先级：高 / 中 / 低
-
-
保存
→ 开发就能在迭代看板看到这条需求，开始干活
4.2 如何建立"缺陷（Bug）"
-
顶部菜单 → 缺陷 → 新建缺陷
-
填写：
-
标题：说清什么问题（如"登录页点击无反应"）
-
复现步骤：
1. xxx 2. xxx 3. 出现 xxx（要详细！） -
严重程度：致命 / 严重 / 一般 / 轻微
-
环境信息：浏览器、版本、账号等
-
指派给：分配给谁修
-
截图 / 日志：有就附上
-
-
保存
4.3 需求 / 缺陷的状态流转（有序的关键）
需求/缺陷从创建到完成，状态依次变化，每次动手都要改状态：
新建 → 研发中 → 已解决 → 测试中 → 已关闭
^ |
| |
+------ 重新打开（没修好）<----------+| 动作 | 改成什么状态 |
|---|---|
| 开始写代码 | 研发中 |
| 写完自测完 | 已解决 |
| 测试接手测 | 测试中 |
| 测试通过 | 已关闭 |
| 没修好退回 | 重新打开 |
⚠️ 状态不实时更新，看板就是假的，站会就失去意义。
4.4 如何使用"迭代"
迭代 = 固定一段时间，集中做完一批需求，到点发布，再开下一轮。
作用：把大项目切成一段段时间，进度可控、节奏稳定、定期出成果。
使用步骤：
-
创建迭代：迭代菜单 → 新建迭代
-
名称：如"迭代1 - X月上半月"
-
起止时间：建议固定周期（常见 2 周）
-
迭代目标：一句话说清这期要达成什么
-
-
规划需求进迭代（按优先级挑，量力而行，别贪多）：
-
方式A：需求列表 → 给每个需求选「所属迭代」
-
方式B：迭代详情页 →「添加需求」→ 勾选
-
-
分配负责人：迭代里每个需求指派给具体开发
-
看迭代看板干活：进迭代 → 看板视图，按状态分列（待处理 / 研发中 / 测试中 / 已完成）；开始做就把卡片拖到下一列，一眼看清本期进度
-
迭代结束（到点）：做完的需求 → 验证 → 发布；没做完的 → 移到下一个迭代（正常现象）；迭代状态改为「已完成」，开下一期
迭代状态流转：未开始 → 进行中 → 已完成
4.5 如何使用"任务"
任务 = 把一个需求拆成开发要做的具体技术步骤（需求是父，任务是子）。
用途：需求大、需多人协作或明确技术步骤时才用；小需求一人包办则不必拆。
使用步骤：
-
开启应用（默认可能未开）：
项目设置 → 应用设置 → 开启"任务" -
建任务（两种方式）：
-
方式A：需求详情页 →「添加子任务」（推荐，自动挂在需求下）
-
方式B：任务菜单 → 新建任务 → 选「所属需求」
-
-
填关键字段：
-
标题：技术动作（如"编写上传接口"）
-
所属需求：挂到哪个需求下
-
负责人：谁做
-
预估工时：预计多少小时
-
-
任务状态流转（比需求简单）：
新建 → 进行中 → 已完成 -
代码关联：若建的是任务，commit 用
--task=任务编号@tapd-工作区编号
需求 vs 任务：
| 需求 | 任务 | |
|---|---|---|
| 回答 | 做什么 | 怎么做 |
| 视角 | 业务 / 用户 | 技术 / 开发 |
| 谁建 | 产品 | 开发 |
| 关系 | 父 | 子（挂在需求下） |
4.6 代码如何关联到工作项
开发改完代码，提交时带上对应的 TAPD 关键字（见第三部分），TAPD 会自动把提交记录挂到对应的需求 / 缺陷 / 任务下。
各类工作项对应的提交关键字：
| 工作项 | 关键字 |
|---|---|
| 需求 | --story=编号@tapd-工作区编号 |
| 缺陷 | --bug=编号@tapd-工作区编号 |
| 任务 | --task=编号@tapd-工作区编号 |
效果：在工作项详情页【Github提交】标签，能看到：
"某某 往 你的仓库 的 xxx 分支提交了代码"（含提交人、时间、版本、改了哪些文件）
第五部分 团队高效协作
5.1 核心节拍：迭代（建议 2 周一轮）
迭代 = 固定一段时间（如 2 周）集中完成一批需求，做完发布，再开下一轮。节奏稳定，不无限期拖。
5.2 角色分工
| 角色 | 职责 |
|---|---|
| 产品 / PM | 建需求、排优先级、规划迭代 |
| 前端 / 后端开发 | 领需求 → 写代码提交带编号 → 修缺陷 |
| 测试 | 写测试用例、建测试计划、提缺陷、回归 |
| 项目负责人 | 建迭代、看迭代看板跟进、协调、组织发布 |
5.3 四条高效铁律
-
状态必须实时更新（看板真实）
-
代码必带 TAPD 编号（关联才有意义）
-
缺陷要规范（复现步骤 + 环境 + 截图）
-
分支名带编号（好追溯）
附录 常见问题
Q：忘了带 TAPD 编号，提交了怎么办？ A：代码已成功提交，只是没关联 TAPD。可在 TAPD 手动补链接，下次记得带。
Q：TAPD 源码关键字编号在哪复制？ A：需求/缺陷详情页的【源码关键字】按钮，点一下就复制好。
Q：--user= 填什么？ A：你的中文姓名（TAPD 里显示的名字），不要用工号。
Q：绿勾（Last delivery was successful）但 TAPD 没显示？ A：绿勾只代表 GitHub→TAPD 网络通了。检查：① 编号对不对（是不是真需求/缺陷的编号）② 关键字是不是从 TAPD 整段复制的 ③ --user 是不是中文名。
Q：想用"任务"管理开发分工，菜单里没有？ A：项目设置 → 应用设置 → 开启"任务"应用，菜单就会出现。
Q：一个提交能关联多个需求吗？ A：可以写多个 --story=，但建议一个提交只做一件事，更清晰。
浙公网安备 33010602011771号