المعلم X (Muallim.X)

معلم افتراضي بالذكاء الاصطناعي، ناطق بالعربية، لطلاب المرحلة الثانوية في العراق (سادس إعدادي / ثالث متوسط). تطبيق ويب مستقل (وليس داخل بيئة محادثة مقيّدة) يفتح المعلم فيه الجلسة بنفسه، يتحقق من المفهوم السابق تشخيصيًا، ثم يشرح — بصوت، وبرسوم توضيحية يولّدها بنفسه عند الحاجة.

المكدس التقني

• Next.js 16 (App Router) + TypeScript + Tailwind CSS v4
• Prisma + Postgres (محليًا وفي الإنتاج بنفس الشكل — قاعدة مجانية من Neon تكفي للبداية). لا يوجد ملف SQLite: منصات مثل Vercel تُشغّل الكود على نظام ملفات للقراءة فقط، فملف قاعدة بيانات محلي يفقد كل بيانات الطلاب عند كل طلب/نشر جديد.
• NextAuth v5 (Credentials + JWT) لحسابات طلاب حقيقية — trustHost: true مفعّل لأن Vercel (وأغلب مزوّدي الاستضافة) يمرّرون Host صحيحًا
• Anthropic Messages API (بث حي + Tool Use لتحديث تقدّم الطالب) لعقل المعلم
• pdf-parse لاستخراج نص الكتب المرفوعة + pdfjs-dist (في المتصفح فقط) لعرض صورة صفحة الكتاب الفعلية
• Web Speech API (speechSynthesis) للتحويل النصي-الصوتي من جهة المتصفح، بلا تبعية خارجية أو تكلفة إضافية
• isomorphic-dompurify لتعقيم أي SVG يولّده المعلم قبل عرضه

البنية

