الباغ الذي كان يختبئ في طبقة الـ API

عَرض الطاولة حُمِّل. وCanvas رُسِم. والطاولة موجودة في قاعدة البيانات.

لكن عندما طلب الـ front-end من الخادم الحالة الحالية للطاولة — المقاعد، والـ stacks، ومن الذي يجلس أين — أعاد الخادم 404. لا شيء. لا مقاعد، ولا بيانات لعبة، ولا شيء يستطيع الـ renderer العمل به.

الـ canvas كان فارغاً لأنه لم يكن لديه شيء يرسمه.

إليك التفسير التقني، مُختصراً قدر الإمكان: الـ API gateway أمام الـ table engine يحذف بادئة من كل URL قبل تمرير الطلب. /api/v1/tables/... تصل إلى الـ table engine باسم /tables/.... مسارات الـ table engine، كما كتبتها جلسة البناء، سُجِّلت متوقِّعةً البادئة الكاملة — أي أن الخادم كان يستمع إلى /api/v1/tables/... لكنه كان يستقبل /tables/.... كل طلب كان يخطئ الهدف.

ليس خطأ منطقياً. وليس خوارزمية معطَّلة. جدول routing بعناوين خاطئة. النوع الذي لا يظهر إلا حين تختبر الـ stack بالكامل معاً.

كم استغرق إيجاده؟

من البداية إلى الإصلاح: أقل من ساعة.

هذا سريع. وما جعله سريعاً: منهجية التصحيح.

العمل مع agent ذكاء اصطناعي على هذا لا يعني السؤال "ما الخطأ؟" وانتظار الإجابة. يعني إعطاء الـ agent السياق الصحيح في وقت واحد — إعدادات الـ proxy التي تتعامل مع البادئة، وملفات تسجيل المسارات في الـ table engine، وسجلات الطلبات التي تُظهر 404 — وطلب تتبُّع التناقض.

عندما تكون هذه القطع مرئيةً معاً، يستطيع الـ agent مطابقة الأنماط عبر مساحة كان مهندس بشري سيحتاج عشرين دقيقة فقط للتنقُّل فيها. عثر الـ agent على عدم التطابق بين قاعدة rewrite الـ proxy وتسجيل المسار في الـ table engine في حوالي ثلاث دقائق.

الباغ خلف الباغ

العثور على باغ الـ routing كشف الباغ التالي.

الـ endpoint يستجيب الآن. لكن البيانات التي يعيدها كانت بتنسيق خاطئ.

الـ table engine يتكلَّم لغة واحدة داخلياً: أرقام مقاعد، ورموز حالة مثل occupied، وأعداد رقائق خام كأعداد صحيحة بسيطة. والـ front-end renderer يتكلَّم لغةً أخرى: فهارس مقاعد، وسلاسل عملة منسَّقة مثل $235.50، وأسماء حقول محدَّدة يتوقَّعها بموجب عقد من تعريف نوع كُتب اعتماداً عليه.

لم يكتب أحدٌ طبقة ترجمة. كتبت جلسة البناء الـ endpoint فأعاد التنسيق الداخلي. واستقبل الـ renderer بياناتٍ لم يتعرَّف عليها فأنتج بصمت لا شيء.

هذه فئة الباغات التي يصعب اشتقاق اختبار لها مقدَّماً. عليك أن تجعل كلا النظامين يعملان، ومتصلَين، ويحاولان التحدُّث مع بعضهما لكي ترى ذلك. لا يُغطِّي أيّ unit test الفجوة بين نظامين حين لا يحوي أيٌّ منهما باغاً بمفرده.

ماذا يعني هذا لمنهجية البناء

مرحلة الاختبار لا تعني أن المنهجية فشلت. تعني أن المنهجية أوصلتنا إلى الاختبار.

كل منصَّة برمجية فيها طبقة تكامل حيث يجب أن تلتقي القطع في العالم الحقيقي. التطوير spec-driven يصل بك إلى تلك الطبقة أسرع. لا يتخطَّاها.

المنشور التالي في هذه السلسلة يغطِّي ما حدث حين طبَّقنا الإصلاحات — وأظهر المتصفح النتيجة المعطَّلة نفسها رغم ذلك.

لمنهجية الهندسة وراء طريقة بنائنا — الـ spec، والجلسات، وما يفعله الـ agent خلال الجلسة وما يفعله المعماري — المقال الكامل على The Salty Korean.

Stay salty.