forked from Tadrisino/MathApp_frontend
AliReza
0ca7b39e49
The API moved to mathapi.tadrisino2.ir on 2026-09-26; api.math.tadrisino2.ir no longer resolves. .env.production is the only place that names it. deploy.sh fetches, runs npm ci and the type-check, builds into dist.next and swaps it in only when everything succeeded, so the site is never served half a build. The previous build stays in dist.prev for rollback, and a hand-edited dist/config.js on the server survives the release. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
90 lines
5.0 KiB
Markdown
90 lines
5.0 KiB
Markdown
# تدریسینو — فرانتِ اپِ ریاضی
|
||
|
||
اپِ وبِ موبایل‌محورِ تدریسینو (React + TypeScript + Vite + Tailwind). بک‌اندش ریپوی
|
||
جداست (`Tadrisino/MathApp`)؛ قراردادِ API در `/api/docs/` همان بک‌اند است.
|
||
|
||
## راه‌اندازی
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev # http://localhost:5173
|
||
```
|
||
|
||
در حالتِ توسعه، درخواست‌های `/api` از خودِ Vite به بک‌اند پاس داده می‌شوند، پس CORS
|
||
مطرح نیست. پیش‌فرض بک‌اندِ محلی است (`python manage.py runserver` روی پورتِ ۸۰۰۰).
|
||
بدونِ بک‌اندِ محلی، یک فایلِ `.env.development.local` بسازید:
|
||
|
||
```bash
|
||
VITE_DEV_PROXY_TARGET=https://mathapi.tadrisino2.ir
|
||
```
|
||
|
||
⚠️ آن‌وقت هر کاری در اپ بکنید روی دیتابیسِ واقعی نوشته می‌شود.
|
||
|
||
| دستور | کار |
|
||
|---|---|
|
||
| `npm run dev` | سرورِ توسعه |
|
||
| `npm run typecheck` | بررسیِ نوع‌ها (strict) |
|
||
| `npm run build` | type-check و بعد build در `dist/` |
|
||
| `npm run preview` | اجرای همان build |
|
||
|
||
## آدرسِ بک‌اند و عوض کردنِ دامنه
|
||
|
||
دامنه هیچ‌جای کد نیامده. آدرسِ API به این ترتیب خوانده می‌شود
|
||
(`src/config.ts`):
|
||
|
||
1. **`dist/config.js`** (از `public/config.js`) — در زمانِ اجرا. بعد از build هم روی
|
||
سرور قابلِ ویرایش است و build دوباره نمی‌خواهد.
|
||
2. **`VITE_API_BASE_URL`** — در زمانِ build، از `.env.production`.
|
||
3. **`/api`** — هم‌دامنه، وقتی nginxِ دامنه‌ی فرانت مسیرِ `/api` را به بک‌اند پراکسی کند.
|
||
|
||
برای جابه‌جایی دامنه:
|
||
|
||
- **سریع، بدونِ build:** روی سرور در `dist/config.js` بنویسید
|
||
`apiBaseUrl: "https://api.new-domain.ir/api"` و کشِ CDN را برای همین فایل پاک کنید.
|
||
- **ماندگار:** خطِ `VITE_API_BASE_URL` در `.env.production` را عوض کنید و build بگیرید.
|
||
- **سمتِ بک‌اند** هم دامنه‌ی تازه‌ی فرانت باید مجاز باشد (`FRONTEND_URL` در `.env`
|
||
بک‌اند). جزئیات در `docs/operations.md` همان ریپو.
|
||
|
||
## دیپلوی
|
||
|
||
روی سرور (`~/mathapp_frontend_new`، که nginxِ `math.tadrisino2.ir` از `dist/`ش سرو می‌کند):
|
||
|
||
```bash
|
||
./deploy.sh # fetch، npm ci، type-check، build در dist.next و جابه‌جاییِ بی‌وقفه
|
||
```
|
||
|
||
buildِ قبلی در `dist.prev` می‌ماند (برگشت: `rm -rf dist && mv dist.prev dist`)، و
|
||
`dist/config.js`ِ ویرایش‌شده روی سرور به buildِ تازه منتقل می‌شود.
|
||
|
||
جای دیگر: `npm ci && npm run build` و سرو کردنِ `dist/`. اپ مسیرِ جدا (route) ندارد و همه‌چیز از `/` بار می‌شود؛
|
||
فقط `index.html` و `config.js` نباید طولانی کش شوند (باقیِ فایل‌ها نامِ hashدار دارند).
|
||
درگاهِ پرداخت کاربر را به `/?orderId=…&status=…` برمی‌گرداند و لینکِ دعوت
|
||
`/?ref=CODE` است؛ هر دو را خودِ اپ می‌خواند.
|
||
|
||
## ساختار
|
||
|
||
```
|
||
src/
|
||
config.ts آدرسِ API (بالا را ببینید)
|
||
api/ تنها درِ ارتباط با سرور — هیچ جای دیگر fetch نمی‌زند
|
||
http.ts timeout، تکرارِ GET، refreshِ تک‌نسخه‌ای، SSE
|
||
index.ts یک تابع برای هر اندپوینت
|
||
types.ts شکلِ پاسخ‌ها، از روی پاسخِ واقعیِ سرور
|
||
app/ App (جریانِ ورود) و MainApp (تب‌ها و صفحه‌ها)
|
||
nav/ ناوبریِ پشته‌ای، هماهنگ با دکمه‌ی back گوشی
|
||
state/ داده‌ی مشترک (پروفایل، نقشه، …) و گفتگوی دستیار
|
||
screens/ یک فایل برای هر صفحه
|
||
components/ اجزای مشترک (سربرگ، برگه‌ی پایین، …)
|
||
mascots/ سه‌یار: سیگما، دلتا، پی
|
||
lib/ اعدادِ فارسی، تاریخِ شمسی، صدا، localStorage
|
||
```
|
||
|
||
قاعده‌ها:
|
||
|
||
- **اعداد:** برای نمایش `toFa`، برای ورودی `digitsOnly` (کیبوردِ فارسی ارقامِ
|
||
`۰-۹` می‌فرستد و `\d` در JS آن‌ها را نمی‌شناسد).
|
||
- **رنگ‌ها** در `src/styles/index.css` (`@theme`) تعریف شده‌اند: `bg-coral`، `text-ink`، …
|
||
- **خطا:** پیامِ کاربر همیشه از `friendlyError` می‌آید، نه متنِ خامِ سرور.
|
||
- **کلاینت را از حافظه ننویسید.** قرارداد را از `/api/docs/` بک‌اند بخوانید و تغییرِ
|
||
`types.ts` را با پاسخِ واقعیِ سرور بسنجید.
|