312362115/claude/code-walkthrough

导读请求
  │
  ├─ 整个项目？
  │   └─ 全局导读：项目架构 → 模块职责 → 核心流程 → 关键决策
  │
  ├─ 某个模块/目录？
  │   └─ 模块导读：模块职责 → 内部结构 → 核心逻辑 → 对外接口
  │
  └─ 某个具体功能/流程？
      └─ 流程导读：入口 → 数据流 → 关键分支 → 输出

1. 读项目根目录结构（ls / Glob）
2. 读配置文件（package.json / pyproject.toml / tsconfig.json）
3. 读 README / CLAUDE.md / docs/（如果有）
4. 检查 git log 最近 20 条提交（了解活跃区域）

## 架构概览
 
### 模块组成
-`src/api/` — API 路由层，接收请求、参数校验、调用 service
-`src/services/` — 业务逻辑层，核心计算和编排
-`src/models/` — 数据模型，定义实体和数据库交互
-`src/utils/` — 工具函数，无业务语义
 
### 依赖关系
api → services → models
         ↓
       utils
 
### 数据流向
请求 → 路由 → 中间件（认证/校验）→ service → model → 数据库
                                                    ↓
响应 ← 路由 ← ─────────────────────── service ← model

## 核心流程
 
### 流程 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，安全
-没有登录失败次数限制

## 关键设计决策
 
### 决策 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

接手新项目 → code-walkthrough（建立心智模型）
                ↓
准备改动 → refactoring（影响分析可以复用导读的架构理解）
                ↓
改动前评估 → dependency-map（导读关注"是什么"，依赖分析关注"改了影响谁"）