به محتوای اصلی

بک‌اند آماده آکادمی آنلاین

دوره، سرفصل و درس، فروش دوره با کد تخفیف و پرداخت زرین‌پال، محتوای قفل‌شده برای ثبت‌نام‌کرده‌ها، پیشرفت، آزمون با تصحیح سمت سرور، نظر دانشجو و گواهی با کد قابل‌تأیید — بک‌اند کامل یک آکادمی، بی‌آنکه چیزی به آن اضافه کنید.

۱۵ روز اول رایگانبا پلنکاپوچینو

اعتبار هدیهٔ ثبت‌نام هزینه‌اش را می‌دهد؛ لازم نیست حتی یک تومان پرداخت کنید.

مناسب برای

  • آکادمی آنلاین با فروش دورهٔ ویدیویی
  • اپ موبایل آموزشی یا آزمون (Flutter / Kotlin / Swift / React Native)
  • دورهٔ رایگان یا پولی با آزمون پایانی و گواهی قابل‌تأیید

همان لحظهٔ ساخت، این‌ها در جدول هستند

دوره/v1/course
  • ساخت اپ فروشگاهی با Flutter۲٬۴۰۰٬۰۰۰ تومان
  • طراحی API برای اپ‌های موبایلمقدماتی
  • تحلیل داده با پایتون۱٬۸۰۰٬۰۰۰ تومان

۱۵ جدولورود کاربران۱۲ قانون۱۰ فانکشن۳۷ ردیف نمونه

با این قالب چه می‌شود ساخت

کارهایی که اپ یا سایت شما از روز اول روی همین بک‌اند انجام می‌دهد.

  • ویترین دوره‌ها با کلید عمومی

    دسته‌بندی، دوره، سرفصل، درس، آزمون، سؤال، نظرها و تنظیمات آکادمی عمومی‌اند؛ اپ پیش از ورود کاربر نشانشان می‌دهد. ویدیو و متن درس، پاسخ درست سؤال و یادداشت داخلی دوره هیچ‌وقت در پاسخ نیستند.

    GET /v1/course
  • ثبت‌نام دانشجو

    دانشجو با ایمیل و رمز ثبت‌نام می‌کند؛ از این به بعد ثبت‌نام، سفارش، پیشرفت، نمره و گواهی‌اش فقط برای خودش است.

    POST /v1/auth/signup
  • ثبت‌نام در دورهٔ رایگان

    با course_id فانکشن enroll_free را صدا بزنید؛ ثبت‌نام ساخته می‌شود و ایمیل خوش‌آمد برای دانشجو می‌رود. دورهٔ پولی رد می‌شود و صدا زدن دوباره همان ثبت‌نام را برمی‌گرداند. POST مستقیم به /v1/enrollment برای دانشجو بسته است.

    POST /v1/fn/enroll_free
  • خرید دوره

    با course_id (و در صورت نیاز coupon_code) فانکشن buy_course را صدا بزنید؛ سفارش «در انتظار پرداخت» با مبلغی که سرور از قیمت دوره و کد تخفیف حساب کرده برمی‌گردد.

    POST /v1/fn/buy_course
  • شروع پرداخت

    با order_id و callback_url فانکشن pay_start را صدا بزنید و کاربر را به payment_url بفرستید. پیش از آن مرچنت‌کد زرین‌پال را با نام ZARINPAL_MERCHANT_ID در secrets پروژه بگذارید. سفارش صفرتومانی بی‌درگاه پرداخت‌شده و ثبت‌نام می‌شود.

    POST /v1/fn/pay_start
  • تأیید پرداخت و ثبت‌نام

    صفحهٔ بازگشت، order_id و Authority و Status را از نشانی برمی‌دارد و به pay_verify می‌فرستد؛ سفارش «پرداخت‌شده» و دانشجو در دوره ثبت‌نام می‌شود. صدا زدن دوباره‌اش بی‌خطر است.

    POST /v1/fn/pay_verify
  • پخش درس

    با lesson_id فانکشن lesson_content را صدا بزنید تا video_url و body برگردد؛ درس پیش‌نمایش برای همه باز است و بقیه فقط برای ثبت‌نام‌کرده‌ها (بقیه ۴۰۳ می‌گیرند). GET هم کار می‌کند: /v1/fn/lesson_content?lesson_id=…

    POST /v1/fn/lesson_content
  • ثبت پیشرفت

    با lesson_id فانکشن complete_lesson را صدا بزنید؛ درس «تمام‌شده» ثبت و شمار درس‌های تمام‌شدهٔ ثبت‌نام به‌روز می‌شود. پیشرفت را مستقیم نمی‌شود نوشت.

    POST /v1/fn/complete_lesson
  • شرکت در آزمون

    سؤال‌ها را از /v1/question بخوانید و پاسخ‌ها را به شکل {"<question id>": شمارهٔ گزینه} با quiz_id به submit_quiz بفرستید؛ نمره و قبولی برمی‌گردد، پاسخ درست نه.

    POST /v1/fn/submit_quiz
  • صدور گواهی

    وقتی همهٔ درس‌ها تمام و همهٔ آزمون‌ها قبول شده، issue_certificate را با course_id و holder_name صدا بزنید؛ گواهی با کد یکتا صادر و برای دانشجو ایمیل می‌شود. پیش از آن می‌گوید چند درس و آزمون مانده.

    POST /v1/fn/issue_certificate
  • تأیید اصالت گواهی

    هر کسی، بی‌ورود و بی‌کلید، با code فانکشن verify_certificate را صدا می‌زند و فقط نام دارنده، عنوان دوره و تاریخ صدور را می‌گیرد. GET هم کار می‌کند: /v1/fn/verify_certificate?code=…

    GET /v1/fn/verify_certificate
  • نوشتن نظر

    دانشجوی ثبت‌نام‌کرده با course_id، rating (عدد صحیح ۱ تا ۵) و comment فانکشن add_review را صدا می‌زند؛ هر دوره یک نظر. ویرایش بعدی با PATCH /v1/review/{id} است.

    POST /v1/fn/add_review
  • لغو دسترسی یا استرداد

    با توکن مدیر یا کلید Production دو کار بکنید: ثبت‌نام را با PATCH /v1/enrollment/{id} و status: revoked لغو کنید (سفارش استردادشده را refunded و گواهی‌اش را revoked)، و یک ردیف access_block با student_id و course_id بسازید. بدون access_block، دانشجو ثبت‌نام خودش را حذف می‌کند و دوباره ثبت‌نام می‌کند؛ این ردیف را دانشجو نه می‌بیند نه حذف می‌کند، و همهٔ فانکشن‌ها آن را می‌سنجند.

    POST /v1/access_block
  • پاک کردن دادهٔ نمونه پیش از راه‌اندازی

    هر آکادمی تازه با دادهٔ نمونه ساخته می‌شود: کاربرهای student@example.com و admin@example.com، کد تخفیف زندهٔ PAEEZ20، گواهی AC-DEMO-7K2M که verify_certificate آن را اصیل نشان می‌دهد، سفارش AC-DEMO-0001 و سه دورهٔ نمونه. پیش از فروش واقعی همه را از پنل حذف کنید.

    DELETE /v1/coupon/{id}
  • ساخت دوره و درس از طرف آکادمی

    با توکن کاربر مدیر یا کلید Production، دوره، سرفصل، درس (با video_url و body)، آزمون و سؤال (با correct_option) بسازید؛ دانشجو هیچ‌کدام را نمی‌تواند بسازد یا تغییر دهد.

    POST /v1/lesson

داده‌ای که همان لحظه دارید

این ردیف‌ها با ساخت پروژه در جدول‌ها هستند. رکورد معمولی‌اند و هر وقت خواستید از پنل ویرایش یا پاکشان می‌کنید.

دسته‌بندی

۲ ردیف/v1/category
نامنشانیترتیب نمایش
برنامه‌نویسی موبایلmobile۱
بک‌اند و APIbackend۲

دوره

۳ ردیف/v1/course
عنوانقیمت (تومان)قیمت پیش از تخفیف (تومان)سطح
ساخت اپ فروشگاهی با Flutter۲٬۴۰۰٬۰۰۰۳٬۲۰۰٬۰۰۰متوسط
طراحی API برای اپ‌های موبایل۰—مقدماتی
تحلیل داده با پایتون۱٬۸۰۰٬۰۰۰—مقدماتی

سرفصل

۴ ردیف/v1/section
عنوانترتیب
شروع کار۱
ساخت فروشگاه۲
اصول طراحی۱

و ۱ ردیف دیگر

درس

۷ ردیف/v1/lesson
عنوانخلاصهترتیبمدت (دقیقه)
راه‌اندازی پروژه و ساختار پوشه‌هانصب ابزارها و چیدمانی که تا آخر دوره با آن کار می‌کنیم.۱۱۸
فهرست محصولات با بارگذاری تدریجیاتصال به API و مدیریت حالت بارگذاری و خطا.۲۳۲
سبد خرید و ثبت سفارشنگه‌داری سبد و ارسال سفارش به سرور.۳۴۱

و ۴ ردیف دیگر

آزمون

۲ ردیف/v1/quiz
عنواننمرهٔ قبولی (از ۱۰۰)سقف دفعات شرکتمهلت پاسخ (دقیقه، راهنمای اپ)
آزمون پایانی Flutter۷۰۳۱۰
آزمون طراحی API۶۰۳۵

سؤال

۵ ردیف/v1/question
متن سؤالترتیب
کدام ویجت برای فهرستی با بارگذاری تدریجی مناسب‌تر است؟۱
حالت سبد خرید را کجا نگه می‌داریم تا بین صفحه‌ها بماند؟۲
قیمت نهایی سفارش را چه کسی باید حساب کند؟۳

و ۲ ردیف دیگر

کد تخفیف

۱ ردیف/v1/coupon
عنوانمقدار (درصد یا تومان)نوعسقف دفعات استفاده
۲۰٪ تخفیف پاییزه۲۰درصدی۱۰۰

تنظیمات آکادمی

۱ ردیف/v1/academy_settings
نام آکادمیتلفنتلگراماینستاگرام
آکادمی کدنویس021-88005678codenevis_academycodenevis.academy

ثبت‌نام

۲ ردیف/v1/enrollment
عنوان دورهمبلغ پرداختی (تومان)راه ثبت‌ناموضعیت
ساخت اپ فروشگاهی با Flutter۲٬۴۰۰٬۰۰۰خریددر حال گذراندن
طراحی API برای اپ‌های موبایل۰دورهٔ رایگانتکمیل‌شده

سفارش دوره

۱ ردیف/v1/course_order
شمارهٔ سفارشقیمت دوره (تومان)تخفیف (تومان)مبلغ قابل پرداخت (تومان)
AC-DEMO-0001۲٬۴۰۰٬۰۰۰۰۲٬۴۰۰٬۰۰۰

پیشرفت درس

۴ ردیف/v1/lesson_progress
عنوان درس
راه‌اندازی پروژه و ساختار پوشه‌ها
فهرست محصولات با بارگذاری تدریجی
صفحه‌بندی: offset یا cursor؟

و ۱ ردیف دیگر

شرکت در آزمون

