proj-dash-backend/GITHUB_API_FEASIBILITY.md

# GitHub Dashboard API 可行性分析报告

## 📊 功能模块 vs GitHub API 支持情况

---

## 1. 仓库概览卡片区

### ✅ 完全支持

| 功能                     | API 端点                              | 返回数据                                            |
| ------------------------ | ------------------------------------- | --------------------------------------------------- |
| **基本信息**             | `GET /repos/{owner}/{repo}`           | 仓库名、描述、创建时间                              |
| **Star/Fork/Watch 数量** | `GET /repos/{owner}/{repo}`           | `stargazers_count`, `forks_count`, `watchers_count` |
| **语言分布**             | `GET /repos/{owner}/{repo}/languages` | `{ "JavaScript": 12345, "Python": 6789 }`           |
| **License**              | `GET /repos/{owner}/{repo}`           | `license.name`, `license.key`                       |
| **Topics**               | `GET /repos/{owner}/{repo}/topics`    | 标签数组                                            |
| **最后更新时间**         | `GET /repos/{owner}/{repo}`           | `updated_at`, `pushed_at`                           |
| **仓库大小**             | `GET /repos/{owner}/{repo}`           | `size` (KB)                                         |
| **开源评分**             | -                                     | ❌ **不支持**，需自行计算                           |

**实现建议：**

- 开源评分可通过组合多个指标计算（Star 数量、贡献者数量、更新频率、文档完整性等）

---

## 2. 活动时间线 (Activity Timeline)

### ⚠️ 部分支持（有限制）

| 功能                    | API 端点                                          | 数据可用性 | 限制                          |
| ----------------------- | ------------------------------------------------- | ---------- | ----------------------------- |
| **最近 commits**        | `GET /repos/{owner}/{repo}/commits`               | ✅ 支持    | 分页限制，最多 100/页         |
| **最近 PRs**            | `GET /repos/{owner}/{repo}/pulls`                 | ✅ 支持    | 可过滤状态（open/closed/all） |
| **最近 Issues**         | `GET /repos/{owner}/{repo}/issues`                | ✅ 支持    | Issues 和 PRs 混合返回        |
| **每日/每周提交热力图** | `GET /repos/{owner}/{repo}/stats/commit_activity` | ✅ 支持    | **仅最近 52 周**              |
| **贡献者活跃度趋势**    | `GET /repos/{owner}/{repo}/stats/contributors`    | ✅ 支持    | **<10k commits 仓库**         |

**API 示例：**

```bash
# 提交活动（按周统计）
GET /repos/{owner}/{repo}/stats/commit_activity
# 返回：[{ "days": [0,3,5,2,1,0,0], "total": 11, "week": 1302508800 }]

# 贡献者统计
GET /repos/{owner}/{repo}/stats/contributors
# 返回：[{ "author": {...}, "total": 135, "weeks": [...] }]
```

**⚠️ 重要限制：**

- 统计数据需要缓存，首次请求返回 `202 Accepted`，需要等待后台计算
- 超过 10,000 commits 的仓库**无法获取详细统计**

---

## 3. 代码统计面板

### ⚠️ 有限支持

| 功能                     | API 端点                                                     | 数据可用性    | 限制                           |
| ------------------------ | ------------------------------------------------------------ | ------------- | ------------------------------ |
| **语言分布饼图**         | `GET /repos/{owner}/{repo}/languages`                        | ✅ 支持       | 返回字节数，非百分比           |
| **代码量趋势**           | `GET /repos/{owner}/{repo}/stats/code_frequency`             | ⚠️ 有限       | **仅周级别统计，<10k commits** |
| **文件结构**             | `GET /repos/{owner}/{repo}/git/trees/{tree_sha}?recursive=1` | ✅ 支持       | 需遍历 tree SHA                |
| **热点文件（最常修改）** | -                                                            | ❌ **不支持** | 需自行分析 commits             |

**代码频率 API：**

```bash
GET /repos/{owner}/{repo}/stats/code_frequency
# 返回：[[1302508800, 1124, -435], ...]  # [周时间戳, 新增行, 删除行]
```

**实现建议：**

