توليد مستندات PDF في خوادم Go للـ SaaS: الفواتير والتقارير والكشوفات

كل منتج SaaS يحتاج في نهاية المطاف إلى توليد مستندات PDF. الفواتير والكشوفات الشهرية وإيصالات التسليم وتقارير الرواتب كلها صيغ يتوقعها العملاء كملفات PDF قابلة للتنزيل. في هذا المقال نشرح كيف نتعامل مع توليد PDF في خوادم Go للمنتجات التي تخدم عملاء في لبنان ومنطقة الشرق الأوسط.

لماذا توليد PDF في Go أصعب مما يبدو

Go لا تمتلك مكتبة أصلية لعرض PDF تتعامل مع التصاميم المعقدة بشكل جيد. النهجان اللذان يعملان في الإنتاج هما: استخدام html/template لإنتاج مستند HTML وتحويله إلى PDF عبر متصفح بدون واجهة رسومية، أو استخدام مكتبة Go أصلية لإنشاء PDF برمجياً.

نهج المتصفح بدون واجهة رسومية عبر Gotenberg أو Chromium يُنتج أعلى جودة في المخرجات لأنك تكتب التصميم بـ CSS وHTML، وهو ما يتقنه كل مطور في الفريق. النهج البرمجي باستخدام مكتبات مثل gofpdf يمنحك تحكماً أكبر في حجم الملف، لكنه يتطلب بناء التصميم في الكود بدلاً من الـ HTML.

بالنسبة لمعظم منتجات SaaS، يفوز نهج التصيير بمتصفح على جودة المخرجات وسرعة التطوير.

نهج HTML مع Gotenberg

Gotenberg هو API مبني على Docker يلف Chromium. ترسل له ملف HTML فيعيد لك ملف PDF. في Go، التدفق يبدو هكذا:

1. تصيير قالب الفاتورة إلى سلسلة HTML باستخدام html/template
2. إرسال طلب HTTP متعدد الأجزاء إلى Gotenberg مع HTML المُصيَّر
3. استلام بيانات PDF في جسم الاستجابة
4. حفظ PDF في S3 أو إرجاعه مباشرة للعميل

دعم اللغة العربية في الفواتير

لعملاء الشرق الأوسط، يجب أن يدعم قالب HTML تصيير النص من اليمين إلى اليسار للفواتير العربية. إضافة dir="rtl" و lang="ar" إلى عنصر HTML الجذري مع تحميل خط عربي يُنتج مخرج PDF عربياً صحيحاً عبر Gotenberg.

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

التعامل مع دقة الأرقام العشرية لمتطلبات الضرائب في الشرق الأوسط

المملكة العربية السعودية والإمارات ولبنان جميعها لديها متطلبات محددة لعرض ضريبة القيمة المضافة على الفواتير. استخدام shopspring/decimal لجميع القيم النقدية في خط توليد PDF يمنع أخطاء التقريب من الظهور على فواتير العملاء.

التخزين المؤقت والتخزين الدائم

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

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

دروس من الإنتاج

Gotenberg يحل مشاكل التصميم الصعبة. CSS flexbox وgrid يعملان في تصيير PDF المبني على Chromium. نموذج HTML يتطور بشكل طبيعي مع زيادة تعقيد التصاميم.

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

اختبر التصيير العربي من البداية إلى النهاية. نص من اليمين إلى اليسار في PDF له تفاصيل تصيير محددة لا تظهر إلا في المخرج النهائي.