Edit project

Update the project definition, status, priority, and metadata.

Name *

Short description

Full description

اسم المشروع:
Shared Document Intelligence Service

الهدف:
إنشاء خدمة مركزية مستقلة لمعالجة الوثائق وفهمها، تعمل كخدمة Infrastructure مشتركة على VPS Ubuntu في Hostinger، ويمكن لعدة مشاريع استدعاؤها عبر REST API موحدة.

هذه الخدمة ليست تطبيقًا نهائيًا للمستخدم، وليست جزءًا داخليًا من Project OS أو Maritime Intelligence. يجب إنشاؤها كمشروع مستقل، مع إمكانية استخدامها لاحقًا من Maritime Intelligence & Vessel Operations وDocument Translation Platform ومشاريع أخرى.

المسار المقترح:
 /opt/document-intelligence

مهم جدًا:
قبل اعتماد أي تقنية أو تعديل الخادم، يجب فحص البنية الحالية للـVPS بطريقة غير مدمرة، بما يشمل CPU وRAM وDisk وDocker والشبكات والمنافذ والخدمات والحاويات الموجودة. توجد حاليًا خدمات فعالة مثل Project OS وn8n وPostgreSQL وTraefik وMaritime Intelligence وEvolution API وتكاملات WhatsApp وTelegram. يجب إعادة استخدام البنية المشتركة المناسبة عند الإمكان، وعدم تثبيت خدمة مكررة أو تغيير أو تعطيل أي خدمة موجودة.

المبدأ المعماري:
Shared Engine ≠ Shared Data.

نريد محرك معالجة مشتركًا، لكن يجب أن تبقى بيانات كل مشروع معزولة. وثائق Maritime لا تختلط بوثائق Translation أو أي مشروع آخر.

يفضل أن تكون الخدمة stateless قدر الإمكان. يحتفظ المشروع المستدعي بالملفات والبيانات الدائمة، بينما يسمح للخدمة باستخدام temporary storage وjob metadata عند الحاجة، مع سياسة واضحة للتنظيف والاسترجاع بعد إعادة التشغيل.

المسؤوليات:
تستقبل الخدمة الوثائق أو مراجع آمنة إليها، وتستخرج النص، وتطبق OCR عند الحاجة، وتحدد اللغة والبنية ونوع الوثيقة، ثم تعيد نتائج منظمة مع confidence وwarnings وprovenance.

الخدمة لا تطبق Business Logic الخاص بالمشاريع المستدعية.

مثال:
يمكن للخدمة اكتشاف أن الوثيقة vessel_license واستخراج vessel_name وIMO وissue_date وexpiry_date. لكنها لا تسجل الرخصة داخل Maritime، ولا تربطها بالسفينة، ولا تنشئ تنبيه انتهاء. هذه القرارات تبقى مسؤولية Maritime Intelligence.

القدرات المستهدفة:
- PDF يحتوي على نص أصلي.
- scanned PDF.
- الصور.
- الوثائق متعددة الصفحات.
- native PDF text extraction.
- OCR عند غياب النص الأصلي أو عدم كفايته.
- العربية والفرنسية والإنجليزية.
- الوثائق متعددة اللغات.
- الدارجة المغربية.
- الدارجة المكتوبة بالحروف اللاتينية وArabizi.
- الحفاظ على ترتيب الصفحات.
- اكتشاف بنية الوثيقة.
- استخراج الجداول عندما يكون ذلك ممكنًا.
- اكتشاف نوع الوثيقة.
- استخراج حقول وحقائق منظمة.
- JSON output.
- التلخيص.
- الترجمة الاختيارية.
- confidence scores.
- warnings وحالات عدم اليقين.
- provenance على مستوى الملف والصفحات وطرق الاستخراج.
- asynchronous jobs.
- job status وprogress.
- API authentication.
- عزل المشاريع.
- health monitoring.

يجب الحفاظ دائمًا على سلسلة البيانات التالية وعدم استبدال أي مرحلة بالأخرى:

Original Document
→ Native Extracted Text أو OCR Text
→ Normalized Text Representation
→ Analysis
→ Translation
→ Structured Facts

الوثيقة الأصلية لا تُستبدل مطلقًا بنتيجة OCR أو الترجمة أو تحليل LLM. يجب أن تكون النتائج مشتقة وقابلة للتتبع إلى الملف والصفحة وطريقة الاستخراج.

