# Git 工作流程

## 分支说明

| 分支 | 用途 | 部署环境 |
|------|------|---------|
| `master` | 生产分支 | 线上生产环境 (45.153.130.80) |
| `develop` | 开发集成分支 | 测试/预发布环境 |
| `feature/*` | 个人功能分支 | 本地开发环境 |

## 分支结构

```
                    master (生产)
                       ↑
                    发布合并
                       ↑
                   develop (开发)
                       ↑
                    功能合并
                       ↑
    ┌──────────────┬────┴────┬──────────────┐
    ↓              ↓         ↓              ↓
feature/xxx-1  feature/xxx-2  feature/xxx-3  feature/xxx-4
 (个人A)       (个人B)       (个人A)        (个人B)
```

---

## 一、工作流程

### 1.1 开发新功能

**从 develop 创建个人功能分支：**

```bash
# 确保本地 develop 是最新的
git checkout develop
git pull origin develop

# 创建个人功能分支（命名规范：feature/功能名 或 feature/功能名-姓名首字母）
git checkout -b feature/user-login
# 或带姓名标识
git checkout -b feature/user-login-mzl
```

**在功能分支上开发：**

```bash
# 开发、提交
git add .
git commit -m "feat: add user login"
git push origin feature/user-login

# 继续开发...
git add .
git commit -m "fix: correct login error handling"
git push origin feature/user-login
```

### 1.2 功能开发完成

**合并到 develop 进行团队测试：**

```bash
# 1. 切换到 develop 并更新
git checkout develop
git pull origin develop

# 2. 合并功能分支（使用 --no-ff 保留合并历史）
git merge --no-ff feature/user-login -m "Merge feature/user-login into develop"

# 3. 推送到远程
git push origin develop

# 4. （可选）删除已合并的功能分支
git branch -d feature/user-login
git push origin --delete feature/user-login
```

### 1.3 发布到生产

**从 develop 合并到 master：**

```bash
# 1. 切换到 master 并更新
git checkout master
git pull origin master

# 2. 合并 develop（使用 --no-ff 保留合并历史）
git merge --no-ff develop -m "Release: merge develop into master"

# 3. 添加版本标签（可选）
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

# 4. 推送到远程
git push origin master
```

### 1.4 生产服务器部署

```bash
ssh root@45.153.130.80
cd /opt/x-server-mobile
git pull origin master
docker restart x-server-backend
# 或
docker-compose -f docker-compose.prod.yml down
docker-compose -f docker-compose.prod.yml up -d
```

---

## 二、分支命名规范

| 分支类型 | 命名格式 | 示例 |
|---------|---------|------|
| 功能分支 | `feature/功能名` 或 `feature/功能名-姓名` | `feature/user-login`, `feature/user-login-mzl` |
| 修复分支 | `fix/问题描述` 或 `fix/问题描述-姓名` | `fix/login-error`, `fix/login-error-mzl` |
| 热修复分支 | `hotfix/问题描述` | `hotfix/security-fix` |

---

## 三、前端部署

```bash
# 1. 切换到 master
git checkout master
git pull origin master

# 2. 构建前端
cd frontend
npm run build --mode production

# 3. 上传到服务器
rsync -avz --delete frontend/dist/ root@45.153.130.80:/www/sites/uniservice-mobile.hnxinyouhe.com/index/
```

---

## 四、提交信息规范

| 类型 | 说明 | 示例 |
|------|------|------|
| `feat` | 新功能 | `feat: add user login` |
| `fix` | 修复bug | `fix: correct i18n loading` |
| `docs` | 文档变更 | `docs: update deployment guide` |
| `style` | 代码格式 | `style: format code` |
| `refactor` | 重构 | `refactor: simplify auth logic` |
| `test` | 测试相关 | `test: add login test` |
| `chore` | 构建/工具 | `chore: update dependencies` |

**完整格式：**
```
<type>(<scope>): <subject>

<body>

<footer>
```

**示例：**
```
feat(login): add feishu auto-login support

- Add H5 JSSDK integration
- Implement tt.requestAuthCode for silent login
- Add token auto-refresh on 401

Closes #123
```

---

## 五、快速发布脚本

### 5.1 功能合并到 develop

```bash
# 添加到 ~/.bashrc 或 ~/.zshrc
git-finish() {
    local branch=$(git branch --show-current)
    if [[ $branch != feature/* ]]; then
        echo "❌ 当前不在 feature 分支上"
        return 1
    fi

    echo "=== 合并 $branch 到 develop ==="
    git checkout develop && \
    git pull origin develop && \
    git merge --no-ff $branch -m "Merge $branch into develop" && \
    git push origin develop && \
    echo "✅ 完成，可删除功能分支: git branch -d $branch"
}
```

### 5.2 发布到 master

```bash
# 添加到 ~/.bashrc 或 ~/.zshrc
git-release() {
    echo "=== 发布 develop 到 master ==="
    git checkout master && \
    git pull origin master && \
    git merge --no-ff develop -m "Release: merge develop into master" && \
    git push origin master && \
    git checkout develop && \
    echo "✅ 发布完成，请部署生产环境"
}
```

---

## 六、协作场景

### 6.1 多人同时开发

```
时间线：
┌─────────────────────────────────────────────────────────────┐
│ A 开发 feature/login                                         │
│ B 开发 feature/dashboard                                     │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ A 完成，合并 feature/login 到 develop                        │
│ B 继续开发 feature/dashboard                                │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ B 完成，合并 feature/dashboard 到 develop                    │
│ (此时 develop 包含 A 和 B 的更改)                            │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ 在 develop 上测试通过后，合并到 master 发布                  │
└─────────────────────────────────────────────────────────────┘
```

### 6.2 处理冲突

```bash
# 合并时遇到冲突
git checkout develop
git merge feature/login

# Git 提示冲突
# Auto-merging src/login.tsx
# CONFLICT (content): Merge conflict in src/login.tsx

# 手动解决冲突后
git add src/login.tsx
git commit -m "Merge feature/login into develop (resolved conflicts)"
git push origin develop
```

---

## 七、远程仓库

- **仓库地址**：http://219.157.255.213:25311/xinyouhe/x-server-mobile.git
- **生产分支**：`master`
- **开发分支**：`develop`
- **个人分支**：`feature/*`

---

## 八、最佳实践

### ✅ 推荐做法

1. **保持分支简短** - 功能分支完成后及时合并并删除
2. **频繁提交** - 小步提交，便于代码审查和回滚
3. **写好提交信息** - 清晰描述做了什么
4. **推送前先拉取** - 避免不必要的冲突
5. **代码审查** - 合并前让团队成员审查代码

### ❌ 避免做法

1. **直接在 master/develop 上开发** - 始终使用功能分支
2. **长时间不合并** - 功能分支会越来越难合并
3. **提交敏感信息** - 密钥、配置等不要提交
4. **强制推送 master/develop** - 可能丢失他人代码

---

## 九、常用命令速查

```bash
# 查看分支状态
git status
git branch -vv

# 创建功能分支
git checkout develop && git pull
git checkout -b feature/xxx

# 合并功能分支
git checkout develop
git merge --no-ff feature/xxx

# 发布到生产
git checkout master
git merge --no-ff develop

# 删除已合并分支
git branch -d feature/xxx
git push origin --delete feature/xxx

# 查看差异
git diff develop master
git log --oneline --graph --all
```

---

**最后更新**: 2026-02-28