- 热点文件需要自己爬取所有 commits，分析每个文件的修改频次
- 文件结构可以通过 Git Trees API 递归获取

---

## 4. Issue/PR 管理看板

### ✅ 完全支持

| 功能             | API 端点                                                   | 返回数据                  |
| ---------------- | ---------------------------------------------------------- | ------------------------- |
| **状态分布**     | `GET /repos/{owner}/{repo}/issues?state=all`               | Open/Closed 数量          |
| **优先级标签云** | `GET /repos/{owner}/{repo}/labels`                         | 所有标签及颜色            |
| **响应时间**     | `GET /repos/{owner}/{repo}/issues`                         | `created_at`, `closed_at` |
| **Issue 时间线** | `GET /repos/{owner}/{repo}/issues/{issue_number}/timeline` | 完整事件历史              |
| **PR 审查状态**  | `GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews`    | 审查状态和评论            |

**API 示例：**

```bash
# 获取所有 Issues（包含 PRs）
GET /repos/{owner}/{repo}/issues?state=all&per_page=100

# 区分 Issue 和 PR
if (issue.pull_request) { /* 这是 PR */ }

# 获取 Issue 时间线
GET /repos/{owner}/{repo}/issues/1/timeline
# 返回：创建、关闭、标签变更、评论等事件
```

**计算响应时间：**

- 平均关闭时间 = `closed_at - created_at` 的平均值
- 首次响应时间 = 第一条评论时间 - 创建时间

---

## 5. 贡献者分析

### ⚠️ 部分支持（有性能限制）

| 功能                | API 端点                                       | 数据可用性    | 限制                         |
| ------------------- | ---------------------------------------------- | ------------- | ---------------------------- |
| **核心贡献者榜单**  | `GET /repos/{owner}/{repo}/contributors`       | ✅ 支持       | 按提交数排序                 |
| **贡献者头像墙**    | `GET /repos/{owner}/{repo}/contributors`       | ✅ 支持       | 包含 `avatar_url`            |
| **提交量/增删行数** | `GET /repos/{owner}/{repo}/stats/contributors` | ⚠️ 有限       | **<10k commits**             |
| **新老贡献者比例**  | `GET /repos/{owner}/{repo}/stats/contributors` | ⚠️ 有限       | 需自行分析                   |
| **协作网络图**      | -                                              | ❌ **不支持** | 需分析 commits 的 co-authors |

**Contributors API：**

```bash
# 获取贡献者列表
GET /repos/{owner}/{repo}/contributors
# 返回：[{ "login": "user", "contributions": 123, "avatar_url": "..." }]

# 获取详细统计（需等待缓存）
GET /repos/{owner}/{repo}/stats/contributors
# 返回：[{ "author": {...}, "total": 135, "weeks": [{ "w": 1302508800, "a": 6898, "d": 77, "c": 10 }] }]
```

**⚠️ 限制：**

- GraphQL API **不支持**获取贡献者，必须用 REST API
- 协作网络图需要自己分析 Git 的 `Co-authored-by` 标记

---

## 6. Release & 版本管理

### ✅ 完全支持

| 功能             | API 端点                                             | 返回数据                       |
| ---------------- | ---------------------------------------------------- | ------------------------------ |
| **版本时间轴**   | `GET /repos/{owner}/{repo}/releases`                 | 所有 releases                  |
| **最新 Release** | `GET /repos/{owner}/{repo}/releases/latest`          | 最新版本信息                   |
| **按标签获取**   | `GET /repos/{owner}/{repo}/releases/tags/{tag}`      | 指定版本                       |
| **更新日志**     | `POST /repos/{owner}/{repo}/releases/generate-notes` | 自动生成 Changelog             |
| **下载统计**     | `GET /repos/{owner}/{repo}/releases/{id}`            | 每个 asset 的 `download_count` |

**Release API 示例：**

```bash
# 获取所有 releases
GET /repos/{owner}/{repo}/releases
# 返回：[{ "tag_name": "v1.0.0", "name": "Release 1.0", "assets": [...] }]

# 每个 asset 包含下载统计
{
  "name": "app.zip",
  "download_count": 12345,
  "size": 9876543,
  "created_at": "2023-01-01T12:00:00Z"
}

# 自动生成 Changelog
POST /repos/{owner}/{repo}/releases/generate-notes
{
  "tag_name": "v1.0.0",
  "previous_tag_name": "v0.9.0"
}
```