۲ ردیف/v1/quiz_attempt
عنوان آزموننمره (از ۱۰۰)پاسخ درستتعداد سؤال
آزمون پایانی Flutter۳۳۱۳
آزمون طراحی API۱۰۰۲۲

گواهی

۱ ردیف/v1/certificate
کد گواهیوضعیتنام دارندهعنوان دوره
AC-DEMO-7K2Mمعتبرمریم احمدیطراحی API برای اپ‌های موبایل

نظر دانشجو

۲ ردیف/v1/review
نظرنام نمایشیامتیاز (۱ تا ۵)
کوتاه و کاربردی؛ بخش صفحه‌بندی دقیقاً مشکلی بود که در اپ خودم داشتم.مریم۵
توضیح‌ها روشن است و پروژه واقعی؛ کاش درس سبد خرید کمی طولانی‌تر بود.مریم۴

جدول‌ها و دسترسی

هر جدول یک مسیر API دارد و از قبل مشخص است چه کسی می‌خواندش. فیلدهای هر جدول زیر همان جدول باز می‌شوند.

  • دسته‌بندی

    /v1/category

    عمومی: هر کسی می‌خواندش، حتی بدون ورود و با کلید عمومی داخل اپ.

    دسته‌بندی دوره‌ها — عمومی، برای منوی اپ

    ۳ فیلدو ۱ رابطه
    • nameناممتنضروری
    • slugنشانیمتنضروری
    • sort_orderترتیب نمایشعدد= 0
    • رابطه با دورهیک به چندcategory_id
  • دوره

    /v1/course

    عمومی: هر کسی می‌خواندش، حتی بدون ورود و با کلید عمومی داخل اپ.

    دوره‌ها — عمومی، ویترین آکادمی؛ فقط دورهٔ «منتشرشده» خریدنی است

    ۱۷ فیلدو ۵ رابطه
    • titleعنوانمتنضروریقابل جستجو
    • slugنشانیمتنضروری
    • summaryمعرفی کوتاهمتن
    • descriptionتوضیحاتمتن
    • coverتصویر دورهفایل
    • category_idدسته‌بندیمتن
    • levelسطحگزینه‌ای= "beginner"
    • priceقیمت (تومان)عددضروری
    • compare_at_priceقیمت پیش از تخفیف (تومان)عدد
    • languageزبان دورهگزینه‌ای= "fa"
    • duration_minutesمدت کل (دقیقه)عدد= 0
    • statusوضعیتگزینه‌ای= "draft"
    • instructor_nameمدرسمتن
    • instructor_bioدربارهٔ مدرسمتن
    • lesson_countتعداد درسعدد= 0
    • student_countتعداد دانشجوعدد= 0
    • internal_noteیادداشت داخلیمتنفقط مدیر
    • رابطه با دسته‌بندیچند به یکcategory_id
    • رابطه با سرفصلیک به چندcourse_id
    • رابطه با درسیک به چندcourse_id
    • رابطه با آزمونیک به چندcourse_id
    • رابطه با نظر دانشجویک به چندcourse_id
  • سرفصل

    /v1/section

    عمومی: هر کسی می‌خواندش، حتی بدون ورود و با کلید عمومی داخل اپ.

    فصل‌های هر دوره، به ترتیب — عمومی

    ۳ فیلدو ۲ رابطه
    • course_idدورهمتنضروری
    • titleعنوانمتنضروری
    • positionترتیبعددضروری
    • رابطه با دورهچند به یکcourse_id
    • رابطه با درسیک به چندsection_id
  • درس

    /v1/lesson

    عمومی: هر کسی می‌خواندش، حتی بدون ورود و با کلید عمومی داخل اپ.

    درس‌های هر دوره — عنوان و خلاصه عمومی‌اند تا خریدار بداند چه می‌خرد؛ ویدیو و متن درس فقط از فانکشن lesson_content

    ۹ فیلدو ۲ رابطه
    • course_idدورهمتنضروری
    • section_idسرفصلمتن
    • positionترتیبعددضروری
    • titleعنوانمتنضروری
    • summaryخلاصهمتن
    • duration_minutesمدت (دقیقه)عدد= 0
    • is_free_previewپیش‌نمایش رایگانبله/خیر= false
    • video_urlنشانی ویدیونشانی وبفقط مدیر
    • bodyمتن درسمتنفقط مدیر
    • رابطه با دورهچند به یکcourse_id
    • رابطه با سرفصلچند به یکsection_id
  • آزمون

    /v1/quiz

    عمومی: هر کسی می‌خواندش، حتی بدون ورود و با کلید عمومی داخل اپ.

    آزمون‌های هر دوره — عمومی؛ برای گرفتن گواهی، قبولی در همهٔ آزمون‌های دوره لازم است

    ۶ فیلدو ۲ رابطه
    • course_idدورهمتنضروری
    • titleعنوانمتنضروری
    • descriptionتوضیحاتمتن
    • pass_scoreنمرهٔ قبولی (از ۱۰۰)عدد= 70
    • max_attemptsسقف دفعات شرکتعدد= 3
    • time_limit_minutesمهلت پاسخ (دقیقه، راهنمای اپ)عدد= 0
    • رابطه با دورهچند به یکcourse_id
    • رابطه با سؤالیک به چندquiz_id
  • سؤال

    /v1/question

    عمومی: هر کسی می‌خواندش، حتی بدون ورود و با کلید عمومی داخل اپ.

    سؤال‌های چهارگزینه‌ای هر آزمون — متن و گزینه‌ها عمومی‌اند، پاسخ درست هرگز در پاسخ API نمی‌آید

    ۵ فیلدو ۱ رابطه
    • quiz_idآزمونمتنضروری
    • positionترتیبعددضروری
    • textمتن سؤالمتنضروری
    • optionsگزینه‌هاJSONضروری
    • correct_optionگزینهٔ درست (از ۰)عددضروریفقط مدیر
    • رابطه با آزمونچند به یکquiz_id
  • کد تخفیف

    /v1/coupon

    کاربران واردشده: هر کاربری که وارد شده باشد همه را می‌بیند.

    کدهای تخفیف خرید دوره — کاربر واردشده شرط‌ها را می‌بیند، خود کد را هیچ‌وقت

    ۹ فیلدو ۱ رابطه
    • titleعنوانمتنضروری
    • codeکدمتنضروریفقط مدیر
    • kindنوعگزینه‌ای= "percent"
    • valueمقدار (درصد یا تومان)عددضروری
    • course_idفقط برای دورهٔمتن
    • expires_atتاریخ انقضاتاریخ
    • usage_limitسقف دفعات استفادهعدد= 0
    • used_countدفعات استفاده‌شدهعدد= 0
    • activeفعالبله/خیر= true
    • رابطه با دورهچند به یکcourse_id
  • تنظیمات آکادمی

    /v1/academy_settings

    عمومی: هر کسی می‌خواندش، حتی بدون ورود و با کلید عمومی داخل اپ.

    یک ردیف: نام، لوگو، تماس و امضای گواهی — عمومی، برای سربرگ و پانویس اپ

    ۹ فیلد
    • academy_nameنام آکادمیمتنضروری
    • logoلوگوفایل
    • aboutدربارهٔ آکادمیمتن
    • phoneتلفنمتن
    • emailایمیلایمیل
    • telegramتلگراممتن
    • instagramاینستاگراممتن
    • certificate_signerامضاکنندهٔ گواهیمتن
    • termsقوانین و شرایطمتن
  • ثبت‌نام

    /v1/enrollment

    فقط صاحب ردیف: هر کاربر فقط ردیف‌های خودش را می‌بیند. مالکیت از روی student_id

    ثبت‌نام‌ها — فقط enroll_free و پرداخت تأییدشده می‌سازند؛ دانشجو فقط ثبت‌نام‌های خودش را می‌خواند

    ۱۰ فیلدو ۲ رابطه
    • student_idدانشجومتن
    • course_idدورهمتنضروری
    • course_titleعنوان دورهمتن
    • sourceراه ثبت‌نامگزینه‌ای= "manual"
    • order_idسفارشمتن
    • price_paidمبلغ پرداختی (تومان)عدد= 0
    • statusوضعیتگزینه‌ای= "active"
    • completed_lessonsدرس‌های تمام‌شدهعدد= 0
    • completed_atتاریخ اتمامتاریخ
    • enroll_keyکلید یکتاییمتنفقط مدیر
    • رابطه با کاربرچند به یکstudent_id
    • رابطه با دورهچند به یکcourse_id
  • سفارش دوره

    /v1/course_order

    فقط صاحب ردیف: هر کاربر فقط ردیف‌های خودش را می‌بیند. مالکیت از روی student_id

    خرید دوره — فقط buy_course می‌سازد و فقط پرداخت تأییدشده پرداخت‌شده‌اش می‌کند؛ خریدار فقط سفارش خودش را می‌خواند

    ۱۲ فیلدو ۲ رابطه
    • order_numberشمارهٔ سفارشمتن
    • student_idخریدارمتن
    • course_idدورهمتنضروری
    • course_titleعنوان دورهمتن
    • priceقیمت دوره (تومان)عددضروری
    • discountتخفیف (تومان)عدد= 0
    • amountمبلغ قابل پرداخت (تومان)عددضروری
    • coupon_codeکد تخفیفمتن
    • statusوضعیتگزینه‌ای= "pending"
    • paid_atزمان پرداختتاریخ
    • payment_authorityAuthority زرین‌پالمتنفقط مدیر
    • payment_refکد پیگیری پرداختمتن
    • رابطه با کاربرچند به یکstudent_id
    • رابطه با دورهچند به یکcourse_id
  • پیشرفت درس

    /v1/lesson_progress

    فقط صاحب ردیف: هر کاربر فقط ردیف‌های خودش را می‌بیند. مالکیت از روی student_id

    درس‌هایی که هر دانشجو تمام کرده — فقط complete_lesson می‌نویسد، فقط خود دانشجو می‌بیند

    ۶ فیلدو ۲ رابطه
    • student_idدانشجومتن
    • enrollment_idثبت‌ناممتن
    • course_idدورهمتنضروری
    • lesson_idدرسمتنضروری
    • lesson_titleعنوان درسمتن
    • progress_keyکلید یکتاییمتنفقط مدیر
    • رابطه با ثبت‌نامچند به یکenrollment_id
    • رابطه با درسچند به یکlesson_id
  • شرکت در آزمون

    /v1/quiz_attempt

    فقط صاحب ردیف: هر کاربر فقط ردیف‌های خودش را می‌بیند. مالکیت از روی student_id

    هر بار شرکت در آزمون با نمره‌اش — فقط submit_quiz می‌نویسد، فقط خود دانشجو می‌بیند

    ۱۰ فیلدو ۱ رابطه
    • student_idدانشجومتن
    • quiz_idآزمونمتنضروری
    • course_idدورهمتنضروری
    • quiz_titleعنوان آزمونمتن
    • scoreنمره (از ۱۰۰)عددضروری
    • correct_countپاسخ درستعدد= 0
    • question_countتعداد سؤالعدد= 0
    • passedقبولبله/خیر= false
    • answersپاسخ‌هاJSON
    • attempt_keyکلید یکتاییمتنفقط مدیر
    • رابطه با آزمونچند به یکquiz_id
  • گواهی

    /v1/certificate

    فقط صاحب ردیف: هر کاربر فقط ردیف‌های خودش را می‌بیند. مالکیت از روی student_id

    گواهی پایان دوره — فقط issue_certificate صادر می‌کند؛ دانشجو گواهی خودش را می‌بیند و هر کسی با کدش از verify_certificate اصالتش را می‌سنجد

    ۸ فیلدو ۲ رابطه
    • student_idدانشجومتن
    • course_idدورهمتنضروری
    • enrollment_idثبت‌ناممتن
    • codeکد گواهیمتنضروری
    • holder_nameنام دارندهمتنضروری
    • course_titleعنوان دورهمتن
    • statusوضعیتگزینه‌ای= "valid"
    • cert_keyکلید یکتاییمتنفقط مدیر
    • رابطه با کاربرچند به یکstudent_id
    • رابطه با دورهچند به یکcourse_id
  • نظر دانشجو

    /v1/review

    عمومی: هر کسی می‌خواندش، حتی بدون ورود و با کلید عمومی داخل اپ.

    امتیاز و نظر دانشجویان — همه می‌خوانند؛ فقط ثبت‌نام‌کرده با add_review می‌نویسد، هر دوره یک بار، و بعد خودش ویرایشش می‌کند

    ۶ فیلدو ۲ رابطه
    • student_idنویسندهمتنفقط مدیر
    • course_idدورهمتنضروری
    • author_nameنام نمایشیمتن
    • ratingامتیاز (۱ تا ۵)عددضروری
    • commentنظرمتن
    • review_keyکلید یکتاییمتنفقط مدیر
    • رابطه با دورهچند به یکcourse_id
    • رابطه با کاربرچند به یکstudent_id
  • مسدودی دسترسی

    /v1/access_block

    کاربران واردشده: هر کاربری که وارد شده باشد همه را می‌بیند.

    دانشجویی که دسترسی‌اش به یک دوره بسته شده (استرداد، تخلف) — فقط آکادمی می‌نویسد و می‌خواند؛ همهٔ فانکشن‌ها پیش از ثبت‌نام، پرداخت، محتوا، آزمون و گواهی آن را می‌سنجند

    ۳ فیلدو ۲ رابطه
    • student_idدانشجومتنضروریفقط مدیر
    • course_idدورهمتنضروریفقط مدیر
    • reasonدلیلمتنفقط مدیر
    • رابطه با کاربرچند به یکstudent_id
    • رابطه با دورهچند به یکcourse_id

