Zareian
5492788bf8
The README had grown into a 295-line mixture of onboarding, an ops runbook, a content-authoring workflow, bulk question generation and a Docker log stack. A reader arriving at the repo could not tell in ten seconds what this service is, whether it is live, or where to start, and five of its claims no longer matched the code: - it said to export .env values by hand; settings.py has loaded .env through python-dotenv for a while now - it listed six variables as "everything the app actually reads"; .env.example has carried many more than that for some time - it called DJANGO_SECRET_KEY, DJANGO_ALLOWED_HOSTS and CACHE_URL required in production; all three now have working defaults, and the app boots without them on purpose so a partial .env cannot take the service down - it claimed there is no insecure SECRET_KEY fallback; there is one, under DEBUG - it required Python 3.12 while the project runs on 3.11 (Docker uses 3.12) The README now states what the service is, where it runs, how healthy it is and how to get it running in six commands, then links onward. Procedures moved to docs/operations.md, docs/content-authoring.md, docs/architecture.md and docs/docker.md, which is where someone follows a procedure rather than skims it. Nothing was dropped; the deploy one-liner now includes the separate sudo restart that deploy.sh cannot perform itself, and backup/restore is written down for the first time. Every number in the README was measured rather than quoted: content counts from the live /api/health and content/seed/curriculum.json, 55 endpoints from the generated OpenAPI schema, 481 tests from a full run. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
151 lines
8.5 KiB
Markdown
151 lines
8.5 KiB
Markdown
# Tadrisino API
|
||
|
||
بک‌اندِ اپلیکیشنِ آموزشیِ تدریسینو — یک REST API روی Django که برنامه‌ی درسی،
|
||
آزمون‌ها، پیشرفتِ کاربر، دستیارِ هوشِ مصنوعی، اشتراک و پرداخت را سرو می‌کند.
|
||
|
||
فرانت‌اند ریپوی جداگانه‌ای است ([`MathApp_frontend`](https://gitea.tadrisino2.ir/Tadrisino/MathApp_frontend)).
|
||
**قراردادِ بینِ دو طرف، اسکیمای OpenAPI همین ریپوست** — نه حافظه‌ی کسی، نه یک
|
||
فایلِ دستی. هر تغییری در API باید از آنجا دیده شود.
|
||
|
||
| | |
|
||
|---|---|
|
||
| **وضعیت** | روی پروداکشن، در حالِ سرویس‌دهی |
|
||
| **آدرسِ زنده** | `https://api.math.tadrisino2.ir` · [سلامت](https://api.math.tadrisino2.ir/api/health) |
|
||
| **استک** | Python 3.11+ · Django 5.2 · DRF · SQLite · Qdrant (RAG) |
|
||
| **API** | ۵۵ اندپوینت · مستنداتِ زنده در `/api/docs/` |
|
||
| **تست** | ۴۸۱ تست، همه سبز (`python manage.py test`) |
|
||
| **محتوا** | ۸ پایه · ۵۸ فصل · ۲۶۳ نود · ۲٬۶۱۷ درس · ۲٬۴۶۳ سوال |
|
||
|
||
---
|
||
|
||
## شروعِ سریع
|
||
|
||
```bash
|
||
python3 -m venv venv && source venv/bin/activate
|
||
pip install -r requirements.txt
|
||
cp .env.example .env # برای توسعه‌ی محلی: DJANGO_DEBUG=1 را ست کنید
|
||
python manage.py migrate
|
||
python manage.py seed_content # برنامه‌ی درسی و سوال‌های واقعی از content/seed/
|
||
python manage.py runserver
|
||
```
|
||
|
||
سرویس روی `http://127.0.0.1:8000` بالا می‌آید. `.env` خودکار خوانده می‌شود —
|
||
لازم نیست چیزی را `export` کنید.
|
||
|
||
| | |
|
||
|---|---|
|
||
| Swagger UI | `/api/docs/` |
|
||
| Redoc | `/api/redoc/` |
|
||
| اسکیمای OpenAPI | `/api/schema/` |
|
||
| پنلِ ادمین | `/admin/` |
|
||
| سلامتِ سرویس | `/api/health` |
|
||
|
||
**اولین درخواست در Swagger:** `POST /api/auth/session` با
|
||
`{"type":"guest","deviceId":"d_test1"}` بزنید، `token` را بردارید، روی
|
||
**Authorize** کلیک کنید و همان رشته را (بدونِ کلمه‌ی `Bearer`) وارد کنید.
|
||
|
||
دستورهای پرکاربردِ دیگر:
|
||
|
||
```bash
|
||
python manage.py test # کلِ تست‌سوییت
|
||
python manage.py createsuperuser # دسترسی به /admin
|
||
python manage.py seed_test_data # داده‌ی ساختگی برای توسعه (فقط محلی)
|
||
```
|
||
|
||
---
|
||
|
||
## معماری
|
||
|
||
هر اپ یک مسئولیت دارد و مدل‌های خودش را نگه می‌دارد:
|
||
|
||
| اپ | مسئولیت |
|
||
|---|---|
|
||
| `accounts` | هویت، session، ورود با OTP |
|
||
| `content` | برنامه‌ی درسی، درس، سوال، پیشرفت روی نقشه |
|
||
| `progress` | آمار، لیدربرد، streak، شخصیت‌های بازی |
|
||
| `ai_tutor` · `rag` | دستیارِ هوشِ مصنوعی: بازیابی از Qdrant + تولید با GPT |
|
||
| `subscription` · `payment` · `discount` | پلن، سفارش، تراکنش، کدِ تخفیف |
|
||
| `notifications` · `affiliate` · `support` · `family` · `campaigns` | امکاناتِ جانبی |
|
||
| `statuslog` | لاگِ عمومیِ تغییرِ وضعیت، مستقل از بقیه |
|
||
| `config` | تنظیمات، روت‌های اصلی، middleware |
|
||
|
||
سه تصمیمِ معماری که غیرِبدیهی‌اند و دانستنشان لازم است:
|
||
|
||
- **احرازِ هویت، سیستمِ خودمان است نه جنگو.** توکنِ bearerِ امضاشده و stateless
|
||
با `django.core.signing` (بدونِ کتابخانه‌ی JWT)، پشتیبانی‌شده با مدلِ
|
||
`accounts.Session`. `accounts.User` عمداً `AUTH_USER_MODEL` **نیست** — یک
|
||
مدلِ بیزنسیِ مستقل است. هدرِ نامعتبر یعنی درخواستِ ناشناس، نه خطا؛ هر ویو
|
||
خودش تصمیم می‌گیرد که آیا ورود لازم است یا نه (`accounts/authentication.py`).
|
||
- **اپ‌ها با قرارداد از هم جدا شده‌اند، نه با ForeignKey.** ارجاعِ بینِ اپ‌ها با
|
||
`user_id` و `object_id` + `label` انجام می‌شود تا هر اپ بعداً قابلِ جدا شدن
|
||
باشد. **FK بینِ اپ‌ها اضافه نکنید.**
|
||
- **محدودیتِ نرخ (throttle) متمرکز است.** هر اندپوینتِ حساس یک
|
||
`throttle_scope` دارد و نرخش در `REST_FRAMEWORK['DEFAULT_THROTTLE_RATES']`
|
||
داخلِ `config/settings.py` تعریف می‌شود. اندپوینتِ جدید یعنی **هر دو**.
|
||
|
||
جزئیاتِ بیشتر: [`docs/architecture.md`](docs/architecture.md).
|
||
|
||
---
|
||
|
||
## دیپلوی
|
||
|
||
کلِ انتشار یک خط است:
|
||
|
||
```bash
|
||
ssh -t administrator@78.38.35.249 \
|
||
'cd ~/mathapp-v2 && ./deploy.sh; sudo systemctl restart zareian-mathapp'
|
||
```
|
||
|
||
`deploy.sh` کد را می‌گیرد، وابستگی‌ها را نصب می‌کند، مهاجرت می‌زند، محتوا را
|
||
seed می‌کند، فایل‌های استاتیک را جمع می‌کند و در پایان **ثابت می‌کند که سرویس
|
||
واقعاً ری‌استارت شده** — نه اینکه فقط فرض کند. ری‌استارت جداست چون `sudo`
|
||
داخلِ اسکریپت نمی‌تواند رمز بپرسد.
|
||
|
||
پس از هر انتشار، از بیرون و بدونِ SSH تأیید کنید:
|
||
|
||
```bash
|
||
curl https://api.math.tadrisino2.ir/api/health
|
||
```
|
||
|
||
`200` یعنی سالم، `503` یعنی چیزی واقعاً خراب است. هیچ سکرتی برنمی‌گرداند.
|
||
|
||
رویه‌ی کامل — متغیرهای محیطی، ورودِ توسعه‌دهنده‌ها، بکاپ، عیب‌یابی:
|
||
[`docs/operations.md`](docs/operations.md).
|
||
|
||
---
|
||
|
||
## مستندات
|
||
|
||
| سند | موضوع |
|
||
|---|---|
|
||
| [`docs/operations.md`](docs/operations.md) | دیپلوی، متغیرهای محیطی، سلامت، بکاپ، ورودِ توسعه‌دهنده‌ها |
|
||
| [`docs/content-authoring.md`](docs/content-authoring.md) | افزودن و ویرایشِ محتوا از پنلِ ادمین، ساختِ انبوهِ سوال |
|
||
| [`docs/architecture.md`](docs/architecture.md) | تصمیم‌های معماری و دلیلشان |
|
||
| [`docs/frontend/README.md`](docs/frontend/README.md) | راهنمای اتصالِ فرانت‌اند + کلاینتِ تایپ‌دار |
|
||
| [`docs/docker.md`](docs/docker.md) | استکِ لاگِ محلی (Loki + Alloy + Grafana) |
|
||
| [`docs/extraction-playbook.md`](docs/extraction-playbook.md) | استخراجِ محتوا از کتاب با مدلِ ویژن و هزینه‌هایش |
|
||
|
||
---
|
||
|
||
## محدودیت‌های شناخته‌شده
|
||
|
||
اینها عمداً نوشته شده‌اند تا کسی دوباره کشفشان نکند:
|
||
|
||
- **دیتابیس هنوز SQLite است**، نه Postgres. برای حجمِ فعلی کافی‌ست، ولی
|
||
تک‌نویسنده بودنش اولین گلوگاهِ مقیاس است.
|
||
- **بکاپِ خودکار وجود ندارد.** `db.sqlite3` در گیت نیست و تنها نسخه‌ی داده‌ی
|
||
کاربران است. روشِ بکاپِ دستی در [`docs/operations.md`](docs/operations.md)
|
||
آمده؛ خودکار کردنش اولین کارِ ارزشمندِ بعدی است.
|
||
- **`CACHE_URL` روی سرور ست نشده**، پس محدودیتِ نرخ بینِ workerها مشترک نیست.
|
||
Redis روی همان ماشین بالاست. `/api/health` این را هشدار می‌دهد.
|
||
- **`KAVENEGAR_API_KEY` تنظیم نشده**، پس `POST /api/auth/otp/request` برای
|
||
شماره‌های واقعی `503` می‌دهد. راهِ ورودِ تیمِ توسعه در
|
||
[`docs/operations.md`](docs/operations.md) توضیح داده شده.
|
||
- **پوششِ محتوا یکدست نیست.** پایه‌های هشتم تا دوازدهم کاملند (هر نود چهار
|
||
سوال)؛ در پایه‌های سوم/ششم/هفتم ۳۹ نود از ۱۴۵ کمتر از چهار سوال دارند —
|
||
هیچ‌کدام خالی نیست، پس روی نقشه نودِ غیرقابلِ بازی وجود ندارد.
|
||
- **محتوای ویدیویی وجود ندارد**، هرچند `Lesson.kind` و `video_url` می‌توانند
|
||
بیانش کنند.
|
||
- **`DEV_MASTER_OTP` (کد `0000`) باید پشتِ `DEBUG` بماند.** روشن بودنش یعنی هر
|
||
کسی می‌تواند به‌جای هر کاربری وارد شود. `/api/health` هشدارش می‌دهد.
|