# نمونه آزمون HTML - راهنمای ادغام
## بررسی کلی
فایل `sample_exam_template.html` یک نمونه کامل و کاربردی است که نحوه ارسال نتایج به سیستم آزمون خود را نشان می‌دهد.
---
## اجزای اصلی
### 1. **متغیر سراسری `window.EXAM_PLATFORM`**
سرور خودکار این متغیر را در تمام آزمون‌ها تزریق می‌کند:
```javascript
window.EXAM_PLATFORM = {
examId: 1,
submitUrl: '/exam/1/submit',
student: {
id: 5,
code: '1001',
firstName: 'محمد',
lastName: 'احمدی',
fullName: 'محمد احمدی',
grade: '10'
}
}
```
### 2. **فیلدهای ارسالی (POST)**
هنگام ثبت نتایج، این فیلدها ارسال می‌شوند:
```javascript
{
student: "محمد احمدی", // نام دانش‌آموز
student_code: "1001", // کد دانش‌آموز
score: "85.5", // نمره (0-100)
details: '{"1":"a","2":"b",...}', // پاسخ‌های خام
answers_json: '{...}', // داده‌های تفصیلی JSON
duration_seconds: 1245, // مدت زمان (ثانیه)
violations: 0 // تعداد تخلفات (اختیاری)
}
```
---
## چگونه آزمون خود را ایجاد کنید
### مرحله 1: تنظیم ساختار HTML
```html
نام آزمون
```
### مرحله 2: اضافه کردن سوالات
#### نوع 1: چندگزینه‌ای
```html
```
#### نوع 2: درست/نادرست
```html
```
#### نوع 3: پاسخ کوتاه
```html
```
#### نوع 4: پاسخ بلند
```html
```
### مرحله 3: جمع‌آوری و ارسال پاسخ‌ها
```javascript
function submitExam() {
// جمع‌آوری داده‌ها
const answers = {};
const form = document.getElementById('exam-form');
const formData = new FormData(form);
for (let [key, value] of formData.entries()) {
answers[key] = value;
}
// دریافت اطلاعات دانش‌آموز از سرور
const student = window.EXAM_PLATFORM.student;
const submitUrl = window.EXAM_PLATFORM.submitUrl;
// ارسال به سرور
const data = new FormData();
data.append('student', student.fullName);
data.append('student_code', student.code);
data.append('score', calculateScore(answers));
data.append('details', JSON.stringify(answers));
data.append('answers_json', JSON.stringify({
answers: answers,
timestamp: new Date().toISOString()
}));
data.append('duration_seconds', getElapsedTime());
fetch(submitUrl, {
method: 'POST',
body: data
})
.then(response => response.ok ?
window.location.href = '/student/dashboard' :
alert('خطا در ثبت نتایج')
);
}
```
---
## نمونه‌های عملی کامل
### مثال 1: آزمون ساده (3 سوال)
```html
آزمون فیزیک
آزمون فیزیک
```
### مثال 2: آزمون با تایمر (15 دقیقه)
```javascript
let examStartTime = Date.now();
const examDuration = 15 * 60 * 1000; // 15 دقیقه
function updateTimer() {
const elapsed = Date.now() - examStartTime;
const remaining = examDuration - elapsed;
if (remaining <= 0) {
document.getElementById('exam-form').submit();
return;
}
const minutes = Math.floor(remaining / 60000);
const seconds = Math.floor((remaining % 60000) / 1000);
document.getElementById('timer').textContent =
`${minutes}:${seconds < 10 ? '0' : ''}${seconds}`;
}
setInterval(updateTimer, 1000);
```
---
## بررسی آزمون‌های ثبت‌شده
### مشاهده نتایج در داشبورد مدیر
1. به `/admin/exams/1/report` بروید
2. نتایج تفصیلی و نمودار توزیع نمرات را مشاهده کنید
3. می‌توانید پاسخ‌های خام را در JSON مشاهده کنید
### دسترسی به داده‌های JSON
```javascript
// نمونه داده‌های ذخیره‌شده
{
"1": "a",
"2": "true",
"3": "محمد",
"4": "سوال چهار جواب داده شد"
}
```
---
## نکات اهم
### ✅ بهترین روش‌ها
- **استفاده از `window.EXAM_PLATFORM`**: این متغیر توسط سرور تزریق می‌شود
- **ارسال JSON**: `answers_json` را برای ذخیره پاسخ‌های تفصیلی استفاده کنید
- **محاسبه نمره**: نمره را در 0-100 محاسبه کنید
- **تایمر**: برای آزمون‌های زمان‌دار، مدت زمان را ثبت کنید
### ❌ بهترین روش‌های نه
- **استفاده URL ثابت**: همیشه از `window.EXAM_PLATFORM.submitUrl` استفاده کنید
- **ارسال بدون validation**: اطمینان حاصل کنید پاسخ‌ها معتبر هستند
- **موارد اختیاری را نادیده بگیرید**: `duration_seconds` و `violations` را ثبت کنید
---
## خطای رایج و حل‌های آن
### خطا: "window.EXAM_PLATFORM is undefined"
**علت**: آزمون بیرون از سیستم یا بدون سرور بارگذاری شده است
**حل**: تأیید کنید آزمون از طریق `/exam/{id}/start` باز شده است
### خطا: 404 در ارسال
**علت**: URL ارسال اشتباه است
**حل**: `window.EXAM_PLATFORM.submitUrl` را چاپ کنید و بررسی کنید
### خطا: CORS Error
**علت**: درخواست از دومین متفاوت
**حل**: اطمینان حاصل کنید که HTML و API یک دومین هستند
---
## فایل‌های مثال
- `sample_exam_template.html` - نمونه کامل (5 سوال)
- `exams/` - پوشه آزمون‌های HTML شما
---
## راهنمای ساخت آزمون در Word/PowerPoint و تبدیل به HTML
### روش 1: آنلاین
1. فایل خود را به Google Docs تبدیل کنید
2. `File > Download > Web Page (.html)` را انتخاب کنید
3. کد را برای یکپارچگی با سیستم ویرایش کنید
### روش 2: تولید با Python
```python
from docx import Document
doc = Document('exam.docx')
html = ""
with open('exam.html', 'w', encoding='utf-8') as f:
f.write(html)
```
---
## پشتیبانی
برای مسائل:
1. Console (`F12`) را بررسی کنید برای خطاها
2. Network tab را برای درخواست POST بررسی کنید
3. `window.EXAM_PLATFORM` را در Console لاگ کنید