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` عوض
+شود، هشِ تازه‌اش باید در همان فایل بنشیند، وگرنه مرورگر آن را اجرا نمی‌کند.
--- a/android/README.md
+++ b/android/README.md
@@ -40,7 +40,7 @@
 - **«برای خروج دوباره بزن»**: دکمه‌ی برگشتِ گوشی حالا قدم‌به‌قدم در خودِ وب عقب می‌رود (`src/nav/Navigator.tsx`) و
  از خانه یک‌راست بیرون می‌رود. اگر تأییدِ خروج خواستید، در `handleOnBackPressed` وقتی `!webView.canGoBack()` یک
  Toast بدهید و فقط برگشتِ دوم در دو ثانیه `finish()` کند. در وب شدنی نیست (کروم ورودیِ history بی‌لمس را رد می‌کند).
- `versionCode`/`versionName` را برای هر نسخه بالا ببرید؛ هنوز ۱ و 1.0.0 است.
+- `versionCode`/`versionName` را برای هر نسخه‌ای که منتشر می‌شود بالا ببرید؛ الان ۲ و 1.1.0 است (بازار فقط `versionCode`ِ بزرگ‌تر را می‌پذیرد).

 قانونِ بازار: داخلِ اپِ بازار حالا پرداخت با درگاه هم پیشنهاد می‌شود (خواستِ مالک). بازار پرداختِ محتوای دیجیتال بیرون از
 پرداختِ درون‌برنامه‌ای را محدود می‌کند؛ پیش از انتشار در بازار این را با بازار یا مالک روشن کنید.