# Workflow: Sprint Report（Sprint 报告）

> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
> **AI Agent 工作流**：此工作流专为 AI Agent 设计，用于自动生成 Sprint 进度报告。

AI Agent 自动汇总 Sprint 期间的 Issue、PR、提交记录等数据，生成结构化的进度报告，帮助团队了解项目进展。

## 工作流概述

Sprint Report 工作流收集 Sprint 期间的所有活动数据，包括 Issue 完成情况、PR 合并状态、代码提交统计、团队成员贡献等，自动生成团队进度报告。

## 适用场景

- **Sprint 回顾**：为 Sprint 回顾会议提供数据支持
- **进度汇报**：向管理层汇报项目进展
- **团队协调**：协调团队工作计划和资源分配
- **绩效评估**：评估团队和个人的工作效率

## 工作流步骤

### 步骤 1：确定报告时间范围

```bash
# 设置 Sprint 时间范围（通常为 2 周）
SPRINT_START="2026-01-01"
SPRINT_END="2026-01-14"

# 或者基于当前时间计算
SPRINT_END=$(date +%Y-%m-%d)
SPRINT_START=$(date -d "14 days ago" +%Y-%m-%d)
```

### 步骤 2：获取 Issue 统计

```bash
# 获取 Sprint 期间关闭的 Issue
CLOSED_ISSUES=$(gitlink-cli issue +list --state closed --format json | \
  jq '.data.issues[] |
      select(.closed_at >= "'$SPRINT_START'" and .closed_at <= "'$SPRINT_END'")')

# 获取新增 Issue
NEW_ISSUES=$(gitlink-cli issue +list --state open --format json | \
  jq '.data.issues[] |
      select(.created_at >= "'$SPRINT_START'" and .created_at <= "'$SPRINT_END'")')

# 统计 Issue 数据
CLOSED_COUNT=$(echo "$CLOSED_ISSUES" | jq -s 'length')
NEW_COUNT=$(echo "$NEW_ISSUES" | jq -s 'length')
```

### 步骤 3：获取 PR 统计

```bash
# 获取 Sprint 期间合并的 PR
MERGED_PRS=$(gitlink-cli pr +list --state merged --format json | \
  jq '.data.prs[] |
      select(.merged_at >= "'$SPRINT_START'" and .merged_at <= "'$SPRINT_END'")')

# 获取新建的 PR
NEW_PRS=$(gitlink-cli pr +list --state open --format json | \
  jq '.data.prs[] |
      select(.created_at >= "'$SPRINT_START'" and .created_at <= "'$SPRINT_END'")')

# 统计 PR 数据
MERGED_COUNT=$(echo "$MERGED_PRS" | jq -s 'length')
NEW_PR_COUNT=$(echo "$NEW_PRS" | jq -s 'length')
```

### 步骤 4：获取提交统计

```bash
# 获取项目活动数据
ACTIVITY=$(gitlink-cli api GET /:owner/:repo/activity --format json | \
  jq ".data.activity[] |
      select(.created_at >= \"$SPRINT_START\" and .created_at <= \"$SPRINT_END\")")

# 提取提交数据
COMMITS=$(echo "$ACTIVITY" | jq 'select(.type == "commit")')
COMMIT_COUNT=$(echo "$COMMITS" | jq -s 'length')
```

### 步骤 5：分析团队贡献

```bash
# 按团队成员统计贡献
CONTRIBUTORS=$(gitlink-cli api GET /:owner/:repo/activity --format json | \
  jq ".data.activity[] |
      select(.created_at >= \"$SPRINT_START\" and .created_at <= \"$SPRINT_END\") |
      .author |
      group_by(.) |
      map({developer: .[0], count: length}) |
      sort_by(.count) | reverse")
```

### 步骤 6：生成 Sprint 报告

