Shared Document Intelligence Service

فحص CPU وRAM وDisk (المساحة الحرة المتاحة) وDocker containers والشبكات والمنافذ المستخدمة والخدمات الفعالة (Project OS، n8n، PostgreSQL، Traefik، Maritime Intelligence، Evolution API) بطريقة read-only دون تعديل أو إعادة تشغيل أي خدمة.

فحص إعدادات PostgreSQL الحالية (إصدار، قواعد البيانات، users، schemas، connection pool، مساحة متاحة) لتحديد إمكانية إنشاء database/schema/user معزول للخدمة. فحص إعدادات Traefik (إصدار، routes، entrypoints، certificates، body size limits الحالية) لتحديد إمكانية إضافة route-scoped limits دون تغيير الإعدادات العامة.

بناءً على نتائج الفحص: (1) توثيق ما إذا كانت مساحة القرص والذاكرة تسمح بقبول ملفات حتى 1GB كحد مبدئي قابل للإعداد، وتحديد الحد العملي الآمن. (2) تقييم إمكانية تشغيل OCR محلي على VPS مع Docker CPU/RAM limits دون التأثير على الخدمات الإنتاجية. (3) تحديد ما إذا كان PostgreSQL الحالي مناسبًا كـ persistent job store أو الحاجة لـ Redis موثقة.

إنتاج تقرير قرار واضح يتضمن: موارد VPS الفعلية (CPU/RAM/Disk المتاح)، مساحة التخزين المتاحة للملفات المؤقتة، تقنية backend المقترحة، persistent job store (PostgreSQL معزول أو بديل موثق — لا Redis تلقائي)، queue، OCR المحلي المشروط بنتائج الموارد أو الخارجي، Provider Router، سياسة الملفات الكبيرة والحد القابل للإعداد، وأثر كل اختيار على الخدمات الموجودة. مراحل التثبيت والتنفيذ تبقى blocked/pending حتى مراجعة المستخدم واعتماد القرارات. البوابة ليست failed بل نقطة مراجعة إلزامية. إذا كان Project OS لا يدعم pause تلقائي بين المراحل، يُوثق ذلك بوضوح ولا تبدأ تغييرات بنيوية أو تثبيت خدمات ثقيلة تلقائيًا.

تصميم المعمارية الكاملة: (1) فصل معماري واضح بين Native Text Extraction وOCR وVision OCR وLLM Analysis وTranslation كطبقات مستقلة. (2) سلسلة معالجة الوثائق (Original → Native/OCR Text → Normalized Text → Analysis → Translation → Structured Facts) مع عدم استبدال أي مرحلة بالأخرى. (3) Provider Router يدعم مزودين متعددين مع quality gates. (4) سياسة external provider: لا إرسال لأي وثيقة أو نص إلى Ollama Cloud أو أي external provider إلا إذا كان مفعّلًا بوضوح مع credentials معتمدة وسياسة مشروع تسمح بالخارج — وإلا استخدام local/mock provider أو إعادة warning/error واضح. لا تنشئ credentials أو حسابات افتراضية. (5) تعريف confidence بطريقة قابلة للتفسير: provider confidence عند توفرها + text-quality heuristics + schema validation + field validation — يمنع اعتماد رقم يخترعه LLM، وإذا لم توجد ثقة قابلة للقياس تكون null مع warning وconfidence_source واضح.

كتابة OpenAPI spec كامل لـ /api/v1 يشمل: (1) رفع وثيقة وبدء job مع streaming/chunked/resumable upload endpoints وupload progress وchecksum verification لكل chunk. (2) الحصول على job ID، متابعة status وprogress على مستوى الرفع والمعالجة والصفحة. (3) إلغاء Job (cancel) عندما تسمح حالتها بذلك. (4) حذف الملف والنتائج المؤقتة مبكرًا (early delete). (5) expires_at وretention metadata لكل job. (6) Idempotency-Key header كآلية idempotency موثقة لا تعتمد على content hash وحده. (7) standardized error response model موحد لكل endpoints. (8) فصل /health/live عن /health/ready. (9) tenant authorization على كل status/result/delete/retry/cancel endpoint — لا وصول لنتائج مشروع عبر API key مشروع آخر. (10) إعادة معالجة صفحات فاشلة محددة.

