07 测试、失败与修复

注入一个已知故障，通过 ClickStack 诊断它，实施修复，并证明已经恢复。

成果

在约 20 分钟 内，你将走完一次从故障到验证恢复的完整事件处理。本模块直接承接模块 06，并使用模块 00 中配置好的 ClickStack MCP。

第 1 步：选择一个故障

从故障 01 开始。故障 02 是第二个简短练习；故障 03 需要更大的数据集才能稳定地触发失败。

分支	预期故障	需要重建
`fault/01-map-not-loading`	地图多边形消失；其他卡片正常	frontend
`fault/02-zone-stats-500`	区域地图数据以 HTTP 500 失败	backend
`fault/03-slow-dashboard`	趋势请求超时；仅在有多月数据时使用	backend

第 2 步：注入并复现它

下面的示例在保留你本地任何工作的同时注入故障 01：

cd "$(git rev-parse --show-toplevel)"
git stash push --include-untracked -m "before-module-07"
git switch build-workshop-v1
git switch fault/01-map-not-loading

cd workshops/build_workshop/app
docker compose --env-file .env.workshop \
  -f docker-compose.workshop.yml \
  -f docker-compose.otel.yml \
  up -d --build frontend

在 localhost:8080 打开一个全新的浏览器会话。现在地图是空的属于预期现象；其他地方的故障不属于这个场景。

第 3 步：从证据出发诊断

给 agent 的是症状，不是答案：

使用 clickstack MCP 调查当前故障。
关联前端和后端的遥测数据，找出根本原因，并引用能够支持结论的具体事件、请求、
响应内容类型或 trace。暂时不要修改代码。

对于故障 01，也要查看 ClickStack → Client Sessions。有用的证据是一个前端错误和一次失败的资源解析；健康的后端 traces 同样是证据，因为它们缩小了影响范围。

ClickStack Client Sessions 显示前端错误以及空地图的回放

在动手修复之前，先写下：

出问题的组件；
能证明这一点的证据；以及
一个在修复前会失败、修复后会通过的恢复检查。

第 4 步：修复并重建

让 agent 做出针对已证实原因的最小改动，然后重建受影响的服务。对于故障 01：

docker compose --env-file .env.workshop \
  -f docker-compose.workshop.yml \
  -f docker-compose.otel.yml \
  up -d --build frontend

对于故障 02 或 03，把 frontend 换成 backend。

打开一个新的浏览器会话。原来的症状必须消失，并且 ClickStack 中不应出现新的匹配错误。旧的事件记录仍然存在于所选的时间范围内；请比较时间戳，而不要期待历史记录消失。

第 5 步：回到干净的基线

保留你尝试过的修复内容，恢复到 build-workshop-v1，并重建两个应用服务：

cd "$(git rev-parse --show-toplevel)"
git stash push --include-untracked -m "module-07-fix"
git switch build-workshop-v1

cd workshops/build_workshop/app
docker compose --env-file .env.workshop \
  -f docker-compose.workshop.yml \
  -f docker-compose.otel.yml \
  up -d --build frontend backend

完成检查

注入的症状在修复之前出现了。
agent 引用了能证明根本原因的遥测数据。
同一个恢复检查在修复之后通过了。
一个全新的会话不会产生新的匹配错误。
git branch --show-current 返回 build-workshop-v1。

继续前往 08 聊天与 Langfuse。

成果