Claude Code遗留系统迁移与重构全实战

graph TD
    A[遗留代码库] --> B{迁移策略选择}
    B -->|大爆炸重写| C[高风险 高回报]
    B -->|Strangler Fig增量| D[低风险 持续交付]
    B -->|绞杀者+AI辅助| E[最优解: Claude Code]
    C --> F[失败率>70%]
    D --> G[安全渐进]
    E --> H[理解旧代码→特征测试→增量替换]
    H --> G

cd legacy-project/
claude

/init

# 项目概述

## 遗留系统概况
- 技术栈: Express 4 + MongoDB + EJS模板
- 起始年份: 2019
- 主要语言: JavaScript (ES5为主，部分ES6)
- 测试覆盖率: ~12% (仅集成测试)
- 最后一次框架升级: 2020年

## 架构说明
- 路由定义: routes/ 目录，每个文件对应一个资源
- 业务逻辑: 散落在路由回调中，无分层
- 数据访问: 直接在路由中调用MongoDB驱动
- 认证: 自定义session中间件，非Passport
- 配置: 硬编码在代码中 + .env混合

## 已知痛点
- callbacks地狱，无async/await
- 全局变量共享状态
- 无类型检查
- 错误处理不一致（部分throw，部分next(err)）
- 报表模块包含大量硬编码的客户专属逻辑

## 迁移目标
- [ ] Express 4 → Express 5 + TypeScript
- [ ] callbacks → async/await
- [ ] MongoDB驱动 → Mongoose ODM
- [ ] 测试覆盖率 → 70%+
- [ ] 引入分层架构（Controller/Service/Repository）

## 安全约束
- API接口签名不可变（有外部系统依赖）
- 报表模块最后迁移（业务逻辑最复杂）
- 每次迁移必须通过现有集成测试

## 构建与测试命令
- npm start (启动开发服务器)
- npm test (运行集成测试)
- npm run lint (ESLint检查)

请分析这个项目的完整架构：
1. 列出所有路由及其对应的处理函数
2. 识别所有数据库集合及其使用模式
3. 找出所有中间件及其执行顺序
4. 标记出最复杂的10个文件（按耦合度排序）
5. 识别隐式依赖和循环引用

请将上面的分析结果保存为 docs/architecture-map.md

分析 routes/ 和 models/ 之间的所有依赖关系，
用Mermaid图表示出来，标注每个依赖的类型（数据访问、函数调用、共享状态）

graph LR
    subgraph "路由层"
        R1[routes/users.js]
        R2[routes/orders.js]
        R3[routes/reports.js]
        R4[routes/auth.js]
    end
    subgraph "数据层(无抽象)"
        DB[(MongoDB直接调用)]
        M1[models/user.js]
        M2[models/order.js]
    end
    subgraph "共享状态(风险)"
        G1[全局config对象]
        G2[全局cache对象]
    end

    R1 -->|直接查询| DB
    R1 -->|引用| M1
    R2 -->|直接查询| DB
    R2 -->|引用| M2
    R3 -->|直接查询| DB
    R3 -->|读取| G1
    R3 -->|读取| G2
    R4 -->|直接查询| DB
    R1 -.->|共享| G2
    R2 -.->|共享| G1

    style G1 fill:#ff6b6b,color:#fff
    style G2 fill:#ff6b6b,color:#fff
    style R3 fill:#ffd93d

请为 routes/users.js 中的每个路由处理函数生成特征测试。
要求：
1. 测试文件放在 test/characterization/ 目录
2. 使用 supertest + jest
3. 记录当前API的实际响应（状态码、响应体结构、响应时间）
4. 不做任何断言修改——只记录事实
5. 使用真实数据库的snapshot数据（test/fixtures/）

// test/characterization/users.test.js
const request = require('supertest');
const app = require('../../app');

describe('GET /api/users - 特征测试 (勿修改)', () => {
  test('返回200和用户列表数组', async () => {
    const response = await request(app)
      .get('/api/users')
      .set('Authorization', 'Bearer test-token-admin');

    // 特征记录：实际行为快照
    expect(response.status).toBe(200);
    expect(response.body).toHaveProperty('users');
    expect(Array.isArray(response.body.users)).toBe(true);
    // 注意：分页参数返回为字符串而非数字（已知遗留问题）
    expect(response.body.page).toBe('1'); // 字符串'1'而非数字1
    expect(response.body.total).toBeGreaterThanOrEqual(0);
  });

  test('无token返回401', async () => {
    const response = await request(app)
      .get('/api/users');
    expect(response.status).toBe(401);
    // 特征记录：错误响应使用 legacy 格式
    expect(response.body).toHaveProperty('error');
    expect(response.body).toHaveProperty('code', 'AUTH_FAILED');
  });

  test('page参数超过范围时返回空数组而非404', async () => {
    const response = await request(app)
      .get('/api/users?page=99999')
      .set('Authorization', 'Bearer test-token-admin');

    expect(response.status).toBe(200);
    expect(response.body.users).toEqual([]);
    // 关键发现：page=99999不报错，返回空——外部系统依赖此行为
  });
});

