PicAnalysis/.project/development-plan.md

# TDD 开发计划 - 图片OCR与智能文档管理系统

## 项目信息
- **开始日期**: 2026-02-21
- **预计完成**: 2026-04-05 (6周)
- **团队规模**: 1-2人
- **开发方法**: TDD (测试驱动开发)
- **迭代方式**: 1周Sprint

---

## 开发原则

### TDD 核心原则
1. **测试先行**: 在写功能代码前先写测试
2. **小步迭代**: 每次只写一个测试和对应实现
3. **持续重构**: 保持代码的简洁和可维护
4. **快速反馈**: 测试必须快速运行

### Ralph Loop 原则
1. **持续反思**: 每个阶段都要问 @ralph
2. **质疑假设**: 不要理所当然，验证一切
3. **追求简洁**: 寻找最简单的解决方案
4. **学习改进**: 从每个实现中学习

### 代码质量标准
- 代码覆盖率: ≥ 80%
- 测试通过率: 100%
- ESLint: 0错误
- TypeScript: 0类型错误

---

## TDD 开发循环

```
┌─────────────────────────────────────┐
│ 1. 🔴 Red: 写一个失败的测试          │
│    @ralph 这个测试描述正确吗？        │
│    @ralph 是否覆盖了核心场景？        │
└──────────┬──────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│ 2. 🟢 Green: 写最小代码通过测试      │
│    @ralph 这是最简单的实现吗？        │
│    @ralph 有不必要的复杂度吗？        │
└──────────┬──────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│ 3. 🔵 Blue: 重构优化代码             │
│    @ralph 代码可以更简洁吗？          │
│    @ralph 有重复代码吗？             │
│    @ralph 命名是否清晰？             │
└──────────┬──────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│ 4. 提交代码                         │
│    @ralph 我完成了吗？还有遗漏吗？    │
│    @ralph 需要添加文档吗？           │
└──────────┬──────────────────────────┘
           ↓
      返回步骤 1 (下一个测试)
```

---

## Sprint 计划

### Sprint 1: 基础架构 (Days 1-5)

#### 任务 1.1: 项目初始化
**时间**: 0.5天
**依赖**: 无
**测试策略**:
- 单元测试: 构建配置正确
- 集成测试: 无

**Ralph 检查点**:
- 开始前: 我是否需要所有这些依赖？
- 实现中: 这个配置是否最小化？
- 完成后: 项目结构是否清晰？

**TDD 循环**:
```typescript
// 1. Red: 测试构建配置
describe('Build Config', () => {
  it('should compile TypeScript', () => {
    // 验证构建输出
  });

  it('should have correct dependencies', () => {
    // 验证package.json
  });
});
```

**验收标准**:
- [ ] 前端项目创建成功 (React + Vite)
- [ ] 后端项目创建成功 (Express + TypeScript)
- [ ] Prisma初始化完成
- [ ] 测试框架配置完成 (Jest + Vitest)
- [ ] Docker配置文件创建
- [ ] ESLint + Prettier配置

---

#### 任务 1.2: 数据库Schema设计
**时间**: 1天
**依赖**: 任务1.1
**测试策略**:
- 单元测试: Schema验证
- 集成测试: Migration成功

**Ralph 检查点**:
- 开始前: 数据模型是否完整？
- 实现中: 关系设计是否正确？
- 完成后: 是否考虑了索引优化？

**TDD 循环**:
```typescript
// 1. Red: 测试Schema
describe('Database Schema', () => {
  it('should create user with correct fields', async () => {
    const user = await prisma.user.create({
      data: { username: 'test', email: 'test@test.com', password_hash: 'hash' }
    });
    expect(user).toHaveProperty('id');
    expect(user).toHaveProperty('created_at');
  });

  it('should allow image without document', async () => {
    const image = await prisma.image.create({
      data: { user_id: userId, file_path: '/path', document_id: null }
    });
    expect(image.document_id).toBeNull();
  });

  it('should enforce unique username', async () => {
    await expect(
      prisma.user.create({
        data: { username: 'duplicate', ... }
      })
    ).rejects.toThrow();
  });
});
```

