التقنيات — كل ما بُني به Saha Doküman

الخادم

الواجهة البرمجية وحدة نشر واحدة على .NET 10، مكتوبة بـ Minimal API بلا controllers.

التقنية	الإصدار	دورها في Saha Doküman
.NET / C#	10 (SDK 10.0.300)	كل جانب الخادم مكتوب بـ C# على .NET 10، ببناء يفحص القيم الفارغة ويعدّ التحذيرات أخطاء.
ASP.NET Core Minimal APIs	10.0	كل نقطة نهاية Minimal API معرَّفة في ملف واحد لكل مجلد ميزة؛ ولا تُستخدم controllers.
Microsoft.AspNetCore.OpenApi	10.0.13	يولّد عقد الواجهة البرمجية بصيغة OpenAPI 3.1؛ وتُكتب نماذج الويب والجوال وفقه.
Scalar.AspNetCore	2.18.0	يوفّر واجهة مرجعية تفاعلية لتجربة الواجهة البرمجية أثناء التطوير (معطّلة في الإنتاج).
JWT Bearer	10.0.13	يتحقق من رموز الوصول؛ وتتبدّل رموز التحديث عند كل استخدام. لا تُوضع الأدوار في الرمز، بل تُقرأ من محرك الصلاحيات عند كل طلب.
PasswordHasher	10.0	تُخزَّن كلمات المرور كبصمات أنشأها PasswordHasher في ASP.NET Core؛ ولا تُحفظ كلمة مرور صريحة.
Rate limiting	10.0	حدود طلبات لكل IP ولكل مستخدم على تسجيل الدخول والمسارات الحساسة؛ ومحاولات التخمين تقفل الحساب.
Entity Framework Core	10.0.13	طبقة الربط بين الكائنات والجداول للوصول إلى البيانات وترحيلات المخطط.
Npgsql EF Core provider	10.0.3	مزوّد PostgreSQL لـ EF Core؛ يستخدم أنواع PostgreSQL وفهارسه الخاصة.
Markdig	1.4.1	يُخزَّن محتوى الصفحات بصيغة Markdown مقيَّدة؛ ويتحقق Markdig منه على شجرة البنية ويحوّله إلى نص عادي للبحث.
SkiaSharp	4.153.1	تُفك كل صورة مرفوعة وتُعاد ترميزها: تُحذف بيانات الموقع وEXIF، ويُحدَّد الحجم، وتُنشأ صورة مصغّرة.
DocumentFormat.OpenXml	3.5.1	يستورد ملفات Word، ويستخرج نص البحث من ملفات Word وExcel وPowerPoint، ويقرأ قالب استيراد المستخدمين من Excel.
PdfPig	0.1.16	يستخرج نص البحث من ملفات PDF ويحتفظ بأرقام الصفحات للاستشهاد. يعمل في عملية فرعية منفصلة لعزل الملفات التالفة.
Serilog	4.3.1	يكتب ملفات سجل منظَّمة؛ وتُخفى الرموز وكلمات المرور وقيم سلسلة الاستعلام قبل وصولها إلى السجل.
MailKit	4.18.1	يرسل صندوق بريد المنصة الصادر عبر SMTP: رابط تعيين كلمة مرور مدير الشركة الجديد وتذكيرات تجديد الاشتراك.
TimeProvider	.NET 10	كل قراءات الوقت تمر عبر TimeProvider؛ وفي الاختبارات يُتحكَّم بالوقت بساعة وهمية مع احترام دقة الميكروثانية في قاعدة البيانات.

البيانات والبحث

كل المحتوى والسجلات وفهرس البحث في PostgreSQL؛ ولا حاجة إلى خادم بحث منفصل.

