> ## Documentation Index
> Fetch the complete documentation index at: https://docs.resq.software/llms.txt
> Use this file to discover all available pages before exploring further.

# المفاهيم

> كيف تتلاءم قطع ResQ Tactical OS معًا: الشبكة المتراصة، سلسلة الأدلة، تدفق المهام، ونطاقات صلاحيات المشغّل.

هذه هي الخريطة المفاهيمية. اقرأها مرة واحدة قبل مرجع API وستتجمّع بقية
الوثائق بسرعة.

## الشبكة المتراصة

يعمل ResQ كـ**شبكة متراصة لامركزية**، وليس كسحابة بنمط hub-and-spoke.
تشكّل الطائرات بدون طيار والوحدات الأرضية ومحطات المشغّل شبكة نظراء
تستمر في العمل عند تعطل البنية التحتية الأمامية أو عدم توفّرها.

* تتواصل العقد عبر وسائط ذات أولوية محلية (راديو الشبكة، LTE، Wi-Fi)
  وتتزامن مع السحابة عند توفّر الفرصة.
* تم تصميم Coordination API للاستمرار في قبول القياس عن بُعد وتقديم
  الحالة المباشرة عند تدهور تبعياتها الأمامية.
* لا توجد نقطة فشل وحيدة. إذا انقطع منسّق، تستمر العقد النظيرة في
  تبادل القياس عن بُعد وإدراج العمل في الطابور.

ستظهر هذه الحالة في API كـ `503 Service Unavailable` لبعض المسارات
أثناء الانقطاعات الجزئية — راجع [الأخطاء](/ar/errors) لإرشادات إعادة
المحاولة.

```mermaid theme={null}
flowchart LR
  subgraph mesh["Local mesh — keeps operating when upstream is unreachable"]
    direction TB
    D["Drone fleet"] <--> G["Ground units"]
    G <--> O["Operator stations"]
    D <--> O
  end

  mesh -. "opportunistic reconcile<br/>mesh radio · LTE · Wi-Fi" .-> C["Coordination API<br/>live fleet state"]
  C --> I["Infrastructure API<br/>persistent state"]

  C -. "degraded: 503 on some routes,<br/>peers keep sharing telemetry" .-> mesh
```

## الأدلة والسلسلة

كل إجراء ذي عواقب في المهمة ينتج **دليلاً**:

1. تلتقط الطائرات بدون طيار إطارات المستشعرات والفيديو والقياس عن بُعد
   المُهيكل.
2. تُثبَّت ملفات الأدلة على **IPFS** ويُشار إليها عبر CID
   (مُعرِّف معتمد على المحتوى).
3. تُربَط الـ CIDs على **Solana**، مما يُنتج سلسلة محصَّنة ضد التلاعب.
4. يكشف Infrastructure API كلا النصفين: `/evidence` لحمولة IPFS،
   و `/blockchain/*` لنقاط الربط على السلسلة.

هذا يُمكّن المراجعة بعد الحدث ومراجعة سلسلة العهدة دون الثقة بأي طرف
وحيد — يمكن لأي شخص لديه CID والمرجع على السلسلة التحقق من البايتات.

```mermaid theme={null}
sequenceDiagram
  autonumber
  participant D as Drone
  participant API as Infrastructure API
  participant IPFS
  participant SOL as Solana
  participant V as Any verifier

  D->>API: sensor frames, video, telemetry
  API->>IPFS: pin evidence payload
  IPFS-->>API: CID (content-addressed)
  API->>SOL: anchor CID on chain
  SOL-->>API: transaction reference

  Note over IPFS,SOL: Checks retrieved bytes against the anchored<br/>CID and chain record. Establishes integrity,<br/>not that the captured data is itself true.

  V->>IPFS: GET /evidence — fetch bytes by CID
  V->>SOL: GET /blockchain/* — check the anchor
```

## مهام مع إنسان في الحلقة

