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

# المتاجر والمخزون

> بِع العناصر وتتبّع ما يملكه كل لاعب.

export const Scope = ({children}) => <Info>
    <b>النطاق:</b> {children}
  </Info>;

يتكوّن اقتصاد Flock من ثلاثة أجزاء:

* **المتاجر** — مجموعات من العناصر القابلة للشراء.
* **عناصر المتجر** — عروض مفردة لكلٍّ منها سعر وعملة.
* **المخزون** — سجلٌّ بما اشتراه كل لاعب.

<Scope>تُعرَّف المتاجر وعناصرها لكل **إصدار لعبة**؛ أما المخزون فلكل لاعب.</Scope>

تخصم عملية الشراء من محفظة اللاعب وتسجّل مدخلًا في المخزون:

```
Shop item ──purchase──▶ wallet debit ──▶ inventory entry
```

وكل عملية شراء تُنشئ مدخلها الخاص، فشراء العنصر نفسه مرتين يمنحك مدخلين. ويحمل كل مدخل حقلَي
`status` و`used_at` يضبطهما الخادم، وكلاهما للقراءة فقط — فلا توجد دالة في أيٍّ من حزمتَي التطوير
تُعلّم المدخل بأنه مستخدَم.

**عملية الشراء آمنة ماليًا.** فهي لا تُعاد أبدًا بعد فشل غامض ولا تُصفّ في طابور عند انقطاع
الاتصال، ومن ثمّ لا يمكن أن تخصم مرتين. ويُجلب المخزون دائمًا محدَّثًا من الخادم؛ أما الكتالوج
فمُخزَّن مؤقتًا ويُقدَّم دون اتصال، لذا عامِل أي سعر معروض على أنه استرشادي حتى تنجح عملية الشراء.

<Warning>
  **لا تمنح عملية الشراء محتويات العنصر.** فعنصر المتجر له اسم وحالة وسعر وعملة — ولا يوجد حقل يصف
  ما الذي يمنحه، لذا لا يملك الخادم ما يضيفه إلى رصيد اللاعب. شراء حزمة «1000 ذهب» يخصم السعر
  ويسجّل المدخل؛ أما الذهب فلا يُضاف.

  ومنح المحتويات من داخل اللعبة نفسها هو الخيار الوحيد اليوم، وهو غير آمن لأي شيء يهمّك: إذ يمكن
  تعديل التطبيق ليمنح أي كمية، كما أن انقطاع الاتصال بعد الخصم يترك اللاعب مخصومًا منه دون مقابل.
  ومنح المكافآت من جهة الخادم مطلبٌ قيد التتبّع.
</Warning>

<Tabs>
  <Tab title="لوحة التحكم">
    اضبط المتاجر وعناصرها لإصدار لعبة من لوحة التحكم — حدّد الأسعار والعملات ومدى التوفّر.

    <Frame caption="اضبط المتاجر والعناصر من لوحة التحكم.">
      <img src="https://mintcdn.com/qwacks/TGGmq_oWzDacAqHl/images/guides/shops.png?fit=max&auto=format&n=TGGmq_oWzDacAqHl&q=85&s=fc1fed5840b96a664392783492a37847" alt="المتاجر والعناصر" width="1440" height="866" data-path="images/guides/shops.png" />
    </Frame>
  </Tab>

  <Tab title="Unity">
    استخدم دوال المتجر في حزمة التطوير لسرد المتاجر والعناصر المتاحة لإصدار لعبتك، ثم نفّذ عملية
    شراء لصالح اللاعب المسجَّل دخوله. وتعمل `PurchaseAsync` افتراضيًا على اللاعب المسجَّل دخوله،
    وتُعيد مدخل المخزون الذي أنشأته.

    ```csharp theme={null}
    PlayerInventory entry = await FlockClient.Instance.Shop.PurchaseAsync("shop-item-id");

    PaginatedResponse<PlayerInventory> owned =
        await FlockClient.Instance.Shop.GetPlayerInventoryAsync();
    ```

    وترمي عملية الشراء المرفوضة استثناءً — التقط `FlockException` وتحقّق من `ErrorCode` بحثًا عن
    `FlockErrorCode.ShopInsufficientFunds` لتمييز «الرصيد غير كافٍ» عن فشل الشبكة.
  </Tab>

  <Tab title="Unreal">
    تصفّح باستخدام عقد *Flock | Shop*، أو مزوّد المتجر في C++. ويمكن قراءة حقلَي `data` و`stats`
    الحرَّين لأي عنصر عبر مسار منقوط، فلا حاجة إلى عقدة لتحليل JSON.

    <Frame caption="اشترِ باختيار عنصر مُولَّد — المعرّف مضمَّن سلفًا ويستحيل أن تخطئ في كتابته.">
      <img src="https://mintcdn.com/qwacks/xJEjgQCFVIWLhvHB/images/sdk/unreal/shop-purchase.png?fit=max&auto=format&n=xJEjgQCFVIWLhvHB&q=85&s=7d62008138e464eab95c97c1be0943a7" alt="عقدة Flock Purchase داخل مخطط Blueprint" width="333" height="237" data-path="images/sdk/unreal/shop-purchase.png" />
    </Frame>

    ```cpp theme={null}
    Sdk->GetShopProvider()->Purchase(ItemId,
        [](TFlockResult<FFlockPlayerInventory> Entry)
        {
            if (!Entry.bSuccess && Entry.Error.Code == EFlockErrorCode::ShopInsufficientFunds)
            {
                // The server declined — show the player, don't retry.
            }
        });
    ```
  </Tab>
</Tabs>

راجع [العملات والمحافظ](/ar/guides/currencies-and-wallets) للاطّلاع على الأرصدة التي تقوم عليها
عمليات الشراء.