قوانین آماده

منطقی که همراه قالب نصب می‌شود و از لحظهٔ ساخت فعال است، بدون اینکه یک خط کد بنویسید.

  • شمارش درس‌های دوره

    تریگرروی درس
  • شمارش دانشجویان دوره

    تریگرروی ثبت‌نام
  • ثبت تاریخ اتمام دوره

    تریگرروی ثبت‌نام
  • ثبت زمان پرداخت سفارش دوره

    تریگرروی سفارش دوره
  • وضعیت ثبت‌نام فقط رو به جلو

    اعتبارسنجیروی ثبت‌نام

    پیامی که کاربر می‌گیرد: «وضعیت ثبت‌نام فقط رو به جلو تغییر می‌کند: در حال گذراندن ← تکمیل‌شده ← لغوشده. ثبت‌نام لغوشده را حذف کنید تا دانشجو از نو ثبت‌نام کند»

  • وضعیت سفارش دوره فقط رو به جلو

    اعتبارسنجیروی سفارش دوره

    پیامی که کاربر می‌گیرد: «وضعیت سفارش فقط رو به جلو تغییر می‌کند: در انتظار پرداخت ← پرداخت‌شده یا لغوشده، و پرداخت‌شده ← مسترد‌شده»

  • امتیاز نظر بین ۱ و ۵

    اعتبارسنجیروی نظر دانشجو

    پیامی که کاربر می‌گیرد: «امتیاز باید عدد صحیحی بین ۱ و ۵ باشد»

  • امتیاز نظر بین ۱ و ۵ (ویرایش)

    اعتبارسنجیروی نظر دانشجو

    پیامی که کاربر می‌گیرد: «امتیاز باید عدد صحیحی بین ۱ و ۵ باشد»

  • گزینهٔ درست عدد صحیح

    اعتبارسنجیروی سؤال

    پیامی که کاربر می‌گیرد: «گزینهٔ درست شمارهٔ یکی از گزینه‌هاست: عدد صحیحی از ۰ تا ۹»

  • گزینهٔ درست عدد صحیح (ویرایش)

    اعتبارسنجیروی سؤال

    پیامی که کاربر می‌گیرد: «گزینهٔ درست شمارهٔ یکی از گزینه‌هاست: عدد صحیحی از ۰ تا ۹»

  • ایمیل ثبت‌نام در دوره

    تریگرروی ثبت‌نام
  • ایمیل صدور گواهی

    تریگرروی گواهی

فانکشن‌های آماده