```bash
# 生成结构化的 Sprint 报告
SPRINT_REPORT="# 📊 Sprint 进度报告

**时间范围**: $SPRINT_START 至 $SPRINT_END
**Sprint 周期**: 14 天

## 🎯 目标达成情况

### Issue 统计
- ✅ **完成 Issue**: $CLOSED_COUNT 个
- 🆕 **新增 Issue**: $NEW_COUNT 个
- 📈 **完成率**: $(($CLOSED_COUNT * 100 / ($CLOSED_COUNT + $NEW_COUNT)))%

### Pull Request 统计
- 🔀 **合并 PR**: $MERGED_COUNT 个
- 🆕 **新建 PR**: $NEW_PR_COUNT 个
- ✅ **合并率**: $(($MERGED_COUNT * 100 / ($MERGED_COUNT + $NEW_PR_COUNT)))%

### 代码提交统计
- 💻 **提交次数**: $COMMIT_COUNT 次
- 📊 **日均提交**: $(($COMMIT_COUNT / 14)) 次/天

## 👥 团队贡献
$(echo "$CONTRIBUTORS" | jq -r '.[] | "- **\(.developer)**: \(.count) 次贡献"')

## 🎉 主要成就
$(echo "$CLOSED_ISSUES" | jq -r '.[] | "- 完成 Issue: \(.subject)"')

## 🔄 进行中工作
$(echo "$NEW_ISSUES" | jq -r '.[] | "- 新建 Issue: \(.subject)"')

## 📈 下期计划
1. 继续进行中的 Issue 开发
2. 新功能规划和设计
3. 技术债务清理
4. 性能优化工作"

# 输出报告
echo "$SPRINT_REPORT"
```

## 完整工作流示例

