# New-API Git 工作流程指南

## 🎯 分支架构

```
main (生产稳定)
├── develop (日常开发)  
├── upstream-sync (上游同步)
└── hotfix/* (紧急修复)
```

## 📋 分支职责

### 🔒 main (生产分支)
- **用途**: 生产环境部署
- **特点**: 只接受经过完整测试的代码
- **保护**: 禁止直接推送，只能通过 PR/MR 合并

### 🚧 develop (开发分支) 
- **用途**: 日常自定义功能开发
- **特点**: 基于 main 分支，包含所有自定义修改
- **流程**: 功能完成后合并回 main

### 🔄 upstream-sync (同步分支)
- **用途**: 跟踪官方 new-api 更新
- **特点**: 保持与上游仓库同步，不包含自定义修改
- **流程**: 定期同步，选择性合并到 develop

### 🚨 hotfix/* (修复分支)
- **用途**: 生产环境紧急问题修复
- **特点**: 基于 main 分支，修复后直接合并回 main 和 develop

## 🔄 标准工作流程

### 1. 日常功能开发

```bash
# 1. 确保在最新的 develop 分支
git checkout develop
git pull origin develop

# 2. 创建功能分支 (可选，小改动可直接在 develop)
git checkout -b feature/智能请求头优化

# 3. 开发和测试
# ... 编码 ...
git add .
git commit -m "feat: 实现新功能"

# 4. 推送到远程
git push origin feature/智能请求头优化

# 5. 测试通过后合并到 develop
git checkout develop
git merge feature/智能请求头优化
git push origin develop

# 6. 部署测试无问题后合并到 main
git checkout main  
git merge develop
git push origin main

# 7. 清理功能分支
git branch -d feature/智能请求头优化
git push origin --delete feature/智能请求头优化
```

### 2. 上游同步更新

```bash
# 1. 切换到同步分支
git checkout upstream-sync

# 2. 拉取上游最新更新
git fetch upstream
git merge upstream/main

# 3. 推送同步结果
git push origin upstream-sync

# 4. 检查更新内容，选择性合并到 develop
git checkout develop
git log upstream-sync --oneline -10  # 查看新提交

# 5. 选择需要的提交合并 (谨慎操作)
git cherry-pick <commit-hash>  # 只合并需要的提交

# 6. 或者创建合并请求进行 code review
```

### 3. 生产环境紧急修复

```bash
# 1. 基于 main 创建修复分支
git checkout main
git checkout -b hotfix/修复Claude透传问题

# 2. 修复问题
# ... 编码修复 ...
git add .
git commit -m "hotfix: 修复 Claude 透传问题"

# 3. 测试修复效果
# ... 测试 ...

# 4. 合并到 main (生产部署)
git checkout main
git merge hotfix/修复Claude透传问题
git push origin main

# 5. 同步修复到 develop
git checkout develop
git merge hotfix/修复Claude透传问题
git push origin develop

# 6. 清理修复分支
git branch -d hotfix/修复Claude透传问题
```

## 🛡️ 安全检查清单

### 合并前检查
- [ ] 代码编译通过
- [ ] Docker 构建成功  
- [ ] 功能测试完成
- [ ] 没有遗留 TODO 或 debug 代码
- [ ] 提交信息清晰明确

### 部署前检查
- [ ] 备份当前生产版本
- [ ] 数据库迁移脚本准备就绪
- [ ] 回滚方案确定
- [ ] 监控告警已配置

## 📁 目录结构说明

```
new-api/
├── temp/
│   ├── git-workflow.md          # 本文档
│   ├── deployment-checklist.md  # 部署检查清单
│   └── troubleshooting.md       # 问题排查指南
├── .claude                      # Claude Code 项目配置
└── ...
```

## 🚀 自动化建议

### Git Hooks
```bash
# pre-commit: 提交前检查
#!/bin/sh
echo "运行代码格式化..."
go fmt ./...

echo "运行静态检查..."
go vet ./...
```

### CI/CD 流程
```yaml
# GitHub Actions 示例
name: CI/CD Pipeline
on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build and Test
        run: |
          go build ./...
          docker build -t new-api-test .
```

## 💡 最佳实践

1. **小步快跑**: 频繁小提交，避免大批量修改
2. **描述清晰**: 提交信息使用约定式提交格式
3. **测试先行**: 每个功能都要有对应测试
4. **文档同步**: 重要修改及时更新文档
5. **备份习惯**: 重要操作前先创建备份分支

## 📞 故障处理

### 紧急回滚
```bash
# 1. 快速回滚到上一个稳定版本
git checkout main
git reset --hard HEAD~1
git push --force-with-lease origin main

# 2. 或回滚到指定版本
git reset --hard <stable-commit-hash>
git push --force-with-lease origin main
```

### 冲突解决
```bash
# 1. 查看冲突文件
git status

# 2. 手动解决冲突
# 编辑冲突文件，删除 <<<<<<< ======= >>>>>>> 标记

# 3. 标记冲突已解决
git add <resolved-file>
git commit
```

---
*本文档由 Claude Code 生成，请根据实际情况调整*