رفتن به متن
باغ ریاضی
results-json-reference
تنظیمات مطالعه
تنظیمات مطالعه

results-json-reference

مستندات اشتراکی · داکیومنت سامانه آزمون آنلاین

مرجع قرارداد و استاندارد 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 بازگرداند. در این حالت:

    1. کارنامه خطای کامپایل یا فرمت را نشان می‌دهد.
    2. هیچ تلاشی از تعداد دفعات مجاز دانشجو در آزمون کسر نمی‌گردد.
  • حالت gradable: true و score: 0.0 (پاسخ نادرست):
    کد کامپایل شده اما در حل مسئله اشتباه کرده و تمام تست‌ها رد شده‌اند. در این حالت یک فرصت تلاش مصرف می‌شود.


۴. قواعد و الزامات پیاده‌سازی

  1. نمایش کامل نمرات تست‌ها:
    اگر در آرایه tests، حتی در یکی از تست‌ها فیلد points یا max_points فراموش شود، سامانه بخش ریزنمرات تست‌ها را مخفی کرده و تنها نمره کل score را نشان می‌دهد.
  2. تست‌های بدون نمره (max_points: 0):
    می‌توانید برای نمایش گزارش سبک کدنویسی (Linter/PEP8) یا ارائه راهنمایی‌های تشخیصی، تستی با max_points: 0 تعریف کنید تا صرفاً جنبه آموزشی داشته باشد.
  3. محدودیت حجم ۱ مگابایت:
    حجم فایل results.json نباید از ۱ مگابایت بیشتر شود. در صورت تولید لاگ‌های کنسول عظیم، حتماً خروجی را با برش متنی (Truncate) کوتاه نمایید.

حالت ارائه