Edit task

## Task
2.2 Design REST API contract with expanded OpenAPI specification

كتابة 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) إعادة معالجة صفحات فاشلة محددة.

Current phase: Phase 2: Architecture and API Contract

Project context: Shared Document Intelligence Service — خدمة مركزية مستقلة لمعالجة الوثائق وفهمها

## Project requirements (authoritative)
The full project description below is the authoritative requirement source. Concrete values it specifies (site URLs, names, labels, texts) are part of the deliverable — never substitute placeholder or example values (e.g. example.com) for them.
اسم المشروع:
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 authenticatio

## Deliverable quality baseline (applies to user-facing output)
If this task produces or changes anything the user sees in a browser, the result must look deliberately crafted — never scaffold-like or raw default markup:
- Clear visual hierarchy: a real page structure with headings, grouping and whitespace — not a bare dump of unstyled elements.
- Deliberate typography and spacing: readable font sizes and line-height, consistent padding/margins; interactive controls (buttons, inputs, links) must be visibly styled, never browser-default only.
- A coherent, restrained color palette (background, text, accent) with accessible contrast.
- Responsive layout: the page must stay usable on a narrow (mobile) viewport.
- Interactions must genuinely work: every control the description asks for performs the requested behavior, and purely local behavior (e.g. a confirmation/status message on click) is implemented client-side — no external service is needed for simple local feedback.
- Accessibility basics: semantic HTML, labels for inputs, alt text for images.
- Status/progress/success/error banners must set BOTH an explicit opaque background and an explicit foreground color that keep high contrast against each other in every state — never a translucent background, never inherited or white text over a light surface, and the text must stay readable when the browser applies its own dark/forced rendering.
- Arabic/RTL correctness: the document must set lang="ar" and dir="rtl", declare UTF-8 charset, and use natural Arabic wording and typography (no machine-stiff phrasing, no reversed or Latin-mixed layout artifacts).
This is a minimum quality floor, not a template: keep full creative freedom in design, layout and copy.

## Native automation (use this instead of building your own backend)
Native automation available for this project (Project OS platform capability).
A managed backend automation of kind 'site.check' is already provisioned for this project.
Use it from the browser via these SAME-ORIGIN endpoints (fetch, JSON):
- POST /api/app/automations/<automationId>/run  body: {"sites":[{"url":"https://…","label":"…"}]}
  → 200 {runId} | 400 {error} | 404 {error} | 429 {error}. Sites: 1..20, https public hostnames only.
- GET /api/app/automations/runs/<runId>  → {status, error?, result?}
  status: PENDING | RUNNING | SUCCEEDED | FAILED; result = {kind:'site.check', summary, results:[{url,label?,ok,statusCode?,latencyMs?,error?}]}.
Poll the run endpoint every ~2s while status is PENDING/RUNNING (timeout ~120s), then render per-site results.
STRICT RULES:
- Check EXACTLY the target sites the project's requirements define. Never substitute invented placeholder or example domains (e.g. example.com) for the project's real targets.
- NEVER render or build fields for webhook URLs, callback URLs, tokens, credentials, run ids of the platform, or any n8n concept. The end user must never see infrastructure.
- NEVER POST to any other host from the app; the automation is invoked exclusively through the run endpoint above.
- While a run is RUNNING show a friendly 'checking…' state; on FAILED show the run's error string and per-site results if present. Never fake results.
- The <automationId> above is a stable id for this project's automation; store it as a constant, not as user input.

Acceptance criteria:
- Implement the task: 2.2 Design REST API contract with expanded OpenAPI specification
- Cover the task description above.
- Keep the change scoped to what this task needs.
- Do not introduce secrets or credentials in code.
- Leave the repository in a consistent state (no stray debug output).
- User-facing output must satisfy the deliverable quality baseline above (deliberate styling, responsive layout, working interactions).
- The deliverable must be a correct Arabic RTL document (lang="ar", dir="rtl", UTF-8) with polished Arabic content.