lnet_tutor/exam_system/USER_SYSTEM_GUIDE.md

# User System Guide

## ✅ User System Implemented!

The exam system now includes complete user management with:
- User registration
- User login/logout
- Exam history tracking
- Ability to retake exams
- View previous exam results

## Features

### 1. User Registration & Login

#### Registration
- Username (unique)
- Email (unique)
- Password (min 6 characters)
- Optional: First name, Last name

#### Login
- Username
- Password

### 2. Exam Management

#### Exam Status
- **Available**: Not yet started
- **In Progress**: Started but not submitted
- **Finished**: Submitted and completed

### 3. Exam History

- View all your exam attempts
- See submission timestamps
- View results for finished exams
- Retake any exam

### 4. Retake Functionality

- Click "Take Again" in history to retake any finished exam
- Creates a new attempt
- Previous attempts are preserved

## Using the System

### Step 1: Register or Login

Visit: **http://localhost/login**

**Register a new account:**
1. Click "Register here"
2. Fill in username, email, password
3. Click "Register"
4. Auto-login after registration

**Or login with existing account:**
- Username: `testuser`
- Password: `test123`

### Step 2: View Available Exams

Visit: **http://localhost**

You'll see:
- List of all published exams
- Status for each exam (Available, In Progress, Finished)
- "Start Exam" or "Continue" button

### Step 3: Take an Exam

1. Click "Start Exam" or "Continue"
2. Answer questions
3. System autosaves every 10 seconds
4. Submit when done

### Step 4: View History

Click "My History" in the header navigation

You'll see:
- All exams you've taken
- All attempts per exam
- Submission timestamps
- "View Results" button for finished attempts
- "Take Again" button to retake

### Step 5: View Results

Click "View Results" on any finished attempt

You'll see:
- All questions and your answers
- Correct answers (for auto-gradable questions)
- Submission details

### Step 6: Retake an Exam

1. Go to "My History"
2. Click "Take Again" on any exam
3. System creates a new attempt
4. Previous attempts are preserved

## API Endpoints

### Authentication
- `POST /api/auth/register/` - Register new user
- `POST /api/auth/login/` - Login
- `POST /api/auth/logout/` - Logout
- `GET /api/auth/me/` - Get current user

### Exams
- `GET /api/exams/` - List exams (with status per user)
- `GET /api/exams/{id}/` - Get exam details
- `POST /api/exams/{id}/attempt/` - Start/resume attempt
- `POST /api/exams/{id}/reset/` - Reset to allow retake

### Attempts
- `PUT /api/attempts/{id}/autosave/` - Autosave answers
- `POST /api/attempts/{id}/submit/` - Submit exam
- `GET /api/attempts/{id}/result/` - Get results

### History
- `GET /api/history/me/` - Get exam history

## Testing

### Test User Created
- Username: `testuser`
- Password: `test123`
- Email: `test@example.com`

### Test Flow

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

2. **List Exams:**
   ```bash
   curl -b cookies.txt http://localhost/api/exams/
   ```

3. **Start Exam:**
   ```bash
   curl -b cookies.txt -X POST http://localhost/api/exams/python-basics-v1/attempt/
   ```

4. **View History:**
   ```bash
   curl -b cookies.txt http://localhost/api/history/me/
   ```

## Data Storage

### User Data
- Stored in SQLite database: `exam_server/db.sqlite3`
- User authentication via Django

### Exam Attempts
- Stored in: `data/attempts/{userId}/{examId}/{attemptId}.json`
- Now uses numeric user IDs (1, 2, 3...) instead of "user_default"

### Output Bundles
- Stored in: `data/output/{examId}_{attemptId}.json`

### Manifest
- Updated to track finished exams per numeric user ID

## Browser Usage

### Navigation

**Header Menu:**
- "Exam System" logo (click to go home)
- "Login" (if not logged in)
- Username + "My History" + "Logout" (if logged in)

**Pages:**
- `/` - Exam list
- `/login` - Login/Register
- `/history` - Exam history
- `/exam/:id` - Exam player
- `/result/:id` - View results
- `/done/:id` - Submission confirmation

## Features Implemented

- [x] User registration
- [x] User login/logout
- [x] Session management
- [x] Exam status tracking per user
- [x] Exam history view
- [x] View previous results
- [x] Retake exams (unlimited)
- [x] Continue in-progress exams
- [x] Autosave with authentication
- [x] Submit with authentication
- [x] Protected API endpoints

## Next Steps

1. **Create more exams** in `data/input/`
2. **Take exams** with your user account
3. **View history** to see all attempts
4. **Retake exams** as many times as you want
5. **Compare results** across attempts

## Security Notes

- Passwords are hashed (Django's default)
- Session-based authentication
- CSRF protection enabled
- Authenticated endpoints check user ownership

## Troubleshooting

### Can't login
- Check username/password
- Verify user exists in database
- Check backend logs: `docker-compose logs exam_server`

### History is empty
- Take an exam first
- Verify exam was submitted successfully
- Check `data/attempts/` folder for your user ID

### Can't retake
- Click "Take Again" in history
- System creates new attempt automatically
- Previous attempts preserved

## Database Management

### List 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})")
```

### Create Admin User
```bash
docker-compose exec exam_server python manage.py createsuperuser
```

Then access admin at: http://localhost/admin

---

**Status:** ✅ Fully Functional
**Features:** Registration, Login, History, Retake, Results
**Ready to Use:** Yes!