# Dev-Tool 集成使用指南

## 概述

Dev-Tool 集成模块在 E2E 测试阶段自动捕获运行时日志、网络请求、状态变化和异常，用于对比"AC 预期行为 vs 实际执行"，快速定位逻辑差异。

## 核心功能

1. **自动日志捕获**：在 E2E 测试时注入监听代码，捕获 console、network、errors、interactions
2. **AC 对比分析**：对比 05-验收清单.md 的预期行为与实际运行日志
3. **差异报告生成**：生成 `19-运行日志差异报告.md`，标注不一致的 AC

---

## 使用流程

### 阶段 1：E2E 脚本注入 dev-tool

在生成 E2E 脚本后，执行：

```bash
npx sdd-flow-kit dev-tool-inject --change <change-name>
```

**作用**：向 `e2e/<change-name>.spec.ts` 注入日志捕获代码。

**注入内容**（自动添加到 E2E 脚本）：

```typescript
// ========== Dev-Tool 日志捕获（自动注入） ==========
const devToolLogs: any[] = [];

test.beforeEach(async ({ page }) => {
  // 捕获 console 日志
  page.on('console', msg => {
    devToolLogs.push({
      timestamp: Date.now(),
      type: 'console',
      level: msg.type(),
      message: msg.text(),
    });
  });

  // 捕获未处理异常
  page.on('pageerror', error => {
    devToolLogs.push({
      timestamp: Date.now(),
      type: 'error',
      message: error.message,
      stack: error.stack,
    });
  });

  // 捕获网络请求和响应
  page.on('request', request => { /* ... */ });
  page.on('response', async response => { /* ... */ });
});

test.afterEach(async ({ page }, testInfo) => {
  // 导出日志到 dev-tool-logs/<test-name>.json
  const logPath = path.join(__dirname, '../dev-tool-logs', `${testInfo.title}.json`);
  await fs.promises.writeFile(logPath, JSON.stringify({
    testTitle: testInfo.title,
    status: testInfo.status,
    logs: devToolLogs,
  }, null, 2));
  
  devToolLogs.length = 0;
});
```

---

### 阶段 2：运行 E2E 测试（自动捕获日志）

```bash
# 正常运行 E2E 测试
npx playwright test --grep <change-name>
```

**结果**：
- E2E 测试正常运行
- 日志自动保存到 `dev-tool-logs/*.json`

**日志示例**（`dev-tool-logs/AC-01-财务列表页展示.json`）：

```json
{
  "testTitle": "AC-01 财务列表页展示",
  "status": "passed",
  "duration": 3245,
  "logs": [
    {
      "timestamp": 1710345600000,
      "type": "console",
      "level": "log",
      "message": "页面加载完成"
    },
    {
      "timestamp": 1710345601000,
      "type": "network",
      "method": "GET",
      "url": "http://localhost:3000/api/finance/list",
      "status": 200
    },
    {
      "timestamp": 1710345602000,
      "type": "error",
      "message": "Uncaught TypeError: Cannot read property 'id' of undefined",
      "stack": "at FinanceList.vue:45:12"
    }
  ]
}
```

---

### 阶段 3：Dev-Tool 验证（对比 AC 预期 vs 实际日志）

```bash
npx sdd-flow-kit dev-tool-validate \
  --run-id <runId> \
  --change <change-name>
```

**流程**：

1. **读取 AC 验收清单**（`05-验收清单.md`）
2. **读取 dev-tool 日志**（`dev-tool-logs/*.json`）
3. **对比预期 vs 实际**：
   - 提取 AC 验收标准中的关键词（如"点击"、"保存"、"财务报表"）
   - 检查日志中是否包含这些关键词
   - 检查是否有未处理异常
4. **生成差异报告**（`19-运行日志差异报告.md`）

**报告示例**：

```markdown
# 19-运行日志差异报告

生成时间：2024-03-14T10:30:00Z
Change：finance-v234

## 汇总

- 总 AC 数：5
- 通过（预期与实际一致）：4
- 不一致：1

## 详细对比

### 1. AC-01

**验收标准**：用户点击「拉取欢聚最新数据」，系统展示财务报表列表

**预期行为**：点击、拉取欢聚最新数据、财务报表

**实际日志**：
```json
[
  { "type": "console", "message": "点击拉取数据按钮" },
  { "type": "network", "url": "/api/finance/sync", "status": 200 },
  { "type": "error", "message": "Cannot read property 'id' of undefined" }
]
```

**结论**：❌ 不一致

**原因**：发现 1 个错误日志；预期行为中的关键词（财务报表）在日志中缺失

---

### 2. AC-02

**验收标准**：双击表格行，打开详情抽屉

**预期行为**：双击、详情抽屉

**实际日志**：
```json
[
  { "type": "console", "message": "双击表格行" },
  { "type": "console", "message": "打开详情抽屉" },
  { "type": "network", "url": "/api/finance/detail/123", "status": 200 }
]
```

**结论**：✅ 一致
```

---

## 集成到自动化流程

### 方案 1：集成到 validate 阶段（推荐）

修改 `.opsx/config.json` 的 `deliveryPipeline`：

