03-修复Bug

用途

修 Bug 不是把报错文字藏起来，而是完成一条证据链：固定现象，收集日志，写出修复前会失败的测试，定位根因，做最小修复，跑回归测试，最后审查 diff。本页只用一个案例贯穿：用户会话过期后刷新页面，POST /api/session/refresh 返回 500。产品约定的正确行为是：有效刷新令牌返回 200；过期或撤销令牌返回 401 和 SESSION_EXPIRED；客户端收到该响应后清理会话并跳转登录页；不改变公开路由、有效响应，也不把令牌写入日志。本文假定项目使用 Node.js、npm、Vitest 和 Git。实际框架、目录和脚本以仓库为准；先看 package.json，不要为了照抄示例而新增测试框架或创建平行实现。

完成标准

一次合格的修复要能回答：

谁在什么环境下遇到了什么现象？
哪些确定步骤可以重新触发？
日志哪一行提供了调用位置，哪一行只是症状？
哪个测试在修复前失败，并表达了用户可观察的契约？
哪个状态或数据假设被违反，才是根因？
为什么这组改动是最小修复？
原失败测试、相关测试和工程检查是否通过？
diff 是否只有目标实现、测试和必要文件？

没有证据的结论标记为“未验证”，不要写成“已解决”。

案例上下文

用户报告：登录后放置超过一小时，再打开订单页，Network 面板显示：

POST /api/session/refresh 500 Internal Server Error

脱敏后的服务端日志：

[session] refresh requested userId=42
TypeError: Cannot read properties of undefined (reading 'id')
    at refreshSession (src/auth/session-service.ts:58:31)
    at async refresh (src/routes/session.ts:27:20)

探索后可能找到的相关文件如下：

src/auth/session-service.ts
auth/routes/session.ts
src/middleware/error-handler.ts
src/client/session-client.ts
tests/auth/session-service.test.ts
tests/routes/session.test.ts
package.json
.env.example

这些路径只是案例上下文。让 Codex 报告你仓库中的实际路径，不要按示例强行创建文件。

1. 先建立安全检查点

检查目录、分支和工具

在项目根目录执行：

pwd
git status --short --branch
node --version
npm --version
codex --version

PowerShell 可执行：

Get-Location
git status --short --branch
node --version
npm --version
codex --version

预期：路径、分支和工具版本都符合任务环境。若 git status 已有他人或其他任务的改动，记录文件名，不要使用 git reset --hard 或 git restore . 清理它们。工作区干净且团队流程允许时，可以先打检查点：

git log -1 --oneline
git add -A
git commit -m "chore: checkpoint before session refresh fix"

不要把别人的未提交改动一起提交。工作区不干净时，用补丁或独立分支保存状态。

先只读调查

启动 Codex：

codex

输入：

这是一个登录会话刷新返回 500 的 Bug 调查。先只读，不要修改文件、安装依赖、提交或访问生产服务。

请读取 package.json、README、与 session 相关的路由、服务、错误处理和 tests。报告：
1. 实际的启动、测试、lint 命令；
2. refresh 的路由、服务调用链和错误处理链；
3. 过期刷新令牌按现有契约应返回什么；
4. 现有测试覆盖哪些分支；
5. 复现还缺哪些环境或数据前提。

只报告发现，不要猜测，不要编辑。

预期动作：Codex 读取真实文件并引用符号，报告调用链和命令，不创建文件。若它在调查阶段改了文件，先停止，查看 git status、git diff，让它撤回调查改动或切到只读模式。

2. 把现象写成复现配方

“登录后有时失败”不是复现步骤。复现配方必须包含初始数据、操作顺序、实际输出和期望输出。时间相关问题使用固定时钟或固定过期时间，不要在测试中真的等待一小时。先查看脚本，不要盲目安装依赖：

node -e "const p=require('./package.json'); console.log(p.scripts)"

在确认仓库脚本后，让 Codex 只运行相关测试或服务。把脱敏事实补充给它：

调查结果与复现条件如下，请先不要改代码。