تدفقات ResQ المستقلة جميعها **مُقيَّدة بـ HITL**. تُطبّق المنصة الإشراف
البشري الوارد في
[المادة 14 من قانون الذكاء الاصطناعي الأوروبي](https://artificialintelligenceact.eu/article/14/):
يجب على مشغّل مُخوَّل أن يوافق على الإجراءات عالية المخاطر قبل أن
ينفّذها النظام.

تتم الموافقة على المهام عبر Coordination API:

* `GET /admin/missions/pending` — الإجراءات قيد الانتظار
* `POST /admin/missions/approve` — الموافقة على مهمة معلّقة
* `POST /admin/missions/reject` — الرفض وتسجيل السبب

تتطلب الموافقة نطاق صلاحية المشغّل `missions.approve`. الاستدعاءات
التي لا تحوزه ترجع `403` — راجع [الأخطاء](/ar/errors).

```mermaid theme={null}
flowchart TD
  P["Autonomous action proposed"] --> A{"Inside permitted airspace?<br/>/solana registry"}
  A -- no --> RJ["Dispatcher refuses the flight plan"]
  A -- yes --> Q["GET /admin/missions/pending"]

  Q --> S{"Operator holds<br/>missions.approve?"}
  S -- no --> F["403 — needs an administrator,<br/>do not retry"]
  S -- yes --> DEC{"Operator decision<br/>EU AI Act Art. 14"}

  DEC -- approve --> OK["POST /admin/missions/approve<br/>system commits the action"]
  DEC -- reject --> NO["POST /admin/missions/reject<br/>reason recorded"]
```

## المجال الجوي والتصاريح

للتسليمات والطيران المستقل، يستخدم ResQ **سجل المجال الجوي** على
السلسلة عبر Solana. تُسجّل نقاط النهاية `/solana` في Infrastructure API
التصاريح وأحداث التسليم واستعلامات السجل. يرفض المُرسِل خطط الطيران
خارج المجال الجوي المسموح به؛ يقع هذا الفلتر قبل الموافقة على المهمة،
وليس بعدها.

## القياس عن بُعد والأحداث المباشرة

تنقل تدفقان البيانات في الوقت الحقيقي:

* **الاستيعاب**: تدفع أساطيل الطائرات بدون طيار دفعات القياس عن بُعد
  إلى `POST /fleet/telemetry` على Coordination API. تُخزَّن الدفعات
  مؤقتًا على الحافة وتُعاد محاولتها — لا يُسقَط القياس عن بُعد بصمت أبدًا.
* **الاشتراك**: يستهلك العملاء الحالة المباشرة عبر Server-Sent Events
  على `/events` و Prometheus scrapes على `/metrics` (Coordination API).

## هوية المشغّل ونطاقات الصلاحيات

يصادق المشغّلون باسم المستخدم وكلمة المرور على `POST /login` ويتلقون
JWT قصير الأجل (راجع [المصادقة](/ar/authentication)). يحمل التوكن
**نطاقات صلاحيات** المشغّل — أذونات دقيقة مثل `missions.approve` أو
`evidence.write` أو `airspace.admin`.

طلب يجتاز المصادقة لكنه يفتقر إلى نطاق الصلاحية المطلوب يُرجِع `403`.
اعرضه على المشغّل ولا تعد المحاولة؛ يتطلب إجراءً من المسؤول.

## حقن الأخطاء والمحاكاة

يكشف Coordination API نقاط نهاية `Simulation` لحقن الأخطاء، وتحوي
SDKs أُطُر محاكاة. الهدف هو ممارسة سلوك الشبكة في الوضع المتدهور في
الاختبار قبل الاعتماد عليه في الإنتاج. استخدمه أثناء اختبارات التكامل،
وليس في العمليات الحية.

## أين يوجد ماذا

| تريد…                             | انظر إلى                       |
| --------------------------------- | ------------------------------ |
| إبقاء الحوادث والأدلة ونقاط الربط | Infrastructure API             |
| إرسال أو قراءة حالة الأسطول الحية | Coordination API               |
| التحقق من من يستطيع فعل ماذا      | [المصادقة](/ar/authentication) |
| فهم الإخفاقات وإعادة المحاولات    | [الأخطاء](/ar/errors)          |
| البناء دون كتابة عميل             | [SDKs](/sdks)                  |

## التالي

<CardGroup cols={3}>
  <Card title="بدء سريع" icon="rocket" href="/ar/quickstart">
    أول استدعاء مُصادَق.
  </Card>

  <Card title="المصادقة" icon="key" href="/ar/authentication">
    دورة حياة JWT ونطاقات الصلاحيات.
  </Card>

  <Card title="مرجع API" icon="code" href="/ar/api-reference/introduction">
    كل نقاط النهاية.
  </Card>
</CardGroup>