تنفيذ إدارة المستندات مع Doconut

عادةً ما تحتاج سير عمل إدارة المستندات في بوابة .NET إلى ثلاثة أشياء:

1. طريقة لتحميل ملفات PDF، ملفات Office، رسومات CAD، أو الصور دون كتابة عارض من الصفر.
2. رمز آمن يربط المستند المحمّل بجلسة المتصفح الحالية.
3. خطوة تنظيف تُفرغ الذاكرة بمجرد انتهاء المستخدم.

توفر Doconut الثلاثة من خلال خدمة Viewer واحدة، جلسة IMemoryCache خفيفة الوزن، واستدعاءات CloseDocument صريحة.

---

1. تسجيل العارض في حاوية DI

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

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

---

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

قم بتكوين طبقة Doconut الوسطية في خط أنابيب الطلب بحيث يتم معالجة أي طلب يحتوي على سلسلة استعلام ?token= بواسطة Doconut. تفرض الطبقة الوسطية علامة الأمان الافتراضية (secure-{token}) عندما يكون UnsafeMode غير صحيح (الإعداد الافتراضي) وتقدم صور الصفحات، المصغرات، وبيانات التعليقات التوضيحية.

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

---

3. فتح مستند والحصول على رمز الجلسة غير الشفاف

أنشئ نقطة نهاية واحدة تستقبل مسار ملف (أو تدفق) وتعيد الرمز. الرمز هو الاعتماد الوحيد الذي يراه عنصر واجهة العميل.

app.MapPost("/api/open", async (Viewer viewer) =>
{
    // الـ token غير شفاف — سلّمه إلى الـ widget، لا تقم بتسجيله أو حفظه أبداً.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Contract.pdf");
    return Results.Ok(new { token });
});

ما يحدث داخل OpenDocumentAsync

1. بوابة الترخيص – ترخيص غير صالح يطرح LicenseException فورًا.
2. إنشاء الجلسة – تختار Doconut عارض الصيغة المناسب (PDF، Word، DWG، …) وتخزن المحرك في IMemoryCache تحت رمز GUID.
3. تسجيل الأمان – باستخدام UnsafeMode = false يتم ربط الرمز بجلسة ASP.NET للمتصل عبر علامة secure-{token}. يمكن لتلك الجلسة المتصفح فقط طلب الصفحات.
4. إرجاع الرمز – يتلقى العميل الرمز ويستخدمه في كل طلب لاحق (/DocImage.axd?token=…).

انتهاء الصلاحية الانزلاقي الافتراضي هو 60 دقيقة (قابل للتكوين عبر DocOptions.TimeOut). كل طلب صفحة يعيد ضبط المؤقت، لذا تختفي الجلسات الخاملة تلقائيًا.

---

4. عرض المستند على جانب العميل

من المتصفح، تستدعي نقطة النهاية، تلتقط الرمز، وتقدمه إلى عنصر Doconut:

fetch('/api/open', { method: 'POST' })
    .then(r => r.json())
    .then(d => {
        const token = d.token;
        objViewer.View(token);   // widget JavaScript المقدم من Doconut
    });

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

---

5. إغلاق المستند بمجرد مغادرة المستخدم للعارض

بالنسبة لملفات PDF أو CAD الكبيرة، يجب تحرير محرك العرض فورًا. استدعِ CloseDocument من نقطة نهاية على جانب الخادم أو من حدث “unload” للعنصر.

// نقطة النهاية على جانب الخادم
app.MapPost("/api/close", (Viewer viewer, string token) =>
{
    viewer.CloseDocument(token);
    return Results.Ok();
});

// استدعاء مباشر من الـ widget (إذا قمت بفتح الـ token للواجهة الخلفية)
viewer.CloseDocument(token);

CloseDocument يزيل الجلسة من الذاكرة المؤقتة، يفرغ محرك المستند الأساسي، يحذف علامة secure-{token}، ويلغي منح الوصول. انتهاء الصلاحية الانزلاقي سيفعل ذلك في النهاية، لكن الإغلاق الصريح يضمن استعادة الذاكرة فور انتهاء المستخدم.

---

6. اختياري: تحويل مستند على الخادم

إذا كان سير عملك يتطلب تصدير PDF لملف Word تم تحميله، فعّل مكوّن Converter في إعدادات Doconut (انظر الوثائق). بعد تسجيل المكوّن يمكنك حقن DocumentConverter واستدعاء طريقة ConvertAsync الخاصة به. يتم تنفيذ التحويل على الخادم، لذا لن تحتاج أبدًا إلى تثبيت Office على خادم الويب.

---

7. اعتبارات التوسع لإدارة المستندات على مستوى المؤسسات

• واجهات أمامية بلا حالة – لا يحتفظ عنصر العارض ببيانات المستند؛ كل المعالجة الثقيلة تبقى على الخادم.
• ذاكرة مؤقتة موزعة – استبدل الذاكرة المؤقتة في الذاكرة الافتراضية بمزود موزع (Redis، NCache) إذا كنت تشغل عدة عقد في مزرعة الويب. خريطة الرمز إلى الجلسة تعمل دون تغيير لأن الطبقة الوسطية تقرأ من IMemoryCache المُكوَّن.
• وظائف خلفية – يمكنك فتح المستندات مسبقًا في عامل خلفي، تخزين الرمز مؤقتًا، وتقديمه إلى واجهة المستخدم لاحقًا. فقط تذكر أن كل رمز يُستخدم مرة واحدة لكل جلسة؛ إعادة الاستخدام تتطلب استدعاء OpenDocumentAsync جديد.

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

---

8. قائمة مراجعة سريعة لتنفيذ جاهز للإنتاج

الخطوة	الإجراء
1	تسجيل خدمات Doconut في Program.cs (التحقق من الترخيص).
2	إضافة طبقة Doconut الوسطية على فرع مخصص.
3	كشف نقطة نهاية /api/open التي تستدعي OpenDocumentAsync.
4	تمرير الرمز المُعاد إلى objViewer.View(token) في العميل.
5	استدعاء CloseDocument(token) عندما يكون العارض مخفيًا أو عندما تُفرغ الصفحة.
6	(اختياري) تمكين ConverterPlugin إذا كنت تحتاج إلى تحويل على جانب الخادم.
7	(اختياري) استبدال IMemoryCache بذاكرة مؤقتة موزعة للتوسع الأفقي.

اتبع القائمة، وستحصل على تدفق إدارة المستندات كامل، آمن، وعالي الأداء مبني على عارض .NET الأصلي من Doconut.