```bash
#!/bin/bash

# Sprint 报告自动化生成脚本

OWNER="username"
REPO="myproject"
REPORT_DIR="sprint_reports"

# 获取时间范围
SPRINT_NUMBER=$1
if [ -z "$SPRINT_NUMBER" ]; then
    # 计算当前是第几个 Sprint（假设每 Sprint 2 周，从项目开始计算）
    PROJECT_START="2026-01-01"
    CURRENT_DATE=$(date +%Y-%m-%d)
    DAYS_DIFF=$(( ($(date -d "$CURRENT_DATE" +%s) - $(date -d "$PROJECT_START" +%s)) / 86400 ))
    SPRINT_NUMBER=$((DAYS_DIFF / 14 + 1))
fi

SPRINT_START=$(date -d "$((SPRINT_NUMBER - 1)) weeks ago" +%Y-%m-%d)
SPRINT_END=$(date -d "$((SPRINT_NUMBER - 1)) weeks ago +14 days" +%Y-%m-%d)

echo "生成 Sprint $SPRINT_NUMBER 报告 ($SPRINT_START - $SPRINT_END)"

# 创建报告目录
mkdir -p "$REPORT_DIR"

# 1. 获取 Issue 数据
echo "收集 Issue 数据..."
ISSUE_DATA=$(gitlink-cli issue +list --owner $OWNER --repo $REPO --format json)

CLOSED_ISSUES=$(echo "$ISSUE_DATA" | jq -r ".data.issues[] | 
    select(.closed_at >= \"$SPRINT_START\" and .closed_at <= \"$SPRINT_END\")")
    
NEW_ISSUES=$(echo "$ISSUE_DATA" | jq -r ".data.issues[] | 
    select(.created_at >= \"$SPRINT_START\" and .created_at <= \"$SPRINT_END\")")

CLOSED_COUNT=$(echo "$CLOSED_ISSUES" | jq -s 'length')
NEW_COUNT=$(echo "$NEW_ISSUES" | jq -s 'length')

# 2. 获取 PR 数据
echo "收集 PR 数据..."
PR_DATA=$(gitlink-cli pr +list --owner $OWNER --repo $REPO --format json)

MERGED_PRS=$(echo "$PR_DATA" | jq -r ".data.prs[] | 
    select(.merged_at >= \"$SPRINT_START\" and .merged_at <= \"$SPRINT_END\")")
    
NEW_PRS=$(echo "$PR_DATA" | jq -r ".data.prs[] | 
    select(.created_at >= \"$SPRINT_START\" and .created_at <= \"$SPRINT_END\")")

MERGED_COUNT=$(echo "$MERGED_PRS" | jq -s 'length')
NEW_PR_COUNT=$(echo "$NEW_PRS" | jq -s 'length')

# 3. 获取提交数据
echo "收集提交数据..."
COMMITS=$(gitlink-cli api GET "/$OWNER/$REPO/commits" --format json | \
    jq -r ".data[] | 
    select(.committed_date >= \"$SPRINT_START\" and .committed_date <= \"$SPRINT_END\")")

COMMIT_COUNT=$(echo "$COMMITS" | jq -s 'length')

# 4. 分析团队贡献
echo "分析团队贡献..."
CONTRIBUTORS=$(echo "$COMMITS" | jq -r '.author | group_by(.) | 
    map({developer: .[0], count: length}) | 
    sort_by(.count) | reverse')

# 5. 分析 Issue 标签
echo "分析 Issue 分类..."
FEATURES=$(echo "$CLOSED_ISSUES" | jq -r '[.[] | select(.issue_tags[]?.name == "feature")] | length')
BUGS=$(echo "$CLOSED_ISSUES" | jq -r '[.[] | select(.issue_tags[]?.name == "bug")] | length')
ENHANCEMENTS=$(echo "$CLOSED_ISSUES" | jq -r '[.[] | select(.issue_tags[]?.name == "enhancement")] | length')

# 6. 计算完成率
COMPLETION_RATE=0
if [ $((CLOSED_COUNT + NEW_COUNT)) -gt 0 ]; then
    COMPLETION_RATE=$((CLOSED_COUNT * 100 / (CLOSED_COUNT + NEW_COUNT)))
fi

# 7. 生成报告
echo "生成 Sprint 报告..."
REPORT_FILE="$REPORT_DIR/sprint_${SPRINT_NUMBER}_$(date +%Y%m%d).md"

cat > "$REPORT_FILE" << EOF
# 📊 Sprint $SPRINT_NUMBER 进度报告

**时间范围**: $SPRINT_START 至 $SPRINT_END
**生成时间**: $(date +%Y-%m-%d)
**报告周期**: 14 天

## 🎯 Sprint 目标达成情况

### 总体概览
| 指标 | 数量 | 说明 |
|------|------|------|
| ✅ 完成 Issue | $CLOSED_COUNT 个 | Sprint 期间关闭的 Issue |
| 🆕 新增 Issue | $NEW_COUNT 个 | Sprint 期间新建的 Issue |
| 🔀 合并 PR | $MERGED_COUNT 个 | Sprint 期间合并的 PR |
| 🆕 新建 PR | $NEW_PR_COUNT 个 | Sprint 期间新建的 PR |
| 💻 代码提交 | $COMMIT_COUNT 次 | Sprint 期间的提交次数 |

### 完成率分析
- **Issue 完成率**: ${COMPLETION_RATE}%
- **PR 合并率**: $((MERGED_COUNT * 100 / (MERGED_COUNT + NEW_PR_COUNT)))%
- **平均日提交**: $((COMMIT_COUNT / 14)) 次/天

## 📊 Issue 分类统计

| 分类 | 数量 | 占比 |
|------|------|------|
| 新功能 | $FEATURES 个 | $((FEATURES * 100 / CLOSED_COUNT))% |
| Bug 修复 | $BUGS 个 | $((BUGS * 100 / CLOSED_COUNT))% |
| 功能改进 | $ENHANCEMENTS 个 | $((ENHANCEMENTS * 100 / CLOSED_COUNT))% |

## 👥 团队贡献统计

$(echo "$CONTRIBUTORS" | jq -r '.[] | |
    "| **\(.developer)** | \(.count) 次提交 | $((.count * 100 / COMMIT_COUNT))% |"')

## 🎉 主要成就

### 完成的 Issue
$(echo "$CLOSED_ISSUES" | jq -r '"- [\(.subject)](#issue/\(.id)) - \(.assigned_to // "未分配")"')

### 合并的 PR
$(echo "$MERGED_PRS" | jq -r '"- [\(.title)](#pr/\(.id)) - \(.author.login)"')

## 🔄 进行中的工作

### 未完成的 Issue
$(echo "$NEW_ISSUES" | jq -r '"- [\(.subject)](#issue/\(.id)) - \(.assigned_to // "未分配")"')

### 待合并的 PR
$(echo "$NEW_PRS" | jq -r '"- [\(.title)](#pr/\(.id)) - \(.author.login)"')

## 📈 趋势分析

### 代码活动趋势
- 本 Sprint 共有 **$COMMIT_COUNT 次提交**，日均 **$((COMMIT_COUNT / 14)) 次**
- 比上 Sprint $([[ $SPRINT_NUMBER -gt 1 ]] && echo "增长了/减少了 XX%" || echo "为基线数据")

### 团队效率分析
- 团队成员积极参与，贡献分布较为均匀
- 代码审查及时，PR 合并率良好

## ⚠️ 风险和问题

### 当前风险
- 高优先级 Issue 积压：$(echo "$NEW_ISSUES" | jq '[.[] | select(.priority_id == 1)] | length') 个
- 长期未解决的 Issue：$(echo "$NEW_ISSUES" | jq '[.[] | select(.created_at < "'$SPRINT_START'")] | length') 个

### 技术债务
- 代码复用待改进
- 测试覆盖率需要提升
- 文档需要更新

## 📋 下期计划

### 主要目标
1. 继续完成当前进行中的 Issue
2. 优化代码质量和测试覆盖
3. 更新项目文档
4. 技术债务清理

### 资源规划
- 开发资源：保持当前团队配置
- 时间规划：重点关注高优先级 Issue
- 技术重点：性能优化和代码重构

## 🙏 致谢

感谢所有团队成员在 Sprint $SPRINT_NUMBER 期间的辛勤工作！

---
**报告生成**: $(date +%Y-%m-%d %H:%M:%S)
**数据来源**: GitLink API
**报告类型**: 自动化 Sprint 报告
EOF

echo "✅ Sprint 报告已生成: $REPORT_FILE"

# 8. 可选：创建 Issue 讨论报告
echo "创建 Sprint 回顾 Issue..."
REVIEW_ISSUE_BODY="## Sprint $SPRINT_NUMBER 回顾

### Sprint 报告
完整的 Sprint 报告请查看: [Sprint $SPRINT_NUMBER 报告](../../blob/master/$REPORT_FILE)

### 讨论要点
1. 目标达成情况分析
2. 团队协作效果评估
3. 流程改进建议
4. 下 Sprint 目标规划

### 问题跟踪
- 需要解决的问题
- 改进建议
- 风险识别"

gitlink-cli issue +create \
  --owner $OWNER \
  --repo $REPO \
  --title "Sprint $SPRINT_NUMBER 回顾" \
  --body "$REVIEW_ISSUE_BODY"

echo "Sprint 报告工作流完成！"
```

