MathApp_frontend/src/api/README.md

اتصال به بک‌اند

کلِ ارتباط با سرور از همین پوشه رد می‌شود. هیچ‌جای اپ مستقیم fetch نزنید — مدیریتِ توکن، تکرارِ درخواست و رفتارِ درستِ خطا اینجا یک‌جا حل شده‌اند.

راه‌اندازی

هیچ تنظیماتی لازم نیست. به‌طورِ پیش‌فرض به بک‌اندِ مشترک (https://api.math.tadrisino2.ir/api) وصل می‌شود:

npm install
npm run dev

فقط اگر بک‌اند را روی ماشینِ خودتان بالا آورده‌اید:

cp .env.example .env      # و خطِ VITE_API_BASE_URL را باز کنید

برای اینکه ببینید اتصال برقرار است، یک خط کافی‌ست (بعداً پاکش کنید):

import { ConnectionCheck } from '@/api/ConnectionCheck';
// داخلِ خروجیِ App:
<ConnectionCheck />

گوشه‌ی صفحه سبز می‌شود و فهرستِ پایه‌ها را از سرور نشان می‌دهد، یا قرمز می‌شود و می‌گوید دقیقاً کجای کار می‌لنگد.

استفاده

import { api, ApiError } from '@/api';

const grades  = await api.grades();
const home    = await api.home();                    // پایه‌ی خودِ کاربر
const intro   = await api.lessons.intro(lessonId);
const answer  = await api.ai.ask('این رو نفهمیدم', { lessonId });

ورود

await api.auth.guest(deviceId);                 // «شروع سریع»، بدونِ شماره
// یا
const { devOtp } = await api.auth.requestOtp('09120000000');
await api.auth.login('09120000000', otp);       // نامِ فیلد در سرور otp است

توکن خودش در localStorage ذخیره می‌شود و به هر درخواست اضافه می‌گردد.

خطاها

try {
  await api.ai.ask(text, { lessonId });
} catch (error) {
  if (error instanceof ApiError) {
    if (error.isRateLimited) { /* ۴۲۹ — خیلی سریع پرسیده */ }
    if (error.isProviderDown) { /* ۵۰۳ — سرویسِ AI موقتاً قطع */ }
    if (error.isNetwork) { /* اصلاً نرسید یا timeout */ }
  }
}

چرا این‌قدر ملاحظه در client.ts

هر تکه‌اش برای حالتی‌ست که فقط زیرِ فشار پیش می‌آید:

مسئله	اگر نباشد چه می‌شود
timeout روی هر درخواست	یک بک‌اندِ کند سوکت‌ها را باز نگه می‌دارد؛ مرورگر به سقفِ ۶ درخواستِ همزمان می‌خورد و کلِ اپ قفل می‌شود
backoff با jitter	هزار کلاینت بعد از یک خطا همزمان دوباره می‌زنند و موجِ دوم سرور را می‌خواباند
تکرارِ خودکار فقط روی GET	تکرارِ POST یعنی سفارش یا پاسخِ تکراری
Idempotency-Key روی ثبتِ پاسخ و سفارش	دابل‌کلیکِ کاربر دو بار XP یا دو سفارش می‌سازد
refresh تک‌نسخه‌ای	۲۰ درخواستِ همزمانِ ۴۰۱ ⇒ ۲۰ بار refresh ⇒ سرور همه را throttle می‌کند
ادغامِ GETهای یکسان	دو کامپوننت که با هم یک چیز می‌خواهند، دو برابر بار می‌سازند
احترام به هدرِ Retry-After	بک‌اند صریح می‌گوید چقدر صبر کن؛ نادیده گرفتنش throttle را طولانی‌تر می‌کند

credentials: 'omit' هم عمدی‌ست: احرازِ هویت توکنِ Bearer در هدر است و سمتِ سرور CORS_ALLOW_CREDENTIALS=False تنظیم شده. عوضش نکنید.

چیزی که هنوز نیست

• صفحه‌ی ورود در اپ وجود ندارد؛ api.auth آماده است ولی UI ندارد.
• api.home() ساختارِ واقعیِ درس‌ها را می‌دهد، ولی وصل کردنش به صفحه‌ها هنوز انجام نشده — این PR عمداً App.tsx را دست نزده تا با کارِ در جریان تصادف نکند.