افزودنِ لایه‌ی اتصال به API بک‌اند (بدونِ تغییر در App.tsx) #1

AliReza_Zareian · 2026-09-13T20:21:31+03:30

AliReza_Zareian commented

2026-09-13 20:21:31 +03:30

سلام 👋

این PR لایه‌ی اتصال به بک‌اند را اضافه می‌کند. عمداً هیچ فایلِ موجودی را دست نزده‌ام — نه App.tsx، نه package.json، نه هیچ کامپوننتی. فقط پوشه‌ی تازه‌ی src/api/ اضافه شده (به‌علاوه‌ی سه خط به .gitignore).

دلیلش این است که کارِ در جریانِ برنچِ updateApp روی App.tsx است و نمی‌خواستم دو تا تغییر روی یک فایل بیفتد. پس این PR با آن کار تصادف نمی‌کند و هر وقت که راحت بودید merge می‌شود.

چطور امتحانش کنید (دو دستور)

npm install
npm run dev

هیچ تنظیماتی لازم نیست — به‌طورِ پیش‌فرض به بک‌اندِ مشترک وصل می‌شود.

برای اینکه ببینید اتصال برقرار است، یک خط به هر جای صفحه اضافه کنید:

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

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

استفاده

import { api } 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 });

لازم نیست به توکن، هدر، یا آدرسِ سرور فکر کنید — همه‌اش داخلِ src/api/ حل شده. راهنمای کامل در src/api/README.md است.

چه چیزی اضافه شد

فایل	چه می‌کند
`src/api/client.ts`	هسته: timeout، تلاشِ دوباره با فاصله‌ی تصادفی، refreshِ توکن، ادغامِ درخواست‌های تکراری
`src/api/index.ts`	اندپوینت‌های آماده و تایپ‌دار
`src/api/types.ts`	تایپِ همه‌ی پاسخ‌های سرور
`src/api/ConnectionCheck.tsx`	ویجتِ بررسیِ اتصال (ابزارِ توسعه)
`src/api/README.md`	راهنما
`.env.example`	فقط اگر بک‌اندِ محلی داشته باشید لازم است

هیچ پکیجِ جدیدی اضافه نشده — فقط fetch استاندارد. package.json و package-lock.json دست‌نخورده‌اند.

تستِ انجام‌شده

npm run build سبز
tsc --strict روی هر ۴ فایلِ جدید، صفر خطا

اگر جایی‌اش به سلیقه یا ساختارِ شما نمی‌خورد، حتماً بگویید — عوضش می‌کنم. تصمیمِ merge هم کاملاً با خودتان است. 🙏

سلام 👋 این PR لایه‌ی اتصال به بک‌اند را اضافه می‌کند. **عمداً هیچ فایلِ موجودی را دست نزده‌ام** — نه `App.tsx`، نه `package.json`، نه هیچ کامپوننتی. فقط پوشه‌ی تازه‌ی `src/api/` اضافه شده (به‌علاوه‌ی سه خط به `.gitignore`). دلیلش این است که کارِ در جریانِ برنچِ `updateApp` روی `App.tsx` است و نمی‌خواستم دو تا تغییر روی یک فایل بیفتد. پس این PR با آن کار **تصادف نمی‌کند** و هر وقت که راحت بودید merge می‌شود. ## چطور امتحانش کنید (دو دستور) ```bash npm install npm run dev ``` هیچ تنظیماتی لازم نیست — به‌طورِ پیش‌فرض به بک‌اندِ مشترک وصل می‌شود. برای اینکه ببینید اتصال برقرار است، یک خط به هر جای صفحه اضافه کنید: ```tsx import { ConnectionCheck } from '@/api/ConnectionCheck'; // داخلِ خروجی: <ConnectionCheck /> ``` گوشه‌ی صفحه سبز می‌شود و می‌گوید چند پایه از سرور آمد، یا قرمز می‌شود و **دقیقاً** می‌گوید مشکل کجاست. بعد از امتحان می‌توانید همان یک خط را پاک کنید. ## استفاده ```tsx import { api } 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 }); ``` لازم نیست به توکن، هدر، یا آدرسِ سرور فکر کنید — همه‌اش داخلِ `src/api/` حل شده. راهنمای کامل در `src/api/README.md` است. ## چه چیزی اضافه شد | فایل | چه می‌کند | |---|---| | `src/api/client.ts` | هسته: timeout، تلاشِ دوباره با فاصله‌ی تصادفی، refreshِ توکن، ادغامِ درخواست‌های تکراری | | `src/api/index.ts` | اندپوینت‌های آماده و تایپ‌دار | | `src/api/types.ts` | تایپِ همه‌ی پاسخ‌های سرور | | `src/api/ConnectionCheck.tsx` | ویجتِ بررسیِ اتصال (ابزارِ توسعه) | | `src/api/README.md` | راهنما | | `.env.example` | فقط اگر بک‌اندِ محلی داشته باشید لازم است | **هیچ پکیجِ جدیدی اضافه نشده** — فقط `fetch` استاندارد. `package.json` و `package-lock.json` دست‌نخورده‌اند. ## تستِ انجام‌شده - `npm run build` سبز - `tsc --strict` روی هر ۴ فایلِ جدید، صفر خطا --- اگر جایی‌اش به سلیقه یا ساختارِ شما نمی‌خورد، حتماً بگویید — عوضش می‌کنم. تصمیمِ merge هم کاملاً با خودتان است. 🙏

