Zareian
a4e0c576bb
- CLAUDE.md: 1,225 → ~430 lines, current state only (the dated status log stays in git history). Server rules moved to the top: what is ours on 249/247 and what is not, non-negotiable rules, announce-before-acting, password handling, and the full "deploy it" procedure with verification. - README: formal entry page with current numbers (10 grades, 18,522 questions, 61 API operations, 973 tests, PostgreSQL/Redis). - Removed docs/frontend/ (Figma-era guide with guest login and its own api.ts; the frontend repo has the real client). Swagger's external-docs link now points at the frontend repo. - architecture/operations/security/content-authoring/loadtest/textbooks: SQLite, guest login, demo accounts, question packs and the port-80 note replaced by what is true now. - Technical handbook text updated throughout; all seven diagrams redrawn (PostgreSQL, phone-only login, subscriptions, current data model); PDF rebuilt. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
کتاب‌های درسی (PDF)
فایل‌های PDF کتاب‌های درسی را در همین پوشه بگذارید. خودِ PDFها در گیت ذخیره نمی‌شوند (حجمشان زیاد است) — فقط همین فایل راهنما ردیابی می‌شود.
منبع
نسخه‌ی رسمی و به‌روزِ کتاب‌ها: https://irtextbook.ir (از خارج ایران در دسترس نیست؛ دانلود باید از داخل ایران انجام شود.)
کتاب‌های ثبت‌شده
فهرستِ کامل در rag/services/textbooks.py است؛ همه روی Qdrantاند، هر کتاب در collectionِ خودش.
| کتاب | خوانده‌شده با |
|---|---|
| ریاضیِ سوم، ششم، هفتم | تیمِ دیگرِ شرکت (پیش از قاعده‌ی «شکل را در متن بنویس»؛ بیشترِ مسئله‌های وابسته به شکل این‌جاست) |
| ریاضیِ چهارم، پنجم، هشتم، نهم، دهم | ما، با gpt-4.1-mini |
| حسابانِ یازدهم و دوازدهم | ما |
| هندسه‌ی دهم، یازدهم، دوازدهم · آمار و احتمالِ یازدهم · گسسته‌ی دوازدهم | ما |
اولِ و دومِ دبستان PDF دارند ولی ثبت نشده‌اند.
⚠️ کتابِ ریاضیِ یازدهم و دوازدهم چند رشته دارد (تجربی، ریاضی‌فیزیک، انسانی).
نامِ فایل و Textbook.grade باید رشته را مشخص کند، وگرنه دو کتابِ متفاوت
سرِ یک collection دعوا می‌کنند.
نام‌گذاری
نامِ فایل باید دقیقاً با filename در rag/services/textbooks.py یکی باشد،
مثلاً ریاضی نهم.pdf.
چطور ingest کنیم
# اول ببینید چه چیزی قرار است پردازش شود (رایگان، هیچ فراخوانیِ مدلی ندارد)
python manage.py rag_ingest_book --grade نهم --plan
# یک فصل، با سقفِ صفحه برای کنترلِ هزینه
python manage.py rag_ingest_book --grade نهم --chapters 1 --max-pages 5
# کلِ کتاب (از جایی که مانده ادامه می‌دهد)
python manage.py rag_ingest_book --grade نهم
هر اجرا صفحه‌هایی را که قبلاً chunk ساخته‌اند رد می‌کند، پس قطع کردنش با Ctrl-C بی‌خطر است و اجرای دوباره هزینه‌ی رفته را دوباره نمی‌پردازد.
بازخوانیِ صفحه‌های معیوب
کتاب‌هایی که پیش از افزوده شدنِ قاعده‌ی «self-contained» به پرامپت ingest شده‌اند، مسئله‌هایی دارند که به «شکلِ زیر» یا «جدولِ روبه‌رو» ارجاع می‌دهند بی‌آنکه محتوای آن شکل در متن آمده باشد. مدل آن شکل را دیده بود؛ فقط از او خواسته نشده بود بنویسدش. پس با خواندنِ دوباره‌ی همان صفحه‌ها جبران می‌شود.
# اول ببینید چند صفحه و چه هزینه‌ای — رایگان، هیچ فراخوانیِ مدلی ندارد
python manage.py rag_ingest_book --grade نهم --refresh both --plan
# فقط صفحه‌های ارجاع‌دهنده به شکل/جدول
python manage.py rag_ingest_book --grade نهم --refresh figures
# صفحه‌های مشخص (وقتی خودتان فهرست دارید)
python manage.py rag_ingest_book --grade نهم --refresh-pages 18,44,60-65
سه نکته که باید بدانید:
- بازخوانی پاک می‌کند. واحدِ کار «صفحه» است نه chunk، چون vision یک صفحه را
یک‌جا می‌خواند. پس chunkهای سالمِ همان صفحه هم دور ریخته و از نو ساخته
می‌شوند و
solution_verdictشان پاک می‌شود. فرمان پیش از خرج کردن نشان می‌دهد چند تای آن‌ها رأیِ «agrees» داشته‌اند و تأیید می‌گیرد (--yesرد می‌کند). - بعدش
rag_verify_solutionsرا دوباره اجرا کنید، وگرنه chunkهای تازه بی‌رأی می‌مانند و تولیدِ سؤال — که فقطagreesمی‌خواند — نادیده‌شان می‌گیرد. - پاک‌سازی صفحه‌به‌صفحه است، درست پیش از خواندنِ همان صفحه. پس قطعِ وسطِ کار (Ctrl-C، تمام شدنِ اعتبار) فقط یک صفحه را خالی می‌گذارد، نه کلِ کتاب را.
افزودنِ کتابِ جدید
در rag/services/textbooks.py یک Textbook بسازید با:
page_offset— اختلافِ شماره‌ی صفحه‌ی چاپ‌شده با شماره‌ی صفحه در PDF (جلد و فهرست جلوترند). از روی فهرستِ کتاب و بازبینیِ یک صفحه‌ی مرزی درمی‌آید.chapters— بازه‌ی صفحه‌ی هر فصل بر اساسِ شماره‌ی چاپ‌شده. بازه‌ها باید پشتِ‌هم و بدونِ حفره باشند (تستِTextbookLayoutTestsهمین را چک می‌کند).grade_label— همان رشته‌ای که در payloadِgradeمی‌نشیند.
عنوانِ فصل‌ها خودکار در known_collections.MATH_CHAPTERS ثبت می‌شود، پس
جستجو بلافاصله می‌تواند شماره‌ی فصل را به رشته‌ی دقیق تبدیل کند.
بعدش چه اتفاقی می‌افتد
هر صفحه به تصویر تبدیل می‌شود، مدل vision انواع مسئله را استخراج می‌کند
(type / keywords / generalSolution / problem / solution)، نتیجه هم در
جدول rag.LessonChunk (منبع حقیقت، پیش خودمان) ذخیره می‌شود و هم به‌صورت
نقطه در Qdrant ایندکس می‌شود — با همان قرارداد payloadی که تیم دیگر دارد.