cli modular refactor (#16)

* add logic to support SENTRY_PROPERTIES parameter * remove update.json and meta.json files in ppk * udpapte * refactor modles * update * add package-module file * update * update readme file * modifu cli.json file * fix command issues * improve version workflow logic * udpate * update * update * update * udpate * udpate * add example * update readme file * udpate version * change logic to use pushy command uniformly
2025-11-22 16:26:10 +08:00 · 2025-07-24 11:46:20 +08:00
parent 4cb5f7fa4e
commit e98bcf504f
53 changed files with 10853 additions and 855 deletions
--- a/example/README.zh-CN.md
+++ b/example/README.zh-CN.md
@@ -0,0 +1,374 @@
+# 自定义模块和工作流示例
+
+这个目录包含了 React Native Update CLI 自定义模块和工作流的完整示例，演示如何扩展 CLI 的功能。
+
+## 📁 目录结构
+
+```
+example/
+├── modules/                    # 自定义模块示例
+│   ├── custom-deploy-module.ts # 自定义部署模块
+│   └── analytics-module.ts     # 分析统计模块
+├── workflows/                  # 自定义工作流示例
+│   └── custom-workflows.ts     # 复杂工作流集合
+├── scripts/                    # 执行脚本示例
+│   ├── register-modules.ts     # 模块注册和执行
+│   ├── provider-api-example.ts # Provider API 使用示例
+│   └── workflow-demo.ts        # 工作流演示脚本
+└── README.md                   # 本文档
+```
+
+## 🚀 快速开始
+
+### 1. 运行模块注册和执行示例
+
+```bash
+# 编译TypeScript (如果需要)
+npm run build
+
+# 运行模块示例
+npx ts-node example/scripts/register-modules.ts
+```
+
+### 2. 运行Provider API示例
+
+```bash
+npx ts-node example/scripts/provider-api-example.ts
+```
+
+### 3. 运行工作流演示
+
+```bash
+# 运行所有工作流演示
+npx ts-node example/scripts/workflow-demo.ts
+
+# 交互式执行特定工作流
+npx ts-node example/scripts/workflow-demo.ts interactive canary-deployment --version 1.0.0 --initialRollout 5
+
+# 多环境部署工作流
+npx ts-node example/scripts/workflow-demo.ts interactive multi-env-deploy --version 1.0.0
+
+# 回滚工作流
+npx ts-node example/scripts/workflow-demo.ts interactive rollback-workflow --targetVersion 0.9.5
+```
+
+## 📦 自定义模块示例
+
+### 1. 自定义部署模块 (`custom-deploy-module.ts`)
+
+这个模块演示了如何创建一个完整的部署管理模块，包含：
+
+#### 命令：
+- `deploy-dev`: 部署到开发环境
+- `deploy-prod`: 部署到生产环境  
+- `rollback`: 回滚到指定版本
+
+#### 工作流：
+- `full-deploy`: 完整部署流程（开发 → 测试 → 生产）
+- `hotfix-deploy`: 热修复快速部署流程
+
+#### 使用示例：
+```typescript
+import { moduleManager } from 'react-native-update-cli';
+import { customDeployModule } from './modules/custom-deploy-module';
+
+// 注册模块
+moduleManager.registerModule(customDeployModule);
+
+// 执行开发部署
+await moduleManager.executeCommand('deploy-dev', {
+  args: [],
+  options: { platform: 'ios', force: true }
+});
+
+// 执行完整部署工作流
+await moduleManager.executeWorkflow('full-deploy', {
+  args: [],
+  options: { version: '1.2.3' }
+});
+```
+
+### 2. 分析统计模块 (`analytics-module.ts`)
+
+演示如何创建分析和统计功能：
+
+#### 命令：
+- `track-deployment`: 记录部署统计信息
+- `deployment-report`: 生成部署报告
+
+#### 工作流：
+- `deploy-with-analytics`: 带统计的部署流程
+
+## 🔄 自定义工作流示例
+
+### 1. 灰度发布工作流 (`canary-deployment`)
+
+实现完整的灰度发布流程：
+
+- ✅ 准备灰度发布环境
+- ✅ 初始小范围部署
+- ✅ 监控关键指标
+- ✅ 基于指标自动扩大发布范围
+- ✅ 最终验证
+
+```typescript
+await moduleManager.executeWorkflow('canary-deployment', {
+  args: [],
+  options: {
+    version: '2.1.0',
+    initialRollout: 10,    // 初始10%用户
+    autoExpand: true       // 自动扩大范围
+  }
+});
+```
+
+### 2. 多环境发布工作流 (`multi-env-deploy`)
+
+实现标准的多环境发布流程：
+
+- ✅ 部署到开发环境
+- ✅ 运行集成测试
+- ✅ 部署到预发布环境
+- ✅ 运行端到端测试
+- ✅ 部署到生产环境
+- ✅ 部署后验证
+
+```typescript
+await moduleManager.executeWorkflow('multi-env-deploy', {
+  args: [],
+  options: {
+    version: '2.1.0',
+    skipProduction: false,     // 不跳过生产部署
+    forceProduction: false     // 测试失败时不强制部署
+  }
+});
+```
+
+### 3. 回滚工作流 (`rollback-workflow`)
+
+安全的应用回滚流程：
+
+- ✅ 验证目标版本
+- ✅ 备份当前状态
+- ✅ 执行回滚操作
+- ✅ 验证回滚结果
+- ✅ 通知相关人员
+
+```typescript
+await moduleManager.executeWorkflow('rollback-workflow', {
+  args: [],
+  options: {
+    targetVersion: '2.0.5',
+    skipVerification: false
+  }
+});
+```
+
+## 🛠️ Provider API 使用示例
+
+Provider API 提供了编程式接口，适合在应用程序中集成：
+
+### 基本使用
+
+```typescript
+import { moduleManager } from 'react-native-update-cli';
+
+const provider = moduleManager.getProvider();
+
+// 打包应用
+const bundleResult = await provider.bundle({
+  platform: 'ios',
+  dev: false,
+  sourcemap: true
+});
+
+// 发布版本
+const publishResult = await provider.publish({
+  name: 'v1.0.0',
+  description: 'Bug fixes',
+  rollout: 100
+});
+
+// 上传文件
+const uploadResult = await provider.upload({
+  filePath: 'app.ipa',
+  platform: 'ios'
+});
+```
+
+### 应用管理
+
+```typescript
+// 创建应用
+await provider.createApp('MyApp', 'ios');
+
+// 获取当前应用
+const { appId, platform } = await provider.getSelectedApp('ios');
+
+// 列出版本
+const versions = await provider.listVersions(appId);
+
+// 更新版本
+await provider.updateVersion(appId, versionId, {
+  name: 'v1.1.0',
+  description: 'New features'
+});
+```
+
+### 自动化服务类
+
+```typescript
+class DeploymentService {
+  private provider = moduleManager.getProvider();
+  
+  async buildAndPublish(platform: Platform, version: string) {
+    // 1. 打包
+    const bundleResult = await this.provider.bundle({
+      platform, dev: false, sourcemap: true
+    });
+    
+    // 2. 发布
+    const publishResult = await this.provider.publish({
+      name: version, rollout: 100
+    });
+    
+    return { bundleResult, publishResult };
+  }
+}
+```
+
+## 🎯 高级特性
+
+### 1. 工作流验证
+
+```typescript
+const workflow: CustomWorkflow = {
+  name: 'my-workflow',
+  steps: [...],
+  validate: (context) => {
+    if (!context.options.version) {
+      console.error('必须指定版本号');
+      return false;
+    }
+    return true;
+  }
+};
+```
+
+### 2. 条件执行
+
+```typescript
+const step: WorkflowStep = {
+  name: 'conditional-step',
+  execute: async (context) => { /* ... */ },
+  condition: (context) => {
+    return context.options.environment === 'production';
+  }
+};
+```
+
+### 3. 错误处理
+
+```typescript
+try {
+  const result = await moduleManager.executeCommand('deploy-prod', {
+    args: [],
+    options: {} // 缺少必需参数
+  });
+} catch (error) {
+  console.error('执行失败:', error.message);
+}
+```
+
+### 4. 自定义工作流注册
+
+```typescript
+const provider = moduleManager.getProvider();
+
+provider.registerWorkflow({
+  name: 'custom-workflow',
+  description: '自定义工作流',
+  steps: [
+    {
+      name: 'step1',
+      execute: async (context, previousResult) => {
+        // 执行逻辑
+        return { step1: 'completed' };
+      }
+    }
+  ]
+});
+
+// 执行工作流
+await provider.executeWorkflow('custom-workflow', {
+  args: [],
+  options: {}
+});
+```
+
+## 📝 最佳实践
+
+### 1. 模块设计
+
+- **单一职责**: 每个模块专注于特定功能领域
+- **清晰命名**: 使用描述性的命令和选项名称
+- **完整文档**: 为所有命令和选项提供描述
+- **错误处理**: 提供清晰的错误信息和恢复建议
+
+### 2. 工作流设计
+
+- **原子操作**: 每个步骤应该是原子的，可独立执行
+- **状态传递**: 合理使用 previousResult 传递状态
+- **错误恢复**: 考虑失败时的清理和恢复机制
+- **进度反馈**: 提供清晰的进度信息给用户
+
+### 3. 开发建议
+
+- **类型安全**: 充分利用 TypeScript 类型系统
+- **测试覆盖**: 为自定义模块编写测试
+- **文档维护**: 保持示例和文档的同步更新
+- **版本管理**: 为模块设置合适的版本号
+
+## 🐛 故障排除
+
+### 常见问题
+
+1. **模块注册失败**
+   ```typescript
+   // 确保模块符合 CLIModule 接口
+   const module: CLIModule = {
+     name: 'my-module',
+     version: '1.0.0',
+     commands: [...],
+     workflows: [...]
+   };
+   ```
+
+2. **命令执行失败**
+   ```typescript
+   // 检查命令名称和参数
+   await moduleManager.executeCommand('correct-command-name', {
+     args: [],
+     options: { requiredParam: 'value' }
+   });
+   ```
+
+3. **工作流验证失败**
+   ```typescript
+   // 确保提供所有必需的选项
+   await moduleManager.executeWorkflow('workflow-name', {
+     args: [],
+     options: { version: '1.0.0' } // 必需参数
+   });
+   ```
+
+## 📖 相关文档
+
+- [主项目 README](../README.md)
+- [模块化架构文档](../docs/architecture.md)
+- [API 参考文档](../docs/api-reference.md)
+- [贡献指南](../CONTRIBUTING.md)
+
+## 🤝 贡献
+
+欢迎提交更多示例和改进建议！请查看主项目的贡献指南。