أرصدة العملاء صحيحة. المخزون صحيح. درج النقد صحيح. وحده ميزان المراجعة كان يعرف: لا مبيعات فيه على الإطلاق، بينما تُرحَّل كل فاتورة شراء فورًا. على الورق، منشأة تشتري ولا تبيع.

FinyX-ERP نظام عربي للمحاسبة ونقاط البيع أصمّمه وأبنيه وأبيعه وحدي. في هذا المقال الآلية التي تُبقيه صحيحًا دون فريق، والسبب الدقيق الذي جعل 372 اختبارًا ناجحًا تعجز عن رؤية ذلك العيب. وحين تنتهي منه ستكون معك بوابة حفظ تنقلها إلى أي تطبيق EF Core، وسجل تدقيق يكتشف التعديل الذي يجري على ملف القاعدة مباشرة، وقائمة فحص للعيوب التي لا تراها اختباراتك بحكم تصميمها.

القاعدة التي تعيش في شاشة تنساها الشاشة التالية

بدأ FinyX برنامجًا محاسبيًا لويندوز. واليوم يضم المستودع نفسه كاشيرًا وبرنامج إدارة بـ WPF، وخادم ASP.NET Core لكل مطعم، ومتجر ويب بـ Next.js، وثلاثة تطبيقات جوال من كود Expo واحد. ولا يستطيع شخص واحد أن يتذكر كل قاعدة في كل هذه الأماكن، لذلك يجب ألا يعتمد التصميم على تذكّر أحد.

تطبيق سطح المكتب وخادم المطعم يترجمان ملفات المصدر نفسها في Domain وApplication وInfrastructure. وكل خدمة أعمال تُسجَّل في دالة واحدة هي AddFinyXBusinessServices()، ويستدعيها المضيفان كلاهما. فالقاعدة التي تُكتب مرة تعمل في الاثنين.

هذا يحسم أين تُكتب القاعدة. أما السؤال الأصعب فهو أين تُفرض. وجوابي: في المكان الوحيد الذي يجب أن يمر به كل تغيير على البيانات.

البوابة التي يعبرها كل حفظ

يعامل FinyX كل حدث تجاري كمعاملة واحدة في قاعدة البيانات: الفاتورة وحركات مخزونها وقيدها المحاسبي تُحفظ معًا أو لا يُحفظ منها شيء. وكل حفظ يمر بوحدة العمل (unit of work)، ووحدة العمل ترفض كل ما يعيد كتابة التاريخ:

public async Task<int> SaveChangesAsync(CancellationToken ct = default)
{
    EnsureAppendOnlyAccountingAndAuditRecords(); // القيود وسطورها والدفعات وسندات الصندوق والتدقيق: إضافة فقط
    EnsurePostedDocumentsAreImmutable();         // الفاتورة المرحّلة تُصحَّح بمستند جديد
    await EnsureNoClosedFinancialPeriodWritesAsync(ct);

    var audits = BusinessAuditCapture.Capture(_context, _operationId, _user.CurrentUserKey);

    await using var tx = await _context.Database.BeginTransactionAsync(ct);
    var changed = await _context.SaveChangesAsync(ct);

    var records = audits.Select(audit => audit.Materialize()).ToArray();
    AuditChain.Link(records, await AuditChain.ReadTailHashAsync(_context, ct));
    _context.BusinessAuditRecords.AddRange(records);
    await _context.SaveChangesAsync(ct);

    await tx.CommitAsync(ct);
    return changed;
}

هذا مختصر. فالدالة الحقيقية تنضم إلى معاملة خارجية إن وُجدت، ولا تطلب من الشاشات المفتوحة أن تعيد القراءة إلا بعد الالتزام (commit)، فلا تقرأ شاشةٌ كتابةً قد يُتراجع عنها.

ثلاثة فحوص، وثلاثة وعود.

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

المرحَّل ثابت. الفاتورة أو المرتجع أو المصروف لا يتغير بعد ترحيله. وتصحيحه يكون بمستند جديد.

الفترة المقفلة تبقى مقفلة. فوق هذا الفحص تعليق يشرح لماذا يعيش هنا، ومعناه: صحة النظام لا يجوز أن تعتمد على أن تتذكر كل خدمة حالية أو قادمة أن تستدعيه. والفحص يقرأ التاريخ الأصلي للسطر المعدَّل وتاريخه الجديد معًا، فلا يُنقل قيد تاريخي إلى خارج فترة مقفلة ولا إلى داخلها. ويقفل كذلك كل ما يسبق نهاية فترة مقفلة، بما في ذلك تاريخ قبل أول فترة أو في فجوة بين فترتين. فالرصيد الافتتاحي التالي هو مجموع كل ما قبله، والسطر الذي يتسلل إلى فجوة يغيّر رقمًا وقّع عليه أحدهم من قبل.

حين كانت البوابة أشدّ مما ينبغي

قد تخطئ البوابة في الاتجاه المعاكس أيضًا، وبالصمت نفسه. أرشفة فاتورة البيع كانت تشترط أن تكون مرحّلة، ثم يرفض فحص المستندات المرحّلة الحفظ لأنها مرحّلة. فلم تنجح الأرشفة مرة واحدة. وعدّاد الطباعة كان يفشل بالطريقة نفسها بعد كل طباعة لفاتورة مرحّلة، فيبقى صفرًا، وتُقرأ الفاتورة «لم تُطبع قط».

الإصلاح قائمة سماح (allow-list) مغلقة. أربعة حقول أرشفة فقط يجوز أن تتغير على فاتورة مرحّلة:

private static readonly string[] SaleInvoiceFilingProperties =
[
    nameof(SaleInvoice.IsArchived),
    nameof(SaleInvoice.ArchivedAtUtc),
    nameof(SaleInvoice.ArchivedBy),
    nameof(SaleInvoice.PrintCount)
];

وإن تغيّر في الحفظ نفسه حقل واحد خارج هذه القائمة، رُفض الحفظ كله. ومن يريد تعديل مبلغ مرحّل لن يجد بابه هنا.

سجل تدقيق يكتشف من عدّل خلف ظهره

كان سجل التدقيق عندي يعد بشيء واحد: لا يمكن تعديله من داخل التطبيق. وهذا وعد ضعيف. فمن يفتح ملف SQLite بأداة قواعد بيانات يستطيع أن يحذف عملية بيع وسجل تدقيقها معًا، ولا يبقى ما يدل على شيء.

لذلك صار كل سجل تدقيق يحمل بصمة SHA-256 لمحتواه هو مع بصمة السجل الذي قبله. غيّر حرفًا واحدًا فتتوقف بصمته عن المطابقة. احذف سجلًا فيشير الذي بعده إلى بصمة لم تعد موجودة.

public static string ComputeEntryHash(BusinessAuditRecord record, string previousHash)
{
    var payload = string.Join("\u001F",            // فاصل لا تحويه أي قيمة
        record.OperationId.ToString("N"),
        record.OccurredAtUtc.ToString("yyyy-MM-ddTHH:mm:ss.fff", CultureInfo.InvariantCulture),
        record.UserKey, record.Action, record.EntityType, record.EntityKey,
        record.ChangedProperties, record.BeforeJson, record.AfterJson,
        record.ApplicationVersion, record.MachineName,
        previousHash);

    return Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(payload))).ToLowerInvariant();
}

اثنا عشر سطرًا، وفيها أربعة فخاخ.

أوقات تعود مختلفة. يعمل FinyX على SQLite أو SQL Server أو PostgreSQL. وSQLite يعيد DateTime بلا Kind، وPostgreSQL يقرّبه إلى الميكروثانية. فلو بصمتَ القيمة كاملة لفشل التحقق من سجل كُتب على SQLite بمجرد انتقال البيانات إلى PostgreSQL. لذلك تأخذ البصمة الوقت بالميلي ثانية بلا لاحقة نوع، فهذه الدقة وحدها تعود سليمة من كل مزوّد.

النص المبصوم صيغة تخزين. ترتيب الحقول والفاصل بينها ثابتان إلى الأبد. غيّر أحدهما فتصير كل بصمة كُتبت من قبل غير قابلة للتحقق، لذلك عامِل أي تغيير هناك معاملة ترحيل للبيانات.

كاتبان وذيل واحد. على خادم مشترك قد يحفظ جهازا كاشير في اللحظة نفسها، فيربط كلاهما سجله بالسجل السابق نفسه. وهذا عمل سليم تمامًا. والفاحص الذي يشترط خطًا مستقيمًا واحدًا سيتهم العميل كل يوم، والإنذار الذي يرنّ كل يوم يُطفأ. لذلك يتجاهل التحقق الترتيب ويفحص ثلاثة أشياء: كل بصمة تطابق محتواها، وكل بصمة سابقة تشير إلى سجل موجود، وللسلسلة بداية واحدة فقط.

الذيل بلا شاهد. احذف آخر سجل، فلن يشير إليه أحد بعده. والسلسلة وحدها لا ترى ذلك، لذلك يُحفظ عدد السجلات وآخر بصمة خارج قاعدة البيانات أيضًا. والسجل الذي قصُر يظهر بنقصان العدد.

والترتيب داخل البوابة مهم كذلك. تُلتقط قيم «قبل» قبل الحفظ الأول، ما دام EF Core يحتفظ بالقيم الأصلية. وتُقرأ قيم «بعد» والمفاتيح الأساسية الجديدة بعده. وتُقرأ بصمة الذيل داخل المعاملة نفسها، فالذيل الذي أربط به هو الذيل الذي يُلتزم به. ولأن الحفظين يتشاركان المعاملة، لا يُلتزم بتغيير تجاري دون دليله.

والاختبار يفعل تمامًا ما يفعله العابث: يكتب في ملف القاعدة بـ SQL خام، من خارج التطبيق:

// تعديل سجل من خارج التطبيق: يُكتشف
ExecuteOutsideTheSystem(db, "UPDATE BusinessAuditRecords SET UserKey = 'someone.else' WHERE Id = (SELECT MIN(Id) FROM BusinessAuditRecords);");
Require(!Verify(db).IsIntact, "An edited audit record went unnoticed.");

// إعادة القيمة: تعود السلسلة سليمة، فالفحص لا يحمل ضغينة
ExecuteOutsideTheSystem(db, "UPDATE BusinessAuditRecords SET UserKey = 'audit.chain.tests' WHERE Id = (SELECT MIN(Id) FROM BusinessAuditRecords);");
Require(Verify(db).IsIntact, "Restoring the original value left the trail broken.");

// حذف سجل من الوسط: يُكتشف
ExecuteOutsideTheSystem(db, "DELETE FROM BusinessAuditRecords WHERE Id = (SELECT MIN(Id) + 1 FROM BusinessAuditRecords);");
Require(!Verify(db).IsIntact, "A deleted audit record went unnoticed.");

وعلى PostgreSQL تحرس المشغّلات (triggers) أحد عشر جدولًا أيضًا، فيبقى القيد المرحّل وسجل التدقيق ثابتين حتى أمام من يملك أداة إدارة. واختبار آلي يقارن هذه القائمة بقائمة SQL Server، فلا يصير نقل عميل إلى خادم تخفيفًا للحماية.

اختبارات تفتح قواعد بيانات حقيقية

لا يستعمل FinyX مكتبة xUnit، فاختباراته برنامج تنفيذي واحد. كل اختبار دالة اسمها جملة إنجليزية تقول الوعد الذي يحفظه، والاختبارات التي تلمس البيانات تعمل على قاعدة SQLite حقيقية في مجلد مؤقت خاص بها. ويطبع كل اختبار سطر METRIC بالأرقام التي أثبتها، ثم PASS أو FAIL أو SKIP:

.\AccountsSystem.Tests.exe
METRIC TRIAL_BALANCE_ROWS=3;BALANCED=TRUE;SHORTAGE=100.00;CASH=900.00
PASS TrialBalance_BalancesAndNamesWhoBearsTheCashShortage
METRIC AUDIT_CHAIN_EDIT_DETECTED=PASS;AUDIT_CHAIN_DELETE_DETECTED=PASS;CLEAN_TRAIL_NOT_ACCUSED=PASS
PASS AuditTrail_DetectsAnEditedOrDeletedRecordMadeOutsideTheSystem

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

ومع كل ذلك، قالت الحزمة 372 من 373. وهذا ما لم تستطع أن تراه.

ما لم تره 372 اختبارًا ناجحًا

شاشة المبيعات تعرض عدد الفواتير المنتظرة للترحيل، ومعه زر يرحّلها. وفي نموذج العرض (view model) كانت تلك القائمة تشترط أن تكون كل فاتورة معتمدة. والاعتماد سياسة اسمها SalesRequireApprovalBeforePosting، وهي مطفأة عند الشحن. فبالإعدادات الافتراضية لم تكن أي فاتورة تصل إلى تلك القائمة، ولم يجد الزر ما يرحّله.

لماذا لم ينتبه أحد؟ لأن كل ما يراجعه الكاشير والمالك كل يوم كان صحيحًا. أرصدة العملاء والمخزون ودرج النقد تحسب المستندات غير المرحّلة عمدًا، لتبقى صحيحة قبل أن يرحّل المحاسب. وحدها التقارير التي تقرأ الدفتر نفسه، ميزان المراجعة وقائمة الدخل، كانت تخلو من كل المبيعات.

ولماذا لم تنتبه 372 اختبارًا؟ هنا الجزء الذي يستحق أن تسرقه. الخدمة كانت تملك الدالة الصحيحة من قبل: GetUnpostedSaleInvoicesAsync. كانت مختبَرة. ولم يكن أحد يستدعيها. الشاشة كانت تبني قائمتها بنفسها من الصفوف التي تعرضها في تلك اللحظة، وبنسختها الخاصة من القاعدة. فالاختبارات كانت تثبت صحة دالة لا يشغّلها المنتج أصلًا.

وللخطأ نفسه عَرَض ثانٍ. فلأن القائمة تأتي من الصفوف الظاهرة، كانت تتغير بتغيّر مرشّح التاريخ في الشاشة. وإذا اختير نطاق «اليوم»، لم يكن ممكنًا ترحيل فاتورة الأمس أصلًا.

انتقلت القاعدة إلى الخدمة، والخدمة الآن تقرأ السياسة نفسها التي يقرؤها الترحيل، والشاشة تأخذ قائمتها من الخدمة:

// AccountingJournalService.GetUnpostedSaleInvoicesAsync
var requireApproval = (await _operationalPolicyService.GetAsync(ct))
    .SalesRequireApprovalBeforePosting;

if (requireApproval)
{
    query = query.Where(invoice => invoice.ApprovedBy != null && invoice.ApprovedBy != "");
}

ما تعرضه الشاشة للترحيل صار هو بالضبط ما تقبله الخدمة.

زر «إلغاء» لا يلمس الدفتر أبدًا

ووجد التدقيق نفسه أن الضغط على «تعديل» لفاتورة مرحّلة كان يمحو قيدها أولًا ثم يفتح المحرر. فمن ضغط «إلغاء» بعدها أخرج الفاتورة من الدفاتر: الإيراد والضريبة والتكلفة والذمة تختفي، والبضاعة تبقى خارج المخزن، والفاتورة تبقى في القائمة. ولا رسالة واحدة.

الآن يُفتح المحرر أولًا. وإن أُغلق دون تأكيد، لا يُمسّ الدفتر إطلاقًا. ولا يُفكّ ترحيل الفاتورة إلا بعد التأكيد، قبيل تطبيق التعديل مباشرة، وأي فشل بعد ذلك يعيد الترحيل. وإن فشلت الإعادة نفسها، تظهر نافذة تسمّي الفاتورة وتقول إن قيدها غائب عن الدفتر.

كيف تختبر قرارًا يعيش خلف نافذة حوار، في حزمة لا شاشة فيها؟ تختبر ترتيبه في المصدر:

var body = MethodBody(File.ReadAllText(salesViewModelPath), "private async Task EditSelectedInvoiceAsync()");
var dialogGuard = body.IndexOf("editor.ShowDialog() != true", StringComparison.Ordinal);
var unpost = body.IndexOf("UnpostSaleInvoiceAsync", StringComparison.Ordinal);

Require(dialogGuard >= 0, "The editor is no longer opened before the invoice is amended.");
Require(unpost > dialogGuard, "The ledger is stripped before the editor is confirmed.");
Require(body.Contains("RestorePostingAfterAbandonedEditAsync"),
    "Nothing restores the entry when the amend fails after the invoice was unposted.");

طريقة بدائية، وهي تقيس بالضبط الشيء الذي انكسر.

باب الطوارئ الذي التفّ حول البوابة

فكّ ترحيل فاتورة يتطلب حذف قيدها، والبوابة تمنع ذلك. لذلك كان لفكّ الترحيل والحذف الإداري طريق خاص بهما: SQL خام مع تعليق مشغّلات القاعدة. هذا الطريق لم يمر بوحدة العمل قط، فلم يلتقِ بفحص الفترة المقفلة. وكان ممكنًا عبره أن يُمحى قيد من شهر أُقفل.

الإصلاح يُجري فحص الفترة قبل فتح الاتصال، وقبل تعليق أي مشغّل. فالطلب الذي يمسّ فترة مقفلة يُرفض قبل أن يُلمس صف واحد.

كل طريق يلتفّ حول البوابة يجب أن يحمل فحوصها معه. وأسرع طريقة لتجد طرقك أنت: ابحث في الكود عن SQL خام.