npx jest test/characterization/ --verbose

PASS test/characterization/users.test.js
  GET /api/users - 特征测试 (勿修改)
    ✓ 返回200和用户列表数组 (145 ms)
    ✓ 无token返回401 (32 ms)
    ✓ page参数超过范围时返回空数组而非404 (28 ms)

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total

请按照上面的模式，为以下所有路由模块生成特征测试：
1. routes/orders.js
2. routes/auth.js
3. routes/products.js
4. routes/reports.js (这个最复杂，请特别关注边缘情况)

每个模块的测试必须覆盖：
- 正常请求路径
- 认证失败
- 参数验证
- 错误处理路径
- 任何你发现的"意外行为"（在注释中标注）

请创建 test/fixtures/ 目录，为每个集合生成测试数据快照。
数据量控制在每集合20-50条记录，覆盖所有已知的字段变体。

请分析项目中所有模块之间的依赖关系，按以下维度评分（1-10）：
1. 入度（被多少模块依赖）
2. 出度（依赖多少模块）
3. 变更频率（git log统计）
4. 测试覆盖率
5. 业务关键度

输出为一个Markdown表格，按综合风险分排序

graph TD
    subgraph "Phase 1: 基础层（低风险高价值）"
        P1A[utils/db.js → Mongoose封装]
        P1B[utils/cache.js → Redis封装]
        P1C[middleware/auth.js → JWT标准化]
    end
    subgraph "Phase 2: 业务路由层"
        P2A[routes/users.js → TypeScript]
        P2B[routes/orders.js → TypeScript]
        P2C[routes/products.js → TypeScript]
    end
    subgraph "Phase 3: 复杂模块（最后攻坚）"
        P3A[routes/reports.js → 分层重构]
        P3B[共享状态清理]
    end

    P1A --> P2A
    P1A --> P2B
    P1B --> P2C
    P1C --> P2A
    P1C --> P2B
    P2A --> P3A
    P2B --> P3A
    P2C --> P3B

    style P1A fill:#4ecdc4,color:#fff
    style P1B fill:#4ecdc4,color:#fff
    style P1C fill:#4ecdc4,color:#fff
    style P3A fill:#ff6b6b,color:#fff
    style P3B fill:#ff6b6b,color:#fff

# 主分支保持稳定
git checkout main
git checkout -b migration/phase1-infrastructure

# 每个Phase完成后合并回main
# Phase内部使用短生命周期分支

请执行以下重构任务：

1. 在 src/repositories/ 创建 UserRepository.js
2. 从 routes/users.js 中提取所有MongoDB查询操作
3. 使用Mongoose模型替代原始MongoDB驱动调用
4. 确保所有特征测试仍然通过
5. 不改变任何API行为

约束：
- 保持函数签名不变
- 错误处理方式与原有一致
- 每完成一个函数，运行测试确认

// src/repositories/UserRepository.js
const mongoose = require('mongoose');

const UserSchema = new mongoose.Schema({
  username: { type: String, required: true },
  email: { type: String, required: true, unique: true },
  role: { type: String, enum: ['admin', 'user', 'viewer'], default: 'user' },
  createdAt: { type: Date, default: Date.now },
  // 保留遗留字段（即使不在schema中，也允许存在）
}, { strict: false }); // strict:false 确保兼容遗留数据

const User = mongoose.model('User', UserSchema);

class UserRepository {
  async findAll({ page = 1, limit = 20 } = {}) {
    // 特征保持：page参数作为字符串传入（遗留兼容）
    const skip = (parseInt(page) - 1) * limit;
    const [users, total] = await Promise.all([
      User.find({}).skip(skip).limit(limit).lean(),
      User.countDocuments({})
    ]);
    return {
      users,
      page: String(page), // 保持字符串返回
      total,
      totalPages: Math.ceil(total / limit)
    };
  }

  async findById(id) {
    return User.findById(id).lean();
  }

  async findByEmail(email) {
    return User.findOne({ email }).lean();
  }
}

module.exports = new UserRepository();

请修改 routes/users.js，将直接MongoDB调用替换为 UserRepository 的方法调用。
要求：
1. 逐个函数替换，每次替换后运行测试
2. 保持所有错误处理路径不变
3. 删除不再使用的旧代码
4. 添加 @migration 标记注释

