# 业务分支 Git 处理方案

本文档定义在本仓库进行业务开发时的分支模型、日常协作流程、合并策略、冲突处理与发布规范，并给出从 `main-framework` 分支合并到当前分支的标准步骤与命令示例。

## 分支模型
- `main-framework`：框架主线分支，承载通用框架能力与底层升级。
- `develop`：集成分支（如有），用于聚合多业务分支进行联调。
- `feature/*`：业务开发分支，以功能或需求编号命名，例如 `feature/order-approval`。
- `hotfix/*`：线上紧急修复分支，例如 `hotfix/login-captcha-null`。

命名建议：
- 使用全小写、连字符分隔；避免中文和空格；包含简短语义或任务号。

## 工作流程（日常循环）
1. 从远端更新框架主线：`git fetch origin && git checkout main-framework && git pull`。
2. 基于业务分支开展开发：`git checkout feature/xxx`。
3. 频繁从 `main-framework` 变更合并（或重置基线），保持同步：
   - 合并：`git checkout feature/xxx && git merge main-framework`。
   - 或重置基线（更干净的线性历史，需团队共识）：`git rebase main-framework`。
4. 提交与推送：按提交规范进行小步提交，`git push -u origin feature/xxx`。
5. 发起合入评审：对 `feature/xxx` → 目标分支（`develop` 或 `main-framework`）创建 PR，并通过 CI。

## 合并策略
- 默认使用 `merge --no-ff` 保留合并信息，便于回溯父子关系。
- 团队同意时，可在业务分支内使用 `rebase` 以获得线性历史；但对共享分支避免对已推送历史进行 rebase。

## 提交规范
- 提交信息格式：`<type>(scope): <subject>`
  - `type`：feat / fix / refactor / docs / test / chore / perf / build / ci
  - `scope`：可选，模块或子系统，如 `auth`、`quartz`
  - `subject`：一句话描述改动，使用祈使句，如 `add captcha ttl config`
- 示例：`fix(quartz): handle null cron when loading jobs`
- 单次提交尽量关注一个变更点；避免将大量无关改动揉在一起。

## 冲突处理
1. 运行合并命令后，如提示冲突：
   - 逐文件解决：打开冲突标记 `<<<<<<<`, `=======`, `>>>>>>>`，保留正确逻辑。
   - 标记已解决：`git add <file>`。
2. 完成后继续：
   - 合并：`git commit`（若自动生成合并提交信息可直接保存）。
   - 变基：`git rebase --continue`。
3. 如需放弃变基过程：`git rebase --abort`；如需放弃合并：`git merge --abort`。

## 质量保障
- 合并后本地构建：`mvn -q -DskipTests spring-boot:run` 或 `mvn -q clean package`。
- 若包含前端：在 `framework/frontend` 下执行 `pnpm install && pnpm build`。
- 通过单元测试与基本功能自检后再推送远端。

## 常用命令速查
- 更新远端引用：`git fetch --all --prune`
- 查看当前分支：`git rev-parse --abbrev-ref HEAD`
- 查看变更：`git status -s`
- 暂存现场：`git stash push -u -m "auto-stash before merge"`，恢复：`git stash pop`
- 创建并推送分支：`git checkout -b feature/xxx && git push -u origin feature/xxx`

## 从 main-framework 合并到当前分支（标准步骤）
在仓库根目录执行：

1. 确认当前分支：
   ```sh
   git rev-parse --abbrev-ref HEAD
   ```
2. 确保工作区干净（如有未提交改动，可先提交或使用 stash）：
   ```sh
   git status --porcelain
   ```
3. 更新远端：
   ```sh
   git fetch --all --prune
   ```
4. 若本地没有 `main-framework`，拉取远端追踪分支：
   ```sh
   git branch --track main-framework origin/main-framework 2>/dev/null || true
   ```
5. 在当前分支执行合并：
   ```sh
   git merge --no-ff main-framework
   ```
6. 解决冲突并提交（如有），然后本地验证构建与运行。
7. 推送当前分支：
   ```sh
   git push
   ```

## 常见问题
- 找不到 `main-framework`：确认远端存在 `origin/main-framework`；如远端名非 `origin`，替换为实际远端名。
- 工作区脏导致合并失败：先提交或使用 `git stash` 暂存，再合并，结束后 `stash pop` 并解决可能冲突。
- 合并后启动失败：优先检查 `pom.xml`、`application-*.yml` 的配置合入及数据库变更迁移是否完整。

---
如需自动化执行“从 main-framework 合并到当前分支”，请确保工作区干净并已配置远端，然后按上文标准步骤执行即可。

## 自动化合并脚本
- 脚本位置：`D:\JavaProjectSpace\scripts\merge-main-framework.ps1`
- 作用：自动执行从 `origin/main-framework` 合并到当前分支的流程，包含工作区检查、自动暂存（可选）、`fetch`、合并、冲突策略与推送。

参数说明：
- `-RepoPath`：仓库路径，默认为脚本所在目录的上一级。
- `-AutoStash`：当工作区不干净时自动执行 `git stash push -u`，默认 `true`。
- `-Push`：合并成功后是否推送到远端，默认 `true`。
- `-OnConflict`：冲突策略，`abort` 立即中止并恢复现场，`leave` 保留冲突现场供手动解决，默认 `leave`。

使用示例：
```powershell
# 常用：自动暂存 + 推送，冲突保留现场
& "D:\JavaProjectSpace\scripts\merge-main-framework.ps1" -AutoStash $true -Push $true -OnConflict 'leave'

# 冲突直接中止合并（不会生成合并提交）
& "D:\JavaProjectSpace\scripts\merge-main-framework.ps1" -OnConflict 'abort'

# 禁止自动暂存，需确保工作区干净
& "D:\JavaProjectSpace\scripts\merge-main-framework.ps1" -AutoStash $false
```

退出码约定：
- `0`：合并（及推送）成功。
- `2`：存在冲突且策略为 `leave`，保留现场供手动解决（按提示执行 `git add` / `git commit`）。
- `1`：命令执行错误或远端分支不存在等异常。

注意事项：
- 需本机安装并可用 `git` 命令。
- 远端分支固定为 `origin/main-framework`，如远端名不同请调整脚本或配置。
- 合并完成后建议在后端与前端分别执行构建验证，确保配置与依赖同步。