312362115 代码导读（Code Walkthrough）
读代码和读书一样——先看目录了解结构，再看核心章节理解逻辑，最后看细节。 不是逐行翻译代码，而是帮读者建立"这个系统怎么运转"的心智模型。
第一步：确定导读范围和深度
导读请求
│
├─ 整个项目？
│ └─ 全局导读：项目架构 → 模块职责 → 核心流程 → 关键决策
│
├─ 某个模块/目录？
│ └─ 模块导读：模块职责 → 内部结构 → 核心逻辑 → 对外接口
│
└─ 某个具体功能/流程？
└─ 流程导读：入口 → 数据流 → 关键分支 → 输出
用 AskUserQuestion 确认：
- 导读目标：看什么？整个项目、某个模块、还是某个功能？
- 导读目的：为什么要看？接手维护、准备改动、还是纯了解？
- 已有认知：对这块代码已经了解多少？（避免输出用户已知的信息）
第二步：全局扫描
不管导读什么范围，先花 2-3 个工具调用建立全局感知：
2.1 项目全局（如果是项目/模块导读）
1. 读项目根目录结构（ls / Glob）
2. 读配置文件（package.json / pyproject.toml / tsconfig.json）
3. 读 README / CLAUDE.md / docs/（如果有）
4. 检查 git log 最近 20 条提交（了解活跃区域）
提取关键信息：
- 技术栈：语言、框架、主要依赖
- 项目类型：前端应用 / 后端服务 / 全栈 / CLI 工具 / 库
- 目录组织：按功能分还是按类型分？有没有约定
2.2 目标区域
定位到导读目标后，了解：
- 入口文件：这个模块/功能从哪里开始？
- 文件清单：涉及哪些文件？各自大概多少行？
- 依赖关系：依赖了什么外部模块？被谁依赖？
第三步：分层梳理
按照 架构 → 流程 → 细节 的顺序递进，每一层解决不同的问题。
Layer 1：架构层 — "系统由什么组成"
回答：这个系统/模块的整体结构是什么？各部分各司什么职？
输出格式：
## 架构概览
### 模块组成
- `src/api/` — API 路由层，接收请求、参数校验、调用 service
- `src/services/` — 业务逻辑层，核心计算和编排
- `src/models/` — 数据模型，定义实体和数据库交互
- `src/utils/` — 工具函数，无业务语义
### 依赖关系
api → services → models
↓
utils
### 数据流向
请求 → 路由 → 中间件（认证/校验）→ service → model → 数据库
↓
响应 ← 路由 ← ─────────────────────── service ← model
Layer 2：流程层 — "核心功能怎么运转"
回答：一个请求/操作从头到尾经过了哪些步骤？
选择 1-3 个最核心的流程做详细走读：
## 核心流程
### 流程 1：用户登录
1. `POST /api/login` → `src/api/auth.ts:handleLogin()`
- 参数校验：email + password
2. → `src/services/auth.ts:login()`
- 查询用户：`UserModel.findByEmail(email)`
- 验证密码：`bcrypt.compare(password, user.hash)`
- 生成 token：`jwt.sign({ userId: user.id }, secret, { expiresIn: '7d' })`
3. → 返回：`{ token, user: { id, name, email } }`
关键点：
- token 过期时间 7 天，写死在代码里（可能需要改为配置）
- 密码验证用 bcrypt，安全
- 没有登录失败次数限制
Layer 3：细节层 — "关键设计决策和隐含知识"
回答：为什么这么写？有什么不明显的约定或陷阱？
## 关键设计决策
### 决策 1：为什么用 Redis 做 session 而不是 JWT 无状态？
- 见 `docs/specs/2026-03-23-auth-session-design.md`（如果有文档）
- 或从代码推断：支持主动注销（删 Redis key 即失效）
### 决策 2：为什么 UserModel 同时用了 ORM 和 raw SQL？
- ORM 用于常规 CRUD
- raw SQL 用于复杂聚合查询（`src/models/user.ts:237` 的注释说明了原因）
## 隐含约定
- 所有 API 响应统一包装为 `{ code, data, message }` 格式（见 `src/middleware/response.ts`）
- 错误处理走全局 error handler（`src/middleware/error.ts`），不需要每个路由单独 catch
- 环境变量从 `.env` 加载，必填项在 `src/config.ts` 中校验
## 注意事项 / 潜在风险
- `src/services/order.ts:89` — 库存扣减没有并发保护
- `src/utils/cache.ts` — 缓存 key 没有 namespace，多服务共用可能冲突
第四步：输出导读文档
输出格式
根据导读深度选择输出方式：
| 深度 | 输出 |
|---|---|
| 快速了解（聊天中回答） | 直接在对话中输出，不存文件 |
| 完整导读（需要沉淀） | 写入 docs/guides/<模块名>-walkthrough.md |
完整导读文档结构
# 代码导读：<模块/项目名>
> 一句话概括这个模块/项目做什么
## 技术栈
- 语言/框架/主要依赖
## 架构概览
（Layer 1 的输出）
## 核心流程
（Layer 2 的输出，1-3 个关键流程）
## 关键设计决策
（Layer 3 的输出）
## 隐含约定
（不写在代码注释里但需要知道的规则）
## 注意事项
（潜在风险、技术债、容易踩的坑）
## 相关文档
- 指向 docs/ 下的相关 spec、plan、decision
导读准则
- 不逐行翻译：读者是开发者，能读代码。导读要提炼的是"代码没直接告诉你的东西"——架构意图、设计理由、隐含约定
- 先宏观后微观：先给全景地图，再放大关键区域。不要一上来就钻进某个函数
- 关注连接：模块之间怎么交互？数据怎么流转？比单个模块内部逻辑更重要
- 标注位置：提到具体逻辑时标注
文件:行号，方便读者跳转查看 - 诚实说不知道：如果某个设计决策从代码看不出原因，说"从代码推断可能是因为 X，但不确定"，不要编理由
- 按读者水平调整：用户说"我是 Go 高手但不懂 React"，就用 Go 的类比解释 React 的概念
与其他 skill 的关系
接手新项目 → code-walkthrough（建立心智模型）
↓
准备改动 → refactoring（影响分析可以复用导读的架构理解）
↓
改动前评估 → dependency-map（导读关注"是什么"，依赖分析关注"改了影响谁"）
code-walkthrough vs dependency-map 的区别：
- code-walkthrough：理解代码，回答"这是什么、怎么运转、为什么这么写"
- dependency-map：评估影响，回答"改这里会动到哪里"
- 通常先 walkthrough 理解，再 dependency-map 评估影响