From 478b5deaba121ccc7bf2d96f7fd3a6120039f373 Mon Sep 17 00:00:00 2001 From: ProjectFrameWork2025 Date: Sun, 9 Nov 2025 15:39:10 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B8=85=E7=90=86main-framework=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .vscode/launch.json | 21 --- framework/Dockerfile | 21 --- git管理方案.md | 408 ------------------------------------------- 3 files changed, 450 deletions(-) delete mode 100644 .vscode/launch.json delete mode 100644 framework/Dockerfile delete mode 100644 git管理方案.md diff --git a/.vscode/launch.json b/.vscode/launch.json deleted file mode 100644 index 02d942d..0000000 --- a/.vscode/launch.json +++ /dev/null @@ -1,21 +0,0 @@ -{ - // 使用 IntelliSense 了解相关属性。 - // 悬停以查看现有属性的描述。 - // 欲了解更多信息，请访问: https://go.microsoft.com/fwlink/?linkid=830387 - "version": "0.2.0", - "configurations": [ - { - "type": "java", - "name": "PlatformApplication", - "request": "launch", - "mainClass": "com.yfd.platform.PlatformApplication", - "projectName": "" - }, - { - "type": "java", - "name": "Current File", - "request": "launch", - "mainClass": "${file}" - } - ] -} \ No newline at end of file diff --git a/framework/Dockerfile b/framework/Dockerfile deleted file mode 100644 index ca2a05f..0000000 --- a/framework/Dockerfile +++ /dev/null @@ -1,21 +0,0 @@ -# syntax=docker/dockerfile:1 -FROM eclipse-temurin:17-jre-alpine - -LABEL maintainer="platform-team" - -ENV TZ=Asia/Shanghai \ - LANG=zh_CN.UTF-8 \ - JAVA_OPTS="-Dfile.encoding=UTF-8" \ - SPRING_PROFILES_ACTIVE=dev - -RUN apk add --no-cache tzdata && \ - ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone - -WORKDIR /app - -# 注意：在构建镜像前先执行 `mvn -DskipTests package` 生成 WAR -COPY target/platform-1.0.war /app/app.war - -EXPOSE 8093 - -ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar /app/app.war --spring.profiles.active=$SPRING_PROFILES_ACTIVE"] \ No newline at end of file diff --git a/git管理方案.md b/git管理方案.md deleted file mode 100644 index a92eb35..0000000 --- a/git管理方案.md +++ /dev/null @@ -1,408 +0,0 @@ -# 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 - - - framework - business-css - - - - - - 21 - 3.x - 3.5.6 - -``` - -### Framework 模块 POM（示例） -```xml -com.yfd.platform -platform-framework -1.0.0 -jar - - - - org.springframework.boot - spring-boot-starter-web - - - com.baomidou - mybatis-plus-boot-starter - ${mybatis-plus.version} - - -``` - -### Business-App 模块 POM（示例） -```xml - - com.yfd.platform - platform-parent - 1.0.0 - - -platform-business-css -war - - - - com.yfd.platform - platform-framework - ${project.version} - - - - - -``` - -### 前端工程（建议） -- `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--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 模板与自动化检查清单。 \ No newline at end of file