معمارية المزودين:
لا تربط النظام بشكل دائم بمحرك OCR أو LLM أو ترجمة واحد.

أنشئ provider abstraction واضحة تشمل:
- OCR provider.
- LLM/analysis provider.
- Translation provider.

يجب أن تتمكن الخدمة لاحقًا من تغيير المزود أو إضافة fallback دون تغيير API التي تستخدمها المشاريع الأخرى.

لا تفترض أن تشغيل نماذج AI ثقيلة محليًا على VPS هو القرار الصحيح. افحص موارد الخادم أولًا، ثم اقترح ما يمكن تشغيله محليًا وما يحتاج إلى external/cloud provider. لا تثبت نموذجًا ثقيلًا قبل فحص الموارد وإجراء قرار موثق.

REST API:
صمّم API موحدة وقابلة للإصدار، مثل /api/v1، لدعم:
- رفع وثيقة وبدء job.
- الحصول على job ID.
- متابعة status وprogress.
- الحصول على بيانات الملف والصفحات.
- text extraction.
- OCR.
- document analysis.
- structured extraction.
- summary.
- optional translation.
- result retrieval.
- health/readiness checks.

يجب ألا يحتاج Maritime أو أي مستهلك آخر إلى معرفة اسم OCR أو LLM المستخدم خلف الخدمة.

MVP:
ابدأ بأصغر نسخة عملية قابلة للاختبار:

Upload PDF أو image
→ Validate file
→ Detect document properties
→ Native text extraction أو OCR عند الحاجة
→ Extracted text
→ Language detection
→ Basic document analysis
→ Structured JSON
→ Optional translation
→ Provenance
→ Confidence and warnings
→ Job status and API response

لا تحاول تنفيذ جميع القدرات المتقدمة في النسخة الأولى. ضع القدرات المستقبلية في مراحل لاحقة دون تضخيم MVP.

Test Interface:
أنشئ واجهة ويب بسيطة للاختبار الداخلي فقط، وليست منصة Document Translation النهائية.

يجب أن تسمح برفع PDF أو صورة وعرض:
- الملف ومعلوماته.
- حالة المهمة ونسبة التقدم.
- طريقة الاستخراج: native text أو OCR.
- النص المستخرج حسب الصفحات.
- اللغة المكتشفة.
- structured data.
- confidence.
- warnings.
- optional translation.
- الأخطاء إن وجدت.

الأمان والعزل:
- يمنع وضع secrets أو API keys في frontend أو repository.
- استخدام credentials/API keys منفصلة لكل مشروع مستهلك.
- التحقق من هوية المشروع في كل طلب.
- project/tenant isolation.
- file signature validation، وليس الاعتماد على extension فقط.
- تحديد أنواع وأحجام الملفات المقبولة.
- أسماء ملفات آمنة ومنع path traversal.
- temporary file cleanup.
- timeouts وresource limits.
- audit/provenance metadata.
- عدم تسجيل محتوى الوثائق الحساسة أو secrets في logs.
- عدم تعريض Test Interface للعامة دون حماية.
- عدم كسر أو تغيير الخدمات الموجودة.
- استخدام Traefik الحالي فقط بعد فحص إعداداته، مع عدم تعديل routes الموجودة بصورة خطرة.

الـJobs والاسترجاع:
قد تستغرق OCR والترجمة والتحليل وقتًا، لذلك يجب دعم asynchronous jobs بحالات واضحة مثل:
queued, processing, completed, failed, cancelled.

يجب أن يدعم التصميم:
- progress.
- timestamps.
- error codes ورسائل أخطاء آمنة.
- retry policy محدودة ومدروسة.
- idempotency لتجنب تكرار نفس الطلب دون قصد.
- استرجاع حالة المهام بعد restart عندما يكون ذلك ضمن MVP أو توثيق واضح إن أُجّل.
- تنظيف الملفات المؤقتة دون حذف نتيجة ما زال المشروع المستدعي يحتاجها.

Database and storage:
لا تنشئ PostgreSQL أو Traefik أو بنية مشتركة جديدة تلقائيًا إذا كانت الموجودة مناسبة.

