README rewritten as a formal entry page for the current app; Android version note corrected

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 18:47:55 +03:30
parent ca96a91dee
commit 3a0192518c
2 changed files with 83 additions and 65 deletions
--- a/README.md
+++ b/README.md
@@ -1,7 +1,20 @@
-# تدریسینو — فرانتِ اپِ ریاضی
+# تدریسینو — اپِ ریاضی (فرانت‌اند)

-اپِ وبِ موبایل‌محورِ تدریسینو (React + TypeScript + Vite + Tailwind). بک‌اندش ریپوی
-جداست (`Tadrisino/MathApp`)؛ قراردادِ API در `/api/docs/` همان بک‌اند است.
+اپِ وبِ موبایل‌محورِ **تدریسینو**، آموزشِ ریاضی به سبکِ دولینگو برای پایه‌ی سوم تا دوازدهم: نقشه‌ای از جزیره‌ها برای هر
+کتاب، آزمون‌های کوتاه از مسئله‌های خودِ کتابِ درسی، دستیارِ هوشِ مصنوعی، همراه‌ها، زنجیره‌ی روزانه و اشتراک. همین
+مخزن پوسته‌ی اندرویدِ اپ را هم دارد ([`android/`](android/README.md)).
+
+بک‌اند مخزنِ جداگانه‌ای است ([`Tadrisino/MathApp`](https://gitea.tadrisino2.ir/Tadrisino/MathApp)) و قراردادِ API
+اسکیمای OpenAPIِ همان‌جاست. این اپ تنها کلاینتِ آن API است.
+
+| | |
+|---|---|
+| **سایتِ زنده** | `https://math.tadrisino2.ir` · API: `https://mathapi.tadrisino2.ir` |
+| **فناوری** | React 18 · TypeScript (strict) · Vite 6 · Tailwind 4 · Motion |
+| **وابستگی‌ها** | عمداً کم: بی‌کتابخانه‌ی router و state؛ ناوبری و داده‌ی مشترک در خودِ کد |
+| **اندروید** | پوسته‌ی WebView روی همین سایت، با پرداختِ درون‌برنامه‌ایِ کافه‌بازار (Poolakey)؛ بسته‌ی `com.tadrisino.math.app` |
+
+---

 ## راه‌اندازی

@@ -10,15 +23,14 @@ npm install
 npm run dev          # http://localhost:5173
 ```

-در حالتِ توسعه، درخواست‌های `/api` از خودِ Vite به بک‌اند پاس داده می‌شوند، پس CORS
-مطرح نیست. پیش‌فرض بک‌اندِ محلی است (`python manage.py runserver` روی پورتِ ۸۰۰۰).
-بدونِ بک‌اندِ محلی، یک فایلِ `.env.development.local` بسازید:
+در حالتِ توسعه، Vite درخواست‌های `/api` را به بک‌اند پاس می‌دهد، پس CORS مطرح نیست. پیش‌فرض بک‌اندِ محلی است
+(`python manage.py runserver` روی پورتِ ۸۰۰۰). بدونِ بک‌اندِ محلی، فایلِ `.env.development.local` بسازید:

 ```bash
 VITE_DEV_PROXY_TARGET=https://mathapi.tadrisino2.ir
 ```

-⚠️ آن‌وقت هر کاری در اپ بکنید روی دیتابیسِ واقعی نوشته می‌شود.
+> ⚠️ در این حالت هر کاری در اپ بکنید روی دیتابیسِ واقعی نوشته می‌شود.

 | دستور | کار |
 |---|---|
@@ -27,77 +39,83 @@ VITE_DEV_PROXY_TARGET=https://mathapi.tadrisino2.ir
 | `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` همان ریپو.
-
-## روش‌های پرداخت
-
-برگه‌ی پرداخت روش‌ها را از `paymentMethods` در `dist/config.js` می‌خواند (`src/lib/paymentMethods.ts`)، جدا برای
-مرورگر (`web`) و داخلِ اپِ اندروید (`app`)؛ مقدارها `"zarinpal"` و `"bazaar"`. پیش‌فرض: مرورگر فقط زرین‌پال، اپ هر دو.
-نسخه‌ای که فقط در کافه‌بازار است: `paymentMethods: { app: ["bazaar"] }`؛ build لازم نیست، فقط کشِ CDNِ این فایل را پاک کنید.
-
-## متنِ فارسی
-
-هیچ اعرابی (کسره، فتحه، تشدید، …) و هیچ «ی»ِ اضافه‌ی نوشته‌شده («پایه‌ی سوم») به کاربر نمی‌رسد (تصمیمِ شرکت،
-۲۰۲۶-۱۰-۱۴)؛ تنوین («قبلاً») می‌ماند. متنِ تازه را همین‌طور بنویسید. متنِ سرور را بک‌اند هنگامِ ساختنِ پاسخ پاک می‌کند
-و `plainPersian` در `MathText` همان کار را برای پاسخِ زنده‌ی دستیار.
-
-## دیپلوی
-
-روی سرور (`~/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 (بالا را ببینید)
+  config.ts            آدرسِ API (بخشِ پایین)
  api/                 تنها درِ ارتباط با سرور — هیچ جای دیگر fetch نمی‌زند
-    http.ts            timeout، تکرارِ GET، refreshِ تک‌نسخه‌ای، SSE
+    http.ts            توکن، timeout، تکرارِ GET، refreshِ تک‌نسخه‌ای، SSE، Idempotency-Key
    index.ts           یک تابع برای هر اندپوینت
    types.ts           شکلِ پاسخ‌ها، از روی پاسخِ واقعیِ سرور
  app/                 App (جریانِ ورود) و MainApp (تب‌ها و صفحه‌ها)
  nav/                 ناوبریِ پشته‌ای، هماهنگ با دکمه‌ی back گوشی
-  state/               داده‌ی مشترک (پروفایل، نقشه، …) و گفتگوی دستیار
+  state/               داده‌ی مشترک (پروفایل، نقشه، کتابِ انتخاب‌شده، همراه) و گفتگوی دستیار
  screens/             یک فایل برای هر صفحه
-  components/          اجزای مشترک (سربرگ، برگه‌ی پایین، …)
-  mascots/             همراه‌ها: سیگما، دلتا، پی، تدی
-  diagram/             شکلِ جوابِ دستیار: توصیفِ JSON از بک‌اند → SVG؛ همه‌ی مختصات این‌جا حساب می‌شود
-                       (plane، shapes، expr، solid، charts، sets، misc، numberline). گالری: ?gallery فقط در dev
-  lib/                 اعدادِ فارسی، تاریخِ شمسی، صدا، localStorage
+  components/          اجزای مشترک: مسیرِ جزیره‌ها، نوارِ کتاب‌ها، برگه‌ی پایین، بازخورد، …
+  mascots/             همراه‌ها (سیگما، دلتا، پی، امگا): SVG از کد، شش حالتِ چهره
+  diagram/             شکلِ درس و جوابِ دستیار: توصیفِ JSON از بک‌اند → SVG؛ همه‌ی مختصات این‌جا حساب می‌شود
+  lib/                 اعدادِ فارسی، تاریخِ شمسی، MathText، پیامِ خطا، صدا، پلِ کافه‌بازار، روش‌های پرداخت
+android/               پوسته‌ی اندروید (README خودش)
+pay.html · src/pay.ts  صفحه‌ی واسطِ پرداختِ زرین‌پال برای اپِ اندرویدِ فعلی
 ```

 قاعده‌ها:

- **اعداد:** برای نمایش `toFa`، برای ورودی `digitsOnly` (کیبوردِ فارسی ارقامِ
-  `۰-۹` می‌فرستد و `\d` در JS آن‌ها را نمی‌شناسد).
+- **کلاینت را از حافظه ننویسید.** قرارداد را از اسکیمای بک‌اند بخوانید
+  (`python manage.py spectacular --file schema.yaml --format openapi`) و هر تغییرِ `types.ts` را با پاسخِ واقعیِ سرور بسنجید.
+- **صفحه‌ها هرگز مستقیم سرور را صدا نمی‌زنند:** همیشه `screens/* → api/index.ts → api/http.ts`.
+- **اعداد:** برای نمایش `toFa`، برای ورودی `digitsOnly` (کیبوردِ فارسی ارقامِ `۰-۹` می‌فرستد و `\d` در JS آن‌ها را نمی‌شناسد).
 - **رنگ‌ها** در `src/styles/index.css` (`@theme`) تعریف شده‌اند: `bg-coral`، `text-ink`، …
 - **خطا:** پیامِ کاربر همیشه از `friendlyError` می‌آید، نه متنِ خامِ سرور.
- **کلاینت را از حافظه ننویسید.** قرارداد را از `/api/docs/` بک‌اند بخوانید و تغییرِ
-  `types.ts` را با پاسخِ واقعیِ سرور بسنجید.
+- **متنِ فارسی** بی‌اعراب و بی «ی»ِ اضافه‌ی نوشته‌شده («پایه‌ی سوم») است (تصمیمِ شرکت)؛ تنوین («قبلاً») می‌ماند. متنِ تازه
+  را همین‌طور بنویسید. متنِ سرور را بک‌اند هنگامِ ساختنِ پاسخ پاک می‌کند و `plainPersian` در `MathText` همان کار را برای
+  پاسخِ زنده‌ی دستیار. `lib/plainMath.ts` هر LaTeX یا markdownی را که برسد ساده می‌کند و باید با `content/plain_math.py`ِ
+  بک‌اند هم‌رفتار بماند.
+
+---
+
+## آدرسِ بک‌اند و عوض کردنِ دامنه
+
+دامنه هیچ‌جای کد نیامده. آدرسِ API به این ترتیب خوانده می‌شود (`src/config.ts`):
+
+1. **`dist/config.js`** (از `public/config.js`) — در زمانِ اجرا؛ بعد از build هم روی سرور ویرایش‌شدنی است.
+2. **`VITE_API_BASE_URL`** — در زمانِ build، از `.env.production`.
+3. **`/api`** — هم‌دامنه، وقتی nginxِ دامنه‌ی فرانت مسیرِ `/api` را به بک‌اند پراکسی کند.
+
+برای جابه‌جاییِ دامنه:
+
+- **سریع، بدونِ build:** روی سرور در `dist/config.js` بنویسید `apiBaseUrl: "https://<دامنه‌ی تازه>/api"` و کشِ آروان را
+  برای همین فایل پاک کنید.
+- **ماندگار:** خطِ `VITE_API_BASE_URL` در `.env.production` را عوض کنید و build بگیرید.
+- **سمتِ بک‌اند** دامنه‌ی تازه‌ی فرانت باید مجاز باشد (`FRONTEND_URL`)، و در CSPِ nginx (`connect-src`) دامنه‌ی تازه‌ی API
+  بیاید. رویه‌ی کامل: `docs/operations.md`ِ بک‌اند، بخشِ «عوض کردنِ دامنه».
+
+## روش‌های پرداخت
+
+برگه‌ی پرداخت روش‌ها را از `paymentMethods` در `dist/config.js` می‌خواند (`src/lib/paymentMethods.ts`)، جدا برای مرورگر
+(`web`) و داخلِ اپِ اندروید (`app`)؛ مقدارها `"zarinpal"` و `"bazaar"`. پیش‌فرض: مرورگر فقط زرین‌پال، اپ هر دو. نسخه‌ای که
+فقط در کافه‌بازار است: `paymentMethods: { app: ["bazaar"] }`؛ build لازم نیست، فقط کشِ آروانِ این فایل را پاک کنید.
+
+---
+
+## انتشار
+
+روی سرور (`~/mathapp_frontend_new`، که nginxِ `math.tadrisino2.ir` از `dist/`ش سرو می‌کند):
+
+```bash
+cd ~/mathapp_frontend_new && ./deploy.sh   # fetch، npm ci، type-check، build در dist.next و جابه‌جاییِ بی‌وقفه
+```
+
+buildِ قبلی در `dist.prev` می‌ماند (برگشت: `rm -rf dist && mv dist.prev dist`) و `dist/config.js`ِ ویرایش‌شده روی سرور به
+buildِ تازه منتقل می‌شود. سرور مشترکِ شرکت است: پیش از هر کار آن‌جا قواعدِ `CLAUDE.md`ِ بک‌اند (بخشِ «Working on the
+servers») را بخوانید.
+
+جای دیگر: `npm ci && npm run build` و سرو کردنِ `dist/`. اپ مسیرِ جدا (route) ندارد و همه‌چیز از `/` بار می‌شود؛ فقط
+`index.html` و `config.js` نباید طولانی کش شوند (باقیِ فایل‌ها نامِ hashدار دارند). درگاهِ پرداخت کاربر را به
+`/?orderId=…&status=…` برمی‌گرداند و لینکِ دعوت `/?ref=CODE` است؛ هر دو را خودِ اپ می‌خواند.
+
+CSPِ سایت در nginx است (`ops/nginx/zareian-front-headers.conf` در مخزنِ بک‌اند). اگر اسکریپتِ درون‌خطیِ `index.html` عوض
+شود، هشِ تازه‌اش باید در همان فایل بنشیند، وگرنه مرورگر آن را اجرا نمی‌کند.