python-template/CLAUDE.md

# CLAUDE.md

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

## Project Overview

This is **学习助手 Pro** (Learning Assistant Pro), an intelligent exam paper management and learning tracking system built with FastAPI (backend) and Vue 3 (frontend). The system specializes in PDF exam paper processing, automatic question extraction using AI/OCR, mistake management, and personalized learning with spaced repetition algorithms.

### Core Features
- **PDF Processing**: High-speed PDF text extraction (0.01s/page) with 95%+ accuracy using hybrid text layer + OCR approach
- **Question Extraction**: AI-powered automatic question identification and extraction from exam papers
- **Mistake Management**: Ebbinghaus forgetting curve-based review system for mistake tracking
- **Word Learning**: SM-2 spaced repetition algorithm for English vocabulary learning
- **Analytics**: Comprehensive learning statistics and progress visualization

## Development Commands

### Quick Start
```bash
# Start both backend and frontend with provided script
./start.sh

# Check system status
./status.sh

# Stop all services
./stop.sh
```

### Backend Development (Python/FastAPI)
```bash
cd backend

# Install dependencies
pip install -r requirements.txt

# Start development server (port 8888)
python main.py
# OR
uvicorn main:app --host 0.0.0.0 --port 8888 --reload

# View API documentation
# Open http://localhost:8888/docs in browser
```

### Frontend Development (Vue 3/Vite)
```bash
cd frontend

# Install dependencies
npm install

# Start development server (auto-selects port, typically 3000-3002)
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview
```

### Database Operations
```bash
cd backend

# Initialize database with default data
python main.py  # Database auto-creates on first run

# Migrate database (if schema changes)
python migrate_db.py
```

## Architecture Overview

### Backend Architecture (FastAPI)
- **Main Application**: `backend/main.py` - Single-file FastAPI application with all API endpoints
- **Database**: SQLite with SQLAlchemy ORM (easily upgradeable to PostgreSQL)
- **Authentication**: JWT-based with bcrypt password hashing
- **File Processing**: Specialized PDF processing modules in `backend/pdf_splitter_*.py`
- **Upload Storage**: Local file storage in `backend/uploads/` directory

### Key Backend Components

#### PDF Processing Pipeline
The system uses a hybrid approach for PDF processing:
- **Primary**: Text layer extraction for maximum speed (0.01s/page)
- **Fallback**: OCR processing for scanned PDFs using EasyOCR
- **Main Module**: `backend/pdf_splitter_hybrid.py` - Intelligent PDF processor

#### Database Models
All models are defined in `backend/main.py`:
- **User Management**: `User`, `UserWordProgress`
- **Word Learning**: `Word`, spaced repetition with SM-2 algorithm
- **Paper Management**: `Paper` with metadata and file references
- **Question Extraction**: `Question`, `QuestionCollection` with auto-extraction support
- **Mistake Tracking**: `Mistake`, `ReviewLog` with Leitner box system

#### API Structure
- **Authentication**: `/api/auth/*` - JWT-based login/register
- **Word Management**: `/api/words/*` - CRUD and spaced repetition learning
- **Paper Management**: `/api/papers/*` - PDF upload and management
- **Question Processing**: `/api/questions/*`, `/api/papers/{id}/split` - AI extraction
- **Mistake Review**: `/api/mistakes/*` - Leitner-based review system
- **Analytics**: `/api/dashboard`, `/api/stats` - Learning statistics

### Frontend Architecture (Vue 3)
- **Framework**: Vue 3 with Composition API
- **UI Library**: Element Plus for consistent design
- **State Management**: Pinia stores for auth and word data
- **Routing**: Vue Router with authentication guards
- **Build Tool**: Vite for fast development and building

#### Key Frontend Components
- **Authentication**: `frontend/src/stores/auth.js` - JWT token management
- **Word Learning**: `frontend/src/stores/word.js` - Spaced repetition logic
- **Views**: Major application pages in `frontend/src/views/`
  - `MainDashboard.vue` - Main learning hub
  - `PaperViewer.vue` - PDF viewing and interaction
  - `Learning.vue` - Word learning interface
  - `MistakeReview.vue` - Review session interface

#### Routing Structure
- `/` - Main dashboard (requires auth)
- `/subjects/:subject` - Subject-specific paper listing
- `/papers/:id` - Paper detail view
- `/papers/:id/view` - PDF viewer with annotation support
- `/words` - Vocabulary learning interface
- `/review` - Mistake review sessions

## Development Guidelines

### Backend Development
- **Database Changes**: Add new models to `backend/main.py`, run `python migrate_db.py` if needed
- **New API Endpoints**: Add to `backend/main.py`, follow existing patterns
- **PDF Processing**: Extend `backend/pdf_splitter_hybrid.py` for new extraction features
- **Authentication**: Use `get_current_user()` dependency for protected routes

### Frontend Development
- **New Views**: Add to `frontend/src/views/` and register in `frontend/src/router/index.js`
- **State Management**: Add new stores in `frontend/src/stores/` following existing patterns
- **API Calls**: Use the existing API service pattern in stores
- **Authentication**: Route guards implemented in router, check `authStore.isAuthenticated`

### File Upload and Storage
- **Backend**: Files stored in `backend/uploads/{user_id}/`
- **PDF Processing**: Temporary files cleaned up automatically
- **Frontend**: File upload through drag-and-drop or click-to-upload interfaces

### Testing and Development
- **Backend Testing**: Use FastAPI's automatic docs at `/docs` for API testing
- **Frontend Testing**: Development server supports hot reload
- **PDF Processing**: Test files can be added to `backend/test_*.py` modules

## Performance Considerations

### PDF Processing
- The system achieves 2900x performance improvement through hybrid text/OCR approach
- Text layer extraction: 0.01s per page
- OCR fallback: Used only when text layer extraction fails
- Image extraction: Automatic correlation with question content

### Database Optimization
- SQLite for development/small deployments
- Easy migration path to PostgreSQL for production
- Indexes on frequently queried fields (user_id, subject, etc.)

### Frontend Performance
- Lazy loading of route components
- Efficient state management with Pinia
- Responsive design with mobile-first approach

## Deployment

### Development Environment
- Use `./start.sh` for easy development setup
- Backend runs on port 8888, frontend auto-selects port (3000-3002)
- Hot reload enabled for both frontend and backend

### Production Considerations
- Change `SECRET_KEY` in backend production
- Configure CORS origins for specific domains
- Set up proper file storage with backup
- Consider PostgreSQL for production database
- Configure HTTPS/reverse proxy with nginx

## Key Files to Understand

### Backend Core Files
- `backend/main.py` - Complete FastAPI application (1659 lines)
- `backend/pdf_splitter_hybrid.py` - PDF processing engine
- `backend/requirements.txt` - Python dependencies
- `backend/initial_words.csv` - Default English vocabulary data

### Frontend Core Files
- `frontend/src/App.vue` - Main application component with global styles
- `frontend/src/main.js` - Application bootstrap
- `frontend/src/router/index.js` - Route definitions and auth guards
- `frontend/src/stores/auth.js` - Authentication state management
- `frontend/src/views/MainDashboard.vue` - Primary user interface

### Utility Scripts
- `start.sh` - Development server startup script
- `status.sh` - System status checking script
- `stop.sh` - Service shutdown script

This system is designed for rapid development and deployment while maintaining high performance for PDF processing and excellent user experience for learning management.