الاختبار الأحمر الذي يتعلم الجميع تجاوزه

الاختبار الوحيد الفاشل من الـ 373 كان يفشل في كل تشغيل عادي. كان يحتاج قاعدة بيانات يجهّزها سكربت منفصل مسبقًا، فهو أحمر دائمًا عند كل من سواه. والفشل الدائم في قائمة خضراء يعلّم قارئها أن يتجاوزه، فيتجاوز معه أول فشل حقيقي. الآن يبني الاختبار قاعدته بنفسه في مجلد مؤقت جديد ويحذفه بعد انتهائه. وبعد الإصلاحات نجحت الحزمة 376 من 376.

وبعد أقل من شهر صار لسطح المكتب 475 اختبارًا.

قائمة الفحص التي أعمل بها

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

لو بدأت FinyX من جديد غدًا لكتبت بوابة الحفظ قبل أول شاشة. فأولى ملاحظات التدقيق كانت قاعدتين تعيشان في شاشة، وطريق SQL خام يلتف حول البوابة. ضع القاعدة حيث تتغير البيانات، ثم اكتب الاختبار الذي يثبت أن الشاشة تستعملها.

وهو الانضباط نفسه الذي أبني به أنظمة الأعمال لعملائي.

كانت طابعة Xprinter XP-370B على جهاز كاشير يعمل فعلًا، فيها رول بعرض 76 مم، وظلّت تُخرج الورق حتى انتهى الرول. وحين قستُ المهمة لاحقًا دون أن أطبعها، وجدتها تطلب 124.7 مم لا أكثر. المهمة كان لها حدّ، والطابعة لم يكن لها حدّ.

والسبب خمسة بايتات. كل صف في صورة الإيصال كان بعرض 72 بايتًا، على رأس لا يطبع إلا 67.

يطبع FinyX-ERP كل إيصالاته بالعربية، وفي أسفلها رمز QR، على طابعات بدقة 203 نقطة في البوصة، ثمنها قليل ولا تغفر شيئًا. ولا يرسل إليها حرفًا عربيًا واحدًا. وحين تنتهي من هذا المقال ستستطيع أن تطبع عربية سليمة على أي طابعة ESC/POS، بسقف صارم لما تستهلكه من ورق، وستعرف بالضبط كيف تحوّل خمسةُ بايتات البكسلاتِ إلى أوامر.

لماذا لا تعرف الطابعة كيف تكتب العربية

الوضع النصي في طابعة الإيصالات صُمّم للحرف اللاتيني: خطوط محفوظة في ذاكرتها، وجداول ترميز تقابل كل بايت بشكل واحد. والعربية تطلب أكثر من ذلك بكثير. الحرف الواحد له حتى أربعة أشكال بحسب جيرانه، واللام والألف يندمجان في شكل واحد، والسطر يجري من اليمين إلى اليسار بينما الأرقام داخله تجري من اليسار إلى اليمين. كتبت عن قواعد الاتصال في لماذا تكسر تأثيرات النص حرفًا بحرف العربية. والوضع النصي لا يفعل شيئًا من هذا.

وفي الواقع، جداول الترميز في البرنامج الثابت للطابعة تفصل الحروف، أو تقلب ترتيبها، أو تضع مكانها أشكالًا لا علاقة لها بالعربية، وقد يختلف سلوك جهازين من الطراز نفسه. ولا أستطيع أن أدعم سلوكًا لا أستطيع توقّعه.

لذلك لا تصل العربية في FinyX-ERP إلى أي طابعة نصًّا. الحاسوب يشكّلها بمحرك نصوص حقيقي، والإيصال كله يصير صورة بالأبيض والأسود، والطابعة لا تستقبل إلا صورًا نقطية. وملصقات الباركود على القاعدة نفسها: في طابعات الملصقات بلغة TSPL، يُرسل اسم الصنف العربي صورةً أيضًا.

الصور تحلّ مشكلة العربية حلًّا كاملًا. لكنها تحمل الخطر الذي تدور حوله هذه القصة، فالصورة عند الطابعة ليست إلا بايتات إضافية في سيل الأوامر.

خمس خطوات من البيع إلى النقاط المحروقة

يركّب QuestPDF الإيصال من اليمين إلى اليسار على صفحة متصلة بلا ارتفاع ثابت، بعرض منطقة الطباعة بالضبط. ثم تُرسم الصفحة بدقة 203 نقطة في البوصة، فيصير كل بكسل نقطة من نقاط الطابعة، ومن هناك إلى آخر الطريق لا شيء إلا البتّات.

المُرمِّز قصير، وثلاثة أسطر فيه تقوم بالعمل كله:

// معادلة Rec. 601 للسطوع، بأعداد صحيحة.
var luminance = (77 * red + 150 * green + 29 * blue) >> 8;

// يُركَّب البكسل الشفاف على أبيض أولًا. بدون ذلك تُقرأ الخلفية غير المرسومة
// سوداء، فيخرج الإيصال مستطيلًا أسود.
luminance = (luminance * alpha + 255 * (255 - alpha)) / 255;

if (luminance < InkThreshold)   // 180
    raster[y * rowBytes + x / 8] |= (byte)(0x80 >> (x % 8));

كل نقطة بتّ واحد، وأقصى نقطة يسارًا في البايت هي أعلى بتّاته، فالنقطة x تقع في البايت x / 8 تحت القناع 0x80 >> (x % 8). والصف الذي عرضه 536 نقطة يساوي 67 بايتًا. احفظ هذا الرقم.

الشرائح تخرج بأمر GS v 0، كل شريحة 128 صفًا. هذا الأمر يقدّم الورق بارتفاع الصورة بالضبط، فتلتقي الشرائح بلا خط فاصل، بينما سطر جديد بينها يفتح شريطًا أبيض. وما تحت آخر صف فيه حبر يُحذف إلا هامشًا نحو 2 مم، فلا يخرج بعد الإيصال شبرٌ من الورق الأبيض.

والإرسال عبر winspool مباشرة بنوع بيانات RAW، على أجزاء من 64 كيلوبايت. وتعريف ويندوز المثبّت لهذه الطابعة تعريفُ ملصقات، وRAW يمنعه من تحويل أوامر ESC/POS إلى لغته TSPL. وإن فشل شيء في المنتصف، يستدعي الكود AbortPrinter ولا يعيد المحاولة أبدًا: مهمة ناقصة غامضة تُرسل مرتين قد تكرّر الإيصال أو تُفرغ الرول.

سبعة أوامر، بكل بايتاتها

لا يحتاج الإيصال إلى أكثر من سبعة أوامر. هذه هي ببايتاتها الدقيقة لورق 76 مم على XP-370B، والأعداد ذات البايتين بترتيب little-endian.

انظر إلى سطر GS W. الرقم 536 أهم رقم في هذا المقال، ولم أختره أنا.

الورقة أعرض من الطباعة

عند 203 نقطة في البوصة، المليمتر نحو ثماني نقاط، لكن عند 203 وحدها. لذلك تتحوّل المليمترات إلى نقاط في دالة واحدة فقط، بدقة الطابعة نفسها، مع تقريب النصف بعيدًا عن الصفر حتى لا تنكمش وحدة الباركود.

الأولان ملفّان عامّان. أما أرقام XP-370B فمقيسة: عرض الورق 607 نقاط، والرأس يطبع 536 منها، وأول 24 نقطة لا يصلها ميكانيكيًا. واستعمال العرض كله كان يقصّ العمود الأيمن. وفي الإيصال العربي، الحافة اليمنى هي حيث يبدأ كل سطر، فهي أسوأ حافة يمكن أن تخسرها.

وفي الإعدادات خمس مناطق طباعة (384 و512 و536 و576 و608 نقطة)، والافتراضي 536 المحافظ. المنطقة الأضيق تُطبع دائمًا. الأعرض هي ما يكسر الأمور، وسترى بعد قليل إلى أي حد.

وأكبر تحسّن في الجودة جاء من قرار واحد. كانت إيصالاتي الأولى تُركَّب بعرض 80 مم، ثم يصغّرها المُرمِّز إلى 536 نقطة، بمعامل 0.84. وتصغير صورة أحادية البت هو ما يجعل العربية مشعّثة: الخطّ المصغَّر يقع بين النقاط، فتضطر العتبة إلى التخمين. الآن تُركَّب الصفحة بعرض منطقة الطباعة نفسها:

// 536 نقطة عند 203 = 67.07 مم. كل بكسل في الصفحة نقطةٌ مطبوعة.
internal static float PageWidthMm(DocumentPrintSettings settings) =>
    (float)(settings.ReceiptPrintAreaDots * 25.4d / RasterDpi);

هذا الرقم 536 جاء من رولٍ ملقى على الأرض، وسنصل إليه. لكن العربية نفسها تحتاج قواعد أولًا، فبتٌّ واحد لكل نقطة وسطٌ قاسٍ لا يرحم.

كيف تنجو العربية ببتٍّ واحد

رأس الطباعة عند 203 لا يعرف الرمادي. كل نقطة إما تحترق أو لا، والخط الأرقّ من نقطة لا يُطبع أصلًا. ومن هنا جاءت أربع قواعد.

اختر الخط بالتجربة. رسمت الفاتورة نفسها بخط Ping AR + LT وبخط Cairo بالمقاس الحقيقي، ومرّرتهما على العتبة نفسها، ثم قارنت. خط Ping أضيق وأكثر انتظامًا، فيتّسع السطر لاسم صنف أطول، وتبقى سيقانه بعرض نقطة كاملة عند 7.5 نقطة. أما Cairo فيبدأ بالتفتّت عند هذه المقاسات. فصار Ping الخط الافتراضي للقوالب الحرارية.

وزن Medium للمتن. عند 8 نقاط، وصلات الوزن العادي المصمَّم للشاشات المضيئة تقلّ عن نقطة واحدة فتنكسر، ويبدو الحرف ممزّقًا.

أرضية 6.5 نقطة. هذا نحو 18 نقطة طباعة ارتفاعًا. وما دونها تبدأ النقاط التي تفرّق الباء عن التاء عن الثاء بالذوبان في جسم الحرف.

لا ألوان ولا رمادي. كل شيء ينهار إلى أبيض أو أسود عند العتبة، فالشريط المظلَّل الفاتح إما لا يُطبع، وإما يصير كتلة سوداء فوق نصّه. واسم المستند نصٌّ أبيض على شريط أسود مصمت.

المتن 8 نقاط، والعناوين الصغيرة 7.5، والإجمالي المستحق 13. ومقاسات بهذا الصغر لا تنجح إلا لأن شيئًا لا يُصغَّر في طريقه إلى الرأس.

الأرقام والاتجاه

مع ثقافة عربية، يحوّل محرك النصوص الأرقام إلى الهندية، فيُطبع 76,400.00 هكذا: ٧٦٬٤٠٠٫٠٠. هذا مقروء، لكن الزبون يقارن السعر بملصق الرف، والمورّد يقرأ أرقام الباركود، وكلاهما يحتاج أرقامًا غربية. لذلك الأرقام الغربية هي الافتراضي، والهندية خيار في الإعدادات. وفي مُصيِّر WPF الذي يرسم الملصقات، المفتاح كائن واحد:

_numbers = new NumberSubstitution(
    NumberCultureSource.Override,
    CultureInfo.GetCultureInfo(arabicIndicDigits ? "ar-SA" : "en-US"),
    arabicIndicDigits ? NumberSubstitutionMethod.NativeNational : NumberSubstitutionMethod.European);

والتاريخ مع الوقت، مثل 2026/09/08 14:35، فيه مقطعان لاتينيان. داخل فقرة عربية يُرتَّبان من اليمين إلى اليسار، فيصل الوقت إلى الورق قبل التاريخ. لذلك توضع هذه القيم داخل عازل اتجاه من اليسار إلى اليمين (isolate):

// U+2066 LEFT-TO-RIGHT ISOLATE … U+2069 POP DIRECTIONAL ISOLATE
internal static string Ltr(string value) =>
    string.IsNullOrEmpty(value) ? value : $"⁦{value}⁩";

العازل يثبّت ترتيب الحروف ويترك موضعها لتدفّق السطر العربي. أما الحاوية ذات الاتجاه اليساري فتدفع القيمة أيضًا إلى الحافة اليسرى من خليتها.

ولا تضع نصًّا عربيًا داخل العازل أبدًا: هناك تنقلب حروف رمز الريال اليمني «ر.ي». لذلك تُطبع العملة برمزها الدولي (YER وSAR)، مرةً واحدة، على الإجمالي المستحق. وخطآن من العائلة نفسها وصلا إلى الورق: سطر الدفع كان يبني نصّه دون عازل فطُبع YER 75,000.00 مقلوبًا، والرصيد السالب طُبع 50,000.00- لأن إشارة السالب أُضيفت خارج العازل. وكلاهما يمرّ الآن على منسّق واحد.

مشكَّلة ومقيسة ومرتّبة، صارت الإيصالات أخيرًا كما ينبغي. ثم طبع كاشير يعمل فعلًا واحدًا منها، ولم يتوقف.

الرول الملقى على الأرض

بدت الفرضية الأولى متماسكة. التعريف يعلن وسائط بعرض 38.1 مم والإيصال بعرض 76 مم، فبدا أن الطابعة عالقة في وضع الملصقات، تبحث عن فاصل لا وجود له في الورق المتصل.

أسقطتُها بسكربت PowerShell. أرسل ESC/POS خامًا إلى الطابعة نفسها بالإعدادات نفسها، فطبع نسخة واحدة سليمة وتوقف. ومهمة RAW تتجاوز التعريف كليًا، فمقاس الوسائط فيه لا يمكن أن يكون السبب. الفرق إذن في البايتات.

فقست المهمة دون أن أرسلها. أداة تشخيص تشغّل المركِّب والمُرمِّز الحقيقيين، وتكتب سيل الأوامر بدل الورق:

QuestPDF: 1 page, 639 × 1037 px = 129.8 mm
ESC @ · ESC a 1 · GS L 0 · GS W 576 · 8 × GS v 0 (72 bytes × 128 rows) · ESC d 3
paper requested: 124.7 mm

اثنا عشر سنتيمترًا، ولا بايت واحد زائد. والذي اختلف عن السكربت الناجح هو الأبعاد:

هذه هي البايتات الخمسة. 576 نقطة بإزاحة صفر أعرض مما يطبعه هذا الرأس على ورق 76 مم. وحين يستقبل البرنامج الثابت صفوفًا أعرض من منطقة طباعته، يعيد المزامنة في منتصف الصورة، ومن تلك اللحظة يقرأ بايتات الصورة على أنها أوامر. وبيانات الصورة مليئة ببايتات معناها «غذِّ الورق». هكذا يصير إيصال طوله 12 سم رولًا على الأرض.

وESC d زاد الطين بلّة: يغذّي بالأسطر، وبعض البرامج الثابتة القادرة على الملصقات تقرؤه طلبًا للانتقال إلى النموذج التالي، والورق المتصل لا نموذج تاليًا فيه.

الإصلاح ثلاثة أجزاء:

• كل صف في الصورة بعرض ما يعلنه GS W تمامًا (rowBytes = printAreaDots / 8)، وما يتجاوزه يُقصّ. فلا يمكن أن يختلف المُرمِّز والطابعة على عدد البايتات، وفحصٌ يشترط rowBytes × 8 == width بالضبط.
• ESC J بالنقاط مكان ESC d، مقسّمًا على خطوات لا تتجاوز 255 لأنه يأخذ بايتًا واحدًا.
• حُذف ESC a 1. الصورة تملأ المنطقة كلها، فلم تكن المحاذاة إلا طريقًا آخر لاختلاف الطرفين.

بعد الإصلاح صار السيل مطابقًا للسكربت الناجح، أمرًا بأمر:

ESC @ · GS L 24 · GS W 536 · 7 × GS v 0 (67 bytes × 128 rows) · ESC J 216
paper requested: 134.9 mm

ثم تأكدت أن أي خطأ تخطيط قادم سينتهي برسالة خطأ. الإيصال الواحد لا يتجاوز 800 مم من الورق، بالتغذية، ويُفحص ذلك قبل أن يخرج أول بايت؛ وكان السقف القديم 40,000 صف، أي نحو خمسة أمتار. وفي إعدادات الطباعة زرٌّ يُفرغ قائمة الطابعة، وسكربت يفعل الشيء نفسه دون تشغيل البرنامج:

# أوقف القائمة حتى لا تبدأ مهمة جديدة، ثم ألغِ ما فيها.
Add-Type -AssemblyName System.Printing, ReachFramework
$server = New-Object System.Printing.LocalPrintServer
$queue  = $server.GetPrintQueues() | Where-Object FullName -eq 'Xprinter XP-370B'
$queue.Pause(); $queue.Commit()
foreach ($job in $queue.GetPrintJobInfoCollection()) { $job.Cancel(); $job.Dispose() }

واعرف حدوده. الورق المتحرك الآن يأتي من ذاكرة الطابعة نفسها ويتوقف حين تنفد. فإن استمر بعد ذلك، فالطابعة تغذّي من تلقاء نفسها، ولن يوقفها إلا مفتاح الطاقة أو تصحيح وضع الوسائط.

وفي سجل الأخطاء نفسه طريقٌ ثانٍ لإهدار رول. Process.Start مع الفعل print يرسل ملف PDF إلى طابعة ويندوز الافتراضية. وعلى جهاز كاشير تكون فيه الطابعة الحرارية هي الافتراضية، تمرّ صفحة A4 عبر التعريف الحراري إلى رول لا حدّ لطول صفحته. الآن يُفتح ملف PDF، ويختار إنسانٌ الطابعة بنفسه.

