# PM Sprint 管理

> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
> **注意**：PM 功能需要项目开启 PM 模块，并通过项目 ID 访问。

GitLink PM Sprint 功能支持敏捷开发的迭代管理，帮助团队组织和管理特定时间段内的开发任务。

## 命令

```bash
# 查看 Sprint Issue 列表
gitlink-cli api GET /pm/sprint_issues --query 'project_id=123'

# 查看当前仓库的项目 ID
gitlink-cli repo +info --format json | jq '.data.project_id'

# 组合命令：自动获取项目 ID 并查看 Sprint
PROJECT_ID=$(gitlink-cli repo +info --format json | jq -r '.data.project_id')
gitlink-cli api GET /pm/sprint_issues --query "project_id=$PROJECT_ID"

# 查看特定 Sprint 的信息
gitlink-cli api GET /pm/sprint_issues --query 'project_id=123&sprint_id=1'

# 查看 Issue 标签
gitlink-cli api GET /pm/issue_tags --query 'project_id=123'
```

## 参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `project_id` | **是** | 项目 ID（通过 `repo +info` 获取） |
| `sprint_id` | 否 | Sprint ID（可选，用于查看特定 Sprint） |
| `--owner` | 否* | 仓库所有者（自动从 git remote 解析） |
| `--repo` | 否* | 仓库名称（自动从 git remote 解析） |
| `--format` | 否 | 输出格式: `json`/`table`/`yaml` |
| `--debug` | 否 | 启用调试输出 |

> *如果在 GitLink 仓库目录下执行，`--owner` 和 `--repo` 可自动推断。

## API

```
GET /api/pm/sprint_issues?project_id={project_id}&sprint_id={sprint_id}
```

**响应示例：**

```json
{
  "ok": true,
  "data": {
    "sprint_issues": [
      {
        "id": 789,
        "subject": "完成用户管理模块",
        "sprint_id": 1,
        "sprint_name": "Sprint 1 - 基础功能",
        "status": "open",
        "priority": "high",
        "assigned_to": "developer1",
        "estimated_hours": 40,
        "spent_hours": 28,
        "completion_percentage": 70,
        "start_date": "2026-01-01",
        "end_date": "2026-01-14",
        "tags": ["backend", "user-management"]
      },
      {
        "id": 790,
        "subject": "实现权限控制",
        "sprint_id": 1,
        "sprint_name": "Sprint 1 - 基础功能",
        "status": "in_progress",
        "priority": "high",
        "assigned_to": "developer2",
        "estimated_hours": 32,
        "spent_hours": 15,
        "completion_percentage": 47,
        "start_date": "2026-01-01",
        "end_date": "2026-01-14",
        "tags": ["backend", "security"]
      }
    ],
    "total_count": 12
  }
}
```

## Workflow

1. **Get Project ID** using `repo +info`.
2. **Execute** `gitlink-cli api GET /pm/sprint_issues --query 'project_id=<id>'`.
3. **Display** sprint issues and progress.

> [!NOTE]
> This is a **Read Operation** — no confirmation needed.

## Use Cases

- **Sprint 规划**：查看和规划 Sprint 中的任务
- **进度跟踪**：监控 Sprint 的执行进度
- **资源分配**：合理分配团队成员到 Sprint 任务
- **性能分析**：分析团队的开发速度和效率

## Sprint Lifecycle

典型的 Sprint 生命周期：

```
1. Sprint 规划
   ├── 确定 Sprint 目标
   ├── 选择要处理的 Issue
   └── 估算工作量

2. Sprint 执行
   ├── 开发团队实现功能
   ├── 每日站会同步进度
   └── 处理阻塞问题

3. Sprint 评审
   ├── 演示完成的功能
   ├── 收集反馈意见
   └── 确定验收结果

4. Sprint 回顾
   ├── 总结经验教训
   ├── 优化工作流程
   └── 制定改进计划
```

## Common Operations

Sprint 常用操作：

### 查看 Sprint 概览
```bash
# 查看 Sprint 统计信息
gitlink-cli api GET /pm/sprint_issues --query 'project_id=123' --format json | \
  jq '{total: .data.total_count,
       high_priority: [.data.sprint_issues[] | select(.priority=="high")] | length,
       completed: [.data.sprint_issues[] | select(.status=="closed")] | length}'
```

### 查看 Sprint 进度
```bash
# 计算 Sprint 完成百分比
gitlink-cli api GET /pm/sprint_issues --query 'project_id=123' --format json | \
  jq '[.data.sprint_issues[].completion_percentage] | add / length'
```

### 分析工作负载
```bash
# 按人员统计工作负载
gitlink-cli api GET /pm/sprint_issues --query 'project_id=123' --format json | \
  jq '[.data.sprint_issues[] | {assigned_to: .assigned_to, estimated: .estimated_hours}] |
     group_by(.assigned_to) |
     map({developer: .[0].assigned_to, total_hours: (map(.estimated) | add)})'
```

## Sprint Metrics

Sprint 关键指标：

