Luckyun Micro 框架升级 CLI 与 ZIP 包设计

这个目录用于提供框架初始化、升级和服务架构切换 CLI，以及定义 CI/CD 生成框架 ZIP 时应遵守的包结构。初始化和升级会处理前后端框架；架构切换只依据 Maven POM 判断，不依赖固定的 frontend、backend 或 server 目录结构。

业务开发人员使用说明见：CLI命令使用说明.md。

这里有两个不同产物：

• CLI 工具包：framework-package/ 本身，提供 micro-gen 命令。不能发布到 npm 市场时，可以把这个目录作为内部工具包分发，开发人员执行 npm install -g <framework-package目录> 安装。
• 框架升级 ZIP：CI/CD 生成并内部下载的框架内容包，例如 micro-framework-0.2.4.zip。它不是 npm publish 包，内部包含 manifest.json 和 payload/，供 CLI 执行升级。

npm install -g .
micro-gen upgrade --zip ./micro-framework-0.2.4.zip --project ../demo
micro-gen init --zip ./micro-framework-0.2.4.zip --project ../demo --frontend-type react
micro-gen init --zip ./micro-framework-0.2.4.zip --project ../demo-vue --frontend-type vue
micro-gen arch --project ../demo --architecture microservice
micro-gen upgrade --zip ./micro-framework-0.2.4.zip --project ../demo --dry-run

也可以直接执行 micro-gen upgrade，再按提示输入 ZIP 路径和业务项目根目录。

如果不希望全局安装，也可以在 CLI 目录直接执行：

npx . upgrade --zip ./micro-framework-0.2.4.zip --project ../demo
npm run micro -- upgrade --zip ./micro-framework-0.2.4.zip --project ../demo

package.json 已配置 bin，通过 npm 安装后会自动生成跨平台命令入口：

• Windows：生成 micro-gen.cmd。
• macOS/Linux：使用 #!/usr/bin/env node 执行。

兼容说明：luckyun-micro 是历史命令兼容别名，新项目和新文档统一使用 micro-gen。

跨平台要求

• Windows、Linux、macOS 均使用 Node.js 18 或更高版本运行，不依赖 Bash 执行 CLI。
• Windows 下 npm 会生成 micro-gen.cmd；CLI 可直接调用 mvn.cmd、.bat 或 Maven 安装目录。
• ZIP 解压会按平台自动尝试 PowerShell 7、Windows PowerShell、unzip、bsdtar、tar、jar、7z 中可用的工具；部署到精简 Linux 镜像时至少保留其中一种。
• 所有项目路径、ZIP 路径和 Maven 路径都通过 Node path API 处理，支持 Windows 盘符、反斜杠和包含空格的路径。

ZIP 推荐结构

micro-framework-0.2.4.zip
├── manifest.json
├── payload/
│   ├── init/
│   │   └── backend/
│   │       ├── AGENTS.md
│   │       └── ...
│   ├── frontend/
│   │   ├── react/
│   │   │   ├── apps/
│   │   │   ├── packages/
│   │   │   └── scripts/
│   │   └── vue/
│   │       ├── apps/
│   │       ├── packages/
│   │       └── scripts/
└── docs/

框架升级 ZIP 支持明文包和加密包两种形态。内部测试可使用明文包；如果存在外传风险，CI/CD 应输出加密包。

更新原则