// routes/users.js (Phase 1 迁移后)
const express = require('express');
const router = express.Router();
const auth = require('../middleware/auth');
const UserRepository = require('../repositories/UserRepository'); // @migration: 新增

// @migration: 原始MongoDB查询已提取到UserRepository
router.get('/api/users', auth.requireAuth, async (req, res) => {
  try {
    const result = await UserRepository.findAll({
      page: req.query.page,
      limit: req.query.limit
    });
    res.json(result);
  } catch (error) {
    // 保持原有错误格式
    res.status(500).json({ error: error.message, code: 'DB_ERROR' });
  }
});

module.exports = router;

# 运行特征测试——确保行为未变
npx jest test/characterization/ --verbose

# 运行所有测试
npm test

# 检查代码覆盖率变化
npx jest --coverage --coverageReporters=text-summary

请对比迁移前后的测试结果：
1. 所有特征测试是否全部通过？
2. 是否有任何响应字段发生变化？
3. 错误处理路径是否完整保留？
4. 列出所有 @migration 标记的位置

graph TB
    MAIN[main分支<br/>稳定基准] --> WT1[worktree: migrate-orders<br/>Claude会话1]
    MAIN --> WT2[worktree: migrate-products<br/>Claude会话2]
    MAIN --> WT3[worktree: migrate-auth<br/>Claude会话3]

    WT1 -->|PR #1| REVIEW1[Code Review]
    WT2 -->|PR #2| REVIEW2[Code Review]
    WT3 -->|PR #3| REVIEW3[Code Review]

    REVIEW1 --> MERGE[合并到main]
    REVIEW2 --> MERGE
    REVIEW3 --> MERGE

# 终端1：迁移orders模块
cd legacy-project/
git worktree add .claude/worktrees/migrate-orders -b migrate-orders
cd .claude/worktrees/migrate-orders
claude

# 终端2：迁移products模块
cd legacy-project/
git worktree add .claude/worktrees/migrate-products -b migrate-products
cd .claude/worktrees/migrate-products
claude

# 终端3：迁移auth模块
cd legacy-project/
git worktree add .claude/worktrees/migrate-auth -b migrate-auth
cd .claude/worktrees/migrate-auth
claude

你正在一个隔离的worktree中工作。任务：迁移 routes/orders.js

## 上下文
- 请先读取 CLAUDE.md 了解项目结构
- Phase 1 已完成：数据库访问层已迁移到 repositories/
- 参考 routes/users.js 的迁移模式

## 具体步骤
1. 创建 src/repositories/OrderRepository.js
2. 提取所有MongoDB查询到Repository
3. 将callback模式改为async/await
4. 确保所有特征测试通过
5. 不修改API接口签名

## 完成标准
- npm test 全部通过
- 无ESLint错误
- 每个迁移点有 @migration 注释

# 合并第一个PR后
git checkout main
git merge migrate-orders

# 合并第二个时检查冲突
git merge migrate-products
# 如果有冲突，让Claude Code帮助解决：

claude -p "解决当前的git合并冲突。优先保留两个分支的功能代码，去除重复的import语句。合并后运行测试确认。"

请为 src/repositories/ 目录下的所有文件添加JSDoc类型注解。
要求：
1. 每个函数的参数和返回值都要有类型注解
2. 定义接口类型（用 @typedef）
3. 标注可能的 null/undefined 返回
4. 不改变运行时行为

/**
 * @typedef {Object} PaginatedResult
 * @property {Object[]} users - 用户列表
 * @property {string} page - 当前页码（字符串格式，遗留兼容）
 * @property {number} total - 总记录数
 * @property {number} totalPages - 总页数
 */

/**
 * 查询所有用户（分页）
 * @param {{ page?: string|number, limit?: number }} options
 * @returns {Promise<PaginatedResult>}
 */
async findAll({ page = 1, limit = 20 } = {}) {
  // ...
}

请将 UserRepository.js 转换为 TypeScript：
1. 文件重命名为 UserRepository.ts
2. JSDoc注解转为正式类型定义
3. 创建 src/types/ 目录存放共享类型
4. 确保 tsconfig.json 配置允许JS（allowJs: true）
5. 运行 tsc --noEmit 检查类型错误