التقنية	الإصدار	دورها في Saha Doküman
PostgreSQL	18.6	مخزن البيانات الوحيد للصفحات والإصدارات والسجلات وفهرس البحث ومقتطفات المعرفة وسجل التدقيق؛ ويُنشأ العنقود بترتيب تركي (ICU tr-TR).
tsvector + GIN		يعتمد البحث النصي الكامل على أعمدة tsvector بفهارس GIN؛ ويُبنى المتجه في C# بقواعد الكلمات نفسها المستخدمة في الاستعلام.
TurkishNormalizer		يوحّد الحروف التركية والعربية بجدول صريح يحافظ على الطول؛ وتوحيد البحث يجري على الخادم فقط.
ArabicWords		يحلّل أشكال الكلمات العربية (مثل أداة التعريف) فيجد البحث الكلمة حتى بلا «ال».
Advisory locks		أقفال تطبيق على مستوى المعاملة تنظّم الأعمال المتزامنة كالنشر والفهرسة.
xmin concurrency		تُكتشف التعديلات المتزامنة بعمود xmin في PostgreSQL (تزامن تفاؤلي) بدل الكتابة فوقها بصمت.
Append-only ledgers		أحداث النشر وسجلات فحص المساهمة للإضافة فقط؛ وصلاحيات دور التشغيل في قاعدة البيانات لا تشمل التحديث والحذف.

الذكاء الاصطناعي وRAG

البحث الدلالي يعمل محليًا؛ وتوليد الإجابات اختياري ولا يستخدم إلا المقتطفات المسموحة.

التقنية	الإصدار	دورها في Saha Doküman
Ollama	0.35.1	يشغّل نموذج التضمين محليًا على الخادم؛ وهو على الشبكة الداخلية فقط وبلا منفذ منشور.
bge-m3	1024 dim.	نموذج تضمين متعدد اللغات (ومنها التركية) ينتج متجهًا من 1024 بُعدًا لكل مقتطف معرفة.
Microsoft.Extensions.AI	10.10.0	طبقة تجريد لمولّد التضمين: Ollama في الإنتاج ومولّد وهمي حتمي في الاختبارات.
OllamaSharp	5.5.0	العميل الذي يربط تجريد Microsoft.Extensions.AI بخادم Ollama المحلي.
System.Numerics.Tensors	10.0.13	حاصل ضرب نقطي وحساب معايير بتسريع SIMD لفهرس المتجهات في الذاكرة؛ ويُطبَّق مرشّح الصلاحيات قبل التقييم.
Hybrid retrieval + RRF		تُدمج أفضل 40 نتيجة من البحث المتجهي والنصي بدمج الرتب التبادلي (RRF)؛ ويُعطى مقتطف القاعدة دفعة صغيرة.
Anthropic C# SDK	12.58.0	حزمة C# الرسمية لإنتاج إجابات المساعد عبر Claude API كتدفق؛ وأنواع الأخطاء وإعادة المحاولة معرَّفة بأنواع.
claude-sonnet-5-5	default model	النموذج الافتراضي claude-sonnet-5-5؛ ويُضبط النموذج ومستوى الجهد من الإعدادات، ويُقرأ مفتاح API من الإعدادات أو مخزن الأسرار فقط.
Citations + prompt caching		تُرسل المقتطفات ككتل مستندات مع تفعيل الاستشهادات، فترتبط كل عبارة بكتلة مصدرها؛ ويُخزَّن موجّه النظام مؤقتًا.
ModelContextProtocol.AspNetCore	2.2.0	خادم MCP للقراءة فقط على /mcp بحزمة MCP الرسمية لـ C#، بأدوات search_documentation وget_page وlist_rules.
Retrieval API		POST /api/rag/retrieve للأنظمة الخارجية: يعيد مقتطفات مع النص وعنوان الاستشهاد ومعرّف الكتلة والإصدار وسجل المصدر كاملًا.
Personal access tokens		مفاتيح وصول شخصية بنطاق وانتهاء وإمكانية إلغاء؛ تُخزَّن بصمتها فقط، وكل استدعاء يعمل بصلاحيات صاحبه.

الويب

واجهة الويب للتطبيق، تُبنى بأنواع مولَّدة من عقد الواجهة البرمجية.

