# PM 周报生成

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

GitLink PM 周报功能提供项目一周工作情况的自动汇总，包括 Issue、Pull Request、提交记录等数据。

## 命令

```bash
# 查看周报数据
gitlink-cli api GET /pm/weekly_issues --query 'project_id=123'

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

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

# 查看特定日期范围的周报
gitlink-cli api GET /pm/weekly_issues --query 'project_id=123&start_date=2026-01-01&end_date=2026-01-07'

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

## 参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `project_id` | **是** | 项目 ID（通过 `repo +info` 获取） |
| `start_date` | 否 | 开始日期（格式：YYYY-MM-DD） |
| `end_date` | 否 | 结束日期（格式：YYYY-MM-DD） |
| `--owner` | 否* | 仓库所有者（自动从 git remote 解析） |
| `--repo` | 否* | 仓库名称（自动从 git remote 解析） |
| `--format` | 否 | 输出格式: `json`/`table`/`yaml` |
| `--debug` | 否 | 启用调试输出 |

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

## API

```
GET /api/pm/weekly_issues?project_id={project_id}&start_date={start_date}&end_date={end_date}
```

**响应示例：**

```json
{
  "ok": true,
  "data": {
    "period": {
      "start_date": "2026-01-01",
      "end_date": "2026-01-07",
      "week_number": 1
    },
    "summary": {
      "total_issues": 15,
      "new_issues": 8,
      "closed_issues": 5,
      "in_progress_issues": 2,
      "total_prs": 6,
      "merged_prs": 4,
      "total_commits": 42
    },
    "issues": [
      {
        "id": 456,
        "subject": "实现用户认证功能",
        "status": "closed",
        "author": "developer1",
        "assigned_to": "developer2",
        "created_at": "2026-01-02T10:00:00Z",
        "closed_at": "2026-01-05T15:30:00Z",
        "labels": ["feature", "authentication"]
      }
    ],
    "pull_requests": [
      {
        "id": 123,
        "title": "Feature: User authentication",
        "status": "merged",
        "author": "developer1",
        "merged_at": "2026-01-05T16:00:00Z",
        "additions": 245,
        "deletions": 18
      }
    ],
    "commits": [
      {
        "id": "abc123",
        "message": "Implement user login",
        "author": "developer1",
        "committed_date": "2026-01-03T14:20:00Z"
      }
    ],
    "team_contributions": [
      {
        "developer": "developer1",
        "issues_created": 3,
        "issues_closed": 2,
        "prs_created": 2,
        "prs_merged": 2,
        "commits_count": 15
      }
    ]
  }
}
```

## Workflow

1. **Get Project ID** using `repo +info`.
2. **Execute** `gitlink-cli api GET /pm/weekly_issues --query 'project_id=<id>'`.
3. **Display** weekly report data.

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

## Use Cases

- **工作汇报**：自动生成周工作总结
- **进度跟踪**：监控项目一周的进展情况
- **团队管理**：了解团队成员的工作贡献
- **数据分析**：分析项目发展趋势和效率

## Weekly Report Structure

典型周报结构：

```
周报（2026-01-01 至 2026-01-07）

## 概览统计
- 新增 Issue：8 个
- 关闭 Issue：5 个
- 进行中 Issue：2 个
- 合并 PR：4 个
- 代码提交：42 次

## 详细内容
### Issue 活动
- 新建：8 个 Issue
- 完成：5 个 Issue
- 持续工作：2 个 Issue

### Pull Request 活动
- 创建：6 个 PR
- 合并：4 个 PR

### 团队贡献
- developer1：15 次提交，2 个合并 PR
- developer2：12 次提交，1 个合并 PR
```

## Common Operations

周报常用操作：

### 生成简明周报
```bash
# 生成简明周报摘要
gitlink-cli api GET /pm/weekly_issues --query 'project_id=123' --format json | \
  jq '# 周报摘要
     "\n## 项目周报 (\(.data.period.start_date) 至 \(.data.period.end_date))",
     "\n### 统计概览",
     "- 新增 Issue: \(.data.summary.new_issues) 个",
     "- 完成 Issue: \(.data.summary.closed_issues) 个",
     "- 合并 PR: \(.data.summary.merged_prs) 个",
     "- 代码提交: \(.data.summary.total_commits) 次"'
