wren
8.1 KiB
前端分支提交与合并防覆盖操作规范
适用范围
本文档适用于 legal-platform-frontend 前端仓库，重点解决以下高频问题：
- 本地有未提交改动时，如何安全合并别人的分支
main、wren-dev、shiy-dev等并行开发分支之间，如何避免代码被覆盖- 为什么“提交历史已经包含某个 commit”，但代码内容实际丢了
- 如何做正确的提交、推送、PR 和合并后校验
一、核心原则
1. 不要在脏工作区直接合并
合并前必须先执行：
git status
如果存在未提交改动，必须先处理：
- 能独立提交的，先提交
- 暂时不想提交的，先
stash
例如：
git stash -u
否则很容易出现：
- 合并过程把本地改动混进别人的改动
- 冲突解决时误选本地旧代码
- 最终提交混杂多个需求，后续难以回溯
2. 不要把“历史包含”误判成“功能保留”
以下命令只能说明“某个提交进入过历史”：
git branch --contains <commit>
但它不能说明这次提交改过的内容现在还保留在代码树里。
实际开发中常见情况是：
- A 分支的提交先合入
main - 后续
main再合到 B 分支 - 冲突时错误选择了旧版本
- 结果：
commit在历史里，但patch被覆盖没了
所以合并后必须额外做“内容保留校验”。
3. 冲突处理不能图快全选一边
遇到冲突时，不能默认：
- 全部选
ours - 全部选
theirs
必须逐文件判断：
- 哪些是对方新增能力
- 哪些是我方已有修复
- 哪些要手工拼接
尤其是以下类型文件最容易被误覆盖：
- 页面组件
- API 路由
- 配置文件
- 公共组件
- 菜单/路由白名单
4. 合并完成后必须做“保留性校验”
至少要检查三件事：
- 提交历史是否进入
- 关键文件是否仍保留目标改动
- 关键标识是否还能在代码中搜到
二、标准操作流程
1. 合并别人的分支到自己分支
假设目标是：把 origin/shiy-dev 合到当前 wren-dev
第一步：同步远程
git fetch origin
第二步：检查本地工作区
git status
如果有未提交改动：
git stash -u
或者先拆分提交。
第三步：确认自己当前所在分支
git branch --show-current
必须确认当前就在 wren-dev，不要站错分支。
第四步：执行合并
git merge --no-ff origin/shiy-dev
如果要明确记录来源，建议使用：
git merge --no-ff origin/shiy-dev -m "merge: sync origin/shiy-dev into wren-dev"
第五步：如果冲突，逐文件处理
处理完冲突后：
git add <冲突文件>
git commit
第六步：恢复之前的 stash
git stash pop
如果 stash pop 冲突，不要慌，继续按文件处理。
2. 合并 main 到自己分支
目标：保持 wren-dev 跟上主线进度
标准步骤：
git fetch origin
git status
git stash -u # 如果有本地未提交改动
git merge --no-ff origin/main -m "merge: sync origin/main into wren-dev"
git stash pop # 如果前面 stash 了
说明：
- 不要直接把
main切到当前脏工作区里操作 - 如果本地
main有 worktree，优先在独立 worktree 同步 - 当前主开发工作区建议长期停留在
wren-dev
3. 合并后做“内容保留校验”
这是最关键的一步。
先检查目标提交是否进入历史
git branch --contains <commit>
再检查关键文件内容是否保住
git diff <commit>..HEAD -- <关键文件>
如果看到的是“反向撤销”差异，说明：
- 历史里有这个提交
- 但代码内容被后续 merge 覆盖掉了
再搜关键符号
例如某次改动新增了：
ENTRY_MODULE_ROUTE_OPTIONSFormSelectisAllowedEntryModuleRoutePath
就应该执行：
rg "ENTRY_MODULE_ROUTE_OPTIONS|FormSelect|isAllowedEntryModuleRoutePath" .
如果关键标识不在，说明功能实际上没有保住。
三、发现“历史包含但代码没了”怎么办
这是本项目已经真实发生过的情况。
处理原则
不要重新大范围 merge。
正确做法是：
- 精确定位丢失的是哪些文件
- 只恢复这些文件
- 单独提交
推荐命令
git restore --source=<目标提交> -- <文件1> <文件2> ...
例如：
git restore --source=2b912ca -- \
app/(audit)/documents/list/DocumentsListClient.tsx \
app/(audit)/entry-modules/new/EntryModuleNewClient.tsx \
app/api/pdf-proxy/route.ts \
components/layout/Sidebar.tsx \
lib/config/entry-module-route-options.ts
然后单独提交：
git add <这些文件>
git commit -m "fix: restore shiy-dev entry route whitelist changes"
git push origin wren-dev
这种方式最安全，且不会影响你当前其他本地需求改动。
四、提交规范
1. 一个提交只解决一类问题
不要把以下内容混在一个 commit：
- 聊天功能修复
- 公文审查 UI 收敛
- 合同模板页面开发
- 分支恢复补丁
应该拆成：
fix: remove govdoc inspector file info tabfix: restore shiy-dev entry route whitelist changesfeat: add contract template search results page
2. 提交前先看范围
提交前务必执行：
git status
git diff --stat
如果只想提交部分文件：
git add <目标文件>
git commit -m "<message>"
不要图省事直接：
git add .
除非你确认工作区所有改动都属于同一件事。
3. 提交信息规范
推荐格式：
feat: 新增功能
fix: 修复问题
refactor: 重构实现
merge: 分支合并
docs: 文档更新
示例：
feat: stabilize rag chat conversation lifecyclefix: remove govdoc inspector file info tabfix: restore shiy-dev entry route whitelist changesmerge: sync origin/main into wren-dev
五、推送规范
推送前先确认：
git status
git log --oneline --max-count=5
再执行：
git push origin wren-dev
如果本地还有未提交改动，不影响推送已提交的 commit，但要明确知道：
- 已提交内容会推上去
- 未提交内容不会推上去
不要误以为“工作区里看到的所有代码”都已经在远程。
六、PR 规范
PR 标题必须说明“做了什么”，不要只写模块名。
推荐示例：
恢复入口模块跳转路径白名单与 FormSelect 收敛改动修复 RAG 对话会话生命周期、自动重命名刷新与列表状态问题
PR 描述建议固定包含：
1. 背景
为什么要改。
2. 本次改动
具体改了哪些点。
3. 影响范围
改到了哪些页面、接口、组件、模块。
4. 验证建议
告诉审核人怎么测。
5. 特别说明
如果是“恢复被覆盖改动”，要明确写出来，避免评审人误解成重复开发。
七、推荐命令清单
检查工作区
git status
git diff --stat
同步远程
git fetch origin
暂存本地未提交改动
git stash -u
git stash pop
合并主线或他人分支
git merge --no-ff origin/main
git merge --no-ff origin/shiy-dev
检查某个提交是否进入历史
git branch --contains <commit>
检查关键 patch 是否仍保留
git diff <commit>..HEAD -- <关键文件>
精确恢复某次提交改动
git restore --source=<commit> -- <文件列表>
只提交指定文件
git add <文件列表>
git commit -m "<message>"
推送当前分支
git push origin wren-dev
八、结论
以后判断一次合并是否真正成功，不能只看：
- 分支图里有没有那个 commit
还必须同时看：
- 关键文件内容还在不在
- 关键标识还能不能搜到
- 最终页面行为是不是正确
一句话总结：
合并成功的标准，不是“历史里有 commit”，而是“当前代码树里还保留对应 patch，并且功能行为正确”。