إنتقل إلى المحتوى الرئيسي

الأسئلة الشائعة عن النقاط

الخلفية​

على Shukah يقرأ التطبيق أسئلة النقاط وأجوبتها عبر GET /maeda/points-faq. ويُرجع GET /api/v2/client/points-faq في Locate القائمة نفسها، وعلى dev كانت العناصر الخمسة مطابقة لما في Shukah في 2026-10-01 ومرة أخرى في 2026-10-02، مفتاحًا بمفتاح. والشيء الوحيد الذي يتغير هو الـ token: فLocate تتطلب واحدًا، وعلى dev اليوم يجب أن يكون token من Shukah، بينما أجاب route الخاص بـ Shukah بدونه.

الميزة​

الأسئلة الشائعة قائمة بأسئلة وأجوبة عن النقاط: كم تساوي النقطة، وكيف تُكسب النقاط، وكيف تُستخدم. وهي القائمة نفسها لكل عميل. وفي نسخة التطبيق اللحظية بتاريخ 2026-02-26 يحدث الاستدعاء مرة واحدة، عندما تعرض شاشة المحفظة (Wallet) قسم الأسئلة الشائعة. ولا يعرض التطبيق شيئًا عندما تكون القائمة فارغة.

يحمل كل عنصر اللغتين: title_ar وtext_ar وtitle_en وtext_en. ويرسل الخادم الأربعة دائمًا، ويختار التطبيق أي زوج يعرضه. وlanguage لا تقرؤه خدمة النقاط، ولا يمرّر order-v2 أي query في هذا الـ route، لذا فإن language الذي يضيفه التطبيق إلى كل استدعاء يُسقَط.

لا يعمل على dev اليوم إلا token من Shukah: فقد حصل JWT من Locate على 401 Invalid or expired token على هذا الـ route في 2026-10-02، مع أن الـ token كليهما عملا على route الرصيد في 2026-10-01 (انظر Which tokens work). يمرّر order-v2 الاستدعاء إلى خدمة النقاط ويُرجع الإجابة دون تغيير.

GET /api/v2/client/points-faq​

يستبدل ShukahGET /maeda/points-faq✅ تم الاستبدال
استبدال مباشر0 breaking · 3 للمراقبة
  • 🟡 تحتاج Locate إلى token؛ وأجابت Shukah بـ 200 بدونه؛ ويرسل التطبيق token دائمًا.
  • 🟡 يحصل JWT من Locate على 401 على dev؛ أرسل token من Shukah.
  • 🟡 العناصر الخمسة متطابقة تمامًا بما فيها \r\n؛ ونص الكسب في الأسئلة الشائعة لا يطابق أيًّا من جدولَي المعدلات.

مدخلات الأسئلة الشائعة الخمسة مطابقة لـ Shukah على dev، لكن Locate تحتاج إلى token بينما كانت Shukah تجيب بدونه.

تخدمه order-v2 → point-serviceتوكن Shukah ✅ · JWT الخاص بـ Locate ❌ (2026-10-02)تم التحقق: استدعاء مزدوج على dev، 2026-10-02قارن مع Shukah ←

الطلب (Request)​

الحقلالموضعالنوعمطلوبالقيودالوصف
AuthorizationheaderstringنعمBearer <token>: token من Shukah على dev اليوم. أما JWT من Locate فيحصل على 401 Invalid or expired token (التُقط على dev، 2026-10-02): انظر Which tokens work.الـ token الخاص بالعميل نفسه.
languagequerystringلايُقبل ويُتجاهل: فالحقول الأربعة تُرجَع دائمًا. ولا يمرّره order-v2.يُبقى حتى تظل سلسلة query القديمة لـ Shukah تعمل.

الاستجابة (Response)​

200 مع مصفوفة مجردة. وتأتي مفاتيح كل عنصر بهذا الترتيب: title_ar وtext_ar وtitle_en و text_en. وتتبع المصفوفة الترتيب المضبوط في إعدادات الأسئلة الشائعة ولا تحتوي إلا العناصر النشطة. وعلى dev كان فيها خمسة عناصر.

الحقلالنوعيقبل nullالصيغة / القيودالوصف
title_arstringلا"" عند الغياب.السؤال بالعربية.
text_arstringلا"" عند الغياب. فيه فواصل أسطر \r\n.الجواب بالعربية.
title_enstringلا"" عند الغياب.السؤال بالإنجليزية.
text_enstringلا"" عند الغياب. فيه فواصل أسطر \r\n. وأحد العناصر الحية ينتهي بـ \t \r\n.الجواب بالإنجليزية.
[
  {
    "title_ar": "كم قيمة النقطة في لوكيت؟",
    "text_ar": "النقطة الواحدة تساوي 0.25 ريال.\r\nيعني 4 نقاط تساوي ريال واحد.",
    "title_en": "How many points are worth in the Locate App?",
    "text_en": "each point equal to 0.25 SR\r\nthat means, each 4 points equal to one SR"
  }
]

التُقط على dev، 2026-10-01 (العميل 356259): أول العناصر الخمسة.