环境：Node 22.14.0，npm 10.9.2，测试数据库为本地 SQLite。
复现：
1. npm run dev 启动服务；
2. 使用测试用户 alice@example.test 登录；
3. 使用项目已有工具生成 exp=2026-09-01T10:00:00Z 的刷新令牌；
4. 在 2026-09-01T10:05:00Z 调用 POST /api/session/refresh；
5. 观察响应和脱敏后的服务端日志。

实际：HTTP 500，{"error":"internal_error"}；日志见上文。
期望：HTTP 401，{"error":"SESSION_EXPIRED"}，且不输出令牌原文。

请只复现并报告命令、退出码、完整相关输出和未确认的前提。

预期结果是：请求进入 refresh 路由，过期分支可被触发，在 session-service.ts 抛出异常，当前错误处理器把它包装成 500。无法复现时不能直接修，转到“环境与数据问题”。

3. 用日志取证

日志要帮助确认：是否进入正确路由；令牌被判断为有效、过期、撤销还是未知；数据库返回 null、undefined 还是连接异常；错误发生在哪个调用点；错误处理器如何映射；是否泄露秘密。让 Codex 区分证据和假设：

请把刚才的复现日志整理成“证据 / 说明 / 尚未证明”三列表格。
区分日志已证明的事实、代码推断的可能性、必须用测试或命令确认的假设。
不要修改日志实现。

本案例中，日志证明 refreshSession 发生了 TypeError，但还不能单独证明查询为空的原因。候选原因包括过期令牌、用户被删除、数据库连接故障或 schema 不一致。堆栈行号是坐标，不是根因。若日志出现下列内容，先遮盖后再交给 Codex：

refreshToken=eyJhbGciOiJIUzI1NiIs...
Cookie: session=真实值
email=真实客户地址

提示：

我已将令牌和个人信息替换为 <REDACTED>。不要读取或打印 .env、生产数据库、完整 Cookie 或令牌原文。

检查日志代码也要限定范围：

只读检查 session 相关 logger 调用，确认没有记录 refresh token、access token、Cookie 或完整用户对象。
列出日志改进建议，但本次只修错误映射，不重构日志系统。

4. 先写修复前失败的测试

没有失败测试，Codex 可能只让 500 消失。先让它阅读已有测试的 fixture、请求工具、时钟和断言风格：

只读查看与 session 相关的测试。说明测试框架、请求工具、时间控制、数据库工厂和断言约定。
不要创建测试，不要修改生产代码。

然后输入：

现在只新增一个最小回归测试，先不要修改生产代码。

测试目标：过期 refresh token 调用 POST /api/session/refresh 时，响应为 401，JSON error 为 SESSION_EXPIRED，日志不包含令牌原文。

遵循现有 fixture、时间控制和请求方式；使用固定过期时间，不等待真实时间；不改变公开 API，不新增依赖；只改直接相关测试文件。写完立即运行这一条测试，报告失败命令、退出码和关键输出。

修复前应看到类似失败：

FAIL tests/routes/session.test.ts
expected 401, received 500
expected "SESSION_EXPIRED", received "internal_error"
Tests: 1 failed, 0 passed
Process exited with code 1

如果测试直接通过，不要宣布 Bug 已修复。检查：过期时间是否真正生效；mock 是否绕过了生产分支；请求是否命中真实路由；工作区是否已经有未提交修复。用 git diff 和测试日志确认。测试应表达契约，而不是实现行号：

expect(response.status).toBe(401);
expect(response.body).toEqual({ error: "SESSION_EXPIRED" });
expect(logOutput).not.toContain(refreshToken);

语法以仓库风格为准。至少保留一条路由或服务边界测试，不能只 mock 一个函数然后断言它抛错。

5. 根据调用链定位根因

让 Codex 对每一步列文件、函数、输入、输出和异常：

根据失败测试和现有代码，追踪一次 refresh 请求：
路由入口 -> token 解析 -> 会话查询 -> 过期/撤销判断 -> 响应映射 -> error handler。

列出每一步的文件、符号、输入、输出和可能异常，并把“已确认根因”和“仍是猜测”分开。先不要修改。