تعريف: (1) نموذج job metadata بحالات (queued, uploading, processing, completed, completed_with_warnings, failed, cancelled) مع timestamps وerror codes ورسائل أخطاء آمنة وexpires_at وretention metadata. (2) بنية provenance تفصيلية على مستوى الملف والصفحة وطرق الاستخراج (provider، model، version، extraction method، confidence_source). (3) نموذج أمان: per-project API keys مخزنة كـsecure hashes (bcrypt/argon2) مع key identifier فريد ودعم rotation/revocation — لا حفظ للمفاتيح الخام في قاعدة البيانات أو logs. credentials داخل secrets/environment الآمنة ولا تظهر في API أو Console. (4) سياسة retention افتراضية قابلة للإعداد (مثل 24 ساعة بعد اكتمال المهمة) مع منع cleanup من حذف chunks أو ملفات أو نتائج تستخدمها job نشطة. (5) تنظيف uploads غير المكتملة بعد مهلة منفصلة. (6) تسجيل cleanup metadata دون تسجيل محتوى الوثيقة.

إنشاء مشروع /opt/document-intelligence مع Dockerfile وdocker-compose مستقل (أو منضم لشبكة Traefik الحالية دون تعديل routes)، بنية مجلدات، إعدادات environment variables بما فيها configurable maximum upload size وretention defaults وexternal provider enablement flags (معطلة افتراضيًا). لا تثبيت خدمات ثقيلة أو مكررة.

تنفيذ: (1) per-project API key authentication مع تخزين المفاتيح كـsecure hashes (bcrypt/argon2) — لا حفظ للمفاتيح الخام في قاعدة البيانات أو logs. (2) key identifier فريد لكل مفتاح ودعم rotation/revocation. (3) credentials داخل secrets/environment الآمنة ولا تظهر في API أو Console. (4) file signature validation (magic bytes) وأسماء ملفات آمنة ومنع path traversal. (5) smart pixel/decompression bomb protection. (6) كشف PDF المحمية بكلمة مرور وإعادة warning واضح (لا دعم لكلمة مرور مؤقت في MVP). (7) tenant authorization على كل endpoint.

تنفيذ endpoints: رفع وثيقة وبدء job، الحصول على job status وprogress، استرجاع النتائج، إلغاء job (cancel)، حذف ملف ونتائج مؤقتة مبكرًا، إعادة معالجة صفحات فاشلة، /health/live و/health/ready منفصلين، standardized error response model. دعم source channels: direct upload من Operations Console، REST API من مشاريع خارجية، ومراجع آمنة. في هذه المرحلة endpoints تعمل لكنها ترجع stub responses أو queued status — الربط الفعلي بـ queue وpipeline يتم في Phase 6.

تنفيذ streaming upload وresumable/chunked upload للملفات الكبيرة (300-500MB+) بحيث لا يُحمّل الملف كاملًا في RAM. يشمل: تقسيم الرفع إلى chunks، progress للرفع على مستوى chunk وملف، checksum لكل chunk، Idempotency-Key header كآلية idempotency موثقة، expires_at وretention metadata للملفات المرفوعة، وتنظيف uploads غير المكتملة بعد مهلة منفصلة.

بناء persistent job store إلزامي: (1) استخدام PostgreSQL الحالي عبر database/schema/user معزول إذا أثبت audit أنه مناسب، أو persistent alternative موثق (لا Redis تلقائيًا إلا إذا أثبت audit الحاجة). (2) تخزين job metadata كامل في persistent store مع حالات (queued, uploading, processing, completed, completed_with_warnings, failed, cancelled) وtimestamps وexpires_at وretention metadata. (3) يُمنع استخدام in-memory-only queue كتنفيذ إنتاجي. (4) restart/recovery: بعد إعادة تشغيل الخدمة، استرجاع jobs النشطة من persistent store واستئنافها أو تعليمها كـinterrupted مع warning.