رمز QR والتغذية والقطع والدرج

رمز QR. يُرسم الرمز بصيغة SVG: مربّع لكل وحدة، وshape-rendering="crispEdges"، بلا تنعيم. الرمز النقطي حين يُعاد تحجيمه تتداخل وحداته فيعجز عنه الماسح، والمتّجه يُرسم مباشرة على شبكة الطابعة نفسها.

var matrix = new QRCodeWriter().encode(content, BarcodeFormat.QR_CODE, 0, 0,
    new Dictionary<EncodeHintType, object>
    {
        [EncodeHintType.ERROR_CORRECTION] = ErrorCorrectionLevel.M,
        [EncodeHintType.MARGIN] = 0,   // الهامش الهادئ يُضاف يدويًا: 4 وحدات
    });
// ثم مربّع "M x,y h1v1h-1z" لكل وحدة سوداء

مستوى تصحيح الأخطاء M: رمز الإيصال نحو 550 حرفًا، والمستوى H يكبّره حتى لا يُطبع بحجم يُقرأ، وM يحتمل خدشًا أو بقعة حبر عادية. ويُطبع بمقاس 38 × 38 مم، في المنتصف بين الإجماليات والتذييل.

التغذية. بعد آخر سطر يتقدّم الورق 27 مم، فيتجاوز التذييل حافة التمزيق. وESC J يعدّ وحدات حركة، وهي نقطة واحدة في هذه الطابعات، فالـ 27 مم تساوي 216 نقطة.

القطع. فقط إن كان للطابعة قاطع، لأن أمر القطع إلى طابعة بلا قاطع يعلّقها أو يُطبع حروفًا. تعريف XP-370B يعرض None وTear Off وPeel Off، ولا يعرض Cut، فيمزّق الكاشير الورقة بيده. وفي غيرها يقطع GS V قطعًا جزئيًا مرةً واحدة بعد الإيصال كله. والمسار الحالي ما زال يتعرّف على XP-370B من اسمها؛ أما المُرمِّز الجديد المقاد بملف الطابعة، الذي أنتقل إليه، فيقرأ القاطع من ملفها.

الدرج. يرسل ESC p نبضة لدرج النقود. وهو في المُرمِّز الجديد، ومطفأ افتراضيًا: نبضة إلى طابعة موصولة بشيء آخر أحسن أحوالها صوت طقطقة.

قبل أن تطبع إيصالًا واحدًا

• عامل العربية بكسلاتٍ من اليوم الأول.
• قِس منطقة الطباعة على الطابعة الحقيقية، واحفظها لكل طابعة، وأعلنها في كل مهمة بـ GS L وGS W.
• اجعل كل صف في الصورة printAreaDots / 8 بايتًا بالضبط، وقُصّ ما يزيد.
• ركّب الصفحة بعرضها النهائي. لا تصغّر صورة أحادية البت أبدًا.
• ركّب الشفافية على الأبيض قبل العتبة.
• غذِّ الورق بالنقاط بأمر ESC J، وضع سقفًا للورق قبل أن ترسل أي شيء.
• عايِن البتات التي سيحرقها الرأس. أداة المعاينة عندي تمرّر الصفحات على المُرمِّز الحقيقي وتحفظ النتيجة PNG، وكشفت الالتفاف والانعكاس والطول الزائد قبل أن تكلّف ورقة.
• لا تُعِد الطباعة تلقائيًا أبدًا.

حين صارت العربية بكسلات، لم يبقَ من المشكلات إلا الهندسة: بأي عرض تطبع، وكم تغذّي، وأين تتوقف. وخمسة بايتات منها كلّفت رولًا كاملًا.

لم يتحرك أي رصيد بريال واحد، فقاعدة البيانات رفضت كل محاولة إدخال منها.

وكل طلب من تلك الطلبات مرّ عبر طبقة idempotency بُنيت لهذا بالضبط: هواتف تعيد الإرسال.

هذه طريقة FinyxWatt في فوترة مشتركي الكهرباء من هواتف تفقد الشبكة: المعرّف الذي يرافق الدفعة من الهاتف حتى الإيصال، والسبب الذي يمنع جمع إجماليات الفواتير، والطابور الصادر الذي يقرر ما يُعاد إرساله، والقاعدة التي كانت تنقصني تلك الليلة. وحين تنتهي ستستطيع أن تبني طابورًا للمال يعمل دون اتصال، لا تستطيع فيه إعادة المحاولة أن تحصّل مرتين، ولا يستطيع فيه الرفض أن يدور في حلقة.

حين تنقطع الشبكة يحتفظ الهاتف بالعمل

تعمل محطة الكهرباء الخاصة عبر سلسلة خطوات صغيرة: المحصّل يقرأ العداد، ثم تصدر الفاتورة، ثم تصل المشترك رسالة SMS، ثم يُحصَّل المبلغ، ثم ينتقل النقد إلى المدير. وFinyxWatt هي المنصة التي بنيتها لهذه السلسلة: أربعة تطبيقات Flutter على API واحد بـ NestJS فوق PostgreSQL. وتطبيق المحطة هو الذي في أيدي المحصّلين، والمحطات تفقد الشبكة كثيرًا.

لذلك لا ينتظر التطبيق الشبكة أبدًا. يعرض النسخ المحفوظة أولًا، وكل عملية كتابة تدخل طابورًا صادرًا (outbox) على الهاتف. وحين يعود الاتصال، يرفعها منسّق واحد بترتيب الاعتماد: المشتركون الجدد أولًا، ثم الفواتير والسندات التي قد تشير إليهم، ثم المحادثات. والسند الذي يخص فاتورة لا توجد بعد إلا على الهاتف ينتظر دوره. وبعد جولة فاشلة ينتظر المنسّق 30 ثانية، ويضاعفها حتى خمس دقائق، كي لا يُثقل على خادم متعثر.

كانت النسخة الأولى على Firebase، ونقلتها إلى خلفيتي الخاصة والمحطات تعمل، فخرجت من النقل بقاعدة واحدة: الهاتف يقترح، والخادم يقرر.

إعادة المحاولة هي التصميم كله، وهذا يفرض سؤالين. إذا كانت إعادة المحاولة أمرًا عاديًا، فما الذي يمنعها من التحصيل مرتين؟ وما الذي يمنعها من أن تستمر إلى ما لا نهاية؟ للسؤال الأول جواب نظيف. أما الثاني فهو ليلة 18 أكتوبر.

أعطِ العملية معرّفها لحظة ولادتها

كل عملية تأخذ UUID عشوائيًا لحظة حفظها أول مرة على الهاتف، وتحتفظ به عبر كل إعادة محاولة، وكل إعادة تشغيل للتطبيق، وكل رد ضائع. والمعرّف هو أيضًا هوية ما تنشئه العملية: الفاتورة المنتظرة في الطابور تُنشأ على الخادم بهذا المعرّف، وكذلك الدفعة.

/// معرّف عشوائي جديد (الإصدار 4)، يُنشأ حين تدخل العملية الطابور أول مرة.
String newOperationId() {
  final random = Random.secure();
  final bytes = List<int>.generate(16, (_) => random.nextInt(256));
  bytes[6] = (bytes[6] & 0x0f) | 0x40;
  bytes[8] = (bytes[8] & 0x3f) | 0x80;
  return _format(bytes);
}

/// المعرّف المحفوظ مع العملية، أو معرّف مشتق للعناصر الأقدم.
String operationIdFor(Map<String, dynamic> payload, String queueItemId) {
  final stored = payload['operationId'];
  if (stored is String && isCanonicalUuid(stored)) return stored.toLowerCase();
  return derivedOperationId(queueItemId);
}

الدالة الثانية تعالج فخًّا يظهر بعد الترقية. قد يصل إصدار جديد من التطبيق إلى هاتف ما زال يحمل عمليات وضعها في الطابور إصدار أقدم لم يكن يحفظ معرّفًا. ولو ولّدت معرّفًا جديدًا مع كل إعادة محاولة، لبنيت بيدك التحصيل المزدوج الذي أردت منعه. لذلك تأخذ العملية القديمة معرّفًا مشتقًا من معرّفها الدائم في الطابور، فيبقى القيمة نفسها في كل إعادة، ويُعلَّم بالإصدار 8 من UUID ليعرف من يقرؤه أنه مشتق.

وداخل هذا الاشتقاق فخ ثانٍ. فهو يستعمل FNV-1a بطول 32 بت، والضرب في عدد FNV الأولي مكتوب إزاحاتٍ:

hash = (hash + (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24)) & 0xffffffff;

السبب أن كود Dart نفسه يُبنى للمتصفح أيضًا، والأعداد الصحيحة هناك أعداد عشرية مزدوجة (doubles). فالضرب العادي قد يتجاوز 2^53 ويفقد بتاته الدنيا، فيشتق المتصفح من عنصر الطابور نفسه معرّفًا غير الذي يشتقه الهاتف.

احجز المعرّف قبل أن تبدأ العمل

على الخادم يصل المعرّف في ترويسة Idempotency-Key، ويحجزه الـ API قبل أن يلمس أي مال. والحجز والعملية يتشاركان معاملة واحدة:

const claimed = await trx.insertInto('idempotency_receipts').values({
  tenant_id, actor_identity_id, idempotency_key: key, operation,
  request_hash: sha256(stableStringify(request)),
  status: 'processing',
}).onConflict((c) => c.columns(['tenant_id', 'actor_identity_id', 'idempotency_key']).doNothing())
  .returning('idempotency_key').executeTakeFirst()

if (claimed === undefined) {
  const existing = await readReceiptForUpdate(trx, key) // SELECT … FOR UPDATE
  if (existing === undefined) throw conflict('IDEMPOTENCY_RECEIPT_UNAVAILABLE') // الفشل مغلقًا
  if (existing.operation !== operation || existing.request_hash !== requestHash) throw conflict('IDEMPOTENCY_KEY_REUSED')
  if (existing.status !== 'completed') throw conflict('OPERATION_IN_PROGRESS')
  return { replayed: true, status: existing.response_status, body: existing.response_body }
}

const result = await execute(trx)       // أول مرة: ننفذ العمل
await markCompleted(trx, key, result)   // ونحفظ استجابته في المعاملة نفسها
return { replayed: false, ...result }

كل سطر هنا يغلق بابًا.

• نسختان من الطلب نفسه تصلان معًا لا تُنفَّذان معًا. فـ PostgreSQL يجعل ON CONFLICT الثانية تنتظر معاملة الأولى، ثم يقرأ الخاسر الإيصال المكتمل.
• الإيصال الموجود الذي تتعذر قراءته يفشل مغلقًا (fail closed). فتنفيذ العملية مرة ثانية هو الشيء الوحيد الذي يجب ألا يفعله هذا الكود أبدًا.
• المفتاح المعروف إذا جاء بجسم مختلف فذلك خطأ في العميل، فيأخذ 409 بدل الإعادة. والجسم يُبصم بعد تحويله إلى نص بترتيب ثابت للمفاتيح، فتعطي العملية نفسها البصمة نفسها دائمًا.
• المفتاح الذي ما زال في حالة processing يجيب بـ OPERATION_IN_PROGRESS، والهاتف يضعه تحت «حاول لاحقًا».

وفخ هنا احتاج ترحيلًا كاملًا لإصلاحه. كان مفتاح جدول الإيصالات الأول هو المحطة والمستخدم والعملية والمفتاح معًا. بدا ذلك مرتبًا، لكنه سمح باستعمال المفتاح الواحد مرة لكل endpoint. فلو وُجّهت إعادة محاولة يومًا إلى endpoint خاطئ، لأمكن للمفتاح نفسه أن يصنع أثرًا ثانيًا. فجعل الترحيل 0015 كل مفتاح صالحًا لمرة واحدة لكل مستخدم، عبر كل أنواع العمليات.

وهكذا صار الرد الضائع بلا ضرر. لكن تذكّر تفصيلًا واحدًا من ذلك الكود: الاستجابة تُحفظ في المعاملة نفسها التي يجري فيها العمل. سنحتاجه بعد قليل.

الخادم هو من يحسب

الطلب الذي لا يتكرر أثره لا يكون آمنًا إلا إذا لم يحمل مالًا اخترعه الهاتف. الهاتف يرسل قراءة العداد، والخادم يتولى الباقي.

قيمة الفاتورة = (القراءة الحالية − القراءة السابقة) × سعر الكيلوواط، مقرّبة إلى منزلتين عشريتين بنوع numeric في PostgreSQL. والقراءة السابقة تأتي من سجل العداد، ويقفله الخادم طوال المعاملة. والسعر هو سعر المشترك الخاص ما دام ضمن تواريخه، وإلا فسعر المحطة. والسعر الذي يرسله الهاتف لا يُعتدّ به إلا في محطة لم تحفظ سعرًا قط، فلا يستطيع هاتف بقي دون اتصال أسابيع أن يفوتر بسعر قديم.

والآثار الجانبية تحتاج الانضباط نفسه. رسالة SMS للمشترك تُنشأ في المعاملة نفسها التي تصدر فيها فاتورته، بالمفتاح invoice:<id>:issued:v1، مع فهرس فريد على المصدر والقالب والمستلم. فلا تستطيع فاتورة مُعادة أن تضيف رسالة ثانية إلى الطابور.

لا تجمع إجماليات الفواتير أبدًا

كل مبلغ على المشترك يعيش في جدول واحد: ledger_entries. قيم الفواتير وعكس الدفعات قيود مدينة، والدفعات وإلغاء الفواتير قيود دائنة، والرصيد هو المجموع. ودور الـ API في قاعدة البيانات لا يملك على هذا الجدول إلا SELECT وINSERT، وtrigger يرفض ما سواهما:

CREATE TRIGGER ledger_entries_append_only
BEFORE UPDATE OR DELETE ON ledger_entries
FOR EACH ROW EXECUTE FUNCTION app_private.prevent_ledger_mutation();
-- يرفع: 'ledger entries are append-only; post a reversal entry instead'

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

الفاتورة أ: 1,000 غير مسددة. الفاتورة ب: 500 + 1,000 متأخرات = 1,500. فقُبلت دفعة 1,000 على أ ودفعة 1,500 على ب، والدين الحقيقي 1,500 فقط. وكان العدادان للمشترك الواحد، أو الفاتورة الملغاة، يفتحان الثغرة نفسها.

غيّر الترحيل 0080 ثلاث قواعد. إصدار فاتورة جديدة يُرحّل إليها كل فاتورة مفتوحة للمشترك، والفاتورة المرحّلة لا تقبل دفعًا. والدفعة محدودة بالمتبقي من الفاتورة وبرصيد المشترك في السجل. وبعد أي تغيير مالي، تضبط قاعدة البيانات حالة كل فاتورة من السجل، بدءًا بأقدم دين، فلا تُستنتج حالة السداد أبدًا من مقارنة paid_amount بـ total_amount.

وكان الخطأ نفسه مختبئًا في لوحة الإدارة. لوحة الموقع كانت تجمع صفحة من 250 صفًا لتعرض ما فُوتر وما بقي. الآن تجمع قاعدة البيانات كل صف يحق للعضو أن يراه، واللوحة تقرأ ذلك الرقم الواحد.

رموز الحالة هي سياسة إعادة المحاولة

نعود إلى الطابور الصادر. حين يفشل الرفع، على الهاتف أن يقرر معنى هذا الفشل، وهو يصنّف كل خطأ في أربعة أنواع:

اقرأ الـ 500 في هذا الجدول مرة أخرى. والآن، ليلة 18 أكتوبر.

كان السند يحمل رقم عملية من مزوّد دفع، أي مرجع حوالة. وهذا الرقم كان موجودًا من قبل على سند آخر ساري من المزوّد نفسه. ففعل الفهرس الفريد payments_provider_reference_unique ما صُمّم له ورفض الإدخال. ولم يكن في الـ API ما يترجم هذا الخطأ، فخرج 500. والهواتف تقرأ الـ 500 فشلًا عابرًا، فأعادت إرسال السند.

والآن سؤال البداية: لماذا لم توقفه طبقة الـ idempotency؟

لأن المفتاح يعيد النجاح فقط. الحجز يعيش في المعاملة نفسها التي يجري فيها العمل، وهذا بالضبط ما يجعله آمنًا: العمل واستجابته المحفوظة يُلتزم بهما معًا أو لا يُلتزم بشيء. فحين فشل الإدخال ألغت PostgreSQL المعاملة، واختفى الحجز معها. لم يبقَ ما يتذكر الفشل، فكانت كل إعادة إرسال محاولةً أولى تفشل بالطريقة نفسها. وحفظ الفشل كان سيكون أسوأ، لأن الفشل العابر، كتعارض أقفال (deadlock) أو إعادة تشغيل، كان سيُعاد عندها إلى الأبد.

المفتاح أدّى عمله، ورمز الحالة كان هو الخطأ. والإصلاح دالة واحدة: صار هذا الخرق للفهرس الفريد 409، يشرحه تطبيق المحطة والموقع بعربية واضحة. وعلى الهاتف يُحجب الـ 409، ويُعرض للمراجعة، ولا يُعاد إرساله أبدًا.