---

## 7. 依赖关系可视化

### ⚠️ 仅 GraphQL 支持

| 功能         | API 端点                           | 数据可用性    | 限制                |
| ------------ | ---------------------------------- | ------------- | ------------------- |
| **依赖树**   | GraphQL `dependencyGraphManifests` | ⚠️ 仅 GraphQL | REST API **不支持** |
| **安全漏洞** | GraphQL `vulnerabilityAlerts`      | ⚠️ 仅 GraphQL | 需启用 Dependabot   |
| **更新提醒** | GraphQL `dependabot`               | ⚠️ 仅 GraphQL | -                   |

**GraphQL 查询示例：**

```graphql
query {
  repository(owner: "facebook", name: "react") {
    dependencyGraphManifests {
      edges {
        node {
          filename
          dependencies {
            edges {
              node {
                packageName
                requirements
                hasDependencies
              }
            }
          }
        }
      }
    }
    vulnerabilityAlerts(first: 10) {
      edges {
        node {
          securityVulnerability {
            package {
              name
            }
            severity
            advisory {
              summary
            }
          }
        }
      }
    }
  }
}
```

**⚠️ 限制：**

- **必须使用 GraphQL API**，REST API 无此功能
- 需要仓库启用 Dependency Graph 和 Dependabot
- 私有仓库需要 `repo` 权限

---

## 8. CI/CD 状态监控

### ✅ 完全支持

| 功能                 | API 端点                                                  | 返回数据             |
| -------------------- | --------------------------------------------------------- | -------------------- |
| **工作流列表**       | `GET /repos/{owner}/{repo}/actions/workflows`             | 所有 workflows       |
| **工作流运行状态**   | `GET /repos/{owner}/{repo}/actions/runs`                  | 运行历史             |
| **特定工作流的运行** | `GET /repos/{owner}/{repo}/actions/workflows/{id}/runs`   | 特定 workflow 的运行 |
| **运行详情**         | `GET /repos/{owner}/{repo}/actions/runs/{run_id}`         | 状态、结论、时长     |
| **任务详情**         | `GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs`    | 每个 job 的状态      |
| **使用统计**         | `GET /repos/{owner}/{repo}/actions/workflows/{id}/timing` | ⚠️ 已废弃            |

**GitHub Actions API：**

```bash
# 获取工作流运行历史
GET /repos/{owner}/{repo}/actions/runs
# 返回：{
#   "workflow_runs": [{
#     "id": 123,
#     "status": "completed",
#     "conclusion": "success",
#     "run_started_at": "2023-01-01T10:00:00Z",
#     "updated_at": "2023-01-01T10:05:30Z"
#   }]
# }

# 计算运行时长
duration = updated_at - run_started_at
```

**构建成功率计算：**

```javascript
const runs = await fetch('/repos/owner/repo/actions/runs')
const successRate = runs.filter((r) => r.conclusion === 'success').length / runs.length
const avgDuration =
  runs.reduce((sum, r) => sum + (r.updated_at - r.run_started_at), 0) / runs.length
```

---

## 9. 流量统计 (Traffic)

### ⚠️ 有严重限制

| 功能              | API 端点                                              | 数据可用性    | 限制         |
| ----------------- | ----------------------------------------------------- | ------------- | ------------ |
| **页面访问量**    | `GET /repos/{owner}/{repo}/traffic/views`             | ⚠️ 有限       | **仅 14 天** |
| **Clone 统计**    | `GET /repos/{owner}/{repo}/traffic/clones`            | ⚠️ 有限       | **仅 14 天** |
| **Top Referrers** | `GET /repos/{owner}/{repo}/traffic/popular/referrers` | ⚠️ 有限       | **仅 14 天** |
| **Top Paths**     | `GET /repos/{owner}/{repo}/traffic/popular/paths`     | ⚠️ 有限       | **仅 14 天** |
| **历史流量**      | -                                                     | ❌ **不支持** | -            |

