# Git 多分支 + 多模块 单仓库方案（优化版）

本方案在原有文档基础上进行了结构重构与细则完善，使其更易落地、可操作性强，并与当前仓库现状保持一致且可平滑演进。

## 0. 适用范围与设计目标

- 适用范围：Java Spring Boot 后端 + 独立前端工程的单仓库（Monorepo）协作。
- 总体目标：
  - 公共框架代码统一维护与版本化发布。
  - 业务系统独立演进，低耦合地复用框架能力。
  - 清晰的分支与发布节奏，降低冲突与回归风险。

## 1. 仓库结构与现状
```

### 推荐结构（框架含基线前端，业务前端复制自框架）
```
JavaProjectRepo/
├── framework/                 # 后端框架（Maven 模块）+ 基线前端
│   └── frontend/              # 基线前端（可作为模板与上游源）
├── business-css/            # 业务系统A（Maven 模块）
│   ├── src/                   # 业务A后端代码
│   └── frontend/              # 业务A前端（由 framework/frontend 复制）
├── docs/
├── pom.xml                    # 父POM（仅管理后端Maven模块）
```

说明：
- 保持 `framework/frontend` 为“基线前端”，承载公共 UI/组件、构建脚本与基础配置。
- 每个业务系统在自身目录下维护独立 `frontend/`，初始化时从 `framework/frontend` 复制；后续按业务需求改造。
- 根 `pom.xml` 仅管理后端模块；各前端项目独立使用 `pnpm/npm/yarn` 管理与构建。

## 2. 分支与权限策略

### 长期分支
```bash
main-framework          # 框架稳定版本（受保护）
develop-framework       # 框架开发分支
main-business-css       # 业务稳定分支（单业务时，受保护）
develop-business-css    # 业务开发分支（单业务时）
# 多业务可扩展：main-business-css / develop-business-css 等
```

### 受保护策略（建议在 Git 服务器上配置）
- `main-framework`、`main-business-css`：
  - 禁止直接 push；必须通过合并请求（MR/PR）。
  - 必须通过 CI（单元测试 + 构建）与至少 1 人代码评审。
  - 建议启用“必须线性历史”（不允许非快进式合并）或统一使用 squash merge。
- 标签（tags）仅允许由“发布管理员”或 CI 流水线创建。

### 合并策略
- 框架到业务：业务分支定期合入 `main-framework` 的框架更新（推荐 `git merge --no-ff` 或 `git rebase`，视团队偏好）。
- 业务到业务稳定：`develop-business-css` → `main-business-css` 通过 MR/PR，保持发布记录清晰。
- 框架发布：`develop-framework` → `main-framework`，并打版本标签。

## 3. 代码组织（Maven 多模块 + 前端）

### 根 POM（示例）
```xml
<!-- pom.xml -->
<modules>
    <module>framework</module>
    <module>business-css</module>
    <!-- 前端不纳入 Maven modules；独立管理 -->
    <!-- 如需统一构建，可在 CI 中分阶段调用前端构建脚本 -->
</modules>

<properties>
    <java.version>21</java.version>
    <spring-boot.version>3.x</spring-boot.version>
    <mybatis-plus.version>3.5.6</mybatis-plus.version>
</properties>
```

### Framework 模块 POM（示例）
```xml
<groupId>com.yfd.platform</groupId>
<artifactId>platform-framework</artifactId>
<version>1.0.0</version>
<packaging>jar</packaging>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-boot-starter</artifactId>
        <version>${mybatis-plus.version}</version>
    </dependency>
</dependencies>
```

### Business-App 模块 POM（示例）
```xml
<parent>
    <groupId>com.yfd.platform</groupId>
    <artifactId>platform-parent</artifactId>
    <version>1.0.0</version>
</parent>

<artifactId>platform-business-css</artifactId>
<packaging>war</packaging>

<dependencies>
    <dependency>
        <groupId>com.yfd.platform</groupId>
        <artifactId>platform-framework</artifactId>
        <version>${project.version}</version>
    </dependency>
    <!-- 业务特定依赖 -->
    <!-- 如需框架版本对齐，建议使用 BOM 或统一 parent 管理 -->
    <!-- 也可将框架发布到私有仓库（Nexus/Artifactory）后以固定版本依赖 -->
