# GitCodeStatic - Git仓库统计与缓存系统

一个用Go实现的高性能Git仓库代码统计与缓存系统，支持批量仓库管理、异步任务处理、智能缓存、多种统计维度，提供 Swagger API 文档和 Web 管理界面。

## 功能特性

### 核心功能
- ✅ **批量仓库管理**：支持批量添加、更新、切换分支、重置仓库
- ✅ **异步任务处理**：基于队列的Worker池，支持并发控制和任务去重
- ✅ **代码统计**：按分支、贡献者维度统计代码变更（新增/删除/修改/净增加）
- ✅ **智能缓存**：基于文件+数据库的双层缓存，自动失效机制
- ✅ **灵活约束**：支持日期范围或提交次数限制（互斥校验）
- ✅ **辅助查询**：查询指定日期到当前的提交次数
- ✅ **凭据管理**：支持私有仓库（用户名/密码/Token）
- ✅ **Git双引擎**：优先使用git命令，可fallback到go-git

### 技术特性
- 📊 **可观测**：结构化日志（zerolog）、基础指标收集
- 🔒 **安全**：凭据加密存储、URL脱敏、命令注入防护
- 🧪 **可测试**：关键逻辑提供单元测试示例
- 🎯 **RESTful API**：统一响应格式、完善错误码
- 📚 **Swagger 文档**：完整的 API 文档和交互式测试界面
- 🖥️ **Web UI**：基于 Vue 3 + Element Plus 的管理界面，支持离线部署
- 🗄️ **存储灵活**：默认SQLite，可扩展PostgreSQL
- ⚡ **高性能**：任务去重、缓存命中、并发控制

## 快速体验

### 启动服务

```bash
# 构建
make build

# 运行
./bin/gitcodestatic

# 或直接运行
go run cmd/server/main.go
```

服务启动后，可以通过以下方式访问：

- **Web UI**: http://localhost:8080/
- **Swagger API 文档**: http://localhost:8080/swagger/index.html
- **Health Check**: http://localhost:8080/health
cp configs/config.yaml configs/config.local.yaml
```

主要配置项：

```yaml
server:
  port: 8080

workspace:
  cache_dir: ./workspace/cache  # 仓库本地缓存
  stats_dir: ./workspace/stats  # 统计结果存储

worker:
  clone_workers: 2   # 克隆并发数
  stats_workers: 2   # 统计并发数

cache:
  max_total_size: 10737418240  # 10GB
  retention_days: 30

git:
  command_path: ""   # 空表示使用PATH中的git
  fallback_to_gogit: true
```

### 运行

```bash
# 开发模式
go run cmd/server/main.go

# 编译
go build -o gitcodestatic cmd/server/main.go

# 运行
./gitcodestatic
```

服务启动后访问：
- API: `http://localhost:8080/api/v1`
- Health: `http://localhost:8080/health`

## Web UI 使用

启动服务后访问 http://localhost:8080/ 进入 Web 管理界面。

### 主要功能

1. **仓库管理**
   - 批量添加仓库（支持多行输入）
   - 查看仓库列表和状态
   - 切换分支、更新、重置、删除操作

2. **统计管理**
   - 触发统计计算（支持日期范围和提交数限制）
   - 查询统计结果（可视化展示）
   - 查看贡献者详情

3. **API 文档**
   - 快速访问 Swagger 文档
   - API 使用示例

详细使用说明请参考 [WEBUI_GUIDE.md](docs/WEBUI_GUIDE.md)

## API 使用示例

### 1. 批量添加仓库

```bash
curl -X POST http://localhost:8080/api/v1/repos/batch \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://github.com/golang/go.git",
      "https://github.com/kubernetes/kubernetes.git"
    ]
  }'
```

响应：
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 2,
    "succeeded": [
      {
        "repo_id": 1,
        "url": "https://github.com/golang/go.git",
        "task_id": 101
      }
    ],
    "failed": []
  }
}
```

### 2. 查询仓库列表

```bash
curl http://localhost:8080/api/v1/repos?status=ready&page=1&page_size=20
```

### 3. 触发代码统计

**按日期范围统计：**
```bash
curl -X POST http://localhost:8080/api/v1/stats/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "repo_id": 1,
    "branch": "main",
    "constraint": {
      "type": "date_range",
      "from": "2024-01-01",
      "to": "2024-12-31"
    }
  }'
```

**按提交次数统计：**
```bash
curl -X POST http://localhost:8080/api/v1/stats/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "repo_id": 1,
    "branch": "main",
    "constraint": {
      "type": "commit_limit",
      "limit": 100
    }
  }'
```

### 4. 查询统计结果

```bash
curl "http://localhost:8080/api/v1/stats/result?repo_id=1&branch=main&constraint_type=date_range&from=2024-01-01&to=2024-12-31"
```

响应：
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "cache_hit": true,
    "cached_at": "2024-12-31T10:00:00Z",
    "commit_hash": "abc123...",
    "statistics": {
      "summary": {
        "total_commits": 150,
        "total_contributors": 5,
        "date_range": {
          "from": "2024-01-01",
          "to": "2024-12-31"
        }
      },
      "by_contributor": [
        {
          "author": "Alice",
          "email": "alice@example.com",
          "commits": 50,
          "additions": 1000,
          "deletions": 200,
          "modifications": 200,
          "net_additions": 800
        }
      ]
    }
  }
}
```

### 5. 辅助查询：统计提交次数

```bash
curl "http://localhost:8080/api/v1/stats/commit-count?repo_id=1&branch=main&from=2024-01-01"
```

