JavaProjectRepo/framework/docs/develop-framework分支Git操作指南.md

develop-framework 分支 Git 操作指南（面向 main-framework 主分支）

适用范围：D:/JavaProjectSpace/framework 项目（Spring Boot 3.3.x，可执行 JAR），远程仓库：http://121.37.111.42:3000/ThbTech/JavaProjectRepo.git 主分支：main-framework；开发分支：develop-framework

分支策略与目标

• main-framework：稳定发布分支，受保护（建议启用 PR 合并、代码审查、CI 通过）。
• develop-framework：日常开发分支，合并至主分支前需完成构建与自测。
• 推荐临时特性分支：feature/<name> 从 develop-framework 拉出，完成后合并回 develop-framework。

初始仓库设置

• 设置用户信息（确保提交署名一致）：

git config user.name "zhengsl"
git config user.email "13910913995@163.com"

• 关联远程（如已有请忽略）：

git remote set-url origin http://121.37.111.42:3000/ThbTech/JavaProjectRepo.git

• 拉取远程分支列表并跟踪：

git fetch --all --prune

开发日常流程（在 develop-framework）

• 切换到开发分支并更新：

git checkout develop-framework
git pull --ff-only

• 提交更改（遵循约定式提交，示例）：

git add .
git commit -m "feat: 支持可执行JAR打包并优化资源复制逻辑"

• 推送到远程：

git push -u origin develop-framework

合并到主分支（首选 PR 流程）

• 方式一：在 Gitea 发起 PR（推荐）

  • 目标：develop-framework -> main-framework
  • 检查 CI 构建通过、代码评审通过后合并。
  • 合并策略建议：Squash 或 Rebase and merge 保持主分支提交整洁。

• 方式二：命令行快速合并（仅在无保护、需要紧急修复时使用）

# 确保主分支最新
git checkout main-framework
git pull --ff-only

# 将主分支变更应用到开发分支，减少合并冲突
git checkout develop-framework
git rebase main-framework
# 解决冲突后：
#   git add <files>
#   git rebase --continue

# 回到主分支并合并（优先快进）
git checkout main-framework
git merge --ff-only develop-framework || git merge --no-ff develop-framework

# 推送主分支
git push origin main-framework

版本与标签（发布规范）

• 采用语义化版本：vMAJOR.MINOR.PATCH（示例：v1.0.0）。
• 打标签并推送：

# 核心检查：构建通过、基本功能自测 OK
mvn -B -DskipTests clean package

# 标签与推送
git tag -a v1.0.0 -m "release: framework v1.0.0 可执行JAR"
git push origin v1.0.0

构建校验（必须）

• 本地快速验证：

# 打包
mvn -q -DskipTests package
# 启动（dev）
java -jar target/platform-1.0.jar --spring.profiles.active=dev
# 浏览器访问（默认端口）
http://localhost:8093/

• 如果使用前端集成：
  • POM 已配置在 generate-resources 阶段执行 npm install 与 npm run build:mvn。
  • 静态资源复制（frontend/dist -> src/main/resources/static）可通过 maven-resources-plugin 控制；必要时启用/关闭 <skip> 或使用 Maven Profile 控制。

分支保护与权限（建议在 Gitea 设置）

• 保护 main-framework：
  • 禁止直接 push 到主分支，仅允许通过 PR 合并。
  • 最少 1 人审核，CI 必须通过。
  • 禁止强制推送（force push）。
• 标签权限：仅发布管理员可打 release 标签。

常见场景与命令速查

• 同步远程状态（清理过期分支）：

git fetch --all --prune

• 创建特性分支：

git checkout develop-framework
git pull --ff-only
git checkout -b feature/<name>

• 将特性分支合并回开发分支：

git checkout develop-framework
git merge --no-ff feature/<name>
git push origin develop-framework

• 更新主分支并合并开发分支（CLI）：

git checkout main-framework
git pull --ff-only
git merge --ff-only develop-framework || git merge --no-ff develop-framework
git push origin main-framework

• 回滚错误提交：

# 回滚指定提交（保留历史）
git revert <commit_sha>
# 或回退到某版本（谨慎，可能重写历史）
git reset --hard <commit_sha>
git push -f origin <branch>   # 若分支受保护，需取消保护或走 PR revert

冲突处理指南

• Rebase 阶段冲突：
  • 编辑冲突文件，确保以 main-framework 为基线保留正确逻辑。
  • 逐个解决后：git add <file>，继续：git rebase --continue。
• Merge 阶段冲突：
  • 优先在 develop-framework 解决，再合并到 main-framework，减少主分支污染。

提交规范建议（Conventional Commits）

• 前缀示例：feat、fix、docs、refactor、perf、test、build、chore。
• 示例：feat: 前端静态资源复制支持 Profile 开关。

CI/CD 建议

• CI：
  • mvn -B -DskipTests clean package
  • 单元测试、依赖安全扫描、代码质量检查
• CD：
  • 根据标签构建镜像，注入敏感配置（环境变量/密钥管理）。

问题排查

• 构建失败：检查 pom.xml 插件配置，先本地运行 mvn -e package 查看详细栈。
• 端口冲突：调整 server.port 或释放占用端口。
• npm 警告/冲突：在 frontend/ 内单独 npm install && npm run build，再复制到后端静态目录。

---

如需将资源复制与文档生成改为按需开关（Maven Profile），可在 pom.xml 中添加 Profile 并通过 -P <profile> 控制。需要我帮助你落地 Profile 与分支保护脚本，请告诉我你的偏好（例如是否必须走 PR）。