prisma/schema.prisma       نماذج قاعدة البيانات
prisma/seed.ts              يزرع 3 مواد أولية: كيمياء، رياضيات، إنكليزي
src/auth.config.ts           إعداد NextAuth الآمن لبيئة Edge (بلا Prisma) — يستخدمه middleware فقط
src/auth.ts                  إعداد NextAuth الكامل (Credentials + bcrypt + Prisma) — يستخدمه كل شيء آخر
src/lib/teacher-prompt.ts    الشخصية والأسلوب التربوي الكامل للمعلم (بالعربية) + أداة تحديث التقدّم
src/app/api/chat/route.ts    المسار الرئيسي: يبني السياق (مادة + تقدّم + سجل حوار)، يبث رد المعلم، يحفظ التقدّم
src/hooks/use-teacher-voice.ts  قراءة صوتية تختار الصوت العربي/الإنكليزي تلقائيًا حسب النص
src/lib/sanitize-svg.ts      تعقيم صارم لأي رسم SVG يولّده المعلم قبل حقنه في الصفحة
src/components/chat-app.tsx  التطبيق الرئيسي: اختيار المادة، الحوار، ملء الشاشة، الصوت
src/app/admin/*              لوحة تحكم للمشرف: مواد جديدة، مصادر دائمة لكل مادة، قائمة الطلاب

لماذا هذا التصميم؟

• المعلم يبدأ هو دائمًا: عند فتح مادة، يرسل العميل طلبًا فارغًا ("kickoff") فيبني الخادم رسالة تعليمة نظام خفية تطلب من المعلم الترحيب والتحقق من المفهوم السابق — لا تُحفظ هذه التعليمة في سجل الحوار المعروض.
• الذاكرة طويلة الأمد بلا تحليل نص هش: بدل تضمين JSON داخل نص الرد (يتطلب parsing هش عبر البث)، يستخدم المعلم أداة Anthropic (update_progress) في نهاية كل رد، فيُفصل تمامًا عن النص المعروض/المنطوق للطالب.
• أول مستخدم = مشرف تلقائيًا: لا حاجة لتعديل قاعدة البيانات يدويًا لإنشاء أول حساب مشرف.
• مصدرا محتوى منفصلان لكل مادة: StudentMaterial (مكتبة كتب خاصة بالطالب لكل مادة، يختار أيها نشط عبر قائمة منسدلة) وMaterial (رفع المشرف، دائم ويظهر لكل الطلاب). عند عدم تفعيل أي كتاب طالب يُستخدم كتاب المشرف.
• علامات صفحات حقيقية داخل نص PDF المستخرَج: كل صفحة تُفصل بعلامة [صفحة N] أثناء الاستخراج (src/lib/extract-pdf-text.ts)، فيستطيع المعلم إخبار الطالب فعليًا "نحن الآن في صفحة 42" بدل تخمين، ويُعرض هذا كشارة 📍 ثابتة أعلى المحادثة.
• صورة حقيقية لصفحة الكتاب: يُحفظ ملف PDF الأصلي كاملًا (fileData) عند الرفع، ويُعرض عبر GET /api/materials/file. العرض والتحويل إلى صورة (canvas) يحدثان بالكامل في متصفح الطالب عبر pdfjs-dist — لا خادم يُترجم الصفحات — لأن محاولة سابقة لعمل هذا على الخادم اصطدمت بنفس مشكلة تحميل عامل (worker) pdfjs التي واجهناها مع استخراج النص. لوحة LessonVisualPanel تعرض تبويبين: صفحة الكتاب الحالية، وآخر رسم توضيحي (SVG) ولّده المعلم — وتتنقّل تلقائيًا لأحدثهما.
• مزامنة تلقائية لقاعدة البيانات بدل ملفات migration: prisma db push يشغَّل ضمن npm run build نفسه، فكل نشر جديد على Vercel يهيّئ قاعدة البيانات ويزرع المواد الأولية تلقائيًا — مناسب لمشروع بمشرف واحد (أنت) بلا حاجة لتشغيل أوامر يدويًا في كل مرة.

الإعداد محليًا (لمن يريد تعديل الكود)

cp .env.example .env
# املأ DATABASE_URL (رابط Postgres، مثلاً من neon.tech)
# املأ ANTHROPIC_API_KEY، وولّد AUTH_SECRET بالأمر: npx auth secret

npm install
npm run dev

npm run dev لا يُنشئ الجداول تلقائيًا في وضع التطوير — شغّل مرة واحدة: npx prisma db push && npm run db:seed. أما npm run build (المستخدم في النشر) فيقوم بهذا تلقائيًا في كل مرة.

افتح http://localhost:3000، أنشئ حسابًا (أول حساب يصبح مشرفًا تلقائيًا ويرى رابط "لوحة التحكم" في الأعلى).

النشر على الإنترنت (بدون أي خبرة برمجية) — Vercel

الكود جاهز للنشر مباشرة: عند البناء (npm run build) يقوم تلقائيًا بمزامنة جداول قاعدة البيانات وزرع المواد الأولية (prisma db push && seed) قبل بناء الموقع — لا حاجة لفتح أي طرفية (terminal).

1. أنشئ قاعدة بيانات Postgres مجانية على neon.tech وانسخ رابط الاتصال (Connection String).
2. أنشئ حسابًا على vercel.com (تسجيل دخول بحساب GitHub أسهل) واستورد هذا المستودع.
3. في خطوة Environment Variables أضف:
   • DATABASE_URL = رابط Neon من الخطوة 1
   • AUTH_SECRET = قيمة عشوائية طويلة (يمكن توليدها بالأمر openssl rand -base64 32 من أي طرفية، أو أطلب من المعلم/المساعد توليد واحدة)
   • ANTHROPIC_API_KEY = مفتاحك من console.anthropic.com
4. اضغط Deploy. خلال دقائق يصبح لديك رابط عام مثل your-project.vercel.app.
5. افتح الرابط وأنشئ أول حساب — يصبح تلقائيًا مشرفًا.

متغيرات البيئة

المتغير	الوصف
DATABASE_URL	رابط اتصال Postgres (نفسه محليًا وفي الإنتاج)
AUTH_SECRET	مفتاح توقيع الجلسات (npx auth secret أو openssl rand -base64 32)
ANTHROPIC_API_KEY	مطلوب لتشغيل المعلم فعليًا
ANTHROPIC_MODEL	افتراضيًا Haiku لتقليل التكلفة (~1-3$ لكل طالب نشط شهريًا)؛ بدّله بنموذج Sonnet لجودة أعلى وتكلفة أعلى

حدود معروفة في هذه النسخة (MVP)

• كل مسارات رفع الكتب ومحادثة المعلم تُصرّح صراحة بمدة تنفيذ أطول (export const maxDuration = 60) لتفادي حدّ الـ10 ثوانٍ الافتراضي لدوال Vercel المجانية أثناء استخراج نص كتاب كبير أو رد طويل من المعلم.
• استخراج نص PDF يعمل مضمّنًا في الطلب نفسه (لا رفع مباشر لتخزين خارجي)؛ منصات serverless معينة (كـ Vercel) قد تفرض حدًا على حجم جسم الطلب (~4.5MB على الخطة المجانية) بغضّ النظر عن MAX_PDF_BYTES في الكود — إن كان كتابك أكبر من ذلك، اضغطه بأداة مجانية لتصغير حجمه قبل الرفع. على خادم Node عادي (self-hosted) لا يوجد هذا القيد.
• نص المادة يُقتطع عند نحو 60 ألف حرف قبل إرساله للنموذج (أكبر بكثير من حد الـ18 ألف حرف في نموذج Artifacts الأولي، لكنه لا يزال اقتطاعًا لكتاب كامل ضخم جدًا). التحسين التالي الطبيعي هو تقسيم/فهرسة دلالية (RAG) بدل الاقتطاع البسيط.
• علامات الصفحات [صفحة N] مأخوذة من ترتيب صفحات ملف الـPDF كما استخرجه pdf-parse؛ إن كان الكتاب صورًا ممسوحة ضوئيًا بلا طبقة نص (OCR)، لن يُستخرج نص ولن تظهر علامات صفحات (لكن صورة الصفحة نفسها تبقى تعمل، لأنها لا تعتمد على النص).
• حفظ ملفات PDF كاملة في قاعدة البيانات يستهلك مساحة التخزين بسرعة أكبر بكثير من حفظ النص المستخرج وحده — قاعدة Neon المجانية عادة توفر مساحة محدودة (غالبًا أقل من 1GB). مناسب لعائلة واحدة بعدد كتب معقول، لكن مع نمو عدد الطلاب/الكتب قد تحتاج ترقية الخطة أو نقل الملفات الأصلية إلى تخزين ملفات مخصص (مثل S3/Vercel Blob) بدل قاعدة البيانات مباشرة.
• لا حدّ استخدام يومي لكل طالب بعد (مهم لضبط التكلفة عند الإطلاق الفعلي).

خارطة الطريق (غير مُنفَّذ بعد، مطابق لما ورد في وصف المشروع)

• نظام تكرار متباعد (Spaced Repetition) لمراجعة نقاط الضعف عبر الوقت بذكاء (البيانات الخام — weakPoints — موجودة بالفعل في Progress، تبقى بناء منطق الجدولة).
• لوحة متابعة لولي الأمر أو معلم بشري مشرف.
• توسعة مكتبة المواد لتشمل مراحل ومواد أكثر (الإضافة من لوحة التحكم تدعم هذا تقنيًا الآن، يبقى المحتوى نفسه).
• إدخال صوتي (STT) عبر SpeechRecognition في المتصفح — لم يكن يعمل في بيئة Artifacts المقيّدة سابقًا، ومن المتوقع أن يعمل بشكل طبيعي هنا كتطبيق مستقل؛ لم يُضف بعد لأنه لم يكن ضمن قائمة الميزات التي أثبتت نجاحها.
• حدود استخدام/تكلفة لكل طالب.