**验收标准**:
- [ ] Prisma Schema定义完成
- [ ] Migration成功执行
- [ ] 所有实体关系正确
- [ ] 索引定义完成
- [ ] Seed脚本创建

---

#### 任务 1.3: 用户认证系统
**时间**: 1.5天
**依赖**: 任务1.2
**测试策略**:
- 单元测试: 密码加密、JWT生成/验证
- 集成测试: 完整注册登录流程

**Ralph 检查点**:
- 开始前: 安全性考虑是否充分？
- 实现中: 密码存储是否安全？
- 完成后: Token过期是否正确处理？

**TDD 循环**:
```typescript
// 1. Red: 测试密码加密
describe('Password Service', () => {
  it('should hash password with bcrypt', async () => {
    const hash = await PasswordService.hash('password123');
    expect(hash).not.toBe('password123');
    expect(hash.length).toBe(60);
  });

  it('should verify correct password', async () => {
    const hash = await PasswordService.hash('password123');
    const isValid = await PasswordService.verify('password123', hash);
    expect(isValid).toBe(true);
  });

  it('should reject wrong password', async () => {
    const hash = await PasswordService.hash('password123');
    const isValid = await PasswordService.verify('wrong', hash);
    expect(isValid).toBe(false);
  });
});

// 1. Red: 测试JWT
describe('Auth Service', () => {
  it('should generate valid JWT token', () => {
    const token = AuthService.generateToken({ user_id: '123' });
    expect(token).toBeTruthy();
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    expect(decoded.user_id).toBe('123');
  });

  it('should verify valid token', () => {
    const token = AuthService.generateToken({ user_id: '123' });
    const payload = AuthService.verifyToken(token);
    expect(payload.user_id).toBe('123');
  });

  it('should reject expired token', () => {
    const expiredToken = '...';
    expect(() => AuthService.verifyToken(expiredToken))
      .toThrow('Token expired');
  });
});
```

**验收标准**:
- [ ] 密码使用bcrypt加密
- [ ] JWT生成和验证正确
- [ ] 注册API完成
- [ ] 登录API完成
- [ ] 认证中间件完成
- [ ] 数据隔离验证通过

---

#### 任务 1.4: 基础API框架
**时间**: 1天
**依赖**: 任务1.3
**测试策略**:
- 单元测试: 路由注册
- 集成测试: API调用

**Ralph 检查点**:
- 开始前: API设计是否RESTful？
- 实现中: 错误处理是否统一？
- 完成后: 响应格式是否一致？

**TDD 循环**:
```typescript
// 1. Red: 测试API响应格式
describe('API Response Format', () => {
  it('should return success response', async () => {
    const response = await request(app)
      .post('/api/auth/register')
      .send({ username: 'test', password: 'pass123' });

    expect(response.status).toBe(201);
    expect(response.body).toHaveProperty('success', true);
    expect(response.body).toHaveProperty('data');
  });

  it('should return error response', async () => {
    const response = await request(app)
      .post('/api/auth/register')
      .send({ username: '', password: '' });

    expect(response.status).toBe(400);
    expect(response.body).toHaveProperty('success', false);
    expect(response.body).toHaveProperty('error');
  });
});
```

**验收标准**:
- [ ] 统一响应格式
- [ ] 错误处理中间件
- [ ] 请求验证中间件
- [ ] CORS配置
- [ ] 日志中间件

---

#### 任务 1.5: Docker配置
**时间**: 0.5天
**依赖**: 任务1.4
**测试策略**:
- 集成测试: 容器构建和运行

**Ralph 检查点**:
- 开始前: 需要多少容器？
- 实现中: 网络配置是否正确？
- 完成后: 数据卷是否持久化？

**验收标准**:
- [ ] Dockerfile创建 (前后端)
- [ ] docker-compose.yml配置
- [ ] 一键启动脚本
- [ ] 数据卷配置

---

### Sprint 2: 图片与OCR功能 (Days 6-12)

#### 任务 2.1: 图片上传功能
**时间**: 1天
**依赖**: Sprint 1
**测试策略**:
- 单元测试: 文件验证、大小限制
- 集成测试: 上传API