بناء job queue وworker للمعالجة غير المتزامنة مع حالات واضحة. progress tracking على مستوى الرفع والمعالجة والصفحة والمرحلة. دعم partial success (completed_with_warnings) عند فشل صفحات محددة مع استمرار المعالجة. عزل أخطاء على مستوى الصفحة — فشل صفحة لا يوقف الوثيقة كاملة. worker يستهلك من persistent queue وليس من in-memory queue.

تنفيذ: (1) Idempotency-Key header كآلية idempotency موثقة لا تعتمد على content hash وحده — نفس Idempotency-Key يرجع نفس job ID. (2) retry policy محدودة ومدروسة للفشل المؤقت على مستوى الصفحة والمرحلة. (3) إعادة معالجة صفحات فاشلة محددة دون إعادة معالجة الوثيقة كاملة. (4) retention افتراضي قابل للإعداد (مثل 24 ساعة بعد اكتمال المهمة). (5) منع cleanup من حذف chunks أو ملفات أو نتائج تستخدمها job نشطة. (6) تنظيف uploads غير المكتملة بعد مهلة منفصلة. (7) تسجيل cleanup metadata دون تسجيل محتوى الوثيقة. (8) حذف مبكر للملف والنتائج المؤقتة عند طلب cancel أو early delete.

بناء طبقات مستقلة: Native Text Extraction وOCR وVision OCR كـ provider interfaces منفصلة (LLM ليس OCR الوحيد). تنفيذ: (1) native PDF text extraction مع fallback إلى OCR عند غياب النص الأصلي أو عدم كفايته. (2) OCR محلي مشروط بنتائج audit للموارد — إذا كانت الموارد لا تسمح، استخدم external OCR provider مفعّل أو أعد warning/error واضح. (3) تقسيم الوثائق متعددة الصفحات إلى صفحات/batches مع الحفاظ على ترتيب الصفحات. (4) معالجة الصور بما في ذلك صور هاتف وScanner عالية الدقة مع limits على الأبعاد وحماية من decompression bombs. (5) لا إرسال لأي وثيقة أو نص إلى Ollama Cloud أو أي external provider إلا إذا كان مفعّلًا بوضوح مع credentials معتمدة وسياسة المشروع تسمح بالإرسال الخارجي — وإلا استخدم local/mock provider حسب البيئة أو أعد warning/error واضح. لا تنشئ credentials أو حسابات افتراضية.

تنفيذ Provider Router يدعم مزودين ونماذج وحسابات متعددة: (1) دعم حسابي Ollama Cloud مع التحويل من الحساب الأول إلى الثاني عند quota/rate-limit/provider failure — فقط إذا كان external provider مفعّلًا بوضوح مع credentials معتمدة. (2) cooldown وcircuit breaker لكل مزود/حساب. (3) quality gates تقارن نتائج OCR من مزودين عند الحاجة. (4) enforcement صارم: إذا لم يكن external provider مفعّل أو credentials غير متاحة، استخدم local/mock provider أو أعد warning/error واضح — لا تقع في silent failure أو إرسال غير مصرح. (5) لا تنشئ credentials أو حسابات افتراضية.