منطقی که نباید دست اپ باشد همراه قالب نصب می‌شود و از لحظهٔ ساخت روشن است. هر فانکشن یک آدرس دارد که اپ یا سرور شما صدایش می‌زند، و از سهمیهٔ فانکشن پلن حساب می‌شود.

  • ثبت‌نام در دورهٔ رایگان

    POST /v1/fn/enroll_free

    دانشجوی واردشده را در یک دورهٔ رایگانِ منتشرشده ثبت‌نام می‌کند. دورهٔ پولی را رد می‌کند (آن را با buy_course بخرید)، و دانشجویی را که دسترسی‌اش به دوره بسته شده هم. صدا زدن دوباره‌اش همان ثبت‌نام قبلی را برمی‌گرداند. ورودی: course_id.

    کاربران واردشده: کاربری که در اپ وارد شده صدایش می‌زند؛ سرور شما هم با کلید API.

    کد فانکشن
    // The only way into a free course. A paid one goes through buy_course
    // and a verified payment; an enrollment row cannot be POSTed directly.
    //
    // Idempotent: a student already enrolled gets that enrollment back. Two
    // racing requests both pass the read; the unique enroll_key refuses the
    // second write, and it answers with the first one's row.
    //
    // An access_block row (written by the academy, never by a student) keeps
    // a revoked student out even after they delete their own enrollment.
    //
    // Ownership is by hand: an admin's own handle reads every student's rows,
    // and this must still only ever look at — and write — the CALLER's.
    function fail(status, code, message) {
      throw {status: status, code: code, message: message};
    }
    // A row that is not there — or an id that cannot be one — is null; any
    // other refusal (the call budget, authorization being unavailable) is
    // not «not found» and goes up as is.
    function getOrNull(handle, entity, id) {
      try { return handle.get(entity, id); } catch (e) {
        if (e && (e.status === 404 || e.status === 400)) return null;
        throw e;
      }
    }
    function view(row) {
      delete row.enroll_key;
      return row;
    }
    
    if (ctx.auth !== "user" || !ctx.user.id) {
      fail(403, "login_required", "ثبت‌نام با توکن دانشجوی واردشده انجام می‌شود، نه با کلید API");
    }
    const me = ctx.user.id;
    const body = ctx.request.body;
    const input = body && typeof body === "object" && !Array.isArray(body) ? body : {};
    const courseId = typeof input.course_id === "string" ? input.course_id.trim() : "";
    if (!courseId) fail(400, "course_required", "شناسهٔ دوره را با course_id بفرستید");
    
    const course = getOrNull(ctx.db.admin, "course", courseId);
    if (!course || course.status !== "published") {
      fail(404, "course_not_found", "این دوره پیدا نشد یا هنوز منتشر نشده است");
    }
    const mine = {student_id: me, course_id: course.id};
    if (ctx.db.admin.list("access_block", {filter: mine, limit: 1}).length > 0) {
      fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید");
    }
    const found = ctx.db.admin.list("enrollment", {filter: mine, limit: 1});
    if (found.length > 0) {
      if (found[0].status === "revoked") {
        fail(403, "enrollment_revoked", "ثبت‌نام شما در این دوره لغو شده است؛ با پشتیبانی آکادمی تماس بگیرید");
      }
      ctx.respond(view(found[0]));
    }
    if (Number(course.price) > 0) {
      fail(409, "course_not_free", "این دوره رایگان نیست؛ آن را با فانکشن buy_course بخرید");
    }
    
    let enrollment = null;
    let raced = false;
    try {
      enrollment = ctx.db.admin.create("enrollment", {
        student_id: me,
        course_id: course.id,
        course_title: course.title,
        source: "free",
        price_paid: 0,
        status: "active",
        enroll_key: me + ":" + course.id,
      });
    } catch (e) {
      if (!e || e.status !== 409) throw e;
      raced = true;
    }
    if (raced) {
      const again = ctx.db.admin.list("enrollment", {filter: mine, limit: 1});
      if (again.length === 0) fail(409, "enrollment_conflict", "ثبت‌نام هم‌زمان انجام نشد؛ دوباره تلاش کنید");
      enrollment = again[0];
    }
    ctx.respond(view(enrollment));
    
  • خرید دوره

    POST /v1/fn/buy_course

    برای دانشجوی واردشده سفارش خرید یک دورهٔ پولیِ منتشرشده می‌سازد: قیمت را از خود دوره و تخفیف را از کد تخفیف می‌خواند. اگر سفارش «در انتظار پرداخت» برای همین دوره دارد، همان را به‌روز می‌کند (یا اگر پرداختش شروع شده، همان را برمی‌گرداند). کسی که ثبت‌نام دارد یا دسترسی‌اش بسته شده رد می‌شود، و مبلغی بین صفر و ۱٬۰۰۰ تومان (کمتر از حداقل زرین‌پال) هم. ورودی: course_id و در صورت نیاز coupon_code.

    کاربران واردشده: کاربری که در اپ وارد شده صدایش می‌زند؛ سرور شما هم با کلید API.

    کد فانکشن
    // Creates (or reprices) the caller's order for one paid course. The
    // amount is read here, from the course and the coupon table; the request
    // names only WHICH course and WHICH code — never a price.
    //
    // One pending order per student and course. A second call reprices it —
    // a different coupon, a changed price — unless its payment has started:
    // then the same order comes back unchanged, so the gateway link the buyer
    // already has still matches the amount pay_verify will check.
    //
    // The coupon's use is counted when the order is PAID (pay_start's free
    // path, pay_verify), not here, and both of those check the coupon again
    // before charging: an order nobody pays must not use it up, and a pile
    // of pending orders must not all pay under a coupon with one use left.
    const MIN_AMOUNT = 1000; // toman: ZarinPal refuses anything smaller
    
    function fail(status, code, message) {
      throw {status: status, code: code, message: message};
    }
    function getOrNull(handle, entity, id) {
      try { return handle.get(entity, id); } catch (e) {
        if (e && (e.status === 404 || e.status === 400)) return null;
        throw e;
      }
    }
    function view(order) {
      delete order.payment_authority;
      return order;
    }
    
    if (ctx.auth !== "user" || !ctx.user.id) {
      fail(403, "login_required", "خرید دوره با توکن دانشجوی واردشده انجام می‌شود، نه با کلید API");
    }
    const me = ctx.user.id;
    const body = ctx.request.body;
    const input = body && typeof body === "object" && !Array.isArray(body) ? body : {};
    const courseId = typeof input.course_id === "string" ? input.course_id.trim() : "";
    const couponCode = input.coupon_code == null ? "" : String(input.coupon_code).trim().toUpperCase();
    if (!courseId) fail(400, "course_required", "شناسهٔ دوره را با course_id بفرستید");
    
    const course = getOrNull(ctx.db.admin, "course", courseId);
    if (!course || course.status !== "published") {
      fail(404, "course_not_found", "این دوره پیدا نشد یا هنوز منتشر نشده است");
    }
    const price = Number(course.price || 0);
    if (price <= 0) {
      fail(409, "course_is_free", "این دوره رایگان است؛ با فانکشن enroll_free ثبت‌نام کنید");
    }
    const mine = {student_id: me, course_id: course.id};
    if (ctx.db.admin.list("access_block", {filter: mine, limit: 1}).length > 0) {
      fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید");
    }
    
    const enrolled = ctx.db.admin.list("enrollment", {filter: mine, limit: 1});
    if (enrolled.length > 0) {
      if (enrolled[0].status === "revoked") {
        fail(403, "enrollment_revoked", "ثبت‌نام شما در این دوره لغو شده است؛ با پشتیبانی آکادمی تماس بگیرید");
      }
      fail(409, "already_enrolled", "شما در این دوره ثبت‌نام کرده‌اید و همهٔ درس‌هایش برایتان باز است");
    }
    
    const pending = ctx.db.admin.list("course_order",
      {filter: {student_id: me, course_id: course.id, status: "pending"}, limit: 1});
    const existing = pending.length > 0 ? pending[0] : null;
    if (existing && existing.payment_authority) {
      ctx.respond(view(existing));
    }
    
    // ── coupon (the code is admin-read: only this handle can match it) ─────
    let coupon = null;
    let discount = 0;
    if (couponCode) {
      const found = ctx.db.admin.list("coupon", {filter: {code: couponCode}, limit: 1});
      coupon = found.length > 0 ? found[0] : null;
      if (!coupon || coupon.active === false) {
        fail(400, "coupon_invalid", "این کد تخفیف معتبر نیست");
      }
      if (coupon.course_id && coupon.course_id !== course.id) {
        fail(400, "coupon_invalid", "این کد تخفیف برای این دوره نیست");
      }
      if (coupon.expires_at && new Date(coupon.expires_at).getTime() <= Date.now()) {
        fail(400, "coupon_expired", "مهلت استفاده از این کد تخفیف تمام شده است");
      }
      const limit = Number(coupon.usage_limit || 0);
      if (limit > 0 && Number(coupon.used_count || 0) >= limit) {
        fail(400, "coupon_used_up", "ظرفیت استفاده از این کد تخفیف پر شده است");
      }
      discount = coupon.kind === "percent"
        ? Math.floor(price * Number(coupon.value) / 100)
        : Number(coupon.value);
      if (discount > price) discount = price;
      if (discount < 0) discount = 0;
    }
    const amount = price - discount;
    if (amount > 0 && amount < MIN_AMOUNT) {
      fail(400, "amount_below_gateway_minimum",
        "مبلغ پس از تخفیف " + amount + " تومان می‌شود و درگاه زرین‌پال کمتر از ۱٬۰۰۰ تومان را نمی‌پذیرد؛ بدون این کد تخفیف بخرید");
    }
    
    const terms = {
      course_title: course.title,
      price: price,
      discount: discount,
      amount: amount,
      coupon_code: coupon ? coupon.code : "",
    };
    let order = null;
    if (existing) {
      order = ctx.db.admin.update("course_order", existing.id, terms);
    } else {
      // A readable, practically unique number: the millisecond in base 36
      // plus two random characters. The field is unique, so a collision
      // refuses the order and the buyer simply retries.
      const suffix = ("0" + Math.floor(Math.random() * 1296).toString(36)).slice(-2);
      order = ctx.db.admin.create("course_order", Object.assign({
        order_number: "AC-" + (Date.now().toString(36) + suffix).toUpperCase(),
        student_id: me,
        course_id: course.id,
        status: "pending",
      }, terms));
    }
    ctx.respond(view(order));
    
  • شروع پرداخت

    POST /v1/fn/pay_start

    برای سفارش «در انتظار پرداخت» خودِ دانشجو تراکنش زرین‌پال می‌سازد و نشانی درگاه را برمی‌گرداند. ورودی: order_id و callback_url (نشانی https صفحهٔ بازگشت اپ شما). شناسهٔ سفارش به callback_url اضافه می‌شود. پیش از هر پرداخت، ثبت‌نام قبلی، بسته بودن دسترسی و اعتبار کد تخفیف دوباره سنجیده می‌شود. سفارشی که قبلاً تراکنش گرفته همان نشانی درگاه را پس می‌گیرد، و سفارش صفرتومانی بی‌درگاه پرداخت‌شده و ثبت‌نام می‌شود.

    کاربران واردشده: کاربری که در اپ وارد شده صدایش می‌زند؛ سرور شما هم با کلید API.

    مقدارهایی که از شما می‌خواهد:
    • ZARINPAL_MERCHANT_IDمرچنت‌کد ۳۶ نویسه‌ای درگاه زرین‌پال شما؛ از پنل زرین‌پال، بخش درگاه‌ها.
    • STORE_URLاختیاری: نشانی سایت یا اپ آکادمی، مثل https://academy.example.com — اگر بگذارید، پرداخت فقط به صفحه‌ای زیر همین نشانی برمی‌گردد.
    • ZARINPAL_SANDBOXاختیاری: برای آزمایش بی‌هزینه 1 بگذارید تا پرداخت به درگاه آزمایشی زرین‌پال (sandbox) برود؛ پیش از فروش واقعی پاکش کنید.
    کد فانکشن
    // Starts a ZarinPal (v4) payment for one of the caller's own pending
    // orders. The amount is the order's own, read here; the request only says
    // which order and where the gateway should send the buyer back.
    //
    // Before anything is charged: a blocked student is refused, a student
    // already enrolled (an admin's grant, a second order) is refused with
    // already_enrolled, and the order's coupon is checked again — one that has
    // since run out, expired or been switched off cancels the order, and the
    // buyer places a new one with buy_course.
    //
    // An order of 0 (a 100% coupon) needs no gateway: it is settled here —
    // paid, enrolled, the coupon counted — before the merchant id is asked for.
    function fail(status, code, message) {
      throw {status: status, code: code, message: message};
    }
    function getOrNull(handle, entity, id) {
      try { return handle.get(entity, id); } catch (e) {
        if (e && (e.status === 404 || e.status === 400)) return null;
        throw e;
      }
    }
    // Why a coupon can no longer pay, or "".
    function couponProblem(c, courseId) {
      if (!c || c.active === false) return "کد تخفیف این سفارش دیگر معتبر نیست";
      if (c.course_id && c.course_id !== courseId) return "کد تخفیف این سفارش برای این دوره نیست";
      if (c.expires_at && new Date(c.expires_at).getTime() <= Date.now()) return "مهلت کد تخفیف این سفارش تمام شده است";
      const limit = Number(c.usage_limit || 0);
      if (limit > 0 && Number(c.used_count || 0) >= limit) return "ظرفیت کد تخفیف این سفارش پر شده است";
      return "";
    }
    // The caller's enrollment in the order's course, made if it is missing.
    // Same idempotent shape as enroll_free: read, write, and on a unique
    // conflict read again.
    function ensureEnrollment(order) {
      const mine = {student_id: order.student_id, course_id: order.course_id};
      const found = ctx.db.admin.list("enrollment", {filter: mine, limit: 1});
      if (found.length > 0) return found[0];
      let made = null;
      try {
        made = ctx.db.admin.create("enrollment", {
          student_id: order.student_id,
          course_id: order.course_id,
          course_title: order.course_title || "",
          source: "purchase",
          order_id: order.id,
          price_paid: Number(order.amount || 0),
          status: "active",
          enroll_key: order.student_id + ":" + order.course_id,
        });
      } catch (e) {
        if (!e || e.status !== 409) throw e;
      }
      if (made) return made;
      const again = ctx.db.admin.list("enrollment", {filter: mine, limit: 1});
      if (again.length === 0) fail(409, "enrollment_conflict", "ثبت‌نام هم‌زمان انجام نشد؛ دوباره تلاش کنید");
      return again[0];
    }
    
    if (ctx.auth !== "user" || !ctx.user.id) {
      fail(403, "login_required", "پرداخت با توکن دانشجوی واردشده شروع می‌شود، نه با کلید API");
    }
    const body = ctx.request.body;
    const input = body && typeof body === "object" && !Array.isArray(body) ? body : {};
    const orderId = typeof input.order_id === "string" ? input.order_id.trim() : "";
    const callback = typeof input.callback_url === "string" ? input.callback_url.trim() : "";
    if (!orderId) fail(400, "order_required", "شناسهٔ سفارش را با order_id بفرستید");
    
    // The admin handle is what reads the stored Authority; whose order it is
    // is checked by hand, for an admin's own handle would see them all.
    const order = getOrNull(ctx.db.admin, "course_order", orderId);
    if (!order || order.student_id !== ctx.user.id) {
      fail(404, "order_not_found", "این سفارش پیدا نشد یا مال شما نیست");
    }
    if (order.status !== "pending") {
      fail(409, "order_not_payable", "فقط سفارش «در انتظار پرداخت» پرداخت می‌شود");
    }
    
    // ── nothing is charged past these ─────────────────────────────────────
    const mine = {student_id: order.student_id, course_id: order.course_id};
    if (ctx.db.admin.list("access_block", {filter: mine, limit: 1}).length > 0) {
      fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید");
    }
    const enrolled = ctx.db.admin.list("enrollment", {filter: mine, limit: 1});
    if (enrolled.length > 0) {
      if (enrolled[0].status === "revoked") {
        fail(403, "enrollment_revoked", "ثبت‌نام شما در این دوره لغو شده است؛ با پشتیبانی آکادمی تماس بگیرید");
      }
      fail(409, "already_enrolled", "شما در این دوره ثبت‌نام کرده‌اید؛ این سفارش نیازی به پرداخت ندارد");
    }
    let coupon = null;
    if (order.coupon_code) {
      const found = ctx.db.admin.list("coupon", {filter: {code: order.coupon_code}, limit: 1});
      coupon = found.length > 0 ? found[0] : null;
      const problem = couponProblem(coupon, order.course_id);
      if (problem) {
        ctx.db.admin.update("course_order", order.id, {status: "cancelled"});
        fail(409, "coupon_no_longer_valid", problem + "؛ این سفارش لغو شد — دوباره با buy_course سفارش بدهید");
      }
    }
    
    if (Number(order.amount) <= 0) {
      ctx.db.admin.update("course_order", order.id, {status: "paid", paid_at: new Date().toISOString(), payment_ref: "FREE"});
      const enrollment = ensureEnrollment(order);
      if (coupon) {
        ctx.db.admin.update("coupon", coupon.id, {used_count: Number(coupon.used_count || 0) + 1});
      }
      delete enrollment.enroll_key;
      ctx.respond({order_id: order.id, order_number: order.order_number, amount: 0, paid: true, enrollment: enrollment});
    }
    
    const merchant = ctx.secrets.ZARINPAL_MERCHANT_ID;
    if (!merchant) {
      fail(400, "payment_not_configured",
        "درگاه پرداخت هنوز تنظیم نشده است: مرچنت‌کد زرین‌پال را با نام ZARINPAL_MERCHANT_ID در secrets پروژه بگذارید");
    }
    const sandboxFlag = String(ctx.secrets.ZARINPAL_SANDBOX || "").trim();
    const gateway = /^(1|true|yes)$/i.test(sandboxFlag) ? "sandbox.zarinpal.com" : "payment.zarinpal.com";
    
    // https only: the gateway sends the buyer back to this page with the
    // payment's Authority in the query string.
    if (!/^https:[/][/][^/\s?#]+([/?#]\S*)?$/.test(callback)) {
      fail(400, "invalid_callback_url", "callback_url باید نشانی کامل https باشد، مثل https://academy.example.com/pay/return");
    }
    // Whitespace-only means unset; the comparison ignores case, as a host does.
    const storeUrl = String(ctx.secrets.STORE_URL || "").trim();
    if (storeUrl) {
      const base = storeUrl.replace(/[/]+$/, "").toLowerCase();
      const rest = callback.slice(base.length);
      const under = callback.slice(0, base.length).toLowerCase() === base &&
        (rest === "" || rest.charAt(0) === "/" || rest.charAt(0) === "?" || rest.charAt(0) === "#");
      if (!under) {
        fail(400, "invalid_callback_url", "callback_url باید زیر نشانی آکادمی (STORE_URL) باشد");
      }
    }
    
    // One order, one transaction. A second request would overwrite the
    // stored Authority, and a buyer who then paid through the FIRST link
    // would be refused by pay_verify with the money already taken.
    if (order.payment_authority) {
      ctx.respond({
        order_id: order.id,
        order_number: order.order_number,
        amount: order.amount,
        authority: order.payment_authority,
        payment_url: "https://" + gateway + "/pg/StartPay/" + order.payment_authority,
      });
    }
    
    const sep = callback.indexOf("?") >= 0 ? "&" : "?";
    let res = null;
    try {
      res = ctx.http.post("https://" + gateway + "/pg/v4/payment/request.json", {
        merchant_id: merchant,
        amount: Math.round(Number(order.amount) * 10), // toman → rial
        callback_url: callback + sep + "order_id=" + encodeURIComponent(order.id),
        description: "خرید دورهٔ " + (order.course_title || "") + " — سفارش " + (order.order_number || order.id),
        metadata: {order_id: order.id},
      }, {headers: {Accept: "application/json"}});
    } catch (e) {
      ctx.respond(502, {code: "gateway_unreachable", detail: "درگاه زرین‌پال در دسترس نبود؛ چند لحظهٔ دیگر دوباره تلاش کنید"});
    }
    const data = res.json && res.json.data && !Array.isArray(res.json.data) ? res.json.data : null;
    if (!data || data.code !== 100 || !data.authority) {
      const errors = res.json && res.json.errors && !Array.isArray(res.json.errors) ? res.json.errors : {};
      ctx.respond(502, {
        code: "gateway_refused",
        detail: "زرین‌پال درخواست پرداخت را نپذیرفت (کد " + (errors.code || (data && data.code) || res.status) +
          ")؛ مرچنت‌کد و نشانی بازگشت را بررسی کنید",
      });
    }
    
    ctx.db.admin.update("course_order", order.id, {payment_authority: data.authority});
    ctx.respond({
      order_id: order.id,
      order_number: order.order_number,
      amount: order.amount,
      authority: data.authority,
      payment_url: "https://" + gateway + "/pg/StartPay/" + data.authority,
    });
    
  • تأیید پرداخت

    POST /v1/fn/pay_verify

    صفحهٔ بازگشت اپ بعد از درگاه صدایش می‌زند: Authority را با تراکنش ذخیره‌شدهٔ سفارش می‌سنجد، ثبت‌نام قبلی، بسته بودن دسترسی و اعتبار کد تخفیف را دوباره می‌سنجد، پرداخت را با مبلغ خود سفارش از زرین‌پال تأیید می‌گیرد، سفارش را «پرداخت‌شده» می‌کند و دانشجو را در دوره ثبت‌نام می‌کند. ورودی: order_id، authority و در صورت وجود status (همان Status بازگشتی). صدا زدن دوباره‌اش بی‌خطر است و ثبت‌نامِ جامانده را هم می‌سازد.

    کاربران واردشده: کاربری که در اپ وارد شده صدایش می‌زند؛ سرور شما هم با کلید API.

    مقدارهایی که از شما می‌خواهد:
    • ZARINPAL_MERCHANT_IDمرچنت‌کد ۳۶ نویسه‌ای درگاه زرین‌پال شما؛ همان که pay_start می‌خواند.
    • ZARINPAL_SANDBOXاختیاری: همان مقدار pay_start؛ 1 یعنی تأیید از درگاه آزمایشی زرین‌پال (sandbox).
    کد فانکشن
    // Verifies a ZarinPal (v4) payment the gateway has just redirected back,
    // then enrolls the buyer.
    //
    // Nothing is verified — so nothing is charged; ZarinPal returns an
    // unverified payment by itself within 72 hours — for a blocked student,
    // one already enrolled, or an order whose coupon has since run out
    // (that order is cancelled).
    //
    // Idempotent: an order already paid is answered as it is — and its
    // enrollment is made if a failure half-way left it missing — so a page
    // that reloads, or a buyer who presses back, never pays or fails twice.
    //
    // NOT atomic: the order flips to paid, then the enrollment is written,
    // then the coupon counted. A failure after the first write is healed by
    // calling this again, except the coupon count, which can stay one short.
    function fail(status, code, message) {
      throw {status: status, code: code, message: message};
    }
    function getOrNull(handle, entity, id) {
      try { return handle.get(entity, id); } catch (e) {
        if (e && (e.status === 404 || e.status === 400)) return null;
        throw e;
      }
    }
    function couponProblem(c, courseId) {
      if (!c || c.active === false) return "کد تخفیف این سفارش دیگر معتبر نیست";
      if (c.course_id && c.course_id !== courseId) return "کد تخفیف این سفارش برای این دوره نیست";
      if (c.expires_at && new Date(c.expires_at).getTime() <= Date.now()) return "مهلت کد تخفیف این سفارش تمام شده است";
      const limit = Number(c.usage_limit || 0);
      if (limit > 0 && Number(c.used_count || 0) >= limit) return "ظرفیت کد تخفیف این سفارش پر شده است";
      return "";
    }
    function ensureEnrollment(order) {
      const mine = {student_id: order.student_id, course_id: order.course_id};
      const found = ctx.db.admin.list("enrollment", {filter: mine, limit: 1});
      if (found.length > 0) return found[0];
      let made = null;
      try {
        made = ctx.db.admin.create("enrollment", {
          student_id: order.student_id,
          course_id: order.course_id,
          course_title: order.course_title || "",
          source: "purchase",
          order_id: order.id,
          price_paid: Number(order.amount || 0),
          status: "active",
          enroll_key: order.student_id + ":" + order.course_id,
        });
      } catch (e) {
        if (!e || e.status !== 409) throw e;
      }
      if (made) return made;
      const again = ctx.db.admin.list("enrollment", {filter: mine, limit: 1});
      if (again.length === 0) fail(409, "enrollment_conflict", "ثبت‌نام هم‌زمان انجام نشد؛ دوباره تلاش کنید");
      return again[0];
    }
    // The buyer's view: the Authority and the uniqueness key stay server-side.
    function answer(order, enrollment) {
      delete order.payment_authority;
      delete enrollment.enroll_key;
      order.enrollment = enrollment;
      return order;
    }
    
    if (ctx.auth !== "user" || !ctx.user.id) {
      fail(403, "login_required", "تأیید پرداخت با توکن دانشجوی واردشده انجام می‌شود، نه با کلید API");
    }
    const body = ctx.request.body;
    const input = body && typeof body === "object" && !Array.isArray(body) ? body : {};
    const orderId = typeof input.order_id === "string" ? input.order_id.trim() : "";
    const authority = typeof input.authority === "string" ? input.authority.trim() : "";
    if (!orderId) fail(400, "order_required", "شناسهٔ سفارش را با order_id بفرستید");
    
    const order = getOrNull(ctx.db.admin, "course_order", orderId);
    if (!order || order.student_id !== ctx.user.id) {
      fail(404, "order_not_found", "این سفارش پیدا نشد یا مال شما نیست");
    }
    const mine = {student_id: order.student_id, course_id: order.course_id};
    if (ctx.db.admin.list("access_block", {filter: mine, limit: 1}).length > 0) {
      fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید");
    }
    if (order.status === "paid") {
      ctx.respond(answer(order, ensureEnrollment(order)));
    }
    if (order.status !== "pending") {
      fail(409, "order_not_payable", "این سفارش در وضعیتی نیست که پرداختش تأیید شود؛ اگر مبلغی کم شده، طی ۷۲ ساعت به حساب برمی‌گردد");
    }
    if (input.status === "NOK") {
      fail(400, "payment_cancelled", "پرداخت انجام نشد یا لغو شد؛ می‌توانید دوباره پرداخت کنید");
    }
    if (!authority || !order.payment_authority || authority !== order.payment_authority) {
      fail(400, "authority_mismatch", "این تراکنش با سفارش جور نیست؛ پرداخت را از نو شروع کنید");
    }
    
    // ── nothing is verified past these ────────────────────────────────────
    const enrolled = ctx.db.admin.list("enrollment", {filter: mine, limit: 1});
    if (enrolled.length > 0) {
      if (enrolled[0].status === "revoked") {
        fail(403, "enrollment_revoked", "ثبت‌نام شما در این دوره لغو شده است؛ اگر مبلغی کم شده، طی ۷۲ ساعت به حساب برمی‌گردد");
      }
      fail(409, "already_enrolled", "شما در این دوره ثبت‌نام کرده‌اید؛ این پرداخت تأیید نمی‌شود و اگر مبلغی کم شده، طی ۷۲ ساعت به حساب برمی‌گردد");
    }
    let coupon = null;
    if (order.coupon_code) {
      const found = ctx.db.admin.list("coupon", {filter: {code: order.coupon_code}, limit: 1});
      coupon = found.length > 0 ? found[0] : null;
      const problem = couponProblem(coupon, order.course_id);
      if (problem) {
        ctx.db.admin.update("course_order", order.id, {status: "cancelled"});
        fail(409, "coupon_no_longer_valid", problem + "؛ این سفارش لغو شد و اگر مبلغی کم شده، طی ۷۲ ساعت به حساب برمی‌گردد");
      }
    }
    
    const merchant = ctx.secrets.ZARINPAL_MERCHANT_ID;
    if (!merchant) {
      fail(400, "payment_not_configured",
        "درگاه پرداخت هنوز تنظیم نشده است: مرچنت‌کد زرین‌پال را با نام ZARINPAL_MERCHANT_ID در secrets پروژه بگذارید");
    }
    const sandboxFlag = String(ctx.secrets.ZARINPAL_SANDBOX || "").trim();
    const gateway = /^(1|true|yes)$/i.test(sandboxFlag) ? "sandbox.zarinpal.com" : "payment.zarinpal.com";
    
    let res = null;
    try {
      res = ctx.http.post("https://" + gateway + "/pg/v4/payment/verify.json", {
        merchant_id: merchant,
        amount: Math.round(Number(order.amount) * 10), // toman → rial, as pay_start sent it
        authority: order.payment_authority,
      }, {headers: {Accept: "application/json"}});
    } catch (e) {
      ctx.respond(502, {code: "gateway_unreachable", detail: "درگاه زرین‌پال در دسترس نبود؛ چند لحظهٔ دیگر دوباره تلاش کنید"});
    }
    const data = res.json && res.json.data && !Array.isArray(res.json.data) ? res.json.data : null;
    // 100: verified now; 101: verified by an earlier call.
    if (!data || (data.code !== 100 && data.code !== 101)) {
      const errors = res.json && res.json.errors && !Array.isArray(res.json.errors) ? res.json.errors : {};
      fail(402, "payment_not_verified",
        "زرین‌پال این پرداخت را تأیید نکرد (کد " + (errors.code || (data && data.code) || res.status) +
        ")؛ اگر مبلغی کم شده، طی ۷۲ ساعت به حساب برمی‌گردد");
    }
    
    const paid = ctx.db.admin.update("course_order", order.id, {
      status: "paid",
      paid_at: new Date().toISOString(),
      payment_ref: String(data.ref_id || ""),
    });
    const enrollment = ensureEnrollment(paid);
    if (coupon) {
      ctx.db.admin.update("coupon", coupon.id, {used_count: Number(coupon.used_count || 0) + 1});
    }
    ctx.respond(answer(paid, enrollment));
    
  • محتوای درس

    POST /v1/fn/lesson_content

    ویدیو و متن یک درس را برمی‌گرداند: درس «پیش‌نمایش رایگان» یک دورهٔ منتشرشده را به هر کسی، حتی بدون ورود؛ بقیه را فقط به دانشجویی که در آن دوره ثبت‌نام فعال یا تکمیل‌شده دارد و دسترسی‌اش بسته نشده. ورودی: lesson_id (در بدنه یا در نشانی، مثل ?lesson_id=…).

    عمومی: هر کسی صدایش می‌زند، حتی بدون ورود و با کلید عمومی داخل اپ.

    کد فانکشن
    // The only door to a lesson's video_url and body: both are admin-read,
    // so a direct GET /v1/lesson never carries them. This reads them with the
    // admin handle and decides who may have them.
    //
    // A free preview of a PUBLISHED course is open to anyone who can reach
    // the function, signed in or not; a draft course's preview is not out
    // yet. Anything else needs a signed-in student with an active or
    // completed enrollment in that very course and no access_block —
    // checked against the CALLER's id, so an admin's token opens only the
    // courses they joined. The project's own API key (a server of yours)
    // reads every lesson.
    function fail(status, code, message) {
      throw {status: status, code: code, message: message};
    }
    function getOrNull(handle, entity, id) {
      try { return handle.get(entity, id); } catch (e) {
        if (e && (e.status === 404 || e.status === 400)) return null;
        throw e;
      }
    }
    
    const body = ctx.request.body;
    const input = body && typeof body === "object" && !Array.isArray(body) ? body : {};
    const raw = input.lesson_id != null ? input.lesson_id : ctx.request.query.lesson_id;
    const lessonId = typeof raw === "string" ? raw.trim() : "";
    if (!lessonId) fail(400, "lesson_required", "شناسهٔ درس را با lesson_id بفرستید");
    
    const lesson = getOrNull(ctx.db.admin, "lesson", lessonId);
    if (!lesson) fail(404, "lesson_not_found", "این درس پیدا نشد");
    
    if (ctx.auth !== "key") {
      const course = getOrNull(ctx.db.admin, "course", lesson.course_id);
      const open = lesson.is_free_preview === true && course !== null && course.status === "published";
      if (!open) {
        if (ctx.auth !== "user" || !ctx.user.id) {
          fail(403, "login_required", "این درس فقط برای دانشجویان ثبت‌نام‌کرده باز است؛ اول وارد شوید");
        }
        const mine = {student_id: ctx.user.id, course_id: lesson.course_id};
        if (ctx.db.admin.list("access_block", {filter: mine, limit: 1}).length > 0) {
          fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید");
        }
        const enrolled = ctx.db.admin.list("enrollment", {filter: mine, limit: 1});
        const status = enrolled.length > 0 ? enrolled[0].status : "";
        if (status !== "active" && status !== "completed") {
          fail(403, "not_enrolled", "این درس فقط برای دانشجویان ثبت‌نام‌کردهٔ همین دوره باز است");
        }
      }
    }
    
    ctx.respond({
      lesson_id: lesson.id,
      course_id: lesson.course_id,
      title: lesson.title,
      duration_minutes: lesson.duration_minutes || 0,
      is_free_preview: lesson.is_free_preview === true,
      video_url: lesson.video_url || "",
      body: lesson.body || "",
    });
    
  • تمام کردن درس

    POST /v1/fn/complete_lesson

    درسی را برای دانشجوی ثبت‌نام‌کرده «تمام‌شده» ثبت می‌کند و شمار درس‌های تمام‌شدهٔ ثبت‌نامش را به‌روز می‌کند. صدا زدن دوباره‌اش بی‌خطر است. ورودی: lesson_id.

    کاربران واردشده: کاربری که در اپ وارد شده صدایش می‌زند؛ سرور شما هم با کلید API.

    کد فانکشن
    // Progress is written here and nowhere else: lesson_progress has an
    // admin-only required lesson_id, so a direct POST cannot mark a lesson
    // done — and issue_certificate trusts these rows.
    //
    // Idempotent: a lesson already done answers with its row. The count on
    // the enrollment is recomputed from the rows every time, so a failure
    // between the two writes heals on the next call.
    const MAX_LESSONS = 500; // one list call; a course larger than this is not counted whole
    
    function fail(status, code, message) {
      throw {status: status, code: code, message: message};
    }
    function getOrNull(handle, entity, id) {
      try { return handle.get(entity, id); } catch (e) {
        if (e && (e.status === 404 || e.status === 400)) return null;
        throw e;
      }
    }
    function view(row) {
      delete row.progress_key;
      return row;
    }
    
    if (ctx.auth !== "user" || !ctx.user.id) {
      fail(403, "login_required", "ثبت پیشرفت با توکن دانشجوی واردشده انجام می‌شود، نه با کلید API");
    }
    const me = ctx.user.id;
    const body = ctx.request.body;
    const input = body && typeof body === "object" && !Array.isArray(body) ? body : {};
    const lessonId = typeof input.lesson_id === "string" ? input.lesson_id.trim() : "";
    if (!lessonId) fail(400, "lesson_required", "شناسهٔ درس را با lesson_id بفرستید");
    
    const lesson = getOrNull(ctx.db.admin, "lesson", lessonId);
    if (!lesson) fail(404, "lesson_not_found", "این درس پیدا نشد");
    const scope = {student_id: me, course_id: lesson.course_id};
    if (ctx.db.admin.list("access_block", {filter: scope, limit: 1}).length > 0) {
      fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید");
    }
    const enrolled = ctx.db.admin.list("enrollment", {filter: scope, limit: 1});
    const enrollment = enrolled.length > 0 ? enrolled[0] : null;
    if (!enrollment || (enrollment.status !== "active" && enrollment.status !== "completed")) {
      fail(403, "not_enrolled", "فقط دانشجوی ثبت‌نام‌کردهٔ این دوره درس‌هایش را تمام می‌کند");
    }
    
    const mine = {student_id: me, lesson_id: lesson.id};
    const found = ctx.db.admin.list("lesson_progress", {filter: mine, limit: 1});
    let progress = found.length > 0 ? found[0] : null;
    if (!progress) {
      let raced = false;
      try {
        progress = ctx.db.admin.create("lesson_progress", {
          student_id: me,
          enrollment_id: enrollment.id,
          course_id: lesson.course_id,
          lesson_id: lesson.id,
          lesson_title: lesson.title,
          progress_key: me + ":" + lesson.id,
        });
      } catch (e) {
        if (!e || e.status !== 409) throw e;
        raced = true;
      }
      if (raced) {
        const again = ctx.db.admin.list("lesson_progress", {filter: mine, limit: 1});
        if (again.length === 0) fail(409, "progress_conflict", "ثبت پیشرفت هم‌زمان انجام نشد؛ دوباره تلاش کنید");
        progress = again[0];
      }
    }
    
    const done = ctx.db.admin.list("lesson_progress", {filter: scope, limit: MAX_LESSONS});
    const lessonIds = {};
    for (const p of done) lessonIds[p.lesson_id] = true;
    const count = Object.keys(lessonIds).length;
    if (Number(enrollment.completed_lessons || 0) !== count) {
      ctx.db.admin.update("enrollment", enrollment.id, {completed_lessons: count});
    }
    
    const out = view(progress);
    out.completed_lessons = count;
    ctx.respond(out);
    
  • ثبت پاسخ‌های آزمون

    POST /v1/fn/submit_quiz

    پاسخ‌های دانشجوی ثبت‌نام‌کرده را سمت سرور تصحیح می‌کند، یک «شرکت در آزمون» با نمره ذخیره می‌کند و فقط نمره و قبولی را برمی‌گرداند — نه پاسخ درست و نه درست یا غلط بودن هر سؤال. برگه باید به همهٔ سؤال‌ها پاسخ بدهد و دفعات شرکت سقف دارد (max_attempts آزمون). ورودی: quiz_id و answers به شکل {"<question id>": شمارهٔ گزینه از ۰}.

    کاربران واردشده: کاربری که در اپ وارد شده صدایش می‌زند؛ سرور شما هم با کلید API.

    کد فانکشن
    // Grades on the server. correct_option is admin-read, so only this
    // handle sees it; the answer carries the score, never which questions
    // were right.
    //
    // What keeps the key from leaking is the attempt cap: with unlimited
    // tries, a student could change one answer at a time and read the key
    // off the score. So every quiz has a max_attempts (at least 1, default
    // 3), a sheet must answer EVERY question with a whole option number — a
    // partial sheet or an odd value is refused, not graded — and each
    // attempt carries a unique attempt_key «student:quiz:n», so two parallel
    // submissions cannot both take the last attempt.
    //
    // The cap counts the caller's own attempt rows and the highest n they
    // carry. A student who DELETEs their latest attempt gets that one back:
    // the role matrix lets a user delete their own rows, and the template
    // cannot change that.
    const MAX_QUESTIONS = 100;
    
    function fail(status, code, message) {
      throw {status: status, code: code, message: message};
    }
    function getOrNull(handle, entity, id) {
      try { return handle.get(entity, id); } catch (e) {
        if (e && (e.status === 404 || e.status === 400)) return null;
        throw e;
      }
    }
    
    if (ctx.auth !== "user" || !ctx.user.id) {
      fail(403, "login_required", "شرکت در آزمون با توکن دانشجوی واردشده انجام می‌شود، نه با کلید API");
    }
    const me = ctx.user.id;
    const body = ctx.request.body;
    const input = body && typeof body === "object" && !Array.isArray(body) ? body : {};
    const quizId = typeof input.quiz_id === "string" ? input.quiz_id.trim() : "";
    const answers = input.answers && typeof input.answers === "object" && !Array.isArray(input.answers) ? input.answers : null;
    if (!quizId) fail(400, "quiz_required", "شناسهٔ آزمون را با quiz_id بفرستید");
    if (!answers) fail(400, "answers_required", "پاسخ‌ها را با answers به شکل {\"<question id>\": شمارهٔ گزینه} بفرستید");
    
    const quiz = getOrNull(ctx.db.admin, "quiz", quizId);
    if (!quiz) fail(404, "quiz_not_found", "این آزمون پیدا نشد");
    const scope = {student_id: me, course_id: quiz.course_id};
    if (ctx.db.admin.list("access_block", {filter: scope, limit: 1}).length > 0) {
      fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید");
    }
    const enrolled = ctx.db.admin.list("enrollment", {filter: scope, limit: 1});
    const status = enrolled.length > 0 ? enrolled[0].status : "";
    if (status !== "active" && status !== "completed") {
      fail(403, "not_enrolled", "فقط دانشجوی ثبت‌نام‌کردهٔ این دوره در آزمونش شرکت می‌کند");
    }
    
    const maxAttempts = Math.max(1, Number(quiz.max_attempts || 3));
    const tried = ctx.db.admin.list("quiz_attempt",
      {filter: {student_id: me, quiz_id: quiz.id}, limit: maxAttempts});
    let n = tried.length;
    for (const a of tried) {
      const m = /:(\d+)$/.exec(String(a.attempt_key || ""));
      if (m && Number(m[1]) > n) n = Number(m[1]);
    }
    n += 1;
    if (tried.length >= maxAttempts || n > maxAttempts) {
      fail(409, "attempts_exhausted", "دفعات شرکت در این آزمون تمام شده است (" + maxAttempts + " بار)");
    }
    
    // One more than the cap is fetched: a quiz larger than that is refused
    // whole, never graded against part of its key.
    const questions = ctx.db.admin.list("question", {filter: {quiz_id: quiz.id}, limit: MAX_QUESTIONS + 1});
    if (questions.length > MAX_QUESTIONS) {
      fail(409, "quiz_too_large", "این آزمون بیش از ۱۰۰ سؤال دارد و تصحیح نمی‌شود؛ آن را به چند آزمون بشکنید");
    }
    if (questions.length === 0) fail(409, "quiz_empty", "این آزمون هنوز سؤالی ندارد");
    
    const byId = {};
    for (const q of questions) byId[q.id] = q;
    for (const id of Object.keys(answers)) {
      const q = byId[id];
      const choice = answers[id];
      const options = q && Array.isArray(q.options) ? q.options.length : 0;
      if (!q || typeof choice !== "number" || !Number.isInteger(choice) || choice < 0 ||
          (options > 0 && choice >= options)) {
        fail(400, "invalid_answer", "پاسخ هر سؤال این آزمون شمارهٔ یکی از گزینه‌های همان سؤال است، از صفر");
      }
    }
    let correct = 0;
    for (const q of questions) {
      if (!Object.prototype.hasOwnProperty.call(answers, q.id)) {
        fail(400, "answers_incomplete", "به همهٔ " + questions.length + " سؤال این آزمون پاسخ بدهید؛ برگهٔ ناقص تصحیح نمی‌شود");
      }
      if (answers[q.id] === Number(q.correct_option)) correct++;
    }
    const score = Math.round(correct * 100 / questions.length);
    const passScore = Number(quiz.pass_score == null ? 70 : quiz.pass_score);
    const passed = score >= passScore;
    
    let attempt = null;
    try {
      attempt = ctx.db.admin.create("quiz_attempt", {
        student_id: me,
        quiz_id: quiz.id,
        course_id: quiz.course_id,
        quiz_title: quiz.title,
        score: score,
        correct_count: correct,
        question_count: questions.length,
        passed: passed,
        answers: answers,
        attempt_key: me + ":" + quiz.id + ":" + n,
      });
    } catch (e) {
      if (!e || e.status !== 409) throw e;
    }
    if (!attempt) {
      fail(409, "attempt_conflict", "پاسخ دیگری هم‌زمان برای همین نوبت ثبت شد؛ نتیجه را از فهرست شرکت‌هایتان ببینید");
    }
    ctx.respond({
      attempt_id: attempt.id,
      quiz_id: quiz.id,
      score: score,
      pass_score: passScore,
      passed: passed,
      correct_count: correct,
      question_count: questions.length,
    });
    
  • صدور گواهی

    POST /v1/fn/issue_certificate

    وقتی دانشجو همهٔ درس‌های دوره را تمام کرده و در همهٔ آزمون‌هایش قبول شده، گواهی با کد یکتا صادر می‌کند و ثبت‌نامش را «تکمیل‌شده» می‌کند؛ پیش از آن می‌گوید چه چیزی مانده. صدا زدن دوباره‌اش همان گواهی قبلی را برمی‌گرداند، و گواهی باطل‌شده ۴۱۰ می‌گیرد. ورودی: course_id و holder_name (نامی که روی گواهی می‌آید).

    کاربران واردشده: کاربری که در اپ وارد شده صدایش می‌زند؛ سرور شما هم با کلید API.

    کد فانکشن
    // Issues the caller's certificate for one course, once.
    //
    // Completion is read from the real rows, a few lists with [in] filters
    // rather than one call per lesson: every lesson of the course must have
    // the caller's progress row, and every quiz of the course a passed
    // attempt. Both kinds of row are written by functions only. A list that
    // reaches its fetch cap is refused, never judged on part of the course.
    //
    // Idempotent: a certificate that exists comes back as it is (a new
    // holder_name is ignored) — and an enrollment a failure left «active»
    // is completed on the way. A revoked one answers 410. The unique
    // cert_key makes a racing second request answer with the first one's.
    //
    // The code is random — 8 characters from an alphabet without look-alikes
    // — and unique; a collision is retried once.
    const MAX_ROWS = 500;
    const ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
    
    function fail(status, code, message) {
      throw {status: status, code: code, message: message};
    }
    function getOrNull(handle, entity, id) {
      try { return handle.get(entity, id); } catch (e) {
        if (e && (e.status === 404 || e.status === 400)) return null;
        throw e;
      }
    }
    function view(row) {
      delete row.cert_key;
      return row;
    }
    function newCode() {
      let s = "";
      for (let i = 0; i < 8; i++) s += ALPHABET.charAt(Math.floor(Math.random() * ALPHABET.length));
      return "AC-" + s.slice(0, 4) + "-" + s.slice(4);
    }
    function capped(rows, what) {
      if (rows.length > MAX_ROWS) {
        fail(409, "course_too_large", "این دوره بیش از " + MAX_ROWS + " " + what + " دارد و گواهی‌اش خودکار صادر نمی‌شود؛ با پشتیبانی آکادمی تماس بگیرید");
      }
      return rows;
    }
    
    if (ctx.auth !== "user" || !ctx.user.id) {
      fail(403, "login_required", "گواهی با توکن دانشجوی واردشده صادر می‌شود، نه با کلید API");
    }
    const me = ctx.user.id;
    const body = ctx.request.body;
    const input = body && typeof body === "object" && !Array.isArray(body) ? body : {};
    const courseId = typeof input.course_id === "string" ? input.course_id.trim() : "";
    const holderName = typeof input.holder_name === "string" ? input.holder_name.trim().replace(/\s+/g, " ") : "";
    if (!courseId) fail(400, "course_required", "شناسهٔ دوره را با course_id بفرستید");
    
    const mine = {student_id: me, course_id: courseId};
    const issued = ctx.db.admin.list("certificate", {filter: mine, limit: 1});
    if (issued.length > 0) {
      if (issued[0].status === "revoked") {
        fail(410, "certificate_revoked", "گواهی شما برای این دوره باطل شده است؛ با پشتیبانی آکادمی تماس بگیرید");
      }
      const held = ctx.db.admin.list("enrollment", {filter: mine, limit: 1});
      if (held.length > 0 && held[0].status === "active") {
        ctx.db.admin.update("enrollment", held[0].id, {status: "completed", completed_at: issued[0].createdAt});
      }
      ctx.respond(view(issued[0]));
    }
    
    if (holderName.length < 2 || holderName.length > 80) {
      fail(400, "holder_name_required", "نامی را که باید روی گواهی بیاید با holder_name بفرستید (۲ تا ۸۰ نویسه)");
    }
    const course = getOrNull(ctx.db.admin, "course", courseId);
    if (!course) fail(404, "course_not_found", "این دوره پیدا نشد");
    if (ctx.db.admin.list("access_block", {filter: mine, limit: 1}).length > 0) {
      fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید");
    }
    const enrolled = ctx.db.admin.list("enrollment", {filter: mine, limit: 1});
    const enrollment = enrolled.length > 0 ? enrolled[0] : null;
    if (!enrollment || (enrollment.status !== "active" && enrollment.status !== "completed")) {
      fail(403, "not_enrolled", "فقط دانشجوی ثبت‌نام‌کردهٔ این دوره گواهی‌اش را می‌گیرد");
    }
    
    // ── completion, from the rows ─────────────────────────────────────────
    const lessons = capped(ctx.db.list("lesson", {filter: {course_id: course.id}, limit: MAX_ROWS + 1}), "درس");
    const quizzes = capped(ctx.db.list("quiz", {filter: {course_id: course.id}, limit: MAX_ROWS + 1}), "آزمون");
    const done = {};
    for (const p of capped(ctx.db.admin.list("lesson_progress", {filter: mine, limit: MAX_ROWS + 1}), "درس")) {
      done[p.lesson_id] = true;
    }
    const passed = {};
    if (quizzes.length > 0) {
      const quizIds = quizzes.map(function (q) { return q.id; });
      const attempts = capped(ctx.db.admin.list("quiz_attempt",
        {filter: {student_id: me, "quiz_id[in]": quizIds, passed: true}, limit: MAX_ROWS + 1}), "آزمون");
      for (const a of attempts) passed[a.quiz_id] = true;
    }
    let lessonsLeft = 0;
    for (const l of lessons) if (!done[l.id]) lessonsLeft++;
    let quizzesLeft = 0;
    for (const q of quizzes) if (!passed[q.id]) quizzesLeft++;
    if (lessons.length === 0) {
      fail(409, "course_empty", "این دوره هنوز درسی ندارد");
    }
    if (lessonsLeft > 0 || quizzesLeft > 0) {
      const parts = [];
      if (lessonsLeft > 0) parts.push(lessonsLeft + " درس");
      if (quizzesLeft > 0) parts.push(quizzesLeft + " آزمون");
      fail(409, "course_not_completed", "هنوز دوره تمام نشده است: " + parts.join(" و ") + " مانده");
    }
    
    // ── issue ─────────────────────────────────────────────────────────────
    const row = {
      student_id: me,
      course_id: course.id,
      enrollment_id: enrollment.id,
      holder_name: holderName,
      course_title: course.title,
      status: "valid",
      cert_key: me + ":" + course.id,
    };
    let cert = null;
    for (let attempt = 0; attempt < 2 && !cert; attempt++) {
      let conflict = false;
      try {
        cert = ctx.db.admin.create("certificate", Object.assign({code: newCode()}, row));
      } catch (e) {
        if (!e || e.status !== 409) throw e;
        conflict = true;
      }
      if (conflict) {
        // Either a racing request issued it first, or the code collided.
        const again = ctx.db.admin.list("certificate", {filter: mine, limit: 1});
        if (again.length > 0) ctx.respond(view(again[0]));
      }
    }
    if (!cert) fail(409, "certificate_conflict", "صدور گواهی هم‌زمان انجام نشد؛ دوباره تلاش کنید");
    
    if (enrollment.status !== "completed") {
      ctx.db.admin.update("enrollment", enrollment.id, {status: "completed", completed_at: new Date().toISOString()});
    }
    ctx.respond(view(cert));
    
  • تأیید اصالت گواهی

    POST /v1/fn/verify_certificate

    عمومی و بدون ورود: با کد گواهی، فقط نام دارنده، عنوان دوره و تاریخ صدور را برمی‌گرداند. کد نادرست ۴۰۴ می‌گیرد و گواهی باطل‌شده ۴۱۰. ورودی: code (در بدنه یا در نشانی، مثل ?code=…).

    عمومی: هر کسی صدایش می‌زند، حتی بدون ورود و با کلید عمومی داخل اپ.

    کد فانکشن
    // Anyone — an employer, a stranger with a link — checks a certificate by
    // its code. The answer is deliberately narrow: the holder's name, the
    // course and the date, never the student's id, email or anything else.
    // The date is the certificate row's createdAt: the moment it was issued.
    function fail(status, code, message) {
      throw {status: status, code: code, message: message};
    }
    
    const body = ctx.request.body;
    const input = body && typeof body === "object" && !Array.isArray(body) ? body : {};
    const raw = input.code != null ? input.code : ctx.request.query.code;
    const code = typeof raw === "string" ? raw.trim().toUpperCase() : "";
    if (!code) fail(400, "code_required", "کد گواهی را با code بفرستید");
    // The certificate code's own pattern; anything else matches nothing, and
    // is never handed to the filter as is.
    if (!/^[A-Z0-9-]{6,40}$/.test(code)) {
      fail(404, "certificate_not_found", "گواهی با این کد پیدا نشد");
    }
    
    const found = ctx.db.admin.list("certificate", {filter: {code: code}, limit: 1});
    if (found.length === 0) fail(404, "certificate_not_found", "گواهی با این کد پیدا نشد");
    const cert = found[0];
    if (cert.status === "revoked") {
      fail(410, "certificate_revoked", "این گواهی صادر شده بود ولی باطل شده است");
    }
    ctx.respond({
      code: cert.code,
      holder_name: cert.holder_name,
      course_title: cert.course_title || "",
      issued_at: cert.createdAt,
      valid: true,
    });
    
  • ثبت نظر

    POST /v1/fn/add_review

    دانشجوی ثبت‌نام‌کرده برای دوره امتیاز (عدد صحیح ۱ تا ۵) و نظر ثبت می‌کند؛ هر دوره یک بار. ویرایش بعدی با PATCH /v1/review/{id} است. ورودی: course_id، rating، و در صورت نیاز comment و author_name.

    کاربران واردشده: کاربری که در اپ وارد شده صدایش می‌زند؛ سرور شما هم با کلید API.

    کد فانکشن
    // Only an enrolled student reviews, once per course. review has an
    // admin-only required course_id, so a direct POST cannot skip this; the
    // student edits their own review afterwards with a plain PATCH, where the
    // rating rules hold again.
    function fail(status, code, message) {
      throw {status: status, code: code, message: message};
    }
    function view(row) {
      delete row.review_key;
      return row;
    }
    
    if (ctx.auth !== "user" || !ctx.user.id) {
      fail(403, "login_required", "نظر با توکن دانشجوی واردشده ثبت می‌شود، نه با کلید API");
    }
    const me = ctx.user.id;
    const body = ctx.request.body;
    const input = body && typeof body === "object" && !Array.isArray(body) ? body : {};
    const courseId = typeof input.course_id === "string" ? input.course_id.trim() : "";
    const rating = input.rating;
    const comment = input.comment == null ? "" : String(input.comment).trim();
    const authorName = input.author_name == null ? "" : String(input.author_name).trim();
    if (!courseId) fail(400, "course_required", "شناسهٔ دوره را با course_id بفرستید");
    // A JSON number only: true, "5" or [5] are not ratings.
    if (typeof rating !== "number" || !Number.isInteger(rating) || rating < 1 || rating > 5) {
      fail(422, "rating_out_of_range", "امتیاز باید عدد صحیحی بین ۱ و ۵ باشد");
    }
    if (comment.length > 1000) fail(400, "comment_too_long", "نظر حداکثر ۱۰۰۰ نویسه است");
    if (authorName.length > 60) fail(400, "author_name_too_long", "نام نمایشی حداکثر ۶۰ نویسه است");
    
    const mine = {student_id: me, course_id: courseId};
    if (ctx.db.admin.list("access_block", {filter: mine, limit: 1}).length > 0) {
      fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید");
    }
    const enrolled = ctx.db.admin.list("enrollment", {filter: mine, limit: 1});
    const status = enrolled.length > 0 ? enrolled[0].status : "";
    if (status !== "active" && status !== "completed") {
      fail(403, "not_enrolled", "فقط دانشجوی ثبت‌نام‌کردهٔ این دوره برایش نظر می‌نویسد");
    }
    const existing = ctx.db.admin.list("review", {filter: mine, limit: 1});
    if (existing.length > 0) {
      fail(409, "review_exists", "شما برای این دوره نظر داده‌اید؛ برای تغییرش PATCH /v1/review/" + existing[0].id + " را بفرستید");
    }
    
    const row = {student_id: me, course_id: courseId, rating: rating, review_key: me + ":" + courseId};
    if (comment) row.comment = comment;
    if (authorName) row.author_name = authorName;
    let review = null;
    try {
      review = ctx.db.admin.create("review", row);
    } catch (e) {
      if (e && e.status === 409) {
        fail(409, "review_exists", "شما برای این دوره نظر داده‌اید");
      }
      throw e;
    }
    ctx.respond(view(review));
    

اولین درخواست

نمونه‌کدی که فقط نشانی پروژه و کلید شما را کم دارد. جای خالی‌ها را بعد از ساخت پروژه، خود پنل پر می‌کند.

از ویترین تا گواهی

ویترین دوره‌ها عمومی است و با کلید عمومی و بدون ورود خوانده می‌شود. ثبت‌نام، خرید، محتوای درس، آزمون و گواهی فقط از راه فانکشن‌ها انجام می‌شوند؛ قیمت، دسترسی به محتوا و نمرهٔ آزمون را سرور تعیین می‌کند، نه اپ.

npm install @fikaro/client
import { createClient } from "@fikaro/client";

const client = createClient({
  project: "{{slug}}",
  key: "{{publishable_key}}",
});

// ۱. ویترین — عمومی، بدون ورود
const { data: courses } = await client.from("course").list({
  filter: { status: "published" },
  sort: "-createdAt",
});
const course = courses[0];
const { data: lessons } = await client.from("lesson").list({
  filter: { course_id: course.id },
  sort: "position",
});

// درس پیش‌نمایش را همه می‌بینند، حتی بدون ورود
const preview = lessons.find((l) => l.is_free_preview);
const sample = await client.request("POST", "/fn/lesson_content", { lesson_id: preview.id });

// ۲. دانشجو ثبت‌نام می‌کند
await client.auth.signup("student-1@example.com", "a-strong-password");

// ۳. دورهٔ رایگان: یک فراخوانی
//    دورهٔ پولی: سفارش، درگاه زرین‌پال، و بعد تأیید در صفحهٔ بازگشت
if (course.price === 0) {
  await client.request("POST", "/fn/enroll_free", { course_id: course.id });
} else {
  const order = await client.request("POST", "/fn/buy_course", {
    course_id: course.id,
    coupon_code: "PAEEZ20", // اختیاری
  });
  const { payment_url } = await client.request("POST", "/fn/pay_start", {
    order_id: order.id,
    callback_url: "https://academy.example.com/pay/return",
  });
  window.location.href = payment_url;
  // صفحهٔ بازگشت: /pay/return?order_id=…&Authority=…&Status=OK
  //   const q = new URLSearchParams(window.location.search);
  //   await client.request("POST", "/fn/pay_verify", {
  //     order_id: q.get("order_id"), authority: q.get("Authority"), status: q.get("Status"),
  //   });
}

// ۴. درس‌ها: محتوا، و ثبت «تمام شد»
for (const lesson of lessons) {
  const { video_url, body } = await client.request("POST", "/fn/lesson_content", { lesson_id: lesson.id });
  await client.request("POST", "/fn/complete_lesson", { lesson_id: lesson.id });
}

// ۵. آزمون: سؤال‌ها عمومی‌اند، پاسخ درست نه؛ تصحیح سمت سرور است.
//    برگه باید به همهٔ سؤال‌ها پاسخ بدهد و دفعات شرکت سقف دارد (max_attempts).
const { data: quizzes } = await client.from("quiz").list({ filter: { course_id: course.id } });
const { data: questions } = await client.from("question").list({
  filter: { quiz_id: quizzes[0].id },
  sort: "position",
});
const result = await client.request("POST", "/fn/submit_quiz", {
  quiz_id: quizzes[0].id,
  answers: Object.fromEntries(questions.map((q) => [q.id, 0])), // شمارهٔ گزینهٔ انتخابی، از ۰
});
// result.score، result.passed

// ۶. گواهی، و تأییدش با کد — بدون ورود، برای هر کسی
const cert = await client.request("POST", "/fn/issue_certificate", {
  course_id: course.id,
  holder_name: "مریم احمدی",
});
const check = await client.request("GET", "/fn/verify_certificate?code=" + cert.code);

کلید عمومی دوره، سرفصل، درس، آزمون، سؤال و نظرها را می‌خواند و امن است که داخل اپ یا APK باشد؛ ویدیو و متن درس و پاسخ درست سؤال هرگز در پاسخ مستقیم API نمی‌آیند. محتوای درس را فانکشن lesson_content فقط به دانشجوی ثبت‌نام‌کرده می‌دهد (درس پیش‌نمایش را به همه). ثبت‌نام، سفارش، پیشرفت، نمره و گواهی «فقط مال خود کاربر» هستند و مستقیم ساخته نمی‌شوند. پرداخت تا وقتی ZARINPAL_MERCHANT_ID را در secrets پروژه نگذارید کار نمی‌کند. توجه: کلید خودِ پروژه همه‌چیز را می‌بیند — اگر از پنل تست می‌کنید داده‌ای می‌بینید که اپ شما نمی‌بیند. پیش از راه‌اندازی واقعی، دادهٔ نمونه را حذف کنید: کاربرهای student@example.com و admin@example.com (مدیر)، کد تخفیف زندهٔ PAEEZ20، گواهی نمونهٔ AC-DEMO-7K2M (که اصیل نشان داده می‌شود)، سفارش AC-DEMO-0001 و سه دورهٔ نمونه با درس‌ها و آزمون‌هایشان.

از همین قالب شروع کنید؛ بک‌اندش با من.

۱۵ روز اول رایگانبا پلنکاپوچینو

اعتبار هدیهٔ ثبت‌نام هزینه‌اش را می‌دهد؛ لازم نیست حتی یک تومان پرداخت کنید.

شروع رایگان با این قالب