Skip to content

SPEC.md

Latest commit

 

History

History
194 lines (167 loc) · 5.1 KB

SPEC.md

File metadata and controls

194 lines (167 loc) · 5.1 KB

GitHub Watcher Go + React - 项目规格

概述

使用 Go + React 重写的 GitHub 仓库监测器，提供更快的后端性能和更好的前端开发体验。

技术栈

后端

  • 语言: Go 1.21+
  • Web 框架: Gin (高性能 HTTP web 框架)
  • ORM: GORM (SQLite)
  • Git 操作: go-git
  • 任务调度: robfig/cron
  • API 风格: RESTful JSON API

前端

  • 框架: React 18 + TypeScript
  • 构建工具: Vite
  • UI 库: 无框架，原生 CSS + JavaScript (或 TailwindCSS)
  • HTTP 客户端: fetch/axios
  • 状态管理: React hooks (useState, useEffect)

功能列表

核心功能

  1. 仓库管理 - 添加/删除 GitHub 仓库地址
  2. 自动同步 - 定期克隆/更新仓库（所有分支）
  3. Issues 保存 - 本地保存所有 issues（含评论）
  4. Releases 保存 - 本地保存 release 信息和资产
  5. 仓库预览 - Web 界面浏览仓库内容

Web 管理器

  • 仓库列表展示（名称、描述、同步状态、最新更新）
  • 添加仓库表单（输入 GitHub URL 或 owner/repo）
  • 删除仓库（可选：同时删除本地文件）
  • 手动触发同步
  • 查看同步历史日志

同步机制

  • 全量克隆首次添加的仓库（包含所有分支）
  • 增量更新已有仓库（git fetch --all）
  • 获取并保存 issues（通过 GitHub API）
  • 获取并保存 releases
  • 同步间隔可配置（默认 1 小时）

数据模型

Repository

type Repository struct {
    ID            uint      `gorm:"primaryKey"`
    Name          string    `gorm:"size:255;not null"`
    Owner         string    `gorm:"size:255;not null"`
    RepoPath      string    `gorm:"size:500;not null"`  // owner/repo
    LocalPath     string    `gorm:"size:1000"`
    Description   string    `gorm:"type:text"`
    LastSync      *time.Time
    SyncInterval  int       `gorm:"default:60"`  // 分钟
    IsActive      bool      `gorm:"default:true"`
    CreatedAt     time.Time
    UpdatedAt     time.Time
}

Issue

type Issue struct {
    ID            uint      `gorm:"primaryKey"`
    RepoID        uint      `gorm:"index"`
    GitHubID      int64
    Number        int
    Title         string    `gorm:"size:1000"`
    Body          string    `gorm:"type:text"`
    State         string    `gorm:"size:20"`
    Author        string    `gorm:"size:255"`
    Labels        string    `gorm:"type:text"`  // JSON
    CreatedAt     time.Time
    UpdatedAt     time.Time
    CommentsCount int
}

Release

type Release struct {
    ID            uint      `gorm:"primaryKey"`
    RepoID        uint      `gorm:"index"`
    GitHubID      int64
    Tag           string    `gorm:"size:255"`
    Name          string    `gorm:"size:1000"`
    Body          string    `gorm:"type:text"`
    Draft         bool
    Prerelease    bool
    CreatedAt     time.Time
    PublishedAt   *time.Time
    Assets        string    `gorm:"type:text"`  // JSON
}

目录结构

github-watcher-go/
├── SPEC.md
├── README.md
├── backend/
│   ├── main.go
│   ├── go.mod
│   ├── go.sum
│   ├── config/
│   │   └── config.go
│   ├── models/
│   │   └── models.go
│   ├── database/
│   │   └── database.go
│   ├── handlers/
│   │   ├── repos.go
│   │   ├── issues.go
│   │   └── releases.go
│   ├── services/
│   │   ├── git_ops.go
│   │   ├── github_sync.go
│   │   └── scheduler.go
│   └── data/
│       ├── repos/         # 克隆的仓库
│       └── db.sqlite      # SQLite 数据库
└── frontend/
    ├── package.json
    ├── vite.config.ts
    ├── index.html
    ├── src/
    │   ├── main.tsx
    │   ├── App.tsx
    │   ├── App.css
    │   ├── components/
    │   │   ├── RepoList.tsx
    │   │   ├── RepoDetail.tsx
    │   │   ├── AddRepoModal.tsx
    │   │   └── ...
    │   └── types/
    │       └── index.ts
    └── tsconfig.json

API 设计

仓库管理

  • GET /api/repos - 仓库列表
  • POST /api/repos - 添加仓库
  • GET /api/repos/:id - 仓库详情
  • DELETE /api/repos/:id - 删除仓库
  • POST /api/repos/:id/sync - 手动同步
  • POST /api/repos/:id/toggle - 启用/暂停同步

Issues

  • GET /api/repos/:id/issues - Issues 列表

Releases

  • GET /api/repos/:id/releases - Releases 列表

文件预览

  • GET /api/repos/:id/tree - 目录树
  • GET /api/repos/:id/blob/*path - 文件内容

配置项

  • DATA_DIR - 数据目录
  • SYNC_INTERVAL - 默认同步间隔（分钟）
  • GITHUB_TOKEN - GitHub API Token（可选）
  • PORT - HTTP 监听端口（默认 8898）

快速开始

后端

cd backend
go mod tidy
go run main.go

前端

cd frontend
npm install
npm run dev

开发说明

  • 后端使用 Gin 提供 REST API
  • 前端使用 Vite 开发服务器，代理 API 请求到后端
  • 数据库使用 SQLite，无需额外安装
  • Git 操作使用 go-git 库