تنفيذ: (1) كشف اللغة (عربية، فرنسية، إنجليزية، متعدد اللغات). (2) الدارجة المغربية وArabizi: في MVP يمكن اكتشاف النص كـmixed/unknown أو best-effort فقط دون ادعاء دعم كامل — الدعم والتحسين والاختبارات المعيارية الكاملة تبقى في Future Capabilities. (3) كشف بنية الوثيقة ونوع الوثيقة. (4) التلخيص. (5) استخراج حقول وحقائق منظمة (JSON output) من النص المحلل مع provenance. (6) تعريف confidence بطريقة قابلة للتفسير: provider confidence عند توفرها + text-quality heuristics + schema validation + field validation — يمنع اعتماد رقم يخترعه LLM. إذا لم توجد ثقة قابلة للقياس، تكون القيمة null مع warning وconfidence_source واضح (مثل 'provider' أو 'heuristic' أو 'schema_validation' أو 'null_no_measureable_confidence').

تنفيذ: (1) translation provider abstraction مع provider أولي للترجمة الاختيارية، مرتبط بـ Provider Router، مع نفس سياسة external provider (لا إرسال إلا إذا مفعّل بوضوح). (2) تسجيل provenance تفصيلية لكل مرحلة: provider، model، version، extraction method، page/batch، confidence_source، timestamps. (3) الحفاظ على سلسلة البيانات (Original → Native/OCR Text → Normalized Text → Analysis → Translation → Structured Facts) دون استبدال أي مرحلة بالأخرى. (4) النتائج مشتقة وقابلة للتتبع إلى الملف والصفحة وطريقة الاستخراج.

ربط جميع API endpoints بالمعالجة الفعلية: (1) رفع وثيقة → إنشاء job في persistent queue → تمرير لـ pipeline. (2) status/progress → قراءة من persistent job store. (3) results → قراءة من persistent store مع tenant authorization. (4) cancel → إيقاف job إذا سمحت حالتها + حذف مبكر للملفات المؤقتة. (5) retry → إعادة معالجة صفحات فاشلة محددة. (6) early delete → حذف ملف ونتائج مؤقتة مع تحديث job state. (7) التأكد من أن كل endpoint يطبق tenant authorization وIdempotency-Key وstandardized error model.

إنتاج عقد API موثق مخصص لاحتياجات Maritime (إرسال وثيقة، استرجاع extracted text وanalysis وstructured facts وconfidence وwarnings وprovenance)، مع test suite مستقل يحاكي استدعاءات Maritime دون لمس كود Maritime أو تعديله. تحديد ما يطبقه Maritime (قواعد العمل، التنبيهات، الربط بالسفن) مقابل ما توفره الخدمة (استخراج، تحليل، حقائق منظمة). وضع خطة تكامل تدريجية: إرسال وثيقة من Maritime إلى الخدمة، استلام النتائج، عرضها في Inbox للمراجعة البشرية، ثم Commit بعد الموافقة — كمرحلة لاحقة بعد MVP.

إنشاء Operations Console ويب محمية (ليست للعامة) تشمل: (1) عرض active/recent jobs مع المصدر والمشروع المستدعي (source_channel، source_project، external_correlation_id). (2) حالة الرفع والمعالجة وprogress على مستوى الصفحة. (3) عرض extracted text وanalysis وstructured facts وconfidence (مع confidence_source) وwarnings وprovenance. (4) إدارة الصفحات الفاشلة وإعادة المعالجة. (5) عزل tenants — tenant عادي لا يرى بيانات tenant آخر. (6) لا عرض لـ API keys الخام أو credentials في Console — عرض key identifier فقط مع إمكانية rotation/revocation. (7) عرض expires_at وretention metadata لكل job. (8) دعم RTL/Arabic في الواجهة.

اختبار: native PDF، scanned PDF، صورة (بما في ذلك صور هاتف وScanner عالية الدقة A4 at 600 DPI)، عربية، فرنسية، إنجليزية، متعدد اللغات، Unicode واتجاه النص العربي، ترتيب الصفحات، provenance تفصيلية، confidence مع confidence_source، partial success، ملفات كبيرة 300-500MB مع resumable upload. الدارجة المغربية وArabizi: اختبار best-effort فقط — اكتشاف كـmixed/unknown دون ادعاء دعم كامل. التحقق من سلسلة البيانات (Original → Native/OCR → Normalized → Analysis → Translation → Structured Facts) وعدم استبدال أي مرحلة.

