TypeScript لا يؤتي ثماره إلا عندما يكون صارما عند الأطراف ومملا في الوسط. ومعظم أخطاء الإنتاج التي نراها في SaaS ومتاجر السعودية ليست خوارزميات. بل await مفقود على مدفوعات وany متسرب من حمولات النظام وwebhooks غير متحقق منها وحقول عربية nullable مفترضة موجودة.
وهذه هي مجموعة القواعد التي نفرضها للحفاظ على هدوء النشر.
1. إعداد صارم يمسك أخطاء حقيقية
فعّل strict وnoUncheckedIndexedAccess وnoImplicitAny وexactOptionalPropertyTypes حيث أمكن. وامنع any عبر eslint. واشترط أنواع إرجاع صريحة للدوال المصدرة. وهذه الثلاثة تمسك التعطل الشهير order.items[0].price عندما تكون فارغة والذي يحدث مع طلبات عربية تجريبية بعينات مجانية.
وأضف منع الوعود العائمة. وawait مفقود على التقاط ميسر يسبب ازدواج دفع عندما ينقر المستخدم آبل باي مرتين. ويجب أن يفشل الفحص البناء لا يحذر.
وأبق tsconfig في الجذر مع مسارات @/lib. ولا تسمح ts-ignore بدون رابط تذكرة. وتتبع عدد التجاهل في CI وافشل إذا نما.
2. تحقق عند الأطراف بـ Zod
كل مدخل خارجي يحصل على مخطط Zod. وXML فاتورة محول JSON وwebhooks الدفع وwebhooks النظام وبيانات الرفع وحقول نماذج عربية مع جوالات. وحلل ولا تصب. واستخدم كائنات صارمة وحول الجوالات E.164 ووحد التواريخ بتوقيت الرياض.
ونمط المثال هو مخطط webhook مع paymentId نص ومبلغ موجب وعملة SAR وحالة enum. وعند الفشل سجل خطأ Zod مع المزود وIP وأعد 400 ونبه إذا قفزت الإخفاقات. وهذا يحول فساد البيانات الصامت إلى 400 مرئية تصلحها في الربط.
وولد أنواع API من مخطط الخلفية أو OpenAPI بدل كتابة مكررة. ولمحتوى النظام ولد أنواع مقالات مع ترجمات nullable للمقتطف. وهذا يزيل any من عرض المحتوى حيث يعيش منطق fallback العربي.
3. أنواع ضيقة للمحتوى ثنائي اللغة
نمذج اللغة union ar-SA مع en-US لا string. ونمذج حالة الترجمة complete أو missing-ar أو missing-en. والدوال التي تعرض يجب أن تقبل محتوى محلولا بعنوان مضمون لا صفوف nullable خام. واكتب دالة resolveLocale تأخذ اللغة والصفوف وتعيد محتوى مع fallback وعلم. وفحص شامل بـ never لضمان تحديث اللغات الجديدة.
وفضل const مع unions على enums للواجهات العامة. فـ enums تصدر JS يعقد edge. وconst أنحف لـ Next.js.
4. الأخطاء والنتائج ومسارات المال
المدفوعات والفوترة يجب أن تستخدم أنماط Result لا رمي لإخفاقات متوقعة. وأعد ok مع قيمة أو err مع كود مثل رصيد ناقص أو مرفوض زاتكا مع كود قاعدة. والمستدعي يقرر إعادة أو رسالة عربية. وارمِ فقط لأخطاء المبرمج.
وغلف مفاتيح منع التكرار لالتقاط ميسر وإعادة مقاصة زاتكا. ونفس المفتاح مع نفس الحمولة يعيد مخزنا. ومفتاح مع حمولة مختلفة خطأ ويجب تنبيه.
وسجل JSON مهيكل مع requestId وorderId وlang وكود مزود. ورسائل العربية في السجلات UTF-8 قابلة للبحث برقم الطلب. وهذا يخفض الدعم من ساعات لدقائق في الجمعة البيضاء.
5. اختبار الأنواع لا الكود فقط
أضف اختبارات نوع expectTypeOf لموصلات حرجة مثل بانئي UBL ومحللات webhook. وأضف اختبارات خاصية لتقريب ضريبة بمبالغ ريال عشوائية لتمسك عدم تطابق نصف لأعلى الذي ترفضه زاتكا.
وراجع فروقات تحت 400 سطر واشترط خطوات إعادة إنتاج لإصلاحات الأنواع. وأبق ADR حيا لماذا كل علم صارم مع روابط حوادث. فيحترم الموظفون القواعد بدل تعطيلها.
والخلاصة صرامة مع أطراف متحقق منها وأنواع ثنائية صريحة. وهذه القواعد الصغيرة تمنع 80 بالمئة من حوادث الدفع وwebhook وRTL في الإنتاج.