```json
{
  "deliveryPipeline": [
    "tdd-script",
    "openspec-superpowers-pipeline",
    "dev-tool-validate",          // 新增
    "demo-fidelity-review",
    "visual-regression-compare"
  ]
}
```

### 方案 2：手动执行（调试阶段）

```bash
# 1. 注入 dev-tool 到 E2E 脚本
npx sdd-flow-kit dev-tool-inject --change finance-v234

# 2. 运行 E2E 测试
npx playwright test --grep finance-v234

# 3. 分析日志差异
npx sdd-flow-kit dev-tool-validate --change finance-v234

# 4. 查看报告
cat openspec/PRD/<runId>/19-运行日志差异报告.md
```

### 方案 3：集成到 07-opsx-auto-chain.template.md

```markdown
### 阶段 E：Validate + Dev-Tool + 视觉回归

\`\`\`bash
# 验收
npx sdd-flow-kit validate --change {{CHANGE_NAME}}

# 【新增】Dev-Tool 验证（对比 AC 预期 vs 实际日志）
npx sdd-flow-kit dev-tool-validate --change {{CHANGE_NAME}}

# 视觉回归对比
npx sdd-flow-kit visual-compare --change {{CHANGE_NAME}}

# 演示保真复查
npx sdd-flow-kit demo-fidelity-review --auto --change {{CHANGE_NAME}}
\`\`\`
```

---

## 配置选项

### 环境变量

```bash
# 禁用 dev-tool（跳过日志捕获）
DEVTOOL_ENABLED=0 npx playwright test

# 自定义日志输出目录
DEVTOOL_LOG_DIR=./custom-logs npx playwright test
```

### 代码配置

```typescript
// src/core/devToolIntegration.ts
export function getDefaultDevToolConfig(outputRoot: string): DevToolConfig {
  return {
    enabled: process.env.DEVTOOL_ENABLED !== "0",
    captureConsole: true,      // 捕获 console.log/warn/error
    captureNetwork: true,      // 捕获 HTTP 请求和响应
    captureState: true,        // 捕获状态变化（预留）
    captureErrors: true,       // 捕获未处理异常
    captureInteractions: true, // 捕获用户交互（预留）
    outputDir: path.join(outputRoot, "dev-tool-logs"),
  };
}
```

---

## 典型问题定位

### 问题 1：预期行为与实际不一致

**报告显示**：

```markdown
**验收标准**：点击保存，展示 toast「保存成功」

**结论**：❌ 不一致

**原因**：预期行为中的关键词（保存成功）在日志中缺失
```

**定位步骤**：

1. 打开 `dev-tool-logs/<test-name>.json`
2. 搜索"保存"相关日志
3. 检查是否有网络请求成功但 toast 未展示
4. 查看代码中 toast 调用是否被注释或删除

---

### 问题 2：发现未处理异常

**报告显示**：

```markdown
**结论**：❌ 不一致

**原因**：发现 1 个错误日志

**实际日志**：
{
  "type": "error",
  "message": "Cannot read property 'id' of undefined",
  "stack": "at FinanceList.vue:45:12"
}
```

**定位步骤**：

1. 打开 `FinanceList.vue:45`
2. 检查数据结构是否为空
3. 添加空值判断或默认值

---

### 问题 3：网络请求失败

**报告显示**：

```json
{
  "type": "network",
  "method": "POST",
  "url": "/api/finance/save",
  "status": 500,
  "body": "{\"error\":\"Internal Server Error\"}"
}
```

**定位步骤**：

1. 检查后端日志
2. 验证请求参数是否正确
3. 检查后端接口是否已实现

---

## 最佳实践

1. **E2E 脚本生成后立即注入 dev-tool**
   ```bash
   npx sdd-flow-kit scaffold-e2e --change <name>
   npx sdd-flow-kit dev-tool-inject --change <name>
   ```

2. **本地开发时持续运行 E2E + dev-tool**
   ```bash
   # 监听模式
   npx playwright test --ui --grep <change-name>
   ```

3. **CI/CD 中集成 dev-tool 验证**
   ```yaml
   - name: E2E 测试 + Dev-Tool 验证
     run: |
       npx playwright test
       npx sdd-flow-kit dev-tool-validate --change ${{ matrix.change }}
   ```

4. **定期清理旧日志**
   ```bash
   # 保留最近 7 天的日志
   find dev-tool-logs -name "*.json" -mtime +7 -delete
   ```

---

## 与其他工具的对比

| 工具 | 用途 | Dev-Tool 的优势 |
|------|------|-----------------|
| Chrome DevTools | 手动调试 | 自动捕获 + AC 对比 |
| Sentry | 生产错误监控 | 开发阶段预防 + 预期对比 |
| LogRocket | 会话重放 | 轻量级 + 集成到 CI |
| Playwright trace | 测试失败回放 | 与 AC 验收绑定 |

---

## 后续计划

- [ ] 支持状态变化捕获（Redux/Zustand DevTools Protocol）
- [ ] 支持用户交互事件捕获（点击、输入、滚动）
- [ ] 集成到 Sentry/LogRocket（生产环境）
- [ ] 可视化日志时间轴
- [ ] AI 自动分析日志差异并生成修复建议

---

完整实现见：
- `src/core/devToolIntegration.ts`（核心模块）
- `src/steps/runDevToolValidate.ts`（命令入口）