**Ralph 检查点**:
- 开始前: 安全性考虑（文件类型验证）？
- 实现中: 存储路径是否安全？
- 完成后: 大文件处理是否正确？

**TDD 循环**:
```typescript
// 1. Red: 测试文件验证
describe('Image Upload Service', () => {
  it('should accept valid image formats', () => {
    expect(ImageValidator.isValidFormat('image/jpeg')).toBe(true);
    expect(ImageValidator.isValidFormat('image/png')).toBe(true);
  });

  it('should reject invalid formats', () => {
    expect(ImageValidator.isValidFormat('application/pdf')).toBe(false);
    expect(ImageValidator.isValidFormat('text/plain')).toBe(false);
  });

  it('should reject files larger than 10MB', () => {
    const largeFile = { size: 11 * 1024 * 1024 };
    expect(ImageValidator.isValidSize(largeFile)).toBe(false);
  });

  it('should accept files under 10MB', () => {
    const file = { size: 5 * 1024 * 1024 };
    expect(ImageValidator.isValidSize(file)).toBe(true);
  });
});
```

**验收标准**:
- [ ] 支持JPG/PNG/WEBP
- [ ] 文件大小验证 (<10MB)
- [ ] 文件类型验证
- [ ] 存储到正确路径
- [ ] 返回图片URL

---

#### 任务 2.2: OCR集成
**时间**: 2天
**依赖**: 任务2.1
**测试策略**:
- 单元测试: 置信度判断、质量检测
- 集成测试: OCR流程

**Ralph 检查点**:
- 开始前: OCR provider选择？
- 实现中: 失败处理是否完善？
- 完成后: 性能是否可接受？

**TDD 循环**:
```typescript
// 1. Red: 测试置信度判断
describe('OCR Service', () => {
  it('should create document when confidence > threshold', () => {
    const result = OCRService.shouldCreateDocument(0.8, 0.3);
    expect(result).toBe(true);
  });

  it('should not create document when confidence < threshold', () => {
    const result = OCRService.shouldCreateDocument(0.2, 0.3);
    expect(result).toBe(false);
  });

  it('should handle threshold boundary', () => {
    expect(OCRService.shouldCreateDocument(0.3, 0.3)).toBe(true);
    expect(OCRService.shouldCreateDocument(0.29, 0.3)).toBe(false);
  });
});

// 1. Red: 测试图片质量检测
describe('Image Quality Analyzer', () => {
  it('should detect clear image', () => {
    const result = QualityAnalyzer.analyze(clearImageBuffer);
    expect(result.quality).toBe('good');
    expect(result.score).toBeGreaterThan(0.7);
  });

  it('should detect blurry image', () => {
    const result = QualityAnalyzer.analyze(blurryImageBuffer);
    expect(result.quality).toBe('poor');
    expect(result.score).toBeLessThan(0.3);
  });
});
```

**验收标准**:
- [ ] OCR provider抽象层
- [ ] 本地OCR集成（可选）
- [ ] 云端OCR集成
- [ ] 置信度判断逻辑
- [ ] 失败时保存到待处理列表
- [ ] 异步处理队列

---

#### 任务 2.3: 待处理图片功能
**时间**: 1天
**依赖**: 任务2.2
**测试策略**:
- 单元测试: 查询逻辑
- 集成测试: API

**Ralph 检查点**:
- 开始前: 查询是否高效？
- 实现中: 是否考虑了分页？

**TDD 循环**:
```typescript
// 1. Red: 测试待处理图片查询
describe('Pending Images Service', () => {
  it('should return images without document', async () => {
    const images = await PendingImagesService.getByUserId(userId);
    images.forEach(img => {
      expect(img.document_id).toBeNull();
    });
  });

  it('should return failed OCR images', async () => {
    const images = await PendingImagesService.getByUserId(userId);
    images.forEach(img => {
      expect(['failed', 'pending']).toContain(img.processing_status);
    });
  });
});
```

**验收标准**:
- [ ] 待处理图片列表API
- [ ] 手动创建文档API
- [ ] 图片增强API
- [ ] 删除图片API

