الإقليم ٥ — Prisma: ORM، وإعادةُ النوع الذي محته اللغة

النبذة

في الإقليم ٤ صرتَ تكتب SQL بيدك وتفهم ما تحته. الآن نضع فوقه طبقةً — لكن انتبه: ليست بديلاً عن فهمك، بل راحةً فوقه. Prisma ستحلّ ثلاث مشكلاتٍ حقيقيةٍ في وصل خادمٍ مكتوبِ-النوع بقاعدةٍ علائقيّة، وأهمُّها لغزٌ تركناه مفتوحاً منذ الإقليم ١: إن كانت الأنواع تُمحى وقت التشغيل، فمن أين أتى newUser بنوعٍ كاملٍ يعرف حقولَه؟ الجواب هنا، وهو أنيقٌ ويختم دائرةً فكرية.

اللغز المستفزّ

ts
const q = `INSERT INTO users (username, email, password_hash)
           VALUES ('${username}', '${email}', '${hash}') RETURNING *`;
const rows = await db.query(q);
const user = rows[0];     // ما نوعُ user؟

ليش: ما الـ ORM، ولماذا (وحدوده)

الجوابُ صنفُ أدواتٍ اسمه ORM (Object-Relational Mapper): يجسر العالمين — كائناتُ برنامجك ⇄ علاقاتُ قاعدتك. تكتب بلغة الكائنات، وهو يولّد SQL المعامَل (parameterized) ويحوّل الصفوفَ العائدةَ إلى كائنات.

ليش يفيد: يقتل الحقنَ (لا يلصق قيمَك في النصّ — يمرّرها كمعامِلاتٍ منفصلة)، ويختصر الترجمةَ المتكرّرة، ويعطي نوعاً للنتائج. وليش احذر: ORM يخفي SQL، فقد يولّد استعلاماتٍ غبيّةً (مشكلةُ N+1 أدناه) إن لم تفهم ما تحته. لهذا رتّبنا المنهج هكذا عمداً: تعلّمتَ SQL أولاً (٤)، فالـ ORM الآن راحةٌ تتحكّم فيها، لا ستارٌ يعميك. القاعدةُ الذهبية لإدارة المشروع: اعرف دائماً أيَّ SQL يولّده استدعاؤك — وستفعل ذلك حرفياً في اللغز (Prisma يطبع لك SQL).

ليش: Prisma ليس ORM تقليدياً — هو "schema-first" بمولّد

أغلبُ ORMs تعرّف النموذجَ بكلاسات/ديكوريترز في الكود. Prisma يقلب الترتيب: ملفُّ سكيمةٍ واحدٌ (schema.prisma) هو مصدرُ الحقيقة الوحيد، ومنه:

خطّان ينطلقان من السكيمة نفسها التي صمّمتَها في الإقليم ٤. نفكّكهما.

الخطّ الأول: migrate — تطوّرُ بنية القاعدة

sh
prisma migrate dev --name add_curriculum

ماذا يفعل؟ يقرأ schema.prisma، يقارنه بحالة القاعدة، يولّد ملفَّ SQL migration يسدّ الفرق (CREATE TABLE, ALTER TABLE ADD COLUMN, CREATE TYPE ... ENUM...) — نفسُ DDL الذي كتبتَه بيدك في الإقليم ٤ — ثم يطبّقه ويسجّله. تاريخُ مشروعك يريك هذا حيّاً: migration الأولى أنشأت users، والثانية حوّلت role من نصٍّ إلى enum وأضافت user_name فريداً (تذكّر تحذيرَها عن فقدِ البيانات — تطوّرُ السكيمة قرارٌ له ثمن).

prisma migrate deploy (لا dev) يطبّق الـ migrations المعلّقة فقط، مُحايِدٌ للتكرار (idempotent) وآمنٌ في كل إقلاع — لهذا وضعه Dockerfile مشروعك في CMD: npx prisma migrate deploy && npx tsx src/server.ts. كلُّ إقلاعٍ يضمن أن بنية القاعدة محدَّثة، بلا ضرر.

الخطّ الثاني: generate — وهنا يُعاد النوعُ الذي مُحي (ختمُ لغز الإقليم ١)

sh
prisma generate

يقرأ السكيمة (التي تصف شكلَ بياناتك وقت التشغيل في القاعدة)، ويولّد كوداً: عميلٌ مكتوبُ-النوع + تعريفاتُ TypeScript لكل نموذج. الآن:

ts
const newUser = await prisma.user.create({ data: { ... } });
//    ^? النوع: User { id: string; username: string; email: string; role: Role; ... }

من أين أتى نوعُ newUser الكامل، والأنواعُ تُمحى وقت التشغيل؟ من خطوةِ توليدِ كودٍ قرأت السكيمة وكتبت الأنواعَ بنفسها. الـ erasure يقول "لا معلوماتِ نوعٍ تنشأ وقت التشغيل"؛ Prisma لا يخالفه — بل ينقل المعلومةَ إلى زمنٍ أبكر: السكيمةُ المكتوبةُ سلفاً تُترجَم إلى أنواعِ TS مكتوبةٍ سلفاً، فيحرسك المترجمُ وقتَ الكتابة، ثم تُمحى كالعادة وقت التشغيل. توليدُ الكود هو الجسر فوق هاوية الـ erasure.

في مشروعك: السكيمة تقول output = "../src/generated/prisma"، وprisma.ts يستورد منها PrismaClient. والعميلُ المولَّد مُتجاهَلٌ في git (لأنه مُشتقّ)، لهذا Dockerfile يشغّل prisma generate داخل الصورة. كلُّ سطرٍ صار مفهوماً.

