Monorepo 改造与 CI/CD 改进 - 同步到上游仓库

[gungunj]

📋 变更概览

本 PR 将 fork 仓库中的 Monorepo 改造 和 CI/CD 改进 同步到上游仓库 vusion/cloud-ui-materials，主要包括：

• ✅ Monorepo 架构改造：从扁平结构迁移到 workspaces 组织
• ✅ 引入 Turborepo：统一构建管道，提升构建效率
• ✅ 引入 pnpm workspace：优化依赖管理
• ✅ 新增自动生成 PR 描述功能
• ✅ 增强发布工作流，支持 PR 合并后自动构建
• ✅ 重构 scripts 目录结构，提升代码组织性

🏗️ Monorepo 架构改造

1. 目录结构重构

从扁平结构迁移到 workspaces 组织：

旧结构 (packages/):
packages/
├── cw/
│   ├── cw_amap/
│   ├── cw_countup/
│   └── ...
├── cust/
└── lcap/

新结构 (workspaces/):
workspaces/
├── legacy-yaml/          # 基于 YAML 配置的组件（Vue 2）
│   └── packages/
│       ├── cw/
│       ├── cust/
│       └── lcap/
├── ts-vue2/              # TypeScript + Vue 2 组件
│   └── packages/
├── ts-vue3/              # TypeScript + Vue 3 组件
│   └── packages/
├── ts-react/             # TypeScript + React 组件
│   └── packages/
└── ts-unknown/           # TypeScript 其他类型组件
    └── packages/

迁移详情：

• 将 packages/ 下的组件迁移到 workspaces/legacy-yaml/packages/
• 部分组件迁移到 workspaces/ts-vue2/packages/（TypeScript 化）
• 按技术栈分类组织，便于管理和维护

2. 引入 Turborepo

文件: turbo.json (新增)

功能: 统一构建管道，支持增量构建和并行执行

特性:

• 增量构建：仅构建变更的组件及其依赖
• 并行执行：充分利用多核 CPU
• 构建缓存：加速重复构建
• 任务管道：定义清晰的构建依赖关系

配置示例:

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    }
  }
}

3. 引入 pnpm Workspace

文件: pnpm-workspace.yaml (新增)

功能: 优化依赖管理，支持工作区依赖共享

配置:

packages:
  - "workspaces/legacy-yaml/packages/*/*"
  - "workspaces/ts-vue2/packages/*/*"
  - "workspaces/ts-vue3/packages/*/*"
  - "workspaces/ts-react/packages/*/*"
  - "workspaces/ts-unknown/packages/*/*"

优势:

• 依赖去重：相同依赖只安装一次
• 快速安装：pnpm 的硬链接机制
• 工作区链接：支持本地包引用

4. 根目录 package.json 更新

主要变更:

• 添加 packageManager: "[email protected]"
• 添加 Turborepo 相关脚本
• 添加 postinstall 钩子，自动安装所有工作区依赖
• 配置 pnpm overrides，统一依赖版本

新增脚本:

{
  "build": "turbo run build --parallel",
  "postinstall": "node scripts/mono/install-all-workspaces.mjs",
  "install:workspaces": "node scripts/mono/install-all-workspaces.mjs --verbose"
}

🎯 CI/CD 改进内容

1. 新增 PR 描述自动生成工作流

文件: .github/workflows/pr-description.yml (新增)

功能: 在 PR 创建或更新时自动生成详细的 PR 描述

特性:

• 自动收集 commit 信息（支持 26+ commits）
• 检测变更的组件包（支持 100+ 组件）
• 生成格式化的变更说明
• 自动更新 PR body，包含变更概览、组件详情和提交记录

2. 增强发布工作流

文件: .github/workflows/release.yml

主要改进:

• ✅ 支持 PR 合并后自动触发构建
• ✅ 改进变更检测逻辑（支持 PR 和 Push 事件）
• ✅ 优化构建矩阵生成，解决 GitHub Actions 256 矩阵限制
• ✅ 增强错误处理和日志输出
• ✅ 支持手动触发和测试模式
• ✅ 自动生成 CHANGELOG、创建 Git Tags 和 GitHub Release
• ✅ 适配新的 workspaces 目录结构

3. 重构 Scripts 目录结构

新增目录结构:

scripts/
├── ci/              # CI/CD 相关脚本（GitHub Actions 使用）
│   ├── build-and-package.mjs
│   ├── generate-pr-body.mjs
│   ├── generate-diff-docs.mjs
│   ├── generate-changelog.mjs
│   ├── create-tags.mjs
│   ├── create-release.js
│   └── ...
├── mono/            # Monorepo 管理脚本
│   ├── install-all-workspaces.mjs  # 安装所有工作区依赖
│   ├── clean-all.mjs                # 清理所有构建产物
│   └── migrate-components.mjs        # 组件迁移工具
├── utils/           # 公共工具函数
│   ├── git.js       # Git 操作工具（ESM）
│   └── fs.js        # 文件系统操作工具（ESM）
└── legacy/          # 已废弃的旧脚本
    └── changelog.js