افحص أولًا:
- هل يمكن استخدام PostgreSQL الحالي عبر database/schema/user منفصل؟
- هل تحتاج الخدمة قاعدة بيانات فعلًا في MVP أم يكفي تخزين metadata/jobs محدود؟
- أين تحفظ الملفات المؤقتة؟
- من يملك الملف الأصلي والنتيجة الدائمة؟
- ما سياسة retention وcleanup؟

يجب أن تكون ملكية البيانات واضحة، وأن تبقى الملفات الدائمة لدى المشروع المستدعي كلما أمكن.

التكامل الأول:
سيكون Maritime Intelligence & Vessel Operations أول مستهلك للخدمة.

Maritime يستقبل حاليًا معلومات من WhatsApp وTelegram وManual Entry، ويحافظ على provenance وInbox وArchive ومراجعة بشرية.

لاحقًا يرسل Maritime وثيقة إلى هذه الخدمة، ويحصل على extracted text وanalysis وstructured facts وconfidence وwarnings، ثم يطبق Maritime قواعده الخاصة والمراجعة البشرية.

لا تعدّل Maritime في MVP الأول للخدمة. جهّز عقد API موثقًا واختبار تكامل مستقلًا، ثم اجعل التكامل الفعلي مرحلة لاحقة بعد نجاح الخدمة منفردة.

Historical Maritime Archive:
يوجد أرشيف تاريخي كبير على قرص خارجي خاص بالسفينة VIKINGBANK ووثائق سنوات سابقة. لا تستورده الآن.

ضع الاستيراد التاريخي كمرحلة مستقبلية منفصلة بعد نجاح الخدمة، وفق المسار:

Scan
→ Extract
→ Propose
→ Human Review
→ Commit

يمنع إدخال الحقائق المستخرجة مباشرة إلى قاعدة Maritime عندما تكون غير مؤكدة أو قبل المراجعة المطلوبة.

الاختبارات المطلوبة:
أنشئ خطة اختبار فعلية باستخدام عينات آمنة، تشمل:
- native PDF.
- scanned PDF.
- image.
- Arabic.
- French.
- English.
- mixed-language.
- multi-page document.
- Unicode واتجاه النص العربي.
- page ordering.
- provenance.
- structured JSON validation.
- API authentication.
- project isolation.
- invalid file and oversized file.
- OCR/provider failure.
- timeout and retry behavior.
- temporary cleanup.
- restart/recovery.
- resource consumption.
- عدم التأثير على الخدمات الأخرى.

شروط التنفيذ:
- ابدأ بمرحلة Discovery/Audit غير مدمرة للبنية الحالية.
- افصل بوضوح بين القرارات المؤكدة والافتراضات.
- أي قرار بين تقنيات متعددة يجب توثيق أسبابه ومقارنته بالبدائل.
- لا تثبت خدمات أو نماذج ثقيلة قبل فحص موارد الـVPS.
- لا تعدّل الخدمات الموجودة لمجرد تسهيل المشروع.
- لا تعتبر المهمة مكتملة بمجرد إنشاء ملفات أو نجاح build.
- كل مرحلة تنفيذية يجب أن تحتوي على acceptance criteria واختبارات قابلة للإثبات.
- وفر OpenAPI documentation وأمثلة request/response.
- استخدم health وreadiness checks.
- وفر تعليمات تشغيل وإيقاف وrollback آمنة.
- لا تنفذ تغييرات مدمرة أو حذفًا أو migrations خطرة.
- اجعل خطة التنفيذ تدريجية وقابلة للمراجعة قبل الانتقال إلى النشر أو التكامل.

المخرجات المطلوبة من AI Planner:
أنشئ Roadmap متوازنة، لا تتضمن عددًا مبالغًا فيه من المراحل أو المهام، وتفصل بين:

1. Discovery and VPS audit.
2. Architecture and API contract.
3. Secure MVP implementation.
4. Provider abstraction and document pipeline.
5. Asynchronous jobs and status.
6. Internal Test Interface.
7. Testing, security and resource validation.
8. Safe deployment using existing infrastructure.
9. Maritime integration contract and future integration.
10. Future capabilities مثل advanced tables، historical archive import، وتوسيع الترجمة.

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

Status

Priority

Progress (0–100)

Target date

Tags (comma-separated)

Blockers (one per line)

Cancel