| 指标 | 说明 | 计算方式 |
|------|------|----------|
| **Sprint 速度** | 团队在一个 Sprint 中完成的工作量 | 完成的 Issue 数 × 复杂度权重 |
| **完成率** | Sprint 中已完成任务的百分比 | 已完成数 / 总数 × 100% |
| **剩余工作量** | Sprint 中未完成的工作量 | 未完成任务的估算小时数 |
| **工作负载** | 团队成员的工作分布 | 每人分配的估算小时数 |
| **延期风险** | 可能无法按时完成的任务 | 接近截止日期但未完成的任务 |

## Analysis Examples

Sprint 数据分析示例：

```bash
# 1. 获取项目 ID
PROJECT_ID=$(gitlink-cli repo +info --format json | jq -r '.data.project_id')

# 2. 查看 Sprint 概览
gitlink-cli api GET /pm/sprint_issues --query "project_id=$PROJECT_ID" --format json

# 3. 分析高优先级任务
gitlink-cli api GET /pm/sprint_issues --query "project_id=$PROJECT_ID" --format json | \
  jq '.data.sprint_issues[] | select(.priority=="high") | {subject, status, completion_percentage}'

# 4. 识别延期风险
gitlink-cli api GET /pm/sprint_issues --query "project_id=$PROJECT_ID" --format json | \
  jq '.data.sprint_issues[] |
      select(.status != "closed" and .end_date < (now | todate)) |
      {subject, end_date, completion_percentage}'

# 5. 计算团队效率
gitlink-cli api GET /pm/sprint_issues --query "project_id=$PROJECT_ID" --format json | \
  jq '{total_estimated: [.data.sprint_issues[].estimated_hours] | add,
       total_spent: [.data.sprint_issues[].spent_hours] | add,
       efficiency: ([.data.sprint_issues[].spent_hours] | add) /
                   ([.data.sprint_issues[].estimated_hours] | add) * 100}'
```

## Sprint Planning

Sprint 规划建议：

1. **合理估算**：基于历史数据估算工作量
2. **优先级排序**：优先处理高价值和高优先级任务
3. **负载均衡**：合理分配任务给团队成员
4. **预留缓冲**：为不可预见的问题预留时间

## Tips

- Sprint 数据可以帮助团队了解开发进度
- 定期查看 Sprint 统计可以及时发现问题
- 结合 Issue 操作可以实现完整的任务管理
- 使用 JSON 格式输出便于自动化分析

## Integration with Other Features

与其他功能集成：

```bash
# Sprint + Issue 操作
# 1. 查看 Sprint 中的任务
gitlink-cli api GET /pm/sprint_issues --query 'project_id=123' --format json

# 2. 查看特定任务详情
gitlink-cli issue +view --issue 789

# 3. 更新任务状态
gitlink-cli issue +update --issue 789 --status_id 3 --done_ratio 80
```

## Best Practices

Sprint 管理最佳实践：

1. **时间盒固定**：Sprint 时长通常为 2-4 周
2. **目标明确**：每个 Sprint 应有明确的目标
3. **任务可衡量**：Sprint 任务应该是可衡量和可完成的
4. **定期回顾**：每个 Sprint 结束后进行回顾总结
5. **持续改进**：基于回顾结果优化工作流程

## Error Handling

常见错误及解决方案：

| 错误 | 原因 | 解决方案 |
|------|------|----------|
| `400` | PM 模块未开启 | 联系项目管理员开启 PM 模块 |
| `404` | 项目不存在 | 检查 project_id 是否正确 |
| `404` | Sprint 不存在 | 检查 sprint_id 是否正确 |
| `403` | 权限不足 | 确认有查看该项目的权限 |

## Advanced Usage

高级用法示例：

```bash
# 生成 Sprint 报告
generate_sprint_report() {
    PROJECT_ID=$(gitlink-cli repo +info --format json | jq -r '.data.project_id')
    
    echo "# Sprint Report"
    echo "## Overview"
    gitlink-cli api GET /pm/sprint_issues --query "project_id=$PROJECT_ID" --format json | \
        jq -r '"Total: \(.data.total_count) issues"'
    
    echo "## Priority Distribution"
    gitlink-cli api GET /pm/sprint_issues --query "project_id=$PROJECT_ID" --format json | \
        jq '.data.sprint_issues | group_by(.priority) | map({priority: .[0].priority, count: length})'
    
    echo "## Team Workload"
    gitlink-cli api GET /pm/sprint_issues --query "project_id=$PROJECT_ID" --format json | \
        jq '[.data.sprint_issues[] | {assigned_to: .assigned_to, hours: .estimated_hours}] |
           group_by(.assigned_to) |
           map({developer: .[0].assigned_to, total_hours: (map(.hours) | add)})'
}
```

## Team Collaboration

团队协作建议：

1. **Sprint 规划会议**：全团队参与 Sprint 规划
2. **每日站会**：简短同步进度和问题
3. **Sprint 评审**：演示和验收完成的功能
4. **Sprint 回顾**：总结经验，持续改进

## References

- [pm-kanban](pm-kanban.md) — 看板管理
- [pm-report](pm-report.md) — 周报生成
- [gitlink-pm](../SKILL.md) — 项目管理总览
- [gitlink-shared](../../gitlink-shared/SKILL.md) — 认证和全局参数
- [repo +info](../../gitlink-repo/references/repo-info.md) — 获取仓库信息
