重构遗留代码

请分析这个项目的代码库，告诉我：
1. 项目的整体架构和技术栈
2. 目录结构和文件组织方式
3. 主要的功能模块有哪些
4. 使用了哪些依赖库以及它们的版本
5. 是否有测试？测试覆盖情况如何？
6. 代码量大概有多少？

项目分析结果：

技术栈：Node.js + Express + MongoDB (Mongoose)
语言：JavaScript (ES5/ES6 混用，无 TypeScript)
目录结构：
  - routes/ — 15 个路由文件
  - models/ — 8 个 Mongoose 模型
  - middleware/ — 3 个中间件
  - helpers/ — 6 个工具文件
  - config/ — 数据库和应用配置

主要问题：
  - 没有测试文件
  - 回调地狱（未使用 async/await）
  - 大量全局变量
  - 部分路由文件超过 500 行
  - 没有输入验证
  - 错误处理不统一
  - 使用 var 声明变量
  - 部分依赖已过时

深入分析代码质量问题，按严重程度排列。特别关注：
1. 安全漏洞（SQL 注入、XSS、缺少认证等）
2. 可能导致 bug 的代码模式
3. 性能问题
4. 代码重复
5. 不良的设计模式

基于你的分析结果，制定一个分阶段的重构计划。要求：
1. 每个阶段都是独立可部署的（不能中途破坏现有功能）
2. 优先修复安全问题
3. 渐进式引入 TypeScript
4. 每个阶段结束时项目都能正常运行
5. 预估每个阶段的工作量

重构计划（分 6 个阶段）：

阶段 1：添加测试安全网（预计 2-3 小时）
  - 安装 Jest 和 Supertest
  - 为现有 API 端点编写集成测试
  - 确保所有核心功能都有测试覆盖
  - 设置 CI 运行测试

阶段 2：修复安全问题（预计 1-2 小时）
  - 添加输入验证（express-validator 或 Zod）
  - 修复认证中间件漏洞
  - 更新过时的依赖
  - 添加 rate limiting 和 helmet

阶段 3：代码现代化（预计 2-3 小时）
  - var -> const/let
  - 回调 -> async/await
  - require -> import（ES Modules）
  - 统一错误处理

阶段 4：TypeScript 迁移（预计 3-4 小时）
  - 配置 TypeScript
  - 逐文件迁移（.js -> .ts）
  - 添加类型定义
  - 修复类型错误

阶段 5：架构优化（预计 2-3 小时）
  - 拆分过大的路由文件
  - 引入服务层（Service Layer）
  - 提取公共逻辑
  - 改善数据库查询

阶段 6：完善与文档（预计 1-2 小时）
  - 补充测试用例
  - 添加 API 文档
  - 更新 README
  - 添加 CLAUDE.md 项目规范

为现有的 API 端点编写集成测试。要求：
1. 安装 Jest 和 Supertest
2. 创建测试用的数据库配置（使用内存数据库或独立的测试数据库）
3. 为每个路由文件编写基本的测试：
   - 正常情况下的请求和响应
   - 缺少必要参数时的错误响应
   - 需要认证的端点测试认证检查
4. 不需要追求 100% 覆盖率，但核心业务路径必须覆盖

运行测试并确认所有测试都能通过。如果有失败的测试，说明测试本身有问题（因为我们还没有改任何代码），请修复测试

将所有 JavaScript 文件中的 var 替换为 const 或 let。
- 如果变量后续没有被重新赋值，用 const
- 如果变量会被重新赋值，用 let
- 每个文件改完后运行测试确认没有问题

将代码中的回调风格改为 async/await。重点处理：
1. Mongoose 查询的回调
2. Express 路由处理函数
3. 中间件函数
4. fs 文件操作

注意保持错误处理的一致性，回调中的 err 参数要转换为 try-catch

// 重构前（回调风格）
router.get("/users/:id", function (req, res) {
  User.findById(req.params.id, function (err, user) {
    if (err) {
      return res.status(500).json({ error: "服务器错误" });
    }
    if (!user) {
      return res.status(404).json({ error: "用户不存在" });
    }
    res.json(user);
  });
});

// 重构后（async/await）
router.get("/users/:id", async (req, res, next) => {
  try {
    const user = await User.findById(req.params.id);
    if (!user) {
      return res.status(404).json({ error: "用户不存在" });
    }
    res.json(user);
  } catch (err) {
    next(err);
  }
});

创建一个全局错误处理中间件，替换现有分散的错误处理逻辑：
1. 创建自定义错误类（AppError），包含 statusCode 和 message
2. 在路由中使用 throw new AppError() 而不是直接 res.json
3. 在全局错误处理中间件中统一格式化错误响应
4. 为 async 路由添加 asyncHandler 包装器

运行全部测试，确认这次修改没有破坏任何功能