</dependencies>
```

### 前端工程（建议）
- `framework/frontend` 作为上游基线；业务前端以复制方式继承并二次开发。
- 每个业务的前端位于 `business-app-*/frontend`，独立构建与发布；与后端解耦。
- 公共前端能力尽量沉淀在基线前端的可复用目录（如 `src/shared`、`ui/components`），便于业务端复制后保持一致。

### 前端复制与同步策略
- 初次复制：从 `framework/frontend` 完整复制到 `business-app-x/frontend`，保留 `.editorconfig`、`eslint/prettier`、`tailwind`、`vite` 等工程化文件。
- 差异化开发：在业务前端中修改业务页面、路由、接口地址、主题等，不直接改动 `framework/frontend`。
- 上游更新引入（从框架基线同步到业务前端）可选方案：
  - 轻量脚本复制：使用 `robocopy`（Windows）或 `rsync`（Linux/Mac）定期同步除配置与 `node_modules` 外的公共目录；同步前使用分支/MR审阅。
  - 组件库抽取：将通用UI/工具抽取为 `shared` 子包（后续可独立NPM私库），业务端通过包管理升级；当前阶段以目录复制为主。
  - 提交粒度控制：框架前端的公共改动与模板变更使用 `feat(shared):`、`refactor(shared):` 提交，业务端便于识别与选择性采纳。

示例：Windows 下使用 `robocopy` 同步公共目录（不覆盖业务自定义配置）
```powershell
# 在仓库根执行，将 framework/frontend 的公共目录同步到业务A前端
$src = "framework/frontend"
$dst = "business-app-a/frontend"
# 同步 src 目录与部分工程化文件；排除 node_modules、环境配置
robocopy $src $dst /MIR /XD node_modules .git .husky /XF .env* pnpm-lock.yaml
# 可按需选择性同步 src/shared、types 等
robocopy "$src/src/shared" "$dst/src/shared" /MIR
```

## 4. 开发与协作工作流（落地命令）

### 初始化与分支创建
```bash
git clone http://121.37.111.42:3000/ThbTech/JavaProjectRepo.git
cd JavaProjectRepo
git checkout -b main-framework
git push -u origin main-framework

# 框架开发分支
git checkout -b develop-framework
git push -u origin develop-framework

# 业务开发分支（如仅一个业务）
git checkout main-framework
git checkout -b develop-business-css
git push -u origin develop-business-css
```

### 框架功能开发
```bash
git checkout develop-framework
# 修改 framework/ 下代码
git add framework/
git commit -m "feat(framework): 新增通用权限管理模块"
git push origin develop-framework

# 合并到 main（发布框架版本）
git checkout main-framework
git merge --no-ff develop-framework
git tag -a fw-v1.1.0 -m "框架版本 v1.1.0"
git push origin main-framework --tags
```

### 业务功能开发与同步框架
```bash
git checkout develop-business
git fetch origin
git merge origin/main-framework   # 合入最新框架

# 在 business-css/ 下开发
git add business-css/
git commit -m "feat(order): 实现订单管理功能"
git push origin develop-business-css

# 稳定分支（如需要）
git checkout -b main-business-css
git push -u origin main-business-css
```

### 业务前端初始化（从框架复制）
```powershell
# 以 business-app-a 为例：在仓库根执行
mkdir business-app-a\frontend
# 复制基线前端（保留工程化配置，排除 node_modules）
robocopy framework\frontend business-app-a\frontend /MIR /XD node_modules .git .husky /XF .env* pnpm-lock.yaml

# 进入业务前端目录并安装依赖
cd business-app-a\frontend
pnpm i || npm ci

# 修改业务专属配置：
# - package.json 的 name、version（如需）
# - .env.*（API 地址、端口等）
# - src/pages/*、src/routes/*（业务页面与路由）

# 开发与启动
pnpm dev || npm run dev
```

### 模块级构建与测试（Maven）
```bash
# 仅构建框架
mvn -pl framework -am clean package

# 仅测试业务模块
mvn -pl business-app -am clean test

# 全部模块
mvn clean verify
```

## 5. 版本与标签策略

- 框架版本采用 SemVer：`fw-vMAJOR.MINOR.PATCH`，如 `fw-v1.2.0`。
- 业务版本与框架版本对齐或独立：建议 `biz-<system>-vMAJOR.MINOR.PATCH`，如 `biz-order-v1.0.0`。
- 标签一律打在稳定分支合并完成后；禁止在临时/开发分支打标签。

## 6. 配置管理与覆盖

### 框架通用配置示例
```yaml
# framework/src/main/resources/application.yml
spring:
  datasource:
    druid:
      url: jdbc:mysql://${DB_HOST:localhost}:3306/${DB_NAME:platform}?useUnicode=true&characterEncoding=UTF8
      username: ${DB_USER:appuser}
      password: ${DB_PASSWORD:}
  profiles:
    active: @activatedProperties@
```

### 业务特定配置示例
```yaml
# business-app/src/main/resources/application-dev.yml
server:
  port: 8093

business:
  order:
    timeout: 3600
  file:
    upload-path: D:/data/business-upload

spring:
  datasource:
    druid:
      url: jdbc:mysql://localhost:3306/business_db
```

配置原则：
- 框架提供默认配置；业务分支优先保留业务特定配置。
- 配置差异通过 profile 管理；不要在框架直接硬编码业务参数。

## 7. 冲突与同步指南

### 定期同步流程
```bash
git checkout develop-business
git fetch origin
git merge origin/main-framework   # 或：git rebase origin/main

# 处理常见冲突：
# - application.yml / profiles 差异
# - 通用实体与业务扩展字段
# - 依赖版本不一致