كيف: لغةُ استعلام Prisma (وكلٌّ يقابل SQL تعرفه)

كلُّ استدعاءٍ هنا يولّد SQL من الإقليم ٤ — اربطهما دائماً:

ts
// SELECT ... WHERE id = ... LIMIT 1  (على عمودٍ فريد)
const u = await prisma.user.findUnique({ where: { email } });

// SELECT id, username, role FROM users WHERE role = 'ADMIN' ORDER BY created_at DESC
const admins = await prisma.user.findMany({
  where: { role: "ADMIN" },
  select: { id: true, username: true, role: true },   // = الإسقاط (projection)
  orderBy: { createdAt: "desc" },
});

// INSERT ... RETURNING (مع select لتقييد ما يعود — مشروعك يفعلها ليُخفي كلمةَ المرور)
const created = await prisma.user.create({
  data: { firstName, lastName, username, email, password: hash, role },
  select: { id: true, username: true, email: true, role: true, createdAt: true },
});

// UPDATE / DELETE
await prisma.user.update({ where: { id }, data: { role: "ADMIN" } });
await prisma.user.delete({ where: { id } });

include = JOIN، وselect = الإسقاط

العلاقاتُ التي بنيتَها بمفاتيحَ أجنبيةٍ في الإقليم ٤، يعبرها Prisma بـ include:

ts
// = JOIN: منهجٌ مع كل سبرنتاته (الواحد-لكثير)
const c = await prisma.curriculum.findUnique({
  where: { id },
  include: { sprints: true },          // يضمّ الجدول المرتبط
});
// c.sprints موجودةٌ ومكتوبةُ النوع — الضمُّ الذي كتبته يدوياً، بنوعٍ كامل

المعاملات — ACID للتصحيح (الإقليم ١٠)

$transaction يلفّ عدّةَ عملياتٍ في معاملةٍ ذرّيّة (تذكّر BEGIN/COMMIT/ROLLBACK):

ts
await prisma.$transaction(async (tx) => {
  await tx.submission.create({ data: { ... } });
  await tx.taskProgress.update({ where: { ... }, data: { score: 80, status: "passed" } });
});   // إمّا الاثنان يثبتان، أو يُلغى الكلُّ عند أي خطأ — الذرّيّةُ التي أثبتّها بـ SQL

هذا حرفياً كيف يكتب نظامُ التصحيح نتيجتَه: نتيجةٌ + تحديثُ تقدّمٍ، ذرّياً.

الأمان من الحقن — مجّاناً

كلُّ قيمةٍ تمرّرها (where: { email }) تذهب معامِلاً منفصلاً، لا تُلصق في نصّ الـ SQL. فمحاولةُ الحقن '); DROP TABLE... تُعامَل كقيمةِ بريدٍ حرفيّةٍ لا ككود. (للحالات النادرة التي تحتاج SQL خاماً، $queryRaw بقوالبَ مُعامَلةٍ آمنة — لا تلصق أبداً.)

كيف: فخّ N+1 — لماذا فهمُك لـ SQL يبقى ضرورياً

الـ ORM يخفي SQL، فيسهل أن تكتب حلقةً تطلق استعلاماً لكل عنصر:

ts
const curricula = await prisma.curriculum.findMany();        // استعلامٌ ١
for (const c of curricula) {
  c.sprints = await prisma.sprint.findMany({ where: { curriculumId: c.id } }); // N استعلام!
}
// المجموع: 1 + N استعلام — كارثةُ أداءٍ مع كثرة المناهج

العلاج: استعلامٌ واحدٌ بـ include (ضمٌّ واحد) بدل N. هذا بالضبط لماذا لا يكفي حفظُ الـ ORM: لو لم تفهم أنه يولّد استعلامات، لما رأيتَ الـ N+1 ولا أصلحتَه. فهمُ الإقليم ٤ هو ما يجعلك تقرأ ما يولّده Prisma بعينٍ ناقدة (والفهارسُ التي تعلّمتَها تسرّع هذه الضمّات).

اللغز / البناء من الصفر

الخلاصة — أين تتّصل هذه العقدة بالشجرة

الوصلة للواقع (نمط SelfLab)

في user.controller.ts يصير كلُّ سطرٍ شفّافاً:

ts
import { prisma } from "../../database/prisma";
const newUser = await prisma.user.create({
  data: { firstName, lastName, username, email, password: await bcrypt.hash(password, 10), role },
  select: { id: true, firstName: true, username: true, email: true, role: true, createdAt: true },
});
return res.status(201).json(newUser);

prisma.user.create = INSERT ... RETURNING؛ وselect = إسقاطٌ يحذف password عمداً من الردّ (لا تُسرَّب التجزئةُ أبداً — درسٌ أمنيّ)؛ وnewUser مكتوبُ النوع من العميل المولَّد؛ وawait لا يحجب خيطَ الحلقة (٢). وفي prisma.ts: new PrismaClient() يقرأ DATABASE_URL من process.env (٢) عبر prisma.config.ts. كلُّ القطع التقت.

ولاحظ ما تملكه الآن: نقلُ منطق Prisma هذا من المتحكّم إلى user.service.ts (فصلُ الطبقات، ٣)، وبناءُ بقيّة النماذج (curriculum → ... → testCase، enrollment، taskProgress) في السكيمة كما صمّمتها.