مرجع قرارداد و استاندارد results.json
در تمامی سوالاتی که از داوری خودکار خارجی (External Grading) استفاده میکنند، کانتینر ارزیابی باید در انتهای اجرای تستهای خود، نتیجه داوری را در فایلی استاندارد با فرمت JSON در مسیر /grade/results/results.json ذخیره کند. این سند مشخصات فنی کامل این فایل را تشریح میکند.
۱. ساختار جامع فایل results.json
{
"gradable": true,
"score": 0.85,
"message": "۸۵ درصد از تستها با موفقیت پاس شدند.",
"output": "لاگ متنی کامپایلر یا کنسول...\nCompilation succeeded with 0 warnings.",
"format_errors": [],
"tests": [
{
"name": "تست ۱: حالتهای پایه و ورودیهای متعارف",
"description": "بررسی مقادیر مثبت و آرایههای مرتب",
"points": 5,
"max_points": 5,
"output": "ورودی [1, 2, 3] -> خروجی صحیح بازگردانده شد.",
"message": "پاس شد."
},
{
"name": "تست ۲: تست مخفی زمان اجرا و حافظه",
"description": "بررسی پیچیدگی محاسباتی برای ورودیهای بزرگ",
"points": 0,
"max_points": 5,
"output": "TimeLimitExceeded: اجرای الگوریتم بیش از سقف مجاز ۲ ثانیه طول کشید.",
"message": "ناموفق (محدودیت زمانی رد شد)."
}
],
"images": [
{
"label": "نمودار مقایسه پاسخ دانشجو با مدل مرجع",
"url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."
}
]
}
۲. تشریح فیلدهای اصلی
| فیلد | نوع داده | وضعیت | توضیحات |
|---|---|---|---|
gradable |
بولین (true/false) |
اجباری | آیا پاسخ دانشجو قابل تصحیح بود؟ اگر false باشد، هیچ فرصتی از دانشجو کسر نمیشود. |
score |
عدد اعشاری (0.0 تا 1.0) |
اجباری | نمره کلی دانشجو به صورت درصدی. |
message |
رشته متنی | اختیاری | خلاصه پیام نهایی که با فونت برجسته در کارنامه نمایش مییابد. |
output |
رشته متنی | اختیاری | خروجی خام متنی (مانند لاگهای خطای کامپایلر یا Traceback). |
format_errors |
آرایهای از رشتهها | اختیاری | در صورت بروز خطای فرمتی، لیست پیامهای خطا برای نمایش به دانشجو. |
tests |
آرایهای از آبجکتها | اختیاری | لیست تفکیکی آزمونها، نمرات و بازخوردهای ریز هر تست. |
images |
آرایهای از آبجکتها | اختیاری | تصاویر نمودارها یا خروجیهای گرافیکی در قالب Base64. |
۳. تفاوت حیاتی gradable: false در برابر score: 0.0
-
حالت
gradable: false(پاسخ غیرقابل نمرهدهی):
اگر فایل ارسالی دانشجو اصلاً کامپایل نشود، نام کلاس اشتباه باشد یا فایل خالی ارسال شده باشد، گرایدر باید"gradable": falseبازگرداند. در این حالت:- کارنامه خطای کامپایل یا فرمت را نشان میدهد.
- هیچ تلاشی از تعداد دفعات مجاز دانشجو در آزمون کسر نمیگردد.
-
حالت
gradable: trueوscore: 0.0(پاسخ نادرست):
کد کامپایل شده اما در حل مسئله اشتباه کرده و تمام تستها رد شدهاند. در این حالت یک فرصت تلاش مصرف میشود.
۴. قواعد و الزامات پیادهسازی
- نمایش کامل نمرات تستها:
اگر در آرایهtests، حتی در یکی از تستها فیلدpointsیاmax_pointsفراموش شود، سامانه بخش ریزنمرات تستها را مخفی کرده و تنها نمره کلscoreرا نشان میدهد. - تستهای بدون نمره (
max_points: 0):
میتوانید برای نمایش گزارش سبک کدنویسی (Linter/PEP8) یا ارائه راهنماییهای تشخیصی، تستی باmax_points: 0تعریف کنید تا صرفاً جنبه آموزشی داشته باشد. - محدودیت حجم ۱ مگابایت:
حجم فایلresults.jsonنباید از ۱ مگابایت بیشتر شود. در صورت تولید لاگهای کنسول عظیم، حتماً خروجی را با برش متنی (Truncate) کوتاه نمایید.