MathApp/README.md

Tadrisino API

بک‌اند اپلیکیشن آموزشی Tadrisino — Django + Django REST Framework.

احراز هویت با OTP، محتوای درسی و پیشرفت کاربر، دستیار هوش مصنوعی، اشتراک و پرداخت، تخفیف، اعلان‌ها، همکاری در فروش، پشتیبانی و حساب خانواده.

اجرا

python3 -m venv venv
source venv/bin/activate        # ویندوز: venv\Scripts\activate
pip install -r requirements.txt

# مهم: از این به بعد DEBUG دیفالتش False هست (برای امنیتِ پروداکشن).
# برای اجرای محلی/تست با Swagger (که به DEV_MASTER_OTP و devOtp توی
# پاسخ نیاز داره)، این env var رو ست کنید:
export DJANGO_DEBUG=1            # ویندوز (PowerShell): $env:DJANGO_DEBUG=1

python manage.py migrate
python manage.py createsuperuser   # اختیاری، برای /admin
python manage.py runserver

در پروداکشن، DJANGO_DEBUG رو ست نکنید (یا 0 بذارید) و حتماً DJANGO_SECRET_KEY و DJANGO_ALLOWED_HOSTS (کاما-جدا) رو هم از env بدید.

اجرا با Docker (اپ + استکِ لاگِ متمرکز)

برای اجرای محلی، در کنارِ Django یک استکِ لاگِ متمرکز هم فراهم شده: Loki (ذخیره‌سازیِ لاگ) + Grafana Alloy (جمع‌آوریِ لاگ از فایلِ اپ) + Grafana (جستجو/فیلترِ لاگ‌ها). این فقط برای dev/local هست، نه یک تنظیمِ پروداکشن (مثلاً هنوز از runserver استفاده می‌شه، نه gunicorn).

# اختیاری: تنظیماتِ خودتون رو ست کنید (وگرنه دیفالت‌های dev استفاده می‌شن)
cp .env.example .env

docker compose up --build

• اپ Django: http://localhost:8000
• Grafana: http://localhost:3000 (بدونِ نیاز به لاگین، anonymous admin فعاله؛ فقط برای محیطِ محلی)

داشبوردِ «Tadrisino Django Logs» به‌صورتِ خودکار در Grafana لود می‌شه و امکانِ فیلتر بر اساسِ سطحِ لاگ (level) و جستجوی متنی رو می‌ده.

جریانِ لاگ: Django همون خطوطِ JSON موجود رو (بدونِ تغییرِ پیام‌ها یا محافظت‌های حساسیتی) هم روی stdout و هم در /var/log/django/app.log (یک ولومِ Docker) می‌نویسه ← Grafana Alloy این فایل رو می‌خونه ← به Loki push می‌کنه ← Grafana از Loki می‌خونه. جزئیاتِ بیشتر در کامنت‌های بالای docker-compose.yml، docker/alloy/config.alloy و config/settings.py (بخشِ LOG_DIR).

اجرای بدونِ Docker (روش قبلی، بالای همین فایل) دقیقاً همون‌طور که بود کار می‌کنه — LOG_DIR فقط داخلِ Docker ست می‌شه.

مستندات API

Swagger UI	http://127.0.0.1:8000/api/docs/
Redoc	http://127.0.0.1:8000/api/redoc/
پنل ادمین	http://127.0.0.1:8000/admin/

شروع سریع در Swagger:

1. POST /api/auth/session با {"type":"guest","deviceId":"d_test1"} → یک token بگیرید.
2. روی دکمه‌ی Authorize بزنید و فقط خودِ token رو (بدون کلمه‌ی Bearer) وارد کنید.
3. برای تست لاگین با شماره: POST /api/auth/otp/request بزنید، یا در محیط توسعه کد 0000 رو با هر شماره‌ای در /api/auth/login امتحان کنید.

ساختار پروژه

