lnet_tutor/exam_system/FINAL_GUIDE.md

# Exam System - Complete User Guide

## ✅ System is Fully Operational!

Your exam system now has complete user management and is ready to use.

## 🚀 Quick Start

### 1. Access the Application
Open your browser to: **http://localhost**

### 2. Register or Login

**Option A: Use Test Account**
- Username: `testuser`
- Password: `test123`

**Option B: Register New Account**
1. Go to: http://localhost/login
2. Click "Register here"
3. Fill in:
   - Username (unique)
   - Email (unique)
   - Password (min 6 chars)
   - Confirm password
4. Click "Register"
5. Auto-login after registration

### 3. Take an Exam

1. You'll see "Python Basics Exam" with status "available"
2. Click "Start Exam"
3. Answer questions (MCQ, True/False, Essay, Code)
4. System autosaves every 10 seconds
5. Watch the timer count down
6. Click "Submit Exam" when done
7. See success page

### 4. View Your History

1. Click "My History" in the header
2. See all your exam attempts
3. Click "View Results" to review answers
4. Click "Take Again" to retake any exam

## 📋 Features

### User Management
- ✅ User registration with email verification
- ✅ Secure login/logout
- ✅ Session persistence
- ✅ Password hashing

### Exam Taking
- ✅ List all published exams
- ✅ Exam status per user (available, in progress, finished)
- ✅ Start new attempts
- ✅ Resume in-progress attempts
- ✅ Timer with auto-submit
- ✅ Autosave every 10 seconds
- ✅ 5 question types supported

### Exam History
- ✅ View all your attempts per exam
- ✅ See submission timestamps
- ✅ View detailed results
- ✅ Compare answers with correct ones
- ✅ Retake any exam unlimited times

### Data Persistence
- ✅ User database (SQLite with persistent volume)
- ✅ Exam attempts in JSON files
- ✅ Output bundles for each submission
- ✅ Progress tracking per user

## 🎯 Complete Workflow

### As a New User

```
Register → Login → See Exams → Start Exam → 
Answer Questions → Submit → View Results → 
Check History → Retake if desired
```

### Navigation

**Header Menu:**
- "Exam System" - Go home
- "Login" - Login/register (if not logged in)
- "[Username]" - Shows your username
- "My History" - View exam history
- "Logout" - Logout

**Routes:**
- `/` - Exam list
- `/login` - Login/register
- `/history` - Your exam history
- `/exam/:id` - Take exam
- `/result/:id` - View results
- `/done/:id` - Submission confirmation

## 🧪 Testing the System

### Test Full Flow

```bash
# 1. Check system is running
docker-compose ps

# Should show 3 containers: exam_server, exam_web, exam_nginx

# 2. Open browser
open http://localhost

# 3. Register/Login
# Use testuser/test123 or create new account

# 4. Take exam
# Click "Start Exam" on Python Basics

# 5. Check data folders while taking exam
ls -la data/attempts/1/python-basics-v1/

# 6. Submit and check output
ls -la data/output/

# 7. View history
# Click "My History" in header

# 8. Retake
# Click "Take Again" on Python Basics
```

### API Testing

```bash
# Login
curl -c cookies.txt -X POST -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"test123"}' \
  http://localhost/api/auth/login/

# List exams
curl -b cookies.txt http://localhost/api/exams/

# View history
curl -b cookies.txt http://localhost/api/history/me/
```

## 📊 Data Structure

### Database (Persistent)
- Location: Docker volume `exam_system_db_data`
- Contains: Users, sessions
- Persists across restarts

### File System
```
data/
├── input/                    # Source exam JSON files
│   └── python-basics-v1.json
├── attempts/{userId}/{examId}/
│   └── {attemptId}.json     # Active attempts
├── output/
│   └── {examId}_{attemptId}.json  # Final bundles
├── progress/
│   └── {userId}.json        # Progress snapshots
└── manifest.json            # Exam registry
```

### User IDs
- Authenticated users: numeric IDs (1, 2, 3...)
- Guest users: `guest_` prefix (for backward compatibility)

## 🔧 Administration

### Create Admin User

```bash
docker-compose exec exam_server python manage.py createsuperuser
```

Access admin at: **http://localhost/admin**

### List All Users

```bash
docker-compose exec exam_server python manage.py shell
>>> from django.contrib.auth import get_user_model
>>> User = get_user_model()
>>> for u in User.objects.all():
>>>     print(f"{u.id}: {u.username} - {u.email}")
```

