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

这个目录用于提供框架升级 CLI，以及定义 CI/CD 生成框架 ZIP 时应遵守的包结构。推荐模式是：开发人员安装 CLI，然后执行命令时输入框架 ZIP 路径和业务项目根目录。业务项目根目录就是待更新位置，CLI 会在这个目录下查找 frontend 和 backend/server。

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

这里有两个不同产物：

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

npm install -g .
micro-gen upgrade --zip ./micro-framework-0.2.1.zip --project ../demo
micro-gen init --zip ./micro-framework-0.2.1.zip --project ../demo
micro-gen arch --project ../demo --architecture microservice
micro-gen upgrade --zip ./micro-framework-0.2.1.zip --project ../demo --dry-run

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

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

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

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

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

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

ZIP 推荐结构

micro-framework-0.2.1.zip
├── manifest.json
├── payload/
│   ├── init/
│   │   ├── frontend/
│   │   └── backend/
│   ├── frontend/
│   │   └── src/
│   │       ├── components/permission/
│   │       ├── contexts/PermissionContext.jsx
│   │       └── PermissionCenter/
│   └── backend/
│       └── ...
└── docs/

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

更新原则

1. 前端不能整目录覆盖业务工程，只能更新 manifest.json 中声明的框架文件。
2. frontend/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 必须是业务项目根目录，且能找到 frontend/package.json 和 backend 或 server 下的 Maven pom.xml；init 支持空目录初始化。
8. init 检测到目标业务项目目录已有内容时，交互模式会提示是否完全覆盖初始化；默认保留已有文件，只有选择完全覆盖或传入 --force-init 才覆盖冲突文件。

初始化和升级的差异

• micro-gen init --zip <zip> --project <dir>：适合新项目。若 ZIP 提供 payload/init，脚本会先复制前端 package.json、vite.config.js、后端 pom.xml、src/main/java、src/main/resources 等基础工程模板，再执行框架文件更新、package.json 合并和 Maven 版本更新。目标目录已有内容时默认跳过冲突文件，需要完全覆盖时使用 --force-init。
• micro-gen upgrade --zip <zip> --project <dir>：适合老项目。只按 manifest 更新框架白名单文件和版本，不覆盖业务资源。
• micro-gen arch --project <dir> --architecture <type>：切换已初始化项目的单体/微服务架构，不需要 ZIP。执行前会校验项目下已存在前端 package.json 和后端 pom.xml。兼容旧写法 micro-gen architecture ...。
• micro-gen upgrade --zip <zip> --project <dir> --dry-run：只打印将要执行的动作，不写入文件。

CLI 参数

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

• --zip <file>：框架升级 ZIP 包路径。
• --project <dir>：业务项目根目录，即待更新位置，默认当前目录。
• --frontend <dir>：前端目录，默认 frontend。
• --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。微服务架构会为后端补充 micro-cloud-starter 和 Nacos 服务发现配置。
• --no-backup：升级时不创建完整项目备份快照。
• --yes：使用默认值，跳过交互确认。

manifest 关键字段

• project.files：允许更新到业务项目根目录的框架文件，例如 AGENTS.md。
• frontend.files：允许覆盖的前端框架文件或目录。
• frontend.files[].modes：限制文件只在指定模式生效，例如 ["init"] 表示只初始化时复制，升级时跳过。
• frontend.blockedTargetGlobs：受保护路径，通常包括图片、静态资源和业务资产。
• frontend.packageMerge：需要合并进业务前端 package.json 的依赖或脚本。
• backend.maven.targetVersion：升级后的框架 Maven parent 版本。
• backend.maven.parentArtifactIds：允许被更新的 parent artifactId 白名单。

维护提醒

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

1. 新增或调整可随框架升级分发的前端框架目录时，同步维护 manifest.json 的 frontend.files。
2. 修改前端依赖或 npm scripts 时，同步维护 manifest.json 的 frontend.packageMerge，保持字段级合并。
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

推荐验证命令：

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

加密框架包

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

明文包结构：

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

加密包结构：

micro-framework-0.2.1.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.1-demo.zip \
  --output framework-package/demo/micro-framework-0.2.1-demo.enc.zip \
  --key <固定密钥>

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

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

使用加密包升级时：

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

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

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

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

CI/CD 打包建议

CI/CD 不应该把完整业务前端直接放进 payload/frontend。推荐只放框架拥有的目录，例如权限中心、公共鉴权组件、框架 Layout、请求封装等。业务页面、业务路由、图片、logo、主题资源应由业务项目维护。

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