mvn clean test -pl business-app
```

### 处理建议
- 配置冲突：业务优先；框架提供可扩展参数，而非覆盖业务。
- 实体冲突：为框架实体保留扩展点（如继承/组合）；避免强耦合。
- API 兼容：框架废弃旧 API 需标注 deprecate，过渡期保留兼容层。
- 推荐启用 `git rerere` 记忆冲突解决，减少重复操作。

## 8. CI/CD 集成建议

### 典型流水线分阶段
```yaml
stages:
  - framework-test
  - business-test
  - frontend-build
  - build
  - deploy

framework-test:
  only:
    - develop-framework
    - main
  script:
    - mvn -pl framework -am clean verify

business-test:
  only:
    - develop-business
    - business-main
  script:
    - mvn -pl business-app -am clean verify

frontend-build:
  only:
    - develop-framework
    - develop-business
    - business-main
    - main
  script:
    # 构建基线前端
    - cd framework/frontend
    - pnpm i --frozen-lockfile || npm ci
    - pnpm build || npm run build
    # 构建业务前端（示例：A；可按项目实际枚举）
    - cd ../../business-css/frontend
    - pnpm i --frozen-lockfile || npm ci
    - pnpm build || npm run build
```

### 分支保护与质量门禁
- `main`/`business-main` 必须通过上述阶段且无失败后才允许合并。
- 建议强制代码扫描（如 SpotBugs、ESLint）、制品上传、部署前审批。

## 9. 落地与迁移指南

### 从当前结构平滑演进到推荐结构
1. 保持现状：`framework/frontend` 作为基线前端，上游统一维护公共能力。
2. 新增 `business-app-a/` 模块（后端）：复制示例 POM，引入 `platform-framework` 依赖。
3. 初始化业务前端：复制 `framework/frontend` → `business-app-a/frontend`，安装依赖并调整 `.env.*`、路由与页面。
4. 在 Git 服务器上设置分支保护与 MR/PR 规则、必需检查与发布审批。
5. 建立“前端同步脚本”或“公共组件抽取”机制，周期性从基线前端引入更新并审阅。

### CSS 项目（Critical Scenario Simulator, CSS）落地步骤
1. 根父 POM：在仓库根新增 `pom.xml`（已添加），注册 `framework` 与 `business-css` 模块。
2. 业务后端：新增 `business-css/pom.xml`，依赖 `com.yfd:platform:1.0` 的 classes JAR（框架已配置 maven-jar-plugin）。
3. 前端初始化：运行 `./scripts/sync-frontend.ps1 -Source "framework/frontend" -Target "business-css/frontend"`，复制基线前端。
4. 前端安装与启动：在 `business-css/frontend` 执行 `pnpm i` 或 `npm ci` 后，`pnpm dev`。
5. 构建与测试：
   - 后端单模块：`mvn -pl business-css -am clean verify`
   - 聚合构建：`mvn clean verify`
6. 分支策略建议：
   - 框架：`develop-framework` → `main`，标签 `fw-vx.y.z`
   - CSS：`develop-business-css`（或沿用 `develop-business`）→ `business-main`，标签 `biz-css-vx.y.z`
7. 同步策略：CSS 业务分支定期合入 `origin/main` 的框架更新；前端公共更新通过脚本或 MR 评审引入。

### 新业务扩展
```
ProjectFrameWork2025/
├── framework/
├── business-app-a/
├── business-app-b/
├── frontend/
└── pom.xml
```
- 每个业务独立 `develop-business-x` 与 `business-x-main` 分支；统一从 `main` 合入框架更新。

## 10. 开发规范（精炼）

### 提交消息（Conventional Commits 建议）
```
feat(order): 新增订单管理功能
fix(auth): 修复用户权限验证问题
docs(api): 更新接口文档
refactor(payment): 重构支付服务层
perf(db): 优化数据库查询性能
```

### 分支命名
- 功能：`feature/<模块>-<简述>`
- 修复：`hotfix/<问题>-<简述>`
- 发布：`release/<版本号>`

## 11. 运维监控与治理

- 分支健康：定期检查各业务分支落后于 `main` 的提交数，提示同步。
- 冲突监控：统计合并冲突频率与位置，反推框架设计优化点。
- 框架使用率：记录各业务对框架模块的依赖程度与版本分布，指导演进。

## 12. 附录：命令速查

```bash
# 获取模块依赖树
mvn -pl framework -am dependency:tree

# 仅运行某模块测试
mvn -pl business-app -am -DskipITs=false test

# 前端构建（根级）
cd frontend && pnpm i && pnpm build
```

---

本优化版方案兼顾当前仓库现状与后续演进路径，优先实现“可用且可管控”，再循序迭代至“前后端分离、多业务扩展”的理想结构。若需要，我可以进一步：
- 提供 Git 服务器（Gitea/GitLab）具体保护规则配置截图级操作步骤；
- 为当前 CI 环境生成可直接使用的脚本与模板文件；
- 输出 `CODEOWNERS`、PR 模板与自动化检查清单。