الإقليم 09منهجٌ يُدرَس وحدك

الإقليم ٩ — التدفّق الكامل: بايتةٌ من النقرة إلى الصفّ ورجوعاً

يبني فوق: كلَّ إقليمٍ سبق. النوعُ: سنثيسس — لا لبنةٌ جديدة، بل وصلُ كلِّ اللبنات في صورةٍ واحدة. يفتح: الكابستون (١٠) — الـ endpoint الوحيد المختلف.

النبذة

هذه هي الصورةُ التي طلبتَها من أول يوم: "أعرف كيف تتدفّق البيانات بوضوح." بنينا كلَّ صندوقٍ على حدة — HTTP، Node، Express، SQL، Prisma، Zod، الهويّة، React. الآن نوصّلها ونتتبّع بايتةً واحدةً في رحلتها الكاملة: من نقرةِ المتدرّب حتى صفٍّ في Postgres ورجوعاً إلى شاشةٍ تتحدّث. لا شيءَ جديدٌ هنا — وهذا هو المقصود. كلُّ نقطةٍ بدت متفرّقةً تتجمّع الآن في "آها" واحدة. وفي النهاية تملك أداةً عمليّةً أقوى من أي لبنة: تشخيصُ أي عطلٍ بمعرفةِ أي طبقةٍ هو فيها.

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

قبل أن نتتبّع، توقّع. لطلبِ تسجيلٍ واحد (POST /api/v1/auth/register)، اكتب بقلمك:

كم حدّاً (boundary) تعبره البياناتُ من النقرة إلى الصفّ؟ وعند كلٍّ، ما شكلُها (كائنُ JS؟ نصُّ JSON؟ بايتاتُ TCP؟ صفٌّ؟) وهل هي مكتوبةُ النوع أم لا؟
أين بالضبط يقف كلٌّ من الحرّاس الثلاثة (مترجم TS / Zod / قيودُ القاعدة) في المسار؟
لو خزّن الخادمُ كلمةَ المرور، أين تماماً تُجزّأ، وعلى أي خيط؟
الردُّ يعود 201 بمستخدمٍ بلا حقل password — أين حُذف، ولماذا؟

إن ترددتَ في أيٍّ، فالصورةُ لم تكتمل بعد. تتبّعها معي الآن، وستكتمل.

المسارُ الكامل (الكتابة): `POST /auth/register`

لنتتبّع كلمةَ المرور "hunter2" في رحلتها. كلُّ خطوةٍ موسومةٌ بإقليمها.

المتصفّح (React) 1. [٨] المستخدمُ يكتب → onChange → setForm({password:"hunter2"}) (حالةٌ، كائنُ JS مكتوبُ النوع) 2. [٨] ضغطُ "تسجيل" → submit() → fetch(POST, body: JSON.stringify(form)) 3. [٠] الجسمُ يصير نصَّ JSON: {"password":"hunter2",...} (النوعُ مُحي — مجرّد نصّ) 4. [٠] رسالةُ HTTP تُبنى: سطرُ طلبٍ + Content-Type: application/json + Content-Length + جسم │ ▼ عبر الشبكة 5. [الشبكات] DNS→TCP؛ البايتاتُ تسري في قناةٍ موثوقة، مؤطَّرةً بـ Content-Length [٠] 6. [٣] أصلٌ مختلف (:5173→:3000) → قد يسبق طلبُ CORS تمهيديّ (OPTIONS) │ ▼ وصولُ الخادم 7. [٢] حلقةُ libuv (epoll) تقبل على socket الاستماع، تقرأ الـ stream قطعاً 8. [٣] سلسلةُ Express، بالترتيب — كلٌّ دالّةٌ (req,res,next): helmet → cors(يسمح للأصل) → express.json()(يجمّع الـ stream → req.body كائنٌ، لكن any!) → rate-limit → router يطابق POST /auth/register 9. [٦] validate(Zod): req.body المجهول (unknown) → فحصٌ وقتَ التشغيل → إمّا 400 + fieldErrors (يعود فوراً) أو data **موثوقةٌ مكتوبةُ النوع** 10. [٣] المتحكّم (قشرةُ HTTP): يقرأ data، ينادي الخدمة 11. [٧/٢] الخدمة: await bcrypt.hash("hunter2", 10) — على **مجمّع خيوط libuv**، والـ await يتنازل للحلقة فتخدم غيره؛ النتيجة: "$2b$10$..." (بصمةٌ مملَّحة) 12. [٥] prisma.user.create({data:{...,password: hash}}) → SQL مُعامَل: INSERT INTO users (...) VALUES ($1,$2,...) RETURNING ... │ ▼ 13. [٤] Postgres: يفرض القيود — username/email **UNIQUE** (الحارسُ الأخير)، NOT NULL، enum للدور — يكتب الصفَّ (ذرّياً)، يرجّعه │ ▲ الرجوع 14. [٥] Prisma يحوّل الصفَّ → كائنُ User **مكتوبُ النوع**؛ select حذف password [٥] 15. [٣] المتحكّم يبني المظروف {success:true, data: user} — **بلا password** [٠/٥] 16. [٢/٠] res.status(201).json(...) → Node يكتب بايتاتِ الردّ: سطرُ حالةٍ 201 + Content-Type + Content-Length + جسم → عبر TCP │ ▼ عودةٌ للمتصفّح 17. [٨] وعدُ fetch يُحَلّ → r.json() → env.data → setUser(...) (تغيُّرُ حالة) 18. [٨] إعادةُ رسمٍ → تصالحٌ (Virtual DOM) → تحديثُ DOM الأدنى → الشاشةُ تعرض النجاح