新增工具函数:

• scripts/utils/git.js - Git 操作工具（统一封装）
• scripts/utils/fs.js - 文件系统操作工具（统一封装）

4. 新增 CI 脚本功能

脚本文件	功能说明
generate-pr-body.mjs	生成 PR 描述，包含 commit 信息和组件变更
generate-diff-docs.mjs	生成差异文档，支持 AI 辅助更新
generate-changelog.mjs	自动生成 CHANGELOG.md
create-tags.mjs	创建 Git Tags，支持语义化版本
create-release.js	创建或更新 GitHub Release
build-and-package.mjs	构建和打包组件，生成 zip 文件
plan-changed-packages.mjs	检测变更的包，生成构建矩阵（适配 workspaces）
install-all-workspaces.mjs	安装所有工作区依赖

📊 变更统计

总体变更

• 文件变更: 2,858 个文件
• 新增代码: 73,742 行
• 删除代码: 61,395 行

Monorepo 改造相关

新增文件:

• turbo.json - Turborepo 配置
• pnpm-workspace.yaml - pnpm workspace 配置
• .npmrc - npm/pnpm 配置
• workspaces/ 目录结构（包含所有迁移的组件）

修改文件:

• package.json - 添加 Turborepo 和 pnpm workspace 支持
• .gitignore - 更新忽略规则

迁移的组件:

• 从 packages/ 迁移到 workspaces/legacy-yaml/packages/
• 部分组件迁移到 workspaces/ts-vue2/packages/
• 删除了一些旧的组件文件（已迁移）

CI/CD 相关文件变更

新增文件 (18 个):

• .github/workflows/pr-description.yml
• scripts/README.md
• scripts/ci/build-and-package.mjs
• scripts/ci/call-coreagent.mjs
• scripts/ci/configure-turbo.mjs
• scripts/ci/create-release.js
• scripts/ci/create-tags.mjs
• scripts/ci/generate-changelog.mjs
• scripts/ci/generate-diff-docs.mjs
• scripts/ci/generate-pr-body.mjs
• scripts/ci/setup-dependencies.mjs
• scripts/legacy/README.md
• scripts/legacy/changelog.js
• scripts/mono/clean-all.mjs
• scripts/mono/install-all-workspaces.mjs
• scripts/mono/migrate-components.mjs
• scripts/utils/fs.js
• scripts/utils/git.js

修改文件 (2 个):

• .github/workflows/release.yml (大幅改进，适配 workspaces)
• scripts/ci/plan-changed-packages.mjs (增强功能，支持 workspaces 检测)

🔍 技术亮点

Monorepo 架构优势

1. 模块化组织: 按技术栈分类，便于管理和维护
2. 依赖优化: pnpm workspace 实现依赖去重和快速安装
3. 构建加速: Turborepo 支持增量构建和并行执行
4. 版本管理: 统一管理所有组件的版本和依赖

CI/CD 改进优势

1. 增量构建: 仅构建被修改的组件及其依赖
2. 智能检测: 支持 PR 和 Push 事件的变更检测，适配 workspaces 结构
3. 批量处理: 解决 GitHub Actions 矩阵限制，支持大量组件并行构建
4. 错误恢复: 增强的错误处理，单个组件失败不影响其他组件
5. 自动化: 从 PR 创建到 Release 发布的完整自动化流程

🧪 测试建议

Monorepo 功能测试

1. 验证 pnpm workspace 安装：

   pnpm install

2. 验证 Turborepo 构建：

   pnpm build

3. 验证增量构建：

   • 修改单个组件
   • 运行 pnpm build
   • 确认只构建变更的组件

CI/CD 功能测试

1. 创建测试 PR，验证自动生成 PR 描述功能
2. 合并 PR 后，验证自动构建和打包功能
3. 检查生成的 CHANGELOG 和 Git Tags
4. 验证 GitHub Release 是否正确创建
5. 验证 workspaces 目录下的组件构建是否正常

📝 注意事项

迁移影响

• ⚠️ 目录结构变更: 所有组件从 packages/ 迁移到 workspaces/
• ⚠️ 构建工具变更: 引入 Turborepo，需要更新构建脚本
• ⚠️ 包管理器变更: 推荐使用 pnpm（支持 npm/yarn，但 pnpm 性能更好）

迁移指南

如果上游仓库需要迁移，建议步骤：

1. 备份当前代码
2. 安装 pnpm: npm install -g [email protected]
3. 安装依赖: pnpm install
4. 验证构建: pnpm build
5. 更新 CI/CD: 使用新的 workflows 和 scripts