# Git 工作流规范 - 番茄小说创作

## 分支策略

### 主分支
- `main/master`: 稳定版本，所有发布版本从此分支创建
- 保护分支，禁止直接推送，必须通过 Pull Request

### 开发分支
- `develop`: 主要开发分支，所有新功能合并到此分支
- `feature/*`: 功能分支，从 `develop` 创建，开发完成后合并回 `develop`
- `fix/*`: 修复分支，从 `develop` 或 `main` 创建，修复完成后合并回对应分支
- `hotfix/*`: 紧急修复分支，从 `main` 创建，修复完成后合并回 `main` 和 `develop`

### 发布分支
- `release/*`: 发布分支，从 `develop` 创建，用于发布准备
- `tag/v*.*.*`: 版本标签，标记发布版本

## 提交规范

### 提交消息格式
```
<type>(<scope>): <subject>

<body>

<footer>
```

### 类型 (type)
- `feat`: 新功能
- `fix`: 修复 bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建过程或辅助工具的变动
- `perf`: 性能优化
- `ci`: CI/CD 配置

### 示例
```
feat(novel): 添加第19章草稿

- 新增叶知秋视角的心理描写
- 完善张明远调查线索
- 添加悬疑钩子设置

Closes #123
```

## 文件组织

### 必版本控制的文件
1. **小说内容** (`novel/`): 所有章节、人物设定、大纲
2. **配置文件** (`*.md`): 核心配置文件
3. **脚本工具** (`*.py`, `*.sh`): 自动化脚本
4. **技能库** (`skills/`): 已安装的技能
5. **记忆文件** (`memory/`): 历史记录

### 忽略的文件
参见 `.gitignore` 配置

## 工作流程

### 日常开发
1. 从 `develop` 创建功能分支: `git checkout -b feature/new-chapter develop`
2. 开发完成后提交: 遵循提交规范
3. 推送到远程: `git push origin feature/new-chapter`
4. 创建 Pull Request 到 `develop`

### 版本发布
1. 从 `develop` 创建发布分支: `git checkout -b release/v1.0.0 develop`
2. 进行最终测试和调整
3. 合并到 `main`: `git checkout main && git merge --no-ff release/v1.0.0`
4. 打标签: `git tag -a v1.0.0 -m "Release v1.0.0"`
5. 合并回 `develop`: `git checkout develop && git merge --no-ff release/v1.0.0`
6. 删除发布分支: `git branch -d release/v1.0.0`

### 紧急修复
1. 从 `main` 创建热修复分支: `git checkout -b hotfix/critical-bug main`
2. 修复问题并提交
3. 合并到 `main`: `git checkout main && git merge --no-ff hotfix/critical-bug`
4. 打标签: `git tag -a v1.0.1 -m "Hotfix v1.0.1"`
5. 合并回 `develop`: `git checkout develop && git merge --no-ff hotfix/critical-bug`
6. 删除热修复分支: `git branch -d hotfix/critical-bug`

## 备份策略

### 本地备份
- 每日自动提交到本地仓库
- 重要变更立即提交

### 远程备份
- 推送到私有 Git 服务器 (Gitea/GitLab)
- 定期推送到多个远程仓库

## 冲突解决

### 预防措施
1. 频繁从上游分支拉取更新
2. 保持分支小而专注
3. 及时合并已完成的功能

### 解决步骤
1. 拉取最新代码: `git pull origin develop`
2. 解决冲突: 手动编辑冲突文件
3. 标记已解决: `git add <file>`
4. 继续合并: `git commit`
5. 推送更新: `git push origin <branch>`

## 工具辅助

### Git 别名
```bash
# 添加到 ~/.gitconfig
[alias]
    co = checkout
    br = branch
    ci = commit
    st = status
    lg = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit
```

### 提交前检查
```bash
# 检查代码格式
black *.py
isort *.py

# 运行测试
pytest tests/
```

## 注意事项

1. **禁止**提交敏感信息 (API Keys, 密码等)
2. **保持**提交历史的清晰和有意义
3. **及时**清理无用分支
4. **定期**备份远程仓库
5. **测试**后再合并到主分支