wwjcloud/tools/QUICK-START.md

# 🚀 工具快速开始指南

## 📋 核心功能

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

---

## ⚡ 快速命令

### 1. 完整迁移（推荐）

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

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

### 2. 单独运行生成器

```bash
# 实体生成器
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. 质量检查

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

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

### 4. 验证修复

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

---

## 🎯 典型工作流

### 场景1: 首次迁移

```bash
# 步骤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: 单独生成某个模块

```bash
# 步骤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: 验证和质量检查

```bash
# 验证修复
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 模式预览结果：
```bash
DRY_RUN=true node tools/migration-coordinator.js
```

### 2. 详细输出帮助调试

遇到问题时启用详细输出：
```bash
VERBOSE=true node tools/generators/entity-generator.js
```

### 3. 组合使用

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

### 4. 快速质量检查

开发过程中频繁运行快速检查：
```bash
node tools/generators/quality-gate.js quick
```

---

## ⚠️ 注意事项

1. **首次运行前备份**
   - 建议先用 dry-run 模式预览
   - 确认结果正确后再实际执行

2. **Quality Gate 可能失败**
   - TypeScript 编译错误
   - ESLint 规范问题
   - 可以先生成代码，后续修复

3. **生成器顺序建议**
   ```
   实体 → 验证器 → 服务 → 控制器 → 模块
   ```

4. **遇到错误时**
   - 查看错误日志
   - 使用 VERBOSE 模式
   - 检查 PHP 源文件是否存在

---

## 🆘 常见问题

### Q: Dry-run 模式不生效？

检查环境变量设置：
```bash
# 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`:
```json
{
  "scripts": {
    "type-check": "tsc --noEmit",
    "lint": "eslint src --ext .ts"
  }
}
```

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

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

---

## 📚 更多信息

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

---

**祝你使用愉快！** 🎉