docs: add CI/CD automated test & release strategy for logic-ide (Spring Boot 2 & 3 compatibility)

自动化测试与发布设计.md

@@ -0,0 +1,178 @@
+# logic-ide 自动化测试与发布设计
+
+## 背景与目标
+- **产品形态**：`logic-ide` 对外作为 SDK，为业务系统提供逻辑编排与运行时能力，需要同时兼容 Spring Boot 2.7.x 与 Spring Boot 3.x。
+- **主要诉求**：在研发提交流程中，当版本号发生变更（例如 `pom.xml` 或 `logic-ide` 模块版本升级）时，自动触发完整的兼容性测试，并在通过所有质量门禁后自动化发布。
+- **期望结果**：缩短发布周期、降低回归漏测风险，确保每次版本迭代都经过双版本 Spring Boot 兼容性验证并生成可追溯的构建产物。
+
+## 流程总览
+```
+开发提交/合并 -> 版本变更检测 -> CI 预检 (PR 检查) -> 主干合并 ->
+版本校验 Job (diff) -> Maven 构建矩阵 (Boot2 / Boot3) -> 集成 & 回归测试 ->
+质量门禁 (覆盖率/安全/制品签名) -> Maven Central / 私服 发布 -> Release Note & Tag ->
+通知 & 反馈闭环
+```
+
+## 触发策略设计
+### 1. Pull Request 阶段
+- **触发条件**：任意针对 `main`/`release-*` 分支的 PR。
+- **目标**：快速反馈编译、单元测试、风格校验问题，避免缺陷进入主干。
+- **测试范围**：
+  - `mvn -pl logic-ide -am -DskipITs test`
+  - 静态检查 (`spotless`, `checkstyle`, `spotbugs`) 按需开关。
+  - 仅校验默认（Spring Boot 2.7）依赖，以缩短反馈周期。
+
+### 2. 版本号变更自动发布
+- **触发条件**：`main` 分支上存在版本号提升的提交。
+- **检测逻辑**：
+  1. 在工作流的初始化 Job 中对比 `HEAD^..HEAD` 修改文件，若涉及 `pom.xml`、`logic-ide/pom.xml` 或 `logic-sdk/pom.xml` 等版本定义文件则继续。
+  2. 使用 `mvn help:evaluate -Dexpression=project.version` 在前后两个 commit 中提取版本，并通过脚本比对是否发生语义化提升。
+  3. 也可追加校验提交信息（如 `release:` 前缀）或标签触发，确保发布动作受控。
+- **手动触发**：保留 `workflow_dispatch` 输入参数（版本号、是否跳过发布）以支持运维介入或热补。
+
+## 测试矩阵与构建策略
+| 维度 | Spring Boot 2.7.x | Spring Boot 3.1.x/3.2.x |
+| --- | --- | --- |
+| JDK | Temurin 17 | Temurin 17/21（按兼容策略） |
+| Maven Profile | `-Pboot2`（或默认 profile） | `-Pboot3`（引入 Spring Boot 3 依赖 BOM） |
+| 构建命令 | `mvn -pl logic-ide -am clean verify -DskipITs=false -Pspring-boot-2` | `mvn -pl logic-ide -am clean verify -DskipITs=false -Pspring-boot-3` |
+| 测试重点 | 历史存量业务场景回归、Bean 兼容性、序列化差异 | Jakarta 命名空间适配、`jakarta.*` 依赖校验、Spring Boot 3 API 变更 |
+
+> **Profile 约定**：在 Maven `logic-ide` 模块中新增 `spring-boot-2` 与 `spring-boot-3` profile，分别引入对应版本 BOM 与差异化依赖（如 `spring-boot-starter-validation` vs `jakarta.validation-api`）。测试命令通过 `-Pspring-boot-{x}` 切换依赖集。
+
+## CI Pipeline 分阶段设计
+1. **Stage 0 – 初始化与版本检测**
+   - Checkout 代码、缓存 `.m2`、安装必要的 JDK。
+   - 运行版本变更检测脚本，决定后续 Job 是否执行发布阶段。
+
+2. **Stage 1 – 静态检查与快速回归**
+   - `mvn -pl logic-ide -am -DskipITs test`
+   - 自定义脚本检查公共 API 是否存在破坏性变更（可选）。
+
+3. **Stage 2 – 兼容性测试矩阵**
+   - 使用 GitHub Actions Matrix 或 Jenkins 并行 Job：
+     ```yaml
+     strategy:
+       matrix:
+         boot-profile: [spring-boot-2, spring-boot-3]
+         java-version: [17]
+     steps:
+       - name: Run compatibility verify
+         run: mvn -pl logic-ide -am clean verify -P${{ matrix.boot-profile }}
+     ```
+   - 可在 `spring-boot-3` 任务中追加迁移用例（如 Jakarta API 覆盖、Context 启动 Smoke Test）。
+
+4. **Stage 3 – 集成 & 回归测试**
+   - 启动 `test-suite` 模块依赖示例，模拟业务系统嵌入逻辑。
+   - 针对关键逻辑编排流程运行端到端测试，确保 `logic-runtime` + `logic-ide` 协同正常。
+   - 如需与外部依赖（Redis、MySQL）联动，可通过 Docker 服务在流水线中启动。
+
+5. **Stage 4 – 质量门禁**
+   - 覆盖率采集并上传至 SonarQube/Codecov。
+   - 依赖漏洞扫描（`mvn org.owasp:dependency-check:check` 或 SCA 工具）。
+   - 产物签名、SBOM 生成（CycloneDX Maven 插件）。
+   - 若任一检测失败，阻断发布流程。
+
+6. **Stage 5 – 发布与验证**
+   - 使用 `mvn -pl logic-ide -am -P<profile> deploy` 发布至 Maven 私服/Nexus。
+   - 根据版本策略发布两套制品：
+     - `logic-ide-${version}-boot2.jar`
+     - `logic-ide-${version}-boot3.jar`（如采用分类器或 profile 区分）。
+   - 自动创建 Git Tag 与 GitHub Release（附带 Release Note、兼容性说明、制品下载链接）。
+   - 通知渠道（钉钉/企业微信/邮件）推送发布成功或失败信息。
+
+## GitHub Actions 样例骨架
+```yaml
+name: logic-ide-release
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'pom.xml'
+      - 'logic-ide/**/pom.xml'
+  workflow_dispatch:
+    inputs:
+      targetVersion:
+        description: '手动发布版本号'
+        required: false
+
+jobs:
+  version-check:
+    runs-on: ubuntu-latest
+    outputs:
+      publish: ${{ steps.diff.outputs.version_changed }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Detect version bump
+        id: diff
+        run: |
+          PREV_VERSION=$(git show HEAD^:pom.xml | mvn -q -N help:evaluate -Dexpression=project.version -DforceStdout)
+          CURR_VERSION=$(mvn -q -N help:evaluate -Dexpression=project.version -DforceStdout)
+          if [ "$PREV_VERSION" != "$CURR_VERSION" ]; then
+            echo "version_changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "version_changed=false" >> "$GITHUB_OUTPUT"
+          fi
+  build-test:
+    needs: version-check
+    if: needs.version-check.outputs.publish == 'true' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        boot-profile: [spring-boot-2, spring-boot-3]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v3
+        with:
+          distribution: temurin
+          java-version: '17'
+      - name: Cache Maven
+        uses: actions/cache@v3
+        with:
+          path: ~/.m2/repository
+          key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
+      - name: Verify ${{ matrix.boot-profile }}
+        run: mvn -pl logic-ide -am clean verify -P${{ matrix.boot-profile }}
+  release:
+    needs: build-test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Publish to Maven Repo
+        run: mvn -pl logic-ide -am deploy -Ppublish -s .github/maven-settings.xml
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: v${{ github.sha }}
+          name: logic-ide v${{ github.sha }} 发布
+          body: '自动发布：兼容 Spring Boot 2 & 3'
+```
+> 上述示例仅展示关键逻辑，实际落地时需拆分 settings、凭证管理与制品分类策略。
+
+## 发布流程与角色职责
+1. **开发**：提交版本变更 PR，确保通过预检流水线。
+2. **Reviewer**：审核代码与版本变更合理性，合并至主干。
+3. **CI/CD 系统**：自动检测版本提升，执行兼容性验证、制品发布、发布记录生成。
+4. **运维/Release Owner**：监控流水线执行结果，如失败及时回滚或重新触发；如成功则更新外部公告。
+
+## 版本管理与回滚策略
+- 采用语义化版本（Major.Minor.Patch）。
+- 流水线在发布前打 `pre-release` Tag，发布成功后升级为正式 Tag；失败则删除 `pre-release` Tag。
+- 引入 `mvn versions:revert` 快速回滚版本号；若制品已发布则通过 Maven Repo 废弃或 Block 该版本，并回滚代码 Tag。
+
+## 安全与合规要求
+- 发布凭证使用 GitHub Encrypted Secrets 或 Jenkins Credentials，最小权限原则管理。
+- 所有制品附带 SBOM 与哈希校验值，保证可追溯性。
+- 引入开源依赖漏洞扫描，发现高危漏洞需阻断发布。
+- 流水线执行日志保存 180 天，支持审计追溯。
+
+## 实施里程碑建议
+1. **阶段一**：引入双 profile 与本地脚本，确保在开发机器可以一键验证两个版本。
+2. **阶段二**：上线 PR 与版本检测流水线，完成自动化兼容性测试。
+3. **阶段三**：接入发布仓库、生成 Release Note、打通通知。
+4. **阶段四（优化）**：引入性能基准测试、Canary 发布、滚动回滚策略等高级能力。
+
+---
+
+通过上述 CI/CD 设计，`logic-ide` 能够在版本迭代时自动覆盖 Spring Boot 2 与 Spring Boot 3 的兼容性验证，并形成标准化的发布流水线，确保对外交付质量与发布效率。