### Reset User's Exam

```bash
# Via API (when logged in)
curl -b cookies.txt -X POST http://localhost/api/exams/python-basics-v1/reset/

# Or manually delete files
rm -rf data/attempts/1/python-basics-v1/*
```

## 🎨 Customization

### Add New Exam

1. Create exam JSON in `data/input/your-exam.json`
2. Follow format in `/docs/exam-format.md`
3. Update `data/manifest.json`:
   ```json
   {
     "exams": [
       ...,
       {
         "examId": "your-exam",
         "path": "input/your-exam.json",
         "published": true,
         "version": "1.0.0"
       }
     ]
   }
   ```
4. Refresh browser - new exam appears!

### Modify Exam Settings

Edit exam JSON in `data/input/`:
- Change duration
- Add/remove questions
- Adjust difficulty
- Update metadata

Changes take effect immediately (refresh browser).

## 🐛 Troubleshooting

### "Failed to load exams"

**Fix:**
```bash
# Restart backend
docker-compose restart exam_server

# Check logs
docker-compose logs exam_server

# Verify manifest exists
cat data/manifest.json
```

### "Can't login"

**Fix:**
```bash
# Verify user exists
docker-compose exec exam_server python manage.py shell
>>> from django.contrib.auth import get_user_model
>>> User = get_user_model()
>>> User.objects.all()

# Create new user if needed
>>> User.objects.create_user(username='user', email='user@example.com', password='pass123')
```

### "History is empty"

**Cause:** You haven't submitted any exams yet

**Solution:** Take and submit an exam first

### "Can't retake"

**Fix:**
1. Go to My History
2. Find the exam
3. Click "Take Again"
4. System resets and redirects to exam

### Database issues

**Complete reset:**
```bash
# Stop containers
docker-compose down -v

# This deletes the database volume
# Then start fresh
docker-compose up --build -d

# Run migrations
docker-compose exec exam_server python manage.py migrate

# Create test user
docker-compose exec exam_server python manage.py shell
>>> from django.contrib.auth import get_user_model
>>> User = get_user_model()
>>> User.objects.create_user(username='testuser', email='test@example.com', password='test123')
```

## 📈 What's Different from Before

### Before (Guest Mode)
- No user accounts
- Session-based with `user_default`
- Can't track individual users
- Can't distinguish attempts

### Now (User System)
- ✅ Individual user accounts
- ✅ Secure authentication
- ✅ Per-user exam history
- ✅ Unlimited retakes
- ✅ View all previous attempts
- ✅ Compare results across attempts

## 🎯 Use Cases

### Student
1. Register account
2. Take assigned exams
3. View results
4. Retake to improve score
5. Track progress over time

### Instructor (Future)
- View all student attempts
- Grade essay questions
- Export results
- Analyze performance

### Self-Learner
- Create own exams
- Test knowledge repeatedly
- Track improvement
- Review past performance

## 💾 Backup

### Backup User Database
```bash
# Export database
docker-compose exec exam_server python manage.py dumpdata > backup_users.json

# Or backup the volume
docker run --rm -v exam_system_db_data:/data -v $(pwd):/backup \
  alpine tar czf /backup/db_backup.tar.gz -C /data .
```

### Backup Exam Data
```bash
tar -czf backup_data_$(date +%Y%m%d).tar.gz data/
```

## 🔐 Security

- Passwords hashed with Django's PBKDF2
- Session cookies with CSRF protection
- User ownership verification on all endpoints
- Input validation on all forms

## 📱 Mobile Support

The UI is responsive and works on mobile browsers.

## ✨ Tips

1. **Use incognito window** to test multiple users simultaneously
2. **Check data folders** to see real-time file creation
3. **View browser console** (F12) to see API calls
4. **Check logs** if something doesn't work
5. **Restart containers** if behavior seems odd

## 🎉 You're All Set!

The system is complete and ready to use:
- ✅ User registration/login
- ✅ Exam taking with autosave
- ✅ Submit functionality working
- ✅ Exam history
- ✅ View results
- ✅ Unlimited retakes
- ✅ All data persisted

**Go to http://localhost and start learning!** 🚀

---

**Need Help?** Check:
- `SETUP.md` - Setup instructions
- `TESTING.md` - Testing guide
- `USER_SYSTEM_GUIDE.md` - User system details
- `TROUBLESHOOTING.md` - Common issues
- `/docs/` - Technical specifications