ثماني عشرة خطوة، تسعةُ أقاليم، حدودٌ كثيرة — وكلٌّ بنيتَه بيدك. هذا "تدفّقُ البيانات بوضوح".

رحلةُ النوع (خيطُ الـ erasure، مرئياً)

تتبّع النوعَ وحده عبر المسار، فترى لماذا احتجنا كلَّ حارس:

TS مكتوبُ النوع (مصدر) → [يُمحى] → نصُّ JSON (بلا نوع) → بايتاتُ TCP → req.body: any/unknown → [Zod يعيد النوع وقتَ التشغيل] → data موثوقةٌ مكتوبةُ النوع → SQL params → صفٌّ → [Prisma يعيد النوع من السكيمة] → User مكتوبُ النوع → مظروف → بايتات → any في المتصفّح → [اختيارياً: تحقّقٌ في العميل] → مكتوبٌ ثانيةً

النوعُ يُولَد ويُمحى مرّاتٍ عبر الحدود. الحرّاسُ الثلاثة هم نقاطُ إعادةِ التوليد: المترجمُ يحرس المصدر (ثم يُمحى)؛ Zod يعيده عند حدّ الشبكة (٦)؛ Prisma يعيده عند حدّ القاعدة (٥)؛ وقيودُ Postgres تحرس الصحّةَ الحتميّةَ في القاع (٤). لا طبقةَ تكفي وحدها — كلٌّ تحرس زمناً ومجالاً مختلفاً. الآن ترى لماذا.

المسارُ الكامل (القراءة): `GET /me` — انعدامُ الحالة حياً

[٨] fetch(GET /me, headers:{Authorization: Bearer <jwt>}) ← العميلُ يحمل الإثبات [٢] الحلقةُ تقبل وتقرأ [٣] السلسلة: helmet → cors → authenticate [٧] authenticate: يفكّ Bearer، verifyJWT(token, SECRET) — يعيد حسابَ HMAC ويقارن. **لا بحثٌ في جلسةٍ، لا تخزين** — الخادمُ عديمُ الحالة. صالحٌ؟ req.user={sub,role}. وإلّا 401 [٥] (اختياري) prisma.user.findUnique({where:{id: req.user.sub}}) [٣/٠] المظروف {success, data: user} → 200 → بايتات [٨] setState → إعادةُ رسم

تأمّل الجوهر: الخادمُ عرفَ من المُرسِل دون أن يحفظ عنه شيئاً — الإثباتُ محمولٌ وموقَّع (٧)، فبقي عديمَ الحالة (٠)، فيتوسّع أفقياً (بنية الويب). الصورةُ المعماريّةُ الكبرى التي رسمها منهجُ البنية كصناديقَ سوداء، امتلأت الآن بالآليّات:

ملاحظة

أين تعيش الحالةُ وأين لا تعيش: الخادمُ (Node/Express) عديمُ الحالة — أيُّ نسخةٍ تخدم أيَّ طلب. الحالةُ كلُّها في Postgres (٤). والهويّةُ يحملها العميلُ في الـ JWT (٧). هذا الثالوثُ هو لماذا يتوسّع النظامُ أفقياً بلا التصاقٍ بنسخة — وعدُ منهجِ البنية، محقَّقاً بآليّاتٍ بنيتَها.

اللغز / التمرين: شخّص بالنموذج الذهنيّ

لا بناءَ جديدٌ هنا — تمرينٌ يحوّل فهمَك إلى مهارةِ إدارةٍ عمليّة: تشخيصُ العطل بمعرفةِ طبقته. لكل عَرَضٍ، حدّد الطبقةَ بالضبط والسبب الجذريّ، مستنداً لرحلة التدفّق — قبل أن تشغّل أي شيء. ثم افتعِل كلَّ عطلٍ وتحقّق:

أ — تشخيصٌ نظريّ (اكتب الطبقة + الجذر لكلٍّ):