```

### 分析团队贡献
```bash
# 按贡献度排序团队成员
gitlink-cli api GET /pm/weekly_issues --query 'project_id=123' --format json | \
  jq '.data.team_contributions | sort_by(.commits_count) | reverse |
      .[] | "\(.developer): \(.commits_count) 次提交, \(.prs_merged) 个合并 PR"'
```

### 查看活动趋势
```bash
# 按日期统计活动
gitlink-cli api GET /pm/weekly_issues --query 'project_id=123' --format json | \
  jq '[.data.commits[] | .committed_date | split("T")[0]] |
     group_by(.) |
     map({date: .[0], count: length}) |
     sort_by(.date)'
```

## Report Metrics

周报关键指标：

| 指标 | 说明 | 用途 |
|------|------|------|
| **新增 Issue 数** | 一周内新建的 Issue 数量 | 反映新需求产生速度 |
| **关闭 Issue 数** | 一周内关闭的 Issue 数量 | 反映问题解决速度 |
| **合并 PR 数** | 一周内合并的 PR 数量 | 反映代码集成速度 |
| **提交次数** | 一周内的代码提交次数 | 反映开发活跃度 |
| **参与人数** | 有贡献活动的团队成员数 | 反映团队参与度 |

## Analysis Examples

周报数据分析示例：

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

# 2. 查看完整周报
gitlink-cli api GET /pm/weekly_issues --query "project_id=$PROJECT_ID" --format json

# 3. 生成团队贡献排名
gitlink-cli api GET /pm/weekly_issues --query "project_id=$PROJECT_ID" --format json | \
  jq '.data.team_contributions | sort_by(.commits_count) | reverse |

# 4. 计算完成率
gitlink-cli api GET /pm/weekly_issues --query "project_id=$PROJECT_ID" --format json | \
  jq '(.data.summary.closed_issues / .data.summary.new_issues * 100) |
      "本周完成率: \(.)%"'

# 5. 分析代码变更量
gitlink-cli api GET /pm/weekly_issues --query "project_id=$PROJECT_ID" --format json | \
  jq '{additions: [.data.pull_requests[].additions] | add,
       deletions: [.data.pull_requests[].deletions] | add,
       net_change: ([.data.pull_requests[].additions] | add) - ([.data.pull_requests[].deletions] | add)}'
```

## Custom Report Generation

自定义报告生成：

```bash
# 生成 Markdown 格式的周报
generate_weekly_report() {
    PROJECT_ID=$(gitlink-cli repo +info --format json | jq -r '.data.project_id')
    END_DATE=$(date +%Y-%m-%d)
    START_DATE=$(date -d "7 days ago" +%Y-%m-%d)
    
    echo "# 项目周报 ($START_DATE 至 $END_DATE)"
    echo ""
    
    gitlink-cli api GET /pm/weekly_issues \
        --query "project_id=$PROJECT_ID&start_date=$START_DATE&end_date=$END_DATE" \
        --format json | \
        jq -r '
            "## 概览统计",
            "- 新增 Issue: \(.data.summary.new_issues) 个",
            "- 完成 Issue: \(.data.summary.closed_issues) 个", 
            "- 合并 PR: \(.data.summary.merged_prs) 个",
            "- 代码提交: \(.data.summary.total_commits) 次",
            "",
            "## 团队贡献",
            (.data.team_contributions | sort_by(.commits_count) | reverse |
             .[] | "- **\(.developer)**: \(.commits_count) 次提交, \(.prs_merged) 个合并 PR"),
            "",
            "## 主要完成",
            (.data.issues[] | select(.status == "closed") |
             "- [\(.subject)](#issue/\(.id)) - \(.assigned_to)"),
            "",
            "## 代码合并",
            (.data.pull_requests[] | select(.status == "merged") |
             "- [\(.title)](#pr/\(.id)) - \(.author) (+\(.additions) -\(.deletions))")
        '
}
```

