13 KiB
13 KiB
G3FO Commit Jira — 详细工作流参考
目录
- 公司 Jira 附件文档政策
- Step 1: 获取并解析提交内容
- Step 2: 任务类型判定与三文档模板
- Step 3: Jira 任务查找与确认
- Step 4: Jira 字段映射与写入
- Step 5: Git Amend 命令详解
- 错误处理表
- Atlassian MCP 工具速查
公司 Jira 附件文档政策
自 2026年3月9日 起，何时附加「开发计划」「影响分析」「任务摘要」以公司强制性指南为准。
完整政策与详细条件表见 references/jira_commit_docs_policy.md。
- 附件命名规范：上传到 Jira 的 MD 必须命名为
<JIRA-ID>_Dev_Plan.md、<JIRA-ID>_Impact_Analysis.md、<JIRA-ID>_Task_Summary.md
例如：G3SF-123_Impact_Analysis.md。 - 根据任务类型仅生成并上传“需要”的文档；无需文档的琐碎改动仍可绑定 Jira 并 amend，但不生成报告、不写评论、不上传附件。
Step 1: 获取并解析提交内容
命令
# 检查 hash 是否为 HEAD
$head = git rev-parse HEAD
$provided = git rev-parse <hash>
if ($head -ne $provided) { Write-Error "提交不是 HEAD，无法 amend" }
# 获取完整 diff 和元数据
git show <hash>
# 仅获取原始 commit message（用于后续 amend 保留）
git log -1 --format="%B" <hash>
# 列出修改的文件（不含 diff 内容，快速预览）
git diff-tree --no-commit-id -r --name-status <hash>
解析要点
从 git show 输出中提取：
| 信息 | 说明 |
|---|---|
--- a/path / +++ b/path |
修改的文件路径 |
@@ ... @@ 上下文 |
修改的类名、方法名 |
+ 行 |
新增代码（方法签名、接口、配置） |
- 行 |
删除/替换代码 |
| 文件路径中的包名 | 推断所属服务（g3fo-trade-service, g3fo-margin-service 等） |
G3FO 服务包路径规律：
com.afe.g3fo.<service-short-name>.*→ 对应服务controller/api→ REST 接口层facade/facade.impl→ Dubbo 接口层service/service.impl→ 业务逻辑层
Step 2: 任务类型判定与三文档模板
2.1 按任务类型确定需生成的文档
| 任务类型 | 开发计划 | 影响分析 | 任务摘要 |
|---|---|---|---|
| 漏洞修复——简单（如拼写、界面对齐） | ❌ | ❌ | ❌ |
| 漏洞修复——中等（范围有限的逻辑错误） | ❌ | ✅ | ❌ |
| 漏洞修复——复杂/高风险（并发、核心模块） | ✅ | ✅ | ✅ |
| 小幅度增强（如小效用方法） | ❌ | ✅ | ❌ |
| 新功能/模块 | ✅ | ✅ | ✅ |
| 主要重构 | ✅ | ✅ | ✅ |
| 配置/基础设施变更 | ❌ | ✅ | ❌ |
生成内容后，在取得 Jira 编号后按公司规范保存为 <JIRA-ID>_Dev_Plan.md / _Impact_Analysis.md / _Task_Summary.md 再上传。无需文档时跳过生成与上传，仅绑定 Jira 并 amend。
2.2 影响分析报告模板
生成影响分析时严格按以下结构输出（Markdown 格式）：
## 影响分析报告
### 1. 改动概览
- **背景与目标**：[说明为什么改、解决什么问题]
- **涉及模块**：[列举受影响的服务/模块，如 g3fo-trade-service、g3fo-margin-service]
- **改动类型**：功能新增 / 缺陷修复 / 重构 / 配置变更（选一或多个）
### 2. 方法级改动分析
| 文件/类 | 方法/接口 | 改动说明 | 行为是否变更 |
|---------|----------|---------|------------|
| XxxService.java | `calculateMargin()` | 新增空值校验 | 否（边界补强） |
### 3. 调用方与影响范围
| 调用方 | 文件路径 | 影响说明 |
|--------|---------|---------|
| XxxController | controller/XxxController.java | 入参校验增强，现有调用方兼容 |
- **破坏性变更**：是 / 否
- 如为"是"，具体变更点：[列出方法签名、返回值、异常类型变化]
### 4. 风险与回滚
- **风险级别**：低 / 中 / 高
- **风险说明**：[说明原因]
- **回滚方式**：回退版本 / 关闭特性开关 / 回滚配置
- **回滚方式是否简单**：是 / 否
### 5. 验证与测试
- **已执行测试**：单测 / 集成测试 / 冒烟测试（选已执行的）
- **关键用例**：[简述关键场景及预期结果]
- **需线上观察**：[列出需关注的日志关键字、监控指标或告警项]
如果 diff 信息不足以确认调用方，在报告中注明：「建议在代码库中搜索
<方法名>确认所有调用方」。
2.3 开发计划模板（仅当任务类型要求时生成）
开发计划用于概述步骤、设计方法和技术决策。结构示例：
## 开发计划
### 1. 目标与范围
- **目标**：[本任务要达成的结果]
- **范围**：[涉及模块、接口、配置等]
### 2. 步骤与设计方法
1. [步骤一：如需求分析、接口设计]
2. [步骤二：如实现方案、关键类/方法]
3. [步骤三：如测试与验证]
### 3. 技术决策
- [关键技术选型或实现方式及理由]
- [与现有架构的衔接方式]
2.4 任务摘要模板（仅当任务类型要求时生成）
任务摘要用于简要回顾所完成的工作，包括任何偏离计划的地方。结构示例：
## 任务摘要
### 1. 完成内容
- [已完成的主要改动与交付物]
### 2. 与计划差异（如有）
- [若实际实现与开发计划有偏差，在此说明原因与结果]
### 3. 后续建议（可选）
- [遗留事项、后续优化或文档更新建议]
Step 3: Jira 任务查找与确认
JQL 查询
project = G3SF AND assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC
- 限制返回 5 条，避免信息过载
- 若返回 0 条，直接告知用户并自动进入新建流程
展示格式
找到以下 G3SF 进行中任务，请输入编号绑定，或输入 0 新建：
1. G3SF-101 [修复保证金计算逻辑] 状态: In Progress
2. G3SF-98 [交易服务批量撤单性能优化] 状态: To Do
3. G3SF-95 [用户服务登录接口重构] 状态: In Progress
0. 新建一个 G3SF Task
请输入 (1/2/3/0)：
确认规则
| 用户输入 | 行为 |
|---|---|
1~N |
使用对应任务，写入评论 |
0 |
新建 Jira Task |
n / no |
等同于 0，新建任务 |
| 其他 | 重新提问一次 |
Step 4: Jira 字段映射与写入
新建 Issue 字段
调用 jira_create_issue（或鉴权后发现的等效工具），传入：
| 字段 | 值 |
|---|---|
project |
G3SF |
issuetype |
Task |
summary |
必须带 [G3SF] 前缀，格式：[G3SF] 提炼后的一句话描述（≤100 字符） |
description |
完整影响分析报告（Markdown / ADF 格式） |
assignee |
必须为当前登录账号（传入当前用户 accountId/name，确保新建任务经办人为自己） |
Summary 生成规则：
- 标题必须统一加前缀：
[G3SF]+ 正文。例如：[G3SF] [g3fo-trade-service] 修复批量撤单时的并发锁问题 - 正文优先使用原始 commit message 的第一行（若描述清晰），否则根据修改内容生成：
[服务名] 功能描述
新建 Issue 成功后，若已配置 jira_upload.env 且本任务需要文档，按公司命名将对应 MD 写入本地后上传到该新 Issue。
保存报告为 MD 并上传附件
- 按公司规范命名并保存：取得 Jira 编号（如
G3SF-123）后，将 Step 2 生成的各文档内容分别写入本地文件，文件名必须为：<JIRA-ID>_Dev_Plan.md<JIRA-ID>_Impact_Analysis.md<JIRA-ID>_Task_Summary.md
仅保存本任务类型要求的那几份（见 2.1 按任务类型确定需生成的文档）。保存位置：当前 Git 项目根目录或项目约定目录（如docs/）。
- 上传到 Jira 附件：Atlassian MCP 不支持上传文件，使用本技能自带脚本上传上述 MD 到当前 Issue：
- 配置文件：在技能目录下配置
jira_upload.env（JIRA_BASE_URL、JIRA_EMAIL、JIRA_API_TOKEN），详见references/env_config.md。 - 命令示例（PowerShell 用
;连接，勿用&&），按需上传多文件：python skills/g3fo-commit-jira/scripts/upload_attachment.py --config "skills/g3fo-commit-jira/jira_upload.env" --issue "G3SF-101" --file "G3SF-101_Impact_Analysis.md" --file "G3SF-101_Dev_Plan.md" --file "G3SF-101_Task_Summary.md" - 未配置
jira_upload.env时跳过上传，仅写评论。
- 配置文件：在技能目录下配置
写入已有 Issue（评论）
调用 jira_add_comment（或等效工具），字段：
| 字段 | 值 |
|---|---|
issue_key |
用户选择的 issue key，如 G3SF-101 |
body |
完整影响分析报告（与已保存的 MD 内容一致） |
Jira 描述格式兼容
部分 Jira 实例使用 Atlassian Document Format (ADF) 而非纯 Markdown。若 MCP 工具提示格式错误，则：
- 将 Markdown 内容作为纯文本写入
- 或使用
{code}块包裹（Jira Wiki 格式兼容）
Step 5: Git Amend 命令详解
PowerShell（Windows 环境）
在 Windows PowerShell 中，直接使用 $origMsg 可能会导致编码问题（乱码）。必须显式指定输出编码为 UTF8。
# 设置控制台和输出编码为 UTF8，防止中文乱码
$OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
# 获取原始 commit message（保留完整内容）
$origMsg = (git log -1 --format="%B").TrimEnd()
# Jira key（从上一步获取）
$jiraKey = "G3SF-123"
# 追加 Jira 行并 amend（不 push）
# 使用 --cleanup=verbatim 确保消息内容不被 git 自动修剪导致编码转换问题
git commit --amend -m "$origMsg`n`n**** Jira $jiraKey" --cleanup=verbatim
Bash/Linux（供参考）
origMsg=$(git log -1 --format="%B" | sed 's/[[:space:]]*$//')
jiraKey="G3SF-123"
git commit --amend -m "$origMsg
**** Jira $jiraKey"
Amend 注意事项
--amend只修改 HEAD，不改变工作区内容- 如果有 GPG 签名要求，告知用户需确认签名
- amend 后 commit hash 会变更，这是正常现象
- 禁止 push：本 skill 不执行
git push，提交操作到amend为止
结果验证
git log -1 --format="%B" # 确认 Jira 行已追加
git log --oneline -1 # 查看 commit 摘要
错误处理表
| 错误场景 | 检测方式 | 处理方式 |
|---|---|---|
| 修订号不存在 | git rev-parse <hash> 报错 |
停止，提示用户提供正确的修订号。 |
| 提交 hash 不是 HEAD | git rev-parse HEAD ≠ git rev-parse <hash> |
停止，提示用户确认 hash（只有 HEAD 才能 amend）。 |
| 项目路径不正确 | git rev-parse --is-inside-work-tree 失败 |
提示用户在正确的 git 项目目录下操作。 |
| Atlassian MCP 未鉴权 | STATUS.md 有提示 / 工具调用返回 401 |
调用 mcp_auth，等待用户完成授权。 |
| Atlassian 插件未安装 | tools/ 目录为空或 MCP 调用失败 |
引导用户在 Cursor Settings → MCP 安装 Atlassian 插件 |
| Jira 项目 G3SF 不存在 | jira_create_issue 返回 404/400 |
提示用户确认 Jira 实例 URL 和项目 key |
| 工作区有未提交变更 | git status --porcelain 有输出 |
警告：amend 会将未暂存变更排除在外，建议先 git add 或 stash |
| commit message 中已有 Jira 行 | message 中包含 **** Jira |
跳过追加，提示用户该提交已绑定 |
| Jira 搜索无结果 | 工具返回空列表 | 直接进入新建流程，无需用户确认 |
| 未配置 jira_upload.env | 上传前检查配置不存在 | 跳过上传附件，仅通过 jira_add_comment 写入报告；提示用户可配置后使用脚本上传 |
| 任务类型判定为「无需文档」 | 按政策表属简单漏洞/琐碎改动 | 不生成报告、不写评论、不上传附件；仍执行 Jira 绑定与 commit --amend，将 Jira 编号追加到 commit message |
Atlassian MCP 工具速查
鉴权成功后，通过列举 mcps/plugin-atlassian-atlassian/tools/ 确认可用工具。常见工具名：
| 功能 | 可能的工具名 |
|---|---|
| 搜索 Issue | jira_search_issues, jira_jql_search |
| 创建 Issue | jira_create_issue |
| 获取 Issue 详情 | jira_get_issue |
| 添加评论 | jira_add_comment |
| 更新 Issue | jira_update_issue |
| 获取当前用户 | jira_get_current_user |
| 获取项目列表 | jira_get_projects |
| 上传附件 | MCP 不支持，使用 scripts/upload_attachment.py + jira_upload.env |
实际工具名以
tools/目录下的 JSON 文件名为准，鉴权后务必先列目录确认。上传附件需使用本技能自带的 Python 脚本，见references/env_config.md。