案例中的调用链可能是：

routes/session.ts: refresh()
  -> auth/session-service.ts: refreshSession()
  -> token.verify(refreshToken)
  -> sessionRepository.findByTokenId(token.jti)
  -> 读取 session.id
  -> middleware/error-handler.ts 转成 500

用下面的输入要求根因证明：

请证明根因，而不是只提出修法：
过期分支中哪个值为空，它的返回类型/契约是什么；
为什么当前代码仍访问它的 id；
error-handler 为什么把它变成 500；
有效 token 为什么不经过这个错误路径；
项目是否已有 SessionExpiredError 或等价错误映射。
无法从代码或失败测试证明的内容标记为未确认。

合理结论是：不可用 session 查询结果被当成成功结果继续使用，访问 session.id 抛出通用 TypeError，统一错误处理器没有识别领域状态，于是返回 500。根因不是“加一个 try/catch”。再排除相邻原因：

请逐项验证以下假设，不要改实现：
A：数据库连接失败导致查询无结果；
B：JWT exp 的秒/毫秒单位错误；
C：过期 token 查询为空是预期业务状态；
D：已有 error-handler 映射到 401；
E：测试 fixture 的 token 已过期但 session 数据仍被当作有效。
每项给出证据文件、命令或测试结果。

若 A 成立，应处理数据库环境，不能把连接故障伪装成 401；若 B 成立，修复位置应是时间解析，而不是错误处理器。

6. 环境与数据问题

无法复现不等于代码没有问题。先比较以下项目：

检查项	应确认	不要做
Node/npm	版本与 lockfile 是否匹配	未确认就升级全局 Node
配置	使用 `.env.example` 的测试值	粘贴生产 `.env`
数据库	schema、迁移、测试库路径	修改生产数据
时间	时区、应用时钟、JWT 单位	`sleep` 等一小时
依赖	lockfile 和安装状态	随意换测试框架
网络	是否需要本地服务或 mock	默认允许联网

启动失败时先运行：

node --version
npm --version
npm run
npm ls --depth=0
git diff -- package.json package-lock.json

若输出为：

Error: Cannot find module 'better-sqlite3'

这是依赖或原生模块环境问题，不是 refresh 根因。确认允许后再运行仓库规定的：

npm ci

不要为绕开缺包而把数据库替换成内存 mock。数据缺失时输入：

当前复现被数据前提阻塞。请先报告数据库是否为测试库、迁移版本、测试用户和 session fixture 是否存在。
不要读取生产数据，不要删除或批量更新。
若仓库有 seed/test factory，只使用它创建 alice@example.test 和固定过期 session，并先列出将执行的命令。

重新创建数据后若仍复现，数据只是条件，不是根因；比较 expiresAt、revokedAt、jti 和时区即可，不要记录真实令牌。

7. 提出并实施最小修复

根因有证据后，先让 Codex 规划边界：

根因已确认：不可用 session 仍被访问 session.id，TypeError 被统一映射为 500。
请先提出最小方案，不要编辑：需要改哪些文件；复用哪个错误类型；有效、过期、撤销、未知 token 和数据库异常各保持什么行为；如何验证和回滚。
不改路由、成功响应、schema、无关日志或依赖。

优先复用已有领域错误。若没有，按项目风格定义最小错误类型；在空值边界显式抛出；只给明确的 session 状态映射 401；数据库异常和未知编程错误继续 500；保留有效 token 的原成功路径。明确拒绝宽泛修法：

try {
  return await refreshSession(token);
} catch {
  return res.status(401).json({ error: "SESSION_EXPIRED" });
}

它会把数据库宕机和编程错误也伪装成过期会话。也不要返回 200 加空 token，这会让客户端误以为刷新成功。确认方案后输入：

按最小方案实施。只允许修改实际调用链中的 session-service、必要的错误映射和直接相关测试。

要求：过期、撤销或不存在的 session 返回 401 SESSION_EXPIRED；有效 token 的 200 响应不变；数据库和未知错误仍走原有 500；不记录令牌，不引入依赖，不改路由、schema 或无关代码；不提交、不推送。
编辑后先展示 diff 和准备运行的命令，不要扩大范围。

