业务分支 Git 处理方案

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

分支模型

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

命名建议：

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

工作流程（日常循环）

从远端更新框架主线：git fetch origin && git checkout main-framework && git pull。
基于业务分支开展开发：git checkout feature/xxx。
频繁从 main-framework 变更合并（或重置基线），保持同步：
- 合并：git checkout feature/xxx && git merge main-framework。
- 或重置基线（更干净的线性历史，需团队共识）：git rebase main-framework。
提交与推送：按提交规范进行小步提交，git push -u origin feature/xxx。
发起合入评审：对 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
单次提交尽量关注一个变更点；避免将大量无关改动揉在一起。

冲突处理

运行合并命令后，如提示冲突：
- 逐文件解决：打开冲突标记 <<<<<<<, =======, >>>>>>>，保留正确逻辑。
- 标记已解决：git add <file>。
完成后继续：
- 合并：git commit（若自动生成合并提交信息可直接保存）。
- 变基：git rebase --continue。
如需放弃变基过程：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 合并到当前分支（标准步骤）

在仓库根目录执行：

确认当前分支：
```
git rev-parse --abbrev-ref HEAD
```
确保工作区干净（如有未提交改动，可先提交或使用 stash）：
```
git status --porcelain
```
更新远端：
```
git fetch --all --prune
```

若本地没有 main-framework，拉取远端追踪分支：

git branch --track main-framework origin/main-framework 2>/dev/null || true

在当前分支执行合并：
```
git merge --no-ff main-framework
```
解决冲突并提交（如有），然后本地验证构建与运行。
推送当前分支：
```
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。

使用示例：

# 常用：自动暂存 + 推送，冲突保留现场
& "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，如远端名不同请调整脚本或配置。
合并完成后建议在后端与前端分别执行构建验证，确保配置与依赖同步。

5.9 KiB Raw Blame History Unescape Escape