wwjcloud/tools/QUICK-START.md

🚀 工具快速开始指南

📋 核心功能

1. Dry-run 模式 - 预览生成结果，不实际修改文件
2. Quality Gate - 自动化质量检查（TypeScript + ESLint）
3. 模块化生成器 - 12个专用生成器，职责清晰

---

⚡ 快速命令

1. 完整迁移（推荐）

# 正常执行
node tools/migration-coordinator.js

# Dry-run 模式（仅预览）
DRY_RUN=true node tools/migration-coordinator.js

2. 单独运行生成器

# 实体生成器
node tools/generators/entity-generator.js

# 实体生成器 (dry-run)
DRY_RUN=true node tools/generators/entity-generator.js

# 控制器生成器
node tools/generators/controller-generator.js --dry-run

3. 质量检查

# 完整质量检查
node tools/generators/quality-gate.js

# 快速检查（仅核心层）
node tools/generators/quality-gate.js quick

4. 验证修复

# 验证所有修复是否正确
node tools/test-fixes.js

---

🎯 典型工作流

场景1: 首次迁移

# 步骤1: 发现PHP文件
node tools/php-file-discovery.js

# 步骤2: 预览迁移结果（dry-run）
DRY_RUN=true node tools/migration-coordinator.js

# 步骤3: 确认无误后执行实际迁移
node tools/migration-coordinator.js

# 步骤4: 质量检查
node tools/generators/quality-gate.js

场景2: 单独生成某个模块

# 步骤1: 预览实体生成
DRY_RUN=true node tools/generators/entity-generator.js

# 步骤2: 实际生成实体
node tools/generators/entity-generator.js

# 步骤3: 生成控制器
node tools/generators/controller-generator.js

# 步骤4: 生成服务
node tools/generators/service-generator.js

# 步骤5: 生成模块文件
node tools/generators/module-generator.js

场景3: 验证和质量检查

# 验证修复
node tools/test-fixes.js

# 质量检查
node tools/generators/quality-gate.js

# 如果有错误，查看详细输出
VERBOSE=true node tools/generators/quality-gate.js

---

🔧 环境变量

变量	作用	示例
DRY_RUN	启用 dry-run 模式	DRY_RUN=true node tools/...
VERBOSE	详细输出模式	VERBOSE=true node tools/...

---

📁 核心文件

文件	作用	何时使用
migration-coordinator.js	主协调器	完整迁移流程
base-generator.js	基础生成器	被其他生成器继承
quality-gate.js	质量门禁	质量检查
test-fixes.js	验证脚本	验证修复是否正确

---

💡 小技巧

1. 使用 dry-run 避免误操作

始终先用 dry-run 模式预览结果：

DRY_RUN=true node tools/migration-coordinator.js

2. 详细输出帮助调试

遇到问题时启用详细输出：

VERBOSE=true node tools/generators/entity-generator.js

3. 组合使用

# 同时启用 dry-run 和详细输出
DRY_RUN=true VERBOSE=true node tools/migration-coordinator.js

4. 快速质量检查

开发过程中频繁运行快速检查：

node tools/generators/quality-gate.js quick

---

⚠️ 注意事项

1. 首次运行前备份

   • 建议先用 dry-run 模式预览
   • 确认结果正确后再实际执行

2. Quality Gate 可能失败

   • TypeScript 编译错误
   • ESLint 规范问题
   • 可以先生成代码，后续修复

3. 生成器顺序建议

   实体 → 验证器 → 服务 → 控制器 → 模块
   

4. 遇到错误时

   • 查看错误日志
   • 使用 VERBOSE 模式
   • 检查 PHP 源文件是否存在

---

🆘 常见问题

Q: Dry-run 模式不生效？

检查环境变量设置：

# macOS/Linux
DRY_RUN=true node tools/...

# Windows PowerShell
$env:DRY_RUN="true"; node tools/...

# Windows CMD
set DRY_RUN=true && node tools/...

Q: Quality Gate 一直失败？

可能原因：

1. TypeScript 配置问题
2. ESLint 配置问题
3. npm script 未配置

检查 package.json:

{
  "scripts": {
    "type-check": "tsc --noEmit",
    "lint": "eslint src --ext .ts"
  }
}

Q: 生成的文件不符合预期？

1. 检查 PHP 源文件是否存在
2. 使用 VERBOSE 模式查看详细日志
3. 检查 php-discovery-result.json 数据

---

📚 更多信息

• 完整文档: README.md
• 迁移规则: MIGRATION-RULES.md
• 修复总结: FIX-SUMMARY.md
• 基础设施指南: INFRASTRUCTURE-USAGE-GUIDE.md

---

祝你使用愉快！ 🎉