PicAnalysis/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

**PicAnalysis** 是一个图片 OCR 与智能文档管理系统，支持从截图中提取文字、AI 智能分析标签分类，并将识别结果转化为待办事项或归档文档。

### 技术栈
- **前端**: React 19 + TypeScript + Vite + Tailwind CSS + Zustand + TanStack Query + React Router v7
- **后端**: Node.js + Express + TypeScript + Prisma ORM
- **数据库**: SQLite (开发) / PostgreSQL (生产)
- **认证**: JWT + bcrypt
- **测试**: Vitest (前端单元测试), Playwright (E2E 测试), Jest (后端测试)

## 开发命令

### 后端 (端口 4000)
```bash
cd backend
npm run dev        # 启动开发服务器 (tsx watch)
npm run build      # TypeScript 编译
npm run start      # 运行生产构建
npm run test       # 运行 Jest 测试
npm run test:watch # Jest 监视模式
npm run test:coverage # 测试覆盖率报告
npm run lint       # ESLint 检查
npm run lint:fix   # ESLint 自动修复
npm run prisma:generate # 生成 Prisma Client
npm run prisma:migrate   # 运行数据库迁移
npm run prisma:studio    # 打开 Prisma Studio
```

### 前端 (端口 3000)
```bash
cd frontend
npm run dev          # 启动 Vite 开发服务器
npm run build        # 构建生产版本
npm run preview      # 预览生产构建
npm run test         # 运行 Vitest 单元测试
npm run test:ui      # Vitest UI 界面
npm run test:coverage # Vitest 覆盖率报告
npm run test:e2e     # 运行 Playwright E2E 测试
npm run test:e2e:ui  # Playwright UI 模式
npm run lint         # ESLint 检查
```

### 数据库操作
```bash
cd backend
npx prisma db push    # 推送 schema 到数据库 (开发环境)
npx prisma migrate dev # 创建并应用迁移
npx prisma studio     # 可视化数据库管理界面
```

## 项目架构

### 后端架构
```
backend/src/
├── index.ts              # Express 应用入口，路由挂载
├── controllers/          # 请求处理器 (Auth, Document, Todo, Image)
├── services/             # 业务逻辑层
│   ├── auth.service.ts   # 认证逻辑 (注册/登录/验证)
│   ├── password.service.ts # 密码验证和强度检查
│   ├── ocr.service.ts    # OCR 处理逻辑（置信度验证、重试）
│   ├── document.service.ts # 文档 CRUD
│   ├── todo.service.ts   # 待办事项管理（三态工作流）
│   └── image.service.ts  # 图片上传和处理
├── routes/               # API 路由定义
├── middleware/           # 中间件 (JWT 认证)
└── lib/prisma.ts         # Prisma 客户端单例
```

**关键设计模式**:
- **分层架构**: Controller → Service → Prisma (数据层)
- **服务类**: 使用静态方法实现无状态业务逻辑
- **中间件**: JWT 认证中间件保护需要登录的路由

### 前端架构
```
frontend/src/
├── App.tsx               # 路由配置，受保护路由包装
├── main.tsx              # 应用入口
├── pages/                # 页面组件 (Login, Dashboard, Documents, Todos, Images)
├── components/           # 可复用 UI 组件 (Button, Input, Card, Layout)
├── services/             # API 服务层，与后端通信
│   └── api.ts            # Axios 封装，拦截器处理 token
├── hooks/                # React Hooks (useAuth, useDocuments, useTodos, useImages)
├── stores/               # Zustand 状态管理
│   ├── authStore.ts      # 认证状态持久化
│   └── uiStore.ts        # UI 状态（通知等）
└── types/                # TypeScript 类型定义
```

**关键设计模式**:
- **受保护路由**: `<ProtectedRoute>` 组件检查认证状态
- **状态管理**: Zustand 负责全局状态，TanStack Query 负责服务器状态
- **API 客户端**: Axios 拦截器自动添加 JWT token

### 数据模型
核心实体关系：
- **User** 拥有多个 Document, Todo, Image, Category, Tag
- **Document** 可关联多个 Image，可生成多个 Todo
- **Image** 的 `document_id` 可为空（支持 OCR 失败的待处理图片）
- **Todo** 有三种状态: `pending` → `completed` → `confirmed`

## 待办事项三态工作流

待办状态流转是核心业务逻辑：
1. **pending** (未完成) - 新创建的待办，进行中的任务
2. **completed** (已完成) - 用户标记完成，可撤销回 pending
3. **confirmed** (已确认) - 完成后经过确认归档，最终状态

相关 API:
- `PATCH /api/todos/:id/complete` - 标记完成
- `PATCH /api/todos/:id/confirm` - 确认归档
- `PATCH /api/todos/:id/reopen` - 撤销到未完成

## OCR 降级处理

当 OCR 置信度低于阈值 (默认 0.3) 时：
1. 图片保存到数据库，`processing_status = 'failed'`
2. 不自动创建文档
3. 用户可在"待处理图片列表"中手动处理

查询待处理图片：
```sql
SELECT * FROM images
WHERE user_id = ? AND (document_id IS NULL OR processing_status = 'failed')
```

## 测试策略

### 后端测试 (Jest)
- 单元测试覆盖所有 Service 类
- 集成测试验证 API 端点
- 目标覆盖率: 80%+

### 前端测试
- **Vitest**: 组件和服务的单元测试
- **Playwright**: E2E 测试，跨浏览器测试 (Chrome, Firefox, Safari)
- 测试文件位于 `e2e/` 目录

## API 端点

### 认证
- `POST /api/auth/register` - 用户注册
- `POST /api/auth/login` - 用户登录

### 文档
- `GET /api/documents` - 获取文档列表
- `POST /api/documents` - 创建文档
- `DELETE /api/documents/:id` - 删除文档

### 待办
- `GET /api/todos` - 获取待办列表（支持 status 参数筛选）
- `POST /api/todos` - 创建待办
- `PATCH /api/todos/:id/complete` - 标记完成
- `PATCH /api/todos/:id/confirm` - 确认归档
- `DELETE /api/todos/:id` - 删除待办

### 图片
- `POST /api/images/upload` - 上传图片
- `GET /api/images` - 获取图片列表

## 环境变量

后端需要创建 `.env` 文件：
```
DATABASE_URL="file:./dev.db"
JWT_SECRET="your-secret-key"
PORT=4000
```

## 测试账号

```
用户名: testuser
密码: Password123@
```

## 当前开发状态

已完成功能：
- ✅ 用户认证系统 (JWT)
- ✅ 文档 CRUD
- ✅ 待办三态工作流
- ✅ 图片上传和 OCR 状态追踪
- ✅ 前后端单元测试 (148 个测试全部通过)
- ✅ E2E 测试框架

待开发功能 (P1 优先级)：
- ⏳ OCR 集成 (Tesseract/PaddleOCR)
- ⏳ AI 分析功能 (GLM/MiniMax/DeepSeek)
- ⏳ 图片-文档-待办关联增强