new-api/temp/git-workflow.md

New-API Git 工作流程指南

🎯 分支架构

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

📋 分支职责

🔒 main (生产分支)

• 用途: 生产环境部署
• 特点: 只接受经过完整测试的代码
• 保护: 禁止直接推送，只能通过 PR/MR 合并

🚧 develop (开发分支)

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

🔄 upstream-sync (同步分支)

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

🚨 hotfix/* (修复分支)

• 用途: 生产环境紧急问题修复
• 特点: 基于 main 分支，修复后直接合并回 main 和 develop

🔄 标准工作流程

1. 日常功能开发

# 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. 上游同步更新

# 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. 生产环境紧急修复

# 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

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

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

CI/CD 流程

# 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. 备份习惯: 重要操作前先创建备份分支

📞 故障处理

紧急回滚

# 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

冲突解决

# 1. 查看冲突文件
git status

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

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

---

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