التقنية	الإصدار	دورها في Saha Doküman
React	19.3.1	واجهة الويب مكتوبة بمكوّنات React 19 الدالّية وhooks.
TypeScript	5.9.3	مشروع الويب مكتوب بـ TypeScript الصارم؛ وتُولَّد أنواع الواجهة البرمجية من العقد.
Vite	8.3.4	أداة البناء وخادم التطوير لتطبيق الويب؛ ويمرّر الواجهة البرمجية محليًا.
Tailwind CSS	4.3.3	تُنسَّق الواجهة بـ Tailwind 4؛ وتحافظ الفئات المنطقية على جاهزية التخطيط من اليمين إلى اليسار للعربية.
React Router	7.18.4	توجيه الصفحات في تطبيق الويب.
TanStack Query	5.104.3	يخزّن حالة الخادم (القوائم والصفحات والصلاحيات) مؤقتًا ويدير إعادة الجلب والإلغاء.
openapi-fetch	0.17.0	عميل صغير آمن الأنواع يستدعي الواجهة البرمجية بأنواع OpenAPI.
openapi-typescript	7.13.0	يولّد أنواع TypeScript من عقد docs/openapi.json؛ ويفشل البناء عند تغيّر العقد.
TipTap + @tiptap/markdown	3.32.0	محرك النص المنسّق لمحرر الكتل؛ يقرأ المحتوى ويكتبه بصيغة Markdown.
react-markdown + remark-gfm	10.1.0 / 4.0.1	يعرض المحتوى بأمان (لا يُقبل HTML خام أبدًا)؛ مع دعم جداول GFM وقوائم المهام.
dnd-kit	6.3.1 / 10.0.0	يعيد ترتيب الكتل بالسحب والإفلات.
lucide-react	1.59.0	مجموعة أيقونات الواجهة.
sonner	2.0.8	يعرض ردود الفعل مثل «تم الحفظ» أو «تم الإرسال» كإشعارات منبثقة.
diff	9.0.0	يحسب الفرق بين إصدارين في سجل الإصدارات.

الجوال

قاعدة شيفرة واحدة لـ Android وiOS؛ وتعمل على الويب أيضًا لاختبارات الدخان.

التقنية	الإصدار	دورها في Saha Doküman
Flutter / Dart	3.41.9 / 3.11	يبني تطبيق Android وiOS من قاعدة شيفرة واحدة (Flutter 3.41 وDart 3.11).
flutter_riverpod	3.3.2	إدارة الحالة بـ Notifier وAsyncNotifier وProvider؛ بلا توليد شيفرة.
go_router	17.5.0	توجيه الصفحات التصريحي لتطبيق الجوال.
dio	5.11.1	عميل HTTP الوحيد، مع معترِض مصادقة يجدّد الرمز في تدفق واحد.
flutter_secure_storage	11.2.0	يحفظ رموز الجلسة في المخزن الآمن لنظام التشغيل (Keychain / Keystore).
flutter_markdown_plus	1.0.12	يعرض محتوى الصفحة بصيغة Markdown خلف مكوّن AppMarkdown واحد.
image_picker / file_picker	1.2.4 / 13.1.0	اختيار الصور والملفات؛ وتُرسل الملفات المرفوعة كبايتات (MultipartFile.fromBytes).
url_launcher	6.3.3	يفتح كتل الروابط والعناوين الخارجية في المتصفح.
flutter_localizations + intl	0.20.2	التوطين وتنسيقات التاريخ والأرقام للواجهة التركية والعربية (من اليمين إلى اليسار) والإنجليزية.
shared_preferences	2.5.6	يحفظ تفضيلات المستخدم غير السرية.

البنية التحتية والتشغيل

يعمل sahadoc.com على خادم Linux واحد بـ Docker؛ ولكل شركة قاعدة بياناتها وحاوية خدمتها.

التقنية	الإصدار	دورها في Saha Doküman
Docker + Compose		حزمة الإنتاج معرَّفة بـ Docker Compose: PostgreSQL وOllama والواجهة البرمجية حاويات منفصلة؛ وقاعدة البيانات وOllama على الشبكة الداخلية فقط.
nginx	1.24	ينهي TLS ويحوّل www إلى النطاق الأساسي؛ ويكتب ترويسات X-Forwarded بنفسه، ولا يتضمن سجل الوصول سلسلة الاستعلام ولا ترويسة Authorization.
Let's Encrypt		شهادات TLS مجانية؛ وتُصدر شهادة شاملة (wildcard) للنطاقات الفرعية للشركات بالتحقق عبر DNS.
Multi-tenant hosting		في SaaS تعمل كل شركة بقاعدة بياناتها ومجلد ملفاتها وحاوية تبعياتها؛ والمفاتيح المشتقة لكل شركة تجعل رمز شركة بلا قيمة عند أخرى.
Backup + restore		تُنسخ قاعدة البيانات والملفات احتياطيًا معًا، ويحافظ سكربت الاستعادة على هذا الترابط.
Verification jobs		مهام تتحقق من سلسلة السجل وسلامة الملفات؛ وفي SaaS تمر على قواعد بيانات كل الشركات.
Structured logs		ملفات سجل منظَّمة تدور يوميًا وخالية من القيم السرية؛ وسجلات الحاويات محدودة الحجم.