AliReza_Zareian added 1 commit 2026-09-13 20:21:32 +03:30

add a typed API layer for the Tadrisino backend be9f99d52a

اپ تا الان هیچ درخواستی به سرور نمی‌زد و همه‌ی داده‌ها داخلِ خودِ کامپوننت‌ها
هاردکد بود. این کامیت لایه‌ی ارتباط را اضافه می‌کند، بدونِ اینکه هیچ صفحه‌ای
را تغییر دهد.

عمداً فقط فایلِ جدید اضافه شده و App.tsx دست نخورده است، چون کارِ در جریانِ
برنچِ updateApp روی همان فایل است و نباید با هم تصادف کنند. وصل کردنِ
صفحه‌ها به این لایه کارِ بعدی‌ست.

هیچ پکیجِ جدیدی اضافه نشد — فقط fetch استاندارد.

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

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

.env هم به .gitignore اضافه شد؛ قبلاً فقط node_modules داخلش بود و آدرس/
تنظیماتِ محلی می‌توانست ناخواسته کامیت شود.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

AliReza_Zareian added 1 commit 2026-09-13 21:41:30 +03:30

match the real API contract, verified against a running backend f61c58eb76

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

چیزهایی که غلط بودند:
• ثبتِ پاسخ به /lessons/{id}/answer می‌رفت — چنین مسیری وجود ندارد.
مسیرِ درست /questions/{id}/answer است و فیلدش selectedOptionId، نه
questionId/choiceId.
• /ai/ask فیلدِ userQuestion می‌خواهد، نه question. با نامِ غلط، پرسش
اصلاً به مدل نمی‌رسید.
• فیدبک isHelpful بولین می‌خواهد، نه رشته‌ی up/down.
• UserProfile فیلدهای xp/coins/streak را نداشت (آن‌ها در /user/summary
هستند) و isGuest/phone را نداشت.
• شناسه‌ها در پاسخ‌ها رشته‌اند، نه عدد.

پاسخِ دستیار هم usedChunks دارد نه sources؛ خالی بودنش یعنی از کتاب چیزی
پیدا نشده، که همان چیزی‌ست که برچسبِ «بر اساسِ کتاب» به آن نیاز دارد.

questions.report تازه اضافه شد: بک‌اند حالا POST /questions/{id}/report
دارد تا کاربر بتواند ایرادِ خودِ سوال را گزارش کند.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Zrabg merged commit 82c9e870b3 into main

2026-09-13 22:07:56 +03:30

Zrabg referenced this issue from a commit

2026-09-13 22:07:57 +03:30

Merge pull request 'افزودنِ لایه‌ی اتصال به API بک‌اند (بدونِ تغییر در App.tsx)' (#1) from AliReza_Zareian/MathApp_frontend:zareian/api-client into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Tadrisino/MathApp_frontend#1

Allow edits from maintainers