**❗ 严重限制：**

- GitHub **仅保留 14 天**的流量数据
- 无法获取历史流量统计
- **必须定期轮询并自行存储**才能构建历史趋势图

**解决方案：**

1. 使用 GitHub Actions 每天自动抓取数据存入数据库
2. 参考开源项目：[github-repo-stats](https://github.com/marketplace/actions/github-repo-stats)

---

## 10. Star 历史趋势

### ⚠️ 有分页限制

| 功能                | API 端点                                               | 数据可用性 | 限制           |
| ------------------- | ------------------------------------------------------ | ---------- | -------------- |
| **Stargazers 列表** | `GET /repos/{owner}/{repo}/stargazers`                 | ✅ 支持    | 最多 40k stars |
| **Star 时间戳**     | 使用 header `Accept: application/vnd.github.star+json` | ✅ 支持    | 最多 40k stars |

**获取 Star 时间戳：**

```bash
curl -H "Accept: application/vnd.github.star+json" \
  https://api.github.com/repos/facebook/react/stargazers?per_page=100&page=1

# 返回：[{ "starred_at": "2023-01-01T12:00:00Z", "user": {...} }]
```

**⚠️ 限制：**

- 每页最多 100 个，最多 400 页 = **40,000 stars**
- 超过 40k stars 的仓库**无法获取完整历史**

---

## 📋 API 限制总结

### Rate Limits（速率限制）

| 认证方式        | 速率限制       |
| --------------- | -------------- |
| **未认证**      | 60 次/小时     |
| **OAuth Token** | 5,000 次/小时  |
| **GitHub App**  | 15,000 次/小时 |

### 数据限制

| 数据类型                | 限制                        |
| ----------------------- | --------------------------- |
| **统计数据（stats）**   | 仅 <10,000 commits 的仓库   |
| **流量数据（traffic）** | 仅 14 天                    |
| **Star 历史**           | 最多 40,000 个              |
| **分页**                | 每页最多 100 条             |
| **Contributors**        | GraphQL 不支持，必须用 REST |

---

## ✅ 推荐实现方案

### 核心功能（完全支持）

1. ✅ 仓库概览卡片
2. ✅ Issue/PR 管理看板
3. ✅ Release 版本管理
4. ✅ CI/CD 状态监控

### 需要定期采集数据

5. ⚠️ 流量统计（每天爬取一次，存入数据库）
6. ⚠️ Star 历史（定期更新）

### 需要混合使用 REST + GraphQL

7. ⚠️ 依赖关系可视化（GraphQL）
8. ⚠️ 安全漏洞（GraphQL）

### 需要自行计算/分析

9. 📊 开源评分（组合多个指标）
10. 📊 热点文件分析（分析 commits）
11. 📊 协作网络图（分析 co-authors）

---

## 🚀 技术栈建议

### 后端

- **REST API**: 使用 Octokit (`@octokit/rest`)
- **GraphQL**: 使用 `@octokit/graphql`
- **定时任务**: GitHub Actions + Cron
- **缓存**: Redis（缓存 stats 数据，避免 202 响应）

### 前端

- **图表库**: Recharts / D3.js / Apache ECharts
- **热力图**: `react-calendar-heatmap`
- **网络图**: `react-force-graph` / `cytoscape.js`
- **时间线**: `react-vertical-timeline`

---

## 📌 注意事项

1. **统计数据可能需要等待**：首次请求返回 `202`，需要轮询直到返回 `200`
2. **流量数据必须自行存储**：否则 14 天后数据丢失
3. **大型仓库限制多**：>10k commits 的仓库很多统计不可用
4. **GraphQL 和 REST 混用**：依赖图必须用 GraphQL，其他用 REST 更方便
5. **速率限制**：建议使用 GitHub App 获取更高的速率限制

---

## 🔗 参考文档

- [GitHub REST API 文档](https://docs.github.com/en/rest)
- [GitHub GraphQL API 文档](https://docs.github.com/en/graphql)
- [Octokit.js 官方文档](https://octokit.github.io/rest.js/)
- [GitHub Actions API](https://docs.github.com/en/rest/actions)