## Tips

- 周报数据可以帮助团队了解工作进展
- 定期生成周报可以保持项目进度的可视化
- 结合其他 PM 数据可以实现完整的项目管理
- 使用 JSON 格式输出便于自动化报告生成

## Integration with Other Features

与其他功能集成：

```bash
# 周报 + 详细操作
# 1. 生成周报概览
gitlink-cli api GET /pm/weekly_issues --query 'project_id=123' --format json

# 2. 查看特定 Issue 详情
gitlink-cli issue +view --issue 456

# 3. 查看特定 PR 详情  
gitlink-cli pr +view --pr 123
```

## Best Practices

周报生成最佳实践：

1. **定期生成**：每周固定时间生成周报
2. **数据验证**：生成后验证数据的准确性
3. **格式统一**：使用统一的报告格式
4. **趋势分析**：比较不同周报的数据趋势
5. **团队分享**：及时分享周报给团队成员

## Advanced Usage

高级用法示例：

```bash
# 比较两周的数据
compare_weeks() {
    PROJECT_ID=$(gitlink-cli repo +info --format json | jq -r '.data.project_id')
    
    # 本周数据
    THIS_WEEK=$(gitlink-cli api GET /pm/weekly_issues --query "project_id=$PROJECT_ID" --format json)
    
    # 上周数据（计算日期）
    LAST_START=$(date -d "14 days ago" +%Y-%m-%d)
    LAST_END=$(date -d "8 days ago" +%Y-%m-%d)
    LAST_WEEK=$(gitlink-cli api GET /pm/weekly_issues \
        --query "project_id=$PROJECT_ID&start_date=$LAST_START&end_date=$LAST_END" --format json)
    
    # 比较输出
    echo "## 周环比分析"
    echo "新增 Issue: $THIS_WEEK ↓ $LAST_WEEK"
    echo "完成 Issue: $THIS_WEEK ↓ $LAST_WEEK"
}

# 导出为文件
export_weekly_report() {
    PROJECT_ID=$(gitlink-cli repo +info --format json | jq -r '.data.project_id')
    DATE=$(date +%Y-%m-%d)
    
    gitlink-cli api GET /pm/weekly_issues --query "project_id=$PROJECT_ID" --format json | \
        jq '.' > "weekly_report_$DATE.json"
}
```

## Team Collaboration

团队协作建议：

1. **定期分享**：每周固定时间分享周报
2. **数据透明**：保持团队对项目进度的了解
3. **问题讨论**：基于周报数据讨论问题和改进
4. **成果认可**：认可和庆祝团队成就
5. **持续改进**：基于周报分析优化工作流程

## Error Handling

常见错误及解决方案：

| 错误 | 原因 | 解决方案 |
|------|------|----------|
| `400` | PM 模块未开启 | 联系项目管理员开启 PM 模块 |
| `404` | 项目不存在 | 检查 project_id 是否正确 |
| `400` | 日期格式错误 | 确保日期格式为 YYYY-MM-DD |
| `403` | 权限不足 | 确认有查看该项目的权限 |
| `404` | 数据不存在 | 指定日期范围内可能没有活动数据 |

## Report Templates

报告模板示例：

```markdown
# 项目周报（第{{week_number}}周）

**时间范围**：{{start_date}} 至 {{end_date}}

## 📊 核心指标
- ✅ 完成 Issue：{{closed_issues}} 个
- 🆕 新增 Issue：{{new_issues}} 个  
- 🔀 合并 PR：{{merged_prs}} 个
- 💻 代码提交：{{total_commits}} 次

## 👥 团队贡献
{{#each team_contributions}}
### {{developer}}
- 提交：{{commits_count}} 次
- 合并 PR：{{prs_merged}} 个
- 完成 Issue：{{issues_closed}} 个
{{/each}}

## 🎯 主要成果
{{#each closed_issues}}
- {{subject}} ({{assigned_to}})
{{/each}}

## 🔄 进行中工作
{{#each in_progress_issues}}
- {{subject}} ({{assigned_to}})
{{/each}}
```

## References

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