## AI Agent 集成示例

Claude Code 等 AI Agent 可以深度集成此工作流：

```python
# AI Agent 生成 Sprint 报告
def generate_sprint_report(owner, repo, sprint_number):
    """AI Agent 自动生成 Sprint 进度报告"""
    
    # 1. 确定 Sprint 时间范围
    sprint_start, sprint_end = calculate_sprint_period(sprint_number)
    
    # 2. 收集数据
    sprint_data = collect_sprint_data(owner, repo, sprint_start, sprint_end)
    
    # 3. AI 分析数据
    analysis = analyze_sprint_performance(sprint_data)
    
    # 4. 生成报告
    report = generate_report_content(sprint_number, sprint_data, analysis)
    
    # 5. 保存报告并创建回顾 Issue
    save_report(report, sprint_number)
    create_review_issue(owner, repo, sprint_number, report)
    
    return report

def collect_sprint_data(owner, repo, start_date, end_date):
    """收集 Sprint 数据"""
    
    return {
        'issues': {
            'closed': get_closed_issues(owner, repo, start_date, end_date),
            'new': get_new_issues(owner, repo, start_date, end_date)
        },
        'pull_requests': {
            'merged': get_merged_prs(owner, repo, start_date, end_date),
            'new': get_new_prs(owner, repo, start_date, end_date)
        },
        'commits': get_commits(owner, repo, start_date, end_date),
        'contributors': get_contributor_stats(owner, repo, start_date, end_date)
    }

def analyze_sprint_performance(data):
    """AI 分析 Sprint 表现"""
    
    analysis = {
        'velocity': calculate_velocity(data),
        'trends': identify_trends(data),
        'risks': identify_risks(data),
        'recommendations': generate_recommendations(data)
    }
    
    # AI 分析完成率趋势
    completion_rate = len(data['issues']['closed']) / (
        len(data['issues']['closed']) + len(data['issues']['new'])
    ) * 100
    
    if completion_rate > 80:
        analysis['performance'] = 'excellent'
    elif completion_rate > 60:
        analysis['performance'] = 'good'
    else:
        analysis['performance'] = 'needs_improvement'
    
    return analysis

def generate_report_content(sprint_number, data, analysis):
    """AI 生成报告内容"""
    
    report = f"""# 📊 Sprint {sprint_number} 进度报告

## 🎯 目标达成情况

### 总体概览
- **完成 Issue**: {len(data['issues']['closed'])} 个
- **新增 Issue**: {len(data['issues']['new'])} 个  
- **合并 PR**: {len(data['pull_requests']['merged'])} 个
- **代码提交**: {len(data['commits'])} 次

### AI 分析结果
- **表现评级**: {analysis['performance']}
- **团队速度**: {analysis['velocity']} story points
- **主要趋势**: {analysis['trends']}

## 🎉 主要成就
"""
    
    # 添加主要成就
    for issue in data['issues']['closed'][:5]:
        report += f"- {issue['subject']} (#{issue['id']})\n"
    
    # 添加风险和建议
    report += "\n## ⚠️ 风险识别\n"
    for risk in analysis['risks']:
        report += f"- {risk}\n"
    
    report += "\n## 💡 改进建议\n"
    for recommendation in analysis['recommendations']:
        report += f"- {recommendation}\n"
    
    return report
```

