مرجع الواجهة البرمجية

تقارير التطبيق

استقبال ملفات JSON لتشخيص جلسات التنقّل في تطبيق الجوال وتصنيف المشاكل في لوحة الإدارة.

تقارير التطبيق

ارفع ملف JSON كامل لجلسة تنقّل من تطبيقات نافو للجوال. تخزّن الواجهة الملف دون اقتطاع للإدخالات أو النصوص، وتصنف مشاكل الواجهة البرمجية مقابل التطبيق، وتعرضها في لوحة الإدارة مجمّعة حسب قيمة endedAt لكل ملف.

مسار الاستقبال ليس مربوطًا بنطاق مفتاح API. يُقفل بالسرّ المشترك في معلمة الاستعلام key (JSON_FILE_REPORT_KEY على الخادم). مسارات القائمة/التفاصيل/التنزيل/المطالبات في الإدارة تتطلب جلسة مسؤول.

حد حجم الجسم للاستقبال: 64 ميجابايت.

تطبيقات الجوال. ابنِ ملف JSON واحدًا لكل جلسة تنقّل (ترويسة + خط زمني entries من api / fix / warning / event)، ثم أرسله بـ POST عند انتهاء الجلسة. استخدم رمزي الحالة الخاصين بالعميل 8 (شبكة) و9 (انتهاء المهلة) عندما لا توجد استجابة HTTP. فضّل multipart إذا كان يجب أن يطابق الملف المُنزَّل البايتات الأصلية. العقد التفصيلي لفرق التطبيق: اطلب من نافو دليل App Reports — Mobile Upload Guide.

POST /app-reports

استقبال ملف تشخيص JSON واحد.

الاستعلام

المعلمة	إلزامي	ملاحظات
`key`	نعم	يجب أن يطابق سرّ استقبال التقارير على الخادم. مفتاح خاطئ أو غائب → `401`.

الجسم

أرسل JSON كـ application/json، أو كحقل ملف multipart. فضّل multipart عندما تحتاج أن يطابق التنزيل البايتات الأصلية؛ جسم JSON يُعاد ترميزه عند التخزين.

يُحفظ المحتوى كاملًا: كل إدخال وتحذير واستدعاء API وملاحظة. لا يُقتطع شيء عند الاستقبال.

الاستجابة

{
  "ok": true,
  "created": true,
  "id": "…",
  "sha256": "…",
  "endedAt": "2026-11-02T16:35:44.000Z",
  "endedAtRaw": "2026-11-02T16:35:44Z",
  "findingCount": 11,
  "highestSeverity": "high",
  "backendFindingCount": 4,
  "frontendFindingCount": 9
}

رفع البايتات نفسها مرة أخرى يعيد الصف الموجود مع created: false (إزالة التكرار بـ SHA-256).

الأخطاء

الحالة	متى
`401`	`key` ناقص أو خاطئ
`400`	جسم فارغ أو JSON غير صالح أو الجذر ليس كائنًا
`413`	الجسم أكبر من 64 ميجابايت
`503`	سرّ الاستقبال غير مضبوط على الخادم

curl -X POST "https://navvo.io/api/v1/app-reports?key=YOUR_SECRET" \
  -H "Content-Type: application/json" \
  --data-binary @nav_session.json

GET /admin/app-reports

قائمة التقارير المستقبَلة (الأحدث حسب endedAt أولًا). يتطلب JWT لمسؤول أو مسؤول أعلى.

الاستعلام

المعلمة	ملاحظات
`limit`	الافتراضي 50، الأقصى 200
`offset`	الافتراضي 0
`platform`	`ios` · `android` · `web` · `unknown`
`severity`	`critical` · `high` · `medium` · `low` · `info`

واجهة الإدارة: /platform-admin/app-reports — تجمع الصفوف حسب endedAt.

GET /admin/app-reports/{id}

التحليل المصنّف كاملًا (النتائج وإحصاءات نقاط النهاية وبيانات الجلسة). لا يضمّن كل إدخالات الخط الزمني الخام؛ استخدم تنزيل الملف الخام أو مسار الإدخالات لذلك.

يحمل كل عنصر أيضًا حقول التشغيل (مستقلة عن status داخل ملف JSON):

الحقل	المعنى
`triageStatus`	`new` · `in_progress` · `blocked` · `done` · `canceled` · `wont_fix` (الافتراضي `new` عند الاستقبال)
`notes`	ملاحظات الفريق
`hasNotes`	`true` عندما تكون الملاحظات غير فارغة

يقبل GET /admin/app-reports المعلمة ?triageStatus= ويعيد triageCounts (الإجمالي لكل حالة).

PATCH /admin/app-reports/{id}

تحديث تصنيف المعالجة و/أو الملاحظات. قد يتضمن الجسم أحد الحقلين أو كليهما:

{ "triageStatus": "in_progress", "notes": "انتهاء مهلة API — أُسند للخلفية" }

يعيد الملخص المحدَّث. triageStatus غير صالح → 400.

DELETE /admin/app-reports/{id}

يحذف صف التقرير نهائيًا و ملف JSON المخزَّن على القرص. لا يمكن التراجع.

{ "ok": true, "id": "…", "deletedFile": true }

GET /admin/app-reports/{id}/raw

تنزيل ملف JSON المخزَّن. Content-Disposition: attachment.

GET /admin/app-reports/{id}/prompts

يبني مطالبتين لوكيل IDE من النتائج المصنّفة:

الحقل	الجمهور
`backend`	فريق الواجهة البرمجية / الخلفية
`frontend`	فريق تطبيق الجوال / الواجهة

النتائج ذات الملكية both تظهر في المطالبتين مع نص الإصلاح المناسب. لكل مطالبة: title وprompt وfindingCount وقائمة قصيرة بالنتائج.

GET /admin/app-reports/{id}/entries

إدخالات الخط الزمني من الملف المخزَّن مع ترقيم الصفحات.

المعلمة	ملاحظات
`list`	`issues` (افتراضي) · `errors` · `warnings` · `notes` · `api` · `failed-api` · `slow-api` · `location` · `all`
`limit`	الافتراضي 100، الأقصى 500
`offset`	الافتراضي 0

أحداث البحث

أبلِغ عن نتيجة البحث التي فتحها المستخدم وما فعله بعدها — أحداث نقر وتحويل مشروطة بالموافقة، تقيس جودة البحث وتحسّنها.

الأماكن

قوائم الأماكن وتفاصيل غنية عن المكان — الفئات وساعات العمل والصور والتقييمات وإرشادات الوصول.