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:

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

2. List Exams:

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

3. Start Exam:

   curl -b cookies.txt -X POST http://localhost/api/exams/python-basics-v1/attempt/
   

4. View History:

   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

• User registration
• User login/logout
• Session management
• Exam status tracking per user
• Exam history view
• View previous results
• Retake exams (unlimited)
• Continue in-progress exams
• Autosave with authentication
• Submit with authentication
• 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

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

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!