---

#### 任务 2.4: 文档管理
**时间**: 1.5天
**依赖**: 任务2.3
**测试策略**:
- 单元测试: CRUD操作
- 集成测试: 文档API

**Ralph 检查点**:
- 开始前: 数据验证是否充分？
- 实现中: 搜索功能是否高效？

**TDD 循环**:
```typescript
// 1. Red: 测试文档CRUD
describe('Document Service', () => {
  it('should create document from OCR result', async () => {
    const document = await DocumentService.createFromOCR({
      ocr_result: 'test text',
      image_id: 'img123',
      user_id: 'user123'
    });
    expect(document.content).toBe('test text');
  });

  it('should search documents by title', async () => {
    const results = await DocumentService.search('meeting');
    results.forEach(doc => {
      expect(doc.title.toLowerCase()).toContain('meeting');
    });
  });
});
```

**验收标准**:
- [ ] 文档CRUD API
- [ ] 文档搜索功能
- [ ] 文档-图片关联
- [ ] 文档列表分页

---

### Sprint 3: AI智能分析 (Days 13-19)

#### 任务 3.1: AI Provider抽象层
**时间**: 1天
**依赖**: Sprint 2
**测试策略**:
- 单元测试: Provider接口

**Ralph 检查点**:
- 开始前: 接口设计是否通用？
- 实现中: 错误处理是否统一？

**TDD 循环**:
```typescript
// 1. Red: 测试AI Provider接口
describe('AI Provider Interface', () => {
  it('should implement analyze method', async () => {
    const provider = new GLMProvider();
    const result = await provider.analyze('test content');
    expect(result).toHaveProperty('tags');
    expect(result).toHaveProperty('category');
  });

  it('should handle API errors gracefully', async () => {
    const provider = new GLMProvider();
    // Mock API failure
    jest.spyOn(provider, 'callAPI').mockRejectedValue(new Error('API Error'));
    await expect(provider.analyze('test')).rejects.toThrow();
  });
});
```

**验收标准**:
- [ ] AI Provider接口定义
- [ ] GLM集成
- [ ] MiniMax集成
- [ ] DeepSeek集成
- [ ] 统一错误处理

---

#### 任务 3.2: 智能标签生成
**时间**: 1.5天
**依赖**: 任务3.1
**测试策略**:
- 单元测试: 标签提取、新标签创建
- 集成测试: 标签API

**Ralph 检查点**:
- 开始前: 标签数量是否合适？
- 实现中: 新标签验证是否充分？

**TDD 循环**:
```typescript
// 1. Red: 测试标签生成
describe('Tag Generation Service', () => {
  it('should extract relevant tags', async () => {
    const result = await AIService.generateTags('会议记录：讨论项目进度和下一步计划');
    expect(result.tags).toContain('会议');
    expect(result.tags).toContain('项目');
  });

  it('should create new tag when needed', async () => {
    const existingTags = ['工作', '个人'];
    const result = await AIService.generateTags('发票报销：午餐费用', { existingTags });
    expect(result.new_tags).toContain('发票');
  });

  it('should limit tag count to 5', async () => {
    const result = await AIService.generateTags('long text...');
    expect(result.tags.length).toBeLessThanOrEqual(5);
  });
});
```

**验收标准**:
- [ ] AI生成标签
- [ ] 新标签创建
- [ ] 标签使用统计
- [ ] 常用标签优先展示

---

#### 任务 3.3: 智能分类与类型
**时间**: 1.5天
**依赖**: 任务3.2
**测试策略**:
- 单元测试: 分类推荐
- 集成测试: 分类API

**Ralph 检查点**:
- 开始前: 分类逻辑是否准确？
- 实现中: 新分类命名是否合理？