يذكر جواب "How I can earn points?" جدول كسب فيه 35–69 SR لنقطة واحدة، و70–139 SR لنقطتين، و140–250 SR لـ 4 نقاط، و251–450 SR لـ 8 نقاط، و451 SR فأكثر لـ 16 نقطة. وهذا لا يطابق أيًّا من جدولَي معدلات الكسب الملتقطين في اليوم نفسه (انظر محفظة النقاط). وأي الجدولين هو الصحيح: غير موثّق بعد.

الأخطاء​

HTTPBodyمتى
401{"success":false,"error":{"code":"UNAUTHORIZED","message":"Missing or invalid authorization header"}}لا يوجد header باسم Authorization، أو لا يبدأ بـ Bearer . التُقط على dev، 2026-10-01، دون token.
401الشكل نفسه، مع message بالقيمة Invalid or expired token أو auth service unreachable: <error text> أو auth response missing numeric client id.رفضت خدمة المصادقة الـ token، أو تعذّر الوصول إليها (فعطل خدمة المصادقة يبدو كـ token سيئ)، أو أجابت دون معرّف عميل. وقد التُقط Invalid or expired token على dev، 2026-10-02، مع JWT من Locate.
500{"success":false,"error":{"code":"INTERNAL_ERROR","message":"Internal server error"}}أي فشل غير متوقع في خدمة النقاط، مثل خطأ في قاعدة البيانات. وتكون الرسالة AUTH_SERVICE_URL not set عندما تكون الخدمة مضبوطة خطأً. لم يُلتقط.
502{"success":false,"error":{"code":"POINT_SERVICE_UNAVAILABLE","message":"Point service unavailable: <error text>"}}تعذّر على order-v2 الوصول إلى خدمة النقاط. وهذا الـ body صادر عن order-v2، لا عن خدمة النقاط. لم يُلتقط.
504{"success":false,"error":{"code":"POINT_SERVICE_TIMEOUT","message":"Point service did not respond in time; the request outcome is unknown"}}لم تجب خدمة النقاط خلال 10 ثوانٍ. وهذا الـ body صادر عن order-v2. لم يُلتقط.

كل خطأ صادر عن خدمة النقاط له الغلاف (envelope) {"success":false,"error":{"code":"…","message":"…"}}.

جرّبه​

export ORDER_BASE_URL=https://dev.v2.api.order.locate.sa
export SHUKAH_TOKEN='<shukah-token>'   # a Locate JWT gets 401 here today; see "Which tokens work" on Points wallet
curl -s "$ORDER_BASE_URL/api/v2/client/points-faq" -H "Authorization: Bearer $SHUKAH_TOKEN"

المتوقع: 200 ومصفوفة من خمسة عناصر مثل المبيّن تحت «الاستجابة». استخدم token من Shukah على dev اليوم: فـ JWT من Locate يحصل على 401 Invalid or expired token (2026-10-02). وبلا token تحصل على 401 المبيّن تحت «الأخطاء».

الفروق عن Shukah​

كانت المصفوفتان ذواتا العناصر الخمسة متطابقتين تمامًا (deep-equal) في 2026-10-01 وفي 2026-10-02، بترتيب المفاتيح نفسه وفواصل الأسطر \r\n نفسها. وتغطي الصفوف أدناه الـ token وURL وbody الخطأ.

الجانبShukahLocateالأثر على التطبيق
URLGET $SHUKAH_BASE_URL/maeda/points-faqGET $ORDER_BASE_URL/api/v2/client/points-faqغيّر base URL والمسار.
الـ Tokenلا حاجة إليه: 200 دون token (التُقط على dev، 2026-10-01).مطلوب: 401 دون token (التُقط على dev، 2026-10-01). وtoken من Shukah فقط على dev اليوم: فـ JWT من Locate يحصل على 401 (2026-10-02).يرسل التطبيق token الخاص به مع كل استدعاء بالفعل، ويجب أن يُبقيه token من Shukah هنا. أما شاشة تعرض الأسئلة الشائعة قبل تسجيل الدخول فستفشل. وهل توجد شاشة كهذه: غير موثّق بعد.
body الخطأغير موثّق بعد. الـ route عام (public)، فلا يوجد 401 للمقارنة.غلاف خدمة النقاط الوارد تحت «الأخطاء».يجب تغيير أي شيء يطابق نص الخطأ.
Content-Typeapplication/jsonapplication/json; charset=utf-8لا شيء.

تنبيه​

  • تتطلب Locate token على هذا الـ route، بينما كان route الخاص بـ Shukah يجيب بدونه.
  • تعود الحقول الأربعة كلها في كل عنصر، ويُتجاهل language، لذا يجب على التطبيق اختيار الزوج العربي أو الإنجليزي بنفسه.
  • جدول الكسب المكتوب في نص الأسئلة الشائعة لا يطابق أيًّا من جدولَي معدلات الكسب على dev.

التفاصيل (للـ backend)​

