# Git 工作流操作手册

**版本**: v1.0  
**创建时间**: 2026-06-18  
**适用项目**: 小虾 SaaS

---

## 一、分支结构

### 主要分支

| 分支 | 用途 | 保护级别 | 合并要求 |
|------|------|----------|----------|
| **main** | 生产稳定版本 | 🔒 最高 | PR + 2 人 Review + CI 通过 |
| **develop** | 开发主线 | 🔒 高 | PR + 1 人 Review + CI 通过 |

### 临时分支

| 分支类型 | 命名 | 从哪里创建 | 合并到 | 示例 |
|---------|------|-----------|--------|------|
| **feature/** | feature/功能名 | develop | develop | feature/asset-upload |
| **bugfix/** | bugfix/bug描述 | develop | develop | bugfix/login-timeout |
| **hotfix/** | hotfix/紧急修复 | main | main + develop | hotfix/payment-crash |
| **release/** | release/版本号 | develop | main + develop | release/v1.2.0 |

---

## 二、日常开发流程

### 开发新功能

```bash
# 1. 确保 develop 是最新的
git checkout develop
git pull origin develop

# 2. 创建功能分支
git checkout -b feature/asset-upload

# 3. 开发 + 提交（多次）
git add .
git commit -m "feat(asset): implement OSS upload"

# 4. 推送到远程
git push -u origin feature/asset-upload

# 5. 在 Gitea 创建 Pull Request
# 访问: https://api.xiaoxiajianji.com/git/xiaoxia/xiaoxia-saas/compare/develop...feature/asset-upload

# 6. 等待 CI 检查通过 + Review 通过

# 7. 合并到 develop（在网页上操作）

# 8. 删除本地分支
git checkout develop
git pull origin develop
git branch -d feature/asset-upload
```

### 修复 Bug

```bash
# 1. 从 develop 创建 bugfix 分支
git checkout develop
git pull origin develop
git checkout -b bugfix/login-timeout

# 2. 修复 + 提交
git add .
git commit -m "fix(auth): resolve login timeout issue"

# 3. 推送并创建 PR（同上）
```

### 紧急修复（Hotfix）

```bash
# 1. 从 main 创建 hotfix 分支
git checkout main
git pull origin main
git checkout -b hotfix/payment-crash

# 2. 快速修复
git add .
git commit -m "fix(payment): resolve null pointer crash"

# 3. 合并到 main
git checkout main
git merge --no-ff hotfix/payment-crash
git tag -a v1.1.1 -m "Hotfix: payment crash"
git push origin main --tags

# 4. 合并回 develop
git checkout develop
git merge --no-ff hotfix/payment-crash
git push origin develop

# 5. 删除 hotfix 分支
git branch -d hotfix/payment-crash
```

---

## 三、Commit 规范

### 格式

```
<type>(<scope>): <subject>

<body>

<footer>
```

### Type 类型

| Type | 说明 | 示例 |
|------|------|------|
| **feat** | 新功能 | feat(asset): add video upload |
| **fix** | Bug 修复 | fix(auth): resolve token issue |
| **docs** | 文档更新 | docs(api): update auth guide |
| **style** | 代码格式 | style(asset): format with black |
| **refactor** | 重构 | refactor(auth): extract JWT service |
| **perf** | 性能优化 | perf(query): add database index |
| **test** | 测试 | test(asset): add upload tests |
| **chore** | 构建/工具 | chore(deps): upgrade fastapi |
| **ci** | CI/CD | ci(github): add security scan |
| **revert** | 回滚 | revert: revert commit abc123 |

### Scope 范围

- asset（素材管理）
- auth（认证）
- workspace（工作空间）
- subscription（订阅）
- generation（视频生成）
- api（API 层）
- ui（前端）
- db（数据库）
- infra（基础设施）

### 完整示例

```bash
feat(asset): implement video classification

- Add AI model adapter for classification
- Add classification job queue
- Add classification result storage
- Update asset entity with classification fields

This implements the core classification feature defined in Phase 7.

Closes #234
```

---

## 四、Pull Request 规范

### PR 标题

- 简洁明了，< 70 字符
- 格式同 Commit 格式：`<type>(<scope>): <subject>`

### PR 描述模板

```markdown
## 变更内容

简要描述本次 PR 的主要变更。

## 变更类型

- [ ] 新功能
- [ ] Bug 修复
- [ ] 文档更新
- [ ] 重构
- [ ] 性能优化

## 测试情况

- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 手动测试完成

## 相关 Issue

Closes #123

## 截图（如有必要）

## 额外说明
```

### Review 检查清单

Reviewer 需要检查：
- [ ] 代码符合项目规范
- [ ] 遵循 Clean Architecture
- [ ] 类型注解完整
- [ ] 有足够的测试覆盖
- [ ] 文档已更新
- [ ] 无安全问题
- [ ] CI 检查全部通过

---

## 五、Git Hooks

### Pre-commit（提交前检查）

自动检查：
- 禁止直接提交到 main/develop
- Python 代码格式（black）
- Python 代码规范（flake8）
- TypeScript/JavaScript 规范（eslint）

### Commit-msg（提交信息检查）

自动检查：
- Commit 格式是否符合规范
- 必须包含 type 和 subject

### 绕过 Hooks（仅紧急情况）

```bash
git commit --no-verify -m "emergency fix"
```

---

## 六、版本发布流程

### 准备发布

```bash
# 1. 从 develop 创建 release 分支
git checkout develop
git pull origin develop
git checkout -b release/v1.2.0

# 2. 更新版本号
# 编辑 package.json, __version__.py 等

# 3. 生成 CHANGELOG
# 使用工具或手动整理

# 4. 提交版本更新
git commit -am "chore(release): prepare v1.2.0"

# 5. 推送并创建 PR 到 main
git push -u origin release/v1.2.0
```

### 发布到生产

```bash
# 1. 合并 release 到 main
git checkout main
git merge --no-ff release/v1.2.0

# 2. 打 tag
git tag -a v1.2.0 -m "Release version 1.2.0"

# 3. 推送
git push origin main --tags

# 4. 合并回 develop
git checkout develop
git merge --no-ff release/v1.2.0
git push origin develop

# 5. 删除 release 分支
git branch -d release/v1.2.0
git push origin --delete release/v1.2.0
```

---

## 七、常见问题

### Q1: 如何撤销最后一次提交？

```bash
# 保留改动
git reset --soft HEAD^

# 丢弃改动
git reset --hard HEAD^
```

### Q2: 如何修改最后一次提交信息？

```bash
git commit --amend -m "new message"
```

### Q3: 如何合并多个提交？

```bash
# 合并最近 3 个提交
git rebase -i HEAD~3
# 在编辑器中将 pick 改为 squash
```

### Q4: 如何解决冲突？

```bash
# 1. 拉取最新代码
git pull origin develop

# 2. 手动解决冲突
# 编辑冲突文件

# 3. 标记为已解决
git add <resolved-files>

# 4. 继续
git rebase --continue
# 或
git merge --continue
```

### Q5: 如何同步 fork 的仓库？

```bash
# 1. 添加上游仓库
git remote add upstream <upstream-url>

# 2. 拉取上游更新
git fetch upstream

# 3. 合并到本地
git merge upstream/main
```

---

## 八、最佳实践

### ✅ 应该做的

1. **经常提交** - 小步快跑，每个逻辑单元一个提交
2. **有意义的提交信息** - 清晰描述"做了什么"和"为什么"
3. **提交前测试** - 确保代码可运行
4. **及时 pull** - 保持本地代码最新
5. **Code Review** - 所有代码必须经过 Review
6. **保持分支干净** - 及时删除已合并的分支

### ❌ 不应该做的

1. **直接提交到 main/develop** - 必须通过 PR
2. **强制推送** - 除非你知道自己在做什么
3. **提交敏感信息** - 密码、密钥、token 等
4. **巨大的提交** - 一次提交改动太多文件
5. **无意义的提交信息** - "fix", "update", "change" 等
6. **跳过 CI 检查** - 必须等 CI 通过

---

## 九、仓库配置

### Gitea 分支保护设置

**访问**: https://api.xiaoxiajianji.com/git/xiaoxia/xiaoxia-saas/settings/branches

**main 分支**:
- ✅ 启用分支保护
- ✅ 禁止强制推送
- ✅ 禁止删除
- ✅ 需要 PR
- ✅ 需要 2 个 Reviews
- ✅ 需要 CI 通过

**develop 分支**:
- ✅ 启用分支保护
- ✅ 禁止强制推送
- ✅ 需要 PR
- ✅ 需要 1 个 Review
- ✅ 需要 CI 通过

---

**文档版本**: v1.0  
**最后更新**: 2026-06-18  
**维护人**: 小虾 🦐