**TDD 循环**:
```typescript
// 1. Red: 测试分类推荐
describe('Category Suggestion Service', () => {
  it('should match existing category', async () => {
    const categories = ['会议记录', '学习笔记'];
    const result = await AIService.suggestCategory('今天开会讨论了项目进度', { categories });
    expect(result.category).toBe('会议记录');
    expect(result.is_new).toBe(false);
  });

  it('should create new category when no match', async () => {
    const categories = ['会议记录'];
    const result = await AIService.suggestCategory('发票号：123456 金额：100元', { categories });
    expect(result.is_new).toBe(true);
    expect(result.category).toBe('发票');
    expect(result.suggested_icon).toBeTruthy();
  });
});
```

**验收标准**:
- [ ] 匹配现有分类
- [ ] 创建新分类
- [ ] 推荐图标
- [ ] 分类使用统计

---

#### 任务 3.4: AI分析API
**时间**: 1天
**依赖**: 任务3.3
**测试策略**:
- 集成测试: 完整分析流程

**Ralph 检查点**:
- 开始前: API响应时间是否可接受？
- 实现中: 降级处理是否完善？

**验收标准**:
- [ ] 分析API
- [ ] 异步处理
- [ ] 轮询状态API
- [ ] 失败降级处理

---

### Sprint 4: 待办管理 (Days 20-26)

#### 任务 4.1: 待办CRUD
**时间**: 1天
**依赖**: Sprint 3
**测试策略**:
- 单元测试: CRUD操作
- 集成测试: 待办API

**TDD 循环**:
```typescript
// 1. Red: 测试待办创建
describe('Todo Service', () => {
  it('should create todo from document', async () => {
    const todo = await TodoService.createFromDocument({
      document_id: 'doc123',
      user_id: 'user123',
      title: '完成报告'
    });
    expect(todo.status).toBe('pending');
    expect(todo.document_id).toBe('doc123');
  });
});
```

**验收标准**:
- [ ] 待办CRUD API
- [ ] 优先级设置
- [ ] 截止日期设置
- [ ] 分类关联

---

#### 任务 4.2: 三状态流转
**时间**: 1.5天
**依赖**: 任务4.1
**测试策略**:
- 单元测试: 状态验证
- 集成测试: 状态流转API

**TDD 循环**:
```typescript
// 1. Red: 测试状态流转
describe('Todo Status Transition', () => {
  it('should allow pending to completed', () => {
    const result = TodoService.validateTransition('pending', 'completed');
    expect(result).toBe(true);
  });

  it('should allow completed to confirmed', () => {
    const result = TodoService.validateTransition('completed', 'confirmed');
    expect(result).toBe(true);
  });

  it('should not allow confirmed to pending', () => {
    const result = TodoService.validateTransition('confirmed', 'pending');
    expect(result).toBe(false);
  });

  it('should update timestamps', async () => {
    const todo = await TodoService.updateStatus(todoId, 'completed');
    expect(todo.completed_at).toBeTruthy();
  });
});
```

**验收标准**:
- [ ] 状态验证逻辑
- [ ] 时间戳自动更新
- [ ] 状态流转API
- [ ] 批量操作API

---

#### 任务 4.3: 待办列表与筛选
**时间**: 1天
**依赖**: 任务4.2
**测试策略**:
- 单元测试: 排序逻辑
- 集成测试: 列表API

**TDD 循环**:
```typescript
// 1. Red: 测试待办排序
describe('Todo Sorting', () => {
  it('should sort by priority then due date', () => {
    const todos = [
      { priority: 'high', due_date: '2024-01-15' },
      { priority: 'high', due_date: '2024-01-10' },
      { priority: 'medium', due_date: '2024-01-10' }
    ];
    const sorted = TodoService.sort(todos);
    expect(sorted[0].priority).toBe('high');
    expect(sorted[0].due_date).toBe('2024-01-10');
  });
});
```

**验收标准**:
- [ ] 三状态列表查询
- [ ] 多条件筛选
- [ ] 排序功能
- [ ] 分页支持

---

### Sprint 5: 前端开发 (Days 27-33)

#### 任务 5.1: 基础布局与路由
**时间**: 1天
**依赖**: Sprint 4
**测试策略**:
- 组件测试: 路由渲染

**验收标准**:
- [ ] 主布局组件
- [ ] 路由配置
- [ ] 导航组件
- [ ] 认证路由守卫

---