8. 审查 diff

先看范围：

git status --short
git diff --name-status
git diff --stat
git diff --check

预期只出现实现、必要映射和回归测试。若出现 lockfile、配置、生成物或其他业务模块，要求：

请撤回与本 Bug 无关的 package、配置、生成文件和其他模块改动，只保留最小修复及回归测试，再展示 diff。

再逐行问：

空结果判断是否早于 session.id？
只有明确 session 状态才返回 401 吗？
数据库异常仍为 500 吗？
有效 token 响应是否完全保持？
是否改变 JSON、路由或客户端依赖？
是否输出令牌、Cookie 或完整用户对象？
测试是否真的控制了过期时间？
是否夹带重命名、格式化或重构？

必要时执行：

git diff --word-diff=plain -- src/auth/session-service.ts src/middleware/error-handler.ts tests/routes/session.test.ts
git diff --check

Diff 大到无法解释时，先停止测试，拆掉无关改动。最小修复是只改变错误状态分支，不是单纯追求最少行数。

9. 分层验证

原失败测试

重新运行修复前的同一条命令：

npm run test:unit -- --run tests/routes/session.test.ts

预期：

PASS tests/routes/session.test.ts
refresh with expired token
  ✓ returns 401 SESSION_EXPIRED without logging the token
Tests: 1 passed
Process exited with code 0

仍失败时，不要连续改代码，输入：

回归测试仍失败。请只分析下面的完整输出，判断属于实现、断言、fixture、时间控制还是环境；先不要编辑。
<粘贴输出>

场景	期望	目的
有效 token	原 `200` 响应	保护主路径
过期 token	`401 SESSION_EXPIRED`	锁定本次 Bug
撤销/未知 token	项目既有约定	检查相邻边界
数据库异常	原 `500`	防止宽泛 catch

手工验收

本地服务可安全启动时：

npm run dev
curl -i -X POST http://localhost:3000/api/session/refresh \
  -H 'content-type: application/json' \
  -d '{"refreshToken":"<EXPIRED_TEST_TOKEN>"}'

预期：

HTTP/1.1 401 Unauthorized
{"error":"SESSION_EXPIRED"}

有效测试 token 还必须返回原成功响应。手工结果不一致时比较环境变量、时钟、数据库和服务进程，不要直接修改实现迎合一次请求。

10. 失败分支

选错文件

若 Codex 改了请求链路不会经过的旧模块：

停止编辑。请从实际调用链证明 refresh 请求经过哪些符号和文件。
撤回未必要的文件改动，只保留经调用链和失败测试证明需要的文件。

只加 try/catch

若数据库断开也变成 401：

当前补丁把所有异常都返回 401，破坏数据库错误的 500 契约。
撤回宽泛 catch，基于已有错误类型或明确 session 状态精确映射。先展示方案，再编辑。

测试绿但没复现

检查 mock 是否绕过生产分支、过期时间是否生效、请求是否命中路由、断言是否只检查“有响应”。让测试在修复前重新运行，必须能失败才能证明它锁住了 Bug。

环境失败

端口占用、缺少原生模块、数据库连接失败或 Node 版本不兼容先记录为环境失败：

命令：npm run test:unit -- --run tests/routes/session.test.ts
Node：22.14.0
退出码：1
错误：EADDRINUSE 127.0.0.1:3000

只释放确认属于当前任务的本地进程，不要杀掉不明服务。环境未恢复时，报告代码验证未完成。

扩大成重构

本任务只修过期 refresh token 的错误映射。撤回重构、命名调整、格式化和日志改造，只保留能让失败测试通过且不改变有效 token 行为的最小 diff。

确实需要重构时另开任务，先计划、分步并分别验证。

11. 最终验收与交付

执行：

git status --short
git diff --stat
git diff --check
git diff --name-only

逐项确认：交付摘要使用证据格式：