gantt
    title 遗留系统迁移时间线（实际执行记录）
    dateFormat  YYYY-MM-DD
    axisFormat  %m/%d

    section Phase 0: 准备
    代码考古与架构分析           :done, p0a, 2026-03-01, 2d
    CLAUDE.md定制               :done, p0b, after p0a, 1d
    特征测试生成                 :done, p0c, after p0b, 3d

    section Phase 1: 基础层
    MongoDB→Mongoose封装         :done, p1a, 2026-03-08, 3d
    缓存层重构                   :done, p1b, after p1a, 2d
    认证中间件标准化             :done, p1c, after p1b, 2d

    section Phase 2: 路由层
    users模块迁移(Worktree 1)    :done, p2a, 2026-03-16, 2d
    orders模块迁移(Worktree 2)   :done, p2b, 2026-03-16, 3d
    products模块迁移(Worktree 3) :done, p2c, 2026-03-16, 2d
    合并集成                     :done, p2d, after p2b, 1d

    section Phase 3: 攻坚
    reports模块分层重构          :active, p3a, 2026-03-22, 5d
    共享状态清理                 :p3b, after p3a, 3d
    TypeScript迁移               :p3c, after p3b, 4d

    section Phase 4: 验证
    全面集成测试                 :p4a, after p3c, 2d
    性能基准对比                 :p4b, after p4a, 1d

# ===== Day 1-2: 代码考古 =====
claude  # 进入交互模式
> /init
> 分析项目架构，识别所有路由、模型、中间件
> 生成依赖热力图和迁移优先级

# ===== Day 3: 特征测试 =====
> 为所有路由生成特征测试
npx jest test/characterization/ --verbose
git add test/characterization/
git commit -m "feat: add characterization tests for all routes"

# ===== Day 4-6: Phase 1 基础层 =====
> 创建 repositories/UserRepository.js, 提取MongoDB查询
> 替换 routes/users.js 中的数据库调用
npx jest test/characterization/ --verbose  # 确认行为不变
git commit -m "refactor: extract UserRepository from routes"

# ===== Day 7-9: Phase 1 完成 =====
> 创建 repositories/OrderRepository.js, ProductRepository.js
> 重构 middleware/auth.js 使用JWT
npm test
git commit -m "refactor: complete infrastructure layer migration"

# ===== Day 10+: 并行Worktree =====
git worktree add .claude/worktrees/wt-orders -b feat/migrate-orders
git worktree add .claude/worktrees/wt-products -b feat/migrate-products
# 在每个worktree中启动独立的claude会话

# ===== 合并与验证 =====
git checkout main
git merge feat/migrate-orders
git merge feat/migrate-products
npm test

请按以下策略管理上下文：
1. 先读取 CLAUDE.md（始终保持在上下文中）
2. 只加载当前正在迁移的模块及其直接依赖
3. 每完成一个模块，总结关键决策到 CLAUDE.md
4. 用 /compact 命令压缩历史对话，保留关键上下文

请帮我找出 routes/reports.js 中所有的隐式行为：
1. 依赖全局变量的副作用
2. 依赖执行顺序的初始化逻辑
3. 未处理的错误被静默吞掉的情况
4. 依赖特定MongoDB版本的查询行为
5. 依赖时区的日期处理

# Phase开始前打标签
git tag pre-phase-1
git tag pre-phase-2

# 如果出问题，精确回滚
git reset --hard pre-phase-1

请检查最近的迁移是否引入了回归。对比特征测试结果：
1. 运行所有特征测试
2. 对比API响应与基线快照
3. 如果发现差异，列出具体变化
4. 生成回滚补丁（git revert格式）

## 迁移日志

### Phase 1 完成 (2026-03-10)
- UserRepository: 完成, 5个方法迁移
- OrderRepository: 完成, 8个方法迁移
- ProductRepository: 完成, 6个方法迁移
- 全局变量: cache对象已替换为Redis封装
- ⚠️ 注意: UserRepository.findAll() 的page参数仍返回字符串

### Phase 2 进行中 (2026-03-16)
- routes/users.js: ✅ 已迁移到TypeScript
- routes/orders.js: 🔄 进行中（Worktree: wt-orders）
- routes/products.js: 🔄 进行中（Worktree: wt-products）
- routes/reports.js: ⏳ 未开始（最高风险，最后处理）

### 已知遗留问题
- [ ] reports模块的"华东区域特殊折扣"逻辑需要业务确认
- [ ] auth中间件的token刷新机制需要重设计
- [ ] 部分EJS模板仍引用已删除的全局变量

# .github/workflows/migration-check.yml
name: Migration Safety Check

on: [pull_request]

jobs:
  characterization-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - name: Run characterization tests
        run: npx jest test/characterization/ --verbose --json --outputFile=results.json
      - name: Compare API responses
        run: |
          node scripts/compare-snapshots.js
      - name: Check coverage threshold
        run: |
          npx jest --coverage --coverageThreshold='{"global":{"branches":70,"functions":70,"lines":70}}'

  regression-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - name: API contract verification
        run: |
          npx newman run test/postman/legacy-api-collection.json