#### 任务 5.2: 认证页面
**时间**: 1天
**依赖**: 任务5.1
**测试策略**:
- 组件测试: 表单验证

**TDD 循环**:
```typescript
// 1. Red: 测试登录表单
describe('LoginForm', () => {
  it('should show error for empty fields', () => {
    render(<LoginForm />);
    fireEvent.click(screen.getByText('登录'));
    expect(screen.getByText('请输入用户名')).toBeTruthy();
  });

  it('should call API on valid input', async () => {
    const mockLogin = jest.fn();
    render(<LoginForm onLogin={mockLogin} />);
    // fill form and submit
    await waitFor(() => expect(mockLogin).toHaveBeenCalled());
  });
});
```

**验收标准**:
- [ ] 登录表单
- [ ] 注册表单
- [ ] 表单验证
- [ ] 错误提示

---

#### 任务 5.3: 图片上传组件
**时间**: 1.5天
**依赖**: 任务5.2
**测试策略**:
- 组件测试: 拖拽、选择、预览

**TDD 循环**:
```typescript
// 1. Red: 测试图片上传
describe('ImageUpload', () => {
  it('should accept drag and drop', () => {
    const onUpload = jest.fn();
    render(<ImageUpload onUpload={onUpload} />);
    const dropZone = screen.getByTestId('drop-zone');

    fireEvent.drop(dropZone, {
      dataTransfer: { files: [new File([''], 'test.png', { type: 'image/png' })] }
    });

    await waitFor(() => expect(onUpload).toHaveBeenCalled());
  });
});
```

**验收标准**:
- [ ] 拖拽上传
- [ ] 文件选择
- [ ] 图片预览
- [ ] 进度显示
- [ ] 错误处理

---

#### 任务 5.4: OCR结果编辑器
**时间**: 1天
**依赖**: 任务5.3
**测试策略**:
- 组件测试: 文本编辑

**验收标准**:
- [ ] 文本编辑区域
- [ ] 图片预览
- [ ] 保存按钮
- [ ] AI分析按钮

---

#### 任务 5.5: 文档管理页面
**时间**: 1.5天
**依赖**: 任务5.4
**测试策略**:
- 组件测试: 列表、搜索、详情

**验收标准**:
- [ ] 文档列表
- [ ] 搜索功能
- [ ] 文档详情
- [ ] 编辑功能
- [ ] 删除功能

---

#### 任务 5.6: 待办管理页面
**时间**: 1.5天
**依赖**: 任务5.5
**测试策略**:
- 组件测试: 三状态列表、批量操作

**TDD 循环**:
```typescript
// 1. Red: 测试待办状态切换
describe('TodoList', () => {
  it('should show pending todos by default', () => {
    const todos = [{ id: 1, status: 'pending', title: 'Test' }];
    render(<TodoList todos={todos} />);
    expect(screen.getByText('Test')).toBeTruthy();
  });

  it('should move todo to completed on click', async () => {
    const onComplete = jest.fn();
    const todos = [{ id: 1, status: 'pending', title: 'Test' }];
    render(<TodoList todos={todos} onComplete={onComplete} />);

    fireEvent.click(screen.getByText('完成'));
    await waitFor(() => expect(onComplete).toHaveBeenCalledWith(1));
  });
});
```

**验收标准**:
- [ ] 三状态Tab
- [ ] 待办卡片
- [ ] 状态切换
- [ ] 批量操作
- [ ] 筛选排序

---

### Sprint 6: 完善与优化 (Days 34-40)

#### 任务 6.1: 配置管理页面
**时间**: 1天
**依赖**: Sprint 5
**验收标准**:
- [ ] OCR提供商配置
- [ ] AI提供商配置
- [ ] 配置测试功能

---

#### 任务 6.2: 待处理图片页面
**时间**: 1天
**依赖**: Sprint 5
**验收标准**:
- [ ] 待处理图片列表
- [ ] 手动创建对话框
- [ ] 图片增强功能

---

#### 任务 6.3: 性能优化
**时间**: 1.5天
**依赖**: 所有Sprint
**验收标准**:
- [ ] 前端代码分割
- [ ] 图片懒加载
- [ ] API响应缓存
- [ ] 数据库查询优化