الواجهةُ تُظهر "CORS error" والطلبُ لم يصل المتحكّم. أي طبقة؟ أيُّ middleware غائبٌ أو خاطئ؟ (٣)
كلُّ طلبٍ يردّ 401 رغم أنك سجّلتَ الدخول. أين الخلل المحتمل؟ (٧ — الرمز لا يُرسَل؟ السرُّ مختلفٌ بين الإصدار والتحقّق؟ منتهٍ؟)
التسجيلُ يردّ 400 مع details.password. أيُّ حارسٍ نطق، ولماذا ليس المترجم؟ (٦ + خيطُ الـ erasure)
التسجيلُ المكرّرُ السريعُ ينشئ مستخدماً واحداً فقط ويرفض الثاني بخطأٍ من القاعدة. أيُّ حارسٍ أنقذك، ولماذا لم يكفِ فحصُ التطبيق؟ (٤ + idempotency من ٠)
طلبٌ واحدٌ بطيءٌ يجمّد كلَّ الطلبات الأخرى. أي طبقة؟ ما القاعدةُ المنتهَكة؟ (٢ — عملٌ محسوبٌ على خيط الحلقة)
الردُّ يصل لكنه يتجمّد ناقصاً في المتصفّح. أي طبقة؟ (٠ — Content-Length كاذب / تأطيرٌ مكسور)
صفحةُ المناهج تعرض قائمةً قديمةً بعد إضافةِ منهج. أي طبقة؟ (٨ — الحالةُ لم تتحدّث / تبعيّةُ useEffect)

ب — افتعِل وتحقّق. لكلِّ عَرَضٍ أعلاه، اصنعه عمداً في مشروعِ تجربةٍ (احذف cors، غيّر JWT_SECRET بين الإصدار والتحقّق، أرسل كلمةً قصيرة، اكتب Content-Length خاطئاً يدوياً عبر nc، ضع حلقةَ حسابٍ في معالِج...)، وراقِب العَرَضَ يظهر كما تنبّأت. التطابقُ بين تنبّؤك والواقع هو الدليلُ أن النموذجَ في رأسك صحيح — وهذه هي القدرةُ التي طلبتَها: تدير المشروعَ لأنك تعرف أين كلُّ شيء ولماذا.

ج — ارسمها لنفسك. أعِد رسمَ مخطّطِ التدفّق الكامل (الكتابة والقراءة) من ذاكرتك على ورقةٍ بيضاء، واسِماً كلَّ حدٍّ وكلَّ حارسٍ وكلَّ تحوّلِ شكلٍ للبيانات. إن استطعتَ رسمَه بلا النظر، فالصورةُ اكتملت فيك.

ملاحظة

هذا الإقليمُ بلا "حلٍّ مخفيّ" — هو خريطتُك أنت. أتقِنه يعني أنك تستطيع وضعَ إصبعك على أي عطلٍ في الستاك دون تخمين. هذا جوهرُ "إدارةِ المشروع".

الخلاصة — الشجرةُ تكتمل

الالتحام: الشجرتان اللتان نبتتا متوازيتين — الستاكُ من جهة، ومعرفتُك السابقة (الشبكات/Docker/C/أنواع TS) من جهة — التحمتا في مسارٍ واحدٍ متّصل. كلُّ إقليمٍ صار حلقةً مرئيّةً في رحلةِ بايتة.
العقدة الجديدة (وهي الكلّ): تدفّقُ البيانات كنظامٍ واحدٍ متّصل — لا صناديقَ منفصلة، بل خطٌّ تتبعه بإصبعك من النقرة إلى الصفّ ورجوعاً، وتعرف عند كل نقطةٍ: الشكلَ، النوعَ، الحارسَ، والخيط.
الباقي: كلُّ endpoints مشروعك تتبع هذا المسار إلا واحداً. واحدٌ لا يكتفي بقراءة/كتابة القاعدة — بل يشغّل كودَ C غريباً أرسله المتدرّب، بأمان، ويصحّحه. الصندوقُ الأخير.

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

افتح مشروعك الآن واتبع POST /auth/register بإصبعك عبر الملفّات الفعليّة، وستمرّ بكل خطوات المخطّط: frontend (fetch) → الشبكة → app.ts (السلسلة) → user.routes.ts (التوجيه) → user.schema.ts + safeParse (Zod) → user.controller.ts (المتحكّم) → bcrypt.hash → prisma.user.create → schema.prisma/القيود → Postgres → ورجوعاً بمظروفٍ بلا password. لم يبقَ سطرٌ واحدٌ في مسار التسجيل غامضاً عليك. وما ينقص مشروعَك (login، /me، البادئة /api/v1، helmet/cors/rate-limit، معالِجُ الأخطاء، الخدمة، بقيّةُ الكيانات، الواجهة) — تعرف أين يقع كلٌّ في هذا المسار، وكيف تبنيه.

بذرة الإقليم التالي

البذرة الأخيرة: كلُّ ما تتبّعناه كان بياناتٍ تُكتَب وتُقرَأ. لكن POST /tasks/:taskId/check مختلف: يأخذ كودَ C من متدرّبٍ — كودٌ غريبٌ قد يكون خبيثاً أو لا نهائياً — ويجب أن يصرّفه ويشغّله ضد حالاتِ اختبارٍ ويصحّحه ويسجّل النتيجة، بأمانٍ تامّ، دون أن يجمّد الخادمَ أو يخترقه. هنا يلتقي كلُّ الستاك الذي تعلّمته بـ أقوى مهارتيك: C و Docker. ننزل للإقليم ١٠، الكابستون — حيث تكتشف أن المنصّةَ كلَّها وُجدت لتُنسّق شيئاً... كنتَ تعرفه من البداية.

الستاك الكامل · من باب الخادم إلى داخله ليش قبل كيف · صُمّم لـ يزيد