function duplicateReference(error: unknown): never {
  const failure = error as { code?: unknown; constraint?: unknown } | null
  if (failure?.code === '23505' && failure.constraint === 'payments_provider_reference_unique') {
    throw new ConflictException({ code: 'PAYMENT_REFERENCE_DUPLICATE' })
  }
  throw error
}

والالتزام (commit) الذي أصلحه مؤرخ بالساعة 22:29 من الليلة نفسها. واختبار التكامل فيه يرسل العملية نفسها مرتين بالمفتاح نفسه، وينتظر الـ 409 نفسه في المرتين. ويتحقق كذلك من أن مزوّدًا آخر يجوز أن يحمل الرقم نفسه.

الكتابات المتأخرة تهبط في الفترة المفتوحة

والهواتف التي تعمل دون اتصال تطرح سؤالًا آخر: ماذا لو رفع هاتف سندًا تاريخه داخل فترة أقفلتها المحطة من قبل؟ إقفال الفترة يكتب لكل مشترك قيد إقفال وقيد افتتاح مجموعهما صفر، ويجب أن يبقى مجموع الفترة المقفلة صفرًا. لذلك ينقل trigger القيد المتأخر إلى بداية الفترة المفتوحة:

CREATE FUNCTION app_private.ledger_entry_into_open_period() RETURNS trigger AS $$
DECLARE open_from timestamptz;
BEGIN
  PERFORM pg_advisory_xact_lock_shared(hashtextextended('archive:' || NEW.tenant_id::text, 0));
  open_from := app_private.archive_boundary(NEW.tenant_id);
  IF NEW.effective_at < open_from AND NEW.entry_kind::text <> 'period_close' THEN
    NEW.effective_at := open_from;
  END IF;
  RETURN NEW;
END $$ LANGUAGE plpgsql;

والإقفال يأخذ القفل الاستشاري (advisory lock) نفسه حصريًا، لكل محطة على حدة. فينتظر الإقفال الكتابات الجارية، وتنتظر الكتابات الجديدة الإقفال.

قائمة الفحص للمال الذي يعمل دون اتصال

• أعطِ كل عملية معرّفها حين تُحفظ أول مرة على الجهاز، واحتفظ به حتى يؤكدها الخادم.
• أعطِ العمليات التي سبقت وجود المعرّفات معرّفًا مشتقًا ثابتًا، ولا تولّد معرّفًا جديدًا مع كل إعادة.
• اجعل المعرّف هوية ما تنشئه العملية: معرّف الفاتورة، ومعرّف الدفعة.
• احجز المفتاح قبل العمل، في المعاملة نفسها، واحفظ الاستجابة معه.
• اجعل المفتاح صالحًا لمرة واحدة لكل مستخدم عبر كل endpoint، وارفضه إن اختلف الجسم.
• افشل مغلقًا حين يوجد إيصال وتتعذر قراءته.
• دع الهاتف يرسل الوقائع، كقراءة العداد، ودع الخادم يحسب كل مبلغ.
• أعطِ الآثار الجانبية مفاتيحها الخاصة، مثل invoice:<id>:issued:v1.
• احفظ الأرصدة في سجل مالي للإضافة فقط، ولا تجمع إجماليات الفواتير أبدًا.
• ترجم كل قيد تفرّد إلى 4xx، فرموز الحالة هي سياسة إعادة المحاولة.
• انقل القيود المتأخرة إلى الفترة المفتوحة، واترك المقفلة مقفلة.

الشبكة ستظل تنقطع، والهواتف ستظل تعيد الإرسال. والرصيد يجب أن يبقى صحيحًا رغم ذلك، والرفض يجب أن يبقى رفضًا.

وهكذا أبني تطبيقات الجوال التي يجب أن تعمل دون اتصال.

لذلك لا شيء هنا يعتمد على أن أتذكّره.

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

وفي الطريق ثلاثة فخاخ: إعداد في PostgreSQL يعود سلسلة فارغة، وترويسة يستطيع أي أحد تزويرها لو انضمت حاوية واحدة إلى الشبكة الخطأ، وقيمة افتراضية لإعادة المحاولة تجعل نسخة تالفة تحتجز اختبارها ساعات.

الطبقة 1: صفوف ترفض المحطة الخطأ

الحد المعتاد بين المستأجرين شرط WHERE يتكرر في كل استعلام. يصمد حتى يأتي استعلام كُتب على عجل فيُسقطه، والخطأ عندها صامت: الصفحة تعمل، لكنها تعرض أكثر مما ينبغي.

FinyxWatt تنقل الحد إلى داخل قاعدة البيانات. أمان الصفوف مفعّل ومُجبَر على 88 جدولًا من أصل 94 في ترحيلاتها (migrations). الجداول الستة الباقية تحمل قائمة الصلاحيات، وبيانات المخطط، وسجلات استيراد جرى مرة واحدة. وكل سياسة (policy) تتحقق من محطة الصف، ومن أن المستخدم عضو نشط فيها:

ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;
ALTER TABLE invoices FORCE ROW LEVEL SECURITY;

CREATE POLICY tenant_scope_api ON invoices FOR ALL TO platform_api
  USING (
    tenant_id = app_private.current_tenant_id()
    AND EXISTS (
      SELECT 1 FROM tenant_memberships m
      WHERE m.tenant_id   = app_private.current_tenant_id()
        AND m.identity_id = app_private.current_identity_id()
        AND m.status = 'active'
    )
  )
  WITH CHECK ( /* الشرط نفسه */ );

الترحيل الذي أضاف شرط العضوية يبدأ بسببه: "خطأ برمجي في المستقبل يجب ألا يحوّل هوية متحققًا منها من المستأجر A إلى المستأجر B لمجرد ضبط خاطئ لإعداد المعاملة". معرّف محطة خاطئ لن يجد عضوية نشطة، فيعود الاستعلام فارغًا.

ويضبط الـ API القيمتين في بداية كل معاملة (transaction)، من الرمز الذي تحقق منه:

async withTenant<T>(tenantId: string, identityId: string, callback: (trx: Transaction<Database>) => Promise<T>) {
  return this.db.transaction().execute(async (trx) => {
    await sql`select set_config('app.tenant_id', ${tenantId}, true)`.execute(trx)
    await sql`select set_config('app.identity_id', ${identityId}, true)`.execute(trx)
    return callback(trx)
  })
}

ثلاث تفاصيل تقرر هل ينجح هذا كله.

الـ true الأخيرة تحصر الإعداد في المعاملة. أما SET العادية فتبقى على الاتصال، فيسلّمه الـ pool إلى الطلب التالي وهو ما زال يشير إلى المحطة A.

السلسلة الفارغة هي الفخ الأول. على اتصال جديد، الإعداد الذي لم يُعرَّف قط يُقرأ NULL. أما على اتصال من الـ pool خدم طلبًا من قبل، فيُقرأ ''، و''::uuid يرمي خطأ. والدالة التي تستدعيها كل سياسة تعالج الحالتين:

CREATE FUNCTION app_private.current_tenant_id() RETURNS uuid
LANGUAGE sql STABLE PARALLEL SAFE AS $function$
  SELECT nullif(current_setting('app.tenant_id', true), '')::uuid;
$function$;

وNULL لا يساوي شيئًا، فالطلب الذي يصل بلا سياق يرى صفر صفوف. يفشل مغلقًا (fail closed).

FORCE مهم لأن مالك الجدول يتخطى سياساته افتراضيًا، والمستخدم الخارق وأدوار BYPASSRLS تتخطاها دائمًا. وهذه مهمة الطبقة الثانية.

ويطبّق الـ CI كل الترحيلات على PostgreSQL جديدة، ويشغّل اختبارات SQL هجومية بدور الـ API نفسه. هذا قلب واحد منها، جاهز للنسخ:

SET ROLE platform_api;
SET LOCAL app.tenant_id   = '<station A>';
SET LOCAL app.identity_id = '<an active member of station A>';

DO $test$
BEGIN
  IF (SELECT count(*) FROM customers) <> 1 THEN
    RAISE EXCEPTION 'RLS expected one station-A customer';
  END IF;

  BEGIN
    INSERT INTO customers (tenant_id, subscriber_number, display_name)
    VALUES ('<station B>', 'ILLEGAL', 'Cross-tenant write');
    RAISE EXCEPTION 'RLS accepted a cross-tenant write';
  EXCEPTION WHEN insufficient_privilege THEN NULL;
  END;
END $test$;

كل هذا يفترض أن الـ API يتصل بدور تنطبق عليه السياسات.

الطبقة 2: حسابات لا تستطيع إطفاءه

اتصل بصفة المالك دون FORCE، أو بمستخدم خارق، أو بدور BYPASSRLS، وتصير كل السياسات السابقة زينة.

قاعدة FinyxWatt تنشئ حساباتها عند أول تشغيل، "قبل أن يُسمح لصورة الـ API بالاتصال أصلًا"، بتعبير السكربت. مختصرًا، والسكربت الحقيقي يأخذ الأسماء من البيئة وكلمات المرور من ملفات سرية:

CREATE ROLE migrator  LOGIN NOSUPERUSER NOCREATEDB CREATEROLE   NOREPLICATION NOBYPASSRLS;
CREATE ROLE api_login LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;

ALTER DATABASE app OWNER TO migrator;
REVOKE CONNECT ON DATABASE app FROM PUBLIC;
GRANT  CONNECT ON DATABASE app TO migrator, api_login;

GRANT platform_api TO api_login;   -- الدور الذي كُتبت له كل السياسات

حساب الترحيل وحده يملك المخطط. لا يحمل أي حساب تشغيل كلمة مرور الترحيل، والـ API يعمل بـ RUN_MIGRATIONS: "false". وخمسة أدوار تشغيل تتقاسم العمل:

والدفتر وسجل التدقيق يرفضان التعديل مرتين:

GRANT SELECT, INSERT ON ledger_entries TO platform_api;   -- لا UPDATE ولا DELETE

CREATE FUNCTION app_private.prevent_ledger_mutation() RETURNS trigger
LANGUAGE plpgsql SECURITY INVOKER SET search_path = pg_catalog, public AS $function$
BEGIN
  RAISE EXCEPTION 'ledger entries are append-only; post a reversal entry instead'
    USING ERRCODE = 'integrity_constraint_violation';
END;
$function$;

CREATE TRIGGER ledger_entries_append_only
BEFORE UPDATE OR DELETE ON ledger_entries
FOR EACH ROW EXECUTE FUNCTION app_private.prevent_ledger_mutation();

قد يوسّع ترحيل لاحق صلاحية بالخطأ. يبقى الـ trigger رافضًا، ورسالته تخبر المطوّر التالي بما يفعله بدلًا من ذلك: القيود للإضافة فقط، والتصحيح يكون بقيد عكسي.

-- حسابات تتخطى أمان الصفوف
SELECT rolname FROM pg_roles
WHERE rolcanlogin AND (rolsuper OR rolbypassrls);

-- جداول ليس عليها أمان صفوف مفعّل ومُجبَر معًا
SELECT relname FROM pg_class
WHERE relkind = 'r' AND relnamespace = 'public'::regnamespace
  AND NOT (relrowsecurity AND relforcerowsecurity);

الأدوار تحدد ما يحق للحساب فعله. أما المحطة التي يعمل باسمها فتأتي من رمز.

الطبقة 3: API لا يصدّق إلا ما تحقق منه

تسجّل FinyxWatt دخول المستخدمين عبر Keycloak. والـ API يتحقق من توقيع كل رمز، ومُصدِره، والجهة الموجَّه إليها، وصلاحيته الزمنية، مقابل المفاتيح التي ينشرها Keycloak:

this.jwks ??= createRemoteJWKSet(new URL(this.config.keycloakJwksUri))
const { payload } = await jwtVerify(token, this.jwks, {
  issuer: this.config.keycloakIssuer,
  audience: this.config.keycloakAudience,
})

ثم يقرأ الـ claim المتحقَّق منه azp ليعرف أي تطبيق حصل على الرمز. والتعليق فوق هذا الفحص هو درس الطبقة كله: "لا تقبل أبدًا ترويسة تحدد نوع التطبيق: يستطيع المتصل تزويرها ليلتفّ برمز أندرويد على مسار لا يقبل إلا الـ cookies".

والمحطة تتبع القاعدة نفسها. الـ API لا يقبل إلا عضويات الهوية المتحقق منها، ثم يعيد قراءة العضوية تحت RLS. والجلسات قصيرة، ورموزها لمرة واحدة:

"accessTokenLifespan": 300,
"revokeRefreshToken": true,
"refreshTokenMaxReuse": 0,
"bruteForceProtected": true,
"failureFactor": 5

رمز الوصول يعيش خمس دقائق. ورمز التحديث يعمل مرة واحدة، فالنسخة المسروقة منه تُستهلك لحظة يستخدمه أي من الطرفين. وخمس كلمات مرور خاطئة تجعل الحساب ينتظر.

حتى الآن كان المهاجم خطأً في كودي أنا. الطبقات التالية تفترض أنه صار داخل حاوية.

الطبقة 4: حاويات لا تكاد تستطيع شيئًا

يعمل هذا الموقع في حاوية Caddy واحدة، تعريفها هكذا:

web:
  image: caddy:2.10.2-alpine
  ports: ['80:80', '443:443', '443:443/udp']
  volumes:
    - ./Caddyfile:/etc/caddy/Caddyfile:ro
    - /srv/moghalis:/srv/moghalis:ro
    - caddy_data:/data
    - caddy_config:/config
  read_only: true
  tmpfs: [/tmp]
  cap_drop: [ALL]
  cap_add: [NET_BIND_SERVICE]
  security_opt: [no-new-privileges:true]
  mem_limit: 128m

لا شيء يُكتب خارج /tmp ووحدتي تخزين الشهادات، وكل صلاحيات Linux مسحوبة إلا ربط المنافذ المنخفضة، ولا عملية تستطيع رفع صلاحياتها، والذاكرة تقف عند 128 ميغابايت.

وFinyxWatt تشغّل عشرين خدمة، كلها بـ no-new-privileges، وبوابتها Caddy للقراءة فقط وبلا أي صلاحيات. والحماية الأقوى هي خريطة الشبكات:

networks:
  edge:
  application:   { internal: true }
  database:      { internal: true }
  observability: { internal: true }
  sms_gateway:   { internal: true }
  egress:

الشبكة internal لا طريق منها إلى الخارج، وكل خدمة لا تنضم إلا إلى ما تحتاجه:

البوابة لا طريق لها إلى قاعدة البيانات، وخدمات الصفوف الثلاثة الأخيرة لا طريق لها إلى الإنترنت.

تحتاج FinyxWatt في الإنتاج إلى 28 سرًا. كل سر ملف مستقل بقيمة عشوائية خاصة به، يُركَّب سرًّا من أسرار Docker في الحاويات التي تحتاجه فقط:

api:
  environment:
    DB_USER: ${PLATFORM_API_USER}
    DB_PASSWORD_FILE: /run/secrets/platform_api_password
  secrets:
    - platform_api_password

ودليل الأسرار يختصر القاعدة في جملة: "لا تضع الأسرار في وسائط سطر الأوامر، ولا في ملفات .env، ولا في سجل الطرفية، ولا في صور الحاويات، ولا في نظام إدارة الكود". متغير البيئة يظهر في docker inspect، أما الملف تحت /run/secrets فلا يوجد إلا حيث رُكِّب.

الطبقة 5: بوابة تجيب أقل

Caddy على خادم هذا الموقع يجدّد شهادات HTTPS، ويضيف هذه الترويسات إلى كل رد:

header {
	Strict-Transport-Security "max-age=31536000; includeSubDomains"
	X-Content-Type-Options "nosniff"
	X-Frame-Options "SAMEORIGIN"
	Referrer-Policy "strict-origin-when-cross-origin"
	Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=()"
	-Server
}

وبوابة FinyxWatt تغلق أيضًا كل ما لا تخدمه:

{
	admin off
}

(restricted_console) {
	@outside_trusted_networks not remote_ip {$ADMIN_TRUSTED_CIDRS}
	respond @outside_trusted_networks 403
	basic_auth {
		{$OBSERVABILITY_USER} {$OBSERVABILITY_PASSWORD_HASH}
	}
}

admin off يطفئ واجهة الإدارة الخاصة بـ Caddy نفسه. ولوحات المراقبة لا تجيب إلا من شبكات موثوقة، ثم تطلب كلمة مرور لا يحفظ الخادم منها إلا تجزئة bcrypt. والمسار /metrics يعيد 404 من الإنترنت، ومسار تسجيل الهواتف العام لا يقبل أكثر من 32 كيلوبايت، لأنه لا يستقبل ملفًا أبدًا. وكل ترويسة أمان تأتي من مكان واحد: الـ API يضع X-Frame-Options بنفسه، فتتركها كتلة الـ API في Caddy.

أما أمتع مهام البوابة فهي فحص جواز سفر كل هاتف يرسل الفواتير.

جواز سفر لكل هاتف

ترسل FinyxWatt فاتورة كل عميل برسالة قصيرة من هواتف أندرويد مخصصة في المحطة. والهاتف الذي يرسل باسم محطة يحتاج أكثر من كلمة مرور، فيحصل على شهادة عميل (client certificate).

قاعدة البيانات لا تحفظ إلا HMAC للرمز، مصنوعًا بقيمة سرية (pepper)، والمخطط نفسه يفرض الحدود:

-- HMAC-SHA-256(code-id || secret), never the raw enrollment code.
code_digest  bytea NOT NULL CHECK (octet_length(code_digest) = 32),
expires_at   timestamptz NOT NULL,
max_attempts smallint NOT NULL DEFAULT 5 CHECK (max_attempts BETWEEN 1 AND 10),
attempts     smallint NOT NULL DEFAULT 0 CHECK (attempts BETWEEN 0 AND 10),
CONSTRAINT sms_device_enrollment_codes_attempts_bound CHECK (attempts <= max_attempts),
CONSTRAINT sms_device_enrollment_codes_expiry CHECK (expires_at > created_at)

والاعتماد يمر عبر الـ API الرئيسي، الذي يرفض منشئ الرمز بالخطأ SMS_ENROLLMENT_SELF_APPROVAL_FORBIDDEN، ويربط شهادة من جهة إصدار خاصة يطابق مفتاحها العام المفتاحَ الذي أثبت الهاتف امتلاكه. ومن بعدها:

tls {
	client_auth {
		mode require_and_verify
		trust_pool file /run/secrets/sms_device_ca_pem
	}
}
reverse_proxy sms-gateway:8081 {
	header_up X-Verified-Client-Certificate-Fingerprint {tls_client_fingerprint}
}

وهنا الفخ الثاني. بوابة الرسائل تصدّق ترويسة البصمة دون سؤال، وهذا آمن لسبب واحد: البوابة تقع على شبكة داخلية لا ينضم إليها إلا Caddy، وCaddy يكتب الترويسة فوق أي قيمة سابقة بعد أن يتحقق من الشهادة. وكود البوابة نفسه يشرح كيف يُكسر هذا: "لا تنشر منفذ حاوية البوابة، ولا تضف حاويات عشوائية إلى تلك الشبكة؛ أيٌّ منهما يجعل هذه الترويسة قابلة للتزوير". سطر ports: واحد يُضاف لتجربة سريعة، ويصير بوسع أي أحد أن يرسل الترويسة بنفسه.

والـ proxy يخفي فخًا آخر. كل طلب يصل إلى البوابة بعنوان Caddy، فحدّ الطلبات لكل IP سيعطي الهواتف كلها ميزانية واحدة مشتركة. لذلك تبني البوابة حدّها على الشهادة المتحقق منها:

await app.register(fastifyRateLimit, {
  max: 120,
  timeWindow: '1 minute',
  keyGenerator: (request) => {
    const fingerprint = request.headers['x-verified-client-certificate-fingerprint']
    const normalized = typeof fingerprint === 'string' ? fingerprint.trim().toLowerCase().replaceAll(':', '') : ''
    return /^[0-9a-f]{64}$/.test(normalized) ? `device:${normalized}` : `addr:${request.ip}`
  },
})

والمفتاح الخاص لجهة الإصدار يبقى خارج الاتصال، وشهادة كل هاتف تُلغى حين يُلغى جهازه.

الطبقة 6: خادم لا يغلق الباب في وجهك

جُهّز خادم هذا الموقع بسكربت واحد، والجزء الخاص بـ SSH فيه حريص على الترتيب:

if [ -s "/home/$USER_NAME/.ssh/authorized_keys" ]; then
  cat >/etc/ssh/sshd_config.d/10-moghalis.conf <<'EOF'
PermitRootLogin no
PasswordAuthentication no
KbdInteractiveAuthentication no
EOF
  sshd -t && systemctl reload ssh
else
  echo "!! No SSH key for $USER_NAME yet: password login left ON."
fi

ufw default deny incoming
ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 443/udp
ufw --force enable

الدخول بكلمة المرور لا يُطفأ إلا إن وُجد مفتاح، وSSH لا يُعاد تحميله إلا إن قبل sshd -t الإعداد، والجدار الناري يسمح بـ SSH قبل أن يُرفع. اعكس أيًّا من الثلاثة على VPS جديد، وستكون محطتك التالية شاشة الإنقاذ عند مزوّد الخادم.

ست طبقات، كل واحدة تفترض أن التي فوقها تسقط. والنسخة الاحتياطية تفترض أنها سقطت كلها.

بجانب الطبقات: نسخة احتياطية تثبت أنها تُستعاد

تؤرشف PostgreSQL في FinyxWatt سجل الكتابة المسبق (WAL) كل خمس دقائق على الأقل، وتأخذ نسخة أساسية كاملة كل ليلة عبر WAL-G، وإصدار WAL-G نفسه مثبّت ومتحقق من بصمته. كل ملف يُضغط ويُشفَّر قبل أن يُكتب. وجهاز مكتب المالك يسحب الملفات الجديدة كل أربع ساعات ويحتفظ بخمسة وأربعين يومًا منها.

مفتاح التشفير هو النسخة الاحتياطية نفسها: إن ضاع صار كل ملف ضجيجًا. لذلك هو مختوم مع بقية أسرار الخادم في ملف محمي بكلمة سر، على ذاكرة USB وفي مكان ثانٍ، وكلمة السر محفوظة بعيدًا عنهما.

ولا شيء من ذلك يثبت شيئًا حتى تنجح استعادة. كل يوم جمعة يستعيد سكربت أحدث نسخة أساسية وكل سجل مؤرشف بعدها في وحدة تخزين مؤقتة. مختصرًا:

timeout --kill-after=60 2700 docker run --rm --network none --name "$name" \
  -e PITR_STORAGE_MODE=local -e WALG_DOWNLOAD_FILE_RETRIES=2 \
  -v "$name:/restore" \
  -v "$repository:/local-pitr:ro" \
  -v "$key:/run/secrets/pitr_encryption_key:ro" \
  --entrypoint bash "$image" /restore-check.sh

وفي الداخل، تُضاف هذه الأسطر إلى إعداد النسخة قبل أن تبدأ PostgreSQL:

cat >> /restore/data/postgresql.auto.conf <<'CONF'
restore_command = '/usr/local/bin/pitr-walg wal-fetch %f %p'
archive_mode = off
listen_addresses = ''
CONF
touch /restore/data/recovery.signal

كل سطر حارس. بلا شبكة، فلا تلمس النسخة قاعدة البيانات الحية. والمستودع والمفتاح للقراءة فقط. لا أرشفة، ولا منفذ يستمع. و$image يُقرأ من حاوية قاعدة البيانات الحية، فيستعيد الفحص بالصورة نفسها التي يعمل بها الإنتاج. وحين تنتهي الاستعادة، يعدّ ما عاد:

SELECT json_build_object(
  'migrations',   (SELECT count(*) FROM schema_migrations),
  'stations',     (SELECT count(*) FROM tenants),
  'customers',    (SELECT count(*) FROM customers),
  'bills',        (SELECT count(*) FROM invoices),
  'receipts',     (SELECT count(*) FROM payments),
  'newestChange', (SELECT max(changed_at) FROM change_log));

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

والآن الفخ الثالث، وسبب WALG_DOWNLOAD_FILE_RETRIES=2. يعيد WAL-G محاولة الملف الذي يتعذر عليه قراءته 15 مرة، تفصل بينها دقائق. وجّهه إلى نسخة تالفة أو لا يمكن فك تشفيرها، ولن يفشل الفحص. سينتظر، لساعات. محاولتان وسقف 45 دقيقة يحوّلان هذا الانتظار إلى فشل واضح مع سببه.

ومراقب يعمل كل عشر دقائق ويبلّغ عما يكسر النسخ الاحتياطية بصمت: قرص امتلأ 85%، وخدمة توقفت، ونسخة كاملة أقدم من 26 ساعة، وأرشفة WAL متعثرة، وجهاز مكتب لم يسحب النسخ منذ ثلاثة أيام، وشهادة أمان تقترب من انتهائها.

البوابة أمام كل إصدار

الطبقات تحمي النظام وهو يعمل. والبوابة تحميه من الإصدار القادم.

فحصٌ للمستودع يُفشل البناء عند وجود مفاتيح خاصة، أو رموز وصول، أو رموز JWT، أو رابط قاعدة بيانات فيه كلمة مرور، أو بريد إلكتروني أو رقم هاتف حقيقي، أو أي ملف .env أو secrets/ متتبَّع:

['private key material', /-----BEGIN(?: [A-Z]+)? PRIVATE KEY-----/],
['GitHub access token', /\bgh[pousr]_[A-Za-z0-9_]{30,}\b/],
['database URI with embedded password', /\bpostgres(?:ql)?:\/\/[^\s:@/${]+:[^\s@/${]{8,}@/i],

وهو يجمع الملفات بـ git ls-files --cached --others --exclude-standard، فإن شغّلته محليًا التقط الملف قبل أن تضيفه إلى Git.

ثم يشغّل الـ CI كل الترحيلات على PostgreSQL جديدة مع اختبارات عزل المحطات، واختبارات الخلفية، واختبارات التكامل بدور قاعدة البيانات المقيّد، وnpm audit --omit=dev --audit-level=high. والنشر التلقائي ينتظر ذلك كله:

on:
  workflow_run:
    workflows: [Independent Platform CI]
    types: [completed]
    branches: [main]

concurrency:
  group: production-deploy
  cancel-in-progress: false

jobs:
  deploy:
    if: github.event.workflow_run.conclusion == 'success'
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.workflow_run.head_sha }}

في هذه الأسطر ثلاثة فخاخ. workflow_run ينطلق حين يكتمل الـ CI، نجح أو فشل، فبدون شرط if ينشر البناء الأحمر. وسحب main بدل head_sha قد ينشر commit لم يختبره الـ CI قط. والنشر الذي يُلغى في منتصفه يترك خادمًا نصف مُرحَّل. والـ job يثبّت بصمة مفتاح الخادم قبل أول أمر SSH.

هاجم نظامك بنفسك، على الورق

مراجعة مكتوبة هاجمت FinyxWatt عبر كودها وبطلبات سلبية لا تغيّر شيئًا على الخوادم الحية، وسجّلت كل نتيجة مع الملف الذي يثبتها:

قائمة الفحص

• أمان الصفوف مُجبَر على كل جدول للمستأجرين، وسياساته تتحقق من عضوية نشطة.
• سياق المستأجر لكل معاملة بـ set_config(..., true)، من الرمز، ويُقرأ عبر nullif.
• لا حساب تطبيق هو المالك أو مستخدم خارق أو BYPASSRLS، وحساب لكل مهمة.
• جداول الدفتر والتدقيق بلا صلاحيات UPDATE أو DELETE، ومعها trigger يرفضهما.
• الأسرار ملفات تُركَّب حيث يلزم فقط، والـ CI يفشل عند المفاتيح والرموز وملفات .env المتتبَّعة.
• حاويات للقراءة فقط، بلا صلاحيات، بحد للذاكرة، على شبكات داخلية.
• ترويسات الهوية لا تُصدَّق إلا على شبكة مغلقة، وحدود الطلبات مبنية على تلك الهوية.
• نسخ احتياطية مشفرة، ومفتاحها بعيد عنها، ونسخة خارج الخادم، وفحص استعادة بحد زمني وتنبيه.
• لا نشر إلا بعد CI أخضر، ومن الـ commit المختبَر، ولا إلغاء في المنتصف.

لا طبقة من هذه ذكية وحدها. القوة في الافتراض الذي تحتها كلها: الطبقة التي فوقك سقطت بالفعل، وعليك أن تصمد مع ذلك. اكتب هذا الافتراض في إعداداتك، ويصير اليوم الذي تسقط فيه إحداها يومًا عاديًا.

وإن كنت تفضّل أن يتولى أحد هذا كله لنظامك، فهذا ما تغطيه الاستضافة والدعم.

بعض أصحاب المنشآت الذين يراسلونني عاشوا هذا الأسبوع من الجهة الأخرى. دفعوا ثمن برنامج ولم يستلموه في حال يستطيع موظفوهم العمل عليها.

أدير مشاريعي بحيث لا يأتي هذا الأسبوع أبدًا. وهذه الطريقة، مكتوبة للمطوّرين والمستقلين. حين تنتهي سيكون بين يديك هيكل عرض يحسم أغلب الخلافات قبل أن تبدأ، ودورة مراحل تضع برنامجًا يعمل على خادم العميل منذ المرحلة الأولى، وطريقة تجعل اختباراتك جزءًا مما يشتريه العميل، وحزمة تسليم، والأسئلة التي يطرحها العملاء الجيدون، مجابًا عنها كتابةً قبل أن يسألوها.

وفي ما يلي شيئان يعملان أكثر من غيرهما: قسم في العرض يمنع من الخلافات أكثر من أي قسم آخر، وسطر في الشروط يجعل الدفعة الأخيرة هي الأسهل.

المكالمة الأولى مقابلة متطلبات

وصف قصير يكفي للبداية: ماذا تعمل المنشأة، ومن سيستخدم النظام، وما الذي لا يعمل اليوم. ونموذج التواصل في موقعي يسأل أيضًا عن نوع المشروع والميزانية التقريبية، و"لم أحدد بعد" واحدة من الإجابات.

بعدها أرسم صورة العمل. ثلاثة أسئلة تحمل معظم الوزن:

• من يستخدم النظام؟ الاستقبال، والمحاسبون، ومديرو الفروع، والسائقون، والعملاء.
• ما البيانات المهمة؟ الفواتير، والمخزون، وملفات المرضى، والقراءات، والصناديق.
• من يحق له فعل ماذا؟ من يلغي الفاتورة، ومن يرى سعر التكلفة، ومن يعتمد الاسترجاع.

السؤال الثالث يحدد من التصميم أكثر مما تحدده أي شاشة. في منصة لإدارة شبكات الإنترنت بنيتها، صارت الإجابة 49 صلاحية منفصلة موزعة على أربعة أدوار. وفي منصة طلبات لتاجر ملابس، كانت القاعدة الأساسية ألا يرى العميل سعر فئة غير فئته، وهذه القاعدة تُفرض داخل قاعدة البيانات نفسها، ولها اختباراتها.

ثم اطلب أن ترى الأدوات التي يعملون بها اليوم: الجدول المشترك، والنموذج الورقي، والبرنامج القديم. هي تُظهر سير العمل الحقيقي أفضل من وصف أي أحد له.

العرض: ستة أقسام، وواحد منها يمنع الخلاف

لا يُبنى شيء قبل أن يحمل العميل عرضًا مكتوبًا. وعروضي تسير على هيكل واحد:

القسم الذي يمنع من الخلافات أكثر من أي قسم آخر هو قائمة "ما لا يشمله العرض". رسوم الخادم والنطاق، وحساب واتساب للأعمال، ورسوم متجري التطبيقات: كلها تُدفع لشركات أخرى. حين تُكتب قبل أن يوقّع العميل، لا يمكن أن يصله أي منها لاحقًا مفاجأةً تحمل اسمك.

وقائمة "ما يشمله" لها وزنها أيضًا. في نموذجي تقول: التصميم، والبرمجة، والاختبارات الآلية، والنشر على خادم العميل، وتدريب فريق الاستقبال، ومدة دعم بعد التسليم الأخير. الاختبارات الآلية بند يقرؤه العميل بعينه، وسيهمّنا هذا لاحقًا.

لكل مرحلة تكلفتها، ونموذجي يربط كل دفعة ببداية مرحلتها. فلا يدفع العميل أبدًا أكثر من مرحلة واحدة قبل برنامج استخدمه بنفسه، ولا تعمل أنت أبدًا أكثر من مرحلة واحدة قبل المال.

صفحة خاصة برابط لا يُخمَّن

يصل العرض إلى العميل صفحةً في موقعي، بالعربية أو الإنجليزية، برقم مرجعي وتاريخ تنتهي عنده صلاحيته. ولا شيء في الموقع يشير إليها. وإن بنيت مثلها، فثلاث قواعد من نظام البناء عندي تستحق النسخ.

اسم الملف هو الرابط، لذلك يرفض البناء أي اسم لا ينتهي بذيل عشوائي من ستة أحرف على الأقل:

const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*-[a-z0-9]{6,}$/

والتوليد المسبق (prerender) يتوقف إن لم تكن صفحة العرض noindex. والعروض تبقى خارج الـ sitemap، وملف robots.txt يمنع مساراتها، وقائمة العروض لا تُضمَّن أبدًا في ما يصل إلى المتصفح.

والخادم يُبعد محركات البحث، ويُخفي الرابط من ترويسة المُحيل (referrer) حين ينقر العميل على رابط خارجي:

@proposals path /p/* /ar/p/*
header @proposals {
	X-Robots-Tag "noindex, nofollow, noarchive"
	Referrer-Policy "no-referrer"
}

التصميم وتغيير الرأي ما زال بدقائق

قبل الكود نتفق على أربعة أشياء: البيانات التي يحفظها النظام، والصلاحيات، والربط مع الأنظمة الأخرى، والشاشات الرئيسية.

هذه أرخص لحظة لأي أحد كي يغيّر رأيه. نقل حقل في رسم أولي يأخذ دقائق. أما تغيير طريقة حفظ البيانات بعد أن يعمل النظام فهندسة حقيقية: حين نقلت FinyxWatt، منصتي لمحطات الكهرباء والمياه، من Firebase إلى PostgreSQL، احتاج ذلك 107 ترحيلات مرتبة ومتحقق منها، والمحطات تعمل طوال الوقت.

كل مرحلة تنتهي وهي تعمل على خادم العميل

يُقسَّم العمل إلى مراحل، وكل مرحلة مفيدة بذاتها. في نموذج العرض الذي أستخدمه، يُقسَّم نظام لمجمع طبي هكذا:

كل مرحلة تنتهي بنسخة تعمل على خادم العميل، أو على الاستضافة التي يسمّيها العرض، ويختبرها فريقه قبل أن تبدأ المرحلة التالية. وداخل المرحلة أعمل بدورات قصيرة، ببرنامج يعمل، واختبارات، وبيئة تجريبية (staging).

هذا الترتيب يحمي الطرفين. يرى العميل برنامجًا يعمل منذ المرحلة الأولى. ويكتشف موظفوه المشكلات التي تهمهم وإصلاحها ما زال رخيصًا. وإن تغيّرت أولوياته، تغيرت المرحلة التالية معها. وكل دفعة بعد الأولى تأتي بعد برنامج استخدمه العميل بنفسه.

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

CURRENT=$(readlink -f "$ROOT/current")
PREVIOUS=$(ls -1dt "$ROOT"/releases/*/ | sed 's:/$::' | grep -vx "$CURRENT" | head -n 1 || true)
[ -n "$PREVIOUS" ] || { echo "!! No earlier release to go back to."; exit 1; }
ln -sfn "$PREVIOUS" "$ROOT/current.new"
mv -Tf "$ROOT/current.new" "$ROOT/current"

يستغرق أقل من ثانية. وحين يكون الرجوع بهذا الثمن، يكفّ وضع مرحلة على خادم العميل عن أن يكون مقامرة.

الاختبارات جزء مما يشتريه العميل

الاختبار الآلي برنامج صغير يتحقق من قاعدة واحدة من قواعد العمل، في كل مرة يتغير فيها الكود. كتبت منها أكثر من أربعة آلاف عبر عشرين منتجًا.

من السهل أن تُعامَل الاختبارات تكلفةً مخفية داخل التقدير. في نموذجي هي في قائمة "ما يشمله العرض"، حيث يقرؤها العميل. والحيلة أن تصف كل اختبار بلغة العميل.

في FinyX-ERP، نظامي للمحاسبة ونقاط البيع، يستطيع المالك حذف فاتورة مرحَّلة عبر أداة إدارية. ومجموعة من الاختبارات تتحقق من أن الحذف يقع، ومن أن الحمايات التي تمنع أي أحد من تعديل مبلغ مرحَّل تعود للعمل بعده، ومن أنها تعود حتى حين يتعثر الحذف في منتصفه. والتعليق في رأس الملف يشرح ما على المحك: المالك طلب الحذف، فالحذف سليم. الخطر دفتر يبقى بلا حراس، بصمت، حتى يعدّل أحدهم مبلغًا مرحَّلًا.

وأول فحص فيه يستحق أن يُنسخ إلى كل مجموعة اختبارات:

Require(before > 0, "The database carries no integrity triggers, so the test proves nothing.");

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

وفي المشاريع الأكبر تعمل الاختبارات قبل خروج أي إصدار. في FinyxWatt تعمل اختبارات التطبيقات مع كل push وكل طلب دمج، ولا يبدأ النشر التلقائي للخادم إلا بعد أن تنجح اختبارات الخادم في الـ CI. وفي متجر بن مسعود يمر كل تغيير في الخلفية عبر فحص جودة الكود، وفحص الأنواع، واختبارات الوحدات مع قياس التغطية، وترحيلات قاعدة البيانات، واختبارات شاملة من طرف إلى طرف.

تقرير القبول

واختبار العميل نفسه يأتي فوق ذلك، ويستحق وثيقة. في منصة إدارة شبكات الإنترنت، جاءت النسخة المرشحة للإطلاق مع تقرير قبول مكتوب:

الصفّان الأخيران يبنيان من الثقة أكثر من بقية الصفوف كلها. المطوّر الذي يكتب حدوده بيده يُصدَّق في كل ما عداها.

حزمة التسليم

والآن السطر الذي في الشروط. نموذجي يقول إن الكود المصدري ملك العميل بعد سداد الدفعة الأخيرة. وحين تحين تلك اللحظة، يكون فريقه قد استخدم كل مرحلة على خادمه هو، فالدفعة الأخيرة تنقل ملكية نظام يشغّله بالفعل. هي أسهل دفعة تطلبها، لأنه لا شيء فيها يُؤخذ على الثقة.

وهذا ما يستلمه:

قائمتا التوثيق والسكربتات هما ما يضمه مستودع منصة إدارة شبكات الإنترنت. واختبار الحزمة بسيط: هل يستطيع المطوّر التالي تشغيل النظام دون أن يتصل بك؟ العميل الذي يعرف أنه يستطيع الرحيل هو العميل الذي يملك ترف أن يثق بك.

التعديلات على النطاق، كتابةً، في كل مرة

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

والمراحل تسهّل الأمر. يمكن تقدير التعديل ووضعه في المرحلة التالية، وحين تتبدل الأولويات تتبدل المرحلة التالية معها. والتعديل المكتوب يحتاج خمسة أشياء: ما الذي يتغير، ولماذا، والتقدير، والمرحلة التي يدخلها، واعتماد العميل.

الدعم بعد الإطلاق

الاستخدام الحقيقي يكشف دائمًا ما لم تكشفه الاختبارات. النشر والنسخ الاحتياطي والمراقبة وتلك الإصلاحات جزء من العمل، ومدة الدعم بعد التسليم الأخير مكتوبة في العرض. أدير اليوم سبعة أنظمة تعمل: إصداراتها، وخوادمها، وأمانها، والإصلاحات التي تبقيها قائمة.

ما الذي يحرّك التقدير

لا أعطي سعرًا قبل المحادثة الأولى، لأن الكلمات نفسها تصف أنظمة مختلفة جدًا. هذه أكثر ما يحرّك التقدير:

• الأدوار والصلاحيات. دوران بصلاحيات كاملة نظام صغير. أدوار كثيرة بقواعد لكل فرع نظام أكبر.
• الربط مع الأنظمة الأخرى. بوابات الدفع مثل Moyasar، وواتساب، وسلة، والرسائل القصيرة. لكلٍّ منها قواعده وبيئة اختباره وخطوات اعتماده.
• المنصات. ويب فقط، أم معه أندرويد وiOS وبرنامج سطح مكتب على Windows.
• العمل دون اتصال. التطبيق الذي يستمر في العمل دون إنترنت يحتاج طريقة آمنة للمزامنة حين يعود الاتصال.
• البيانات الحالية. نقل سنوات من الجداول أو من قاعدة بيانات قديمة مهمة قائمة بذاتها.
• التقارير. كل تقرير استعلام وشاشة وتصدير.
• التشغيل. النسخ الاحتياطي، والمراقبة، ومن يتولى الخادم.

والمراحل تفيد هنا أيضًا. يمكن أن تُحجَّم المرحلة الأولى على قدر ميزانية العميل، وتبقى مفيدة بذاتها.

الأسئلة التي يطرحها العملاء الجيدون

العملاء الجيدون يطرحون هذه الأسئلة قبل التوقيع. ضع كل إجابة في العرض، ولن تضطر إلى قول أي منها في خلاف.

• هل سيصلني عرض مكتوب بمراحل، وبقائمة لما لا يشمله؟
• أين سيعمل النظام، وباسم من الخادم والنطاق؟
• هل سأختبر كل مرحلة على خادمي قبل أن تبدأ التالية؟
• لمن الكود المصدري، ومن متى؟
• كم عدد الاختبارات الآلية، وهل تعمل قبل كل إصدار؟
• كيف تُؤخذ النسخ الاحتياطية، ومتى جُرّبت الاستعادة آخر مرة؟
• ما التوثيق الذي سأستلمه عند التسليم؟
• كيف تُسعَّر التعديلات خارج النطاق، وكيف تُعتمد؟
• إن فشل إصدار، كيف يُتراجع عنه، وكم يستغرق ذلك؟
• بعد الإطلاق، من يصلح المشكلات، وإلى متى؟

الدفعة الأخيرة سهلة حين لا يكون فيها شيء جديد. العميل استخدم كل مرحلة على خادمه، وقرأ قائمة ما لا يشمله العرض قبل التوقيع، واعتمد كل تعديل كتابيًا، ويحمل حزمة تتيح له تشغيل النظام من دونك. ولهذا السبب نفسه يعود.

وكل مشروع في صفحة الخدمات يسير بهذه الطريقة.

على الهاتف، تقطّعت الصفحة نفسها.

توقعت صورة ثقيلة أو حزمة JavaScript منتفخة. ما أراني إياه Chrome كان أغرب: والشاشة لا يلمسها أحد، كان الخيط الرئيسي (main thread) مشغولًا 98% من كل ثانية.

فبدأت أطفئ الحركات واحدة تلو الأخرى بحثًا عن المذنبة. لم يتغير شيء. وتبيّن أن هذا الطريق المسدود أثمن دليل في الرحلة كلها.

في آخر هذا المقال ستعرف لماذا تفرض حركة واحدة ضريبة على كل الحركات الأخرى، وكيف تجعل Chrome يسمّي الحركة المذنبة بنفسه، وستخرج بسكربتين يقيسان ذلك عنك.

98% انشغال، ولا أحد يلمس الصفحة

الاختبار بسيط: أفتح الصفحة على محاكاة هاتف (390×844، كثافة بكسل 3×، ومعالج أبطأ 4 مرات)، أتركها تُكمل التحميل، لا ألمس شيئًا، ثم أسأل Chrome: كم من كل ثانية قضاها الخيط الرئيسي في تنفيذ المهام؟

عند 98%، كل نقرة وكل تمرير ينتظر في الطابور خلف عمل لا يراه المستخدم. الصفحة تبدو حيّة، وتُحَسّ ميتة.

وعدد الإطارات في الثانية أخفى هذا كله. معظم حركاتي كانت تعمل على الـ compositor، وهو خيط منفصل ظل يحرّك الطبقات بنعومة بينما الخيط الرئيسي يغرق. عدّاد الـ FPS كان يقيس الخيط السليم.

الرقم يأتي من مقياس واحد في بروتوكول أدوات المطوّر (CDP) اسمه TaskDuration: مجموع الثواني التي قضاها الخيط الرئيسي في المهام. اقرأه، انتظر ثلاث ثوانٍ، اقرأه مجددًا، واقسم. السكربت الكامل، بالمقارنة قبل/بعد والوسيط، تجده قرب النهاية.

وتحذير قبل أي رقم: جهازي كان مشغولًا غالبًا بأعمال أخرى، فالقياس المنفرد يكذب. كل مقارنة في هذا المقال كانت قبل/بعد، بالتناوب، ووسيطَ عدة جولات.

الدليل: إطفاء الحركات لم يغيّر شيئًا

أطفأت الحركات مجموعةً مجموعة. أزلت الـ canvas، فبقيت الصفحة عند 98%. أزلت الحلقات، فبقيت عند 98%.

لا مجموعة بمفردها صنعت فرقًا، فعرفت أنني أسأل السؤال الخطأ. الكلفة تصرفت كرسم ثابت، وحفنة من الحركات كانت تُلزم الصفحة كلها بدفعه.

الحركة المركّبة (composited) طبقة يحرّكها كرت الشاشة وحده: يسلّمها الخيط الرئيسي مرة ثم يهدأ. أما الحركة غير المركّبة فتحتاج الخيط الرئيسي ليصنع إطارًا جديدًا مع كل تحديث للشاشة، وهو إطار كامل: حساب الأنماط، ومتابعة التخطيط، والرسم، وتحديث الطبقات، للصفحة كلها.

هكذا دفعت مئتا حركة، معظمها على الـ GPU أصلًا، هذه الكلفة الثابتة، لأن حفنة منها ظلت تطلب إطارًا. وإزالة مجموعة لا تفيد ما دامت أخرى ما زالت تطلب.

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

المشتبهون الستة الذين طاردتهم، وما حلّ محل كل منهم

1. الـ canvas الذي "بُني ليكلّف شبه لا شيء"

هكذا قال تعليق الملف القديم، وبدا كلامًا مسؤولًا: مطر الرموز كان canvas شفافًا واحدًا بحجم بكسلات CSS، بسقف 24 إطارًا في الثانية على الهاتف و30 على الكمبيوتر، ويتوقف حين يُخفى التبويب.

هذه حلقته:

const tick = (t: number) => {
  raf = requestAnimationFrame(tick)
  if (t - last < frameMs) return // مبكر جدًا: تخطَّ هذا الإطار
  last = t
  draw()
}

الفخ في سطر التخطي. كل استدعاء من هذه، حتى الذي يعود فورًا، طلبٌ لإطار على الخيط الرئيسي. سقف الإطارات وفّر وقت الرسم، ولم يوفّر شيئًا غيره.

البديل لا يرسم شيئًا أثناء التشغيل: ستة وعشرون عمودًا من الرموز، نص كل عمود يُختار مرة واحدة من بذرة ثابتة (فيتطابق الـ HTML المولَّد مسبقًا مع ما يرسمه المتصفح)، وكل عمود ينزل بـ transform في CSS:

.rune-col {
  position: absolute;
  top: 0;
  left: var(--x);
  width: 1ch;
  word-break: break-all;           /* رمز في كل سطر: عمود */
  mask-image: linear-gradient(transparent, #000 80%); /* الذيل يتلاشى */
  transform: translate3d(0, -110%, 0);
  animation: rune-fall var(--dur) linear infinite;
  animation-delay: var(--delay);   /* سالب: يتساقط منذ أول رسم */
}

@keyframes rune-fall {
  to { transform: translate3d(0, calc(100vh + 10%), 0); }
}

@media (max-width: 760px) {
  .rune-col:nth-child(2n) { display: none; } /* نصف الأعمدة على الهاتف */
}

كل عمود يأخذ --x خاصًا به، ومدة بين 11 و24 ثانية، وتأخيرًا سالبًا. الشكل نفسه، وصفر سكربت في كل إطار.

2. حالة React تدق كالساعة

الطرفية كانت تكتب باستدعاء setState على مؤقت: كل 42 إلى 82 ملّي ثانية أثناء الكتابة، وكل 18 أثناء المسح. كل استدعاء يعني render وإعادة حساب أنماط وتخطيطًا، لأن عرض النص يتغير في كل مرة.

الآن الكتابة CSS خالصة. نافذة أعرض من الأمر بحرف واحد تنزلق خطوة بحرف، والنص داخلها ينزلق عكسها بالقدر نفسه، فيظهر كل حرف في مكانه بالضبط، ولا يتحرك شيء سوى transform.

.tw {
  display: inline-block;
  animation: tw-in var(--type) steps(var(--steps), jump-start) both;
}
.tw-window {
  position: relative;
  display: block;
  width: calc(var(--steps) * 1ch);
  height: 1.5em;
  overflow: hidden;
  animation: tw-out var(--erase) steps(var(--steps), jump-start) calc(var(--type) + var(--hold)) forwards;
}
.tw-text-out {
  display: block;
  animation: tw-text-out var(--erase) steps(var(--steps), jump-start) calc(var(--type) + var(--hold)) forwards;
}
.tw-text {
  display: block;
  width: calc(var(--steps) * 1ch);
  line-height: 1.5em;
  animation: tw-text-in var(--type) steps(var(--steps), jump-start) both;
}

@keyframes tw-in       { from { transform: translate3d(-100%, 0, 0); } }
@keyframes tw-out      { to   { transform: translate3d(-100%, 0, 0); } }
@keyframes tw-text-in  { from { transform: translate3d(100%, 0, 0); } }
@keyframes tw-text-out { to   { transform: translate3d(100%, 0, 0); } }

.caret {                          /* يركب آخر خانة في النافذة */
  position: absolute;
  top: 50%;
  right: 0;
  width: 1ch;
  height: 1.15em;
  translate: 0 -50%;
  background: currentColor;
  animation: caret-blink 1s steps(1) infinite;
}
@keyframes caret-blink { 50% { opacity: 0; } }

وReact يضبط التوقيت مرة واحدة لكل أمر:

import type { CSSProperties } from 'react'

const TYPE_MS = 55
const ERASE_MS = 18
const HOLD_MS = 1700

export function TypeLine({ text }: { text: string }) {
  const timing = {
    ['--steps' as string]: text.length + 1, // خطوة لكل حرف، وواحدة للمؤشر
    ['--type' as string]: `${text.length * TYPE_MS}ms`,
    ['--hold' as string]: `${HOLD_MS}ms`,
    ['--erase' as string]: `${text.length * ERASE_MS}ms`,
  } as CSSProperties
  // الـ key يعيد تركيب الطبقات، فيبدأ كل أمر جديد حركاته من الصفر.
  return (
    <span key={text} className="tw" style={timing}>
      <span className="tw-window">
        <span className="tw-text-out">
          <span className="tw-text">{text}</span>
        </span>
        <span className="caret" />
      </span>
    </span>
  )
}

يحتاج خطًا أحادي العرض (monospace)، لأن كل خطوة 1ch. بدّل النص بعد text.length * (TYPE_MS + ERASE_MS) + HOLD_MS وفاصل قصير. أي setState واحد كل بضع ثوانٍ، بعد أن كانت عشرات في الثانية.

تأمّل هذه الطبقات الأربع. أول نسخة CSS كانت أقل منها طبقات، وهنا يكمن السبب السادس.

3. ضوء ينزلق بـ background-position

خط كل عنوان قسم كان يمر عليه ضوء ذهبي: تدرّج أعرض من الخط ثلاث مرات، يتحرك بـ background-position. والـ compositor لا يستطيع تحريك خلفية داخل عنصر، فكان ذلك إعادة رسم في كل إطار، لكل عنوان.

/* قبل: إعادة رسم في كل إطار */
.eyebrow::before {
  background: linear-gradient(90deg, var(--gold) 0 35%, var(--gold-fill-2) 50%, var(--gold) 65% 100%);
  background-size: 300% 100%;
  animation: rule-scan 3.4s linear infinite;
}

/* بعد: الخط يرسم نفسه امتدادًا وانكماشًا */
.eyebrow::before {
  transform-origin: left center;
  animation: rule-draw 3.4s ease-in-out infinite alternate;
}
html[dir='rtl'] .eyebrow::before {
  transform-origin: right center; /* يبدأ من الجهة التي يبدأ منها النص */
}
@keyframes rule-draw {
  from { transform: scaleX(0.35); opacity: 0.55; }
  to   { transform: none; opacity: 1; }
}

تأثير مختلف، خط يتنفس امتدادًا وانكماشًا، ولا يكلّف شيئًا في أي إطار. ولاحظ سطر dir='rtl': في العربية يمتد الخط من اليمين، حيث تبدأ القراءة.

4. المشتبه به البريء: خط وامض داخل SVG

المؤشر تحت حرف M في شعاري كان يومض بـ opacity على path داخل الـ SVG. كنت أظن أن ذلك يعيد رسم الـ SVG في كل إطار، فنقلت الوميض إلى عنصر HTML موضوع بالضبط حيث كان الـ SVG سيرسمه. والأرقام مأخوذة من هندسة الـ SVG نفسها: خط طوله 16 وحدة بنهايتين مستديرتين سُمكهما 2.6، داخل viewBox من 64 وحدة يُرسم بعرض 30px، عرضه (16 + 2.6) × 30 ÷ 64 = 8.7px.

.logo-mark { position: relative; }

.logo-caret {
  position: absolute;
  top: 27.8px;
  left: 50%;
  width: 8.7px;
  height: 1.3px;
  translate: -50% 0;
  border-radius: 1px;
  background: var(--blue);
  animation: caret-blink 1.1s steps(1) infinite;
}

@keyframes caret-blink { 50% { opacity: 0; } }

ثم أعدت، من أجل هذا المقال، اختبار كل مشتبه به في صفحة وحده. الشعار القديم يومض وحيدًا فلم يسبب أي إطار على الخيط الرئيسي، لا في Chrome 153 ولا في Edge 155، ولم يسجّل الـ trace أي فشل له. هذا كان بريئًا.

المؤشر بـ HTML باقٍ، فالشفافية على عنصر HTML هي بالضبط الحالة التي بُني الـ compositor لها. أما الدرس فهو ما يستحق البقاء: اختبر كل مشتبه به وحده، وإلا نسبت الفضل لإصلاح لم يفعل شيئًا.

5. إطار مخروطي يدور بـ @property

نموذج التواصل كان يدور حول إطاره ضوء: تدرج مخروطي زاويته خاصية مخصّصة مسجّلة، تتحرك من 0 إلى 360 درجة.

/* قبل: يُحسب على الخيط الرئيسي في كل إطار */
@property --spin {
  syntax: '<angle>';
  inherits: false;
  initial-value: 0deg;
}
.contact-panel::before {
  background: conic-gradient(from var(--spin), transparent 0 68%, var(--gold) 84%, transparent 100%);
  animation: spin-border 6s linear infinite;
}

@property يجعل الزاوية قابلة للتحريك، ويبقى الـ compositor عاجزًا عن تشغيلها. فيعيد Chrome حساب النمط ورسم التدرج في كل إطار.

الشكل نفسه يتحقق بمربع كبير من التدرج المخروطي يدور بـ transform، تحت قناع حلقي عرضه بكسل واحد لا يتحرك أبدًا:

/* العنصر الأب يحتاج position: relative و isolation: isolate */
.spin-ring {
  position: absolute;
  inset: -1px;
  z-index: -1;
  overflow: hidden;
  padding: 1px;
  border-radius: inherit;
  /* لا يبقى إلا البكسل الواحد من الـ padding: حلقة */
  -webkit-mask: linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0);
  -webkit-mask-composite: xor;
  mask-composite: exclude;
  pointer-events: none;
}
.spin-ring > span {
  position: absolute;
  top: 50%;
  left: 50%;
  width: 150%;
  aspect-ratio: 1;
  translate: -50% -50%;
  background: conic-gradient(transparent 0 68%, var(--gold) 84%, transparent 100%);
  animation: spin-ring 6s linear infinite;
}
@keyframes spin-ring { to { transform: rotate(360deg); } }

التدرج يُرسم مرة واحدة. لا يتغير إلا دورانه، والدوران من عمل الـ compositor.

6. حركتان، عنصر واحد، والرقم 64

هذا السبب ما كنت لأجده بقراءة الكود أبدًا. خرج من trace في Chrome، ومعه رقم: 64.

في أول طرفية بـ CSS، حمل عنصر واحد الحركتين tw-in (انزلاق للداخل أثناء الكتابة) وtw-out (انزلاق للخارج أثناء المسح)، وtw-out لا تبدأ إلا بعد أن تفرغ tw-in من الحركة. ومع ذلك رفض Chrome تسليم أيٍّ منهما للـ compositor. كلتاهما عملت على الخيط الرئيسي، في كل إطار، طوال ظهور الطرفية على الشاشة.

الرقم 64 قناع بتات (bitmask) من شيفرة Chromium المصدرية (compositor_animations.h)، والبت السادس فيه اسمه kTargetHasIncompatibleAnimations. وChromium يسمح فعلًا بعدة حركات transform على عنصر واحد إن استهدفت كلٌّ منها خاصية مختلفة، كـ rotate في واحدة وscale في أخرى. حركتاي كلتاهما حرّكتا transform.

الحل هو الطبقات التي رأيتها: حركة transform واحدة لكل عنصر، بعمق أربع طبقات متداخلة.

فكيف تجعل Chrome يعطيك هذا الرقم؟

اجعل Chrome يسمّي المذنب

Chrome يسجّل سبب عجزه عن تركيب كل حركة على الـ GPU، وما عليك إلا أن تسأل. سجّل trace بفئة blink.animations واقرأ أحداث Animation:

• حدث البداية (ph: 'b') يحمل args.data.displayName (اسم الـ @keyframes، أما name فيأتي فارغًا لحركات CSS) وnodeName وnodeId.
• الأحداث اللحظية (ph: 'n') تحمل args.data.compositeFailed، وهو bitmask، وargs.data.unsupportedProperties، أي خصائص CSS التي عجز عنها الـ compositor.
• والنوعان يشتركان في id2.local، وبه تربط بينهما.

هذا كله في سكربت واحد. أعطه رابطًا، فيطبع كل حركة رفضها الـ compositor، مع السبب بالكلمات.

// composite-audit.mjs   التشغيل: node composite-audit.mjs http://localhost:4173/
import { chromium } from 'playwright'

// بتات CompositorAnimations::FailureReason في Chromium (compositor_animations.h)
const REASONS = {
  [1 << 3]: 'unsupported timing parameters',
  [1 << 5]: 'target has invalid compositing state',
  [1 << 6]: 'target has incompatible animations',
  [1 << 10]: 'transform cannot be accelerated on this target',
  [1 << 12]: 'filter may move pixels',
  [1 << 13]: 'unsupported CSS property',
  [1 << 17]: 'no visible change',
  [1 << 18]: 'animates an !important property',
  [1 << 19]: 'SVG target has an independent transform property',
}
const decode = (mask) =>
  Array.from({ length: 22 }, (_, bit) => 1 << bit)
    .filter((flag) => mask & flag)
    .map((flag) => REASONS[flag] ?? `bit ${Math.log2(flag)}`)
    .join(', ')

const browser = await chromium.launch()
const context = await browser.newContext({ viewport: { width: 390, height: 844 }, deviceScaleFactor: 3, isMobile: true })
const page = await context.newPage()
await browser.startTracing(page, { categories: ['devtools.timeline', 'blink.animations'] })
await page.goto(process.argv[2], { waitUntil: 'load' })
await page.waitForTimeout(5000)
const { traceEvents } = JSON.parse((await browser.stopTracing()).toString())
await browser.close()

const idOf = (e) => e.id2?.local ?? e.args?.data?.id
const started = new Map()
for (const e of traceEvents) if (e.name === 'Animation' && e.ph === 'b') started.set(idOf(e), e.args.data)

const printed = new Set()
for (const e of traceEvents) {
  const mask = e.name === 'Animation' && e.ph === 'n' ? e.args.data?.compositeFailed : 0
  if (!mask) continue
  const { displayName = '?', nodeName = '?' } = started.get(idOf(e)) ?? {}
  const props = e.args.data.unsupportedProperties?.join(', ')
  const line = `${nodeName}  ${displayName}  ${mask}: ${decode(mask)}${props ? `  [${props}]` : ''}`
  if (!printed.has(line)) {
    printed.add(line)
    console.log(line)
  }
}

// السكربت لا يظهر فوق. عُدّ عمل الخيط الرئيسي في آخر 3 ثوانٍ بدلًا من ذلك.
const end = traceEvents.reduce((max, e) => Math.max(max, e.ts ?? 0), 0)
const recent = (name) => traceEvents.filter((e) => e.name === name && e.ts > end - 3e6).length
console.log('last 3 s:', {
  FireAnimationFrame: recent('FireAnimationFrame'),
  TimerFire: recent('TimerFire'),
  UpdateLayoutTree: recent('UpdateLayoutTree'),
})

شغّلته على صفحة اختبار فيها كود CSS "قبل" من هذا المقال وحلقة الـ canvas القديمة. هذا ما طبعه Chrome 153:

DIV class='contact-panel'  spin-border  8192: unsupported CSS property  [--spin]
SPAN class='tw-window'  tw-in  64: target has incompatible animations
SPAN class='tw-window'  tw-out  64: target has incompatible animations
SPAN class='eyebrow-rule'  rule-scan  8224: target has invalid compositing state, unsupported CSS property  [background-position-x]
last 3 s: { FireAnimationFrame: 180, TimerFire: 0, UpdateLayoutTree: 180 }

اقرأه سطرًا سطرًا:

• [--spin] و[background-position-x] يأتيان من unsupportedProperties. ولاحظ الثاني: Chrome يسمّي الخاصية المفصّلة (longhand)، لا الاختصار الذي كتبته.
• حركتا الطرفية كلتاهما تفشلان بـ 64، ولهذا لم تعمل أيٌّ منهما على الـ GPU.
• 180 استدعاء FireAnimationFrame في 3 ثوانٍ هي حلقة الـ canvas بسقف إطاراتها: واحد مع كل تحديث للشاشة. السقف لم يُنقص الاستدعاءات قط.
• UpdateLayoutTree هو إعادة حساب الأنماط في Chrome. و180 منه في 3 ثوانٍ تعني واحدًا في كل إطار.

والصفحة نفسها بكود CSS "بعد" لم تطبع أي فشل، ولا أي استدعاء إطار، و11 إعادة حساب أنماط فقط في 3 ثوانٍ.

سببان لا يظهران أبدًا كأحداث Animation، لأنهما سكربت: حلقة الـ canvas، والمؤقت خلف setState. FireAnimationFrame يعدّ استدعاءات requestAnimationFrame، وTimerFire يعدّ المؤقتات. وفي صفحة ساكنة ينبغي أن يقترب الاثنان من الصفر.

فخّان بدَوَا فكرتين جيدتين

استُبدل المشتبه بهم الستة جميعًا ونزل الرقم. ثم جاء محدِّد أنيق واحد فضاعفه.

:has() فوق شجرة فيها حركة. لمعة العنوان الذهبية كان عليها أن تنتظر حتى يفرغ العنوان من فك تشفيره. والطريقة الأنيقة لقول ذلك:

.hero-headline:has(.decode:not(.is-done)) .sheen-band {
  animation-play-state: paused;
}

نجح ذلك، وضاعف انشغال المعالج على الهاتف والصفحة ساكنة. فمع حركات تعمل داخل العنوان، صار Chrome يعيد فحص :has() في كل إطار.

الحل ممل: React يضيف كلاسًا مرة واحدة حين يستقر فك التشفير، وCSS يقرأ الكلاس:

.hero-headline:not(.is-decoded) .sheen-band,
.hero-headline:not(.is-decoded) .sheen-copy {
  animation-play-state: paused;
}

ضبابية الخلفية فوق خلفية متحركة. الشريط العلوي على الكمبيوتر كان عليه backdrop-filter: blur(18px) saturate(140%) فوق خلفية بشفافية 78%. وخلفه لا تكف الرموز عن التساقط، فكانت الضبابية تُحسب من جديد في كل إطار. رفعت الشريط إلى 94% وحذفت الضبابية، وبهذه النسبة لا يميّز أحد الفرق. أما الهاتف فكانت الضبابية مطفأة فيه أصلًا.

أوقف ما لا يراه أحد

الحركات خارج الشاشة تكلّف شيئًا أيضًا، والصفحة الطويلة تُبقي معظم حركاتها خارج الشاشة. مراقب IntersectionObserver واحد يعلّم كل قسم خارج نطاق الرؤية، وCSS يوقف كل ما بداخله:

[data-offscreen]::before,
[data-offscreen]::after,
[data-offscreen] *,
[data-offscreen] *::before,
[data-offscreen] *::after {
  animation-play-state: paused !important;
}

import { useEffect } from 'react'

const TARGETS = 'section, footer'

export default function OffscreenPause() {
  useEffect(() => {
    if (!('IntersectionObserver' in window)) return
    let io: IntersectionObserver | undefined
    let mo: MutationObserver | undefined
    let cancelled = false
    const each = (node: Node, fn: (el: Element) => void) => {
      if (!(node instanceof Element)) return
      if (node.matches(TARGETS)) fn(node)
      node.querySelectorAll(TARGETS).forEach(fn)
    }
    const start = () => {
      if (cancelled) return
      const observer = (io = new IntersectionObserver(
        (entries) => entries.forEach((e) => e.target.toggleAttribute('data-offscreen', !e.isIntersecting)),
        { rootMargin: '160px 0px' }, // يبدأ الحركة قبيل ظهور القسم
      ))
      document.querySelectorAll(TARGETS).forEach((el) => observer.observe(el))
      // تغيير الصفحة يضيف أقسامًا ويحذف أخرى.
      mo = new MutationObserver((records) =>
        records.forEach((r) => {
          r.addedNodes.forEach((n) => each(n, (el) => observer.observe(el)))
          r.removedNodes.forEach((n) => each(n, (el) => observer.unobserve(el)))
        }),
      )
      mo.observe(document.body, { childList: true, subtree: true })
    }
    // HTML مولَّد مسبقًا: انتظر حتى يستلم React الصفحة، وإلا رأى خصائص لم يرسمها.
    const kick = () =>
      window.requestIdleCallback ? window.requestIdleCallback(start, { timeout: 2500 }) : window.setTimeout(start, 300)
    if (document.readyState === 'complete') kick()
    else window.addEventListener('load', kick, { once: true })
    return () => {
      cancelled = true
      window.removeEventListener('load', kick)
      mo?.disconnect()
      io?.disconnect()
    }
  }, [])
  return null
}

ركّبه مرة واحدة، في أي مكان. وتفصيلتان أخذتا مني وقتًا:

• هامش الـ 160px. الأقسام تبدأ الحركة قبل أن تظهر، فلا يرى أحد لحظة انطلاقها.
• CSS يوقف الحركات، والحركات فقط. مؤقتاتك تستمر. مؤقت الطرفية يفحص closest('[data-offscreen]')، فإن وجد قسمه موقوفًا انتظر ثانية ثم فحص من جديد.

قِسها بنفسك: السكربت كاملًا

هذا هو قياس السكون الذي بدأ به المقال. ابنِ النسختين اللتين تريد مقارنتهما، شغّلهما على منفذين، ثم أمر واحد.

// idle-busy.mjs   التشغيل: node idle-busy.mjs http://localhost:4173/ http://localhost:4174/
import { chromium } from 'playwright'

const RUNS = 5          // لكل رابط، بالتناوب: A، B، A، B...
const SETTLE_MS = 4000  // دع التحميل ينتهي: نريد الكلفة والصفحة ساكنة
const WINDOW_MS = 3000

const browser = await chromium.launch()

async function idleBusy(url) {
  const context = await browser.newContext({
    viewport: { width: 390, height: 844 },
    deviceScaleFactor: 3,
    isMobile: true,
    hasTouch: true,
  })
  const page = await context.newPage()
  const cdp = await context.newCDPSession(page)
  await cdp.send('Emulation.setCPUThrottlingRate', { rate: 4 })
  await cdp.send('Performance.enable')
  await page.goto(url, { waitUntil: 'load' })
  await page.waitForTimeout(SETTLE_MS)

  const taskSeconds = async () =>
    (await cdp.send('Performance.getMetrics')).metrics.find((m) => m.name === 'TaskDuration').value
  const before = await taskSeconds()
  await page.waitForTimeout(WINDOW_MS)
  const after = await taskSeconds()
  await context.close()
  return ((after - before) / (WINDOW_MS / 1000)) * 100
}

const urls = process.argv.slice(2)
const runs = Object.fromEntries(urls.map((url) => [url, []]))
for (let i = 0; i < RUNS; i++) for (const url of urls) runs[url].push(await idleBusy(url))
await browser.close()

