# 场景 5：科研进度智能跟踪与预警

## 目标

跟踪科研项目的开发进度，检测异常信号，生成周报和早期预警。

## 参数

| 参数 | 必需 | 说明 |
|------|------|------|
| `--owner` | 是 | 仓库所有者 |
| `--repo` | 是 | 仓库名称 |
| `--org` | 否 | 组织名称（多仓库模式） |
| `--weeks` | 否 | 回溯周数（默认 4） |
| `--output` | 否 | 输出文件路径 |

## 数据收集步骤

### Step 1: Issue 数据
```bash
gitlink-cli issue +list --owner $OWNER --repo $REPO --state open --limit 100 --format json
gitlink-cli issue +list --owner $OWNER --repo $REPO --state closed --limit 100 --format json
```
提取：
- 每个 Issue 的状态、创建时间、更新时间、标签
- 按周统计创建数/关闭数
- 识别停滞 Issue（open + 60天无更新）
- 识别未分配 Issue

### Step 2: PR 数据
```bash
gitlink-cli pr +list --owner $OWNER --repo $REPO --state merged --limit 100 --format json
gitlink-cli pr +list --owner $OWNER --repo $REPO --state open --limit 50 --format json
```
提取：
- 按周统计合并数/新建数
- 开放 PR 的平均年龄
- PR 瓶颈检测：开放 > 5 且平均年龄 > 14 天

### Step 3: Release 数据
```bash
gitlink-cli release +list --owner $OWNER --repo $REPO --limit 20 --format json
```
- 计算发布间隔
- 检测长期无发布（> 180 天）

### Step 4: CI 数据
```bash
gitlink-cli ci +builds --owner $OWNER --repo $REPO --limit 20 --format json
```
- 构建成功率
- 最近失败次数

### Step 5: 多仓库模式（可选）
如果指定 `--org`：
```bash
gitlink-cli repo +list --user $ORG --limit 50 --format json
```
对每个仓库执行 Step 1-4，生成聚合报告。

## 健康评分

```
Health = issue_velocity  * 0.30
       + pr_merge_rate   * 0.25
       + milestone_ok    * 0.25
       + release_cadence * 0.10
       + activity_trend  * 0.10
```

### issue_velocity
```
velocity = issues_closed_28d / 28
score = min(velocity / 1.0, 1.0)  # 目标：日均关闭 1 个 Issue
```

### pr_merge_rate
```
score = merged_prs_90d / max(total_prs_90d, 1)
```

### release_cadence
```
interval = avg_days_between_last_3_releases
score = interval <= 30 ? 1.0 : interval <= 90 ? 0.5 : interval <= 180 ? 0.2 : 0
```

### activity_trend
```
trend = (activity_this_month - activity_last_month) / max(activity_last_month, 1)
score = clamp(trend + 0.5, 0, 1)
```

## 异常检测规则

| 异常类型 | 触发条件 | 严重程度 |
|----------|---------|---------|
| 🔴 Issue 停滞 | open > 60 天，无更新 > 14 天 | Warning |
| 🔴 里程碑逾期 | 超过截止日期，progress < 100% | Critical |
| 🟡 活动骤降 | 月活动量环比下降 > 50% | Warning |
| 🟡 PR 积压 | open PRs > 5, avg_age > 14 天 | Warning |
| 🟠 长期无发布 | 距上次 release > 180 天 | Info |
| 🟠 CI 持续失败 | 最近 5 次构建中 ≥ 3 次失败 | Warning |
| 🟢 无人认领 | 未分配 Issue > 总数 30% | Info |

## 输出

1. **HTML 周报** (`output/progress-weekly-{date}.html`)：
   - 健康评分仪表盘
   - Issue/PR 流速趋势折线图（4 周窗口）
   - 开放 vs 关闭 Issue 堆叠柱状图
   - Release 时间线
   - 异常预警表（严重程度着色）

2. **Wiki Markdown** — 周报摘要 + 异常列表

3. **控制台摘要** — 关键指标一目了然

## 可执行脚本

```bash
# 单仓库
bash workflows/10-research-progress.sh --owner zzx-coder --repo gitlink-cli

# 多仓库（组织）
bash workflows/10-research-progress.sh --org zzx-coder --weeks 4
```

## 风险管理建议

对于检测到的异常，自动生成建议：

| 异常 | 建议 |
|------|------|
| Issue 停滞 | 重新评估优先级，关闭或推进；通知负责人 |
| 里程碑逾期 | 重新规划里程碑时间表；拆分为更小的子任务 |
| 活动骤降 | 检查团队是否有阻塞因素；组织一次同步会议 |
| PR 积压 | 安排 Code Review 时间；简化 PR 粒度 |
| 长期无发布 | 考虑发布当前 master 的最小可用版本 |
| CI 持续失败 | 优先修复 CI；暂时阻止新 PR 合并直到 CI 恢复 |