## 报告模板

### 标准报告结构

```markdown
# Sprint {NUMBER} 进度报告

## 元信息
- **时间范围**: {START_DATE} - {END_DATE}
- **Sprint 周期**: 14 天
- **生成时间**: {TIMESTAMP}

## 目标达成
### 完成情况
- 计划完成: X 个 Issue
- 实际完成: Y 个 Issue  
- 完成率: Z%

## 工作统计
### Issue 统计
- 关闭: N 个
- 新建: M 个
- 分类统计

### PR 统计
- 合并: N 个
- 新建: M 个
- 合并率: X%

### 提交统计
- 总提交: N 次
- 日均: X 次

## 团队贡献
- 成员A: N 次贡献
- 成员B: M 次贡献

## 风险和问题
- 当前风险
- 技术债务
- 阻塞问题

## 下期计划
- 主要目标
- 资源规划
- 时间安排
```

## 数据分析维度

### 1. 速度分析
- Story Points 完成
- Issue 完成数量
- PR 合并数量

### 2. 质量分析
- Bug 修复比例
- 代码审查通过率
- 测试覆盖率变化

### 3. 效率分析
- 平均 Issue 解决时间
- 平均 PR 合并时间
- 代码审查周期

### 4. 团队分析
- 成员贡献分布
- 协作效率
- 沟通成本

## 最佳实践

1. **定期生成**：每个 Sprint 结束后及时生成报告
2. **数据准确**：确保收集的数据完整准确
3. **客观分析**：基于数据进行客观分析
4. **行动导向**：报告应包含可执行的改进建议
5. **团队参与**：让团队成员参与报告讨论

## 质量保证

报告质量检查：

- [ ] 数据完整性检查
- [ ] 计算准确性验证
- [ ] 格式一致性检查
- [ ] 语法和拼写检查
- [ ] 链接有效性验证
- [ ] 客观性审查

## References

- [workflow-issue-triage](workflow-issue-triage.md) — Issue 分类工作流
- [workflow-pr-review](workflow-pr-review.md) — PR 审查工作流
- [gitlink-workflow](../SKILL.md) — 工作流总览
- [gitlink-shared](../../gitlink-shared/SKILL.md) — 认证和全局参数
- [pm-sprint](../../gitlink-pm/references/pm-sprint.md) — Sprint 管理
- [pm-report](../../gitlink-pm/references/pm-report.md) — 周报生成