const median = (xs) => [...xs].sort((a, b) => a - b)[Math.floor(xs.length / 2)]
for (const [url, xs] of Object.entries(runs)) {
  console.log(`${median(xs).toFixed(0)}% busy at rest  ${url}  (runs: ${xs.map((x) => x.toFixed(0)).join(', ')})`)
}

التثبيت: npm i -D playwright ثم npx playwright install chromium.

ما الذي تغيّر

الصفحة نفسها، والحركات نفسها، على محاكاة الهاتف نفسها:

مكاسب التحميل جاءت من ثلاثة تغييرات أخرى: حذفت framer-motion ‏(42 KB مضغوطة) لصالح بضع حركات CSS. وتوقفت الصفحة الرئيسية عن حزم نصوص دراسات الحالة الكاملة، فنزل السكربت الرئيسي من 416 KB إلى 324 KB. وصارت الخطوط تُحمَّل دون أن تعطّل سكربت التطبيق.

ولم تُحذف حركة واحدة.

القائمة التي أراجعها الآن

• حرّك transform وopacity على عناصر HTML. ولا شيء غيرهما في حلقة متكررة، أبدًا.
• لا سكربت يعمل إلى الأبد: لا حلقات requestAnimationFrame، ولا إعادة رسم canvas، ولا تحديث حالة على مؤقت.
• حركة transform واحدة لكل عنصر. وإن احتجت اثنتين، أضف عنصرًا يغلّفه.
• لا :has() فوق شجرة فيها حركة. ضع كلاسًا مرة واحدة.
• لا backdrop-filter فوق محتوى متحرك.
• أوقف ما هو خارج الشاشة، واجعل مؤقتاتك تنتظر معه.
• شغّل سكربت التدقيق بعد كل تأثير جديد. كل سطر يطبعه إطار على الخيط الرئيسي تدفع ثمنه.
• اختبر كل مشتبه به وحده قبل أن تنسب الفضل لإصلاح. واحد من إصلاحاتي الستة لم يغيّر شيئًا.
• قِس الخيط الرئيسي والصفحة ساكنة، قبل/بعد وبالوسيط. عدد الإطارات في الثانية لا يحدّثك إلا عن الخيط السليم.

الحركة لم تكن يومًا الجزء المكلف. المكلف هو الحركة الواحدة التي تطلب من الخيط الرئيسي إطارًا بصمت، والصفحة كلها تدفع الثمن.

والعنوان ذو اللمعة الذهبية نفسه انكسر بالعربية بطريقة لا يكشفها أي trace. تلك القصة الأخرى.

ثم حوّلت الصفحة إلى العربية.

قبل أن ينتهي التأثير، تعثّرت عيني بكلمة واحدة: «كاملًا». الـ«لا» في آخرها، الشكل الذي يعرفه كل قارئ عربي من أول نظرة، وقفت حرفين منفصلين. وبعد ثانية مرّت اللمعة الذهبية على العنوان، فبدت كل كلمة مكررة مرتين.

كلمة واحدة فيها خطآن، وخطأ ثالث يمتد على السطر كله. والحل الذي يمد إليه كل مطوّر يده، Intl.Segmenter، يعالج واحدًا منها فقط.

وحين أعدت بناء الخطأ في صفحة اختبار من أجل هذا المقال، صار أغرب: العناصر نفسها كانت سليمة في فقرة عادية. احتاج كسرُها إلى خاصية CSS واحدة في عنواني.

في آخر المقال ستعرف ما هذه الخاصية، ولماذا الكلمة أصغر وحدة يمكنك تحريكها بأمان في العربية، وكيف تعيد السطر نصًا عاديًا فينطبق عليه كل ما فوقه بالبكسل، وستخرج بمكوّن جاهز للنسخ.

النسخة التي يكتبها الجميع أولًا

قسّم النص إلى حروف، ضع كل حرف في span، اتركها شفافة حتى يأتي دورها، وارسم فوقها رمزًا عشوائيًا أثناء الانتظار:

{Array.from(text).map((char, i) => (
  <span key={i} className="dc">{char}</span>
))}

.dc { color: transparent; }
.dc.is-scr::after { content: attr(data-g); position: absolute; /* … */ }
.dc.is-on { color: inherit; }

جزء واحد من هذا صحيح، وقد بقي. كل حرف موجود في الصفحة من أول إطار، فالسطر يأخذ عرضه النهائي ويلتف حيث سيلتف، ولا شيء يتحرك في التخطيط أثناء التأثير.

أما كل ما عداه فكان لا بد أن يتغير.

ما الذي انكسر في العربية، طبقة بعد طبقة

الخطأ الأول: الحركات سقطت عن حروفها

Array.from() يقسّم النص حسب نقطة الترميز (code point). و«كاملًا» فيها ست نقاط:

const hex = (s) => [...s].map((c) => c.codePointAt(0).toString(16).toUpperCase().padStart(4, '0'))

hex('كاملًا')
// ['0643', '0627', '0645', '0644', '064B', '0627']   ست نقاط ترميز، ستة عناصر

الـ 064B هو التنوين، الحركة التي تعلو اللام. ولأنه نقطة ترميز مستقلة، أخذ عنصرًا مستقلًا، بعيدًا عن الحرف الذي ينتمي إليه.

ولا تفترض أن نصوصك خالية من الحركات. عربية الواجهات تُسقط معظمها، لكن تنوين الفتح في كلمات مثل «كاملًا» و«أيضًا» من صلب الإملاء، والشدّة تظهر في أسماء مثل «محمّد».

ما يراه القارئ حرفًا واحدًا هو عنقود حروف (grapheme cluster)، والمتصفح يقسّمه لك:

const seg = new Intl.Segmenter(undefined, { granularity: 'grapheme' })

Array.from(seg.segment('كاملًا'), (part) => hex(part.segment).join('+'))
// ['0643', '0627', '0645', '0644+064B', '0627']   خمسة عناقيد: الحركة ترافق لامها

الخطأ الأول انحلّ. والآن انظر إلى آخر عنصرين.

الخطأ الثاني: «لا» انشقّت، وIntl.Segmenter عاجز عن منعها

0644+064B هي اللام بحركتها، و0627 هي الألف. عنقودان، أي عنصران ما زالا منفصلين.

اللام متبوعة بالألف هي الحرف المركّب (ligature) الوحيد الذي تفرضه العربية. يحتفظ Unicode بالشكل الجاهز للتوافق فقط (ﻻ، U+FEFB). أما النص الحقيقي فيخزّن حرفين، والخط يرسمهما شكلًا واحدًا حين يشكّلهما معًا.

عناقيد الحروف تصف ما يراه القارئ حرفًا واحدًا. والحرف المركّب أكبر من ذلك: حرفان يدمجهما الخط في شكل واحد. ولا تقسيم بالعناقيد يستطيع إبقاءه سليمًا، لأنه يمتد على عنقودين.

فمتى يظهر الانشقاق فعلًا؟ أعدت بناء العنوان في صفحة اختبار (خط IBM Plex Sans Arabic بوزن 600، في Chrome 153 وEdge 155، وقد تطابقا بالبكسل) وقست السطر في خمسة أوضاع:

في سطر عادي، يشكّل Chrome الحروف عبر العناصر السطرية فتنجو الكلمة. لكن عنواني كان عليه text-wrap: balance، ومعها فقدت العناصر نفسها الحرف المركّب، وعددًا من نقاط الاتصال، و43 بكسلًا من العرض. وصفّ inline-block هو ما تحصل عليه من أي تأثير يحرّك الحروف واحدًا واحدًا، لأن الـ transform يحتاج صندوقًا: فيقف كل حرف وحيدًا.

وحتى في الحالة التي تنجو فيها الكلمة، هناك فخ. مع خطي، الحرف المركّب شكل واحد، وChrome يلوّنه بلون عنصر اللام. في اختباري ظهرت «لا» كاملة لحظة استقرار اللام، وما دامت اللام شفافة بقيت الألف مختفية معها. نصف شكل لا يمكن تحريكه.

الخطأ الثالث: اللمعة الذهبية تضاعفت

فوق عنواني لمعة ذهبية: نسخة ثانية من العنوان كنص عادي، يكشفها شريط متحرك. والنص العادي والعناصر المقسّمة صارا يختلفان بـ 43 بكسلًا في أعرض سطر، فتباعدت الحروف وتوازن السطر بطريقتين، ولم تعد الحروف الذهبية فوق البيضاء.

الكلمة أصغر وحدة آمنة

الكلمة أصغر قطعة من العربية تحمل تشكيلها كاملًا: اتصال حروفها، وحركاتها، وحروفها المركّبة. لذا تُفك العربية كلمةً كلمة. أما الإنجليزية فتبقى حرفًا حرفًا، لأنها تُقرأ جيدًا بالحروف اللاتينية ولا تكلّف شيئًا إضافيًا.

const ARABIC = /\p{Script=Arabic}/u
const byWord = ARABIC.test(text)
// المسافات تبقى نصًا عاديًا بين الكلمات.
const units = byWord ? text.split(/( )/).filter(Boolean) : graphemes(text)

موقعي يفحص كتلة العربية الأساسية، من U+0600 إلى U+06FF، وهي تغطي نصوصه. أما \p{Script=Arabic} فهو الخيار الأسلم لنص لا تتحكم فيه: يطابق أيضًا الكتل الملحقة والموسّعة وأشكال العرض.

وأي نص فيه حرف عربي واحد يُفك بالكلمات، بما فيها الكلمات اللاتينية. «مهندس برمجيات Full Stack» تُفك أربع كلمات.

احتاج الإيقاع إلى تعديلين، وكلاهما في المكوّن أدناه:

الكلمة تأخذ ثلاث خطوات، فلا تمر خاطفة في زمن حرف واحد. وأثناء انتظارها تُظهر دفعة رموز بطولها تقريبًا، فيحتفظ السطر بنسيجه.

أنهِ على نص عادي، وإلا لن ينطبق الذهب

العناصر المقسّمة بالكلمات تطابق النص العادي في حدود 0.03px في صفحة اختباري. والنص العادي يطابق نفسه تمامًا، بعقدة نصية واحدة بدل عنصر لكل كلمة. لذا حين ينتهي التأثير، تختفي العناصر كلها.

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

if (settled) return <span className="decode is-done">{text}</span>

اللمعة تنتظر هذه اللحظة بكلاس، ولا تنتظرها بـ :has() أبدًا. ولماذا ضاعف :has() هناك انشغال المعالج والصفحة ساكنة، تجده في مقال الأداء.

واللمعة نفسها حركتا transform. شريط بعرض 30% من العنوان ينزلق في اتجاه، وداخله نسخة نصية بعرض العنوان كله تنزلق عكسه بالمسافة نفسها وعلى الساعة نفسها، فتبقى الحروف الذهبية فوق البيضاء. وهندستها تستخدم left الفيزيائي عمدًا: في العربية يجب أن ينقلب النص الذي داخلها فقط، ويبقى مسار الشريط كما هو.

من اليمين إلى اليسار، مجانًا

فك التشفير يسير من اليمين إلى اليسار في العربية دون حالة خاصة واحدة.

الوحدات بترتيب الـ DOM، وهو الترتيب المنطقي: الترتيب الذي تكتب به وتقرأ. الفهرس 0 هو أول كلمة يراها القارئ، على اليمين. والحلقة تمشي على الفهارس، فيتحرك المؤشر كما تتحرك عين القارئ.

وطبقة الرموز لا تحتاج قواعد اتجاه هي الأخرى. تجلس عند left: 50% مع translate: -50% 0، في منتصف وحدتها أيًّا كان الاتجاه.

الأرقام هي الموضع الوحيد الذي يستحق التصريح. الأرقام داخل النص العربي تجري من اليسار إلى اليمين، لذا تجلس الأرقام تحت عنواني في عناصرها الخاصة بـ dir="ltr"، وتُفك عبر رموز أرقام بدل الرموز البرمجية.

إبقاؤه خفيفًا

هذا التأثير يشغّل حلقة requestAnimationFrame، وهو ما يعدّه مقال الأداء علامة خطر. الفرق أن هذه الحلقة تنتهي.

• حلقة واحدة لكل نص، لا تلمس إلا الوحدات داخل نافذة التبدّل. تخرج عند أول وحدة بعد النافذة، وتتوقف حين تستقر آخر وحدة.
• رموز جديدة كل 60 ms، نحو 16 مرة في الثانية: سريعة بما يكفي لتبدو تشويشًا، وبطيئة بما يكفي لتُرى الرموز.
• الوحدات التي تتبدل في تلك اللحظة فقط تأخذ position: relative، وهي ما يحتاجه الرمز. العنصر المتموضع يصير طبقة رسم مستقلة، ومئة منها جعلت كل إطار من التأثير ثقيلًا.
• أطوال دفعات الرموز للكلمات العربية تُحسب مرة واحدة. تشغيل Intl.Segmenter مع كل تبديل لكل كلمة منتظرة ظهر في الـ profile.
• ومع تفضيل تقليل الحركة (reduced motion)، يستقر النص فورًا.

وبالقياس قبل/بعد على محاكاة هاتف بمعالج أبطأ أربع مرات، يكلّف التأثير كله نحو 0.35 ثانية من عمل الخيط الرئيسي موزعة على أول ثانيتين، ولا شيء بعدها.

المكوّن، جاهزًا للنسخ

هذا المكوّن من موقعي، مختصرًا إلى ما يهم. يحتاج مكتبة ES2022 أو أحدث في TypeScript من أجل Intl.Segmenter، ويعود إلى نقاط الترميز إن غاب عن المتصفح.

import { useEffect, useMemo, useRef, useState } from 'react'

const GLYPHS = '{}[]()<>/=+-*&|!?#$%@;:01λΣ'
const ARABIC = /\p{Script=Arabic}/u

/** الحروف كما يراها القارئ، فيحتفظ الحرف بحركاته. */
const graphemes = (text: string): string[] =>
  typeof Intl.Segmenter === 'function'
    ? Array.from(new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(text), (s) => s.segment)
    : Array.from(text)

type Props = {
  text: string
  delay?: number // ms قبل أن تبدأ أول وحدة
  step?: number // ms لكل حرف؛ والكلمة العربية تأخذ ثلاث خطوات
  window?: number // كم وحدة أمام المؤشر تتبدل رموزها
  onSettled?: () => void
}

export default function DecodeText({ text, delay = 0, step = 20, window: span = 5, onSettled }: Props) {
  const ref = useRef<HTMLSpanElement>(null)
  const onSettledRef = useRef(onSettled)
  useEffect(() => {
    onSettledRef.current = onSettled
  })
  const byWord = ARABIC.test(text)
  // العربية بالكلمات (المسافات تبقى نصًا عاديًا بينها)، وغيرها بالعناقيد.
  const units = useMemo(() => (byWord ? text.split(/( )/).filter(Boolean) : graphemes(text)), [text, byWord])
  const [settledText, setSettledText] = useState<string | null>(null)
  const settled = settledText === text

  useEffect(() => {
    const root = ref.current
    if (!root || settled) return
    const cells = Array.from(root.querySelectorAll<HTMLElement>('.dc'))
    const settle = () => {
      setSettledText(text)
      onSettledRef.current?.()
    }
    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
      settle()
      return
    }

    const noise = (n: number) => Array.from({ length: n }, () => GLYPHS[(Math.random() * GLYPHS.length) | 0]).join('')
    // دفعة الكلمة بطولها تقريبًا: تُحسب مرة واحدة، لا مع كل تبديل.
    const burst = cells.map((c) => (byWord ? Math.min(7, Math.max(2, graphemes(c.textContent ?? '').length)) : 1))
    const pace = byWord ? step * 3 : step
    const start = performance.now() + delay
    let raf = 0
    let timer = 0
    let lastShuffle = 0

    const tick = (now: number) => {
      const t = now - start
      const shuffle = now - lastShuffle > 60 // نحو 16 رمزًا جديدًا في الثانية
      if (shuffle) lastShuffle = now
      let landed = 0
      for (let i = 0; i < cells.length; i++) {
        const cell = cells[i]
        const at = i * pace
        if (t >= at) {
          if (!cell.classList.contains('is-on')) {
            cell.classList.remove('is-scr')
            cell.classList.add('is-on')
          }
          landed++
        } else if (t >= at - span * pace) {
          if (shuffle || !cell.classList.contains('is-scr')) {
            cell.dataset.g = noise(burst[i])
            cell.classList.add('is-scr')
          }
        } else break // كل ما بعد هذه الوحدة ما زال ينتظر
      }
      if (landed < cells.length) raf = requestAnimationFrame(tick)
      else timer = window.setTimeout(settle, 200) // ثم أعِد النص عاديًا
    }
    raf = requestAnimationFrame(tick)
    return () => {
      cancelAnimationFrame(raf)
      window.clearTimeout(timer)
    }
  }, [text, units, byWord, delay, step, span, settled])

  const className = settled ? 'decode is-done' : 'decode'
  // بعد الاستقرار: نص عادي واحد، يُشكَّل كأي نص آخر في الصفحة.
  if (settled) return <span className={className}>{text}</span>
  // المفتاح هو النص، فتبديل اللغة يركّب وحدات جديدة مخفية.
  return (
    <span key={text} ref={ref} className={className}>
      {units.map((unit, i) => (unit === ' ' ? ' ' : <span key={i} className="dc">{unit}</span>))}
    </span>
  )
}