---

#### 任务 6.4: 测试完善
**时间**: 1天
**依赖**: 所有Sprint
**验收标准**:
- [ ] E2E测试补充
- [ ] 覆盖率达到80%+
- [ ] 所有测试通过

---

#### 任务 6.5: 文档与部署
**时间**: 1.5天
**依赖**: 所有Sprint
**验收标准**:
- [ ] API文档
- [ ] 部署文档
- [ ] Docker镜像构建
- [ ] 一键部署验证

---

## 测试矩阵

| Sprint | 单元测试 | 集成测试 | E2E测试 | 覆盖率目标 |
|--------|---------|---------|---------|-----------|
| Sprint 1 | 20 | 5 | 0 | 80% |
| Sprint 2 | 35 | 10 | 3 | 80% |
| Sprint 3 | 40 | 8 | 2 | 80% |
| Sprint 4 | 30 | 8 | 4 | 85% |
| Sprint 5 | 25 | 5 | 8 | 75% |
| Sprint 6 | 7 | 0 | 2 | 80% |
| **总计** | **157** | **36** | **19** | **80%** |

---

## 技术栈

### 测试框架
- **后端单元**: Jest
- **后端集成**: Supertest
- **前端单元**: Vitest
- **前端组件**: Testing Library
- **E2E**: Playwright

### 代码质量工具
- **Linter**: ESLint
- **Formatter**: Prettier
- **Type Check**: TypeScript
- **Coverage**: c8 / istanbul

---

## 每日流程

### 开发开始
```bash
# 1. 拉取最新代码
git pull

# 2. 运行所有测试确保通过
npm test

# 3. 查看任务列表
# @ralph 我今天要做什么？
```

### TDD 开发循环
```bash
# 1. 🔴 Red: 写失败的测试
# 创建测试文件，描述期望行为

# 2. 🟢 Green: 写最小代码通过
# 实现功能，不考虑代码质量

# 3. 🔵 Blue: 重构优化
# 清理代码，提取抽象

# 4. 提交代码
git add .
git commit -m "feat: description"
```

### 开发结束
```bash
# 1. 运行所有测试
npm test

# 2. 检查覆盖率
npm run test:coverage

# 3. 提交代码
git push

# 4. @ralph 今天我学到了什么？
```

---

## Ralph Loop 检查清单

### 实现前
- @ralph 我是否完全理解了要实现的功能？
- @ralph 有什么边界情况我没考虑到？
- @ralph 这个设计是否遵循 SOLID 原则？
- @ralph 是否有更简单的实现方式？

### 实现中
- @ralph 这段代码是否容易理解？
- @ralph 变量/函数名是否清晰？
- @ralph 是否有重复代码？
- @ralph 这段代码性能如何？

### 实现后
- @ralph 所有测试都通过了吗？
- @ralph 代码可以更简洁吗？
- @ralph 是否需要添加文档？
- @ralph 我从这次实现中学到了什么？

---

## 风险和缓解

| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|----------|
| AI API不稳定 | 测试失败 | 中 | 使用Mock，减少真实调用 |
| OCR耗时 | 测试慢 | 高 | 使用预设结果 |
| 时间估算偏差 | 延期 | 中 | 预留20%缓冲时间 |
| 需求变更 | 返工 | 低 | 快速反馈，小步迭代 |

---

## 成功指标

### 质量指标
- 代码覆盖率: ≥ 80%
- 测试通过率: 100%
- TypeScript错误: 0
- ESLint错误: 0

### 流程指标
- 每日提交次数: ≥ 5
- 代码审查时间: < 24小时
- Bug修复时间: < 4小时

---

## 下一步

开发计划已制定完成。下一步：

1. **查看Sprint详细计划** - 每个Sprint的具体任务
2. **生成测试骨架** - 创建测试文件模板
3. **开始开发** - 执行第一个TDD循环

```bash
# 查看Sprint 1详细计划
cat .project/sprints/sprint-1.md

# 开始开发
cd backend && npm test
```