اپ	مسئولیت	مدل‌های اصلی
accounts	هویت کاربر و session	User, Profile, Session, OTPCode
content	محتوای درسی و پیشرفت روی درس	Grade, Unit, Node, Lesson, Question, Choice, NodeProgress
progress	آمار، لیدربرد، streak	UserStats, LeaderboardEntry, StreakRecord, UserHearts
ai_tutor	دستیار هوش مصنوعی	Conversation, Message, MessageFeedback
subscription	پلن و اشتراک	Plan, Subscription
payment	سفارش و تراکنش	Order, Transaction
discount	کد تخفیف و آفر	DiscountCode, Redemption, Offer, UserOffer
notifications	اعلان‌ها	Notification
affiliate	همکاری در فروش	AffiliateAccount, Conversion
support	تیکت و گزارش باگ	BugReport, Ticket, TicketMessage
family	حساب خانواده / کنترل والدین	FamilyLink, ParentalSettings, WeeklyReportLog
statuslog	لاگ عمومی تغییر status، مستقل از بقیه‌ی اپ‌ها	StatusChangeLog
config	تنظیمات و url های اصلی پروژه	—

نکات فنی مهم

• احراز هویت: Bearer token امضاشده و stateless (django.core.signing، بدون کتابخانه‌ی JWT خارجی)، هماهنگ با مدل Session.
• accounts.User عمداً AUTH_USER_MODEL جنگو نیست؛ یک مدل بیزنسی مستقل است.
• بین اپ‌ها به‌جای FK واقعی از ارجاع سبک (user_id, object_id + label) استفاده شده تا هر اپ در آینده قابل جدا شدن باشد.
• POST /api/ai/ask فعلاً پاسخ stub برمی‌گرداند؛ محل اتصال مدل واقعی در ai_tutor/views.py (تابع generate_tutor_answer) مشخص شده.
• DEV_MASTER_OTP (کد 0000) فقط برای تست در توسعه است — پیش از دیپلوی پروداکشن باید حذف یا به DEBUG مقیّد شود.
• لاگِ ساختاریافته: همه‌ی درخواست‌های /api/ به‌صورتِ JSON لاگ می‌شن (متد/مسیر/وضعیت/مدت/کاربر، بدونِ بدنه/هدر/سکرت)؛ قابلِ مشاهده و جست‌وجو در Grafana (بخشِ Docker بالا).

قبل از دیپلوی پروداکشن

• DEBUG و SECRET_KEY و ALLOWED_HOSTS از env خونده می‌شن (دیفالتِ DEBUG روی False است)
• DEV_MASTER_OTP و برگردوندنِ devOtp توی پاسخ، فقط وقتی DEBUG=True فعالن؛ در پروداکشن غیرفعالن
• rate limit (throttle) روی endpointهای احرازهویت و بقیه‌ی endpointهای حساسِ پروژه (پرداخت، خرید اشتراک، تخفیف، AI، محتوا، خانواده، پشتیبانی، affiliate، …) پیاده‌سازی شده؛ برای کاربرهای مهمان بر اساسِ IP کلید می‌خوره تا چرخشِ حساب مهمان دورش نزنه
• IDOR در GET /api/home و GET /api/progress/nodes اصلاح شد: قبلاً بدون هیچ توکنی، با فرستادنِ userId دلخواه می‌شد آمار/پیشرفتِ هر کاربرِ دیگه‌ای رو خوند؛ حالا auth اجباریه و فقط خودِ کاربر یا والدِ تأییدشده‌اش (FamilyLink با status='accepted') اجازه‌ی دسترسی دارن
• دیتابیس Postgres به‌جای SQLite
• اتصال واقعی به سرویسِ پیامک برای ارسالِ OTP: دیگه استاب نیست؛ از طریق کاوه‌نگار (kavenegar.com) ارسال می‌شه (کلید از KAVENEGAR_API_KEY)، و هر شکست (شبکه/کلید/رد اپلیکیشنی) به‌جای موفقیتِ ساختگی، خطای صریح ۵۰۳ برمی‌گردونه
• بررسیِ دوره‌ای throttle rate ها با توجه به ترافیکِ واقعی