الجودة

تُتحقق الصلاحيات والخصوصية بالاختبارات وبتدقيق هجومي معًا.

التقنية	الإصدار	دورها في Saha Doküman
xUnit v2	2.9.3	إطار اختبارات الخادم (الإصدار 2).
Shouldly	4.3.0	تأكيدات مقروءة؛ ولا تُستخدم FluentAssertions وMoq عمدًا.
NSubstitute	6.2.0	يحاكي التبعيات في اختبارات الوحدة.
Respawn	7.0.0	يعيد تهيئة قاعدة البيانات بسرعة بين اختبارات التكامل؛ ولكل مجموعة اختبارات قاعدة بياناتها.
ASP.NET Core test host	10.0.13	يختبر الواجهة البرمجية من البداية إلى النهاية في الذاكرة على PostgreSQL حقيقية.
FakeTimeProvider	10.11.0	يختبر السلوك المرتبط بالوقت (التذكيرات ومدد الجلسات) بشكل حتمي.
Persona x endpoint matrix		جدول شخصية × نقطة نهاية لكل نقطة نهاية: يجب أن يحصل غير المخوَّل على 404، وتُضاف كل نقطة جديدة إلى الجدول.
OpenAPI snapshot + JSON samples		وثيقة OpenAPI اختبار لقطة؛ وتغذي عيّنات JSON اختبارات العملاء؛ ويُغيَّر العقد عن قصد.
Vitest	5.0.5	مشغّل اختبارات الويب.
Testing Library (React)	16.3.3	يختبر المكوّنات كما يراها المستخدم.
MSW	3.0.3	يحاكي الواجهة البرمجية على مستوى الشبكة في اختبارات الويب.
flutter_test + mocktail	1.0.5	اختبارات وحدة وواجهات للجوال؛ وتُختبر النماذج بملفات JSON في docs/samples.
Red-team audit		تُفحص كل قناة تسريب (البحث والملفات والإشعارات والمساعد والواجهة البرمجية وMCP) بأشخاص غير مخوَّلين، وتُختبر سيناريوهات سحب الصلاحية.

رحلة الطلب

عندما يبحث مستخدم أو يسأل المساعد يحدث ما يلي بالترتيب.

العميل
يرسل تطبيق الويب أو الجوال (أو أداة خارجية عبر MCP) طلب HTTPS.
nginx
ينتهي TLS هنا؛ وتُكتب ترويسات عنوان العميل والبروتوكول بشكل موثوق.
الهوية والحدود
يُتحقق من الرمز، وتُطبَّق حدود الطلبات، وتُحدَّد الشركة (من النطاق الفرعي في SaaS).
الصلاحيات
يحدد محرك الصلاحيات ما يحق للمستخدم رؤيته؛ وكل ما لا يظهر هو 404.
البيانات والبحث
تُجلب مرشحات البحث النصي والمتجهي من PostgreSQL وتُصفّى بحسب الصلاحية.
الذكاء الاصطناعي (اختياري)
تُفحص المقتطفات المسموحة المختارة مرة أخرى؛ وإذا كان مفعّلًا يكتب Claude الإجابة مع المصادر.
الاستجابة
تعود النتيجة إلى العميل ومعها معلومات المصدر، دون أن تُخزَّن مؤقتًا في أي طبقة وسيطة.

واجهة
خدمة
مخزن بيانات
خارجي
المسار الرئيسي
تدفق بيانات
في الخلفية
مُصفّى بالصلاحيات

رحلة المعلومة

من لحظة كتابتها إلى لحظة العثور عليها: لكل خطوة صاحب، وعلى الطريق أربع نقاط تحقق.

واجهة
نقطة تحقق
خدمة
مخزن بيانات
خارجي
المسار الرئيسي
تدفق بيانات
في الخلفية
مُصفّى بالصلاحيات

أربع نقاط تحقق على الطريق

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

كل تقنية مستخدمة في Saha Doküman