From b8a2635707941d67d203b7f417eb896f31c39989 Mon Sep 17 00:00:00 2001
From: ProjectFrameWork2025 <noreply@example.com>
Date: Sun, 9 Nov 2025 16:25:49 +0800
Subject: [PATCH] =?UTF-8?q?docs=EF=BC=9A=E6=B7=BB=E5=8A=A0=E4=BA=86?=
 =?UTF-8?q?=E5=BC=80=E5=8F=91=E5=88=86=E6=94=AFGIT=E6=93=8D=E4=BD=9C?=
 =?UTF-8?q?=E6=8C=87=E5=8D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../docs/develop-framework分支Git操作指南.md  | 160 ++++++++++++++++++
 1 file changed, 160 insertions(+)
 create mode 100644 framework/docs/develop-framework分支Git操作指南.md

diff --git a/framework/docs/develop-framework分支Git操作指南.md b/framework/docs/develop-framework分支Git操作指南.md
new file mode 100644
index 0000000..4fd1334
--- /dev/null
+++ b/framework/docs/develop-framework分支Git操作指南.md
@@ -0,0 +1,160 @@
+# 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 "zhengsl@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）。
\ No newline at end of file