代码导读（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，多服务共用可能冲突

第四步：输出导读文档

输出格式

根据导读深度选择输出方式：

完整导读文档结构

# 代码导读：<模块/项目名>

> 一句话概括这个模块/项目做什么

## 技术栈
- 语言/框架/主要依赖

## 架构概览
（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 评估影响