tests/routes/users.test.js 中的第三个测试失败了，错误是：
[粘贴错误信息]

请分析原因并修复。注意是重构代码的问题，不是测试本身的问题

为项目配置 TypeScript：
1. 安装 typescript、ts-node、@types/node、@types/express 等
2. 创建 tsconfig.json，使用以下配置：
   - strict: true（严格模式）
   - allowJs: true（允许 JS 和 TS 共存，方便渐进式迁移）
   - outDir: ./dist
   - rootDir: ./src
3. 修改 package.json 的脚本
4. 确保项目在只有 JS 文件时也能正常构建和运行

按以下顺序将文件从 .js 迁移到 .ts：

1. 先迁移工具文件（helpers/）— 它们通常没有外部依赖
2. 然后迁移模型文件（models/）— 添加接口定义
3. 接着迁移中间件（middleware/）
4. 最后迁移路由文件（routes/）

每迁移一个文件：
- 将 .js 重命名为 .ts
- 添加类型注解
- 修复 TypeScript 报告的类型错误
- 运行测试确认功能正常

先从 helpers/validator.js 开始

迁移 models/user.js 到 TypeScript。要求：
1. 定义 IUser 接口描述文档字段
2. 定义 IUserMethods 接口描述实例方法
3. 使用 Mongoose 的 Schema.Types 正确定义 schema
4. 导出类型化的 Model
5. 保持现有的虚拟字段和中间件

routes/api.js 有 600 多行代码，包含了用户、文章和评论三个模块的路由。
请将它拆分为三个独立的路由文件：
1. routes/users.ts
2. routes/posts.ts
3. routes/comments.ts

同时引入服务层，将业务逻辑从路由中提取出来：
1. services/userService.ts
2. services/postService.ts
3. services/commentService.ts

路由只负责：解析请求 -> 调用服务 -> 返回响应
服务层负责：业务逻辑 -> 数据库操作 -> 返回结果

我发现很多路由中有重复的分页逻辑和权限检查逻辑。请：
1. 创建一个通用的分页工具函数
2. 创建权限检查中间件（检查用户角色）
3. 创建资源所有权检查中间件（检查资源是否属于当前用户）
4. 将所有路由中的重复逻辑替换为这些公共工具

这段代码在 routes/posts.ts 的第 45-80 行中进行了复杂的数据转换。
请将它提取为一个独立的函数，放在 helpers/transforms.ts 中，并添加类型注解

routes/notifications.ts 中有一个很长的 switch-case 来处理不同类型的通知（邮件、短信、推送）。
请用策略模式重构它，让每种通知类型都是独立的策略类

扫描所有源代码文件，找出硬编码的数字和字符串常量，将它们提取到
constants/ 目录下的常量文件中。例如：
- HTTP 状态码 -> 使用 http-status-codes 库
- 错误消息 -> 集中到 constants/errors.ts
- 配置值 -> 移到环境变量或配置文件

// 不推荐
请将所有 15 个路由文件一次性迁移到 TypeScript

// 推荐
请先将 routes/users.js 迁移到 TypeScript，迁移完后我们运行测试确认没问题

在重构 models/user.ts 之前，请先检查 userSchema 上是否注册了
pre/post 中间件（如 pre save 的密码哈希），确保重构后这些行为被保留

以下哪些文件值得重构？请根据以下标准评估：
- 修改频率（经常改动的文件优先）
- 复杂度（代码复杂的文件优先）
- bug 历史（经常出 bug 的文件优先）
- 耦合度（被很多文件依赖的文件优先）

如果某个文件很少修改且运行稳定，即使代码不够优雅也可以暂时不动

routes/payment.js 的第 120 行有一段看起来很奇怪的逻辑：
[粘贴代码]

这段代码是什么意思？是 bug 还是有意为之？如果删除它可能会有什么影响？

# 重构说明

## 项目背景
这是一个正在从 JavaScript 迁移到 TypeScript 的 Express API 项目。

## 当前进度
- [x] 阶段1：测试安全网
- [x] 阶段2：安全修复
- [x] 阶段3：代码现代化
- [ ] 阶段4：TypeScript 迁移（进行中，已完成 8/15 个文件）
- [ ] 阶段5：架构优化
- [ ] 阶段6：完善与文档

## 已迁移的文件
- helpers/*.ts ✅
- models/user.ts ✅
- models/post.ts ✅
- middleware/auth.ts ✅

## 注意事项
- models/payment.js 中的 webhook 处理逻辑较复杂，暂不修改
- routes/legacy-api.js 将被废弃，不需要迁移
- 所有 Mongoose pre/post hooks 必须保留

## 代码规范
- 使用 async/await，不要使用回调
- 使用 const 优先，必要时 let，禁止 var
- 函数参数和返回值必须有类型注解