zero-script-qa

概述

Zero Script QA 是一种方法论，通过结构化日志与实时监控来验证功能，而无需编写测试脚本。

传统流程：编写测试代码 → 执行 → 检查结果 → 维护。 Zero Script 流程：搭建日志基础设施 → 手动 UX 测试 → AI 日志分析 → 自动问题检测。

核心原则

记录一切：所有 API 调用（包括 200 OK）、所有错误、所有重要业务事件，整个流程可通过 Request ID 追踪。
结构化 JSON 日志：可解析的 JSON 格式，字段一致（timestamp、level、request_id、message、data），不同环境使用不同日志级别。
实时监控：Docker 日志流式输出，Claude Code 实时分析，即时发现问题并记录。

日志架构

JSON 日志格式标准：

{
  "timestamp": "2026-01-08T10:30:00.000Z",
  "level": "INFO",
  "service": "api",
  "request_id": "req_abc123",
  "message": "API Request completed",
  "data": {
    "method": "POST",
    "path": "/api/users",
    "status": 200,
    "duration_ms": 45
  }
}

必需日志字段：timestamp（ISO 8601，发生时间）、level（DEBUG、INFO、WARNING、ERROR）、service（服务名，如 api、web、worker）、request_id（请求追踪 ID）、message（日志消息）、data（附加数据，可选）。

日志级别策略：Local 最低 DEBUG；Staging 最低 DEBUG；Production 最低 INFO。

Request ID 传播：Client → API Gateway → Backend → Database，各层使用同一个 Request ID（如 req_abc）进行追踪。

实现模式

入口处生成 Request ID：使用 uuid 生成 req_ 前缀 ID，并通过 header X-Request-ID 传播。
提取与传播 Request ID：从 header 中提取或生成，写入所有日志，调用下游服务时放入 header。

后端日志（FastAPI）

提供 JsonFormatter 与 LoggingMiddleware 代码示例：中间件读取 X-Request-ID 或生成新的，记录请求开始（method、path、query）、请求完成（status、duration_ms），并在响应 header 中回写 X-Request-ID。业务逻辑日志示例为 create_user，记录“Creating user”和“User created”及 user_id。

前端日志（Next.js）

提供 lib/logger.ts 模块，定义 LogLevel、LogData、LOG_LEVELS、MIN_LEVEL（生产为 INFO，其余为 DEBUG），log 函数输出 JSON 到 console。提供 lib/api-client.ts 集成示例：生成 requestId，记录“API Request started”“API Request completed”（包括 200 OK）、“API Request failed”“API Request error”，并携带 X-Request-ID header。

Nginx JSON 日志

提供 nginx.conf 中 log_format json_combined 配置示例，输出 timestamp、level、service、request_id、message 及 data（remote_addr、method、uri、status、body_bytes_sent、request_time、upstream_response_time、http_referer、http_user_agent），access_log 使用该格式。

基于 Docker 的 QA 工作流

提供 docker-compose.yml 示例，包含 api、web、nginx 服务，api 设置 LOG_LEVEL=DEBUG、LOG_FORMAT=json 及 json-file 日志驱动（max-size 10m，max-file 3）。

实时日志监控命令：

docker compose logs -f
docker compose logs -f api
docker compose logs -f | grep '"level":"ERROR"'
docker compose logs -f | grep 'req_abc123'

QA 自动化工作流步骤：1. 启动环境（docker compose up -d，docker compose logs -f）；2. 手动 UX 测试（注册、登录、核心功能、边界情况）；3. Claude Code 实时日志分析（监控流、检测错误模式、异常响应时间、按 Request ID 追踪全流程、自动记录问题）；4. 输出问题文档。

问题检测模式与阈值

严重级别与条件：Critical 对应 level: ERROR 或 status: 5xx、duration_ms > 3000、连续失败 3 次以上，均立即报告；Warning 对应 status: 401、403 或 duration_ms > 1000；Info 对应缺失日志字段、Request ID 未传播，记为改进项。

阶段集成

Phase 4（API）API 响应日志验证；Phase 6（UI）前端日志验证；Phase 7（Security）安全事件日志验证；Phase 8（Review）日志质量评审；Phase 9（Deployment）生产日志级别配置。

迭代测试周期

以 bkamp.ai 通知功能开发为例的 8 轮测试过程：第 1 轮 30%（DB schema 不匹配，执行 schema 迁移）、第 2 轮 45%（缺少 NULL 处理，添加 null 检查）、第 3 轮 55%（路由错误，修复 deeplink）、第 4 轮 65%（类型不匹配，修复 enum 类型）、第 5 轮 70%（计算错误，修复计数逻辑）、第 6 轮 75%（事件缺失，添加事件触发）、第 7 轮 82%（缓存同步问题，修复缓存失效）、第 8 轮 89%（稳定，最终打磨）。循环工作流：运行测试脚本（E2E 或手动）→ Claude 实时监控日志 → 记录通过/失败 → Claude 定位根因 → 立即修复代码（热重载）→ 记录 Cycle N → Bug → Fix，重复直到通过率可接受（>85%）。

模板与检查清单

提供 E2E 测试脚本模板（bash，使用 curl 调用 API，统计 PASS/FAIL/SKIP）、测试周期文档模板、以及日志基础设施、后端日志、前端日志、QA 工作流的检查清单。

自动应用规则

构建日志基础设施时：实现 API/后端时建议创建日志中间件、设置 JSON 格式 logger、添加 Request ID 生成与传播逻辑；实现前端时建议创建 Logger 模块、与 API client 集成、携带 Request ID header。执行 QA 时：引导运行 docker compose logs -f、请求用户手动 UX 测试、实时监控日志、发现问题立即记录、提供修复建议。

限制

资料未说明该方法的收费、价格、平台支持范围与效果承诺。