现象：过期 refresh token 原返回 500。
复现：<命令或测试路径>。
根因：session 查询为空后访问 session.id，未转换为领域错误。
修复：在边界处识别不可用 session，复用现有 401 映射。
验证：<修复前失败输出>；<修复后命令、退出码和结果>。
变更文件：<git diff --name-only>。
未验证：<环境差异或无>。
回滚：保留当前 diff，按文件审查后恢复，不覆盖他人改动。

可直接使用的 Codex 输入

请修复登录会话刷新 Bug，但严格按“复现 -> 日志取证 -> 失败测试 -> 根因 -> 最小修复 -> 回归 -> diff 审查”执行。

Bug：已过期或已撤销 refresh token 调用 POST /api/session/refresh 返回 500。
期望：返回 401，JSON 为 {"error":"SESSION_EXPIRED"}；有效 token 的 200 响应不变；令牌原文不进入日志。

先只读调查实际调用链和 package.json，报告命令和数据前提，不要编辑。
再用仓库已有 fixture 和固定时钟新增回归测试，先运行确认修复前失败。
只有根因被调用链和失败输出证明后，才提出并实施最小修复。

约束：不改路由、成功响应、schema；不引入依赖；不读取 .env、生产数据、Cookie 或真实令牌；不提交、不推送、不访问生产服务；不把数据库异常或未知错误宽泛映射为 401。

验证：回归测试修复前失败、修复后通过；有效、过期、撤销/未知 token 和数据库异常的相关测试通过；按 package.json 执行 lint/build；执行 git diff --check，并报告每条命令、退出码和 git diff --name-status。

失败时停止扩大修改范围，先判断是代码、测试、数据还是环境问题。

预期不是“一次生成补丁”，而是依次得到调用链、失败输出、根因证明、最小 diff 和验证结果。

小结

固定复现
  -> 采集脱敏日志
  -> 让测试先失败
  -> 对照调用链定位根因
  -> 区分代码、环境和数据问题
  -> 只修必要分支
  -> 运行分层回归测试
  -> 审查文件范围与行为 diff

接口不再返回 500，只说明症状改变。只有失败测试变绿、有效路径不回归、异常没有被吞掉、diff 范围可解释，并且剩余环境假设被记录，这次 Bug 修复才算完成。参考资料：参考/codex/14-workflows.md、参考/codex/06-first-task.md、参考/codex/13-prompting.md。

开始

Codex 完整教程

Claude Code 完整教程

用途

完成标准

案例上下文

1. 先建立安全检查点

检查目录、分支和工具

先只读调查

2. 把现象写成复现配方

3. 用日志取证

4. 先写修复前失败的测试

5. 根据调用链定位根因

6. 环境与数据问题

7. 提出并实施最小修复

8. 审查 diff

9. 分层验证

原失败测试

相关测试和工程检查

手工验收

10. 失败分支

选错文件

只加 try/catch

测试绿但没复现

环境失败

扩大成重构

11. 最终验收与交付

可直接使用的 Codex 输入

小结

​用途

​完成标准

​案例上下文

​1. 先建立安全检查点

​检查目录、分支和工具

​先只读调查

​2. 把现象写成复现配方

​3. 用日志取证

​4. 先写修复前失败的测试

​5. 根据调用链定位根因

​6. 环境与数据问题

​7. 提出并实施最小修复

​8. 审查 diff

​9. 分层验证

​原失败测试

​相关测试和工程检查

​手工验收

​10. 失败分支

​选错文件

​只加 try/catch

​测试绿但没复现

​环境失败

​扩大成重构

​11. 最终验收与交付

​可直接使用的 Codex 输入

​小结

用途

完成标准

案例上下文

1. 先建立安全检查点

检查目录、分支和工具

先只读调查

2. 把现象写成复现配方

3. 用日志取证

4. 先写修复前失败的测试

5. 根据调用链定位根因

6. 环境与数据问题

7. 提出并实施最小修复

8. 审查 diff

9. 分层验证

原失败测试

相关测试和工程检查

手工验收

10. 失败分支

选错文件

只加 try/catch

测试绿但没复现

环境失败

扩大成重构

11. 最终验收与交付

可直接使用的 Codex 输入

小结