فُحص dev فقط، عبر order-v2 على https://dev.v2.api.order.locate.sa، والبادئة /api/v2/client. الـ hosts في UAT وproduction: غير موثّق بعد. في هذا القسم تعني OV2: المستودع locate-order-v2-api@d9e4e5f6 وتعني PS: المستودع locate-point-service@2c44ce3. وكيف يعمل الـ proxy وفحص الـ token وغلاف الأخطاء موصوف مرة واحدة، تحت كيف تعمل الاستدعاءات الممرَّرة.

الـ Route والـ proxy​

يذهب GET /api/v2/client/points-faq إلى GET /api/client/points-faq في خدمة النقاط. ويمرّر order-v2 Authorization فقط، بحد زمني 10 ثوانٍ، ودون query (OV2: src/modules/client/point/point.controller.ts:47-59، PS: services/api/src/routes/client.routes.ts:19، PS: services/api/src/handlers/client-points-faq.ts:6-9).

ما تقرؤه خدمة النقاط​

تقرأ صفوف point_faqs بحالة status: 'active'، مرتبة بحسب ordering من الأدنى إلى الأعلى، وتسطّح كل وثيقة {title:{en,ar}, text:{en,ar}} إلى المفاتيح الأربعة المسطّحة. والقيمة المفقودة تصبح "" (PS: services/api/src/services/client-points.service.ts:43-50، PS: services/api/src/services/client-points.mappers.ts:58-71؛ الاختبارات PS: services/api/src/services/client-points.mappers.test.ts:88-107). والقائمة ليست خاصة بعميل بعينه. فـ ETL الخاص بخدمة المصادقة يملأ point_faqs من جدول الأسئلة الشائعة في Shukah؛ ولا تستطيع routes العميل الكتابة فيه (PS: docs/integrations/2026-07-16-client-facing-point-apis.md:172-174، PS: docs/2026-07-10-local-testing.md:53).

التطابق (Parity)​

في 2026-10-01 قورنت مصفوفتا Locate وShukah برمجيًا وكانتا متطابقتين تمامًا (deep-equal)، بترتيب المفاتيح نفسه. وفي يوليو كانت قائمة Locate stub فارغة، لذا فهذا يُغلق تلك الملاحظة (PS: docs/reports/2026-07-17-client-api-parity.md:165-168). وكانت وثيقة خدمة النقاط قد سجّلت التطابق بعد تنفيذ 2026-07-17 (PS: docs/integrations/2026-07-16-client-facing-point-apis.md:171-174).

التطبيق​

يحوّل التطبيق كل عنصر إلى عنوان ونص بالإنجليزية وبالعربية، ويعرض الزوج المطابق للغة التطبيق، ويستخدم العنوان الإنجليزي مفتاحًا للقائمة، ولا يعرض شيئًا لقائمة فارغة (mobile/locate-client@e960c3a: src/entities/points/model/api/dto/points.dto.ts:53-68، mobile/locate-client@e960c3a: src/features/PointsFaq/ui/FaqItem/FaqItem.tsx:32-37، mobile/locate-client@e960c3a: src/features/PointsFaq/ui/PointsFaq/PointsFaq.tsx:27-70). ويستدعي الـ route دون أي query من عنده (mobile/locate-client@e960c3a: src/entities/points/model/api/services/points.service.ts:62-76).

حيث تختلف الوثائق عن الشيفرة (القول للشيفرة)​

  • 2026-10-02: قالت هذه الصفحة إن token من Shukah وJWT من Locate عملا كلاهما هنا. وفي 2026-10-02 حصل الـ JWT على 401 Invalid or expired token، ويستخدم قسم «جرّبه» الآن token من Shukah (PS: services/api/src/services/client-auth.service.ts:22-29؛ انظر Which tokens work).

Sources​

  • locate-order-v2-api@d9e4e5f6: src/modules/client/point/point.controller.ts:47-59
  • locate-point-service@2c44ce3: services/api/src/routes/client.routes.ts:19، services/api/src/handlers/client-points-faq.ts:6-9، services/api/src/services/client-points.service.ts:43-50، services/api/src/services/client-points.mappers.ts:58-71، services/api/src/services/client-points.mappers.test.ts:88-107
  • وثائق locate-point-service@2c44ce3: docs/integrations/2026-07-16-client-facing-point-apis.md:171-174، docs/2026-07-10-local-testing.md:53, docs/reports/2026-07-17-client-api-parity.md:165-168
  • نسخة الجوال اللحظية mobile/locate-client@e960c3a (الفرع development، 2026-02-26؛ شيفرة التطبيق نفسه، وليست من Locate): src/entities/points/model/api/services/points.service.ts:62-76، src/entities/points/model/api/dto/points.dto.ts:53-68، src/features/PointsFaq/ui/PointsFaq/PointsFaq.tsx:27-70، src/features/PointsFaq/ui/FaqItem/FaqItem.tsx:32-37، platforms/mobile/products/locate/screens/home/mainInner/Wallet/ui/Wallet/Wallet.tsx:84
  • التقاطات dev، 2026-10-02 (parity audit): points-faq--shukah وpoints-faq--locate-st و points-faq--locate-jwt وpoints-faq-notoken--shukah
  • التقاطات dev، 2026-10-01: locate-points-faq وshukah-points-faq وprobe-locate-points-faq و probe-shukah-points-faq