响应：
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "repo_id": 1,
    "branch": "main",
    "from": "2024-01-01",
    "to": "HEAD",
    "commit_count": 150
  }
}
```

### 6. 其他操作

**切换分支：**
```bash
curl -X POST http://localhost:8080/api/v1/repos/1/switch-branch \
  -H "Content-Type: application/json" \
  -d '{"branch": "develop"}'
```

**更新仓库：**
```bash
curl -X POST http://localhost:8080/api/v1/repos/1/update
```

**重置仓库：**
```bash
curl -X POST http://localhost:8080/api/v1/repos/1/reset
```

## 数据模型

### 统计指标说明

| 字段 | 说明 | 计算方式 |
|------|------|----------|
| `additions` | 新增行数 | git log --numstat 的additions |
| `deletions` | 删除行数 | git log --numstat 的deletions |
| `modifications` | 修改行数 | min(additions, deletions) |
| `net_additions` | 净增加行数 | additions - deletions |

**修改行数定义**：一行代码被替换时，同时计入additions和deletions，`modifications`取两者最小值表示真正被修改的行数。

### 约束类型互斥

`date_range` 和 `commit_limit` 互斥使用：

- ✅ `{"type": "date_range", "from": "2024-01-01", "to": "2024-12-31"}`
- ✅ `{"type": "commit_limit", "limit": 100}`
- ❌ `{"type": "date_range", "from": "2024-01-01", "to": "2024-12-31", "limit": 100}` - 错误

## 缓存策略

### 缓存Key生成

```
SHA256(repo_id | branch | constraint_type | constraint_value | commit_hash)
```

### 缓存失效时机

1. 仓库更新（pull）：commit_hash变化，旧缓存自然失效
2. 切换分支：branch变化，缓存key不同
3. 重置仓库：主动删除该仓库所有缓存

### 存储位置

- **元数据**：SQLite `stats_cache` 表
- **结果数据**：文件系统 `workspace/stats/{cache_key}.json.gz`（gzip压缩）

## 任务系统

### 任务类型

- `clone`: 克隆仓库
- `pull`: 拉取更新
- `switch`: 切换分支
- `reset`: 重置仓库
- `stats`: 统计代码

### 任务状态

- `pending`: 等待处理
- `running`: 执行中
- `completed`: 完成
- `failed`: 失败
- `cancelled`: 已取消

### 去重机制

相同仓库+相同任务类型+相同参数的待处理任务只会存在一个，重复提交返回已有任务ID。

## 测试

### 运行单元测试

```bash
# 运行所有测试
go test ./...

# 运行特定测试
go test ./test/unit -v

# 测试覆盖率
go test ./... -cover
```

### 测试示例

见 `test/unit/` 目录：
- `service_test.go` - 参数校验测试
- `cache_test.go` - 缓存key生成测试

## 开发指南

### 添加新的 API 端点

1. 在 `internal/api/handlers/` 创建handler方法
2. 添加 Swagger 注释
3. 在 `internal/api/router.go` 注册路由
4. 重新生成 Swagger 文档：
   ```bash
   swag init -g cmd/server/main.go -o docs
   ```

### 添加新的任务类型

1. 在 `internal/models/task.go` 定义任务类型常量
2. 在 `internal/worker/handlers.go` 实现 `TaskHandler` 接口
3. 在 `cmd/server/main.go` 注册handler

### 扩展存储层

实现 `internal/storage/interface.go` 中的接口即可，参考 `sqlite/` 实现。

### 扩展 Web UI

1. 修改 `web/index.html` 添加新的页面组件
2. 在 `web/static/app.js` 添加相应的方法和数据
3. 参考 [WEBUI_GUIDE.md](docs/WEBUI_GUIDE.md) 了解详细开发流程

## 错误码

| Code | 说明 |
|------|------|
| 0 | 成功 |
| 40001 | 参数校验失败 |
| 40002 | 操作不允许 |
| 40400 | 资源未找到 |
| 40900 | 资源冲突 |
| 50000 | 内部错误 |
| 50001 | 数据库错误 |
| 50002 | Git操作失败 |

## 文档

- [架构设计](ARCHITECTURE.md) - 系统架构和技术选型
- [快速开始](QUICKSTART.md) - 快速上手指南
- [Web UI 使用指南](docs/WEBUI_GUIDE.md) - 前端和 Swagger 文档使用
- [项目总结](SUMMARY.md) - 项目完整总结

## 性能优化建议

1. **Git命令模式**：确保安装git命令，性能比go-git快10-100倍
2. **并发调优**：根据CPU核心数和IO性能调整worker数量
3. **缓存预热**：对常用仓库/分支提前触发统计
4. **定期清理**：配置缓存保留天数和总大小限制

## 已知限制

1. 单机部署，不支持分布式（可扩展）
2. go-git模式性能较差，仅作为fallback
3. 大仓库（>5GB）统计可能耗时较长
4. SSH认证暂未完整实现（仅支持https）

## 技术栈

- **后端**: Go 1.21+, Chi Router, zerolog
- **存储**: SQLite (可扩展 PostgreSQL)
- **Git**: git CLI + go-git fallback
- **文档**: Swagger 2.0 (swaggo/swag)
- **前端**: Vue 3, Element Plus, Axios
- **特性**: 完全离线部署支持

## 贡献

欢迎提Issue和PR！

## License

MIT License

## 作者

Created by Senior Backend/Full-stack Engineer (Go专家)