# 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）。