基本能力编写完成

QUICKSTART.md

@@ -0,0 +1,188 @@
+# GitCodeStatic - 快速启动指南
+
+## 🚀 5分钟快速上手
+
+### 1. 编译并运行
+
+```bash
+# 安装依赖
+go mod tidy
+
+# 运行服务
+go run cmd/server/main.go
+```
+
+服务将在 `http://localhost:8080` 启动
+
+### 2. 添加第一个仓库
+
+```bash
+curl -X POST http://localhost:8080/api/v1/repos/batch \
+  -H "Content-Type: application/json" \
+  -d '{
+    "urls": ["https://github.com/gin-gonic/gin.git"]
+  }'
+```
+
+响应示例：
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "total": 1,
+    "succeeded": [{
+      "repo_id": 1,
+      "url": "https://github.com/gin-gonic/gin.git",
+      "task_id": 1
+    }],
+    "failed": []
+  }
+}
+```
+
+### 3. 等待克隆完成
+
+```bash
+# 查看仓库状态
+curl http://localhost:8080/api/v1/repos/1
+```
+
+等待 `status` 变为 `"ready"`
+
+### 4. 触发代码统计
+
+```bash
+curl -X POST http://localhost:8080/api/v1/stats/calculate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "repo_id": 1,
+    "branch": "master",
+    "constraint": {
+      "type": "commit_limit",
+      "limit": 100
+    }
+  }'
+```
+
+### 5. 查询统计结果
+
+```bash
+curl "http://localhost:8080/api/v1/stats/result?repo_id=1&branch=master&constraint_type=commit_limit&limit=100"
+```
+
+你将看到：
+- 总提交数
+- 贡献者列表
+- 每个贡献者的代码变更统计（新增/删除/修改/净增加）
+
+## 📊 完整工作流示例
+
+```bash
+# 1. 添加多个仓库
+curl -X POST http://localhost:8080/api/v1/repos/batch \
+  -H "Content-Type: application/json" \
+  -d '{
+    "urls": [
+      "https://github.com/gin-gonic/gin.git",
+      "https://github.com/go-chi/chi.git"
+    ]
+  }'
+
+# 2. 查看所有ready状态的仓库
+curl "http://localhost:8080/api/v1/repos?status=ready"
+
+# 3. 先查询某个日期到现在有多少提交（辅助决策）
+curl "http://localhost:8080/api/v1/stats/commit-count?repo_id=1&branch=master&from=2024-01-01"
+
+# 4. 根据提交数选择合适的约束类型
+# 如果提交数少（<1000），用日期范围
+curl -X POST http://localhost:8080/api/v1/stats/calculate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "repo_id": 1,
+    "branch": "master",
+    "constraint": {
+      "type": "date_range",
+      "from": "2024-01-01",
+      "to": "2024-12-31"
+    }
+  }'
+
+# 5. 查询结果（会自动命中缓存）
+curl "http://localhost:8080/api/v1/stats/result?repo_id=1&branch=master&constraint_type=date_range&from=2024-01-01&to=2024-12-31"
+
+# 6. 切换分支
+curl -X POST http://localhost:8080/api/v1/repos/1/switch-branch \
+  -H "Content-Type: application/json" \
+  -d '{"branch": "develop"}'
+
+# 7. 更新仓库（获取最新代码）
+curl -X POST http://localhost:8080/api/v1/repos/1/update
+
+# 8. 重置仓库（清除缓存+重新克隆）
+curl -X POST http://localhost:8080/api/v1/repos/1/reset
+```
+
+## 🔧 常见问题
+
+### Q: 如何处理私有仓库？
+A: 暂不支持通过API设置凭据，需要手动在数据库中添加或使用https://username:token@github.com/repo.git格式
+
+### Q: 统计任务一直pending？
+A: 检查worker是否正常启动，查看日志：
+```bash
+# 日志会显示worker pool启动信息
+# 确认没有错误
+```
+
+### Q: 如何加速统计？
+A: 
+1. 确保安装了git命令（比go-git快很多）
+2. 增加stats_workers数量
+3. 使用commit_limit而不是date_range（如果适用）
+
+### Q: 缓存占用空间过大？
+A: 修改配置：
+```yaml
+cache:
+  max_total_size: 5368709120  # 改为5GB
+  retention_days: 7            # 只保留7天
+```
+
+## 🎯 API完整列表
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/api/v1/repos/batch` | POST | 批量添加仓库 |
+| `/api/v1/repos` | GET | 获取仓库列表 |
+| `/api/v1/repos/:id` | GET | 获取仓库详情 |
+| `/api/v1/repos/:id/switch-branch` | POST | 切换分支 |
+| `/api/v1/repos/:id/update` | POST | 更新仓库 |
+| `/api/v1/repos/:id/reset` | POST | 重置仓库 |
+| `/api/v1/repos/:id` | DELETE | 删除仓库 |
+| `/api/v1/stats/calculate` | POST | 触发统计 |
+| `/api/v1/stats/result` | GET | 查询统计结果 |
+| `/api/v1/stats/commit-count` | GET | 查询提交次数 |
+| `/health` | GET | 健康检查 |
+
+## 📝 日志查看
+
+```bash
+# 开发模式：日志输出到stdout
+go run cmd/server/main.go
+
+# 查看结构化日志
+# 示例：
+{"level":"info","time":"2024-12-31T12:00:00+08:00","message":"worker started","worker_id":1}
+{"level":"info","time":"2024-12-31T12:00:01+08:00","message":"task started","worker_id":1,"task_id":1,"task_type":"clone","repo_id":1}
+```
+
+## 🎉 下一步
+
+- 阅读完整 [README.md](README.md) 了解所有功能
+- 查看 [ARCHITECTURE.md](ARCHITECTURE.md) 理解系统架构
+- 查看单元测试示例学习如何测试：`test/unit/`
+- 根据需求调整 `configs/config.yaml` 配置
+
+Happy Coding! 🚀