1. 前端不能整目录覆盖业务工程，只能更新 manifest.json 中声明的框架文件。
2. 前端根目录及 workspace 的 package.json 只能做字段级合并，默认只合并 dependencies、devDependencies、scripts。
3. src/assets/**、public/**、src/**/assets/** 默认受保护，不允许通过框架包覆盖；框架运行必需的基础资源可在 manifest 单项配置 allowBlocked: true 和 modes: ["init"] 后仅初始化时复制。
4. 后端升级默认优先识别业务项目根目录下的 backend，找不到时兼容 server，然后扫描其中的 pom.xml 更新指定 parent 的 Maven 版本。
5. upgrade 正式写入前默认完整备份业务项目根目录到 .micro-framework-backup/YYYY-MM-DD_HH-mm-ss/，但会排除 .micro-framework-backup 自身、任意层级的 node_modules 和 dist，以及后端目录下的 target，避免备份构建产物和依赖目录。
6. CLI 会先检查 ZIP 是否存在、是否为 .zip、文件签名是否有效、解压后是否存在 manifest.json，并校验 manifest 声明的 payload 是否真实存在。
7. upgrade 会校验 --project 必须是业务项目根目录，且能找到前端 package.json 和后端 Maven pom.xml；init 支持空目录初始化并选择 React/Vue。
8. arch 不校验前端，也不绑定后端目录名；项目根目录或其子目录中层级最浅的服务 POM，只要 parent artifactId 是 com-luckyun-micro-parent 即支持切换，父版本在切换前后保持不变。
9. init 检测到目标业务项目目录已有内容时，交互模式会提示是否完全覆盖初始化；默认保留已有文件，只有选择完全覆盖或传入 --force-init 才覆盖冲突文件。

初始化和升级的差异

• micro-gen init --zip <zip> --project <dir>：适合新项目。脚本先复制 payload/init 中的后端基础工程，并将框架仓库的 backend/AGENTS.md 初始化到业务后端目录；业务项目根目录的 AGENTS.md 属于受保护文件，即使旧 ZIP 包含该文件或在 project.files 中声明，也不会创建或覆盖。随后按 --frontend-type 初始化 React/Vue 白名单文件，最后执行 package.json 字段合并和 Maven 版本更新。目标目录已有内容时默认跳过冲突文件，需要完全覆盖时使用 --force-init。
• micro-gen upgrade --zip <zip> --project <dir>：适合老项目。只按 manifest 更新框架白名单文件和版本，不覆盖业务资源。
• micro-gen arch --project <dir> --architecture <type>：切换单体/微服务架构，不需要 ZIP，不校验前端或固定目录；按 com-luckyun-micro-parent 识别服务 POM。兼容旧写法 micro-gen architecture ...。
• micro-gen upgrade --zip <zip> --project <dir> --dry-run：只打印将要执行的动作，不写入文件。

CLI 参数

micro-gen upgrade --zip ./micro-framework-0.2.4.zip --project ../demo --dry-run
micro-gen init --zip D:\packages\micro-framework-0.2.4.zip --project D:\work\demo
micro-gen init --zip D:\packages\micro-framework-0.2.4.zip --project D:\work\demo-vue --frontend-type vue
micro-gen upgrade --zip ./micro-framework-0.2.4.zip --project ../demo --frontend web --backend backend --yes

• --zip <file>：框架升级 ZIP 包路径。
• --project <dir>：业务项目根目录，即待更新位置，默认当前目录。
• --frontend <dir>：前端目录，默认 frontend。
• --frontend-type <type>：前端技术栈，支持 react 和 vue。交互初始化时选择；--yes 未指定时默认 react。升级时默认按现有 package.json 自动识别。
• --backend <dir>：后端目录；不传时自动识别 backend 或 server。
• --server <dir>：兼容旧参数，等同 --backend。
• --dry-run：只预览，不写入文件。
• -d, --detail：展示文件级明细；默认只输出 add/edit/delete/skip 汇总。
• --maven <cmd/path>：指定 Maven 安装根目录或 mvn/mvn.cmd 完整路径；不要填写 settings.xml。init 正式写入后默认自动执行 mvn compile。
• --maven-settings <file>：指定 Maven settings.xml。
• --skip-compile：初始化完成后跳过后端 Maven 编译；不影响前端依赖自动安装。
• --force-init：init 时完全覆盖已有初始化文件和框架白名单文件；默认保留已有文件。
• --architecture <type>：初始化架构类型，支持 monolith 和 microservice；默认 monolith。单体后端只默认依赖 com-luckyun-micro-base；微服务后端额外依赖 micro-cloud-starter 并补充 Nacos 服务发现配置。com-luckyun-micro-workflow 始终默认注释。

初始化正式写入后，CLI 会先尝试执行后端 mvn compile；未找到 Maven 时会提示开发人员进入后端目录自行构建。随后在前端目录执行 pnpm install；未找到 pnpm 时使用 npm 执行 npm install -g pnpm 后继续安装，pnpm 与 npm 都不可用时提示开发人员自行安装依赖和构建。React/Vue 的 /api 默认代理到后端 http://localhost:38080，前端开发服务器仍使用 5173/5174，避免与后端端口冲突。

• --no-backup：升级时不创建完整项目备份快照。
• --yes：使用默认值，跳过交互确认。

manifest 关键字段

• init.template：初始化基础模板；后端开发规范固定写入业务项目的 backend/AGENTS.md，不在业务项目根目录创建框架仓库级 AGENTS.md。
• frontend.variants.react/vue：两套前端框架的独立源码目录、升级白名单和 package 合并目标。
• frontend.variants.*.files：允许覆盖的前端框架文件或目录；modes 和 strategy 分别限制执行模式与覆盖策略。
• frontend.blockedTargetGlobs：受保护路径，通常包括图片、静态资源和业务资产。
• frontend.variants.*.packageMergeTargets：声明需要字段级合并的 package.json。打包脚本从当前 React/Vue 源码提取 dependencies、devDependencies、scripts 写入 ZIP manifest，避免版本漂移。CLI 仍兼容旧版 frontend.packageMerge/packageMerges。
• backend.maven.targetVersion：升级后的框架 Maven parent 版本。
• backend.maven.parentArtifactIds：允许被更新的 parent artifactId 白名单。

维护提醒

修改框架代码时不要只改业务源码，需要同步检查升级包清单：

1. 新增或调整可随框架升级分发的前端框架目录时，同步维护对应 frontend.variants.react/vue.files。
2. 新增需要合并的 workspace package.json 时，同步维护对应 packageMergeTargets；已有目标的依赖和 scripts 会在打包时自动读取当前源码。
3. 修改后端 Maven parent 或框架版本时，同步维护 manifest.json 的 backend.maven.targetVersion。
4. 不要把业务图片、Logo、上传资源或其他静态资产加入覆盖清单；src/assets/**、public/**、src/**/assets/** 默认受保护。
5. 修改 manifest.json 或 bin/micro-framework.js 后，重新生成或校验 demo/micro-framework-*-demo.zip。

重新生成 demo 包：

npm --prefix framework-package run build:demo

macOS/Linux 可使用交互式 Shell 脚本生成正式升级包：

./framework-package/scripts/build-upgrade-package.sh

脚本会依次询问版本号、输出目录和是否加密。默认输出目录为 framework-package/release：

• 明文包：micro-framework-{version}-plain.zip。
• 加密包：micro-framework-{version}.zip。
• 输入的版本号只写入本次升级包内的 frameworkVersion 和 backend.maven.targetVersion，不会修改仓库中的 manifest.json。

跨平台构建使用 npm 命令。加密包通过 LUCKYUN_MICRO_KEY 提供密钥：

# macOS/Linux
LUCKYUN_MICRO_KEY='your-key' npm --prefix framework-package run build:upgrade

# Windows PowerShell
$env:LUCKYUN_MICRO_KEY='your-key'
npm --prefix framework-package run build:upgrade

该 npm 命令不依赖 Bash，Windows、Linux、macOS 均可执行；版本和输出目录默认读取 manifest.json，如需自定义可直接执行 node framework-package/scripts/build-demo-package.js --release --version <version> --output-dir <dir>。

推荐验证命令：

node framework-package/bin/micro-framework.js upgrade \
  --zip framework-package/demo/micro-framework-0.2.4-demo.zip \
  --project . \
  --dry-run \
  --yes

加密框架包

如果框架升级 ZIP 可能被带到外部，CI/CD 应输出加密包。CLI 同时兼容明文包和加密包：

明文包结构：

micro-framework-0.2.4-plain.zip
├── manifest.json
├── payload/
└── docs/

加密包结构：

micro-framework-0.2.4.zip
├── package.meta.json
└── package.enc

package.enc 内部加密的是完整明文包 ZIP。package.meta.json 只包含算法、salt、iv、authTag 和明文包 sha256，不包含 manifest 和 payload 结构。

加密算法约定：

• algorithm：aes-256-gcm
• kdf：scrypt
• key length：32
• salt：16 bytes
• iv：12 bytes
• authTag：GCM 认证标签

生成加密包示例：

node framework-package/scripts/encrypt-package.js \
  --input framework-package/demo/micro-framework-0.2.4-demo.zip \
  --output framework-package/demo/micro-framework-0.2.4-demo.enc.zip \
  --key <固定密钥>

也可以用环境变量传密钥：

LUCKYUN_MICRO_KEY=<固定密钥> node framework-package/scripts/encrypt-package.js \
  --input framework-package/demo/micro-framework-0.2.4-demo.zip \
  --output framework-package/demo/micro-framework-0.2.4-demo.enc.zip

使用加密包升级时：

micro-gen upgrade \
  --zip ./micro-framework-0.2.4-demo.enc.zip \
  --project ./business-project

CLI 会提示输入解密密钥。也可以非交互传入：

LUCKYUN_MICRO_KEY=<固定密钥> micro-gen upgrade \
  --zip ./micro-framework-0.2.4-demo.enc.zip \
  --project ./business-project \
  --dry-run \
  --yes

注意：固定密钥不要写进 CLI 源码或提交到仓库。当前方案用于避免 ZIP 泄露后直接暴露框架结构和源码；由于解密发生在开发人员本机，它不是绝对保密方案。

CI/CD 打包建议

CI/CD 不应该无清单地复制前端目录。当前打包脚本分别从 frontend-react、frontend-vue 读取 frontend.variants.*.files 白名单，并输出到 payload/frontend/react|vue；图片、logo、上传资源等受保护路径默认只在初始化时按明确白名单复制。

如果 CI/CD 输出加密框架包，必须和 CLI 保持相同的 package.meta.json + package.enc 格式和上述加密算法。推荐 CI/CD 直接调用 framework-package/scripts/encrypt-package.js，减少算法不一致风险。