اختبار: (1) API authentication وproject isolation — التأكد من عدم تسريب بيانات بين المشاريع عبر API وOperations Console وlogs. (2) tenant authorization على كل status/result/delete/retry/cancel endpoint. (3) API keys مخزنة كـsecure hashes — التأكد من عدم وجود مفاتيح خام في DB أو logs. (4) external provider policy: التأكد من عدم إرسال وثائق لـ external provider عندما يكون معطّلًا — استخدام local/mock أو warning/error. (5) confidence: التأكد من عدم اعتماد أرقام يخترعها LLM — null مع warning عند غياب ثقة قابلة للقياس. (6) Idempotency-Key: نفس key يرجع نفس job. (7) retention وcleanup: لا حذف لموارد تستخدمها jobs نشطة. (8) /health/live و/health/ready منفصلين. (9) password-protected PDF detection. (10) provider failover بين حسابي Ollama Cloud عند التفعيل.

مراقبة استهلاك CPU وRAM وDisk أثناء تشغيل الخدمة تحت حمل (بما في ذلك معالجة ملفات كبيرة 300-500MB وOCR محلي إن وُجد)، والتأكد من عدم التأثير على Project OS وn8n وPostgreSQL وTraefik وMaritime Intelligence وEvolution API. اختبار restart/recovery: إعادة تشغيل الخدمة أثناء jobs نشطة والتحقق من استرجاعها من persistent store.

اختبار مسار Telegram via n8n باستخدام workflow اختبار معزول ومعطل افتراضيًا أو محاكاة مستقلة — لا تعديل لـ workflow إنتاجي قائم. التحقق من استلام وثيقة من محاكاة Telegram وتمريرها للخدمة واسترجاع النتائج. طلب موافقة صريحة قبل ربط workflow الاختبار بتدفق Telegram الحقيقي. توثيق نتائج الاختبار وما هو مطلوب للربط الفعلي.

إضافة route جديد في Traefik للخدمة دون تعديل routes الموجودة. فحص إصدار Traefik الفعلي واستخدام route-scoped upload limits/timeouts/buffering بالطريقة التي يدعمها هذا الإصدار — لا افتراض لاسم إعداد محدد قبل الفحص. لا تغيير للإعدادات العامة أو routes الحالية. لا نشر DNS أو domain جديد دون إعداد معتمد. ضبط limits لدعم الملفات الكبيرة (حتى الحد المحدد بعد audit). إعداد health checks (/health/live و/health/ready) في docker-compose. إجراء rollback آمن جاهز.

كتابة تعليمات تشغيل وإيقاف وrollback آمنة، إجراءات المراجعة، سياسة retention وtemp file cleanup (قابلة للإعداد، افتراضي 24 ساعة)، خطوات استرجاع بعد restart من persistent store، قائمة contacts/responsibilities، إعدادات configurable maximum upload size وretention وexternal provider enablement flags، وتعليمات rotation/revocation لـ API keys.

وضع خطط تفصيلية لـ: (1) استخراج الجداول من PDF والصور. (2) استيراد الأرشيف التاريخي لـ VIKINGBANK وفق مسار Scan → Extract → Propose → Human Review → Commit. (3) الدعم الكامل للدارجة المغربية وArabizi في OCR والتحليل مع اختبارات معيارية كاملة — في MVP كان مجرد اكتشاف best-effort كـmixed/unknown. (4) إدخال password مؤقت للـPDF المحمية. (5) التكامل الفعلي مع Maritime Intelligence: إرسال وثيقة من Maritime، استلام النتائج، عرض في Inbox للمراجعة البشرية، ثم Commit بعد الموافقة. (6) ربط Telegram الحقيقي بعد موافقة. (7) توسيع الترجمة لدعم لغات إضافية.